深深桌宠 Jcnet-9527/dsh-Jpet-phone

dsh-Jpet-phone 🐾 深深桌宠（手机版）

本仓库是 PC2005-cloud/dsh-pet v0.3.7 的手机版适配 fork（原项目 MIT 许可证，LICENSE 保留原作版权信息）。
适配目标：dsh 安卓手机版（引擎 0.2.1-rc.2）。桌面端请使用原作者仓库。
改动明细见仓库根目录《手机版适配说明.md》。

两套玩法，随便选（也可以两个都要）

这个仓库里放的是同一只宠物的两种形态，它们互不依赖、互不干扰，设置各存各的：

| | ① 插件版（dsh 手机版内） | ② 独立 App 版（安卓原生悬浮宠） |
| 怎么装 | dsh plugin add github:Jcnet-9527/dsh-Jpet-phone | 下载 APK 安装（见 Releases） |
| 在哪出现 | dsh 手机版的网页里，跟着页面走 | 系统悬浮窗，任何界面最上层，可后台常驻 |
| 需要 dsh 吗 | 需要 | 不需要，装完就能用 |
| 动画素材 | 全部随插件打包 | 自带 7 段核心动作，其余 99 段用到时自动下载（也可一键全下） |
| 对话 / 余额 | 有 | 有（在设置里填自己的 API Key） |
| 长按菜单 | 动作分类列表、对话、查看余额… | 同款：动作分类列表、对话气泡、查看余额… |

- 只想用插件：按下面《快速开始（安装插件）》做，android-app/ 整个目录你都不用看。
- 只想装软件：去 Releases 下 APK，不用装 dsh、不用装插件。
- 两个都要：先装插件，再装 APK。想同一只宠同时出现在两个地方就都开着，不想就只开一个——删掉其中一个，另一个照常工作。

仓库结构

├── package.json / cordis.patch.yml / src / lib ← ① dsh 插件（仓库根目录就是插件本体） ├── android-app/ ← ② 安卓原生悬浮桌宠工程 ├── 手机版适配说明.md ← 插件版相对原版改了什么 └── android-app/README.md ← APK 版怎么编译、素材怎么来的

远程动画素材

APK 只有 ~45 MB，因为它只打包了 7 段核心动画；完整 106 段的逐帧素材放在独立仓库 Jcnet-9527/dsh-Jpet-phone-assets， App 通过 CDN 按需下载并缓存在手机里（设置 → 动画素材 可以一键全下 / 清除 / 换下载源）。

App 版 v0.6.3 更新

能自己检查更新了，说话也终于对着动作说：

- 内置检查更新：设置页底部多了「检查更新」，启动时也会静默查一次（6 小时内最多一次，没网就当没发生）。发现新版本会弹窗，选「立即更新」跳到下载页，选「稍后」一天内不再自动打扰。
版本号是按数字逐段比的，不会把 0.10.0 当成比 0.9.1 更旧。
- 台词跟着动作走：内置的「好女孩……」「好模型……」那五句已经全部删除。现在有 10 个动作各自带一句台词——点它的五种回应（傲娇生气、元气挥手、害羞惊讶、开心跃动、挠痒咯咯笑）和五个自言自语的动作（深度思考、发呆、对屏、擦桌、吃什么），动作一播，台词就上气泡；开了语音模式连朗读一起走。台词写在 clip_lines.json 里，以后想加改这个文件就行。
- 默认人设换成小鲸鱼：原来的默认人设是「深深·蓝发小女仆」，可素材里全是鲸鱼尾巴、蓝鲸现世、吃 Token，说话还自称「本鱼」——人设和形象是对不上的。新版默认人设改成傲娇嘴硬的 DeepSeek 小鲸鱼，句子长度从「只说一两句」放宽到 10–40 字（气泡和朗读都更顺），并且明确写了「没有联网能力，查不了实时信息」，不会再出现「我去查一下」然后没了下文。
自己改过人设的不受影响；想回到新默认，设置页有「恢复默认人设」。
- 修好余额显示：以前点「查看余额」永远只得到「余额查询成功，但接口没给出数字」。
原因是 DeepSeek 的 /user/balance 把 balance_infos 返回成数组，代码却按对象解析，读出来是空的。现在会正常显示：余额 ¥110.00（赠金 ¥10.00 · 充值 ¥100.00）。

App 版 v0.6.2 更新

修复四个实机问题，无需重新下载模型：

- 特效不再偏透明：特效动画以前画在第二个"可穿透触摸"的窗口里，而 Android 12 起会对这类窗口限制不透明度（上限约 80%），看起来就像蒙了一层、能透过去看到后面。
现在特效和普通动作画在同一个窗口，透明度完全一致。
- 长按菜单滚动不再外溢：圆角卡片的背景以前画在滚动容器自己身上，View 的背景不会裁剪子内容，滚动时文字会冲出圆角；背景挪到独立容器并开启圆角裁剪后，文字始终待在卡片内。
- AI 回答不再"查一下就没下文"：回复以前被气泡硬截断到 90 字，而且人设会让它说 "我去查一下"就收尾（实际并没有联网能力）。现在完整回答按句子分批在气泡里依次显示、语音整段朗读、全文进聊天记录；请求加了 max_tokens 并检查截断标记；人设改为明确 "没有联网能力，遇到实时问题直说看不到"。
- 修复关语音模式闪退：以前在主线程直接释放正在朗读/识别的本地引擎，撞上正在跑的合成线程就是 use-after-free，立刻崩溃（这也解释了"先暂停再关就不崩"）。现在关停被挪到后台线程、先等播放线程离开引擎再释放，同时消除了主线程等录音的卡顿隐患。

App 版 v0.6.1 更新

语音模式重做 + 三种音色，并修掉 0.5.1 遗留的特效重叠：

- 语音模式＝朗读所有气泡：开关打开后，深深在气泡里说的每一句话都会读出来——打字聊天、语音聊天、点它说话、余额播报都算，不用管你是哪种输入方式。
「语音输入」是另一个独立开关，两者互不依赖（关掉麦克风也可以只让它读）。
- 麦克风常驻：语音输入打开后，宠物旁边一直有「按住说话」按钮，跟着宠物移动；点按钮外的任意位置可暂时收起，长按菜单里的「语音输入」再叫回来。
不用再从菜单进入，也就没有「问一句答一句」的机器人感了。
- 三种音色可选：甜甜（默认女声，matcha，约 140 MB）、小雅（清亮女声，piper int8，约 21 MB）、超文（沉稳男声，piper int8，约 21 MB）；设置页可直接试听，换音色后第一次使用自动下载对应模型。
- 修复特效动画重叠：0.5.1 点「特效」时会新开一个窗口播特效，而原窗口的旧画面没有被清掉（清空调用在上层被当成「这一帧还没解码」直接忽略了），两个动画叠在一起。
现在特效播放期间主窗口停止绘制但保留触摸，特效结束自动恢复，不再出现两个深深。
- 语音引擎不变：识别用 sherpa-onnx 流式中英双语 zipformer（边说边出字），朗读本地合成，自带数字/日期/多音字正音；模型从动画素材同一组镜像按需下载。

App 版 v0.6.0 更新（语音对话首次上线）

- 按住宠物旁的按钮讲话，松手后转成文字发给 DeepSeek，回复会用本地 TTS 读出来；识别与朗读完全在手机本地运行，不联网、不额外消耗 API 额度。
- 识别约 50 MB、朗读约 140 MB，首次使用时下载；APK 只增加约 12 MB 运行库。
- 需要一次性授予「麦克风」权限。

修复 0.5.0 引入的两个体验回退（拖拽跟手 / 切动作闪跳，详见 0.5.1）：
- 拖拽按下时挂全屏透明抓取窗接收完整拖拽轨迹，抬手即撤；第二根手指落下不再打断拖拽。
- 窗口固定为「日常舞台盒」（常规动画并集，约 161dp 宽），切动作只平移内容不再 resize。
- 特效动画挪出随机待机池，改到「特效」分类点播；触摸命中放宽为 ±12px 9 点采样。

以下是原项目 README

dsh-pet 🐾

一只住在 DeepSeek Harness Web UI 里的桌面宠物：待机呼吸、随机动作（打瞌睡、玩魔方、写代码、吃火锅……97 个手绘风透明动画随时无缝衔接）、左右转向、屏幕漫游、点击 Q 弹、拖拽甩抛反弹、右键菜单点播动作、余额动画 + 头顶联想气泡、时不时的碎碎念与对话（都能配一张表情包）——可多开同屏，能脱离浏览器住上桌面（透明置顶小窗），也能自己添加全新宠物种类（pet pack）。

🚀 快速开始（安装插件）

--profile 填你实际在用的那个：桌面应用（Electron 版）→ desktop；dsh web → web
dsh plugin --profile desktop add dsh-pet

装完重开桌面应用（dsh web 用户则重启 dsh web）才生效。宠物出现在界面右上角（默认配置角落，可在设置页修改）——全部透明动画开箱即用，无需任何生成流程。

💡 单一格式（默认 .webm）：浏览器 Chrome/Edge/Firefox 与桌面模式（Electron=Chromium）直接透明播放；Safari 不认 webm alpha（黑底），macOS 需要改用 .mov，见下方「🖥️ macOS 使用 mov」。

💡 想自己造一只专属宠物？克隆 PC2005-cloud/dsh-pet 仓库，用内置素材链（AI 提示词 → 绿幕视频 → 透明动画，素材由豆包生成）从零生成，全流程可复现。

💡 不想每次都开着 DSH？npx dsh-pet-standalone 可以完全不打开 DSH 让桌宠住在桌面上，见下方「🧍 独立运行（完全不打开 DSH）」。

🖥️ macOS 使用 mov（Safari 透明播放）

macOS 的 Safari/WKWebView 下透明动画需用 .mov 素材，三步：

1. 下载 mov 素材：<https://github.com/PC2005-cloud/dsh-pet/releases/tag/assets-mov>（保持最新，zip 解压后文件名与 webm 一一对应）
2. 放入素材目录：把 .mov 文件放进 $DSH_HOME/dsh-pet/main-animation/mov/（pet pack 宠物则是 pet/<种类名>-animation/mov/）
3. 改变量：搜 ANIMATION_EXT，把 .webm 改为 .mov：
- npm 包用户改产物 lib/client.js（桌面端如需再改 runtime/electron-helper/shared-core.js）
- 自构建用户改源码 src/shared/constants.ts 后重新构建

改完重启 dsh web（或重新加载页面）即生效，其余平台不受影响。

✨ 功能特性

- 纯粹的桌宠：不掺业务功能——没有天气查询、系统监控、Agent 状态感知，就一件事：陪你（外加可选的余额展示、系统通知、碎碎念与对话，见配置节）。零核心改动；默认零模型成本——只有主动开启碎碎念（pets[].whisperEnabled）或主动发起对话时才会调用当前会话所用的模型，其余功能运行时零 LLM/API 调用
- 手绘风透明动画：待机呼吸、打瞌睡、玩魔方、哼歌、炸毛、吐泡泡、玩水枪、小提琴演奏、蓝鲸现世、吃白饭、照镜子、三支舞、写代码、四季动作（放风筝、堆雪人、吃冰淇淋、放烟花……）全部无缝衔接
- 永不停止的动画链：每段动画播完立即按权重选下一个（默认 idle 10 / turn 5 / move 5，剩余 80% 归随机动作分类）
- 屏幕漫游：朝 facing 方向行走，自动检查空间、不走出屏幕
- 点击 / 拖拽（弹簧跟手 + 甩抛反弹 + Q 弹）：点击有随机回应动画（开心 / 害羞 / 傲娇）并「Q 弹」挤压回弹（垂直压扁 55% → easeOutBack 回弹过冲，贴地锚定）；拖拽为过阻尼弹簧跟手（不抖不飘、无 overshoot）；松手按最后轨迹估速（停顿/慢速 = 温柔放下原地停住）——用力甩出即沿抛物线飞行：撞屏幕边缘按恢复系数反弹、落地摩擦减速至停，每次落地按冲击速度 Q 弹（轻落 0.8 ~ 重砸 0.55）；物理与挤压曲线纯函数在 src/shared/physics.ts，浏览器与桌面严格同一手感（prefers-reduced-motion 时跳过挤压）
- 物理参数化（0.2.5）：拖拽抛掷手感全部由配置 physics 段驱动——重力（gravity，0 = 无重力漂浮）/ 碰壁恢复系数（restitution）/ 地面摩擦（groundFriction，0 = 冰面）/ 顶部反弹开关（ceilingBounce）/ 总力度（throwPower）/ 多宠物碰撞开关（petCollision），所有宠物共用（全局默认：设置页改一次对含 pet pack 的全部宠物生效；种类文件顶层可覆盖，见配置节）；设置页「物理」区可图形化编辑（6 个控件，与四个全局开关同一套语义：改完点「保存」整包写入用户配置，非法值就地红字提示、宿主也会拒绝）
- 点击积分（0.2.5）：飞行中的宠物被按下（速度 ≥ 400px/s）→ 点击处爆开粒子 + 弹出积分卡片；分数 = 速度/100 × 462/大小（线性，越快/越小分越高——小宠物目标小、更难命中，奖励更高）；静止/慢速点击维持普通点击回应动画（prefers-reduced-motion 时跳过粒子）
- 多宠物碰撞（0.2.5）：petCollision: true 开启后，飞行中的宠物撞到其它宠物按动量守恒 + 恢复系数 0.995 弹开（质量 ∝ size²，被撞方从落点以新初速抛出去），浏览器与桌面跨窗口同语义（默认关闭）
- 碎碎念：宠物时不时自己冒一句——按 eventsRefreshSec.whisper 周期（默认 300 秒）调用当前会话所用的模型生成（人设 = 所属条目的 whisperPrompt，每个种类一份，另追加一句名字声明），气泡展示 10 秒；右键菜单「碎碎念」可立即催一句（绕过节流，同一实例的多端一起看到）。默认开启，按宠物可关（pets[].whisperEnabled）
- 对话：右键「对话」弹窗跟宠物聊天，也能用 /chat <消息> 命令（留空 = 催一句碎碎念）——记忆持久化在 $DSH_HOME/dsh-pet/memory.json（全存不删，每次请求只带最近 chatMemoryRounds 轮），浏览器与桌面共享同一份记忆；对话目标为 /pet 选中的那只，未选则取列表第一只
- 表情包配图（0.2.9）：气泡可以带一张表情包——碎碎念随机抽 1 张（whisperImageEnabled：只是把这张图的描述加进同一次请求，约 +100 字符 / ≈60 token，增量可忽略）；对话把整张清单交给模型按语境选（chatImageEnabled：每条消息约 +1.1k 字符 / ≈650 token，约碎碎念配图的 11 倍，随图片数量线性增长）。图片与描述的映射在 memes（键 = 表情包目录里的 <键>.png；素材归属与动画同一套，见「高级自定义」），两个开关默认都开
- 右键级联菜单：右键宠物弹出（桌面与浏览器共用同一份组件，src/shared/menu.ts）——桌面端根项「打开网站 / 查看余额 / 回到初始位置 / 重载配置 + 动作」、浏览器端「回到初始位置 + 动作」；「打开网站」用系统默认浏览器打开 DSH 网站（等效网页里 Ctrl+点击链接）；「查看余额」立即拉余额弹气泡播档位动画（与周期触发同一展示路径）；「回到初始位置」停漫游回配置角落；「重载配置」（桌面专属）请宿主重启桌面 Helper——全部桌面宠物窗口按最新配置重建，改完配置文件不必回设置页点保存（与保存同一条重启路径：等旧进程退出再起新的；代价是会话内拖拽落点清空、回配置角落）；动作 → 分类 → 具体动画（分类 = 待机/转向/拖拽/点击回应/移动/随机动作分类/余额档位；点播「移动」分类动画会真实行走一段——边界检查/随机距离/起停时段与随机移动完全一致；noMirror 文字类朝右时自动强制朝左）——浏览器端只在宠物命中区拦截右键（preventDefault），完全不进入/改动 DSH 页面自己的菜单。「打开网站」按宿主自动分派：宿主是 DSH 桌面应用时该项自动变「打开 DeepSeek Harness」，用应用自注册的 dsh://open 协议把桌面应用主窗口唤到前台（已运行前置 / 未运行拉起）；dsh web 与独立模式仍是系统默认浏览器打开站点
- 左右朝向：所有动画 CSS 镜像，人物可朝左 / 朝右
- 落地对齐：动画统一脚底线，宠物始终站在"地面"上
- 流畅切换：双缓冲 video 交叉淡入，切换零空白帧
- 无障碍友好：支持 prefers-reduced-motion
- 多开：可配置多个宠物同屏，每只独立的 id/大小/位置/余额开关/显示位置（设置页「桌宠配置」添加/删除）
- 桌面模式（可选）：可脱离浏览器住上桌面——透明置顶局部小窗，与浏览器严格同行为（见下节）
- 余额展示：实时显示余额/额度，按档位播动画 + 头顶联想气泡，每只宠物可独立开关
- 额外宠物种类（pet pack）：在 pet/ 自建「种类」（独立动画池 + 自己的素材），多实例共享，与主宠物严格隔离（见配置节）
- 自定义动画：main-animation/webm/ 放 VP9-Alpha .webm 即作为新动画，优先于包内素材

🪟 桌面模式（脱离浏览器，可选）

默认情况下宠物住在 DSH 网页里（浏览器 overlay）。安装后还会自动拉起一个脱离浏览器的桌面形态：

- 独立透明置顶窗口：为每只桌面宠物各开一个局部小窗口（尺寸 = 宠物包围盒 + 四周外扩余量，为气泡/弹窗预留空间；透明、置顶、跳过任务栏），窗口跟随宠物移动；窗口永不铺满屏幕（全屏透明置顶窗会触发 Windows DWM 视频合成黑屏：需「透明置顶 + 非点击穿透 + 可聚焦且已聚焦 + 完整盖住视频窗」四项齐备，与窗口尺寸无关，详见 runtime/electron-helper/main.js 文件头注释；桌宠悬停时会翻成可交互、show() 也会聚焦，故全屏画布形态仍不做）。与浏览器一致，只有宠物身体命中区可交互，窗口内其余透明像素与窗口外一律点击穿透到下层应用（setIgnoreMouseEvents + 悬停命中翻转）
- 与浏览器严格同行为（同一份源码两个外壳）：宠物功能/文案完全对齐——多开宠物同屏显示、角落+边距定位、同一动画链/点击/拖拽/余额档位动画与富余额气泡；页面配置的显示位置由 display 字段决定，两端宠物内容只可能一致，不会出现"一个有另一个没有"。系统通知是独立于宠物的能力（见配置节 notificationsEnabled），不在此列
- 共享纯逻辑：待机选择 / 移动几何 / 余额折算 / 配置校验 / 通知映射都在 src/shared/，浏览器 bundle 与桌面 shared-core.js（构建产物，window.PetShared）共用同一份源码，只有最外层的渲染壳不同（React vs 纯 DOM）

桌面模式怎么装 / 关

- 依赖 Electron：首次拉起时自动探测（DSH_PET_ELECTRON_PATH 环境变量 → 本机 electron 包 → ~/.dsh/electron/ 落地路径），找不到会通过官方 @electron/get 自动下载到 ~/.dsh/electron/（npm run ensure:electron 可手动触发）；Electron 不可用时仅日志告警，不影响浏览器形态
- 开关 = 每只宠物的 display 字段（pets 必填，四个值）：
- web = 仅浏览器 overlay / desktop = 仅桌面模式 / both = 两者都显示 / none = 都不显示
- 桌面模式渲染 display 含 desktop 的全部宠物（多开同屏，与浏览器一致）；大小/位置各自读自己的配置
- 在 DSH 设置页「桌宠配置」编辑，保存即时生效；display 缺失/非法即配置错误，代码不做兜底
- 桌面与浏览器是同一套动画素材（/dsh-pet-7340/thumb/<前缀>/<name>.webm：main 用用户 main-animation/ 目录优先 + 包内素材；额外宠物只查自己的 pet/<前缀>-animation/，同种类多实例共享）；配图（表情包）共用同一套素材归属（/dsh-pet-7340/pic/memes/<前缀>/<名>.png：pet/<前缀>-memes/ 独占 → 用户 memes/ → 包内 assets/memes/）；配置加载失败会大声报错（红色错误条 + 每 5 秒自动重试），绝不静默兜底

🧍 独立运行（完全不打开 DSH）桌面形态由 DSH 宿主拉起。独立模式让它不需要 DSH 在跑：把插件自己的宿主半边（src/host/index.ts 的 apply）跑在一个最小的伪 ctx 上，再起一个本机 HTTP 服务接管路由 ——路由表仍然只有插件那一份（同一个 handler 同时服务 HTTP 与桌面助手的 bridge 管道）。
sh
npm install -g dsh-pet # 必须 npm 装；dsh plugin add 装进 profile，bin 不在 PATH 上
dsh-pet-standalone # http://127.0.0.1:3080/dsh-pet-7340/（占用则顺延） dsh-pet-standalone --check # 只体检 dsh-pet-standalone --port 3100

npm run build && npm run standalone # 仓库里（先构建）

- 能用：动画链、点击/拖拽/甩抛、右键菜单、多开、自定义动画与表情包、pet pack。
- 不可用：余额、碎碎念、对话、系统通知——返回带 reason 的结构化失败，不假装成功。
- 配置：与 DSH 同一份（$DSH_HOME/dsh-pet/main-config.jsonc → 包内默认）。
- 只显示 display 含 desktop/both 的实例；端口默认 3080；Ctrl+C 或 POST /shutdown 退出。
- 与 DSH 内运行可同时开，但共用 %APPDATA%\dsh-pet-electron-helper，可能互相踩缓存（仅告警）。

⌨️ 斜杠命令

在 DSH 输入框里以 / 触发（与其它插件命令同一入口，命令面板可搜）：

| 命令 | 说明 |
| /pet [id 或名字] | 选择「当前桌宠」——也就是 /chat 的对话目标。留空查看当前选中的是谁；浏览器端支持命令面板的选择框，也可手输 id 或名字（名字重名时必须用 id，报错会列出候选 id） |
| /chat [消息] | 与当前桌宠对话：留空 = 立刻催一句碎碎念（绕过节流，等价于右键菜单「碎碎念」）；输入消息 = 正常对话。回复会写进记忆，并以气泡出现在宠物头顶（浏览器与桌面两端都能看到，配图随回复一起） |
| /balance | 手动触发余额显示并立即弹出气泡（与到点自动触发同一条展示路径）：服务商有余额/额度接口 = 档位动画 + 余额气泡；未登记接口 / 缺凭证 / 抓取失败 = 文字说明气泡（绝不静默无反应） |

没选过 /pet 时，命令作用于有效宠物列表的第一只（列表 = config.jsonc 的 pets + pet/ 目录的种类文件，同屏多开则按顺序取首只）。配图开关见配置节 whisperImageEnabled / chatImageEnabled。

⚙️ 配置

| 配置项 | 说明 |
| 设置页「桌宠配置」 | DSH 设置 → 桌宠配置：图形化编辑大小 / 位置 / 边距，支持多开（添加/删除宠物，每只独立配置）；全局开关也在设置页——系统通知（点保存才写入）、碎碎念配图 / 对话配图 / 抛掷锁定（随「保存」一起写入）；保存即时生效，「同步」把项目内置的 config.jsonc（原文，含注释与全部高级字段）整份写入用户配置，既是恢复默认又留下一份可直接编辑的完整配置 |
| pets（config.jsonc） | 默认宠物列表：[{ "id", "name", "size", "balanceEnabled", "whisperEnabled", "workStatusEnabled", "display", "position": { "corner", "marginX", "marginY" } }]；display 取值为 web/desktop/both/none（必填，缺失即配置错误）；whisperEnabled / workStatusEnabled = 碎碎念 / 工作状态气泡开关（默认：true）；配几只就开几只，display 含 desktop 的宠物出现在桌面窗口（与浏览器同屏渲染），首只作为「添加宠物」的默认模板 |
| whisperPrompt | 碎碎念与对话共用的人设系统提示词（条目级：每个种类一份，种类文件顶层可覆盖）：默认「你是主人桌面上的Q版蓝发小女仆……20 字以内」；实际发出的 system = 它 + 一句「你的名字是“<宠物名>”。」 |
| chatMemoryRounds | 每次对话请求携带的最近历史轮数（默认 5；1 轮 = 1 问 1 答；0 = 不带历史）：memory.json 全存不删，此值只决定截取多少进上下文。全局默认（设置页「AI 模型与对话上下文」区一个数字输入框，改一次对所有宠物生效，含 pet pack；种类文件顶层可覆盖） |
| whisperModel / chatModel | 碎碎念 / 对话各自用哪个服务商 + 模型（全局默认：设置页改一次对所有宠物生效，含 pet pack；种类文件顶层可覆盖。设置页「AI 模型」每项一个下拉框，与 DSH 对话框右下角的模型选择器同款：搜索 + 按服务商分组的清单，选项同源）。provider 与 model 都留空 = 跟随当前对话的模型（默认）；只填一半即配置错误。填了但调用失败（凭据被删 / 模型下架）会自动回落到当前对话的模型重试一次 |
| whisperImageEnabled（0.2.9） | 碎碎念配图开关（布尔，默认开；全局默认，pet pack 可在种类文件里覆盖）：开启后每次碎碎念从 memes 池随机抽 1 张，连同那句话一起显示。token：碎碎念本来就每次生成都要调一次模型，配图只多约 100 字符（≈60 token），增量可忽略 |
| chatImageEnabled（0.2.9） | 对话配图开关（布尔，默认开；全局默认，pet pack 可在种类文件里覆盖）：开启后把整张 memes 清单交给模型按语境选 1 张（可不选；选了池外名称视为没选，标记会原样留在正文里）。token：每条消息约 1.1k 字符（≈650 token），随图片数量线性增长 |
| chatImageLimit | 对话配图张数上限（非负整数，默认 10，0 = 不限制；全局默认，pet pack 可在种类文件里覆盖）：对话时只把 memes 清单的前 N 张（= 配置里写在前面的那 N 条，想优先发哪几张就往前写）交给模型选图。原因：整张清单是每条消息都要附的，token 随张数线性增长（27 张约 1.1k 字符 ≈ 650 token），限制成前 N 张即可给配图开销封顶。设置页「AI 模型与对话上下文」区可改。只影响对话选图——碎碎念只带抽中的那一张 |
| memes（0.2.9） | 表情包映射：键 = 表情包目录里的 <键>.png 文件名（不含扩展名），值 = 该图内容的简要描述（模型据此选图/配文）。图片按素材归属查找（种类独占 pet/<前缀>-memes/ → 用户目录 memes/ → 包内 assets/memes/，与动画同规矩）；配置里写了但哪个目录都没有该文件的条目自动失效（删图不必同步改配置）；删掉某个键即停用该图 |
| notificationsEnabled | 系统通知总开关（布尔，默认开）：对话完成 / 生成失败 / 输出截断 / 权限申请 / 用户选择，窗口失焦时弹系统级通知（桌面右下角） |
| physics（0.2.5） | 拖拽抛掷物理参数（全局默认，所有宠物共用；种类文件顶层可覆盖）：gravity 重力 / restitution 碰壁恢复系数（0~1）/ groundFriction 地面摩擦 / ceilingBounce 顶部反弹 / throwPower 总力度 / petCollision 多宠物碰撞开关；缺省取内置默认（1400 / 0.78 / 2.5 / true / 1.0 / false）；gravity=0 为无重力，petCollision=true 开启多宠物碰撞 |

说明：插件安装即用，配置均为可选；设置页保存的用户覆盖写入 $DSH_HOME/dsh-pet/main-config.jsonc（用户层，优先于包内默认）。

📄 高级自定义（直接编辑配置文件）

用户数据统一收敛在 $DSH_HOME/dsh-pet/：

| 层 | 路径 | 作用 |
| 默认配置（只读） | 包内 assets/config.jsonc | 完整结构参考：宠物列表 / 动画池（idle/turn/drag/clicks/moves/categories）/ 播放权重 |
| 用户配置 | $DSH_HOME/dsh-pet/main-config.jsonc | 覆盖片段：可整体覆盖 pets / animations / animationWeights，缺省字段回落默认 |
| 对话记忆（自动生成） | $DSH_HOME/dsh-pet/memory.json | 对话历史（user/assistant 正文，全存不删；每次请求只取最近 chatMemoryRounds 轮）。删掉即清空记忆 |
| 用户动画（可选） | $DSH_HOME/dsh-pet/main-animation/ | 放入 .webm（VP9-Alpha）即可作为动画播放，优先于包内素材（放 main-animation/webm/ 子目录） |
| 用户表情包（可选） | $DSH_HOME/dsh-pet/memes/ | 放入 .png 即可作为配图，优先于包内素材；键（文件名去扩展名）与描述仍需写进配置的 memes |

- 设置页底部「高级配置」显示这些路径；「卸载与存储」列出插件的全部存储位置与卸载命令
- 自定义动画：把 xxx.webm 放进 main-animation/webm/，在动画池/分类里写 "xxx"，刷新页面即可（无需重启 DSH）
- 格式：.webm 需 VP9 Alpha 编码（Chrome/Edge/Firefox），与包内素材同规范，普通编码会有黑底
- 修改用户配置后同样刷新页面生效
- 动画名请对照默认配置填写，避免引用不存在的动画
- 表情包图片按素材归属查找（与动画同一套）：pet/<前缀>-memes/（种类独占，见下节）→ 用户目录 $DSH_HOME/dsh-pet/memes/ → 包内 assets/memes/。往用户目录放 xxx.png，再在 config 的 memes 里写 "xxx": "这张图的描述"，刷新页面即可用（加图/换图不必再改包内目录，也就不会被 add/更新覆盖）；只想去掉某张图，删 config 里对应的键即可（不用动图片文件）

🐾 额外宠物（pet pack）——添加新「种类」

默认只能调整主宠物（config.jsonc / main-config.jsonc 的 pets）。要添加全新种类的宠物（独立动画池 + 自己的素材），在用户数据根下建 pet/ 目录：

$DSH_HOME/dsh-pet/pet/
├─ pig-config.json ← 额外宠物 pig 的配置（命名词干 = 种类名，实例 id 任意） ├─ pig-animation/ ← pig 自己的动画素材（直接平铺 .webm，仿 main-animation） │ ├─ 待机.webm │ └─ 打滚.webm └─ pig-memes/ ← 可选：pig 自己的表情包（直接平铺 .png，仿用户 memes/） └─ 吃白饭的大肥鱼.png

每只额外宠物 = 一个 -config.json（配置）+ 一个 -animation/ 目录（素材），同前缀配对，扫描 pet/ 自动发现（浏览器与桌面同时生效，无需重启）；-memes/ 目录可选，有则独占该种类的配图（见下节）。

配置文件与 main-config.jsonc / config.jsonc 完全同构——直接复制一份 main 配置、换成自己的动画池，就是一只新宠物。一个 -config.json 定义一个「种类」（动画池 + 素材目录），pets 数组可放该种类的任意多只实例（每只独立 size/位置，共享动画池与素材）： jsonc // pet/pig-config.json —— 与 main-config.jsonc 同构的完整配置；animations / animationWeights 必填（不回落全局） { "notificationsEnabled": true,
"pets": [
{
"id": "pig1", // 实例 id（可多只；不必等于文件名前缀） "size": 420, "balanceEnabled": true, "display": "both", // web / desktop / both / none
"position": { "corner": "top-right", "marginX": 24, "marginY": 100 },
},
{
"id": "pig2",
"size": 360,
"balanceEnabled": false,
"display": "web",
"position": { "corner": "top-left", "marginX": 24, "marginY": 100 },
},
],
"animations": {
"idle": ["待机"],
"turn": [],
"drag": [],
"clicks": ["打滚"],
"moves": { "default": { "minDist": 80, "maxDist": 360, "margin": 20, "leadSec": 2, "tailSec": 2 }, "actions": [] },
"categories": [],
"events": {
"balance": ["余额-钱袋满溢", "余额-金袋叮当", "余额-钱袋如常", "余额-数金皱眉", "余额-袋空如洗", "余额-分文不剩"],
},
},
"animationWeights": { "idle": 80, "turn": 0, "move": 0 },
"eventsRefreshSec": { "balance": 1800 },
}

规则（与主宠物严格隔离，绝不混用）：

- 素材只查自己的：素材目录名 = 文件名前缀（pet/pig-config.json → pet/pig-animation/），该种类所有实例共用；动画 URL 为 /thumb/<前缀>/<名>.webm，查不到即 404 报错——绝不落到 main-animation 或包内素材。配图同理：pet/<前缀>-memes/ 存在时只查它（/pic/memes/<前缀>/<名>.png 查不到即 404），绝不回落到用户 memes/ 或包内 assets/memes/
- 动画池不回落全局：animations / animationWeights 是该种类的（结构校验与主配置同一套规则）
- pets 数组非空、每只字段（id/size/balanceEnabled/display/position）完整合法、数组内 id 唯一——id 随意写、数量随意，与主配置完全一致
- 用户层的「全局默认」会生效：physics / confineToScreen / whisperImageEnabled / chatImageEnabled / chatImageLimit / chatMemoryRounds / whisperModel / chatModel / eventsRefreshSec 这 9 个是用户级成本 / 偏好 / 环境 / 节奏参数——用户在设置页（写进 main-config.jsonc）改一次就对该种类生效；种类文件顶层写了则用自己那份
- 所有顶层字段都是整段替换：写了就整段用自己的，缺的子键不会从内置默认补回来（消费端各自兜底：余额周期读不到按 1800、碎碎念按 300）
- notificationsEnabled 是全局（只读 main 条目那份）：种类文件里写了不生效（不报错）
- eventsRefreshSec 内部两个键的消费端不同：.whisper 按宠物所属条目读（种类文件顶层可覆盖）；.balance 只读 main 条目（余额是一个账号一份数据，host 只有一个刷新定时器）
- 配置非法 / 缺少 -animation/ 目录 / 实例 id 与主宠物冲突 → 加载时显式报错并跳过该宠物（不影响其他宠物）
- 设置页不列出文件宠物（改文件即生效，刷新可见）；设置页保存/同步不会把它们写进 main-config.jsonc
- 添加/修改/删除 → 刷新页面（浏览器）或重启 Helper（桌面）生效

🗑️ 卸载 sh

--profile 填你安装时用的那个：桌面应用 desktop、dsh web → web

dsh plugin --profile desktop remove dsh-pet

插件在本机落下的全部位置（设置页「卸载与存储」区块也列出这些，且路径按你的机器实时解析）：

- $DSH_HOME/dsh-pet/ —— 插件用户数据：自定义配置 main-config.jsonc、对话记忆 memory.json、自定义动画素材 main-animation/、自定义表情包 memes/、文件宠物 pet/
- $DSH_HOME/electron/ —— 桌面宠物用的 Electron 运行时（体积较大；删除后下次启用桌面模式会自动重新下载）
- %APPDATA%\dsh-pet-electron-helper\ —— 桌面宠物窗口缓存与主屏缩放缓存（macOS：~/Library/Application Support/；Linux：$XDG_CONFIG_HOME 或 ~/.config/；可删，会自动重建）
- %LOCALAPPDATA%\electron\Cache\ —— Electron 安装包下载缓存（macOS：~/Library/Caches/electron；Linux：$XDG_CACHE_HOME 或 ~/.cache/；可删，需要时会重新下载）
- 插件本体 —— 由 DSH 管理，用上面的命令移除，不要手删

删之前先退出 DSH（桌面宠物随之退出）。缓存类删了无影响；$DSH_HOME/dsh-pet/ 删了会丢配置与对话记忆（想保留就先备份 main-config.jsonc）。

🖥️ 运行效果宠物实际运行在 DSH Web 界面中的样子：

🎬 效果预览

动画为透明背景；GIF 预览中透明部分显示为页面底色，实际播放为透明。

全部动画见仓库：dsh-pet/assets/webm/（VP9-alpha，唯一发布格式）。

📚 完整项目（不止是插件）

这是完整的三件套项目，任何人 clone 仓库都可以从零生成自己的桌面宠物：

① 提示词（配方） → ② 素材生成链（引擎） → ③ 插件（成品） AI 生成动画的配方 源视频 → 透明动画的管线 运行在 DSH 里的宠物

- 仓库：PC2005-cloud/dsh-pet
- 素材生成提示词：prompts/（10 秒动作提示词 + 系统通知图标提示词，可直接喂给豆包）

🔎 发现更多 DSH 插件

- 社区插件目录：awesome-dsh-plugin.com
- DSH 官方仓库：deepseek-ai/DeepSeek-Harness

📄 许可

- 代码：MIT
- 素材（动画/提示词/源视频）：允许开源使用，禁止商用