前言¶
在 DSH 的“一切皆插件”场景里，Web GUI 可以通过客户端插件扩展界面。对使用 DSH 观察 agent 会话的开发者来说，常见需求是把当前会话状态从文字提示中抽出来，快速看到它是在运行、等待输入、报错、完成还是待机。
@minybear/dsh-pet 是 minybear 维护的 DSH 客户端插件，许可证为 MIT。它在 DSH Web GUI 中漂浮一只动画小宠物，由当前会话的 agent 运行状态实时驱动，并提供喂食、玩耍、设置等轻量交互。
插件定位¶
一句话定位：Codex 风格的“桌面宠物”DSH 客户端插件，在 DSH Web GUI 里漂浮一只动画小宠物，由当前会话的 agent 运行状态实时驱动。
它解决的问题：把当前会话状态映射为宠物动画，并加入位置、外观、数值和自定义宠物包导入等设置，方便在不频繁查看状态栏或日志的情况下感知 agent 当前状态。
核心功能¶
漂浮宠物¶
宠物注册进 DSH 的 shell.overlay 槽，属于帧级浮动层，可点透，默认右下角常驻，可拖拽换位。
状态驱动¶
插件读取当前会话状态，并映射到 Codex 的 9 状态动画行。
会话信号按存活期衰减：
Running：3minFailed：1hWaiting：24hReview：7d
超时后回退到 idle。
减少动态¶
插件跟随系统 prefers-reduced-motion，也可以在设置里手动锁定“完整 / 减少动态”。
进入减少动态后，按 Codex 行为固定显示 idle 第一帧。
点击菜单¶
点击宠物会弹出菜单，可用操作包括：
1、喂食（eat）
2、玩耍（play）
3、设置
拖拽移动¶
拖拽可以移动宠物位置。
拖动时按方向播放 running-left/right 行走动画，静止时进入 drag 姿态，位置会持久化到 localStorage。
养成数值¶
插件内置饱食 / 心情数值，范围均为 0–100，并随墙钟时间衰减；关掉浏览器也会继续计时，约 8h / 6h 见底。
数值变化规则：
- 喂食：饱食 +30
- 玩耍：心情 +25
菜单里有两条数值条。当宠物待机且某项低于 20 时，会提示“饿了 / 想玩”。
内置宠物¶
内置五只宠物：
- Dee（青绿）
- Amber（琥珀）
- Berry（莓紫）
- 灰鲸（DeepSeek Harness logo 造型）
- 蓝鲸（DeepSeek 官方 logo 造型）
可以在设置面板一键切换。
外观设置¶
外观设置包括：
- 尺寸：0.5–1.5
- 透明度：0.2–1
- 动画模式
- 宠物选择
这些设置全部持久化到 localStorage。
自定义宠物包¶
设置面板支持导入标准 Codex 宠物包，包括：
pet.json- 图集图片
导入后会先校验，再存入 localStorage，并立即可选；也可以删除。
兼容包格式由 pet.json 和一张行优先图集描述。pet.json 字段包括：
{
"id": "",
"displayName": "",
"description": "",
"spritesheetPath": "",
"frame": null,
"animations": null
}
图集前 9 行为 Codex V1 官方 9 状态，第 9–11 行为交互状态（eat / play / drag）。
如果自定义宠物包没有额外交互行的官方 9 行图集，会自动回退：交互态播放 idle 行。
安装与启用¶
客户端插件需要宿主端打包（dsh.client.inject），安装后需要重启 DSH 并刷新页面才生效。
已给出的安装命令为：
dsh plugin --profile web add github:minybear/DeepSeek-Harness-Pet
安装后重启：
dsh web
然后刷新页面，宠物应出现在右下角。
离线环境或无需 pnpm 时，可使用手动安装脚本：
deploy\install.ps1
典型用法¶
1、安装并重启 DSH 后，打开 Web GUI，确认右下角出现宠物。
2、点击宠物，弹出菜单后执行喂食、玩耍或进入设置。
3、拖拽宠物到合适位置，位置会持久化到 localStorage。
4、在设置面板中切换内置宠物，调整尺寸、透明度和动画模式。
5、导入自定义 Codex 宠物包：上传 pet.json 与图集图片，校验通过后立即可选。
6、如果需要运行测试或图集自检，可以执行：
npm test
node scripts/render-atlas.mjs --all
其中 npm test 依次跑 pet-core / client-contract / parity；node scripts/render-atlas.mjs --all 软渲染三只内置宠物图集并自检网格不变量。
实现与测试注意¶
client.js 内联了一份 pet-core，test/parity.test.mjs 会对两份副本做全量行为一致性校验，防止行为分叉。
适用场景与注意¶
适合：
- 使用 DSH Web GUI，希望把 agent 状态可视化成宠物动画的开发者。
- 想按 Codex 宠物包格式导入或制作自定义宠物动画的开发者。
- 需要低打扰状态提示，并且重视系统减少动态设置的开发者。
注意：
- 插件以当前 dsh 进程权限运行；安装前应检查源码和 MIT 许可证。
- 养成数值按墙钟时间衰减，不依赖浏览器是否打开。
- 自定义宠物包如果没有交互行，交互态会回退到
idle行。 - 本文只使用资料中明确给出的安装命令，不把它表述为唯一官方安装入口。
结尾¶
@minybear/dsh-pet 的价值在于把 DSH 当前会话状态映射为 Codex 风格宠物动画，并提供喂食、玩耍、拖拽、外观、自定义宠物包导入等轻量设置。
社区目录是独立站点，与 DeepSeek / 幻方无官方从属关系。本文资料未提供目录页 URL，源码地址为：
https://github.com/minybear/DeepSeek-Harness-Pet
