dsh-pixel-pet
已验证@pifu/dsh-pixel-pet · v0.1.0 · MIT · Web 界面
DeepSeek Harness Web 的宝可梦风像素桌宠：渲染在现有 Web 界面浮动层内，实时反应对话状态（idle/thinking/tool/waiting/error/success/sleeping），支持导入 sprite sheet 宠物包。
安装
dsh plugin add @pifu/dsh-pixel-pet 用 dsh --profile default --dump-config 确认 layer 已生效 —— 参见安装指南。
源码
发布到 npm 但没有公开仓库。安装前请检查包内容。
标签
作者
说明文档
dsh-pixel-pet
DeepSeek Harness Web 的宝可梦风像素桌宠：渲染在现有 Web 界面浮动层内，实时反应对话状态（idle/thinking/tool/waiting/error/success/sleeping），支持导入 sprite sheet 宠物包。
显著声明：纯 DSH 插件，渲染在现有 DSH Web 界面 DOM 内；不需要任何独立桌面应用；不起额外进程、不监听额外端口（复用 DSH 自己的 3080 web server，证据：ctx.webServer 前缀路由）。
安装
方式一：npm 安装（推荐）
dsh plugin add @pifu/dsh-pixel-pet
然后重启 dsh web 并刷新页面。
方式二：git 克隆安装
git clone https://github.com/zhuifengqug/dsh-pixel-pet.git
cd dsh-pixel-pet
dsh plugin --profile web add link:.
然后重启 dsh web 并刷新页面。
方式三：本地链接安装（开发用）
dsh plugin --profile web add link:D:/dsh/dsh-pixel-pet
然后重启 dsh web 并刷新页面。
配置
用户态配置文件：$DSH_HOME/dsh-pixel-pet/config.json（本机 = D:\DSHData\home\dsh-pixel-pet\config.json）
包内默认配置：assets/config.jsonc（本插件与历史 pet.json / settings 的 pet: 段完全无关，不读不写不迁移）
设置页 key：pixel-pet
配置字段表
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
visible |
boolean | true |
是否显示桌宠 |
petId |
string | "default" |
使用哪个宠物包（目录名） |
scale |
integer (1..4) | 3 |
像素缩放倍数，只允许整数倍 |
corner |
string | "bottom-right" |
停靠角落：top-left / top-right / bottom-left / bottom-right |
margin |
object | { "x": 16, "y": 16 } |
距离该角落的边距（CSS px） |
sleepingAfterMs |
number | 300000 |
无活动多久后进入 sleeping（毫秒），0 = 关闭 |
minStateDurationMs |
number | 400 |
状态最小驻留时间（毫秒），合并高频事件避免闪烁 |
errorSuppressSuccessMs |
number | 5000 |
error 之后多久内不再播 success（毫秒） |
successHoldMs |
number | 1600 |
success 瞬时态的持续时间（毫秒） |
errorHoldMs |
number | 2500 |
error 瞬时态的持续时间（毫秒） |
respectReducedMotion |
boolean | true |
尊重系统的 prefers-reduced-motion: reduce |
roam |
boolean | true |
是否允许 idle 时随机漫游 |
opacity |
number (0..1) | 1 |
桌宠透明度 |
instances |
array | [] |
多开实例列表，每项可独立配置 id/petId/scale/corner/offset |
状态映射表
| 状态 | 真实事件名 | 桌宠表现 | 接通情况 |
|---|---|---|---|
idle |
agent/status idle | 待机呼吸+随机小动作 | ✅已接通 |
thinking |
agent/status running | 思考动作 | ✅已接通 |
tool |
tools/pre-execute | 敲电脑忙碌动作 | ✅已接通（有真实事件源） |
waiting |
approval/request | 举手等待 | ✅已接通，但受会话审批策略限制（danger-full-access 下永不触发，workspace-write 下正常） |
error |
agent/error | 摔倒冒烟 | ✅已接通 |
success |
agent/status idle（且非error后5s内） | 欢呼跳跃 | ✅已接通 |
sleeping |
idle持续超阈值 | 睡觉Zzz | ✅已接通 |
导入任天堂素材操作指南
显著提示：第三方素材仅限个人本地使用，不得商用或再分发；该目录不会进 git、不会随 npm 发布（指出 .gitignore / .npmignore / files 白名单的具体行作为证据）。
步骤
生成样板包
- 在设置页点击「生成样板包」按钮
- 打开生成的目录：
D:\DSHData\home\dsh-pixel-pet\pets\<name>\
准备 sprite sheet
- 将你的素材图片切成 sprite sheet
- 帧尺寸必须一致（如 32×32 像素）
- 图片尺寸必须是帧尺寸的整数倍（如 512×32 = 16 帧）
- 每帧四周留至少 1px 空白，避免缩放时被裁掉
- 用完全透明（alpha=0）做背景，不要用纯色背景
帧索引规则
- 按行优先（row-major）排列，索引从 0 开始
- 示例：512×32 图片，32×32 帧 → 16 帧，索引 0..15
- 第一行：0, 1, 2, ..., 15
- 第二行：16, 17, 18, ..., 31（如果有多行）
修改 pet.jsonc
- 打开
pet.jsonc文件 - 修改
id、displayName、frame、sheets、animations、states等字段 - 参考
assets/pets/default/pet.jsonc中的注释
- 打开
设置页切换
- 在设置页选择你的宠物包
- 保存后即时生效
故障排查
桌宠没出现怎么办
- 检查 DSH Web 是否已重启并刷新页面
- 检查浏览器控制台是否有错误
- 检查宠物包是否正确加载（设置页会显示校验结果）
坏包报错怎么看
- 在设置页查看宠物包列表，每个包都会显示校验状态
- 错误码说明见
docs/PET_PACK.md第 5 节 - 常见错误：帧尺寸不整除、缺少 idle 动画、图片路径错误
怎么恢复默认
- 在设置页点击「恢复默认」按钮
- 或者手动删除用户态配置文件：
D:\DSHData\home\dsh-pixel-pet\config.json - 宠物会自动回退到内置 default 包
相关文件
| 文件 | 作用 |
|---|---|
assets/pets/default/pet.jsonc |
内置默认包，注释齐全的活文档 |
assets/pets/default/base.png |
内置默认 sprite sheet（512×32，16 帧） |
assets/templates/starter/ |
给用户抄的样板包（含标尺占位图 + 中文 README） |
tools/gen-default-sprite.mjs |
程序化生成上面两张 PNG（零依赖，可复现） |
tools/check-sheet.mjs |
开发期体检：尺寸整数倍、空帧、贴边、颜色数、半透明统计 |
tools/preview-sheet.mjs |
开发期预览：放大 + 网格排布 + 帧分隔线，输出到临时目录 |
THIRD_PARTY_NOTICES.md |
素材原创声明与第三方素材使用边界 |
docs/PET_PACK.md |
宠物包格式详细文档 |
DESIGN.md |
设计文档（不在 npm 包内，仅用于开发参考） |
发布卫生验证
npm pack --dry-run 输出（确认只包含原创素材，无第三方内容）：
npm notice
npm notice package: [email protected]
npm notice Tarball Contents
npm notice 5.7kB README.md
npm notice 5.7kB THIRD_PARTY_NOTICES.md
npm notice 1.9kB assets/config.jsonc
npm notice 1.5kB assets/pets/default/base.png
npm notice 4.4kB assets/pets/default/pet.jsonc
npm notice 529B assets/templates/starter/base.png
npm notice 5.8kB assets/templates/starter/pet.jsonc
npm notice 7.1kB assets/templates/starter/README.md
npm notice 459B cordis.patch.yml
npm notice 25.9kB docs/PET_PACK.md
npm notice 82.6kB lib/client.js
npm notice 9.1kB lib/config.js
npm notice 5.0kB lib/http.js
npm notice 28.5kB lib/index.js
npm notice 2.9kB lib/jsonc.js
npm notice 24.1kB lib/pet-pack.js
npm notice 10.6kB lib/state-machine.js
npm notice 1.3kB package.json
npm notice Tarball Details
npm notice name: dsh-pixel-pet
npm notice version: 0.1.0
npm notice filename: dsh-pixel-pet-0.1.0.tgz
npm notice package size: 72.5 kB
npm notice unpacked size: 223.0 kB
npm notice shasum: 63f245540e49fa7601074bf18be5cdb5e0a998c7
npm notice integrity: sha512-QT+mGzRFL7cuC[...]N/6xTd2/cqV1g==
npm notice total files: 18
npm notice
dsh-pixel-pet-0.1.0.tgz
注意：DESIGN.md 不在 package.json 的 files 白名单中，不会包含在 npm 包内。如需发布设计文档，需将 DESIGN.md 添加到 files 数组。
错误码说明
错误码 PPxxx 的完整定义见 docs/PET_PACK.md 第 5 节。以下为关键映射（以文档为准）：
| 错误码 | 级别 | 说明 |
|---|---|---|
| PP100 | fatal | 宠物包缺少 pet.jsonc |
| PP101 | fatal | pet.jsonc 语法错误 |
| PP103 | fatal | pet.jsonc 顶层不是对象 |
| PP200 | fatal | 缺少 id 或 id 不合法 |
| PP300 | fatal | frame 尺寸不合法 |
| PP301 | fatal | 图片尺寸不是帧尺寸的整数倍 |
| PP400 | fatal | 图片文件不存在 |
| PP401 | fatal | 图片格式不支持（v1 只支持 .png） |
| PP500 | fatal | 帧号越界 |
| PP700 | fatal | 缺少必填动画 idle |
| PP800 | warn | 状态指向了不存在的动画 |
许可证
MIT