代码仓库导览视频
目标是制作一个团队成员观看后能理解仓库的视频：它的用途、各个部分如何组合在一起、每个函数的真实运行情况，包括今天哪里坏了。这里混合了两个任务，应按以下顺序执行：
- 真实测试仓库。 视频中显示的每个命令都真正运行过，并且读取了其输出。
- 将其记录为一个故事。 章节遵循系统的结构，每个章节都有旁白。
只展示成功命令的视频会误导团队。在测试过程中发现的失败往往是视频中最有价值的部分，所以给它们一个独立的结束章节。
输出布局
在仓库之外的一个文件夹中工作。由用户选择；如果用户不选，则使用同级目录，例如 <parent-of-repo>/video/，因为像 /video 这样的磁盘根路径在 macOS 上通常是只读的。
video/
├── <name>-walkthrough.mp4 # 完整视频：章节 + mov_text 字幕轨道
├── <name>-walkthrough.srt # 相同的旁白，也可用作文字稿
├── chapters/NN-slug.mp4 # 每个章节一个文件
├── README.md # 章节索引，包含开始时间，以及如何重新录制
├── src/ # engine.py, make_readme.py, script.py (+ 辅助程序)
├── work/ # 仓库的一次性克隆：每个命令都在这里运行
└── build/ # 中间文件（每段语音、帧、片段）
绝不要在用户的工作副本上运行演示命令。将其克隆到 work/ 中（git clone <repo> work/<name>），这样视频可以故意破坏（错误的清单、注入故障）并通过 git checkout . && git clean -fd 重置。如果用户的检出有未提交的更改，请提及它们并保持不动。
步骤 1：检查工具，并告诉用户缺少什么
which vhs ffmpeg ffprobe jq; python3 -c "import PIL; print(PIL.__version__)"; say -v '?' | head -3
如果缺少任何东西，在安装之前告诉用户要安装什么以及为什么（brew install vhs ffmpeg jq）。对于 Pillow，不要动系统 Python。而是通过 uv 运行引擎：uv run --no-project --with pillow python engine.py ...。将其包装在一个 shell 函数中（py() { uv run --no-project --with pillow python "$@"; }），因为包含命令的变量不会作为一个整体展开。仓库需要的任何其他东西也是如此，例如正在运行的 Docker、模拟器栈或凭据。向用户询问这些，并且永远不要编造秘密。
高级语音（系统设置 → 辅助功能 → 口语内容，例如 "Ava (Premium)"）听起来比默认的 Samantha 好得多。提供选择，但不要阻塞；VOICE=... engine.py --force 稍后可以重新配音。
步骤 2：在写下任何旁白之前理解并测试仓库
阅读 README、文档或 ADR、CLI 入口点（每个子命令的 --help）、测试标记、Makefile 和 CI 配置。构建一个用户可执行的每个函数清单：每个 CLI 子命令、每个测试套件、每个集成、以及代码防御的每个故障模式。
然后在 work/ 中运行所有内容，并记下：
- 能很好展示每个功能的确切命令，输出要简短（通过
jq、head、tail、cut -c1-160管道） - 什么失败了，以及它是真正的错误还是只是你的环境问题（错误的默认路径、缺少的环境变量）。在克隆中或通过环境变量修复环境问题，并使该修复在视频中可见，因为团队也会遇到它。
- 如何故意破坏每个安全规则（通过固定装置、对副本使用
sed），以便视频可以展示规则触发
这些笔记成为发现章节。将它们保留为编号的具体项目列表。
步骤 3：规划章节
遵循系统自身的管道，而不是文件夹列表。一个效果很好的结构：
| # | 章节 | 内容 |
|---|---|---|
| 00 | 欢迎 | 标题卡片，然后是“你将看到什么”幻灯片 |
| 01 | 大局 | 一句话的目的、带盒子和箭头的管道、仓库布局的终端场景 |
| 02 | 设置 | 安装、按目的分组的 CLI、快速测试套件 |
| … | 每个管道阶段一个章节 | 真实命令，以及每个规则的“故意破坏”场景 |
| … | 实时/集成 | 真实的后端服务，端到端 |
| N-1 | 约定/交接 | 其他团队依赖的内容 |
| N | 发现与下一步 | 编号的发现列表，然后是下一步做什么 |
目标是每个章节 1-3 分钟，总共 15-25 分钟。一个章节是一个想法；一个片段是一个屏幕加一段旁白。在录制之前向用户展示这个大纲（章节标题和每章节一行说明）。
步骤 4：编写 src/script.py
将捆绑的脚本复制到视频文件夹中：
mkdir -p video/src && cp <skill-dir>/scripts/{engine.py,make_readme.py,agent.jq} video/src/
cp <skill-dir>/scripts/script_template.py video/src/script.py
script.py 包含所有文字和所有命令。engine.py 将其转换为视频。阅读 references/script-format.md 以了解完整的片段模式、幻灯片布局和旁白风格。scripts/script_template.py 展示了每种片段类型以及一个工作示例；以相同的结构构建其余章节（步骤 3 给出了章节大纲）。
最重要的旁白规则：
- 为听觉而写：短句，无 markdown，并拼出语音会念错的缩写（
"M C P"、"C L I"），或者将它们添加到script.py的SPOKEN中。 - 说出观众应该看什么（"看技能：零"）。语音和画面必须一致，所以如果你改变了命令的输出（计数、速度因子），也要修复句子。
- 字幕（终端场景的底部栏）是陈述要点的一行文字，反引号内为
code。
步骤 5：试运行，然后录制
cd video/src # `py` = 带有 Pillow 的 Python（见步骤 1）
py engine.py --dry # 在普通 bash 中运行每个终端命令并打印输出，不生成视频
py engine.py --dry --only 04 # 一个章节
py engine.py --only 04 # 录制一个章节（快速反馈外观）
py engine.py # 所有缺少或更改的内容，然后组装完整视频
py engine.py --only 07 --reuse-terms # 保留 VHS 片段，只重新录制语音和帧（旁白修复）
py make_readme.py # 写入带有章节索引的 README.md
始终先试运行。只需几分钟而不是一小时，并且能捕获所有报错、挂起或输出过多的命令。在完整构建之前先录制一个章节并查看帧：
ffmpeg -v error -ss 20 -i chapters/04-*.mp4 -frames:v 1 build/check.png # 然后读取 PNG
完整构建需要很长时间（21 分钟的视频大约需要 40 分钟）。在后台运行它，并等待完成通知，而不是轮询。章节由其脚本的哈希值缓存，因此重新运行只重建更改过的部分。
步骤 6：验证并移交
ffprobe -v error -show_chapters -show_streams -of compact video/<name>-walkthrough.mp4 | head -40
检查以下内容：
- 时长
- 1920×1080 h264、aac 以及一个 mov_text 字幕流
- 每个章节一个章节标记
- 从几个章节中采样帧：没有文本溢出框，字幕在两行内
然后告诉用户 MP4、chapters/ 文件夹、SRT 和 README 的确切路径。添加如何打开它（open video/<name>-walkthrough.mp4；QuickTime 或 VLC 会显示章节和字幕菜单）以及发现列表。提及你留下的任何容器或服务以及如何停止它们。
已解决的陷阱（编辑引擎时请牢记）
- 沙盒 shell： vhs、Docker、
uv缓存和say在命令沙盒下经常失败（"操作不允许"、Docker socket 错误）。这些命令需要在沙盒外运行。open也被阻止，所以给用户提供自己运行的命令。 - VHS 丢帧： 默认的 50 fps 在长场景中会丢帧。引擎使用
Set Framerate 15。 - VHS 的
Output必须是裸文件名。 使用cwd设置为输出文件夹来运行vhs。 - VHS 字符串没有转义。
json.dumps引号会破坏 PS1 转义序列。使用引擎中的q()，它会选择一个文本中不包含的"、'或`分隔符。 Wait会挂起 如果模式与提示不匹配。引擎设置一个以$结尾的 PS1，并使用WaitPattern /[>$]$/。输出以$或>结尾的最终行的命令可能会提前结束等待，因此在那里添加一个pause。- 长时间运行的场景（AI 代理、管道运行）：在片段上设置
"speedup": True。引擎将片段加速到大致旁白的长度，并在头部打上sped up ×N.N标记，所以要说它被加速了。 - 幻灯片上的文本溢出：
wrap()以等宽字体测量代码片段。保持框体简短，并将长路径拆分为两行。 - 等待循环： 一个
pgrep -f <pattern>循环会匹配自身。改为等待一个 PID 或文件。 - 前置钩子（章节上的
"before": [...]）准备状态：重置数据库容器、触发管道、注入故障。将撤销（重置、取消注入）放在同一章节中，这样一个章节的重建永远不会使平台处于损坏状态。 - 演示需要的秘密放在克隆中一个被 git 忽略的文件中（例如
dev-vault.env）。绝不要在屏幕上显示它们的值，也绝不要提交它们。
展示工作中的 AI 代理（可选）
如果仓库构建或配置了一个代理，最有力的场景是代理诊断一个真实的、注入的故障。以无头模式运行它，输出 stream-json，并使用捆绑的 agent.jq 格式化流（每行一个工具调用，然后是答案）：
claude -p "<question>" --output-format stream-json --verbose | jq -rj -f /path/to/video/src/agent.jq
将该片段标记为 "speedup": True，并在同一章节中随后重置故障。