前言¶

用 DeepSeek Harness（dsh）跑 Agent 时，想确认它此刻在思考、在调工具，还是已经完成或出了错，通常得盯着 Web 页面里的会话流。dsh-pet 换了一种呈现方式：把 Agent 的实时事件映射成一只桌面宠物的动画，事件来了切状态，扫一眼页面角落就知道当前进展。

下面介绍这个插件的功能、安装方式与典型用法。

这是什么¶

dsh-pet 是 levi52 维护的 DSH 插件，一句话定位：Codex 风格的 DeepSeek Harness 桌面宠物——内嵌 DSH Web 界面，跟着 Agent 实时状态播放动画，精灵图与动画节奏都可以在设置页里可视化配置。项目采用 MIT 许可证。

实现上它不改动 dsh 本体：通过官方 webServer.tapIndex 把桌宠浮层注入 dsh 的 3080 Web 页面，与 dsh 同源同页、一起出现一起消失。

核心功能¶

• 事件驱动动画：订阅根 context 的 session/event，按 turn/start、tool/call、turn/end 等事件，在待机、思考、执行、等待、完成、失败六种动画之间切换。
• 精灵图即配置：精灵图的网格布局与「状态 → 行」映射由配置声明（config.sprite 或同名 .json 侧车文件），换图不需要改源码。
• 设置页管理：dsh 设置页有「桌宠」分区，可视化配置上传/选择精灵图（webp/png/gif/jpg/svg）、网格、状态映射、缩放、动画速度、待机延迟、显隐。
• 配置热推送：改动经 SSE config 事件热推给渲染器，缩放、动画速度、待机延迟调整即时生效，不需要刷新或重启。
• 自动持久化：设置保存到 pet/user-config.json，刷新后自动恢复，优先级高于 cordis.patch.yml。
• 多形态呈现：除内嵌浮层外，还提供独立弹窗页、Chrome app 无边框窗、pywebview 透明窗（可打包 .exe）、Electron。

安装与启用¶

环境要求两条：

• DeepSeek Harness（dsh CLI）已安装并运行过 Web profile
• Node.js ≥ 18

安装分两步。第一步，把本地插件目录注册到 web profile：

dsh plugin --profile web add <本目录路径>

第二步，启动 dsh，会一并启动 Web GUI：

dsh --profile web

经过上面的步骤，打开终端打印的 Web 地址（通常是 http://127.0.0.1:3080/），页面右下角会出现桌宠；管理入口在 设置 → 桌宠。

卸载执行：

dsh plugin --profile web remove dsh-pet

注意：卸载后用户数据（pet/user-config.json 与 pet/uploads/）会保留，如需彻底清除要手动删除。

配置¶

默认配置开箱即用。需要覆盖默认值时，在 profile 的 cordis.patch.yml（顶层 YAML 数组）中加入：

- insert:
  - id: dsh-pet
    name: dsh-pet
    config:
      idleMs: 3000
      scale: 1
      fpsScale: 1
      injectOverlay: true
      overlayRoute: /dsh-pet

支持的配置项：

• idleMs（默认 3000）
• scale（默认 1）
• fpsScale（默认 1）
• injectOverlay（默认 true）
• overlayRoute（默认 /dsh-pet）
• enabled（默认 true）
• spriteFile（默认 doraemonsprite.webp）
• sprite（网格与状态映射）

其中 sprite 声明精灵图的网格布局与状态到行的映射，spriteFile 指定精灵图文件。设置页保存的配置会写入 pet/user-config.json，优先级高于 cordis.patch.yml。

独立窗口模式¶

除了内嵌浮层，桌宠渲染器也提供独立页面，地址：

http://127.0.0.1:3080/dsh-pet/

想做成无边框的桌面窗口，可以用 Chrome 应用模式：

chrome --app="http://127.0.0.1:3080/dsh-pet/" --window-size=256x320

也可以用 pywebview 起一个透明窗体：

cd dsh-pet/pet
pip install pywebview
python launch.py

需要分发时，用 pyinstaller 打包成单文件 .exe：

pyinstaller --onefile --windowed --add-data "doraemonsprite.webp;." --add-data "pet.html;." launch.py

特性列表中还列出了 Electron 形态，但 README 正文没有给出具体操作步骤。另外，未连接 dsh 时，独立页会自动循环播放各状态动画（演示模式），按 D 键可手动切换，适合单独预览动画效果。

适用场景与注意事项¶

适合的人群：

• 日常通过 dsh Web 页面操作 Agent，希望状态一眼可见的人
• 想给工作区加状态可视化、又不想改动 dsh 本体的人

使用前与使用中需要注意：

1. 插件以当前 dsh 进程的权限运行，安装前请自行检查插件源码与许可证（本项目为 MIT）。
2. 所有数据仅存储在本机（pet/ 目录与 dsh profile），不上传任何内容，也不采集密钥或凭据，资源仅本地可访问；精灵图上传接口只接受图片格式，文件名做了白名单校验防路径穿越。
3. waiting 状态目前仅由演示模式手动触发。
4. 改动生效方式：纯客户端改动（精灵图、缩放、动画速度等）只需强制刷新浏览器；宿主侧改动（index.js）需要重启 dsh。
5. 如果要基于此插件做二次开发，注意设置页的 client 条目依赖 package.json 的 dsh.client.inject 与 exports["./package.json"]，缺少任一项，设置页就不会出现「桌宠」区块。

小结¶

dsh-pet 解决的问题很具体：让 Agent 的运行状态从日志变成一眼可见的动画，同时把换图、调节奏做成纯配置操作。DSH 的理念是「一切皆插件」，这种不侵入宿主的扩展正是这套机制适合做的事。

• 插件目录页（社区站点，与 DeepSeek 无官方从属关系）：https://www.skillhub.cn/plugins/levi52/dsh-pet
• GitHub 仓库：https://github.com/levi52/dsh-pet