前言¶

跑 DSH 的人大多遇到过同一个问题：agent 一跑就是几分钟甚至更久，你切到别的窗口干活，回来第一件事是确认它现在是在跑、在等审批，还是已经报错停了。目前的办法只有切回 Web GUI 盯着输出，或者翻日志。

silverhand-dsh-pet 换了个思路：把状态显示交给一只桌面宠物。它在 DSH Web GUI 右下角常驻，agent 空闲时呼吸、干活时工作、出错时闹脾气，你瞥一眼角落就知道 agent 的状态。下面介绍这个插件的具体功能、安装步骤和排查方法。

这是什么¶

silverhand-dsh-pet 是一个标准的 DSH 插件包，作者是 Qiao-NEYC，代码以 MIT 许可发布。它在 DSH Web GUI 的 shell.overlay 层渲染一个名叫 Silverhand 的角色（带银色义肢的赛博朋克雇佣兵形象），固定在窗口右下角，由 DSH host 事件驱动，随 agent 状态做出反应。

素材原样迁移自 Codex pet 格式（spritesheet.webp + pet.json），图集为 8×9、单元格 192×208，没有重新设计。

核心功能¶

• 在 DSH Web GUI 的 shell.overlay 层渲染，固定于右下角；默认点击穿透，只有宠物本体可交互，不影响其他操作。
• 由 DSH host 事件驱动，状态映射如下：
• idle / running：来自 agent/status
• review：来自 tools/result
• failed：来自 agent/error
• waving：来自 agent/created 与 agent/session-start
• jumping：一个 turn 结束（running → idle）时触发
• waiting：approval/request 打开期间
• 可拖动移动，宠物朝拖动方向行走。
• 悬停显示当前状态；单击（无位移）使其跳跃。

安装与启用¶

这是标准的 DSH 插件包，README 给出两种安装方式，推荐从 GitHub 安装。

1、编辑 ~/.dsh/profiles/<profile>/package.json，把它加进 dependencies 和 dsh.profile.bundles：

{
  "dependencies": {
    "silverhand-dsh-pet": "github:Qiao-NEYC/silverhand-dsh-pet"
  },
  "dsh": {
    "profile": {
      "bundles": [
        "...your existing bundles...",
        "silverhand-dsh-pet"
      ]
    }
  }
}

2、在 profile 目录运行 pnpm install（或者让 DSH 桌面应用在启动时安装）。

3、重启 DSH，宠物会出现在右下角。

另一种方式是 npm 安装：先运行 npm i silverhand-dsh-pet，再把 "silverhand-dsh-pet" 加入 dsh.profile.bundles。注意 README 把这条路标注为 Once published，即 npm 包发布后方可使用，目前推荐用上面的 GitHub 依赖方式。

插件的 peerDependencies 为 react ^18.2.0、@deepseek-ai/cordis ^4.0.1、@deepseek-ai/dsh-client-runtime ^0.1.0-rc.6、@deepseek-ai/dsh-client-ui-layout ^0.1.0-rc.6、@deepseek-ai/dsh-client-ui-slots ^0.1.0-rc.6。如果遇到宠物图像空白或缺失，先确认使用的包版本为 1.0.1 及以上（当前版本为 1.0.2）——从 1.0.1 起 client bundle 显式声明了布局依赖，保证注册前 shell.overlay 已可用。

工作原理¶

一个 DSH 插件是拆成两半的 Cordis 插件，这个项目也一样：

• Host 半（lib/index.js）运行在 DSH 的 Node 进程里。它通过 import.meta.url 从自己的 assets/ 目录读取图集（无论包装在哪里都能找到），并注册两个同源 HTTP 路由：
• GET /silverhand-pet/spritesheet.webp：精灵图集
• GET /silverhand-pet/state：从 agent 事件推导出的状态，返回 { "state": "..." }
• Client 半（lib/client.js）运行在浏览器里。它注册进 shell.overlay，每 300ms 轮询一次 /silverhand-pet/state，并从 /silverhand-pet/spritesheet.webp 播放对应图集行的动画。

两半之间只靠普通的同源 HTTP 路由通信，没有额外的通道。

配置与排查¶

插件没有独立配置项，所有可调参数都是两半代码顶部的常量：

• lib/index.js：ROUTE_SPRITE / ROUTE_STATE，以及事件监听器里各状态的瞬态时长。
• lib/client.js：ANIMS（每行动画的行号、帧数、节奏）、STATE_ANIM（状态到动画的映射）、PET_W / PET_H（显示尺寸）和 CSS 块（位置、阴影、悬停样式）。

排查宠物图像空白或缺失时，按下面的顺序检查：

1、确认包版本不低于 1.0.1。
2、Client 会探测 /silverhand-pet/spritesheet.webp，如果 Host 半没有正常提供图集，浏览器控制台会记录路由错误。出现 404 或 500 表示 host 包未激活，需要重装 bundle 并重启 DSH。
3、状态切换时动画帧会重置，避免过期的帧序号在切回六帧的 idle 或 waiting 行时选中空白单元——这是内置的保护逻辑，不是故障。
4、如果宠物容器存在但透明，打开浏览器 Network 面板检查 sprite 路由：正常响应应为 image/webp、体积约 1 MB。

仓库还带了三个开发辅助脚本，前两个需要 Python 3 以及 Pillow、numpy：

# 重新生成 docs/demo.gif
python scripts/make_demo_gif.py

# 输出每行不透明单元格数量与相邻帧差异
python scripts/analyze_frames.py

# 渲染带标注的 contact sheet（完整版 + 放大的易混淆行）
python scripts/contact_sheet.py

适用场景与注意¶

适合两类人：一是长期把 DSH 放在后台、需要不切窗口就能看到 agent 状态的使用者；二是想学习 DSH 插件两半结构（host + client、同源 HTTP 通信、shell.overlay 注册）的开发者，这个包体量小、结构清晰，可以当参考实现读。

安装前有两点务必注意：

1、插件以当前 dsh 进程的权限运行，安装前应检查源码与许可证。代码部分是 MIT 许可；但 sprite 素材（Silverhand 形象）的许可未在仓库中声明，素材迁移自本地 Codex pet 目录（~/.codex/pets/silverhand/），README 明确要求：在公开发布这个仓库之前，需自行确认你持有（或已取得）sprite 与 Silverhand 形象的再分发权。个人本地使用前也建议自行评估。
2、另外，社区插件目录是独立站点，与 DeepSeek / 幻方没有官方从属关系，安装任何第三方插件时都以源码为准。

结尾¶

silverhand-dsh-pet 解决的是一个很小的痛点：不用盯着窗口也能知道 agent 在干什么。它实现干净——两个 HTTP 路由加一个 300ms 轮询的客户端，事件到状态的映射一目了然，既是小玩具，也是一份可以照着写的 DSH 插件样例。

• 目录页：https://www.skillhub.cn/plugins/Qiao-NEYC/silverhand-dsh-pet
• GitHub：https://github.com/Qiao-NEYC/silverhand-dsh-pet