c-ling / dsh-plugin-pet

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 后仍然保留。

结构

文件	作用
lib/index.js	宿主插件：宠物持久化 + 挂在 harness webServer 服务上的 HTTP 路由
lib/client.js	浏览器 bundle（手写 factory-CJS，无构建步骤）：宠物浮层与设置面板
test/	node --test 测试套件，覆盖宿主路由与零依赖图片嗅探器

本包是双面插件：宿主半边是普通 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.0.3"

或使用已有的 dsh 命令：

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

pnpm 不在 PATH 上时：

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

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 按进程缓存包裁决，新包必须重启宿主），然后硬刷新页面。 宠物会出现在右下角，配置入口在 设置 → 宠物。

验证

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

用新的 #v1.0.3 重新执行安装命令即可升级依赖；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. 设置 → 宠物 → 精灵图 → 导入 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）。方向行（1/2）与 V2 的朝向行（9/10）本插件不使用。

通用精灵图

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

HTTP 接口

方法	路径	用途
GET	/dsh-plugin-pet/config	当前生效的宠物配置
POST	/dsh-plugin-pet/config	更新名字 / 大小 / 可见性 / 内置形象 / 精灵图 fps、状态行、帧数
GET/POST/DELETE	/dsh-plugin-pet/image	读取 / 上传（原始字节）/ 删除自定义图片
GET/POST/DELETE	/dsh-plugin-pet/sheet	读取 / 上传（原始字节，?source=codex&version=1|2|auto 或 ?source=custom&cols=&rows=&fps=）/ 删除精灵图
POST	/dsh-plugin-pet/petjson	导入 Codex pet.json（要求已有尺寸匹配的精灵图）

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

开发

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