讲解视频
你制作的讲解视频要让特定观众看得懂，而且 必须正确。决定结果的有两件事：
references/STYLE.md 中的规则（它们来自真实的审校反馈），以及计算并核对每个显示数值的习惯。渲染是最简单的部分。
仓库结构：库 animkit/（API 参考 animkit/README.md），工具 tools/，示例 examples/，两个完成的剧集 episodes_example/（复制其故事板和镜头格式；声明格式见 references/VERIFY.md），你的工作放在 episodes/<ID>_<topic>/。
0. 开始之前
- 环境正常吗？
python -I -B -X utf8 tools/selftest.py必须打印all OK。如果缺少config/animkit.json，运行python -X utf8 tools/setup_config.py（配置是每检出一次：新的 clone 或 git worktree 需要重新执行，或者设置ANIMKIT_CONFIG）。问题：见SETUP.md。 - 只向用户询问你无法默认设定的内容（一条消息，简短）：
- 主题和源材料（讲义、论文、网页）；你需要为每个声明提供来源；
- 观众以及他们已知的内容（设定深度，见
references/STORYBOARD.md§观众）； - 时长；是否想要翻译版本/解说/配音？
- 是否可以运行真实模型（GPU，下载）？默认：否，使用已知真实情况的合成场景。
- 未回答时的默认值：1080×1440，30 fps，仅字幕，无配音，计划一轮审校。
- 创建
episodes/<ID>_<topic>/目录以及STATUS.md（阶段/下一步/等待的内容/来自date的时间）。
1. 管线（详细信息和命令：references/PIPELINE.md）
| 阶段 | 你需要产出 | 进入下一阶段前的检查点 |
|---|---|---|
| A. 研究 | 源摘要；可选参考视频分解（references/REFERENCES.md） | 你能将机制表述为：输入 → 公式 → 形状 → 小数值示例 → 原因 |
| B. 故事板 | storyboard.md，CLAIMS_to_verify.md，episode.json（+ elements_needed.md 如果库缺少某些元素） | 长剧集需用户同意大纲；完成独立验证轮次 1 并应用更正（references/VERIFY.md） |
| C. 镜头 | shots/sNN_*.py，每个包含 @shot.check | --check-only 通过；检查联系表；完整渲染；修复 check.json 中的警告 |
| D. 合成 | render/<ID>.mp4（tools/concat.py），review/round1/review.html（tools/review_page.py） | 你已查看每个镜头的联系表；屏幕上的数值 = 声明 |
| E. 审校轮次 | review/roundN/feedback.md（用户的笔记），review/roundN+1/changes.md，重新渲染 | 每条反馈都得到回应；新声明已验证（最多每项两轮） |
| F. 可选 | 翻译版本（references/I18N.md），解说（references/NARRATION.md），配音（references/TTS.md） | 每项都有自己的检查 |
直接以视频的语言编写镜头（示例中使用英语）：字幕、标题和标签在脚本中就是普通字符串。--lang 仅用于第二个翻译版本。
微路径（≤ 60 秒，1–3 个镜头）。 相同阶段，更精简。episodes/<ID>_<topic>/ 中的最小文件列表：
storyboard.md：一个表格，每行一个字幕（时间范围，字幕，屏幕上的变化，计算性的或说明性的）。框架：templates/storyboard_skeleton.md。CLAIMS_to_verify.md：每行一个屏幕上的数值/事实（声明，来源，检查方法，测量/计算/推断/论文）。shots/s01_<name>.py基于templates/shot_template.py，包含一个@shot.check，用于断言每个计算出的数值与其显示的字符串一致。- 验证：一个全新的子代理，使用
templates/verifier_prompt.md，范围涵盖所有声明行；应用其更正（旧措辞加删除线）。 - 渲染：
--check-only→--sheet-only（查看sheet.jpg）→ 完整渲染。 - 仅当有 2 个或以上镜头时才需要
episode.json+tools/concat.py；使用tools/review_page.py <EP> --round 1生成审校页面（一轮）。不要跳过声明表、@shot.check或联系表检查。
2. 永远不可选的规则
- 每个可计算的视觉元素都必须被计算（投影、注意力权重、重塑、反向投影、拟合线）并在
@shot.check中断言，包括 显示的字符串：ck.eq("depth on screen", f"{z:.3f}", "1.976")。格式来自全精度；绝不重新舍入已打印的值。说明性视觉元素需添加shot.tag("Illustration")；降维的绘图要注明。 - 每个数值都有来源（论文 § / 表格 / 公式，官方代码文件 + 行号，或我们自己的脚本）在
CLAIMS_to_verify.md中，标记为 measured / computed / inferred / paper。比较中需说明度量标准、单位，以及是否越低越好或越高越好；百分比需说明其分母。 - 每个符号在出现的地方都要定义，每次出现；观众可能不认识的术语需添加弹出式侧边窗口（
animkit.Popup）简要说明后关闭。 - 一个字幕对应一个视觉变化，不超过 12 个单词，宽度不超过帧（渲染会发出警告；在 42 像素宽度下，通常每行约 8 个长单词，最多 2 行），每个持续 2–3 秒，没有任何静态内容。
- 图优先，公式其次，逐项点亮显示，每个术语用颜色标注或链接到其对应的图片部分。
- 我们自己的测试要标明为原创（非论文的实验），首次出现时标记，之后使用相同标签。
- 独立验证：谁写了声明，谁就不验证它；修正视为新声明；最多两轮，之后按措辞应用并进行抽查。旧措辞需加删除线（
~~旧~~ → 新），绝不静默删除。 - 在翻译或解说中不编造事实：它们只能说明已验证的字幕/声明内容。
- 完整清单：
references/STYLE.md（§A 内容，§B 节奏，§C 视觉语法，§D 交付前，§E 成为规则的审校反馈）。在编写故事板前阅读它，并在每个审校轮次前再次阅读。
3. 工作风格
- 阅读
animkit/README.md中你需要的 API 部分（内容较长：用 grep 搜索元素，然后阅读该部分）。从episodes_example/中最相似的镜头复制模式，而不是自己发明布局。templates/shot_template.py是一个最小化的完整镜头模板。 - 使用
--still t1 t2（PNG 帧）和--sheet-only（12 帧联系表）迭代镜头；最后才进行完整渲染。每次都要自己查看联系表（重叠、文字出画、方块 = 缺失字形、字幕覆盖图片）。静止帧不会因后续渲染而刷新：每次编辑后重新运行--still。 - 3D 场景：
animkit/README.md§3D 场景（PinholeCam, OrbitCam 方位角/俯仰角约定：az=90, el=0 是侧视图）。例如针孔侧视图的 2D 图：§2D 侧视图（等比例 Plot2D）。 - 以
python -I -B -X utf8运行 Python；在其他会话渲染时绝不编辑库文件（references/PITFALLS.md）。 - 保持
STATUS.md简短且最新；在effort_log.csv中记录工作量（item,size,start,end,render_s,iterations,note）。 - 长剧集或大量镜头：按照
references/DISPATCH.md将工作拆分到多个会话/子代理中（主会话上下文预算约 300k，一次性子代理 ≤ 150k，切换前传递文件）。
4. 交付
告知用户：视频路径，审校页面路径（review/roundN/review.html，在浏览器中打开；每个镜头有评论框和“复制全部”按钮），哪些是计算性的、哪些是说明性的，验证了什么以及由谁验证，未解决的问题。当用户反馈回来时，逐字保存为 review/roundN/feedback.md（每行一个镜头 ID，例如 E03-02: ...），逐条回应，并将任何通用偏好转换为你的剧集本地规则的新行（追加到 episodes/ 中的 STYLE_local.md 中），以便下一集从该规则开始。
参考索引
| 文件 | 何时阅读 |
|---|---|
references/PIPELINE.md | 开始时；阶段命令、文件格式、检查点 |
references/STYLE.md | 编写故事板时；每个审校轮次前 |
references/STORYBOARD.md | 阶段 B：观众深度、故事板 + 声明格式、故事模式 |
references/REFERENCES.md | 研究参考视频/源论文时 |
references/VERIFY.md + templates/verifier_prompt.md | 声明完成后，模型运行后，解说/翻译后 |
references/REVIEW.md | 阶段 D–E：审校页面、反馈文件、轮次 |
references/I18N.md | 英文剧集的翻译版本（--lang） |
references/NARRATION.md | 每个视觉片段的解说脚本 |
references/TTS.md | 本地 TTS 配音、时间安排、混音 |
references/DISPATCH.md | 多会话/子代理工作、成本、共享机器礼仪 |
references/PITFALLS.md | 出现问题时；修改库之前 |
templates/ | 会话和子代理的提示词、框架文件、镜头模板 |