有机反应机理动画视频制作

把「一个机理」变成一段可放进课堂的动画视频：立体球棍模型 + 弯箭头/鱼钩箭头 + 中文解说与字幕 + 统一版式，全程 Python 逐帧绘制，不依赖剪辑软件。

三条硬规矩（违反即返工）：

1. 几何先算，再画。任何碳中心必须先确定杂化态（sp / sp² / sp³），由 mechkit.geom 生成轨道方向，再落原子坐标。不许"看着像"就摆位置。
2. 交付三件套。每次出片自动产出 成片.mp4 + <标题>-机理说明.md + <标题>.py（mechkit.export 负责，不许省）。
3. preview 目检不能跳。带已知缺陷全量渲染 = 白烧 15 分钟。

一、环境（一次配好，长期复用）

PY=~/.workbuddy/binaries/python/envs/chemvideo/Scripts/python.exe        # Windows
# 若不存在：
#   <托管python> -m venv ~/.workbuddy/binaries/python/envs/chemvideo
#   .../chemvideo/Scripts/pip install numpy pillow imageio-ffmpeg edge-tts

<skill>/scripts 下的一切都用这个 $PY。TTS 需联网（edge-tts）；离线加 --skip-tts 复用上次 out/audio/durations.json。

二、三步出片

cd <skill>/scripts
$PY build_video.py --list                          # ① 看内置预设
$PY build_video.py --preset sn2 --preview          # ② 代表帧目检（out/check/）
$PY build_video.py --preset sn2                    # ③ 全量渲染 + 配音 + 三件套导出

每次 build_video.py 结束都会写三件套（preview 阶段也写，方便先审说明文档）：

三、几何铁律（科学性核心）

详细推导与代码用法见 references/hybridization-geometry.md。四条不可协商：

• p 轨道只在内部作为几何依据，画面里不画（用户明确要求）。它的作用是决定 120°/180°、平面性、多重键第二条线的偏移方向，以及 π 键的相对朝向。
• 多重键必须写 "order": 2/3 + "pdir"（π 键法向）。双键两条线要沿 pdir 的屏幕投影分开，不能水平硬偏；三键为"中间一条 + 两侧各一条"。
• 构型翻转（Sₙ2/Walden）要改的是三个基团相对反应轴的位置（tetra_from(-轴)），不是把整个分子镜像。
• 键长用 pm→单位换算：C–C 154、C=C 134、C≡C 120、C–H 109、C–O 143、C=O 122、C–Br 194、C–Cl 177、O–H 96；1 单位 ≈ 100 pm。
• 写完 spec 立刻跑自检：preset 的 notes.hybridization 声明"哪个场景、哪个原子、什么杂化、连哪几个邻居"，导出时会实测键角并写进 md。出现 **FAIL** 必须改几何，不许改理论值凑数。

自检怎么工作：notes.hybridization[].neighbors 显式列出"参与该杂化的 σ 键"。过渡态里正在形成/断裂的键不要放进 neighbors，否则会拿部分键算键角，得到假失败。

四、工作流程

Step 1　判定输入级别

• L1 命中预设 → --preset 直接用；要改内容就改 presets/<name>.json 的文案/几何再渲染。
• L2 有描述 → 复制最接近的预设为新文件，替换 narration / caption / 分子几何 / 箭头。
• L3 只有名称 → 查 references/mechanism-playbook.md；未命中套通用四段式：title → 反应物与电子流向 → 关键中间体/过渡态 → 产物与要点。

Step 2　写 spec（几何先行）

1. 定每个碳中心的杂化：数 σ 键。
2. 用 mechkit.geom.hybrid("sp2", u, n=..., roll=...) 拿 sigma / p 方向，再乘键长落坐标。
3. 填 bonds（多重键带 order + pdir）、labels、arrows、cards。
4. 在 notes.hybridization 里登记每个中心，供自动键角审计。

语法见 references/preset-dsl.md；版式坐标/字号见 references/layout-spec.md。

文案底线：

• 箭头规范：异裂用弯箭头（curly），均裂/单电子转移用鱼钩箭头（fishhook）。起点在键或孤对电子上，终点在原子或新键上。
• 文字不压元素：标签用 place: below/above/left/right 贴球外，别用裸 dy 手调大偏移。
• 上下标走富文本：CH_{4}、HO^{-}、CH_{3}^{+}、·CH_{3}；字幕与旁白口径一致。
• 解说里要点明杂化变化（如"失去一个氢后碳由 sp³ 转 sp²，三个氢被压到同一平面，键角 109.5° → 120°"），这是教学价值所在。

Step 3　preview 目检（必做）

--preview 每段出 2 帧到 out/check/：0.30 看动作中（箭头/断键），0.62 看动作完成（版式是否压字）。逐张按 references/pitfalls.md 的清单核对：

• 文字与球、键、箭头、卡片有无重叠（用户零容忍）；
• 卡片标题与首行是否粘连；
• 分子是否被卡片/字幕条切掉；
• 几何是否真的对：四面体看着像平面、双键两条线重合、过渡态 O/Br 不共线——都要在这一步看出。

Step 4　全量渲染与交付

$PY build_video.py --preset X → 完成后用 present_files 一次性交出 mp4 + md + py，并说明时长/分镜/科学要点。首次给某机理出片时把 spec 存成 presets/<英文名>.json，下次即 L1。

五、命令速查

六、内置预设

七、验收清单（交付前逐条过）

• [ ] 代表帧无任何文字压住球、键、箭头、卡片
• [ ] md 里的键角自检表全部 PASS（有 FAIL 不许交付）
• [ ] sp³ 中心确为正四面体（不是"压扁的四面体"）；sp² 中心三键共面 120°；sp 中心两键严格共线
• [ ] 双键/三键的 pdir 与分子平面法向一致，两条/三条线看得清且不压球
• [ ] 过渡态/中间体的价键与几何合理；Sₙ2 的 Br–C–O 共线 180°
• [ ] 画面中没有绘制 p 轨道哑铃（p 轨道只做几何依据）
• [ ] 所有化学式上下标正确；箭头类型（弯钩/鱼钩）与断键方式匹配
• [ ] 三件套齐全且同源：mp4、md、py 的文件名与标题一致
• [ ] py 能独立跑通（几何自检通过 → 出片）

八、参考文档

• references/hybridization-geometry.md　sp/sp²/sp³ 严格几何、p 轨道语义、键长表、常见骨架、自检机制
• references/preset-dsl.md　spec 全字段（分镜、DSL、多重键、富文本、时间）
• references/layout-spec.md　版式（坐标网格、配色、字号、行距）
• references/mechanism-playbook.md　常见机理的编排要点与分镜模板
• references/pitfalls.md　踩坑清单与目检方法
• references/rendering-3d.md　三维渲染：光照模型、圆柱键、接触阴影、投影与摆向

九、常见问题