dsh-plugin-pet

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

English

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

• 6 个内置形象（blob / cat / duck / robot / axolotl / ghost，内联 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.1.0"

或使用已有的 dsh 命令：

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

pnpm 不在 PATH 上时：

cd ~/.dsh/profiles/web
corepack pnpm add "github:c-ling/dsh-plugin-pet#v1.1.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）

重启 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.1.0"
# 或：npx @deepseek-ai/dsh plugin --profile web add "github:c-ling/dsh-plugin-pet#v1.1.0"
# 或：cd ~/.dsh/profiles/web && corepack pnpm add "github:c-ling/dsh-plugin-pet#v1.1.0"

用新的 #v1.1.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/ 下，直到你手动删除该目录。

使用宠物

• 拖动宠物到任意位置；位置按浏览器记忆。
• 单击宠物抚摸它（冒出爱心）。双击隐藏它；点击爪印按钮可重新唤出。
• 心情由实时会话状态推导：空闲、思考、工作中（气泡显示当前工具名）、难过（提示词出错）、
  等待（待你确认交互），以及一轮对话完成时的庆祝跳跃。
• 更强的状态感知：长时间无操作会进入“打瞌睡”状态；工作中气泡会展示多层工具调用栈与
  当前耗时；连续工作一段时间后还会提醒喝水、休息、护眼。

陪伴养成

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

• 亲密度 / 等级 / 经验值：喂食、玩耍、抚摸会提升亲密度与经验；每日在线时长和完成任务数也会带来成长。等级上限 1000 级，满级显示 MAX。
• 互动反馈：浮层上的 🍖 / 🎾 / 🤚 按钮分别对应喂食、玩耍、抚摸，宠物会即时反馈并获得经验。
• 成就系统：连续工作、修复错误、深夜陪伴等成就会在达成时自动解锁。
• 本地统计面板：设置 → 宠物 → 陪伴成长，可查看陪伴时长、互动次数、心情分布和成就列表。

成长数据保存在 $DSH_HOME/storages/dsh-plugin-pet/stats.json，独立于外观配置，不会写入 settings。

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、thinking→8（review）、working→7（running）、
happy→4（jumping）、sad→5（failed）、waiting→6、petting→3（waving）、sleeping→0（复用 idle）。
方向行（1/2）与 V2 的朝向行（9/10）本插件不使用。

通用精灵图

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

HTTP 接口

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

/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「尾部空帧」自动检测；帧数来自规格默认值或你的显式配置。
• 宠物位置按浏览器存储（localStorage），不跨设备同步。
• 激活插件需要重启 dsh web 宿主进程（web profile 默认关闭了 Cordis HMR 宿主行）。

License

MIT