情景教学视频生产线（Video Studio Playbook）
把一次成功的情景教学视频制作，抽象成七个阶段 + 四道闸门 + 一套校验脚本，使同一方法可复制到任何题材（科普、故事、课文、古诗、宣传片），并在长任务中不靠运气、不靠记忆、不靠反复试错。
定位：本技能是方法论 + 编排层；生成能力（文生图 / GEM TTS / metaso H3）由已安装的引擎 scenario-instruction-video__skillhub/scripts 提供。若引擎缺失或更换，本技能的模版与校验仍可用，只需改 --engine 目录。
何时使用
- 用户要「把某个题材做成带配音的教学视频」，且期望可复用、可复现；
- 已有分镜脚本/课文/知识点，需要落地成片；
- 需要复盘一次视频制作、把经验沉淀为团队模版；
- 长任务（>10 分钟、多段、多 API 调用）需要断点续跑与成本控制。
不适用：单张图、单条配音、纯剪辑。
铁律（违反必然返工）
- 先定分支，再写提示词。每段先判 A（纯旁白，画面闭口）/ B（角色开口，口型同步）。分支决定提示词骨架，写反了等于重做。
- 文本锁逐字复用。画风句 + 角色/场景锁定句在
plan.json的design_bible里定义一次，由脚本展开到每段；禁止手写、禁止同义改写、禁止残留{占位符}。 - 以声定时。视频时长由 TTS 实测时长决定（
clamp(round(sec), 4, 30)），不靠预估。 - 成品配音只用 TTS 原声。H3 重渲染的人声带混响，一律丢弃其音轨、后期混入 TTS 原声。
- 闸门前不推进。锚点图/静帧/音色未经用户确认，不进入批量生成——省下的不是时间，是返工。
- 一切都可续跑。每步产物落盘 + 状态文件记录；任何中断后
--stage重入只补缺失项。 - 密钥只走环境变量。不写进 plan、不写进日志、不回显；
preflight.py只报「已配置/缺失」。
七阶段 + 四闸门
| 阶段 | 动作 | 产物 | 闸门 |
|---|---|---|---|
| S0 需求门控 | 问清 6 件事：题材与受众、时长、分支（A/B/混合）、画风、音色、是否要封面/字幕 | 决策写入 plan meta |
闸⓪ 需求确认 |
| S1 剧本 | 分幕表：每段 画面 + 台词 + 时长 + 分支 | script.md |
用户改稿 |
| S2 文本锁 | design_bible：1 句画风 + N 条角色/场景锁定（英文，体型+服饰+特征三叠加） |
plan.json |
— |
| S3 锚点图 | 2~3 张角色四视图 + 主场景图 | stills/anchor_*.png |
闸① 形象确认 |
| S4 静帧 | 每幕一张静帧（提示词 = 场景句 + 锁 + 画风句） | stills/still_*.png |
闸① 同批确认 |
| S5 配音 | 每条台词 TTS → 实测时长回填 plan；音色先试听 | tts_out/*.wav |
音色试听 |
| S6 视频 | 逐段 H3：A 段音频关、B 段带参考音；失败重试 | h3/<key>.mp4 |
抽检 1~2 段 |
| S7 合成 | 封面蒙板 → 拼接 → 混音 → 烧字幕 | final.mp4 |
闸② 成片验收 |
各阶段命令与判定细节见 references/workflow.md。
快速开始（3 步）
# 0) 自检环境（缺什么给出修复命令；--fix 安装 python 依赖）
python scripts/preflight.py --plan plan.json --engine "$ENGINE"
# 1) 文本锁展开 + 占位符校验（残留 {xxx} 或锁定句漂移即失败）
python scripts/expand_locks.py --plan plan.json --check-only
# 2) 分阶段执行（幂等、可续跑、失败重试、成本估算）
python scripts/orchestrate.py --plan plan.json --engine "$ENGINE" --stage stills
python scripts/orchestrate.py --plan plan.json --engine "$ENGINE" --stage tts
python scripts/orchestrate.py --plan plan.json --engine "$ENGINE" --stage video
python scripts/orchestrate.py --plan plan.json --engine "$ENGINE" --stage assemble
# 3) 交付前体检
python scripts/qa_check.py --plan plan.json
ENGINE 默认 ~/.workbuddy/skills/scenario-instruction-video__skillhub/scripts。
脚本职责
| 脚本 | 解决什么 | 关键参数 |
|---|---|---|
scripts/preflight.py |
环境/依赖/密钥/plan 结构/中文路径/ffmpeg+ffprobe 体检，可自愈 | --fix --json |
scripts/expand_locks.py |
design_bible 逐字展开为每段提示词，消除占位符漂移 | --check-only --force |
scripts/orchestrate.py |
阶段编排：幂等、断点续跑、重试、成本与耗时估算 | --stage --only --dry-run |
scripts/qa_check.py |
成片体检：时长对齐、音轨存在、分辨率、文件完整性 | --strict |
scripts/run_batch.sh |
批处理执行器模板（规避超长复合命令被拦截/中断） | 见脚本内注释 |
模版：assets/plan.template.json（含 A/B 双分支示例）、assets/design-bible.example.json（四套画风锁）、assets/prompt-A.txt、assets/prompt-B.txt。
灵活响应原则（题材变了，骨架不变）
- 只换 design_bible 与剧本，不动流水线。写实纪实 / 绘本卡通 / 水墨 / 水彩四套锁见
references/prompt-recipes.md。 - 时长不确定就先出试听：一遍 TTS 比一次返工便宜。
- 角色 >3 或换场频繁：把「同场角色」拆成独立段，降低单帧一致性压力。
- 用户临时改画风/音色：只重跑
--only <key>受影响段，不重跑全片。 - 引擎不可用：
--engine指向自定义目录，plan 格式不变。
经验与教训
实战踩坑清单（沙箱拦截复合命令、占位符未展开、ffmpeg/ffprobe 缺失、时长错位、分支写反、密钥落盘风险等）见 references/lessons.md；验收细则见 references/qa-checklist.md。开工前读 lessons，收工前跑 qa_check。
