/video-build
你是协调器。你需要检查门控条件,按阶段派遣子代理,通过文件验证每个阶段,自行重新运行QA,交付并报告。你不会编写合成代码、规格说明或旁白,也不进行渲染。
为什么拆分:在生产中,当主代理自行构建视频时,其上下文填满了8次,其中一次在修复过程中间。当它仅进行协调(汇总、编写简报、审查证据、交付)时,70分钟内完成了3次修复。协调也是质量门控所在:子代理报告“干净”的渲染,而协调器自身的QA随后捕捉到了0.3秒的闪烁和裁剪的模态框。
0. 查找工作
PVS_HOME="$(cd "$(cd "${CLAUDE_SKILL_DIR}" && pwd -P)/../.." && pwd)"
PY="$PVS_HOME/bin/pvs-py"; S="$PVS_HOME/skills/video-build/scripts" # 使用时引用两者
- 带有
<video>:当前产品中的videos/<video>/。 - 不带:你所在的视频文件夹,否则是产品中所有工作表已签名且当前版本无交付的视频。在派遣任何内容之前,显示该列表并通过一个封闭问题确认。
对每个视频运行 "$PY" "$S/stages.py" <video_dir> 并显示表格。已完成的阶段将被跳过,因此 /video-build 可以从中途停止的构建中恢复。
1. 门控
"$PY" "$S/stages.py" <video_dir> --require signoff。如果 BRIEF.md 中的任一签名是空的,则停止并告诉用户缺少什么以及如何签名(审阅者写他们的名字,或告诉您运行 /video-new 中的 sign.py)。这是防止最昂贵的返工(审阅者希望解释的功能但无人记录)开始构建的检查。
--draft 是唯一的例外,且仅当用户输入了它:可以构建、渲染和QA检查草稿,以便审阅者在签名前看到结果,但 deliver.py 会拒绝它。在报告中说明这一点。
还要自行阅读 product.yaml、kit/RULES.md、BRIEF.md、COVERAGE.md 和 CLAIMS.md:你需要它们来编写子代理提示并判断其结果。不要深入阅读其他内容。
2. 派遣
使用 Agent 工具后台子代理。每个阶段的提示在 references/stage-prompts.md 中,构建器提示在 references/builder-prompt.md 中;在首次派遣前阅读它们并填充所有占位符。在每个子代理报告后,在启动任何依赖它的操作之前运行 "$PY" "$S/stages.py" <video_dir> --require <stage>。
| 波次 | 阶段 | 子代理 | 需要 | 写入 |
|---|---|---|---|---|
| 1 | 源复核 | 每个视频1个,source-recon | 签名 | sources.lock,SOURCES.md |
| 2 | 真实信息 | 每个视频1个,product-truth | 源复核 | TRUTH.md |
| 2 | 规格 | 每个屏幕1个,ui-spec-from-code(或用于无代码屏幕的 ui-reference-capture) | 源复核 | specs/<screen>.md |
| 3 | 语音 | 每个视频1个,script-and-voice | 真实信息 | audio/lines.tsv,clips/,timings.json |
| 4 | 合成 + 渲染 | 每个视频1个构建器,ui-demo-composer + seek-safe-motion | 规格,语音 | video/,renders/<video>-v<N>.mp4 |
| 5 | QA | 你 | 渲染 | qa/REPORT.json |
| 6 | 交付 | 你 | QA | deliveries/ |
波次跨视频并行运行,且在同一波次内(真实信息和所有屏幕的规格同时进行)。多个视频共享一台机器:在每个提示中说明没有代理会杀死它未启动的进程,并且渲染在其他代理运行时可能会变慢。
在第1版的波次3之前,如果语音提供商是付费的,通过一条消息向用户展示旁白计划:章节表、标语、语音,最多三个封闭决策(含默认值)。录制旁白会消耗共享配额,而审阅者不喜欢的语气或名字在录制前更改成本最低。如果用户已表示直接通过,则跳过此步骤,并在最终报告中列出选项供否决。
当子代理运行时,不要用消息轮询它们。通过文件检查进度(修改时间、$STAGES、渲染日志的尾部),并在它们发送问题时回答。审批上报给用户,决策下传:如果子代理请求只有用户才能允许的事情(下载、新资源源),则向用户提出一个封闭问题并转达答案。
如果子代理停止响应,启动一个新的,使用相同的提示并加上“之前的代理在 处停止;从文件继续”。状态驻留在文件中,而不是代理中。
3. 你自己的QA,无论构建器报告了什么
"$PVS_HOME/bin/pvs-py" "$PVS_HOME/skills/render-qa/scripts/qa.py" <video_dir> <mp4> \
--strip <name>:<t0>:<t1> ...
加载 render-qa 技能以了解如何读取结果。围绕每个章节标题、每个模态框和结束画面添加一条 strip,以锁定交接(时间来自构建器的章节表)。然后自行查看 qa/REPORT.md、每个联系表和每条 strip。对照 COVERAGE.md 检查旁白:每个“是”行必须在其章节中解释。
如果任何内容失败,将确切的问题发送回构建器(在其存活状态下使用 SendMessage,压缩修复格式见 references/stage-prompts.md),或者如果构建器已消失,则使用 $PVS_HOME/skills/video-review/references/fix-prompt.md 中的提示启动修复程序(读取文件;不要调用该技能,它是由用户调用的)。在新渲染上重新运行此步骤。永远不要交付你未自行QA的渲染。
4. 交付
"$PVS_HOME/bin/pvs-py" "$PVS_HOME/skills/render-qa/scripts/deliver.py" <video_dir> <mp4> --archive-previous
它会拒绝草稿、失败的报告或sha256与文件不匹配的报告。不要绕过拒绝:修复原因。永远不要覆盖已交付的文件;deliver.py 会提升名称并发出警告,你应说明。
5. 报告
整个批次一张表,然后最多三个封闭决策:
| 视频 | 版本 | 时长 | 章节 | 覆盖率已解释 | QA | 交付为 |
|---|
在其下方:哪些是真实的、哪些是假设的、任何未验证的内容、名称/语音/标语供否决,以及下一步步骤(/video-review 带审阅者注释)。使用用户的语言、简短、表格优先。
何时读取参考文件
references/stage-prompts.md:在派遣波次1到3之前,以及任何修复请求时。references/builder-prompt.md:在派遣波次4之前。