照照小厨娘 ting-good/dsh-cook-pet

照照 · dsh-cook-pet 🍳

一只小厨娘桌宠，住在 DeepSeek Harness 里。
她叫照照 —— 没活干时握着锅铲站着晃；你派活给她就颠锅炒菜；一轮任务做完，她端着一盘热菜来报喜；需要你批准或回话时，她托着腮歪头等你；戳一下还会 wink 或转个圈。

照照：透明背景，直接浮在桌面上

四种状态（动图，就是桌面上的实际动作）：

| 待机 | 炒菜 | 上菜 | 托腮 |
| 待机 | 炒菜 | 上菜 | 托腮 |
| 站着轻轻晃 | 颠锅翻炒 | 端盘报喜 | 歪头等你 |

✨ 她会做什么

| 时机 | 状态 | 画面 | 文字 |
| 没有任务在跑 | 待机 | 握着锅铲站着轻轻晃 | 无 |
| 回合进行中（turn/start） | 炒菜 | 颠锅翻炒 | 无 |
| 等你批准 / 等你回答问题 | 托腮 | 手背抵着下巴歪头看你 | 等你回话 |
| 回合成功完成 | 上菜 | 端着盘子报喜，约 5 秒后自动回待机 | 无 |
| 回合被打断 / 出错 | 静默回待机 | 不庆祝 | 无 |
| 你点她一下 | wink 或转圈 | 两个里随机挑一个，播完回到当前状态 | 无 |

只有「托腮」会显示一行字，其余全部纯动作。桌宠是装饰性的，平时不该有字挡住画面；只有"轮到你了"这件事值得你一眼看见。

还有一条刻意的设计：「上菜」只在任务真的成功时出现。被打断、出错、超时，她只会安静地回到待机 —— 不会给你一个假的「完成」信号。

🤔 「托腮」到底在等什么

托腮不是模糊的"忙碌"态，它只对应两类真实等待：

| 触发 | 对应宿主事件 |
| 权限确认弹窗（某个工具要你允许/拒绝） | approval/asked → approval/decided |
| 模型用 ask_user_question 向你提问 | tool/call → tool/result |
| 计划模式把方案交给你批准（exit_plan_mode） | 同上 |
| run_code 脚本里发起的提问 | tool/ptc-dispatch-start → tool/ptc-dispatch |

这些是成对出现的持久化事件，所以「开始等你」和「你已答复」都能被精确捕获 ——不需要轮询、不需要猜，也不会因为弹窗被直接关掉而卡在托腮状态。

🖱️ 交互

| 操作 | 效果 |
| 单击 | 随机 wink 或转圈，播完回到当前状态 |
| 拖拽 | 换位置，松手记住（刷新不丢） |
| 右键 | 在 110 / 138 / 190 / 260 px 四档间切换大小（同样记住） |

| 点一下 · wink | 点一下 · 转圈 |
| wink | 转圈 |

📦 安装

需要 DSH ≥ 0.2.0（在 0.2.0-rc.1 ~ 0.2.1-rc.2 上实测通过）。

⚡ 一句命令安装（推荐，走 npm）

dsh plugin --profile desktop add dsh-cook-pet

把 desktop 换成你实际使用的 profile 名（dsh web 用户一般是 web），然后重启 DSH。

- ✅ 不需要 git：pnpm 直接从 npm registry 拉包，机器上有没有 git 都不影响
- ✅ 国内用户若配了 registry.npmmirror.com 镜像，会自动走镜像加速
- ✅ 锁定版本：dsh plugin --profile desktop add dsh-cook-pet@1.0.1
- 本项目是纯 JavaScript、无构建步骤，也没有安装时脚本，所以不需要任何构建授权

备选：从 GitHub 安装

dsh plugin --profile desktop add github:ting-good/dsh-cook-pet

注意：这一路需要机器上装有 git 且能连 github.com（git 解析器要跑 git ls-remote）。

🧑💻 从本地目录安装（开发者 / 离线）

dsh 不在 PATH 时用全路径，例如 Windows 桌面版：
D:\Deepseek\resources\runtime\cli\bin\dsh.cmd
dsh plugin --profile desktop add file:/绝对路径/dsh-cook-pet

🛠️ 装不上时：镜像加速与排查

| 现象 | 原因 | 解法 |
| git ls-remote failed | github 方式需要 git，机器上没有 | 改用 npm 方式（推荐） |
| npm 方式很慢 | 直连 registry.npmjs.org 慢 | 在 ~/.npmrc 写 registry=https://registry.npmmirror.com（DSH 自带 pnpm 会自动读取） |
| dsh 不是命令 | 打包版 CLI 不在 PATH | 用全路径：<安装目录>\resources\runtime\cli\bin\dsh.cmd |

🖥️ 桌面置顶窗：Electron 会自动准备好（可选）

「浮在其它应用之上」那个窗口由独立 Electron 进程渲染，需要一份 Electron 运行时（DSH 宿主本身是纯 Node，不带 Electron 二进制）。

你不需要做任何事：首次缺运行时的时候，插件会在后台自动下载（约 140 MB，只做一次），下载完成后桌面窗会自动出现。下载期间 DSH 完全正常，只是还没看到她。

下载本身是打不死的：

| 能力 | 说明 |
| 多镜像回退 | npmmirror → registry.npmmirror → huaweicloud，逐个尝试 |
| 有限重试 | 每个镜像 3 次；全部失败才放弃 |
| 断点续传 | 中断/重启后从已下载的字节继续，进度保留在 ~/.dsh/electron/.download/ |
| 停滞超时 | 连续 60 秒无数据主动放弃本次尝试，不会挂死 |

万一全部失败，DSH 日志里会打印可照抄的手动安装指引（手动下载 URL、解压目录、指定已有 Electron、关闭桌面窗四种方式），重启 DSH 后自动续传。

| 想做的事 | 怎么做 |
| 手动触发/重试下载（自动续传） | node scripts/ensure-electron.mjs |
| 复用已有的 Electron | DSH_COOK_PET_ELECTRON=<electron 可执行文件路径> |
| 换下载镜像（设置后只用它） | DSH_COOK_PET_ELECTRON_MIRROR=<镜像地址> |

注意：删掉 ~/.dsh/electron 后，她就不会出现了（插件本身仍在跑）。
想彻底关掉桌宠：DSH_COOK_PET_DESKTOP=0，或直接卸载插件。

装完照照会出现在屏幕右下角（屏幕，不是页面里 —— 她浮在所有应用之上）。
位置可以拖，大小右键切换，下次启动都还记得。

🗑️ 卸载

dsh plugin --profile desktop remove dsh-cook-pet

卸载后 Electron 进程、定时器、事件监听全部回收（有测试守着这条）。

🎨 她是怎么做出来的

角色与全部 6 段动作都是 AI 生成（Q 版日系画风，绿幕/黑底源），再经一条可复现的素材管线转成带 alpha 的透明视频。

| 步骤 | 做法 | 为什么 |
| 1. 取 alpha | 只把「与画面四边连通的纯黑」当背景 | 黑色锅铲、深棕描边不会被误删 |
| 2. 边缘颜色外扩 | 把人物颜色铺满羽化带 | 否则羽化带里的黑底会变成一圈脏黑边 |
| 3. 统一裁切框 | 6 段共用同一框（并集） | 切换动作时人物不会跳位 |
| 4. 编码 | 预乘 alpha → VP9 yuva420p | 浏览器唯一可靠的透明视频格式 |

最关键的一条：mp4/H.264 没有 alpha 通道。所谓"抠图 mp4"只是把背景换成了纯黑或绿幕，透明信息在文件里并不存在 —— 必须重新编码成 yuva420p 的 WebM。

🎨 想换成自己的角色？

第 0 步（最关键）：生成视频时用绿幕。

| 背景选择 | 后果 |
| 纯绿幕 #00FF00 ⭐ | 最好抠：绿与人物色差大，能干净分离；半透明效果（烟雾、光晕）也能保住 |
| 纯黑背景 | 能扣，但半透明内容会被压平（白色半透明的烟会变成不透明的深灰），需要额外反推 |
| 白/灰/渐变背景 | 难抠，容易误伤人物浅色部分（白帽子、白围裙） |

另外这几条也要写进生成提示词：正对镜头固定机位、人物不产生位移、 首尾帧姿态一致（循环才不跳帧）、无文字/水印。
本项目 6 段素材的完整提示词可直接参考 docs/视频提示词-等待确认.md 与 docs/视频提示词-点击回应.md。

第 1 步：准备素材文件

6 段视频按动作语义命名，放进 assets/cook-已抠图/：

| 文件名 | 什么时候播 | 要求 |
| 待机.mp4 | 没有任务 | 首尾姿态一致，可循环 |
| 颠锅.mp4 | 回合进行中 | 同上 |
| 上菜.mp4 | 回合成功完成 | 一次性播放 |
| 托腮.mp4 | 等你批准/回答 | 首尾姿态一致，可长时间循环 |
| wink.mp4 | 点击回应 | 首尾姿态 = 待机姿态 |
| 转圈.mp4 | 点击回应 | 同上 |

也可以像本项目最终版那样，直接用逐帧抠好的 PNG 序列（真 alpha）替换 ——画质最好，不需要反推。参考 scripts/build-assets.py 里的读取分支。

第 2 步：跑管线并验收

npm run assets # 生成 6 段透明 WebM 到 assets/pet/
npm run assets:check # 验收：四角透明 / 暗部未误抠 / 6 段尺寸一致 / 颜色通道顺序

管线会自动：取 alpha → 边缘颜色外扩 → 统一裁切框 → 编码 VP9 alpha。
控制台会打印每段的尺寸、alpha 覆盖率与四角 alpha。

第 3 步：只有换了画幅比例时才要改的两处

| 改了什么 | 还要同步改哪里 |
| 裁切框（脚本顶部 CROP） | runtime/electron-helper/renderer.js 顶部的命中框比例常量 |
| 素材内容变了 | renderer.js 里的 ASSET_VERSION +1（否则桌面窗可能读到旧缓存） |

第 4 步：重启 DSH

桌面窗在启动时就把素材读进内存了，所以换素材后必须重启才完全生效。

素材管线踩过的坑（都有数据与回归测试）见 docs/素材管线实测.md。

🗂️ 项目结构

dsh-cook-pet/
├── 🧩 lib/ # 宿主侧：跑在 DSH 进程里 │ ├── index.js # 入口：监听事件、暴露 /state 与 /asset、拉起桌面窗 │ ├── state.js # 四态状态机（idle / cook / serve / think） │ ├── waiting.js # 「等你回话」识别 │ └── desktop.js # 桌面窗进程管理（含自动准备 Electron） │ ├── 🖥️ runtime/electron-helper/ # 桌面窗：独立 Electron 进程，就是你在屏幕上看到的那只 │ ├── main.js # 透明·置顶·无边框窗口 + 点击穿透 + 右键改大小 │ ├── renderer.js # 播放动画、命中判定、拖拽 │ └── preload.js # 渲染端与主进程的桥 │ ├── 🎬 assets/pet/.webm # 6 段透明动画（514×512, VP9 alpha） ├── 🛠️ scripts/ # 素材管线、发布自检、Electron 准备 └── 📚 docs/ # 详细文档（不随包发布）

它是怎么跑起来的：

DSH 宿主进程（lib/index.js） ├─ 监听 session/event → lib/state.js（四态） ├─ 监听审批/提问 → lib/waiting.js（托腮） └─ 暴露 /dsh-cook-pet/state 与 /asset/ │ 1 秒轮询 ▼ Electron 桌面置顶窗（runtime/electron-helper）透明·无边框·浮在所有应用之上

没有构建步骤：lib/*.js 是手写纯 JS，DSH 直接加载。
也没有浏览器内嵌版本 —— 照照只以这个置顶窗存在，最小化 DSH 也能看见她。

🧩 兼容性

| 项 | 状态 |
| DSH | 0.2.0-rc.1 / 0.2.0-rc.2 / 0.2.1-rc.1 / 0.2.1-rc.2 实测通过（engines.dsh: >=0.2.0） |
| 桌面窗 | Windows 实测通过（Electron 43，transparent + alwaysOnTop）；macOS/Linux 未实测 |
| Node | ≥ 22.12 |

⚠️ 已知限制

1. 素材的 alpha 部分是推算的：源视频没有 alpha，4 段靠「从黑底/绿幕反推」得到；颠锅与上菜已换成逐帧抠图的 PNG 序列（真 alpha），边缘更准。
2. 上菜素材是 30fps 但删过 5 帧（4.73s → 4.57s），理论上可能有一帧级的细微跳变。
3. 换素材要重启一次：?v= 版本号能绕过缓存，但桌面窗启动时就把素材读进内存了。
4. 点击回应是随机二选一，不按点击位置/次数区分。
5. 没有设置页：大小用右键循环（110 / 138 / 190 / 260），位置拖拽即可（都持久化）。
6. 只在桌面窗里存在：Electron 首次需下载约 100 MB。没有页面内嵌版本 ——如果 Electron 起不来（下载失败、极端受限环境），就看不到照照，但 DSH 本身不受影响。

📜 许可

- 角色「照照」的形象与全部 6 段动作素材由本项目自行生成。
- 本插件代码以 MIT 许可发布，详见 LICENSE。

📚 相关文档

| 文档 | 内容 |
| docs/素材管线实测.md | 6 段素材的重编码实测数据：尺寸、帧数、alpha 覆盖率、裁切框推导 |
| docs/视频提示词-等待确认.md | 托腮动作的完整生成提示词 |
| docs/视频提示词-点击回应.md | wink / 转圈两个点击回应的完整提示词 |