DeepSeek-Harness-Pet

一句话定位

在 DeepSeek Harness (DSH) Web 客户端右下角养一只漂浮的小宠物，宠物的动画、状态气泡和养成数值由当前会话的 agent 运行状态实时联动——agent 工作时它踩齿轮奔跑，等待你输入时它举手要操作，运行时崩溃它翻白眼躺平。

核心能力

• 实时把 agent 状态映射成 9 段官方动画：工作中奔跑、等待输入时举手、报错时躺平、刚完成时庆祝跳跃、会话切换时挥手打招呼
• 内置 5 只宠物可选：Dee（青绿）、Amber（琥珀）、Berry（莓紫）、灰鲸（DeepSeek Harness logo 造型）、蓝鲸（DeepSeek 官方品牌蓝造型）
• 养成数值系统：🍖 饱食 / 😊 心情 0–100，按真实时间衰减（关浏览器也计时），喂食 +30、玩耍 +25；某项低于 20 时待机状态自动提示
• 点击弹出 🍗 喂食 / 🎾 玩耍 / ⚙ 设置菜单；拖拽移动位置（位置持久化到 localStorage）；尺寸 0.5–1.5、透明度 0.2–1 全可调
• 支持导入官方 Codex 宠物包（pet.json + 图集），校验后存 localStorage，可随时切换或删除
• 跟随系统「减少动态」偏好或手动锁定，启用时固定显示 idle 第一帧
• 自带桥接模式：把会话状态 POST 到 http://127.0.0.1:8765/pet-state，供桌面端 dsh-pet-desktop 浮窗消费

技术实现

• 语言: JavaScript (ESM)
• 关键依赖: @deepseek-ai/dsh-client-runtime ^0.1.0-rc.6、@deepseek-ai/dsh-client-ui-slots ^0.1.0-rc.6、@deepseek-ai/cordis ^4.0.1、react ^18.2.0
• 架构模式: 双端注入——宿主端 lib/index.js 是空 apply（占位注册），浏览器端通过 package.json#dsh.client.inject 加载 exports["./client"]，由 window.__ModuleLoader__ 装载；通过 cordis.patch.yml 把 ui-pet 写入浏览器花名册；运行时向 shell.overlay 槽注入两个组件：PetOverlay（可视宠物）和 BridgeOverlay（无 UI 状态桥接）
• 入口文件: lib/client.js（浏览器主体）、lib/index.js（宿主侧空占位）、lib/pet-core.js（无 DOM 纯逻辑层，状态机 + pet.json 解析 + 帧索引 + 衰减）

适用场景

长时间盯 DSH Web 端等 agent 跑活、想给工作界面添点陪伴感的用户。适合那些盯着日志觉得枯燥、希望用一只宠物的动作一眼判断 agent 当前状态的场景；不适合需要严肃后台监控或希望最大化屏幕空间的场景（宠物默认占右下角浮动层，可拖走但不可彻底关闭）。

前置依赖与兼容性

安装方式

dsh plugin --profile web add github:minybear/DeepSeek-Harness-Pet

配置项

常见问题

Q: 安装后没看到宠物怎么办？

A: 客户端插件需要宿主端打包并在重启 dsh web 后生效。安装完成后必须重启 dsh web 进程并刷新页面（默认 http://127.0.0.1:3080），右下角才会出现宠物。

Q: 需要单独写代码或配置吗？

A: 不需要。插件默认使用内置青绿色宠物 Dee，安装即用；尺寸、透明度、动画模式、宠物选择都通过设置面板交互，无需编辑配置文件。

Q: 我能换一只自己的宠物吗？

A: 可以。设置面板提供「导入 Codex 宠物包」，按官方 pet.json 格式提供清单文件和图集图片（PNG/WebP/GIF，<2MB）即可导入，校验通过后存到 localStorage，可随时切换或删除。

Q: 关闭浏览器宠物会饿死吗？

A: 会。饱食和心情数值按墙钟时间衰减（约 8 小时 / 6 小时见底），关闭浏览器期间也持续计时，重新打开后数值按上次更新时刻折算。

Q: 数据存哪里？会同步到云端吗？

A: 全部存在浏览器 localStorage（dsh-pet:* 命名空间），包括宠物选择、位置、尺寸、养成数值、导入的自定义宠物。本插件不发送任何网络请求（除非同时安装了 dsh-pet-desktop 桌面浮窗，则会向本地 127.0.0.1:8765 推送状态）。

Q: 「减少动态」是什么意思？启用后宠物会怎样？

A: 减少动态模式（系统设置或本插件设置面板）下，宠物固定显示 idle 动画的第一帧，不会播放动作。这是对系统 prefers-reduced-motion 的标准响应，帮助晕动症用户使用 DSH。

Q: 能关闭宠物但保留安装吗？

A: 不能直接「隐藏」，但可以把透明度调到 0.2 或拖到屏幕角落；想彻底移除请用 dsh plugin --profile web remove @minybear/dsh-pet 卸载。

Q: 五只宠物之间有什么区别？

A: 三只 blob 造型（Dee/Amber/Berry）共享同一套 12 行走走/挥手/跳跃/躺平等动作，只是配色不同；两只鲸鱼（灰鲸/蓝鲸）是侧视侧视图，工作中会冒气泡、idle 时喷水柱、waving 时举胸鳍，整体镜像处理方向。

上手难度

入门 — 装完即用，无需写代码或编辑配置；进阶玩家可以导入自定义 Codex 宠物包或调整透明度/尺寸/动画策略。

已知问题与限制

• 当前版本无活跃 TODO/FIXME；历史问题（如 React hooks 顺序违规、pet-core 与 client 内联副本状态机分叉、install 脚本硬编码路径）均已在 0.2.0/0.4.0 版本修复
• 自定义宠物图集大小上限约 3MB（含 base64 编码），超出时导入会被拒绝并提示「请用 <2MB 的 WebP/PNG」，导入前请先用 ImageOptim 等工具压缩
• 仅 9 行 Codex V1 官方图集可享受完整状态机动画；自定义宠物如果缺少交互行（eat/play/drag），交互时回退到 idle 行
• BridgeOverlay 桥接模式默认开启，会向 http://127.0.0.1:8765/pet-state 发请求；如果没有运行配套的桌面浮窗，请求会被静默丢弃，但可在 DevTools Network 面板看到

Codex 风格的「桌面宠物」DSH 客户端插件：在 DeepSeek Harness（DSH）Web GUI 里漂浮一只动画小宠物，由当前会话的 agent 运行状态实时驱动（工作 / 等待输入 / 报错 / 刚完成 / 待机）。

复刻对象：OpenAI Codex 桌面版的 Pets 功能。调研结论见 docs/Codex-Pet-能力分析.md 与 docs/复刻方案.md；与 Codex 官方能力的逐项对照见 docs/差距分析.md；版本变更记录见 CHANGELOG.md。

能力

• 漂浮宠物：注册进 DSH 的 shell.overlay 槽（帧级浮动层，可点透，右下角常驻，可拖拽换位）。

• 状态驱动：读当前会话状态并映射到 Codex 的 9 状态动画行；会话信号按 Codex ambient.rs 的存活期衰减（Running 3min / Failed 1h / Waiting 24h / Review 7d，超时回退 idle）：

  DSH 信号	宠物状态（行）	状态标签
  running === true	running（7）	Running
  pendingInteraction	waiting（6）	Needs input
  lastAgentError	failed（5）	Blocked
  running true→false 边沿	jumping（4）	Done!（约 2.6s）
  completed	review（8）	Ready
  切换/打开会话	waving（3）	Hi!（约 1.7s）
  拖拽移动中	running-left/right（1/2，按方向）	（无）
  无活动	idle（0）	（无）

• 减少动态：跟随系统 prefers-reduced-motion，或在设置里手动锁定「完整 / 减少动态」；减少动态时按 Codex 行为固定显示 idle 第一帧。

• 交互：

  • 点击 → 弹出菜单：🍗 喂食（eat）、🎾 玩耍（play）、⚙ 设置。
  • 拖拽 → 移动宠物位置（按拖动方向播放官方 running-left/right 行走动画，静止时为 drag 姿态，位置持久化到 localStorage）。

• 养成数值：🍖 饱食 / 😊 心情 0–100，随墙钟时间衰减（关掉浏览器也计时，约 8h / 6h 见底）；喂食 +30 饱食、玩耍 +25 心情；菜单里有两条数值条，待机且某项 <20 时宠物会冒「🍖 饿了 / 🎾 想玩」提示。

• 多宠物：内置五只宠物——Dee（青绿）/ Amber（琥珀）/ Berry（莓紫）同模配色，以及灰鲸（DeepSeek Harness logo 造型）/ 蓝鲸（DeepSeek 官方 logo 造型，品牌蓝）两只侧视鲸鱼，设置面板一键切换。

• 自定义宠物导入：设置面板可导入标准 Codex 宠物包（pet.json + 图集图片，如 ~/.codex/pets/ 下 hatch-pet 生成的宠物），校验后存入 localStorage 并立即可选；可删除。无额外交互行的官方 9 行图集会自动回退（交互态播放 idle 行）。

• 外观设置：尺寸（0.5–1.5）、透明度（0.2–1）、动画模式、宠物选择，全部持久化到 localStorage。

• Codex 兼容包格式：宠物由 pet.json（id/displayName/description/spritesheetPath/frame/animations）+ 一张行优先图集（无独立 atlas 文件，帧索引 index = row×columns + col）描述；内置默认宠物在运行时用 canvas 生成。前 9 行为 Codex V1 官方 9 状态，第 9–11 行为交互状态（eat/play/drag），经官方 frame 覆写（96×104×8×12）与 animations 字段声明。

结构

lib/pet-core.js    纯逻辑（Node 可测）：pet.json 解析 + 帧切片 + 状态机 + 状态存活期
lib/index.js       host 侧 apply（空，纯 UI 插件）
lib/client.js      浏览器侧：window.__ModuleLoader__.load + apply/inject + PetOverlay + 精灵生成
test/*.test.mjs    Node 单测（pet-core + client 契约 + 双副本一致性）
docs/              调研、方案与差距分析

注：client.js 内联了一份 pet-core（DSH 模块加载器无法解析包内文件），test/parity.test.mjs 会对两份副本做全量行为一致性校验，防止分叉。

测试

npm test            # 依次跑 pet-core / client-contract / parity
node scripts/render-atlas.mjs --all   # 软渲染三只内置宠物图集并自检网格不变量

安装到 DSH

# 从 npm（发布后）
dsh plugin --profile web add @minybear/dsh-pet

# 或一条命令装本地 checkout（包自带 dsh.bundle.patch 自注册）
dsh plugin --profile web add .

# 或从 GitHub
dsh plugin --profile web add github:minybear/DeepSeek-Harness-Pet

然后重启 dsh web 并刷新页面，宠物应出现在右下角。离线环境或无需 pnpm 时，用 deploy\install.ps1 手动装；完整步骤见 INSTALL.md。

注：客户端插件需宿主端打包（dsh.client.inject）与重启后生效。