orxz/deepseek-harness-pets

deepseek-harness-pets

让 DeepSeek Harness 的状态动起来——官方原生 dsh 桌宠插件。

安装

两条命令（v0.2.2 起已上 npm）：

dsh plugin --profile web add deepseek-harness-pets
dsh web

打开 http://localhost:3080——鲸鱼已经在右下角了。完整指南（前置条件、源码安装、手写 patch 行、故障排查）：docs/installation.zh.md。

本项目是一个符合 DeepSeek Harness (dsh) 官方原生安装要求的插件：按官方 bundle/profile 机制安装后，一只鲸鱼（官方 DeepSeek Whale SVG，v0.2 艺术层）会常驻 DSH Web UI 的右下角悬浮窗（shell.overlay 插槽，不占用聊天流），随你的评测与回合状态实时换动作、弹气泡——像 Codex 桌宠一样，但零外部依赖。

宠物可通过 cordis.yml 一行配置切换或随机；宠物资产采用 Petdex 标准格式（pet.json + 8×9 spritesheet），将来可直接复用到 Petdex 桌面悬浮端或提交到 petdex.dev 社区画廊。

效果演示

真实 dsh web 会话截图（dsh 0.1.0-rc.5，零 console 报错）：

| 闲置——浮动打瞌睡 zzZ | 悬停——“嗯？” | 点击——跃起 + 随机开心文案 | 拖拽——位置持久化，刷新不丢 |
|:---:|:---:|:---:|:---:|
| 右下角闲置悬浮窗 | 悬停反应气泡 | 点击反应气泡 | 拖拽到自定义位置 |

可拖到视口内任意位置（clamp 不越界，localStorage 持久化）。全部截图见 docs/screenshots/；像素 spritesheet 就绪后补 GIF（见 皮肤创作指南）。

免责声明：本项目是社区驱动的非官方项目，与 DeepSeek（深度求索）无隶属关系。"DeepSeek" 是 DeepSeek AI 的注册商标，此处仅作主题致敬。

包名区分：dsh 官方为 npm 包 @deepseek-ai/dsh（Node.js）。PyPI 上的 deepseek-harness 是与本插件无关的第三方 Python 库，安装时请勿混淆。

核心特性

- 官方原生安装：标准 dsh bundle（package.json 的 dsh.bundle.patch + cordis.patch.yml），无 fork、无补丁宿主。
- 右下角常驻悬浮窗：宠物浮在 Web UI 右下角（shell.overlay root 域插槽，跨会话常驻，不占聊天流），基于官方 DeepSeek 鲸鱼 SVG，随回合状态实时换 CSS 动画。
- 拟真互动四项：点击（跃起 + 随机开心文案，~1.5s 回落）、悬停（放大微倾 + 气泡"嗯？"）、随机闲置（idle 时每 20–60s 一次 3s 小动作）、拖拽（自由摆放、clamp 视口内、localStorage 位置持久化，刷新不丢）。
- 状态实时映射：dsh durable session 事件（turn/step/tool）驱动宠物状态机，评测跑分过程一眼可读。
- 彩蛋触发：评测完成弹 Score 气泡、跃出水面；检测到 SOTA 特征（v0.1 为文本近似判定）触发限定动画。
- 宠物切换 / 随机：默认出场是 DeepSeek 标志性大鲸鱼 deepseek-whale；可在 ~/.dsh/settings.yaml（用户设置层）或 profile patch（base 层）换成 random（按 turn id 种子确定性选择，重放一致）或三源发现的任意皮肤；设置面板选择行开发中（见 Roadmap）。注：v0.2 悬浮窗艺术层统一渲染鲸鱼 SVG，其他皮肤的专属视觉待 spritesheet 就绪（见 Roadmap）。
- 皮肤源优先级：自定义源 > Petdex 社区源 > 内置源——同名皮肤高优先源覆盖，你的自定义皮肤永远赢。
- Petdex 资产兼容：像素资产即标准 Petdex 宠物包，可 npx petdex submit 上架社区画廊。

宠物状态映射

三层契约：dsh 事件信号 → 插件语义状态 → 悬浮窗 CSS 动画 + 气泡（Petdex 动画行作为 spritesheet 就绪后的资产契约保留）。机器可读版见 mappings/harness-states.json。

| dsh 事件信号 | 语义状态 | 动画行 | 悬浮窗视觉 / 气泡 |
|---|---|---|---|
| 会话空闲 | idle | idle | 缓慢浮动打瞌睡 / zzZ |
| turn/start 后首轮准备 | loading | waiting | 上浮蓄力 / 加载数据中 |
| step/start、工具高频活动 | inferring | running | 左右摇摆游动 / 推理中 |
| 报告/评分类工具调用 | scoring | review | 审视微旋 / 评分中 |
| turn/end 正常完成 | done | waving | 摆动挥舞 / 完成！ |
| 完成且带 SOTA 文本特征 | sota | jumping | 跃起回弹 / SOTA！ |
| turn/end 失败/中断 | error | failed | 翻肚灰度 / [ERROR] 请检查日志 |

悬浮窗视觉由 src/pet-art.js 的 OVERLAY_ANIMATIONS 动画表驱动（CSS transform keyframes，v0.2 艺术层为内联鲸鱼 SVG）；动画行仍为 Petdex 9 标准行（idle / running / running-left / running-right / waving / jumping / failed / waiting / review）的子集，供 spritesheet 切换点消费。失败信号（status: failed、error、outcome: stopped）任一命中即进入 error。

安装

前置：Node.js ≥ 22，已可运行 dsh web（dsh 0.1.0-rc.5 验证通过）。

方式 A：安装到 dsh profile（官方 bundle 机制，已实测）

1) 构建浏览器半边产物 lib/client.js（dsh 的 node 半边按 exports["./client"] 加载它）
cd deepseek-harness-pets && npm install && npm run build

2) 登记进 web profile（~/.dsh/profiles/web）
package.json 两处：dependencies 加 "deepseek-harness-pets": "link:"；
dsh.profile.bundles 数组末尾追加 "deepseek-harness-pets"
cd ~/.dsh/profiles/web && pnpm install

3) 重启 DSH Web（bundle 不热加载）
dsh web

安装后可用 dsh --profile web --dump-config 检查 deepseek-harness-pets 行是否在组合树中；
浏览器打开后 window.__DSH_BOOT__ 应含该条目，/plugins/deepseek-harness-pets/client.js 返回 200，且打开任意会话应看到右下角鲸鱼悬浮窗（idle 浮动 + zzZ 气泡）。

方式 B：dsh plugin add（等价于方式 A 的自动化路径）

dsh plugin --profile web add    # dsh 0.1.0-rc.5 实测可用

方式 C：从 npm 安装（发布后可用）

npm install -g deepseek-harness-pets   # 计划中，见 Roadmap

给本仓库打上 GitHub topic dsh-plugin，即可被 dsh 官方插件生态发现。

皮肤源优先级（custom > petdex > bundled）

插件启动时扫描三个皮肤目录，同名 slug 按以下优先级覆盖（离线判定，不依赖网络）：

| 优先级 | 源 | 目录 | 说明 |
|---|---|---|---|
| 1（最高） | 自定义 custom | ~/.dsh/pets/（$DSH_HOME/pets） | 你自己放或 hatch-pet 生成的皮肤，可覆盖任何同名皮肤 |
| 2 | Petdex 社区 petdex | ~/.petdex/pets/ | npx petdex install  落地的社区皮肤 |
| 3（兜底） | 内置 bundled | 插件包内 assets/pets/ | 随插件分发的 deepseek-whale / deepseek-octo |

合并后的池进入设置可选值与 random 随机池（设置面板选择行开发中，当前经 settings.yaml 消费）；某源目录缺失/不可读时该源降级为空，绝不阻断（fail-open）。

注：v0.1 中 custom/petdex 皮肤的选中与优先级判定已生效；v0.2 悬浮窗艺术层统一渲染内联鲸鱼 SVG，外部源与内置皮肤的 spritesheet 像素图待 Host 静态服务与渲染切换点接入（Roadmap）。spritesheet 契约仍由 src/pet-pool.js 的 BUNDLED_ARTWORK 登记表锁定（测试强制登记与实际文件一致，杜绝破图）。

配置（宠物切换 / 随机）

方式一（当前可用）：编辑用户设置文档。插件已把 pet 注册为 dsh 用户设置（命名空间 deepseek-harness-pets，Host 侧 schema 校验生效）：直接编辑
~/.dsh/settings.yaml，重启 DSH Web 生效（设置面板选择行开发中，见 Roadmap）：

deepseek-harness-pets:
pet: deepseek-octo   # 缺省不写 = 默认大鲸鱼；random = 按 turn id 确定性随机

方式二：profile patch 行 config（composition base 层）：在
~/.dsh/profiles/web/cordis.patch.yml 里按 id 覆盖：

- id: deepseek-harness-pets
config:
pet: random            # deepseek-whale（默认·大鲸鱼） | deepseek-octo | random
pets:                # 可选：覆盖皮肤池扫描结果
- deepseek-whale
- deepseek-octo

- 优先级：用户设置文档 > 行 config（base） > schema 默认 deepseek-whale（大鲸鱼）；
删掉用户层字段即回继承 base 层；
- pet: random 时每个 turn 按其 id 种子确定性选皮，同一会话重放结果一致；
- 池外皮肤名会被 Host 侧 schema 校验拒绝（注册时 fail loud，命名空间不装）；
- 配置/文档层之外，浏览器侧对池漂移降级回默认并 console.error（fail-open，不阻断会话渲染）。

宠物资产与 Petdex 互通

每只宠物就是一个标准 Petdex 宠物包：

assets/pets/deepseek-whale/
├── pet.json            # Petdex 元数据（slug/帧规格/9 状态行/调色板）
└── spritesheet.webp    # 8 列 × 9 行、每帧 192×208、背景纯品红 #FF00FF（占位待补）

想把这只会动的鲸鱼浮在桌面上？把 assets/pets/deepseek-whale/ 复制到 ~/.petdex/pets/（或 ~/.codex/pets/），装 Petdex 桌面端即可——同一套资产，两种形态。也欢迎 npx petdex submit ./assets/pets/deepseek-whale/ 上架社区画廊（审核约 24 小时）。

皮肤创作指南

放哪里？ 三选一（见上文源优先级）：
- 想让皮肤只在自己机器生效且优先级最高 → 放 ~/.dsh/pets//；
- 想用社区现成皮肤 → npx petdex install （落在 ~/.petdex/pets/）；
- 想给本仓库贡献内置皮肤 → 提 PR 到 assets/pets/。

内置皮肤贡献流程：

1. Fork 本仓库，在 assets/pets/ 下新建 / 目录；
2. 用 Codex 的 hatch-pet skill 生成或手绘 spritesheet，严格遵守 帧规范：8×9 网格、每帧 192×208、背景纯品红 #FF00FF、行序 idle→review；
3. 复制一份 pet.json 改成你的宠物元数据；
4. 提 PR。想让宠物进随机池？在 src/index.js 的 DEFAULT_PET_POOL 中同步登记（或用 cordis.yml 的 pets 覆盖）。

创意方向欢迎：不同参数量大小的鲸鱼宝宝、穿格子衬衫的 AI 鲸鱼、更多机械海洋生物……

Roadmap

- [x] 真实 dsh 环境全链路验收（安装→组合→boot graph→client bundle→设置注册→三层解析，2026-08-15 实测）
- [ ] 设置面板宠物选择行：浏览器半边注册 settings.general.item 偏好行（defineStore + locale + scope.set，参照 @dshthemes/ui 的 ThemePickerRow 形态）
- [x] 悬浮窗实机目验（2026-08-15 完成：常驻右下角/悬停/点击瞬态/拖拽持久化刷新恢复/turn 状态流转/loading→动画/console 零报错/聊天流零卡片，Chrome DevTools 实测）
- [ ] 像素图就绪（spritesheet.webp × 2，社区认领）
- [ ] Host 静态服务：向 Web UI 提供 custom/petdex 源的 spritesheet（消除占位块）
- [ ] Host 侧专用事件族：精确判定评测阶段与 SOTA（需 TS declaration merging，迁移到 TS 包）
- [x] 常驻浮层形态（shell.overlay root 域插槽注入，v0.2 已实施——见 evidence.md #29）
- [x] 发布到 npm 并登记 dsh-plugin topic（v0.2.0 起在 npm；发布经 GitHub Actions trusted publishing 自动完成——推 v* tag 即验证+发布，零 token，见 CONTRIBUTING 发布流程）
- [ ] 机械章鱼 octo 上色稿
- [ ] npx petdex submit 上架画廊

贡献与许可

- 贡献指南：CONTRIBUTING.md
- 架构与证据：docs/architecture/（三视图 + 证据置信度）
- 代码 MIT（见 LICENSE）；像素资产版权归各自贡献者，按其 pet.json 声明的许可使用。

故障排查

- 设置面板没有宠物项：属预期——面板偏好行（settings.general.item 插槽）开发中（见 Roadmap）；当前用 ~/.dsh/settings.yaml 或 profile patch 配置。
- 悬浮窗不出现：先确认 dsh ≥ 0.1.0-rc.5（更早版本无 shell.overlay 插槽）；bundle 不热加载，重启 DSH Web；仍无则 dsh --profile web --dump-config 确认 deepseek-harness-pets 行存在，浏览器控制台查 window.__DSH_BOOT__ 是否含该条目、Network 看 /plugins/deepseek-harness-pets/client.js 是否 200（404 多半是没跑 npm run build 或 exports["./client"] 指错），console 无 [deepseek-harness-pets] 报错即说明插槽声明被宿主静默忽略（fail-open 设计，宠物安静不出现）。
- 悬浮窗位置丢失（回到右下角）：属预期——拖拽位置存于浏览器 localStorage（key dsh-pets-overlay-pos），清缓存/换浏览器/隐私模式后回落默认右下角。
- 设置面板缺项但能启动：~/.dsh/settings.yaml 里该命名空间的值不合法时注册被拒、命名空间不装但启动不会报错（实测容纳性，见 evidence.md #25）；改正为池内值或删掉该 section 重启。
- 换了皮肤但悬浮窗视觉没变：v0.2 艺术层统一渲染内联鲸鱼 SVG，皮肤选中与优先级已生效（slug 见悬浮窗 data-dsh-pet-overlay 属性），专属像素视觉待 spritesheet 切换点接入（见 Roadmap 的像素图与 Host 静态服务）。
- random 每次不一样：random 按 turn id 种子选择，同一 turn 重放一致；跨 turn 允许换皮（这是特性）。
- dsh 升级后异常：dsh 处于 developer preview，不排除 breaking changes；本插件验证于 dsh 0.1.0-rc.5（2026-08 本机实测：安装→组合→boot graph→设置注册→三层解析全链路），出新问题时请附 --dump-config 输出提 issue。