Qiao-NEYC/silverhand-dsh-pet

Silverhand — DSH 桌面宠物

License: MIT
DeepSeek Harness
Cordis

一个用于 DeepSeek Harness Web GUI 的桌面宠物。Silverhand（一个拥有银色机械臂的赛博朋克雇佣兵）住在右下角，并对智能体正在做的事情做出反应——空闲时的呼吸、活跃工作、查看输出、挥手打招呼、庆祝回合结束、因错误而闷闷不乐，以及等待你的批准。

角色美术资源是原样从 Codex 宠物格式迁移过来的——没有重新设计，只是原始的 spritesheet.webp + pet.json。

功能特性

- 渲染在横跨整个框架的 shell.overlay 图层中，固定在右下角。
- 默认点击穿透（只有宠物本身可交互）。
- 对真实的智能体状态做出反应，由 DSH 宿主事件驱动：
- 来自 agent/status 的 idle / running
- 来自 tools/result 的 review
- 来自 agent/error 的 failed
- 来自 agent/created / agent/session-start 的 waving
- 当回合结束时（running → idle）的 jumping
- 当审批请求处于打开状态时（approval/request）的 waiting
- 拖动宠物来移动它——它会朝拖动方向左右行走。
- 悬停可查看当前状态；点击（不移动）会让它跳跃。

安装

这是一个标准的 DSH 插件包。有两种安装方式：

从 GitHub 安装（推荐）

1. 将它添加到你的配置文件的 dependencies 和 dsh.profile.bundles 中
（位于 ~/.dsh/profiles//package.json）：

{
"dependencies": {
"silverhand-dsh-pet": "github:Qiao-NEYC/silverhand-dsh-pet"
},
"dsh": {
"profile": {
"bundles": [
"...你现有的 bundles...",
"silverhand-dsh-pet"
]
}
}
}

2. 在配置文件目录中运行 pnpm install（或让 DSH 桌面应用在启动时安装）。
3. 重启 DSH。宠物会出现在右下角。

从 npm 安装

发布后：npm i silverhand-dsh-pet，然后将 "silverhand-dsh-pet" 添加到
dsh.profile.bundles。

目录结构

Silverhand/
├── README.md
├── LICENSE
├── .gitignore
├── package.json           # DSH 插件清单（dsh.client、exports）
├── lib/
│   ├── index.js           # 宿主端：读取精灵图，提供 HTTP 路由 + 状态
│   └── client.js          # 客户端：渲染宠物，轮询状态
├── assets/
│   ├── pet.json           # 迁移后的 Codex 清单
│   └── spritesheet.webp   # 迁移后的精灵图集（8×9，192×208 单元格）
├── scripts/
│   ├── make_demo_gif.py   # 渲染 docs/demo.gif（动画演示）
│   ├── analyze_frames.py  # 测量每行的帧数 / 差异
│   └── contact_sheet.py   # 渲染带标签的缩略图总览
└── docs/
├── demo.gif           # 动画演示（所有动画）
└── sprite-atlas.md    # 图集布局 + 状态映射

结构剖析

DSH 插件是一个 Cordis 插件，分为两半：

- 宿主端（lib/index.js）运行在 DSH Node 进程中。它从自身的 assets/
读取精灵图（通过 import.meta.url，因此无论包安装在何处都能正常工作），
并注册两个 HTTP 路由：
- GET /silverhand-pet/spritesheet.webp —— 精灵图集。
- GET /silverhand-pet/state —— 由 agent 事件推导出的 { "state": "..." }。
- 客户端（lib/client.js）运行在浏览器中。它注册到 shell.overlay，
每 300 毫秒轮询一次 /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.0.1 或更新版本的包。客户端 bundle 现在显式声明了布局依赖，
因此在宠物注册之前 shell.overlay 就已可用。
- 客户端会探测 /silverhand-pet/spritesheet.webp，如果宿主端没有提供图集，
会在浏览器控制台记录一条路由错误。404 或 500 表示宿主包未激活；
请重新安装 bundle 并重启 DSH。
- 每当状态变化时，动画帧都会重置。这可以防止在切回六帧的 idle 或
waiting 行时，过期的帧索引选中空的图集单元格。
- 如果宠物容器存在但透明，请检查浏览器 Network 面板中的精灵图路由，
并确认其响应为 image/webp，且负载约为 1 MB。

素材来源

该图像迁移自本地 Codex 宠物目录
（~/.codex/pets/silverhand/）。它是你的素材——在将此仓库发布到 GitHub
之前，请确认你拥有（或已获得）重新分发该 sprite 以及 Silverhand 肖像的权利。
本仓库中的代码采用 MIT 许可；精灵图的许可由你自行声明。

开发辅助工具
bash
重新生成 docs/demo.gif
python scripts/make_demo_gif.py

报告每行的不透明单元格数量以及连续帧差异
python scripts/analyze_frames.py

渲染带标注的拼版图（完整版 + 放大的模糊行）
python scripts/contact_sheet.py

analyze_frames.py / contact_sheet.py 需要 Python 3 以及 Pillow 和
numpy。