HeronBo-AIGC-Prompt

AI 视频提示词生成

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

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

职责边界

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

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

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

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

配套口径：

• 分类由需求定，写什么由素材定——不看素材既归不了类，也写不出提示词；素材必须逐项看清并归纳职责（哪份管形象/台词/音色/动作），识别手法见规则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 预下转写模型）。装软件必须用户同意，不许静默安装。

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

① 请问您要把项目建在哪里？您提供好素材后，我会自动将其进行归类 ② 你主要用哪个平台做 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 只按"字数 × 4.5–4.8 字/s"告知本条预计多少秒（超过用户所选档位上限才提醒一句）。

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

替换类进门先看素材（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：

[ {"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；要 exe 就跑 python tools\部署.py vendor --fetch --yes 拿官方 exe（Release 附件）。
   • 窗口用法：选样本 → 选成片 → 六维/违禁项逐项点分 → 五星 + 结论 + 备注 → 保存评分（也可 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 封装，已自动避开端口冲突、会话钉在项目上）。 也就是说两边都能发起一轮，不必等对方在线——状态全在磁盘上。

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

固定四步：

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 页嵌进 工作台，不是弹窗）——五步各一张卡，写明"谁在做 / 现在什么状态 / 这一步怎么做"，卡上的按钮当场就能执行 （选素材 · 建框架归类 · 让 agent 核对归类 · 出提示词 · 复制提示词+清单 · 收成片 · 收废片 · 去打分 · 提交反馈 · 评价反哺 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 用户裁定："把归类按钮放到存这个位置，存这个按钮不要了， 两个按钮重复了"）：点它先静默把需求存下，再让 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，下一轮开头必然读到。 ②栏还有一颗「不许额外加工」开关（存 框架.json → project.forbidExtra）：勾上就是硬约束， agent 一个加工动作都不许做，非做不可只能写 _会话/待确认.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 复核并写回 框架.json）· 评价反哺 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 找法按"根目录 + 13 层通配"搜（能认出 F:\新建文件夹 (3)\ZCode\resources\glm\zcode.cjs 这种多套一层的情况）；跑之前还会查 `/.zcode/cli/config.json` 有没有 provider/model，没有就直说 「先跑一次 zcode login」，别让用户"选了才发现跑不了"。
• 打包替换 exe（2026-09-16 加）：python tools\部署.py vendor --fetch --yes（从 Release 拿官方 exe，换到 tools\dist\score-tool.exe， 自动留一份 score-tool_旧_*.exe 回滚）。换位工具会拦"工作台还开着"：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）。