照照 · dsh-cook-pet 🍳
中文 | English
一只住在 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 四档间切换大小（同样记住） |
📦 安装
需要 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
🖥️ 桌面置顶窗：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 |
⚠️ 已知限制
- 素材的 alpha 部分是推算的：源视频没有 alpha，4 段靠"从黑底/绿幕反推"得到；
颠锅与上菜已换成逐帧抠图的 PNG 序列（真 alpha），边缘更准。
- 上菜素材是 30fps 但删过 5 帧（4.73s → 4.57s），理论上可能有一帧级的细微跳变。
- 换素材要重启一次：
?v= 版本号能绕过缓存，但桌面窗启动时就把素材读进内存了。
- 点击回应是随机二选一，不按点击位置/次数区分。
- 没有设置页：大小用右键循环（110 / 138 / 190 / 260），位置拖拽即可（都持久化）。
- 只在桌面窗里存在：Electron 首次需下载约 100 MB。没有页面内嵌版本 ——
如果 Electron 起不来（下载失败、极端受限环境），就看不到照照，但 DSH 本身不受影响。
📜 许可
- 角色「照照」的形象与全部 6 段动作素材由本项目自行生成。
- 本插件代码以 MIT 许可发布，详见 LICENSE。
📚 相关文档
