raydez/dsh-pet-plugin

🐾 deepseek-harness-pet-plugin（桌面宠物插件）

English · 中文

为 deepseek-harness Web 对话界面
（pnpm dsh web → http://127.0.0.1:3080）开发的桌面宠物风格交互插件：一只用内联 SVG +
CSS 绘制的圆滚滚小猫（尾巴、耳朵、眼睛、胡须、表情齐全），常驻页面右下角，随对话状态做出
反应，支持拖拽、双击彩蛋、右键菜单与开关控制。

- 不改动 deepseek-harness 的任何核心源码，全部代码独立放在本文件夹。
- 不引入任何第三方库与外部图片资源（视觉全部由内联 SVG + CSS 绘制）。
- UI 元素（菜单/气泡/开关/恢复按钮）优先复用宿主页面的 --dsw-alias- 主题令牌，
取不到时回退到内置配色，保证与深色/浅色界面都协调。

文件结构

deepseek-harness-pet-plugin/
├── README.md                     # English readme
├── README.zh.md                  # 本说明
├── pet_cordis.yml                # Cordis overlay patch（供 pnpm dsh web --patch 使用）
├── scripts/
│   ├── pet_install.sh            # 安装：把插件插入 dsh profile 用户层（幂等）
│   └── pet_uninstall.sh          # 卸载：从 profile 用户层移除插件
├── src/
│   └── pet_server.ts             # 服务端 Cordis 插件：挂载 /pet/ 静态路由 +
│                                 #   向 index.html 注入 /（HMR 可热加载）
└── public/
├── pet_main.js               # 客户端主逻辑：状态机、拖拽、彩蛋、菜单、开关
└── pet_style.css             # 宠物视觉：内联 SVG + CSS 变量 + 全部状态动画

前置条件

- 本机已 clone deepseek-harness
并完成 pnpm install，pnpm dsh web 能正常启动。
- 本插件是 Cordis overlay 插件：不改动 deepseek-harness 任何核心源码，
零运行时依赖，不需要 npm install / 构建步骤。

如何让插件生效

启动命令依然是 pnpm dsh web（在 deepseek-harness 仓库目录下执行），无需任何额外参数。

方式一（推荐）：运行安装脚本，把插件写入 dsh 的 profile 用户层
（~/.dsh/profiles/web/cordis.patch.yml，即插件自动加载层）：

cd /path/to/deepseek-harness-pet-plugin
./scripts/pet_install.sh
cd /path/to/deepseek-harness
pnpm dsh web

- 如果服务已经在运行，保存补丁文件后 HMR 会自动热加载，刷新浏览器页面即可看到宠物。
- 脚本幂等：重复执行只会刷新插件源码路径，不会重复插入。
- 可选：--home 安装到 $DSH_HOME/cordis.patch.yml（作用于所有 profile）。

方式二（临时试用）：启动时显式挂载 overlay：

pnpm dsh web --patch /path/to/deepseek-harness-pet-plugin/pet_cordis.yml

pet_cordis.yml 内是插件服务端的绝对路径；本机 clone 位置与示例不符时请同步修改，
或直接用安装脚本（它会自动计算正确路径）。

功能清单

基本存在与操作
- 默认出现在页面右下角，约 100×100 px。
- 浮动在页面最上层（z-index 极高），默认位置会避开对话输入框与发送按钮
（自动停靠在输入条上方）；透明区域不拦截点击，不遮挡页面操作。
- 按住拖拽可移动到任意位置，位置保存在 localStorage（键 pet_pos），下次打开自动恢复。

状态联动
| 状态 | 触发条件 | 表现 |
|---|---|---|
| 待机 | 默认 | 呼吸浮动 + 眨眼 + 耳朵轻抖 + 尾巴慢摇 |
| 倾听 | 输入框获得焦点或正在打字 | 头部微微侧倾、右耳竖起、眼睛放大 |
| 思考 | AI 回复生成中（检测到输入条按钮变为“停止生成”） | 快速抖动 + 尾巴快摇 + 虚线加载环 + “思考中…”气泡 |
| 开心 | AI 回复完成 | 跳跃两次 + ❤️/⭐/✨ 粒子迸发，持续 3 秒后回到待机 |
| 打盹 | 页面空闲超过 30 秒无操作 | 闭眼、头下垂、缓慢摇摆、飘出“Zzz”；任意点击/按键立即唤醒 |

说明：思考/倾听/开心状态期间不会进入打盹；测试时可用
http://127.0.0.1:3080/?pet_idleMs=5000 把空闲阈值临时缩短到 5 秒。

交互彩蛋
- 双击宠物：随机触发一个趣味动画（翻滚 / 弹跳 / 摇摆 / 翻转 / 脉冲 / 压扁 / 跳跃 / 彩虹变色），
随机切换一个表情（星星眼 / 爱心眼 / 哇嘴 / 开心吐舌），并弹出随机俏皮话气泡（内置 14 条）。
- 右键宠物：极简菜单
- 「换个形象」：循环切换宠物角色（小猫 🐱 → DeepSeek 小鲸鱼 🐳 → 熊猫 🐼 → 小狗 🐶 → 兔子 🐰 → 牛来 🐂 → …），
选择会记忆（localStorage 键 pet_char）；角色由角色注册表驱动，新增形象只需在
pet_main.js 的 CHARACTERS 里加一个 SVG 模板 + 在 CSS 里加一套配色。
- 「切换日夜模式」：更换宠物颜色主题（日：角色本色 / 夜：深色变体），选择会记忆；
未手动选择时自动跟随页面明暗主题。
- 「重置位置」：回到右下角默认位置。
- 「隐藏宠物」：与右上角开关等价（同一个开关状态），隐藏后 🐾 恢复按钮出现在
宠物默认所在的位置（右下角、避开输入区），点击即可唤回；右上角开关同样可以恢复。

开关控制
- 页面右上角提供 🐾 启用/禁用开关（默认开启），状态记忆在 localStorage（键 pet_enabled）。
- 开关与右键菜单「隐藏宠物」是同一个开关状态：无论从哪个入口关闭，
恢复路径统一为右下角 🐾 恢复按钮或右上角开关，不会出现「禁用」与「隐藏」两种状态。

视觉
- 内置 6 个可切换的宠物形象（内联 SVG，无外部图片）：
- 🐱 小猫（默认）：橙猫，尾巴 / 耳朵 / 胡须 / 头顶花纹
- 🐳 DeepSeek 小鲸鱼：DeepSeek 蓝，尾鳍 / 胸鳍 / 头顶喷水孔
- 🐼 熊猫：黑白配，黑眼圈 / 黑圆耳 / 头顶竹叶
- 🐶 小狗：金棕色，下垂长耳 / 头顶小圆斑
- 🐰 兔子：奶白色，粉色长耳 / 头顶小花
- 🐂 牛来（电影《牛来》主角）：橙黄色小牛犊，小弯角 / 头顶一撮毛 / 四条短腿
- 每个角色共用同一套「动画契约」类名（.pet-tail / .pet-ear / .pet-eye /
.pet-mouth- 等），状态动画（眨眼、耳/鳍/尾摆动、呼吸、抖动、跳跃、闭眼 Zzz）自动生效；
局部动画通过 transform-box: fill-box 实现，动画全部为 transform/opacity，低开销可合成。
- 日夜主题通过 CSS 变量整体换色（每个角色有日/夜两套配色），UI 元素颜色优先取宿主
--dsw-alias- 令牌。

如何禁用 / 卸载

- 临时禁用：点右上角 🐾 开关，或右键菜单「隐藏宠物」，即可隐藏宠物（不卸载代码）；
关闭后右下角会出现 🐾 恢复按钮，点击或再点开关即可唤回。
- 卸载插件：

cd /path/to/deepseek-harness-pet-plugin
./scripts/pet_uninstall.sh

脚本从 profile 用户层删除插件插入块；运行中的实例会通过 HMR 自动卸载，
刷新页面后宠物与开关消失。若此前用的是 --patch 方式，去掉该参数即可。

实现要点与边界处理

- 服务端（pet_server.ts）：零运行时依赖，仅使用 Node 内置模块与 webServer
服务；/pet/ 前缀路由只允许 pet_main.js / pet_style.css 两个文件名，
其余一律 404；index 注入带幂等标记，HMR 重载不会重复注入。
- 客户端（pet_main.js）：宠物整体放在 Shadow DOM 中，样式与 DOM 与宿主应用
完全隔离；状态检测只依赖稳定的 DOM 信号（[data-composer-card]、发送/停止按钮
的 aria-label），不触碰前端内部实现；所有定时器与事件都有边界保护，控制台无报错。
- 视觉（pet_style.css）：宠物为内联 SVG，全部部件用 CSS 变量着色、用
transform/opacity 动画（尊重 prefers-reduced-motion）；日夜主题通过
:host(.pet-night) 变量切换，UI 元素颜色优先取宿主 --dsw-alias- 令牌。
- 安装/卸载脚本：幂等；处理了「空 patch」边界——卸载后若补丁文件只剩空白，
会写入合法的空列表 []（否则 dsh 启动会因 patch 文件不是 top-level YAML 数组
而失败），安装时遇到 [] 或空白文件则直接覆盖而非追加。
- 持久化键：pet_pos / pet_enabled / pet_theme / pet_char（localStorage）。

常见问题（FAQ）

- 启动报错 / 宠物不出现：确认 public/pet_main.js、public/pet_style.css 存在；
服务端插件只读文件失败时只回 404，不影响 dsh 本体。安装后若服务已在运行，等待 HMR
热加载（几秒）再刷新浏览器页面；若仍不出现，检查 ~/.dsh/profiles/web/cordis.patch.yml
里 # >>> deepseek-harness-pet-plugin 标记块是否完整。
- 换机器 / 换目录后失效：pet_cordis.yml 与补丁里的 name 是绝对路径；重新运行
scripts/pet_install.sh 会自动更新为当前仓库的实际路径。
- 重复安装会不会插两次：不会。安装脚本幂等，检测到标记块已存在时只刷新路径。
- 卸载后 dsh 启动报 patch 解析错误：不应发生——卸载脚本会把残留的空 patch 文件写成
合法的 []。若之前手删过补丁内容导致空文件，把该文件内容改为 [] 即可。
- 与其他插件的兼容性：本插件不注册工具、不订阅模型事件、不写会话日志，不参与
agent 循环，与任何工具类插件（如 scratch-plugin）无冲突；/pet/ 路由只挂自己的
两个文件名，不会抢占其他插件路径。
- 页面深色/浅色主题切换后宠物 UI 不协调：不会——UI 元素复用宿主 --dsw-alias-
令牌会自动跟随；宠物身体颜色由「切换日夜模式」控制，未手动选择时也会自动跟随页面主题。

许可证

MIT © 2026 raydez

English ·