桌宠养成插件mjw-git/dsh-pet

dsh-pet — 独立养成宠物插件（DeepSeek Harness）

一个独立的桌宠养成插件，面向 DeepSeek Harness（dsh，基于 Cordis 的智能体壳）。宠物随你的 agent 一起工作并成长：每条 assistant/message 汇总四个 token 桶（input/cacheRead/cacheWrite/output）累计为经验，等级解锁称号阶梯；agent 的实时状态（思考中 / 调用工具 / 出错 / 回答完成）通过 SSE 毫秒级推送驱动桌宠切换动作。宠物可命名、可换精灵表、可缩放拖放，面板为极简单色设计。

桌宠悬浮在 DeepSeek Web UI 右下角，随 token 消耗成长

开发→部署全流程（双仓库同步、打包、profile 安装、验证、排障）见 DEVELOPMENT.md。

可用精灵图下载地址：codex-pets.net（pixel 标签页下）。

特性

- 随 token 成长 —— 消耗即经验：等级、称号阶梯（单色明度渐变体现等级感）、经验进度条
- 实时状态联动 —— 宿主把会话事件投影为粗粒度状态（thinking / calling-tool / tool-ok / tool-error / answered / turn-end），经 /pet/events SSE 流推送，桌宠与页面输出同步切换动作（3 秒轮询兜底）
- 状态 → 动作映射 —— 用户自选每种状态播放精灵表的哪一行，本地保存
- 自定义精灵表 —— 单图 + JSON 布局配置上传，宿主校验尺寸/帧数并重建 manifest
- 宠物命名 / 缩放 / 拖放 —— 名字、大小（50%–200%）、位置均为本地持久化
- 消耗不可清零 —— token/经验/等级每次启动从持久会话日志重算（ground truth），/pet/reset 仅接受 sprite 范围
- 极简单色 UI —— 纯黑白卡片、衬线标题、等宽微标签、直角、无阴影
- 内网 P2P 五子棋 —— 悬浮桌宠时旋出环绕 dock（齿轮=设置、棋盘=五子棋）；15×15 双人对局走 WebRTC DataChannel，无信令服务器（同一内网两台浏览器靠手动交换两段短码完成连接）

安装（一条命令）

npx @deepseek-ai/dsh plugin --profile web add @dsh-pet/pet
然后启动 Web UI（与官方快启同一条命令）
npx @deepseek-ai/dsh web

所有内容都装在一个双面包里：@dsh-pet/pet 自带 dsh.bundle（cordis.patch.yml 把 pet 行插进组合树，安装即自动激活，无需手编任何 yml），挂载宿主半边（/pet/ 路由 + SSE 流），并以 dsh.client 声明浏览器 dock，由 dsh-client-modules 自动发现、伺服 /plugins/@dsh-pet/pet/client.js。卸载同一条命令换 remove 即可。

升级

已装过？重跑一遍 add 命令即可——裸包名解析到最新已发布版本并重写 profile 依赖（reconcile 会按安装态重新核对层列表）：

npx @deepseek-ai/dsh plugin --profile web add @dsh-pet/pet

然后重启 dsh web，浏览器硬刷新（boot 图是每次页面加载时注入的）。

- 从三包时代（≤ 0.2.1：@dsh-pet/bundle + @dsh-pet/host + @dsh-pet/ui-pet，或 0.1.0 的 @dsh-pet/client）升级——先卸旧套装再装单包：
npx @deepseek-ai/dsh plugin --profile web remove @dsh-pet/bundle @dsh-pet/host @dsh-pet/ui-pet @dsh-pet/client（多写不存在的名字没关系），再执行上面的 add。
- 0.1.1+ 需要 rc.2 线的 harness——@deepseek-ai/dsh 要一起升级（npx @deepseek-ai/dsh web 本身就跑最新）。
- 宠物数据升级不丢：XP/等级/名字在 ~/.dsh/storages + 会话日志里（每次启动从 ground truth 重算）；浏览器侧缩放/位置/状态映射是 per-origin localStorage。已保存的缩放不会被升级重置为新默认。

仓库结构

本仓库与上游 monorepo 解耦：不依赖 deepseek-harness 源码树，只消费其已发布的 npm 包（精确锁定 0.1.1-rc.2 线；当前 0.3.0；框架线 @deepseek-ai/cordis@4.0.1）。上游更新不会改变本仓库行为，除非你主动重新锁版。0.3.0 起全部合为单包 @dsh-pet/pet（0.1.x 曾拆为 host/ui-pet/bundle 三包，0.1.0 的前端旧名 @dsh-pet/client 以 /client 结尾在 rc.2 下不可用，见 DEVELOPMENT.md）。

| 包 | 路径 | 职责 |
|---|---|---|
| @dsh-pet/pet | packages/pet/ | 整只桌宠，双面一体：宿主半边（src/——经济、存储域、精灵表校验、/pet/ 路由、SSE）、浏览器半边（src/client/——右下角 dock，dsh.client 模块）、自安装 cordis.patch.yml（dsh.bundle） |

dsh-pet/
├─ package.json / pnpm-workspace.yaml / vitest.config.ts / tsconfig.base.json
├─ config/tsdown-client.ts        # 独立客户端 bundle 渲染器（模块加载器闭包、CSS 内联）
└─ packages/pet/                  # 唯一的双面包（@dsh-pet/pet）
├─ package.json                # dsh.bundle + dsh.client 声明
├─ cordis.patch.yml            # 插入 pet 行——自安装
├─ src/                        # 宿主半边：{index,spec,types,economy,catalog,usage,default-sprite,spritesheet,invariant}.ts
├─ src/client/                 # 浏览器半边：{PetCompanion,PetCompanion.module.css,agent-status,titles,locales,pet-api,slots,spritesheet,auto-sprite-config,Gomoku,gomoku-net,OrbitDock,index}
├─ assets/default-sprite.webp
└─ tests/                      # 宿主 + 前端用例（91 项）

常用命令

pnpm install        # 从 npm 解析全部 @deepseek-ai/ 依赖（锁版）
pnpm build          # tsc host → lib/types · tsc client · tsdown 客户端 bundle → lib/client.js
pnpm typecheck      # 两包 tsc --noEmit
pnpm test           # vitest：宿主经济/用量/精灵表/目录 + jsdom 桌宠用例（85 项）

客户端模块如何被伺服

浏览器半边是独立的客户端模块（dsh.client 声明 + lib/client.js）。运行时 dsh-client-modules 按需以 /plugins//client.js 提供，SPA 懒加载——安装新客户端包无需重新编译 Web bundle。已发布的客户端包只带 lib/；./src/ 导出是源码启动占位，无法从发布 tarball 加载，本仓库已移除深层 …/src/… 导入。

五子棋 —— 内网 P2P

15×15 五子棋棋盘藏在桌宠悬浮环绕 dock 后面。基于 WebRTC DataChannel 点对点直连，不使用信令服务器——同一内网两台浏览器靠手动交换两段短码完成连接：

1. 房主 → 生成邀请码 → 把邀请码（offer + 房主 ICE 候选的 base64）发给访客。
2. 访客 → 加入 → 粘贴邀请码 → 把回执码（answer + 访客 ICE 候选的 base64）发回给房主。
3. 房主 → 粘贴回执码 → 连接 → 数据通道打开。

iceServers: [] 只收集 host 候选（无 STUN/TURN、无外部依赖），因此隔离内网也能用。现代浏览器把内网 IP 混淆成 mDNS .local 主机名；同机双标签页最稳，或在 chrome://flags/#enable-webrtc-hide-local-ips-with-mdns 关掉混淆以获得原始 IP 候选。落子以 {t:'move',x,y,c} 在通道传输；双方各自维护棋盘并用 winLine 本地判定五连，获胜的几颗子会脉动直到房主重开。点面板只隐藏（peer 连接与棋局状态保留）；退出房间才真正拆掉会话。详见 packages/pet/README.zh.md。

发布（由维护者执行——需要 npm 凭据）

三个包都发布到 @dsh-pet scope。请用 pnpm publish（不要用 npm publish）：pnpm 会把工作区内部的 workspace: 依赖（客户端 → 宿主、bundle 的 peer）规范化为真实版本。

./scripts/publish.sh              # 构建测试门禁 → 打包断言 → 发布

发布后，本地安装命令即可从 file: tarball 换成裸包名（无 pnpm file: 缓存问题）。

实机验证

端到端开跑（dsh web → 右下角出现悬浮桌宠 → 发消息 → XP 增长 / 称号变化 → 桌宠随输出实时切换动作 → 上传精灵表 / 改名 / 调大小）需要运行中的 harness 与 API key。除真实 provider 调用外的一切均已由测试覆盖；本地 tarball 装进 profile 的完整链路亦已实测（见 DEVELOPMENT.md §3.7 的 curl 验证清单）。

版本策略

依赖在各包 package.json 中锁定。要吸收一次 harness 发布：把 @deepseek-ai/dsh-* 锁版与框架版本线一起提升，重跑 pnpm install && pnpm build && pnpm test，并确认 config/tsdown-client.ts 中的客户端外部平台模块集与新 harness 提供的保持一致。