影片製作工作流程
這是此儲存庫中唯一的影片製作工作流程。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 voice+audio ⇒ 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（從工作流程 v3 開始存在content階段，init會建立它；正在進行中的 v2 影片（僅通過關卡 A 審查）會使用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。
| Phase | 要設定的階段 | 關卡 / 檢查點 |
|---|---|---|
| 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、音訊資料夾、QA 前綴和輸出同時執行。處理同一個影片的代理程式擁有互斥的場景檔案；只有
video-director可以編輯kit、timeline、Reel、Root和語音 JSON。此管道會序列化對一個狀態和一個輸出名稱的寫入。
代理程式名冊與交接
video-director 是管道擁有者和資訊管理者：它初始化狀態、將當前的簡報/腳本/來源決策作為唯一真理來源、選擇設定檔、分配檔案、整合工作、執行關卡命令，並交付結果。為每個專家提供已接受的簡報、確切輸入、預期輸出路徑和驗收檢查。在交接時，video-director 會根據這些輸入檢查回傳的成品，將決定或未解決的問題記錄在 docs/<vid>/ 中，更新狀態，並僅將已接受的版本交給下一個專家。審查者必須有乾淨的上下文，且不得是產出該成品並為其評分的代理程式。video-director 不為自己的工作評分。
video-director 是主要的對話執行緒（您），而非子代理程式。它管理以下所有代理程式：調度、交接已接受的輸入、路由修復、整合共享檔案、記錄狀態/關卡，並與使用者交談。每個階段由其各自命名的代理程式執行；審查代理程式是分開的、使用乾淨的上下文，並且每輪都是新的。
| Phase | 產出代理程式 | 審查代理程式 (關卡) | 擁有並回傳的內容 |
|---|---|---|---|
| 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：每個鏡頭的螢幕文字、字幕區塊、重點詞、封面/重新鉤子/CTA 文字、宣稱→來源表格、minh hoạ 標籤 / content-pack-review.md |
| 3b 音訊 | voice-agent + audio-agent | audio-reviewer (分支, 機器判定) | sN.mp3 + 持續時間 + ASR (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：tsc、確定性、幀/轉場/字幕檢查、每個鏡頭的設計忠實度分數、修復路由給所有者 |
| 9 渲染 | render-agent | video-reviewer (C, 最終關卡) | 驗證過的 MP4 + final-check.md (在 MP4 上進行完整回歸測試) + render-evidence.md (聯絡表、密集幀、響度、ASR) / video-review.md |
| 10 交付 | video-director | — (人類聆聽 = 選用記錄) | 導演執行 check 並撰寫交付報告 |
只有 video-director 可以寫入共享的 kit、timeline、Reel、Root 和 voice.json；專家在他們的交接中提議對這些檔案的更改。場景代理程式從影片的 SHOTS 對應讀取持續時間，並將動作錨定到測量到的語音區間。絕不要將同一個可寫檔案分配給兩個代理程式。如果使用者停止工作，也請停止背景代理程式。關卡 C 是對聯絡表、密集幀、ffprobe/響度資料和 ASR 的 AI 審查；在 C 之後的人類聆聽（pipeline.py listen）是選用記錄，不是交付障礙。
速度規則：預設並行調度
video-director 必須在工作允許的情況下，以並行方式調度盡可能多的子代理程式，以便盡快且盡可能好地完成影片。當步驟可以同時執行時，一個接一個地執行是一種缺陷。
- 在一個訊息中發送所有獨立的 Agent 呼叫（一個工具區塊），永遠不要每回合一個。
- 當輸入已接受且可寫檔案不重疊時進行並行化：
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起草計劃，scene-agent們在 E 審查時建構早期骨架；B 審查等待 E 通過（如果 E 更改了任何內容，計劃也會改變）。 - Phase 7：
scene-agent× N 處理互斥檔案；Phase 8：每個鏡頭集群和靜止幀渲染的qa-agent；Phase 9：同時計算聯絡表、密集幀、響度和 ASR 證據。 - 修復輪次：不同所有者的票證在同一個訊息中發出。審查可以同時進行，但導演記錄分數並嚴格按順序 A → D → E → B → C 執行
gate（pipeline.py強制執行），且如果較早的關卡重新開啟，則較晚審查者的結果無效。
- Phase 0：
- 僅在存在真實依賴關係時保持順序： 關卡 A → D → E → B → C（審查者需要其成品完成）、依賴於先前審查的修復輪次，以及任何具有單一所有者的檔案（
kit、timeline、Reel……）不再繼續，因為提供的內容已截斷。
[截斷的內容結束]