git2video — 從真實 Git 歷史製作發布影片
讀取儲存庫的實際 Git 歷史記錄，產生準確且精美的發布影片：收集 → 腳本 → 驗證 → 渲染 → QA → 交付。完全在本地端執行（Node ≥ 22、ffmpeg、Playwright Chromium — 請先使用 doctor 檢查環境）。渲染時無需網路連線；敏感資訊會從差異片段中清除；電子郵件絕不會出現在輸出中。
skills/git2video/scripts/doctor.mjs # 檢查環境，修復 MISSING 行
scripts/collect.mjs # git -> story.json（分組提交、重大變更、統計、清理後的片段）
scripts/validate.mjs # 無音效的腳本必須先通過驗證才能渲染
scripts/render.mjs # storyboard -> video.mp4 (+ webm/gif)、layout-audit.json
scripts/qa.mjs # 腳本化關卡：out/qa/ 中的 report.json + report.md
references/storyboard-guide.md # 場景類型、資料格式、撰寫規則 — 在創作前閱讀
references/faq.md # 故障排除
工作流程
1. 收集歷史記錄。
node skills/git2video/scripts/collect.mjs --repo <儲存庫目錄> --out /tmp/g2v/story.json \
[--from <標籤|SHA|YYYY-MM-DD>] [--to HEAD] [--max-commits 400] [--include-contributors] [--gh]
預設值：最後一個標籤 → HEAD；無標籤：最近 30 天。之後請閱讀 /tmp/g2v/story.json。
2. 創作 storyboard.json（由你，AI 代理來做 — 先閱讀 references/storyboard-guide.md）。製作 30–45 秒發布影片的經驗法則：
標題 (3–4秒) → 亮點 (5–8秒) → 差異 (5–8秒) → 統計 (4–5秒) →
時間軸 (可選 4–6秒) → 重大變更 (3–5秒，僅在有時) →
貢獻者 (3–5秒，僅在使用 --include-contributors 時) → 結尾 (3–4秒)
每個場景包含：id、type、duration（0.8–15秒）、narration（≤ 2 句話；以每秒 0.35 個單詞的速度可在該時段內讀完）、source（支援說明的提交 SHA）、data（類型特定 — 格式請參考指南）。所有論述必須追溯到 story.json — 不得憑空捏造。
3. 驗證。
node skills/git2video/scripts/validate.mjs --storyboard /tmp/g2v/storyboard.json \
--story /tmp/g2v/story.json
在渲染前修正所有錯誤。僅在使用者要求製作短測試片段時，才能使用 --min/--max 放寬總時長視窗。
4. 渲染。
node skills/git2video/scripts/render.mjs --storyboard /tmp/g2v/storyboard.json \
--out /tmp/g2v --preset 16:9 --fps 30 --theme dark [--formats mp4,webm,gif]
預設：16:9@1920、9:16@1080、1:1@1080。主題：dark（預設）、light、neon。在同一台機器上渲染結果具有確定性；40秒 30fps 的影片約需 2–4 分鐘。v0.1 為無聲版本：旁白會自動以字幕形式嵌入。
5. QA（腳本化，非憑感覺）。
node skills/git2video/scripts/qa.mjs --storyboard /tmp/g2v/storyboard.json --out /tmp/g2v
閱讀 out/qa/report.md。PASS → 交付。FAIL → 查看 report.json 的詳細資訊，修正 storyboard，重新渲染，重新執行 QA。最多 3 次修復迴圈。 之後，如實報告仍然失敗的項目及其原因。
6. 交付。 告訴使用者：video.mp4（+ webm/gif）的絕對路徑、一行 QA 結論、任何第三次迴圈的遺留問題，並提供其他選項：其他預設（垂直）、主題變體（light/neon），或提供用於 README 嵌入的 GIF（--formats gif）。
嚴格規則
- 絕不捏造提交、統計資料或差異：每個場景的
source必須指向 story.json 中的真實 SHA。如果歷史記錄不支援某種場景類型，則跳過該場景。 - 絕不將貢獻者的電子郵件放入輸出中；僅在使用 --include-contributors 時使用名稱。
- 在渲染過程中不要編輯 skills/git2video/templates/ 或 scripts/ 下的檔案；確定性引擎和 QA 假設它們不變。場景/主題/資源的樣式更改只能作為獨立且已宣告的工作進行。
- 優先使用數量較少但準確的場景，而不是填充內容；旁白不超過 2 句話。