视频制作工作流
这是此仓库中唯一的新视频制作工作流。video-director负责最终的成果和状态。对于研究和写作技巧，请参考.claude/skills/viral-tech-video-creator/SKILL.md；对于镜头、动作和声音参考，请参考.claude/skills/video-shotcraft/SKILL.md。当这些资源与本文件冲突时，以本文件为准。开始工作前请先阅读CLAUDE.md和选定的参考资料。回复请用越南语；代码用英文编写。
工作流是完全自动化的：智能体自己进行制作、审核并通过门控，没有步骤等待用户手动批准。绝不要在回合或智能体报告的结尾使用“gửi bạn nghe thử / duyệt giúp / OK chưa”；选择最佳选项，将决定记录在docs/<vid>/中，然后继续。仅在缺少关键输入且无法安全推断时，或用户明确请求决策门时，才询问用户。人工听审（音频、最终MP4）是可选的记录，绝不是问题或阻塞。独立审核员使用干净的上下文。仅保留用户标记为强制要求的用户台词原样；其他所有内容可以为了服务于故事而进行戏剧化处理或重写（参见常见失败点中的gate-A教训）。发布需要单独的用户请求。
精简模式。 对于较短的story视频，或者当用户提供了脚本/语音时，导演可以合并步骤但不跳过任何门控：一个research-agent；当用户账户是来源时，不生成研究文件；三个Phase 3分支在一个并行消息中；task-planner搭配每3-4个镜头一个scene-agent。门控A、D、E、B、C、内容和音频分支审核、修复循环纪律以及文件所有权始终保留。
流水线图
在门控A之后，工作分叉为三个并行分支（内容、音频、设计），每个分支都有自己的制作人→独立上下文审核员循环。当三个分支都通过后，video-director将它们合并，门控E在构建前审核合并后的计划。
flowchart TD
P0["0 接收<br/>intake-agent ×2-3"] --> P1["1 研究<br/>research-agent ×N"]
P1 --> P2["2 脚本<br/>script-agent"]
P2 --> A{"门控 A ≥ 9<br/>script-reviewer"}
A -- "修改 (≤3轮)" --> P2
A -- 通过 --> FORK(("分叉"))
subgraph BR["3 · 三个并行分支"]
direction LR
subgraph B1["3a 内容"]
CA["content-agent<br/>content-pack.md"] --> CR{"content-reviewer ≥ 9"}
CR -- 修改 --> CA
end
subgraph B2["3b 音频"]
VA["voice-agent + audio-agent<br/>sN.mp3, BGM/SFX, 混音计划"] --> AR{"audio-reviewer ≥ 9"}
AR -- 修改 --> VA
end
subgraph B3["3c 设计"]
DA["design-agent<br/>原型, 风格帧, 封面, 故事板"] --> DR{"门控 D ≥ 9<br/>design-reviewer"}
DR -- 修改 --> DA
end
end
FORK --> CA
FORK --> VA
FORK --> DA
CR -- 通过 --> J
AR -- 通过 --> J
DR -- 通过 --> J
J["4 合并<br/>video-director: voice.json, timeline.ts,<br/>协调时间/文本/氛围"] --> E{"门控 E ≥ 9<br/>integration-reviewer"}
E -- "工单 → 所属分支" --> BR
E -- 通过 --> P6["6 任务<br/>task-planner"]
J -.->|早期脚手架| P7
P6 --> B{"门控 B ≥ 8<br/>task-reviewer"}
B -- 通过 --> P7["7 构建<br/>scene-agent ×N"]
P7 --> P8["8 质量保证<br/>qa-agent ×N"]
P8 --> P9["9 渲染<br/>render-agent"]
P9 --> C{"门控 C ≥ 8 · 最终屏障<br/>在MP4上完整重新测试<br/>final-check.md 全部 ✓ + video-reviewer ×3"}
C -- "修复 → 负责人, 重新渲染, 重新测试所有内容" --> P7
C -- 通过 --> P10["10 交付<br/>video-director"]
文本后备方案：0 接收 → 1 研究 → 2 脚本 ⇒ A → 分叉[ 3a content-agent ⇒ content-reviewer | 3b 语音+音频 ⇒ audio-reviewer | 3c design-agent ⇒ D ] → 4 合并 → E → 6 任务 ⇒ B → 7 构建 → 8 质量保证 → 9 渲染 ⇒ C → 10 交付。
约定与命名
- 一个视频有一个唯一的、小写的kebab-case主题ID
<vid>，一个语音slug<voice>，docs/<vid>/，src/<vid>/，public/audio/<vid>/，和out/qa/<vid>-*.png。 - 唯一的最终视频是
out/<vid>-<voice>-reel.mp4，例如out/cam-on-phien-ban-minh-anh-khoi-reel.mp4。语音slug描述的是实际听到的语音。当语音更改时，在渲染前运行python3 -I scripts/pipeline.py voice <vid> <new-voice>；先前的文件仍然可用。 - 首先运行
python3 -m unittest scripts.test_voice_catalog以确保目录预览能够解析。根据目录描述和用户请求，从vietnamese-voice-samples/previews/中选择一个候选（该文件夹就是目录；文件名是简短的语音名称），并在brief.md中记录提供商及其语音ID。预览本身不授予任何商业或克隆权利。 - 在Phase 0的重复主题检查通过后，初始化一次：
python3 -I scripts/pipeline.py init <vid> --comp <CompId> --voice <voice> --profile story|product|knowledge|news。--voice对于新制作是必需的：传递当前的最佳猜测，然后在路线确定后尽快运行pipeline.py voice <vid> <slug>（slug必须命名实际听到的语音）；--out仅用于遗留的输出名称。在分派制作智能体之前，启动或重用端口4180上的Pipeline Monitor。不要手动编辑status.json。 - 在每个工作阶段前后，调用
pipeline.py set <vid> <stage> in_progress，然后是done，blocked，或failed。阶段包括research, brief, script, content, voice, design, build, audio, qa, render（content从工作流v3开始存在，由init创建；一个已在进行的、仅有门控A审核的v2视频，通过pipeline.py upgrade <vid>移至v3）。render命令会更新自己的阶段。审核门控按顺序运行 A → [content · audio · D] → E → B → C；两个分支审核像门控一样记录（review <vid> content|audio …，gate <vid> content|audio，上限3次override），并且门控E会拒绝，直到content、audio和D都被接受。门控A、content、audio、D和E通过分数为 9/10，B和C为 8（pipeline.py强制执行分数）。 - 智能体活动（驱动监控器）。 每次
video-director分派一个智能体时，运行pipeline.py agent <vid> <agent-name> running --stage <stage> --note "<task>"；当其完成通知到达时，运行pipeline.py agent <vid> <agent-name> done（或failed）。并行副本使用编号名称（scene-agent-1，research-agent-2）。没有这些记录，监控器只能根据阶段状态进行猜测，并且审核员永远不会亮起。一个门控只有在分数达到阈值且没有打开的Cao/Trung工单时才通过（参见修复循环纪律）；pipeline.py无法看到工单，因此审核员在任何工单打开时设置--verdict revise。
| 阶段 | 要设置的阶段 | 门控/检查点 |
|---|---|---|
| 0 接收 | — (init) | — |
| 1 研究 | research | — |
| 2 脚本 | brief, script | A |
| 3a 内容分支 | content | 审核 content (content-reviewer) |
| 3b 音频分支 | voice, audio | 审核 audio (audio-reviewer, 机器判定) |
| 3c 设计分支 | design | D |
| 4 合并 | — (导演集成) | — |
| 5 集成 | (修复时重新打开所属阶段) | E |
| 6 任务 | build → in_progress | B |
| 7 构建 | build, audio (混音集成) | — |
| 8 质量保证 | qa | — |
| 9 渲染 | render (自动) | C (人工听审 = 可选记录) |
重新打开一个阶段（in_progress/blocked/failed）会使以下审核失效：research/brief/script → A（以及两个分支审核），content → 审核 content + E及之后，voice → 审核 audio + E及之后，design → D及之后，build/audio/qa/render → C。一个新的审核条目也会使其之后的所有内容失效（一个分支审核会重新打开E、B、C）。按顺序重新运行每个失效的门控。
- 不同的视频可以使用不同的ID、音频文件夹、质量保证前缀和输出同时运行。处理一个视频的智能体拥有不相交的场景文件；只有
video-director编辑kit、timeline、Reel、Root和语音JSON。流水线将写入序列化到一个状态和一个输出名称。
智能体名册与交接
video-director 是流水线所有者和信息管理器：它初始化状态，将当前的简报/脚本/来源决策作为唯一真实来源，选择配置文件，分配文件，集成工作，运行门控命令，并交付结果。为每个专家提供已接受的简报、精确输入、预期输出路径和验收检查。在交接时，video-director 检查返回的工件是否与这些输入匹配，将决策或未解决的问题记录在 docs/<vid>/ 中，更新状态，并仅向下一专家提供已接受的版本。审核员必须拥有干净的上下文，且不能是产生它评分工件的智能体。video-director 不为自己的工作评分。
video-director 是主要对话线程（您），而不是子智能体。它管理下面的每个智能体：分派、移交已接受的输入、路由修复、集成共享文件、记录状态/门控，并与用户交谈。每个阶段由其各自的命名智能体运行；审核智能体是独立的、拥有干净上下文的，并且每轮都是新的。
| 阶段 | 制作智能体 | 审核智能体 (门控) | 拥有并返回的内容 |
|---|---|---|---|
| 0 接收 | intake-agent (只读) | — | 重复主题报告，预检结果；导演写入 brief.md 头部；仅在关键输入缺失时询问用户 |
| 1 研究 | research-agent (按来源组 × N) | — | research.md 或 research-<group>.md: 来源、受众语言、事实/推断/未知、五个钩子候选 |
| 2 脚本 | script-agent | script-reviewer (A) | brief.md, script.md, voice.proposed.json / script-review.md |
| 3a 内容 | content-agent | content-reviewer (分支) | content-pack.md: 每个镜头的屏幕文字、字幕块、重音词、封面/再钩子/行动号召文本、主张→来源表、minh hoạ 标签 / content-pack-review.md |
| 3b 音频 | voice-agent + audio-agent | audio-reviewer (分支, 机器判定) | sN.mp3 + 时长 + 自动语音识别 (voice-report.md); BGM/SFX + 节拍网格 + 混音计划 + assets-manifest.md / audio-review.md |
| 3c 设计 | design-agent | design-reviewer (D) | design-spec.md + 原型 + 3个风格帧 + 封面 + 故事板 + 钩子动作条 / design-review.md |
| 4 合并 | video-director | — | voice.json, timeline.ts 草稿, docs/<vid>/join-notes.md (时间/文本/氛围协调) |
| 5 集成 | (修复指向所属分支制作人) | integration-reviewer (E) | integration-review.md, 在完整构建前进行判定 |
| 6 任务 | task-planner | task-reviewer (B) | task-review.md: 工具, 镜头→文件所有权, 依赖关系, 检查 |
| 7 构建 | scene-agent-1..N (并行, 每个一个文件) | — | src/<vid>/scenes*.tsx + 静帧；导演集成 timeline/kit/Reel/Root/音频 |
| 8 质量保证 | qa-agent | — | qa-report.md: TypeScript编译, 确定性, 帧/转场/字幕检查, 每个镜头设计保真度评分, 修复路由到负责人 |
| 9 渲染 | render-agent | video-reviewer (C, 最终屏障) | 已验证的MP4 + final-check.md (在MP4上的完整回归测试) + render-evidence.md (联系表, 密集帧, 响度, 自动语音识别) / video-review.md |
| 10 交付 | video-director | — (人工听审 = 可选记录) | 导演运行 check 并编写交付报告 |
只有 video-director 写入共享的 kit、timeline、Reel、Root 和 voice.json；专家在其交接中提议对这些文件的更改。场景智能体从视频的 SHOTS 映射中读取时长，并将动作锚定到测量的语音跨度。切勿将同一个可写文件分配给两个智能体。如果用户停止工作，也停止后台智能体。门控C是对联系表、密集帧、ffprobe/响度数据和自动语音识别的人工智能审核；C之后的人工听审（pipeline.py listen）是可选的记录，不是交付阻塞。
速度规则：默认并行分派
video-director 必须在工作允许的情况下尽可能多地并行分派子智能体，以便视频尽可能快、尽可能好地完成。一步一步地运行本可以一起运行的步骤是一个缺陷。
- 在一个消息（一个工具块）中发送所有独立的智能体调用，绝不要每轮一个。
- 只要输入被接受且可写文件不重叠，就进行并行化：
research-agent× N（每个来源组一个）；三个Phase 3分支（content-agent，voice-agent+audio-agent，design-agent）一起；scene-agent× N（每个一个文件和一个镜头ID列表）；qa-agent按镜头集群拆分；工作流/技能/文档修复与视频工作同时进行；同一轮中独立修复路由到不同的负责人。 - 独立阶段并行运行（阶段图）：
- Phase 0：
intake-agent检查（重复主题、工具预检、语音目录测试）在一个消息中；Phase 1：所有research-agent来源组。 - Phase 3：A通过后立即在一个消息中发送所有三个分支制作人。然后每个分支独立地在自己的制作人和审核员之间循环：一个通过的分支在合并点等待，而其他分支继续修复；一个分支绝不等待另一个分支的审核。
- Phase 5–6：
task-planner在E审核的同时起草计划和scene-agents 构建早期脚手架；B审核等待E通过（如果E更改了任何内容，计划会改变）。 - Phase 7：
scene-agent× N 处理不相交的文件；Phase 8：qa-agent处理每个镜头集群和静帧渲染；Phase 9：联系表、密集帧、响度和自动语音识别证据同时计算。 - 修复轮次：针对不同负责人的工单在一个消息中发出。审核可以并发运行，但导演记录分数并严格按顺序运行门控A → D → E → B → C（
pipeline.py强制执行），如果较早的门控重新打开，则较晚审核员的结果无效。
- Phase 0：
- 仅在存在真正依赖关系时保持顺序： 门控A → D → E → B → C（审核员需要其工件完成），依赖先前审核的修复轮次，以及任何具有单个所有者的文件（
kit，timeline，Reel
…
[为翻译而截断]