DoubleWhopperS/video-craft-playbook

Video Craft Playbook

這是一本給編碼 Agent 的影片工藝手冊，幫你在動手前看清：做一條高品質影片，手邊有哪些畫面能力可以調；每種能力在什麼樣的表達上成立、在哪裡會失效、要付出什麼；之前的案例怎麼組合、踩過哪些坑。

本手冊不規定選哪個工具。工具沒有預設項，也沒有固定配方：同一種畫風、同一類片子，在不同的約束（預算、素材、時長、要不要真物理、要不要真人、會改幾輪）下，合適的組合會完全不同。選型由你針對當前任務做有目的的規劃，本手冊只提供判斷依據。

怎麼用

1. 開工前：檢查回寫欠帳

python3 ~/.agents/skills/video-craft-playbook/scripts/playbook.py status

status 列出尚未蒸餾的案例卡（cases/inbox/）、超過複核期的能力卡，以及候補層（references/lessons-backlog.md）的條數；到歸納閾值時提示跑 consolidate。inbox 裡只有上次判斷值得沉澱、但沒來得及蒸餾的卡。有欠帳時，先花幾分鐘把它蒸餾進手冊（見第 4 步），再開新片；時間緊時至少告訴用戶有幾條待回寫。

2. 規劃：先拆表達需求，再匹配能力

不要從「用什麼工具」開始，從「這條片子裡每個元素靠什麼成立」開始：

1. 把成片拆成元素：主體、環境、運動、鏡頭、文字與圖形、質感、聲音、節奏。
2. 對每個元素回答 references/task-lenses.md 裡的幾個問題：它的「真」從哪裡來，要不要逐幀精確，會改幾輪，能不能付費，要多快出片。
3. 在 references/capability-atlas.md 裡為每個元素找出至少兩種可行能力：先掃頂部總覽表挑候選，再讀對應卡片；比較後選定，把選定理由和放棄的替代寫下來。候選裡要包含「找得到的真實素材」（atlas H 組：本地素材索引、開放素材庫），不只比較生成與程式碼；來源階梯與「文案 → 鏡頭描述 → 檢索 → 許可核對 → 合成」的鏈路見 task-lenses 第 11 問與 craft-lessons L60。
4. 幾種能力拼在一起時，先定好介面：時間權威、幀率、座標與相機、alpha、色彩、音訊匯流排（task-lenses 第三節）。
5. 開工前寫出「能力分工表」（模板在 task-lenses 第四節），在第一條回覆裡給用戶看，然後執行，不必等確認。

剪輯類任務（素材已給定，主要做剪輯與後處理）另看 task-lenses 第六節：手法拆成通用部件與「訊號 → 手法」規則，見 references/editing-grammar.md；理解層要產出的訊號與欄位，見 references/edit-signals.md。兩份目前都是推斷，用時當作起點，收尾時判斷能否升級。

鏡頭級的運動語法（開場、轉場、字卡、介面登場、收場）在選定 Remotion 後可以查外部配方庫索引 references/shot-vocabulary.md：按職能槽位和能量找卡，再去倉庫讀卡全文和 demo 源碼；它來自產品宣傳片語境，本機未驗證。

references/composition-patterns.md 記錄了歷史案例實際怎麼組合的，可以用來啟發思路、預估代價。它們是當時那個任務的解，不是模板：照搬前先確認你的任務約束和當時一樣。

3. 執行：工藝與坑

• 跨工具都成立的做法（驗收先行、時間單一權威、畫面是 t 的純函數、審片分層、付費三件套、音訊規範等）見 references/craft-lessons.md。
• 按工具分組的已知坑見 references/pitfalls.md。用到某個工具前，先掃一眼它那一組。
• 具體工具的呼叫方式以對應 Skill 為準（atlas 每張卡寫了入口）；本手冊不重複它們的命令細節。

4. 收尾：先判斷值不值得沉澱，再決定回不回寫

手冊靠案例生長，但不是每個案例都要寫回來：只重複已有條目、或只對這一條片子成立的細節，寫進來只會稀釋手冊。交付影片（或中止任務）時，按 references/writeback.md 第一節列候選、過三道門（復用、不可推導、代價），全過且有證據的才算數；能併進已有條目的就不新增。

• 有一條以上算數：按 writeback 第二節回寫：new-case 建案例卡 → 蒸餾進對應檔案（常駐層滿時寫進 references/lessons-backlog.md）→ check → close。來不及蒸餾就把卡留在 inbox，下次 status 會提醒。
• 一條都不算數：跳過回寫，不建案例卡、不登記臺帳。用戶說不回寫時同樣跳過。

最終交付說明裡寫一行 Playbook 回寫，寫明結論：改了哪些檔案，或案例卡待蒸餾，或「跳過：<一句話理由>」。

中立原則（寫手冊和用手冊都要守）

• 能力卡只寫事實：擅長什麼、不擅長什麼、代價、確定性、驗證來源。不寫「預設」「首選」「推薦」「優先使用」這類排序詞；playbook.py check 會攔截這些詞。
• 卡片順序按媒介類別排，不代表排名。
• 案例裡某個工具用得好，記成「在什麼約束下、因為什麼成立」，不要升級成「這類片子用它」。
• 沒在本機案例裡驗證過的能力也要收錄，標明「已安裝未驗證」或「推斷」；不要因為沒用過就略掉，也不要因為用過就誇大。
• 篇幅也是傾向：卡片欄位定長，功能清單和實現細節不進卡，用得多的工具不因此佔更多版面。
• 發現某條記錄帶出了傾向（比如某個工作區的說明寫著「預設選某某」），回寫時改成條件句：在什麼約束下它合適。