Chuyển đến nội dung chính
dsh marketplace

dsh-pixel-pet

Đã xác minh

@pifu/dsh-pixel-pet · v0.1.0 · MIT · Giao diện web

DeepSeek Harness Web 的宝可梦风像素桌宠：渲染在现有 Web 界面浮动层内，实时反应对话状态（idle/thinking/tool/waiting/error/success/sleeping），支持导入 sprite sheet 宠物包。

Cài đặt

dsh plugin add @pifu/dsh-pixel-pet

Xác nhận layer đã áp bằng dsh --profile default --dump-config — xem hướng dẫn cài plugin.

Mã nguồn

Phát hành lên npm mà không có repository công khai. Hãy kiểm tra nội dung package trước khi cài.

Thẻ

Tác giả

Readme

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 白名单的具体行作为证据）。

步骤

  1. 生成样板包

    • 在设置页点击「生成样板包」按钮
    • 打开生成的目录：D:\DSHData\home\dsh-pixel-pet\pets\<name>\

  2. 准备 sprite sheet

    • 将你的素材图片切成 sprite sheet
    • 帧尺寸必须一致（如 32×32 像素）
    • 图片尺寸必须是帧尺寸的整数倍（如 512×32 = 16 帧）
    • 每帧四周留至少 1px 空白，避免缩放时被裁掉
    • 用完全透明（alpha=0）做背景，不要用纯色背景

  3. 帧索引规则

    • 按行优先（row-major）排列，索引从 0 开始
    • 示例：512×32 图片，32×32 帧 → 16 帧，索引 0..15
    • 第一行：0, 1, 2, ..., 15
    • 第二行：16, 17, 18, ..., 31（如果有多行）

  4. 修改 pet.jsonc

    • 打开 pet.jsonc 文件
    • 修改 id、displayName、frame、sheets、animations、states 等字段
    • 参考 assets/pets/default/pet.jsonc 中的注释

  5. 设置页切换

    • 在设置页选择你的宠物包
    • 保存后即时生效

故障排查

桌宠没出现怎么办

  1. 检查 DSH Web 是否已重启并刷新页面
  2. 检查浏览器控制台是否有错误
  3. 检查宠物包是否正确加载（设置页会显示校验结果）

坏包报错怎么看

  1. 在设置页查看宠物包列表，每个包都会显示校验状态
  2. 错误码说明见 docs/PET_PACK.md 第 5 节
  3. 常见错误：帧尺寸不整除、缺少 idle 动画、图片路径错误

怎么恢复默认

  1. 在设置页点击「恢复默认」按钮
  2. 或者手动删除用户态配置文件：D:\DSHData\home\dsh-pixel-pet\config.json
  3. 宠物会自动回退到内置 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