@linxin666/dsh-pet

dsh-pet · DeepSeek Harness (DSH) 桌面宠物伴侣与 Live2D 互动挂件插件

[English](README.md) | 中文

<p align="center">

<img src="https://img.shields.io/npm/v/@linxin666/dsh-client-ui-pet?style=flat-square" alt="Version">

&nbsp;

<img src="https://img.shields.io/badge/DSH-%3E%3D0.2.2--rc.1-4c6ef5?style=flat-square&amp;labelColor=454a54" alt="DSH">

&nbsp;

<img src="https://img.shields.io/badge/license-Apache--2.0-blue?style=flat-square" alt="License">

</p>

<p align="center">

<strong>DeepSeek Harness（DSH）官方 Web GUI 与桌面客户端专属桌面宠物伴侣生态</strong><br>

<em>智能体思考跟随 · Live2D / 精灵图桌宠 · 摸头喂食互动 · 实时状态气泡 · 创意工坊宠物下载</em>

</p>

一个注册表驱动的桌面宠物伴侣：内置萌系鲸鱼娘，同时支持从创意工坊一键下载安装任意 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 + 一张图集。除此之外什么都不需要——不用改任何宿主或客户端代码。

{
  "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 <dir> --write（默认 dry-run；保留 pet.json.v1.bak）。

宠物的来源（后注册的来源在同 id 冲突时覆盖前者）：

1. 内置：本包 assets/<dir>/pet.json。

2. legacy 自定义宠物：${CODEX_HOME:-~/.codex}/pets/<pet>/pet.json —— hatch-pet 流水线把产物放在这里，孵化的宠物无需任何接线即可出现在选择器里。

3. 宠物中心用户目录：$DSH_HOME/pets/<id>/——推荐安放位（见下方 CLI）。

4. 组合注入：嵌入应用通过 PetConfig.pets 传入的 manifest 条目。

用 CLI 校验并安装宠物目录（零构建、零发布）：

node scripts/dsh-pet validate <dir>           # 清单 + 资产 + Live2D 引用闭包 + voice.json
node scripts/dsh-pet install <dir>            # 校验通过后拷入 $DSH_HOME/pets/<id>/
node scripts/dsh-pet install <dir> --force    # 覆盖同名已安装宠物

非法条目永不覆盖可用宠物：它们被跳过（设置页不再列出它们；用 node scripts/dsh-pet validate <dir> 查看目录被拒的原因）。注册表在宿主启动时构建一次；新增或修改宠物后重启 dsh web 生效。

语音包与面板定制（voice.json，宠物中心 M4，#677）

气泡里的状态/工具/碎碎念文案与悬浮面板的按钮/统计/等级名，都可以被一只宠物（或你本人）整体替换——宠物不再只能换图，还能换「话」与「面板」。载体是宠物目录内的可选 voice.json（随宠物分发），以及全局覆盖文件 $DSH_HOME/pets/.voice.json（不改宠物目录即可换词）。

{
  "voicePackVersion": 1, 

…(truncated)