照照 · 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 四档间切换大小（同样记住）

点一下 · wink	点一下 · 转圈

---

📦 安装

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

⚡ 一句命令安装（推荐）

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

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

这条命令走的是 git 安装 —— 本项目是纯 JavaScript、无构建步骤， 所以不需要 prepare 构建授权，装完即可用。

🧑‍💻 从本地目录安装（开发者）

# 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 二进制）。

你不需要做任何事：首次缺运行时的时候，插件会在后台自动下载（约 100 MB，只做一次， 走 npmmirror 镜像），下载完成后桌面窗会自动出现。下载期间 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.1-rc.1 实测通过；0.2.0-rc.1 / 0.2.0-rc.2 契约一致
桌面窗	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 / 转圈两个点击回应的完整提示词