坤宠桌宠 Practice019/dsh-kun-pet

🐔 Kun Like 桌宠 - DSH 桌面宠物插件

npm 主页 ·
GitHub 仓库 ·安装指南 ·常见问题

DeepSeek Harness 桌面宠物插件 Web 界面右下角的小坤宠，随 Agent 工作状态切换动作，任务完成时播放「你干嘛~哎哟」语音

🎨 状态总览

| 状态 | 触发条件 | 气泡文字 |
| 💤 idle | 空闲时 | 休息中~ 有事叫我 |
| 🔧 working | 工具执行中 | 努力工作中… |
| 🤔 review | 思考中 | 思考中… |
| ⏳ waiting | 等待用户回复 | 在等你回复哦~ |
| ❌ failed | 出错时 | 呜…出错了 (._.) |
| 🎉 celebrating | 任务完成 | 完成啦！你干嘛~哎哟 |
| 🏃 runRight/runLeft | 拖拽时 | 呜哇~ 别拽我！ |
| 👋 wave | 点击时 | 诶嘿~ |

✨ 功能特性

| 功能 | 说明 |
| 🎭 9种动画状态 | idle、working、review、waiting、failed、celebrating、runRight、runLeft、wave/jump |
| 🔊 单端语音播放 | 每个对话窗口停止输出时由 Host PowerShell 各播放一次（提问工具触发后不重复；多窗口各自触发，不依赖浏览器焦点） |
| 🖱️ 拖拽移动 | 按住桌宠拖动到任意位置 |
| 👆 点击互动 | 点击桌宠挥手打招呼 |

📦 一键安装（静态插件）

前置条件

- 已安装 DeepSeek Harness (DSH)
- 已安装 pnpm
- Windows 系统（需要 PowerShell）

安装命令

方式 1（推荐）：从 npm registry 一键安装
dsh plugin --profile web add dsh-kun-pet

方式 2：从 Git 仓库安装
dsh plugin --profile web add github:Practice019/dsh-kun-pet

方式 3：本地开发（link 模式，改代码重启即生效）
dsh plugin --profile web add ./dsh-kun-pet

安装后重启 DSH 即可，桌宠会自动出现在 Web 界面右下角，无需任何手动激活步骤。

更新插件

检查并更新到最新版本
dsh plugin update dsh-kun-pet

安装原理

dsh plugin add → pnpm 安装包
→ 识别 package.json 的 dsh.bundle.patch 声明 → 自动加入 profile 的 bundles 列表 → 识别 dsh.client 声明，注册浏览器端 bundle 重启 DSH → Host 端 (lib/index.js) 由 cordis.patch.yml 自动加载 → Client 端 (lib/client.js) 由浏览器模块表自动加载

卸载

dsh plugin --profile web remove dsh-kun-pet

🎮 使用说明

交互方式

- 拖拽：按住桌宠拖动到任意位置
- 点击：小鸡会挥手打招呼
- 任务完成：自动播放「你干嘛~哎哟」语音

声音播放

- 任务完成：Host 端 PowerShell 系统级播放（完整播放，等待播放结束才关闭；需要 Windows PresentationCore）；多窗口同时工作时，每个窗口停止输出都会各自播放一次
- 提问等回复：AI 调用提问工具的瞬间立即播放；同一回合停止输出时不会重复播放
- 点击小鸡：浏览器 Audio 即时播放（交互反馈）

🔧 技术架构

┌─────────────────────────────────────────────────────────────┐
│ DSH Web 界面 │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ shell.overlay 插槽 │ │ │ │ ┌─────────────────────────────────────────────┐ │ │ │ │ │ KunPet 组件 │ │ │ │ │ │ - 精灵图动画 (8列×9行) │ │ │ │ │ │ - 状态同步 (每400ms) │ │ │ │ │ │ - 拖拽/点击交互 │ │ │ │ │ │ - 浏览器 Audio 播放声音 │ │ │ │ │ └─────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────┘ │ │ fetch('/kun-pet/state') 每 400ms ▼ ┌─────────────────────────────────────────────────────────────┐ │ DSH Host 进程 │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ 状态机 │ │ │ │ - 轮询 agents.list() 每500ms │ │ │ │ - 监听 approval/request, tools/execute 事件 │ │ │ │ - 推导桌宠状态 (idle/working/review/celebrating) │ │ │ └─────────────────────────────────────────────────────┘ │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ 资源服务 │ │ │ │ - /kun-pet/sprite.webp (精灵图) │ │ │ │ - /kun-pet/voice.mp3 (声音) │ │ │ │ - /kun-pet/state (状态 JSON) │ │ │ └─────────────────────────────────────────────────────┘ │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ PowerShell 声音播放 │ │ │ │ - 任务完成时系统级播放声音 │ │ │ │ - 不依赖浏览器焦点 │ │ │ └─────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────┘

📁 文件结构

dsh-kun-pet/
├── package.json ← DSH 插件声明 (dsh.bundle.patch + dsh.client) ├── cordis.patch.yml ← Host 插件行（DSH 启动时自动加载） ├── README.md ← 本文档 ├── lib/ │ ├── index.js ← Host 端代码（状态机 + 资源服务 + 声音播放） │ └── client.js ← Client 端 bundle（UI + 交互 + 浏览器声音播放） ├── assets/ │ ├── spritesheet.webp ← 精灵图 (8列×9行, 192×208/格) │ └── voice.mp3 ← 「你干嘛~哎哟」语音 ├── docs/ │ ├── logo.png ← README 主图（idle 第一帧） │ ├── preview-sequence.png ← 动画序列帧预览 │ └── states.png ← 9 种状态总览图 └── scripts/ └── gen-docs-images.mjs ← 文档图片生成脚本

🐛 常见问题

1. 任务完成时没有声音

原因：PowerShell 播放失败（缺少 PresentationCore 程序集）或语音文件缺失

解决方案：
- 确认系统为 Windows（需要 PowerShell + WPF 运行时）
- 检查 node_modules/dsh-kun-pet/assets/voice.mp3 是否存在
- 手动测试：powershell -c "Add-Type -AssemblyName PresentationCore; $p = New-Object System.Windows.Media.MediaPlayer; $p.Open([uri]'file:///D:/path/to/dsh-kun-pet/assets/voice.mp3'); $p.Play(); Start-Sleep -Seconds 5"

1b. 声音被截断 / 播放两次

原因：旧版本固定等待 3 秒，长语音会被截断；或者双端同时播放

解决方案：
- 升级到 v1.0.0+（lib/index.js 会等待 NaturalDuration 完整播放）
- 任务完成声音统一由 Host PowerShell 播放一次，Client 只保留点击交互播放

2. 精灵图不显示

原因：资源文件读取失败，或者 Host 插件未生效（/kun-pet/state 返回 HTML 而非 JSON）

解决方案：
- 检查 node_modules/dsh-kun-pet/assets/ 目录下是否存在精灵图文件
- 确认 Host 插件注入了 webServer 服务（lib/index.js 的 inject: ['timer', 'webServer']），否则启动早期服务未就绪时插件会静默退出
- 重启 DSH 后测试 http://127.0.0.1:3080/kun-pet/state 是否返回 JSON

3. 修改代码后不生效

原因：静态插件在 DSH 启动时加载

解决方案：修改 lib/ 下代码后重启 DSH 生效

📝 开发说明

精灵图规格

- 格式：WebP
- 布局：8 列 × 9 行
- 每格尺寸：192 × 208 像素
- 总尺寸：1536 × 1872 像素

状态对应

| 行号 | 状态 | 帧数 |
| 0 | idle | 6 |
| 1 | runRight | 8 |
| 2 | runLeft | 8 |
| 3 | wave | 4 |
| 4 | jump | 5 |
| 5 | failed | 8 |
| 6 | waiting | 6 |
| 7 | working | 6 |
| 8 | review | 6 |

📄 许可证

MIT License

Made with ❤️ for DSH users