# dsh-pet · DeepSeek Harness (DSH) 桌面宠物伴侣与 Live2D 互动挂件插件
[English](README.md) | 中文
DeepSeek Harness（DSH）官方 Web GUI 与桌面客户端专属桌面宠物伴侣生态
智能体思考跟随 · Live2D / 精灵图桌宠 · 摸头喂食互动 · 实时状态气泡 · 创意工坊宠物下载
> 一个注册表驱动的桌面宠物伴侣：内置萌系鲸鱼娘，同时支持从创意工坊一键下载安装任意 Live2D 与精灵图桌宠。
模型思考时你在等待，你的桌面宠物在屏幕上畅游交互。它深度跟随 DeepSeek Harness 官方智能体会话生命周期，在空闲等待、模型思考、调用工具（Bash / 代码编写 / 网页检索）、整理回复、庆祝完成与报告失败时自动无缝切换动画；你还可以随时摸摸头、喂食小鱼干互动，看着专属亲密度与等级不断提升。桌面宠物基于资产注册表驱动而不是硬编码：每只宠物只需一份 `pet.json` manifest 加一张贴图集（或 Live2D 动作模型包），宿主启动时自动发现并支持热切换。
从桌面应用的经典宠物系统重构演进，完美适配官方 DSH 插件形态（cordis bundle：host 宿主半区 + client 浏览器半区一站式融合）。
## 功能
| 功能 | 说明 |
|---|---|
| 多宠物注册表 | 宿主扫描内置 `assets/`、hatch-pet 自定义宠物目录和组合配置条目；每只宠物 = manifest + 图集 |
| 设置中选择宠物 | 可视化预览卡列出所有已注册宠物（内置资产 + 用户目录，即已安装集合）；切换即持久化，精灵立即更换。页面位于「设置 → Web 扩展 → 宠物」，父级缺席时保留一级「宠物」分区 |
| 每只宠物独立命名 | 在悬浮面板改名；每只宠物保存自己的名字（按宠物 id 存储，旧版平铺名字自动迁移） |
| 状态动画 | 官方会话活动 → manifest 定义的 9 态轨道序列；每条轨道播完自身完整时长后切换，整条序列循环 |
| 摸头互动 | 点击宠物 → 气泡反馈 + 亲密度 +1（10s 冷却） |
| 喂食 | 悬浮面板 喂食 → 消耗 1 条小鱼干 + 亲密度 +5（30s 冷却） |
| 小鱼干经济 | 库存（上限 20）：每工作 30 轮 +1，每 300 分钟（5 小时）+1 —— 获取难度为原来的 10 倍 |
| 亲密度 | 每完成一轮 +1；9 级：幼鲸 → 伙伴 → 挚友 → 深海羁绊 → 心有灵犀 → 传说羁绊 → 神话羁绊 → 永恒之契 → 鲸生共渡（上限 999,999,999） |
| 拖动 | 按住拖动宠物换位置；位置持久化 |
| 隐藏/召唤 | 悬浮面板位于宠物下方（下方空间不足时上移到状态气泡之上）并提供 隐藏；隐藏后出现 召唤{name} 按钮 |
| 妙语库 | 内置默认妙语库（每类事件 10 句）+ 宠物自定义台词；成功文案按持久化成功次数轮换，冷却文案按持久化拒绝次数轮换 |
| 状态气泡 | 默认只有一个顶层会话说话——上报 GUI 当前会话时优先它，否则是最近活动的一个——其余会话收进主气泡右上角的 +N 角标，不再叠出一长列；悬停气泡（触屏点按角标）即可向上展开所有会话的气泡，点击任一气泡跳转到对应会话；子代理会话借由其发起会话体现，不占用独立气泡；瞬时互动反馈临时优先。气泡文案按场景准备了大量轮换词库（等待 / 思考 / 整理 / 完成 / 失败……），工具调用按工具族映射俏皮文案并带上真实参数（如 跑跑 npm test），同一场景持续数秒会自动换一种说法。宠物自带的这些状态气泡可在 设置 → Web 扩展 → 宠物 → 状态气泡 关掉，此时整行气泡留给自建气泡面的插件；通过 `pet.announce` 推送的公告气泡两种模式下都照常渲染 |
| 碎碎念 | 会话流式输出期间，宠物会偶尔借该会话自己的气泡说出内心独白——新鲜的碎碎念接管所属会话的气泡并以「」引号标记——与状态气泡共用同一片 DeepSeek 蓝黑玻璃，气泡栈内颜色统一不再色差——不再叠出第二只气泡——分类台词由「正在干什么」触发（思考 / 写回复 / 正在跑的工具族），结果台词只由结构化结果触发（测试工具通过 → 全绿、工具失败 → 报错、回合完成 → 收工）——决不读模型说的话，讨论里提到关键词也不会误触发心境；碎碎念也从不引用真实内容（无工具名、路径、模型原文）；分类冷却 9 秒、结果冷却 5 秒，展示 8 秒后气泡恢复状态文案 |
| 多会话活动 | 宠物是宿主全局的：最近一次有意义事件驱动精灵动画，同时每个活动的顶层会话用自己的气泡报告各自状态；每个会话（含子代理）完成的轮次都计入亲密度与小鱼干 |
| 语音包与面板 DIY | 宠物目录 voice.json + 全局 $DSH_HOME/pets/.voice.json 覆盖气泡全部文案与悬浮面板（按钮标签/统计格式/按钮显隐）；合并优先级 宠物自带 > 全局 > 内置，坏包警告不拒载 |
| 面板动作扩展点 | 兄弟插件通过进程内 pet 服务（`ctx.pet.registerPanelAction({ id, label, onSelect })`）把自己的动作注册进悬浮面板的动作行；宠物渲染按钮并把点击派发回插件自己的回调，动作随注册一起回收 |
## 宠物契约
一只宠物 = 一个目录 + 一份 `pet.json` manifest + 一张图集。除此之外什么都不需要——不用改任何宿主或客户端代码。
```jsonc
{
"id": "whale-girl", // 唯一的小写 kebab id
"displayName": "鲸鱼娘", // 显示在设置选择器与面板上
"description": "一只软萌治愈的鲸鱼娘。", // 可选
"spritesheetPath": "spritesheet.webp", // 图集，相对 manifest 所在目录
"cell": { "width": 192, "height": 208 }, // 可选；默认 Codex 契约
"columns": 8, // 可选；默认 8
"spriteVersionNumber": 1, // 可选；2 表示 11 行 v2 图集（9 行动画行 + 2 行视线跟随行）
"frames": [6, 8, 8, 4, 5, 8, 6, 6, 6], // 可选的每行帧数
"tracks": { // 可选的每轨节奏覆盖
"idle": { "durations": [400, 400, 500, 400, 400, 500] }
},
"sequences": { // 可选的每场景轨道序列（每条至少 5 项）
"thinking": ["running", "running-right", "running", "running-left", "waiting"]
},
"remarks": { // 可选妙语（每个槽位一行或多行）
"pet": "摸摸水獭的头～",
"feed": ["小鱼干真香", "再来一条～"]
}
}
```
- 图集是 8 列 × 9 行网格（默认 192×208 单元格）；行序固定：0 idle、1 running-right、2 running-left、3 waving、4 jumping、5 failed、6 waiting、7 running、8 review。未使用的格子保持全透明。v2（Codex）图集在 manifest 里声明 `"spriteVersionNumber": 2`，共 11 行——同样的 9 行动画行外加末尾 2 行视线跟随行；插件渲染这 9 行动画行、忽略视线行。
- 可选 remarks 块覆盖宠物在 pet（摸头）/ petCooldown / feed（喂食）/ feedCooldown / noTreats（缺粮）事件上的气泡台词。每个槽位接受一句或一组台词；声明过的槽位只替换该槽位的内置默认池。成功与冷却池使用对应的持久化成功或拒绝次数，noTreats 则独立轮询。社区贡献就是这样给自家宠物配上专属妙语的。
- `frames` 记录每行用到的列数（缺省按 hatch-pet 契约表 `[6, 8, 8, 4, 5, 8, 6, 6, 6]`）；`tracks` 按动画覆盖每帧时长（按该行帧数循环补足）、`loop` 与 `fallback`（默认：全部循环；`jumping` 与 `failed` 停在最后一帧后回到 `idle`）。
- `sequences` 可选地把活动场景（`idle` / `waiting` / `thinking` / `tool` / `review` / `done` / `failed`）映射到至少 5 条动画轨道。每项按 `tracks` 中的时长播完所有帧后进入下一项，整条序列循环；未声明的场景保持标准单轨播放。
### 清单 v2（宠物中心，#623）
宠物目录的 `pet.json` 在 v2 中显式声明渲染器：
- `petManifestVersion: 2`（缺省 = v1，按 `sprite2d` 兼容读并给出迁移提示）；
- `renderer`：`"sprite2d"`（上文图集契约）、`"live2d"` 或 `"frames2d"`；
- `license`（v2 必填）：资产授权标识——社区宠物必须携带来源声明；
- 渲染器专属块：`sprite2d`（spritesheetPath/cell/columns/atlasRows/frames/tracks）、`live2d`（model/motions/expressions/hitAreas/scale/translate）或 `frames2d`（dir/defaultFrameMs/tracks/phases——目录式帧序列）。
校验纪律：结构 fail-closed（未知字段或未知渲染器直接拒载并给出诊断），sequences/remarks 内容维持 warn-and-drop。机器可读 schema 见 `contracts/pet-manifest-v2.schema.json`，权威校验器为 `src/manifest-v2.ts`。迁移 v1 清单：`node scripts/dsh-pet-migrate-v2.mjs --write`（默认 dry-run；保留 `pet.json.v1.bak`）。
宠物的来源（后注册的来源在同 id 冲突时覆盖前者）：
1. **内置**：本包 `assets//pet.json`。
2. **legacy 自定义宠物**：`${CODEX_HOME:-~/.codex}/pets//pet.json` —— hatch-pet 流水线把产物放在这里，孵化的宠物无需任何接线即可出现在选择器里。
3. **宠物中心用户目录**：`$DSH_HOME/pets//`——推荐安放位（见下方 CLI）。
4. **组合注入**：嵌入应用通过 `PetConfig.pets` 传入的 manifest 条目。
用 CLI 校验并安装宠物目录（零构建、零发布）：
```sh
node scripts/dsh-pet validate # 清单 + 资产 + Live2D 引用闭包 + voice.json
node scripts/dsh-pet install # 校验通过后拷入 $DSH_HOME/pets//
node scripts/dsh-pet install --force # 覆盖同名已安装宠物
```
非法条目永不覆盖可用宠物：它们被跳过（设置页不再列出它们；用 `node scripts/dsh-pet validate ` 查看目录被拒的原因）。注册表在宿主启动时构建一次；新增或修改宠物后重启 `dsh web` 生效。
## 语音包与面板定制（voice.json，宠物中心 M4，#677）
气泡里的状态/工具/碎碎念文案与悬浮面板的按钮/统计/等级名，都可以被一只宠物（或你本人）整体替换——宠物不再只能换图，还能换「话」与「面板」。载体是宠物目录内的可选 voice.json（随宠物分发），以及全局覆盖文件 $DSH_HOME/pets/.voice.json（不改宠物目录即可换词）。
```jsonc
{
"voicePackVersion": 1, // 可选；缺省视为 1
"status": { // 状态池：键 = 场景 id，逐键覆盖内置池
"done": ["搞定收工～", "交差！下一位"]
},
"tools": { // 工具池：键 = 工具族；允许 {tool} / {hint}
"shell": ["跑跑 {hint}", "敲回车！{hint}"]
},
"toolRemaining": ["后台还有 {n} 位小助手"], // 允许 {n}
"whispers": { // 碎碎念：按键替换内置池
"categories": { // 分类池；显式空数组 = 静音该分类
"thinking": ["让我想想……"],
"running": ["正在跑，我盯着"]
},
"results": { // 结果池（测试全绿 / 报错 / 完成）
"pass": ["全绿！"]
}
},
"panel": { // 悬浮面板（每槽未声明时回落插件 i18n 文案）
"labels": { "feed": "投喂", "hide": "藏起来", "rename": "起名字", "confirm": "好的" },
"stats": { "rank": "好感 {rank}", "treats": "鱼干 ×{n}", "points": "{points} 分" },
"ranks": [ // 仅显示用的等级阶梯；首条 min 必须为 0
{ "min": 0, "name": "小煤球", "nameEn": "Little Coal Ball" },
{ "min": 25, "name": "火星伙伴", "nameEn": "Martian Buddy" }
],
"actions": ["feed", "rename", "hide"] // 子集（按规范顺序）；省略 = 全部；[] = 只显示统计行
}
}
```
- 合并优先级（逐槽）：宠物自带 voice.json > 全局 .voice.json > 内置文案。status/tools/whispers 逐键合并、panel 逐槽合并，任何层缺失的槽位回落下一层。
- 占位符白名单：tools 允许 {tool} / {hint}；toolRemaining 允许 {n}；panel.stats 允许 {rank} / {n} / {points}；status、碎碎念与面板标签不允许任何占位符（含非法占位符的行被警告丢弃）。
- 等级阶梯（panel.ranks）：替换该宠物内置的鲸鱼等级名，仅影响显示——点数、每轮奖励、冷却与持久化账本都不变。必须是 1-16 条的数组，首条 min 为 0，min 严格递增且唯一，名字 1-24 字符。name 为默认名字；nameEn 在 UI 语言为英文时显示（省略则两种语言都用 name）。非法阶梯整体丢弃并警告，沿用内置名字。panel.stats 的 {rank} 收到宠物当前等级名。
- 上限（warn-and-drop）：每池 64 行以内、每行 160 字符以内；面板标签 40 以内、统计 80 字符以内。
- 坏包不影响宠物：voice.json 不是合法 JSON 或根不是对象 → 警告并整体忽略；其余问题逐槽警告丢弃。node scripts/dsh-pet validate 会把结构错误判为安装失败、内容问题列为警告。
- 语义细节：status/tools 的空池回落内置文案（场景行始终有话说）；whispers 的显式空数组是静音（关掉该通道）；面板 actions 为空数组 = 三个按钮全部隐藏；未覆盖的按钮/统计继续使用插件双语字典。旧的 whispers.generic / whispers.rules 字段已不再支持，会被忽略并给出警告。
## Live2D 宠物（renderer: live2d）
Live2D 宠物经 PixiJS/WebGL 渲染：MIT 许可的 pixi.js + untitled-pixi-live2d-engine 栈以按需加载的 vendor 分包随插件内置，纯 sprite 用户永不下载、永不解析它。**本插件永不内置、永不代下 Cubism Core 运行时**——Live2D 专有许可不允许再分发。启用 Live2D 宠物：
1. 自行从 Live2D 官方渠道获取 Cubism SDK for Web（你自行同意其许可），取得 `live2dcubismcore.min.js`；
2. 放到 `$DSH_HOME/pets/.runtime/live2dcubismcore.min.js`——插件把它连同自带的 vendor 分包一起提供给页面；
3. 安装 Live2D 宠物（含 `pet.json` v2、`renderer: "live2d"` 与模型文件的目录）。
core 缺失时，Live2D 宠物在渲染位置给出安装指引卡；sprite2d 宠物不受影响。法律提示：本插件属 Live2D 术语下的「可扩展性 APP」——你公开发布基于可加载用户模型的衍生作品时，可能不论规模都须与 Live2D 签订发行许可；发布前请自行评估义务。
Live2D 清单把七个活动相位映射到模型的动作组：
```json
{
"petManifestVersion": 2,
"id": "my-live2d-pet",
"displayName": "My Live2D Pet",
"license": "CC0-1.0",
"renderer": "live2d",
"live2d": {
"model": "model/my-pet.model3.json",
"motions": { "idle": "Idle", "thinking": "Think", "failed": "TapBody" },
"hitAreas": ["Body"]
}
}
```
- `model`：相对宠物目录的 `.model3.json` 路径。模型引用的一切文件（moc、贴图、动作、物理、姿态、表情）都必须放在目录内——宿主恰好只服务这个引用闭包。
- `motions`（必填，且必须含 `idle`）：相位 → 动作组。未映射的相位与模型缺失的组一律回退 `idle`；组内有多条动作时随机播放一条。官方 Cubism 示例模型只带 `Idle` 与 `TapBody` 两个组。
- `expressions`（可选）：相位 → 表情名，叠加在动作之上。
- `hitAreas`（可选）：点击落在列出的命中区时播放模型的 `TapBody` 组，播完回到当前相位的动作组。任何点击仍计入摸头——交互经济与 sprite2d 一样由 chrome 掌管。
- `scale` / `translate`（可选）：模型自动适配显示盒；`scale` 在适配结果上乘算（默认 1，范围 (0, 10]），`translate` 以中心为基准做像素偏移。
模型授权：Live2D 官方示例模型（Hiyori、Haru 等）仅供评估、禁止再分发——只发布你有权的模型（原创作品或宽松授权的模型）。
## Frames2d 宠物与玩法（renderer: frames2d）
frames2d 宠物不用图集，直接交付目录式帧序列：`thumb/