dsh-plugin-pet

DeepSeek Harness Web GUI 的桌面电子宠物插件：由实时 agent 状态驱动心情动画，支持内置形象、自定义图片与 Codex 风格多帧精灵图导入。

English

一个为 DeepSeek Harness Web GUI 打造的桌面电子宠物插件，灵感来自 Codex companion 与 Claude Code Buddy。宠物常驻页面右下角，实时响应 agent 的状态（思考 / 调用工具 / 报错 / 完成 / 等待你操作），并支持改名、缩放、隐藏与完全换肤：

• 14 个内置形象（blob / cat / duck / robot / axolotl / ghost / panda / shiba / fox / bunny / penguin / frog / owl / slime，内联 SVG，纯 CSS 动画），并带心情联动表情系统—— 每只形象都会眨眼，并随心情切换眼睛（开心 ^ ^ / 难过 / 安睡闭眼）与嘴形（微笑 / 咧嘴笑 / 瘪嘴）
• 自定义图片上传（PNG / JPEG / GIF / WebP；动图会原样播放）
• Codex 风格多帧精灵图——导入 Codex 宠物包（pet.json + spritesheet.webp，V1 1536×1872 与 V2 1536×2288，见 Codex pet package spec）， 或配置通用网格（列数 / 行数 / fps / 各心情状态行）

所有二进制素材（自定义图片/精灵图）都保存在 $DSH_HOME/storages/dsh-plugin-pet/ 下，重启 dsh web 后仍然保留。 在 DSH 1.0.7 且挂载 settings 服务时，宠物配置会写入 $DSH_HOME/settings.yaml；没有 settings 服务时自动回退到 storages/dsh-plugin-pet/config.json。

结构

本包是双面插件：宿主半边是普通 Cordis 插件；客户端半边通过 "dsh": { "client": { "platform": "web", "inject": [], "immediately": true } } 加 "./client" 导出声明，因此 harness 的 client 模块系统会在 /plugins/dsh-plugin-pet/client.js 提供它，并在启动时立即加载。

安装

从 GitHub 安装到 web profile（需要 pnpm 在 PATH 上；没有则用下面的 corepack 方式）：

npx @deepseek-ai/dsh plugin --profile web add "github:c-ling/dsh-plugin-pet#v1.4.0"

或使用已有的 dsh 命令：

dsh plugin --profile web add "github:c-ling/dsh-plugin-pet#v1.4.0"

pnpm 不在 PATH 上时：

cd ~/.dsh/profiles/web
corepack pnpm add "github:c-ling/dsh-plugin-pet#v1.4.0"

dsh plugin 把参数原样转发给 pnpm，直接从本仓库拉取包（pnpm 9+，本机需装有 git）。 安装时若看到 declares no dsh.bundle — installed as a plain dependency 的提示属正常现象： 本插件不是 profile bundle 层，而是通过下面的 loader 行激活。

然后在 ~/.dsh/profiles/web/cordis.patch.yml 增加一行插入：

- insert:
    - id: dsh-plugin-pet
      name: 'dsh-plugin-pet'
      config:
        maxImageBytes: 5242880        # 可选：单张图片上传上限（默认 5 MB）
        maxSheetBytes: 10485760       # 可选：精灵图上传上限（默认 10 MB）
        interactionCooldownMs: 1500   # 可选：互动冷却毫秒（默认 1500，0 关闭）
        maxDailyInteractions: 500     # 可选：每日互动计次上限（默认 500）

重启 dsh web（client-modules 按进程缓存包裁决，新包必须重启宿主），然后硬刷新页面。 宠物会出现在右下角，配置入口在 设置 → 宠物。

1.0.7 配置

在 Harness 1.0.7 且已挂载 settings 服务时，Settings → 宠物 的配置会持久化到 $DSH_HOME/settings.yaml； 客户端通过 settingsScope 响应式读取。如果本地 link: 开发时没有安装 @deepseek-ai/dsh-settings， 设置页会自动降级读写 $DSH_HOME/storages/dsh-plugin-pet/config.json。

验证

curl -s http://127.0.0.1:3080/plugins/dsh-plugin-pet/client.js | head -c 60

应输出 window.__ModuleLoader__.load({ 开头的 factory bundle；页面右下角能看到宠物。

更新

dsh plugin --profile web add "github:c-ling/dsh-plugin-pet#v1.4.0"
# 或：npx @deepseek-ai/dsh plugin --profile web add "github:c-ling/dsh-plugin-pet#v1.4.0"
# 或：cd ~/.dsh/profiles/web && corepack pnpm add "github:c-ling/dsh-plugin-pet#v1.4.0"

用新的 #v1.4.0 重新执行安装命令即可升级依赖；cordis.patch.yml 中的 loader 行保持不变。 重启 dsh web，然后硬刷新页面。

卸载

cd ~/.dsh/profiles/web
corepack pnpm remove dsh-plugin-pet   # 或 dsh plugin --profile web remove dsh-plugin-pet

同时删除 cordis.patch.yml 中对应的 insert 行，然后重启 dsh web。 已上传的数据仍保留在 $DSH_HOME/storages/dsh-plugin-pet/ 下，直到你手动删除该目录。

使用宠物

• 拖动宠物到任意位置；位置按浏览器记忆。拖动时会朝移动方向播放奔跑动画 （Codex 精灵图为行 1 / 行 2，内置形象为翻转的奔跑动画）。
• 单击宠物抚摸它（冒出爱心）。双击隐藏它；点击爪印按钮可重新唤出。宠物支持键盘操作：Tab 聚焦后按 Enter / 空格抚摸。
• 心情由实时会话状态推导：空闲、思考、工作中（气泡显示当前工具名）、难过（提示词出错）、 等待（待你确认交互），以及一轮对话完成时的庆祝跳跃。
• 更强的状态感知：长时间无操作会进入“打瞌睡”状态；工作中气泡会展示多层工具调用栈与 当前耗时；连续工作一段时间后还会提醒喝水、休息、护眼。
• 成就解锁与升级会在浮层上方弹出提示气泡。

陪伴养成

宠物不再只是“状态显示器”，而是一个会成长的桌面伙伴：

• 亲密度 / 等级 / 经验值：喂食、玩耍、抚摸会提升亲密度与经验；每日在线时长和完成任务数也会带来成长。等级上限 1000 级，满级显示 MAX。
• 互动反馈：浮层上的 🍖 / 🎾 / 🤚 按钮分别对应喂食、玩耍、抚摸，宠物会即时反馈并获得经验。
• 成就系统：连续工作、修复错误、深夜陪伴等成就会在达成时自动解锁，并弹出提示。
• 本地统计面板：设置 → 宠物 → 陪伴成长，可查看陪伴时长、互动次数、心情分布和成就列表。
• 防刷与去重：互动接口有服务端冷却（默认 1.5s，可用 interactionCooldownMs 配置）与每日上限（maxDailyInteractions，默认 500）；多标签页只由主标签发送心跳，后台标签不计在线时长、不采样心情。

成长数据保存在 $DSH_HOME/storages/dsh-plugin-pet/stats.json，独立于外观配置，不会写入 settings。 每次成功写入都会同步写一份 stats.json.bak；主文件损坏时自动从备份恢复，不会清零成长记录。

Codex 精灵图导入

1. 设置 → 宠物 → 精灵图 → 导入 Codex 宠物包。
2. 先上传 spritesheet.webp/spritesheet.png。图片必须是 1536×1872（V1，9 行） 或 1536×2288（V2，11 行）——8 列网格、每格 192×208。版本会自动检测。
3. 可选导入 pet.json——它会应用 displayName 并校验 spriteVersionNumber 是否与已上传 的精灵图匹配。

Codex 状态行与 DSH 心情的映射：idle→0、run_right→1（running-right）、run_left→2（running-left）、 petting→3（waving）、happy→4（jumping）、sad→5（failed）、waiting→6、working→7（running）、 thinking→8（review）、sleeping→0（复用 idle）——V1 的九行动作全部启用。仅 V2 的朝向行（9/10） 不使用。

通用精灵图

在 精灵图 → 通用精灵图 下，任何宽高能被网格整除的 PNG/WebP 都可用：设置列数、行数与 fps，上传图片，再为每个心情分配行号与帧数。应用前会有一个实时预览播放动画。

HTTP 接口

上传统均在服务端校验：魔数嗅探（PNG/JPEG/GIF/WebP）、大小上限、Codex 精确尺寸，以及通用 网格的整格切分。配置与成长统计写入都是原子性的，并保留 .bak 备份供损坏恢复。

错误响应带稳定机器码（{ ok: false, error, code, params? }，如 bad_json / too_large / codex_size / grid_uneven），由客户端按当前语言翻译显示。成长类接口 （heartbeat / interaction / task / event）的响应额外携带 unlockedKeys（本次新解锁的成就） 与 levelUp（跨过的等级，未跨级为 null）；interaction 超出冷却或每日上限时返回 throttled: true 且不加值。

/dsh-plugin-pet/config 在 DSH 1.0.7 有 settings 服务时仍可用作兼容写入入口（host 会同步到 settings）；客户端优先通过 settingsScope 读取，无 settings 服务时该路由作为 fallback。

开发

node --check lib/index.js lib/client.js
node --test test/sniff.test.mjs test/host.test.mjs

客户端 bundle 是 harness 的 factory-CJS 格式纯 JavaScript （window.__ModuleLoader__.load({ id: "dsh-plugin-pet", factory })）；require("react") 解析 到 shell 的静态模块表，所有 UI 贡献都通过 shell.overlay 与 settings.section 插槽注册， 并用 ctx.effect 持有的 disposer 管理生命周期。

已知限制

• 每页只有一个全局宠物（根作用域浮层），不按会话区分。
• 未实现 Codex「尾部空帧」自动检测；帧数来自规格默认值或你的显式配置。
• V2 精灵图的朝向行（9/10，look-directions）仍不使用。
• 宠物位置按浏览器存储（localStorage），不跨设备同步。
• 激活插件需要重启 dsh web 宿主进程（web profile 默认关闭了 Cordis HMR 宿主行）。

License

MIT