坤宠桌宠liyupi/dsh-kun-like-pet

🐤 Kun Like 桌宠

DeepSeek Harness（DSH）桌面宠物插件 —— 一只住在 Web 界面右下角的小坤宠。
它会盯着 Agent 干活：你搓代码时它努力搬砖，你思考时它托腮，等你回复时它翘首以盼，任务完成时它挥手跳跃、大喊 「你干嘛~哎哟」 🏀

Kun Like 桌宠 · 工作中

Kun Like 桌宠 · 挥手

✨ 特性

- 9 种状态动画：完全沿用 Codex 桌宠精灵图契约（8 列 × 9 行、每格 192×208），素材零重绘
- 实时感知 Agent 状态：轮询 agents 服务感知每个 Agent 的 running/idle 状态，配合 tools/execute、approval/request、agent/request-error 事件推导工作 / 思考 / 等待 / 出错 / 空闲五种模式
- 任务完成全机可闻：宿主进程用系统命令播放「你干嘛~哎哟」，任何窗口、任何会话完成任务都会响，与浏览器静音无关
- 可互动：拖动桌宠到处跑（跑步动画方向跟随），点击它会挥手打招呼
- 内置调试工具：kun_pet_debug 可随时查看状态机内部计数与轮询健康度

🎮 状态 → 动作映射

| Agent 工作状态 | 桌宠动作 | 气泡文案 |
| --- | --- | --- |
| 工作中（有工具在执行） | 专注干活（第 7 行） | 努力工作中… |
| 回合中但空闲 | 思考循环（第 8 行） | 思考中… |
| 等待用户回复 / 审批 | 期待等待（第 6 行） | 在等你回复哦~ |
| 出错 | 难过低落（第 5 行） | 呜…出错了 (._.) |
| 空闲 | 呼吸待机（第 0 行） | 休息中~ 有事叫我 |
| 任务完成 | 挥手 + 跳跃庆祝（第 3/4 行交替）＋ 系统音「你干嘛~哎哟」 | 完成啦！你干嘛~哎哟 |
| 拖动 | 跑步（第 1/2 行，方向跟随） | 呜哇~ 别拽我！ |
| 点击 | 挥手（2.4s 反应） | 诶嘿~ |

🚀 安装

方式一：DSH 动态插件（推荐，已实测）

桌宠以 DSH 动态插件 形式开发并运行验证（cordis_define）。在 DSH 会话里让 Agent 执行，或手动调用 cordis_define 工具：

1. 克隆本仓库：

git clone https://github.com/liyupi/dsh-kun-like-pet.git

2. 修改 src/host.js 顶部 CONFIG 中的素材路径：

const CONFIG = {
spritePath: '/你的/路径/dsh-kun-like-pet/assets/spritesheet.webp',
voicePath:  '/你的/路径/dsh-kun-like-pet/assets/voice.mp3',
// macOS 默认用 afplay；Windows / Linux 请改成对应播放命令
playCommand: (path) => "afplay '" + path.replace(/'/g, "'\\''") + "'",
}

3. 生成一键安装载荷并粘贴给 cordis_define 工具：

node scripts/build-kunpet-package.mjs -   # 输出 JSON 载荷

载荷结构（kind: "new" 创建新插件；后续更新用 kind: "existing" + pluginId）：

{
"plugin": { "kind": "new", "idPrefix": "kunpet" },
"name": "Kun Like 桌宠",
"purpose": "在 Web 界面右下角显示 Kun Like 桌宠，随 Agent 工作状态切换动作，任务完成时播放「你干嘛~哎哟」语音。",
"code": { "host": "", "client": "" }
}

4. 用 cordis_run 激活，Web 界面右下角即出现桌宠。

方式二：直接预览动画（无需 DSH）

打开 demo/index.html（建议起个静态服务器，如 npx serve . 或 python3 -m http.server），即可查看全部 9 种动画并拖动互动。

⚙️ 配置

所有可调项集中在 src/host.js 顶部 CONFIG：

| 配置 | 默认值 | 说明 |
| --- | --- | --- |
| spritePath | ~/.codex/pets/kun-like/spritesheet.webp | 精灵图路径 |
| voicePath | ~/Downloads/你干嘛哎呦.mp3 | 完成音路径 |
| playCommand | afplay '…' | 系统级播放命令（Windows：powershell -c (New-Object Media.SoundPlayer '…').PlaySync()；Linux：ffplay -nodisp -autoexit '…'） |
| pollMs | 500 | Agent 状态轮询间隔 |
| celebrateMs | 4800 | 庆祝动画时长 |
| failedMs | 2600 | 失败动画时长 |

📁 项目结构

dsh-kun-like-pet/
├── src/
│   ├── host.js        # 插件 Host 半：状态机、素材路由、系统音、pet-state RPC、kun_pet_debug 工具
│   └── client.js      # 插件 Client 半：shell.overlay 注入、9 种动画渲染、拖动/点击互动
├── assets/
│   ├── spritesheet.webp   # 8×9 精灵图（1536×1872，Codex 桌宠契约）
│   └── voice.mp3          # 「你干嘛~哎哟」完成音
├── demo/index.html    # 独立动画演示页（无需 DSH）
├── docs/
│   ├── SPRITESHEET-CONTRACT.md   # 精灵图契约与动画行速查
│   └── screenshots…
├── scripts/
│   ├── build-kunpet-package.mjs  # 生成 cordis_define 安装载荷
│   └── validate.mjs              # 仓库完整性校验
├── CHANGELOG.md       # v1 → v5 迭代记录（含事件隔离根因分析）
└── kunpet.package.json    # 由 build 脚本生成的一键安装载荷

校验：node scripts/validate.mjs

❓ 常见问题

为什么桌宠只在某一个窗口里？
动态插件是会话级绑定：桌宠界面只注入到激活它的会话页面。但 v5 起完成音由宿主进程系统级播放，任何窗口、任何会话完成任务本机都会响。若要让桌宠形象出现在所有窗口，需将插件升级为宿主组合级插件包（欢迎 PR）。

为什么不用事件监听而要轮询？
开发过程中用 internal/dispatch 探针实证发现：部分部署里 agent/status、agent/turn-stopping 等 Agent 状态事件不流经动态插件所在总线（831 次事件观测中 status 类事件为 0），事件监听永远等不到「任务完成」。轮询 agents 服务是最可靠的跨部署方案。详见 CHANGELOG v3/v4。

⚠️ 素材版权声明

- assets/voice.mp3 为网络公开的二创梗语音片段（含公众人物声音），版权归原作者所有，仅供个人学习交流使用，请勿用于商业用途；如需商用请自行替换为无版权素材。
- assets/spritesheet.webp 为粉丝二创像素形象，沿用 Codex 桌宠素材契约制作。
- 若您是权利人且不希望相关内容被展示，请联系删除。

📄 License

代码以 MIT License 开源。素材文件（assets/）仅限个人学习交流，遵循上一条声明。