Master class render

输入：<source>/scripts/NN - Title.script.md（由 master-class 编写）。你编写：<source>/scenes/NN.scenes.md（D2文本，无坐标，无时间）。一条命令生成：<videos>/NN - Title.mp4 + <notes>/NN - Title.md + <notes>/<MOC>.md。

所有操作均在本地运行：D2 布局图表（手绘风格），Kokoro-82M 语音合成，时间来自真实音频，Chromium 在每个视觉变化时截取一帧，ffmpeg 编码。不向第三方发送任何内容。唯一消耗的Token是 scenes 文件（约为脚本大小的1倍）。

0 · 环境设置（每台机器只需一次；重复运行安全）

bash ~/.copilot/skills/master-class-render/scripts/setup.sh

安装 d2、ffmpeg、uv（通过Homebrew），在 scripts/.venv 中创建虚拟环境并安装 kokoro-onnx、soundfile 和 playwright（Chromium），以及 Kokoro 模型到 ~/.cache/kokoro（约350 MB）。如果 scripts/.venv/bin/python 已存在，则设置完成。

1 · 编写场景文件

首先阅读 references/scenes-guide.md 和已批准的示例：01、05、08。每个示例都与 ~/.copilot/skills/master-class/examples/ 中的脚本配对，以便您准确看到每个 画面（Screen） 如何变成图表。此步骤在小型/快速模型上也能良好运行：一次只处理一个课程，让验证器告诉您何时正确。然后，对于每个脚本，一个 ## Beat N 对应一个 ```d2 代码块，将节拍的画面描述转换过来：

# @at "短语"（从该节拍旁白中逐字复制的3–7个词）用于控制当旁白说出该短语时显示相应内容。最终布局一次性计算完成，因此不会发生跳跃；新出现元素会短暂闪烁。
# @continue 扩展前一个节拍的图表。
类（Class）：model、code、tool、data、person、bad、good、note（贴纸，包含结论；这些将成为课程笔记中的关键要点）、muted、wrong。
指南列出了D2的易错点（\$，{} 块内不能使用 @at，|||md 表格，样式变化不会产生动画）。

逐个课程进行验证（必须输出 ok: 且无 warning:）：

cd ~/.copilot/skills/master-class-render/scripts && export PATH=/opt/homebrew/bin:$PATH
.venv/bin/python render.py "<source>/scripts/NN - Title.script.md" "<source>/scenes/NN.scenes.md" /tmp/check.html

多个课程时 → 使用指南和示例，将任务分给多个并行子代理（每个代理约4个课程）。

2 · 构建课程

cd ~/.copilot/skills/master-class-render/scripts && export PATH=/opt/homebrew/bin:$PATH
.venv/bin/python build_course.py \
  --source "<lab>/_attachments/master-class/source" \
  --videos "<lab>/_attachments/master-class" \
  --notes  "<lab>/Master class" \
  --moc    "<Lab name> · Master class" \
  --course "<video左上角显示的标签>" \
  --tags   "course/<课程标签>,section/labs,topic/<x>,type/lesson" \
  --intro  "MOC的一段描述：课程由哪些内容组成（[[来源笔记链接]]）及其意图。" \
  --voice am_michael --lang en-us

语言/语音：英语 --voice am_michael --lang en-us（备选 am_puck、bm_george --lang en-gb）；西班牙语 --voice em_alex --lang es（女声：ef_dora）。
--only 03,07 仅重新渲染所选课程（笔记始终为所有课程重新生成）。--notes-only 仅生成笔记，不生成视频。
每个课程约15秒（语音缓存后）；首次合成每个课程约1分钟。输出文件在临时文件夹中编码后复制，因为直接写入OneDrive同步的文件夹会超时。
确保 --tags 与源笔记使用的标签匹配。

3 · 报告前验证

构建输出中每个课程都显示了 ok:，且无 !! … @at phrase(s) not found 警告。
从一两个MP4中提取帧并查看（每次使用新文件名；图像查看器会缓存）： ffmpeg -v error -ss 120 -i "<mp4>" -frames:v 1 -vf scale=1280:-1 /tmp/mc_check_<n>.png 检查：图表可读（不是细长条）、字幕匹配、显示正确的节拍。
图表太小？渲染器会自动尝试另一种布局方向；如果仍然太小，请拆分该节拍的图表或删除 @continue 并将前面的步骤总结到一个 muted 框中。
打开MOC笔记和一篇课程笔记：视频嵌入 ![[NN - Title.mp4]]、目标、关键要点、自检（问题 + 折叠答案）、折叠的转录、上一页/下一页链接。

每篇课程笔记包含的内容（生成，零Token）

Frontmatter（标签、课程、时长、课程链接）· 嵌入的MP4 · 目标 · 常见误解 · 关键要点（来自 note 贴纸）· 自检（来自 Retrieval pause 节拍）· 折叠的转录 · ← 上一页 · 课程索引 · 下一页 →。

文件

scripts/：build_course.py（入口点）· render.py（脚本 + 场景 → 中间HTML，含音频和时间线）· export_mp4.py（HTML → MP4）· make_notes.py（笔记 + MOC）· player.html（中间模板；也可用作脱机播放器）· prelude.d2（类、字体大小）· setup.sh。缓存：scripts/.cache/（语音片段、图表；可安全删除）。

master-class-render