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 # 故事板 -> 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 <repo-dir> --out /tmp/g2v/story.json \
[--from <tag|sha|YYYY-MM-DD>] [--to HEAD] [--max-commits 400] [--include-contributors] [--gh]
默认：最后一个标签 → HEAD；没有标签时：最近 30 天。之后查看 /tmp/g2v/story.json。
2. 创作故事板（storyboard.json） —— 由你（agent）完成，先阅读 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（支持所述主张的 commit 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 中的详细信息，修复故事板，重新渲染，重新运行 QA。最多 3 次修复循环。 之后，如实报告仍然失败的内容及原因。
6. 交付。 告知用户：video.mp4（+ webm/gif）的绝对路径、一行 QA 结论、任何 3 次循环后遗留的问题，并提供其他预设（垂直）、主题变体（light/neon）或用于 README 嵌入的 GIF（--formats gif）等选项。
硬性规则
- 永远不要发明提交、统计数据或差异：每个场景的
source必须指向 story.json 中真实的 SHA。如果历史不支持某种场景类型，则跳过该场景。 - 永远不要在输出中包含贡献者的邮箱；只有在使用 --include-contributors 时才包含名称。
- 不要在渲染过程中编辑 skills/git2video/templates/ 或 scripts/ 下的文件；确定性引擎和 QA 假定它们不变。场景/主题/素材的样式更改只能作为独立、声明的工作进行。
- 优先选择更少但准确的场景，而不是填充物；旁白保持在 ≤ 2 句话。