HeronBo-AIGC-Prompt

---
name: HeronBo-AIGC-Prompt
description: 生成各类 AI 视频的提示词：①图生视频（图片/首尾帧/多图驱动，含道具与主体替换）②文生视频（纯文字）③参考视频生视频（参考运镜/动作/节奏）④参考视频替换生视频（保留动作构图、只换主体）；也用于拆解 AI 二创/爆款成片（读片三问 + 机器证据 + 拆解报告）。当用户要求写视频提示词、把文案/台词/素材变成生成指令、做分镜、换人换物换装、复刻或仿做某条片子，或在即梦/Seedance/MiniMax H3 等平台生成视频时使用。限额按模型维护，见 `references/platforms.md` 的「模型与限额」表；本 skill 只产出提示词文字与分析报告，不提交生成、不消耗积分；并根据每次成片反馈持续优化规则。
version: 0.6.5
agent_created: true
---

# AI 视频提示词生成

输入「文案/台词 + 素材（图片/视频/音频）」→ 按类型与所选模型输出可直接粘贴到生成平台的提示词；每次成片反馈都沉淀成规则，越用越准。

**覆盖四大类**：图生视频（含道具替换）／文生视频／参考视频生视频／参考视频替换生视频。口播只是其中一种形态，人物（老师/角色/数字人）是项目给的参数，不是预设。

## 职责边界

- 只产出**提示词文字 + 素材清单（+ 拼接说明）**；默认不提交生成、不消耗积分。
- 交付物**禁止出现**：CLI 命令、积分/价格、队列等待、提交方式配置。
- 只有用户**明确要求代提交**时才执行：先报单价 → 用户确认 → 执行 → 如实报告消耗；这类内容不进常规交付（rules.md 第13条）。
- 生成结果的评价由用户用**评分工具（窗口版，交付后由 agent 弹出）**完成，废片归档同样归用户；本 skill 只回收这些反馈来更新规则。

## 按需读取（无需通读全文）

| 场景 | 读什么 |
|---|---|
| 首次使用（没有 `references/paths.local.md`） | 先执行「工作流 0」的两句问答 |
| 写任何提示词前 | `references/rules.md` **顶部的规则索引** → 只读本次相关条目 |
| 选模板、定段数 | `references/prompt-templates.md`（开头有「四大类 ↔ 模板」总表） |
| 定类型、查模型档位与时长/数量上限 | `references/platforms.md` 的「模型与限额」表（**唯一真相源**）+ 本文件「四大类判定表」 |
| 替换类任务（换人/换物/换装/复刻原片） | `references/playbooks.md` 第一部分（替换类手册）+ 规则索引「替换类」那组 |
| **用户发来成片要拆解/仿做（AI 二创、爆款复现）** | `references/playbooks.md` 第二部分（二创拆解手册）+ `tools\成片拆解.py`（机器证据）、`tools\成片对比.py`（二创 vs 原片：声音路线/画面同轴）（规则33–38「二创与拆解」组）；**读片优先级：用户发文件 ＞ 不下载（平台接口/字幕）＞ 下载后本地读** |
| 深度视频 / 人物遮罩 / 环境准备（L4 复刻动作的前置） | `references/playbooks.md` 第三部分 + `tools\深度视频.py`、`tools\人物遮罩.py` |
| 给图片遮脸（过审核 / 防 20b 身份锚定；用户勾了「素材加工→遮脸」才做） | `tools\人脸遮罩.py`（YuNet 检测，色块/模糊，输出 `原名_遮脸.png`） |
| 换机 / 换 agent / 工具报缺依赖 | `python tools\环境检查.py`（逐项自检 + 缺什么装什么；**装前先问用户**） |
| 结构/节奏/微表情/平台玩法细化 | `references/platforms.md` 第三部分（15 秒五段式、爆款框架、微表情三禁忌、分镜注入纪律、角色设定图） |
| 成片打分（**交付后必弹**） | `tools\score_gui.cmd`（优先 `dist\score-tool.exe`，没有则 pythonw 兜底）；无图形环境用 `tools\评分.py`。旧网页版 `评价工具.html` 已降级为兜底 |
| 收素材 / 建项目框架（**出提示词后自动调**） | `tools\dist\score-tool.exe --material`（同一个 exe 的第二个用途）；无图形环境用 `python tools\project_core.py --root "<项目库>" --name "<实验名>" --add "<素材路径>"` |
| 改完规则做回归自检 | `references/eval-cases.md`（用例 + 断言） |
| 平台与 CLI、提交纪律 | `references/platforms.md` 第一、二部分 |
| 路径变量 | `references/paths.md`（模板）+ `references/paths.local.md`（本机取值） |
| 本机个人经验 | `references/rules.local.md`（**优先级高于上游 rules.md**） |
| 样本记录 | `references/samples-db.md`（读 + 追加） |

## 四大类判定表（先定路线，再取模板）

**判定看「用户给什么 + 要什么」，不看素材本身**——同一张图，用户要"让它动起来"是图生视频，要"把里面的书换掉"是道具替换（属图生视频），要"照这段视频复刻动作"是参考生视频。

| 大类 | 判定信号（用户给什么 / 要什么） | 模板 | 关键差异 |
|---|---|---|---|
| **图生视频** | 给图（形象图/首帧/尾帧/四视图），无参考视频；要"让它动起来" | 模板 A / C2b | 图片是唯一锚。**道具替换**（例：换掉手里三本书）走这条 |
| **文生视频** | 什么都不给，只有一段文字 | 模板 F（**未验证：本机暂无样本**） | 全部靠文字描述（人物/场景/动作/镜头/风格都要写全），无锚定 → 一致性靠描述词逐字复用 |
| **参考视频生视频** | 给参考视频，要"照它的运镜/动作/节奏"生成新画面 | 模板 C | @视频1 = 运镜/动作/节奏；画面内容自己写 |
| **参考视频替换生视频** | 给原片 + 要"把里面的人/物换掉"，保留动作构图 | 模板 C1/C2、E | 锁机位构图与镜头节奏，只换表现层；难度分级与工具选型见 playbooks.md |
| （音乐二创/翻唱） | 给音乐，要卡点/配口型 | 模板 D | 参考视频类的特例，保留 |

配套口径：

- **分类由需求定，写什么由素材定**——不看素材既归不了类，也写不出提示词；素材必须逐项看清并归纳职责（哪份管形象/台词/音色/动作），识别手法见规则11、职责写法见规则30。
- **模型档位由用户选**，本 skill 只按字数估算预计秒数并提醒超限（规则17）。
- 每类的模板框架、示例与禁令见 `references/prompt-templates.md`；模型的输出/输入上限见 `references/platforms.md` 的「模型与限额」表。

## 工作流

### 0. 落位（每次新的提示词需求先判断是不是新项目）

**判断分流**：每收到一条新的提示词需求，**先判断是不是新项目**——
- **是新项目** → 走本节：先建框架（`文案/ 素材/ 成片/ 废片/ 评价/ 备注/`，交付提示词时再加 `平台上传/`），再动手写提示词；
- **不是新项目**（延续已有主题/同一支片子） → **沿用已有项目文件夹**，在其 `文案/提示词.txt` 追加版本、`素材/` 收素材，**不要另建目录**；
- 命名：**不带日期戳**；同一主题重开**依次加 1、2、3**（**「0」就是第一个、不写 0**：`三本书`、`三本书1`、`三本书2`）。

**换机 / 换 agent / 第一次用：先跑 `python tools\环境检查.py`**（逐项自检 ffmpeg/ffprobe、numpy/opencv、faster-whisper、onnxruntime、Yunet/Depth 模型、系统 OCR）；缺项**先问用户**，同意后 `python tools\环境检查.py --install --yes`（`--models` 补深度模型、`--warm-asr` 预下转写模型；两者都走国内模型镜像 modelscope.cn 优先、hf-mirror.com 兜底，不用挂代理）。**装软件必须用户同意，不许静默安装。**

同一轮问两句（固定话术）：

> ① 请问您要把项目建在哪里？您提供好素材后，我会自动将其进行归类
> ② 你主要用哪个平台做 AI 视频？即梦 / 小云雀 / updream

拿到回答后：

1. 建框架：`文案/ 素材/ 成片/ 废片/ 评价/ 备注/`（交付提示词时再加 `平台上传/`）；一条命令完成：`python tools\首次配置.py --project "<项目目录>"`。
2. 归类素材：口播稿→`文案/口播稿.txt`；提示词→`文案/提示词.txt`；参考图/产品图/音频/原片→`素材/`（保留原文件名）；并回报「文件名 → 去向」。
3. 处理平台：按 `references/platforms.md` 检测该平台 CLI——**有 CLI 且用户同意才装，没有就不装**；不检测账号、不代登录。结果记进 `paths.local.md`（`python tools\首次配置.py --platform 即梦 --cli dreamina`）。
4. 登记路径：项目库 = 项目目录的上一级（评分工具连接这一级），写入 `paths.local.md`。

用户没给明确位置就**再问一次**：不猜路径、不建默认目录。换平台时重问第 ② 句。

### 1. 分类（定模板）

> **默认轻流程（rules 第49条，2026-09-16 用户裁定 —— 先读这三行再动手）**
> 拿到素材**只做三件事**：①抽 4–8 帧看图，给素材定 role、**给上传的视频定类别**；
> ②读 `框架.json` 的 need 与文案稿，弄清要什么、说什么；③按统一骨架出提示词 + 跑体检。
> **静音、裁时长、转画幅/裁比例、转深度片、转写、OCR、全片运动量、抽帧拼图、去水印——全部不是默认步骤**，
> 命中 `rules.md` 第49条那张表的触发条件才做。默认预算：看图+读需求 1–3 分钟、出提示词 1–5 分钟；
> 超过 10 分钟先自查是不是掉进了"重加工"。**用户原话："这是一个很快的流程"。**

- **先按「四大类判定表」定路线**（图生/文生/参考生/参考替换），再取对应模板框架。
- **用户给的是"一条成片"、诉求是拆解/仿做/复现** → 走二创拆解流程（`references/playbooks.md` 第二部分 + `tools\成片拆解.py`）：先机器证据 → 读片三问（规则33）→ 出拆解报告；**报告先给用户，复现路线等他决定**，不要直接开写提示词。
- **按「用户的需求与台词文案」判断，不是按素材判断**：用户说"把视频里的人换成另一个人""复刻这段动作"→ 替换类/参考视频类；用户只给文案＋图/音频、没有要复刻的视频 → 生成类。**素材只是执行条件，不决定分类。**
  - **但「不决定分类」≠「不用看素材」**——两句话说的是两件事：**分类由需求定（走哪条路线、取哪套模板框架），写什么由素材定**。素材必须逐项看清并归纳出各自职责（哪份管形象/台词/音色/动作），这份总结直接决定提示词正文能写什么；**不看素材既归不了类，也写不出提示词**。识别手法见 rules.md 第11条，职责写法见第30条。
- **生成类提示词禁止出现「参考视频 / 视频1」**（rules.md 第10条）。**提示词里写到的每个 @图片N/@视频N 都必须真实上传过——以实际素材为准；传了视频就要逐帧查看**，其它素材也要逐项过一遍（识别先行，rules 第11条）。
- **用户没传素材时先分清两种情况**：①**延续同一个项目** → 沿用该项目上次的素材与提示词，不要另起一套；②**用户想先出基础素材**（如人物四视图先在即梦生成）→ 先把图片生成出来给用户挑选确认，**确认后再写视频提示词**。
- **时长只估不选**：模型档位由用户选；agent 只告知本条**预计多少秒**（超过用户所选档位上限才提醒一句）。估时两档口径：**口播带货切片＝快口播，按 5.5–6 字/s**（2026-09-28 用户裁定：约 85 字 15s 说得完，2.0fast 可试）；常规朗读、或拿不准语速时仍按 4.5–4.8 字/s 偏高估。

### 2. 产出（每条提示词、每个镜头单元都要满足）

| 硬项 | 要求 |
|---|---|
| **统一骨架** | **逐字用 `references/prompt-templates.md` 第 0 节那 11 个小节与顺序**（总纲 → 素材分工 → 主体 → 场景 → 道具 → 动作与时间轴 → 口播·音色·口型 → 镜头与景别 → 画面纪律 → 负面）＋元信息 3 行；**不许改名换序**（rules 第48条，2026-09-16 用户要求"风格一致"） |
| 负面词 | 每段写死：不要有任何字幕 / 全程绝对无运镜 / 无AI畸变 |
| 引用一致 | 出现的 @视频1/@图片1/@音频1 必须真实存在于本次上传素材；生成类只有「图片1 + 音频1」 |
| 动作-台词 | 动作前置、台词加引号、一行一组、一一对应；**每行标时间区间**（`0–3秒 …`，连续不跳变，末拍对齐总时长） |
| 多段 | 段间只写承接点（形象/背景/位置/持物）；描述句逐字复用第一段 |
| 时长 | 每段标注**预计时长**（只估算、不据此选模型） |
| **出完自检** | 跑 `python tools\提示词体检.py --project "<项目>"`，**有 FAIL 就改到没有为止**（只改格式、不为过检改内容） |

**替换类进门先看素材**（rules 第47条）：小动作素材（口播/拎盒展示，峰值运动量长期低于约 5% 画面）
→ 主版走**原片直投**，**别去转深度片**；大动作/影视素材 → 才上深度片信息过滤。
深度片在本机约 1.2–2 帧/秒（8 秒片 ≈ 6.5 分钟），**默认不装不跑**。

**提示词不是固定模板**：先定分类（图生/文生/参考生/参考替换；旧称生成类 A/B、参考视频类 C、替换类 L1–L4），再取对应模板框架（`references/prompt-templates.md`）；**骨架的小节名与顺序固定（第 0 节），模板只决定"每节写什么"**，硬项一条不省。
**画幅只作提醒**：提示词里的画幅句**不决定成片画幅**——交付时必须提醒用户「**请在平台上手选画幅**」（默认竖版 9:16，横屏/方屏按当次需求定；**不强制竖屏**。rules 第26条，2026-09-15 用户裁定提醒口径；本机若 `rules.local.md` 另有裁定，从其规定）。

### 2.5 要问用户的事，写进 `_会话/待确认.json`（2026-09-17）

**别在回执里跟用户聊天式提问**——回执落在执行记录里，用户基本不会翻（用户原话：
"agent 在执行记录给出了像对话一样的询问来确定意见，但是一般用户不会注意"）。
要把"用 a 还是 b""这两张图是不是同一个角色"这类问题**写进 `<项目>/_会话/待确认.json`**：

```json
[ {"q": "参考音频9 怎么用？", "hint": "a 声线克隆 / b 直接铺原声"},
  "四视图里是同一个角色吗？" ]
```

工作台会**弹窗**逐题收答案（③栏还有「待确认 N」胶囊随时能再打开），用户答完写回 `_会话/待办.jsonl`
（kind=反馈），**下一轮 agent 调用就会读到**。写不出文件时，退路是在回执**开头**用「❓待确认：」逐条列出。

### 3. 交付

1. **提示词正文**（按统一骨架写的整段，可直接粘贴）——**只写进 `文案/` 两处**（2026-09-21 用户裁定：
   不要在项目根再放一份，根目录只留 `框架.json` 与文件夹）：
   `文案\提示词.txt` = 完整交付（元信息 3 行 + 上传行 + 正文，**体检认这一份**）；
   `文案\提示词正文.txt` = **只有主版正文**（从【总纲】到【负面】，不含元信息/上传行/版本说明——
   ③栏显示与「复制提示词」用的就是它）。用 `python tools\project_core.py --project "<项目>" --assemble`
   可让程序从正文自动拼出完整交付那份（正文只写一遍）。
   交付前跑一次 `python tools\提示词体检.py --project "<项目>"` 并**贴出它的通过数**。
2. 素材清单（每文件路径 + 角色：形象参考/台词配音/音色参考/原片/产品图；这份放备注，不进正文）
3. 多段时附拼接说明（切点/承接点/跳切微调）
4. **硬性要求：交付完必须把评分工具弹出来**——这是交付动作的一部分，不是可选项；不许只留一句「记得打分」就算完。
   - 起法（agent 自己起，别让用户去找）：`tools\score_gui.cmd`（双击等价）；想打开就定位到某个项目 → `tools\dist\score-tool.exe --sample "<项目名关键词>"`。
   - 没打包过 exe 的机器：`score_gui.cmd` 会自动改用 pythonw 起 `score_gui.pyw`；要用现成工作台就到 Release 下载 v0.4.1 完整安装包（双击即装）。
   - 窗口用法：选样本 → 选成片 → 六维/违禁项逐项点分 → 五星 + 结论 + 备注 → **保存评分**（也可 `Ctrl+S`）。
   - 可换主题（浅色 / 深色 / 莫兰迪 / 护眼绿 / 暗夜），选过的主题自动记住。
   - **没保存就关窗会被拦**：弹「还有没保存的评分」，给「返回继续 / 直接关闭 / 保存并关闭」三个选择。
   - 写出的 json 与命令行版 `tools\评分.py` **完全等价**（同一份 `score_core.py`），`tools\评价回收.py` 照常回收。
   - 固定话术：「成片出来后，用刚弹出的评分窗口打一下分（六维+违禁项+结论），保存后我会读这份 json 更新规则，并问你要不要继续优化 skill」
   - 命令行版（备选，无图形环境时用）：`python tools\评分.py`（`--list` 清单 / 问答式打分 / `--show` 看历史）。
   - 旧网页版 `评价工具.html` **不再作为常规路径**（已被 exe 取代），仅在图形界面完全起不来时兜底。
4b. **硬性要求：提示词一出来，先把「素材投放 · 建框架」弹出来**——收素材与建框架已从"agent 手工 mkdir + 聊天来回确认"搬进工具（同一个 exe 的第二个用途）。
   - 起法：`tools\dist\score-tool.exe --material`；双击 `tools\score_gui.cmd` 后点左下角「素材/框架」等价。
   - 一步到位带参：`--root "<项目库>" --name "<实验名>" --add "<素材1>" "<素材2>"` → 自动建框架（同名自动加序号 1/2/3）并把素材归类进 `<项目>/素材/`。
   - 无图形界面时的等价命令行：`python tools\project_core.py --root "…" --name "…" --add "…" --json`（可解析输出）。
   - 它产出 `<项目>/框架.json`（机器读）+ `<项目>/框架.md`（人读）：字段含 相对路径 / 类型 / 宽高 / 时长 / 体积 / hash / 备注，**agent 后续直接读它，不要再逐个问用户"这是什么素材"**。
   - **不要让用户手选分类**：落进「素材/」即归类（rules.md 第264–272 条）；要细分就加备注，别加目录。
   - 素材是**复制**进项目（不是引用），便于整包发给用户；同名不覆盖、按 hash 判重。

5. **回收与优化（保存后必做）**：跑 `python tools\评价回收.py` → 有新的就按《反馈优化循环》更新 `rules.md`/模板/`samples-db.md` → `--mark-all` 记账，并回报改了什么、问用户要不要继续优化。

### 3b. 与程序的联调（**项目文件夹就是接口**）

程序（`tools\dist\score-tool.exe`）与 agent 不互相调 API，各自读写同一个项目目录：
`<项目>/_会话/{状态.json, 待办.jsonl, 回执.jsonl, 轮次/}`。全文见 `tools\联调说明.md`。

**agent 侧每轮必做（按顺序）**：

1. **先读待办**：`python tools\project_core.py --project "<项目>" --todos`
   —— 有 open 的 `反馈`，就是用户又要改一版，**先处理再交付**；反馈原文在 `_会话/轮次/*-反馈.txt`，别只信对话转述。
2. **扫项目出提示词**：读 `框架.json`（素材清单带 `role`）+ `文案/`（用户给的需求）+ `素材/`，
   按规则出提示词 → 写回 `框架.json` 的 `prompts`、`文案/提示词.txt` 与 `文案/提示词正文.txt`
   （**不要往项目根写**，2026-09-21 起提示词只出现在 `文案/` 里）。
3. **加工待上传副本**：按引用编号放 `平台上传/`（`图片1_形象参考_xxx.png` 这种）；
   **一版东西多（几十个分段视频）时按版本分子目录**：`平台上传/v1 主推/`、`平台上传/v2 换服装/`，
   旧版保留（换回上一版能直接用）。**不再写 `上传说明.txt`**（2026-09-21 用户裁定：没用，已废弃）。
4. **写回执**：`python tools\project_core.py --project "<项目>" --receipt "改了什么" --receipt-files 文案/提示词.txt --todo-done`
   —— 不写回执，界面上会一直挂着"待办 N"。
5. **起程序**（硬性要求，不许只在回复里说一句"请打开工具"）：
   `tools\dist\score-tool.exe --project "<项目>"`。程序是单实例：已在跑就提到前台并切到该项目，没跑就新开。
6. 用户看完提示词去平台生成 → 把成片/废片丢给程序 → 程序弹反馈窗 → 用户提交 → 回到第 1 步。

**程序也能主动叫 agent**：用户在界面点「提交并让 agent 再出一版」时，程序会调
WorkBuddy 的 headless CLI（`tools\agent_bridge.py` 封装，已自动避开端口冲突、会话钉在项目上）。
也就是说**两边都能发起一轮**，不必等对方在线——状态全在磁盘上。

## 反馈优化循环（每次拿到反馈完整走一遍）

| 来源 | 采集方式 |
|---|---|
| 六维评价 | 样本目录 `评价/*.json`（评分工具窗口版产出） |
| 用户口头反馈 | 对话里的效果判断原话（「口型对不上」「这条成了」） |
| 废片原因 | `废片/` 文件名（废因） |
| 对照分析 | 提示词 vs 成片的生效/失效对照 |

固定四步：

1. 判新规律还是重复确认：新规律 → 追加/修订 `rules.md`（写明日期与依据；跨机通用的写上游，本机个人经验写 `rules.local.md`）；重复确认 → 只加一次「再次验证」标记。
2. 模板导致的问题改模板，不加新规则。
3. `references/samples-db.md` 对应样本追加记录（成片评价/废片/反馈摘要）。
4. 回复用户列出本次改了什么、为什么，并询问是否按此反馈继续优化 skill。

**优先级**：用户当次指令 > `rules.local.md` > `rules.md` > 模板 > 推断。
**提炼时机**：同一现象 ≥2 次且因果明确 → 升为「已验证规律」；只出现 1 次 → 先记「待验证」。

## 兼容与维护

- **改完规则先跑回归**：`references/eval-cases.md`（真实用例 + 逐条断言，改 `rules*.md`/`prompt-templates.md` 后照它跑一遍；真实失败案例就补一条用例）。方法学抄自 ModelScope《skill-creator》：**造测试题 → 跑一遍 → 逐条断言 → 按结果改**，不靠"我觉得这样写更好"。
- **模型与限额只有一个真相源**：`references/platforms.md` 的「模型与限额」表。模型或限额有变动时**只改那张表**；rules 与模板只引用，不写死数字。
- 本机经验只写 gitignored 文件：`paths.local.md`（路径/平台）、`rules.local.md`（个人规则）、`eval-absorbed.local.json`（评价账本）→ `git pull` 永不与本地冲突。
- 上游 `version` 变大：更新后自检 `python tools\首次配置.py`（无参）、`python tools\评价回收.py`、评分工具能弹出（`tools\score_gui.cmd`）；`rules.local.md` 与上游新规则冲突时**以本机实测为准**并提示用户。
- 文件写作规范：只写「规则 + 依据（日期/来源）」，不写推理过程、情绪化措辞或口语复盘。
- 仓库协作与发布约定见仓库根 `AGENTS.md`；安装/换机见 `README.md`。


## 工作台（HTML 界面）与部署

- **界面**：主界面是 HTML 工作台（界面与本地服务，pywebview 独立窗口，
  内嵌 WebView2；不依赖用户的浏览器）。四栏＝①项目 ②素材 ③分镜/提示词 ④评分；顶部流程条五步可点、
  可上/下步、当前阶段那一栏会高亮；③栏 agent 徽章可看/切 agent（红绿点）；右上角 7 套主题（默认「原版」）、
  「经典界面」可切回旧 Tk 界面（`--classic`）。**关窗口＝退出**。
- **流程指挥台**（右上「？流程指挥台」）：整条流程一张板子（**独立 HTML 页嵌进
  工作台**，不是弹窗）——五步各一张卡，写明"谁在做 / 现在什么状态 / 这一步怎么做"，卡上的按钮**当场就能执行**
  （选素材 · 建框架 · 素材与需求识别 · 出提示词 · 复制提示词+清单 · 收成片 · 收废片 · 去打分 ·
  提交反馈 · 评价反哺 skill）。板子只画界面，动作仍由 `app.js` 的同一套函数执行（不留两份实现）。
- **四栏口径（2026-09-16 用户裁定）**：
  - ①栏：「＋ 新建项目」给一张白纸（空素材、空提示词，`register=False` 不动全局项目库）；
    项目行的**删除**给两个选择（2026-09-16 用户要求）：**扔进回收站**＝Windows 系统回收站
    （ctypes 调 `SHFileOperationW`，`FOF_ALLOWUNDO`；回收站用不了时退回项目库的 `_已删除/`）·
    **永久删除**＝`shutil.rmtree`，界面上要点两次才执行（先"上膛"再确认）；
  - ①栏列表的**排序与主题都记住上次的选择**（2026-09-16 修）：存在本机偏好文件
    `workbench.local.json`（源码＝`tools/`、打包后＝**exe 旁边**，与 `agent_bridge.local.json` 同目录）；
    从前这份文件固定写在 `__file__` 旁边 → 打包后落进 `%TEMP%\_MEIxxxx`，关窗即删，用户看到的
    现象就是"每次打开都回到默认排序"（与 agent 配置那次同源的坑）。主题另存一份 localStorage
    只为首屏上色，**权威值在偏好文件**（localStorage 的域带端口，端口一变就丢）；
  - ②栏＝**文案 / 素材识别**：写用户的「简单需求」（落 `框架.json → project.need` + `备注/需求.txt`，
    agent 出提示词与素材识别都读它）+ 素材清单（角色 / 名称 / 大小，**可拖动排序、可单件移除**）。
    拖动排序改的是 `框架.json → materials` 的顺序——**这个顺序就是 @图片1 / @音频1 的编号顺序**；
    移除＝文件移到项目里的 `_已移除/`（不真删，能捞回来）。
    - **需求框右边只有一颗「素材与需求识别」**（2026-09-17 用户裁定按钮位置；2026-10-13 用户改名并改口径）：
      点它先**静默把需求存下**，再让 agent 逐件识别素材角色、**按「素材加工」清单把加工做完并归位
      `平台上传/`**（原话："在这一步直接对素材进行加工然后放到正确的文件夹，之后出提示词对着
      已经加工好的素材参考去出就行"）；需求框失焦也会自动存。
      这一栏不再有单独的「存」。
    - **「分镜字段」六栏**（2026-09-17 加，景别 / 运镜 / 光影 / 情绪 / 口播文案 / 字幕）：用户能直接拧的
      旋钮，填了存进 `框架.json → project.fields` + `备注/分镜字段.txt`，**agent 出提示词时必须按它写**
      （rules 第51条）；留空＝agent 自定，**不阻塞轻流程、也不许反问用户**。
    - 标题条上「素材仓」＝打开本机素材根目录（`paths.local.md → MATERIALS_ROOT`，没设过就引导选一次并记住）；
    - 拖进②栏的单个文件 **>100MB 当场拦下**，提示改用「选择素材」（那条只传路径，不搬字节）。
  - ③栏＝**提示词正文**：只放提示词（`框架.json → prompts` 或 `文案/*提示词*`），**文案稿不进这一栏**
    （2026-09-16 修：从前把 `文案/*.txt` 也算提示词，没出提示词时这一栏显示的是文案稿）。
- **给工作台提意见 ＝ 投递到维护者**（2026-09-17 定型，用户两次改口径后的最终版）：
  入口在①栏「设置 → 给这个工作台提意见」（顶部栏那颗已收进设置页）。提交后：
  ① 正文落 `<项目库>/_工作台反馈/<时间>-<类型>.md`（**不进 git、不进项目**、可追溯）；
  ② 服务器**打开本机投递页** `/wbfeedback/send?f=<文件>`（浏览器里），页面上有正文、
     一键 `mailto:z230410@126.com`、一键复制全文——**用户自己在浏览器里点发送**。
  **刻意不用的两条路**（都试过、都放弃）：服务器直发 SMTP（要在每台机器放发信凭据，
  而仓库是公开的）；让 agent 代发（依赖每台机器的 agent 有没有邮件能力）。
  换机要改收件邮箱：`workbench.local.json → feedbackMail`（默认 `z230410@126.com`）。
- **提交即入信箱 · 每轮先读**（2026-09-17 加，rules 第52条）：用户在④栏打分、收成片/废片、提反馈时，
  工作台把它记进 `<项目>/_会话/信箱.jsonl`，并**立刻**把「读信箱」那一轮叫起来
  （agent 正忙就排队，当前这轮跑完自动接上；水位记在 `_会话/信箱水位.json`，**跑成功才推进**）。
  此外**每一次** agent 任务的指令开头都会列出"你还没读的 N 条"。③栏有「待读 N」胶囊可看是哪几条。
- **看得见 + 刹得住**（2026-09-17 加，rules 第55条）：跑的时候进度条下面显示
  **"现在在做：ffmpeg.exe 已 3:20 · 转码/合成/抽帧"**（agent 自己拉起来的子进程，2 秒扫一次）；
  一旦出现额外加工类产物（深度/静音/裁剪/转写/拼图/水印…）就**报警并把「暂停」按钮点亮**。
  「暂停」= `taskkill /T` **连子进程一起停**（原先只 kill 父进程，深度视频会继续算），
  还能顺手写一句（弹窗里有预置句）——那句话进 `_会话/信箱.jsonl`，下一轮开头必然读到。
  **②栏还有一张「素材加工」可展开清单**（2026-10-06 清单制，存 `框架.json → project.allowExtra`，
  rules 55）：勾了哪项才允许做哪项（遮脸/静音/裁剪/转画幅/深度片/转写/OCR/抽帧拼图/去水印…），
  **一项都不勾＝只做识别与改名**（默认勾选＝抽帧拼图 + OCR + 裁剪，2026-10-13 起裁剪也默认）；
  清单外的加工只能写 `_会话/待确认.json` 来问用户。
- **对话默认续用同一个对话**（2026-09-17 加，用户要求"缩短生成时间"）：会话 id 存 `状态.json → agentSession`，
  丢了会从本项目 `_会话/agent记录/*.jsonl` 里捞回来；偏好里 `sessionMode` 可切「每轮新开」。
  **⚠️ 会话是"按 agent 各管各的"**（用户实测：项目里存着 ZCode 的 `sess_…`，切到 WorkBuddy 后拿去
  `--resume` → `No conversation found with session ID`，整轮白跑）：所以 `状态.json` 里同时记
  `agentSessionOf`（这条会话是哪家的），**换了家就不续**、直接新开一个（换回来还能续上）；
  老数据没记属主时会按"这份会话正文在哪个 agent 的目录里"认一次并补写。
  另外**续不上会自动兜底**：认出 `No conversation found` 这类"rc=0 但内容是 JSON 错误"的假成功 →
  清掉会话、改成新对话重跑一次，并如实报失败（不再把那段 JSON 当"agent 回来了"显示）。
  **上下文涨到 `HERONBO_COMPACT_MB`（默认 10MB）时会自动压缩一次**：让 agent 在**同一个会话**里把交接要点
  写进 `_会话/上下文摘要.md`（只写要点、不干活），然后清会话、本轮换新对话并带着这份摘要跑——
  等于把"新会话要重读全部技能"换成"读一份摘要"。压缩跑失败就沿用原会话，不卡住。
- **agent 干的活有四件**（都走 `POST /api/agent`，同一套进度/回执机制）：
  出提示词 · 按反馈重出一版 · **素材与需求识别**（软件只按文件名猜角色，靠 agent 复核；按清单加工并归位 `平台上传/`，
  role 写进回执）· **评价反哺 skill**（读 `评价/*.json`、废片废因、`_会话/回执.jsonl`，把可复用经验沉淀成
  `references/rules*.md` 的规则——④⑤两栏的产出必须回到 skill，闭环才成立）。
- **谁干活**：`agent_bridge.py` **按环境探测**——本机装了什么就认什么（WorkBuddy / Claude Code / Codex / ZCode / DSH / 豆包工作，界面**只列本机真正有的**，没装的收进折叠块，别在别人的电脑上显示他没装的 agent）——优先"把本技能装在
  自己名下且命令行可用"的那个；多个可用时首次会问用户一次并记住。**选择记在哪**见 `cfg_path()`：源码运行＝
  `tools/agent_bridge.local.json`，打包后＝**exe 旁边**的同名文件（界面的 agent 弹窗会把它显示出来）。
  2026-09-15 修过一个 bug：原先固定写 `__file__` 同目录，打包后那是 PyInstaller 的 `%TEMP%\_MEIxxxx`
  临时解包目录，程序一关连文件一起被删 → 每次重开都退回自动挑选（用户看到的现象是"agent 总是重置成
  workbuddy"）。**配置必须落在 exe 旁边，不能落在 `__file__` 旁边**——EXE 内其它写盘同理。
- **部署（新机最短路径）**：**双击仓库根的 `一键安装.cmd`**，或 `python tools\部署.py all --yes`
  —— 找 Python → 装依赖（**优先用仓库自带的离线 wheel**：`tools/_vendor/wheels/`，约 4 MB，免联网）
  → 接 agent 通道并**真跑一句最小任务验证"装完就能干活"** → 建桌面快捷方式 → **把工作台弹出来**。
  单项：`check|install|agents|shortcut|start|wx`。**装任何东西前不加 `--yes` 只打印命令**。
  图标：`python tools\图标.py`。**没打包 exe 也能用**：`python tools\工作台.py` 起源码版工作台。
  **依赖分两档**（2026-09-16：新机一次装几百 MB、用户反馈"装得慢"）：必需＝pywebview/pythonnet/clr_loader
  （离线包）；按需＝numpy/opencv/faster-whisper/onnxruntime（用到才装，`--extras` 一次装全）。
- **工作台界面白屏 = WebView2 运行库坏了**（2026-09-16 另一台机器实测：注册表写着装了某版本，但那个目录里
  `msedgewebview2.exe` 不见了，`msedge.dll` 还在）→ 现在三道防线：①起窗前 `webview2_state()` 预检
  （注册表版本 + 宿主 exe 是否真在），不可用就**根本不试独立窗口**、直接退 Edge；②**白窗看门狗**：25 秒内
  页面没连上来就关窗退 Edge 并写 `%TEMP%\heronbo_webview2.txt`；③`部署.py check` 里有「WebView2 运行库」一行。
  修：`python tools\部署.py wx --yes`（微软官方引导器，装前校验签名）。**这条不只影响工作台**——本机所有用
  WebView2 的程序都会白屏。整条新机流程见 `docs/新机部署.md`。
- **agent 通道与 node**：探测**不绑定某一家**，哪台电脑装了哪个就用哪个（明确选过 > 跟随正开着的客户端 >
  装了本技能的 > 任意可用）。**没有 Node.js 也能接 WorkBuddy / ZCode**——它们自带 Electron，加
  `ELECTRON_RUN_AS_NODE=1` 就是一个完整 node（ZCode.exe 实测报 v24.14.0）；Codex / DSH 才必须有 Node.js。
  ZCode 的 CLI 找法按"根目录 + 1~3 层通配"搜（能认出 `F:\新建文件夹 (3)\ZCode\resources\glm\zcode.cjs`
  这种多套一层的情况）；跑之前还会查 `~/.zcode/cli/config.json` 有没有 provider/model，没有就直说
  「先跑一次 zcode login」，别让用户"选了才发现跑不了"。
- **更新工作台**：普通用户在工作台点「检查更新」、或下载 v0.4.1 完整安装包重装；开发者重打 exe 用 `tools\打包换位.py`
  （换位会拦"工作台还开着"：exe 在跑的时候换，正在跑的实例可能莫名崩，2026-09-16 用 `mv -f` 硬换踩到过；
  被拦下就关掉工作台再换位，实在要硬换加 `--force` 并**手工关掉重开**那个实例）。
- **clone 用 `--depth 1`**（2026-09-16）：仓库历史里有历代 18 MB 的 exe，完整 clone 要下 70 MB+ 历史，
  浅克隆 20 MB 左右。新机照着 `docs/新机部署.md` 走。
- **图文教程**：`docs/工作台与新手教程.html`（内容与本节同步；改规则请改仓库文件，不要只改那份 html）。