教材 → 动画讲解视频
目标:通俗易懂,同时不丢深度和完整性。 这三者之间的张力,靠三种载体分工来解决:
| 载体 | 负责什么 | 不该负责什么 |
|---|---|---|
| 画面(动画) | 机制、结构、因果、数量级、“为什么”——观众看得见的东西 | 长句、定义全文、清单 |
| 旁白(TTS 配音) | 论证、定义、例子、证据、限定条件——要点覆盖的主要载体 | 只有画面才能讲清的过程 |
| 屏幕文字 | 锚点:术语、关键数字、一句结论(同屏 ≤ 3 行) | 代替旁白 |
为什么这样分:如果把“每条要点都要以画面文字出现”当作验收标准,视频就会退化成会动的 PPT——
大半时长是文字卡,动画播完就静止,观众一边读字一边看图,两样都顾不上;
而且只核对文字的审查,会漏掉“画面和文字意思相反”这类错误。
这些失败模式和对应规则的来由,见 references/failure-modes.md。
贯穿全程的两条原则
- 原文是唯一的权威,其余都是 outline。 inventory、design、beats 都是对原文的有损压缩。 只照着它们生成,它们漏掉的东西动画里就不会有;审查时再拿同一份清单去对,也查不出来。 所以写分镜、写场景代码、做审查时,都要回到对应的原文页(含图、图注、侧栏、脚注)。 发现原文里有、清单里没有的内容,先补进清单(标注“rN 补”),再往下改。
- 多轮迭代,每轮完整保留。 “生成 → 审查 → 修改”按轮次循环,每轮的产物存进
rounds/<unit>/rN/, 存好后不再改动,修改一律进入下一轮,这样任意两轮都能直接对比。 自动审查清零后交给用户看,用户确认满意才算定稿。
每章的产物
<chapter>/
├── inventory.md # 1. 分级要点清单(原文 → 要点,带页码、类型、优先级);每轮可补充,后补的条目标注“rN 补”
├── design.md # 2. 教学设计(学习单元、钩子、误区、核心画面、深度演示、要点 → 载体映射)
├── beats.md # 3. 分镜:旁白先行,一拍一行(当前工作版本)
├── beats.json # 3'. 从 beats.md 抽出的旁白文本(喂给 TTS)
├── audio/<unit>/ # 5. 每拍一个音频文件
├── timeline/<unit>.json # 5'. audio_timeline.py 生成:每拍时长,场景代码据此定时
├── subs/<unit>.srt # 5'. 同一份时间轴生成的字幕
└── rounds/<unit>/ # 7. 每轮一个快照目录,存好后只读
├── r1/
│ ├── beats.md # 本轮所用分镜的副本
│ ├── timeline.json # 本轮所用时间轴的副本
│ ├── <unit>.mp4 # 本轮成片
│ ├── sheet.png # 每拍抽一帧的联系表
│ ├── lint.txt # lint_scenes.py 的输出
│ └── review.md # 本轮审查、与上一轮的对比、用户反馈
├── r2/ …
└── FINAL # 定稿时写入:定稿轮次(如 r3)、日期、用户确认的原话
场景代码:motion-canvas/src/scenes/<chapter>/*.tsx、manim/<chapter>/*.py
场景代码用版本库管理,每轮在 review.md 里记下当时的 commit;没有版本库时,把本轮改过的场景文件也复制进快照目录。
原文全文只放本地临时目录(如 /tmp/<chapter>-fulltext.txt),不进版本库(版权),但在 inventory.md 头部写清楚
怎么重新抽取(pdftotext -layout -f A -l B book.pdf,以及书页和 PDF 页的换算)。
第一次在项目里使用:搭建
本 skill 自带全部模板和辅助代码,在 assets/ 下。新项目按下表复制(已有项目缺哪个补哪个):
| skill 里的文件 | 复制到 | 作用 |
|---|---|---|
assets/motion-canvas/theme.ts | motion-canvas/src/lib/theme.ts | 配色、颜色语义、字体、字号、安全区 |
assets/motion-canvas/beats.ts | motion-canvas/src/lib/beats.ts | beat():动画时长由旁白音频决定 |
assets/motion-canvas/card.tsx | motion-canvas/src/lib/card.tsx | 文字卡(≤ 3 行,旁白驱动),只用于引言和小结 |
assets/motion-canvas/render/headless.ts | motion-canvas/src/headless.ts | 无头渲染入口 |
assets/motion-canvas/render/headless.html | motion-canvas/public/headless.html | 加载上面的入口 |
assets/motion-canvas/render/render.mjs | motion-canvas/scripts/render.mjs | 渲染驱动(在 motion-canvas/ 下运行) |
assets/motion-canvas/render/vite.config.ts | motion-canvas/vite.config.ts | Vite 插件配置,文件头写了依赖清单 |
assets/manim/theme.py、assets/manim/beats.py | manim/ | Manim 版的 theme 和 Beats |
scripts/ 下的两个脚本直接从 skill 目录运行,不用复制。
流程
按顺序走,每一步过了门槛再进下一步。整章不要一口气做完:先做一个学习单元的样片,跑完全部审查,定型后再铺开。 第 1、2 步每章做一次;第 3–7 步对每个学习单元按轮次循环(r1 → 审查 → r2 → …),直到定稿。
0. 全书一次性准备
视觉规范(配色、颜色语义、字体、分辨率、安全边距)定在 theme 里;搭好上面的渲染管线;
选定 TTS 引擎和音色;把反复出现的视觉元素做成组件。工程细节见 references/motion-canvas.md、references/manim.md。
1. 通读 → 分级要点清单(inventory.md)
逐节读原文全文,包括图注、侧栏、脚注,不要只看标题。每条要点一行:
ID | 要点(自己的话转述)| 类型 | 优先级 | 书页 | 图/表 | 可视化潜力
- 类型: 定义 / 论断 / 机制 / 数字 / 例子 / 图 / 限定条件 / 交叉引用 / 花絮
- 优先级(决定载体,也决定审查力度):
- P0 核心概念、定义、主论断:必须讲透,必须有画面动作
- P1 支撑证据、关键数字、主例子:必须准确,旁白讲到即可
- P2 出处、花絮、长清单的细项:可选,可只在旁白里一句带过,或放进视频简介
- 数字 原样记下单位和语境(“平均”“峰值”“某年数据”):语境丢了,数字就会被误读。
- 另起一节记**“原文没有、但我们想加的”**(示意模型、类比、引申),每条注明理由;成片里出现时必须标注“示意”或“引申”。
门槛: 每个小节都读过全文;P0 条目一般占 20–30%;所有数字都核对过原文。
2. 教学设计(design.md)
按概念切学习单元,不按目录标题切段。 一个单元 3–6 分钟,讲透一个问题,可以跨几个小节,也可以只是一个小节的一半。 每个单元写清楚:
- 钩子问题:观众为什么要关心?用一个具体场景提问(如“写进去的数据,多久才能被读到?”)。
- 学习目标:看完能回答的 2–3 个问题(之后也用作“新手测试”的题目)。
- 常见误区:要主动拆掉的错误直觉(如“均值能代表用户体验”)。
- 核心画面:贯穿整个单元的一个视觉隐喻或主线例子,尽量延续到下一个单元。
- 深度演示:书里一句话带过、但动画能让人“看见”的点(概率放大、分布排序、排队、相关故障……),
每单元至少一个。模式库见
references/pedagogy.md。 - 要点 → 载体映射:每条 P0/P1 要点落到哪一拍、由画面还是旁白承载。
- 叙事顺序:默认跟原书的论证顺序;要调整就写明理由。新增内容要编织进叙事,不要追加成补丁段。
门槛: 每条 P0 都有画面动作,每条 P1 都有承载的拍;单元之间没有重复的结论句。
3. 分镜(beats.md)——旁白先行
动笔前先重读原文。 打开这个单元覆盖的原文页(含图、图注、侧栏、脚注),和 inventory、design 对照着写。 inventory 和 design 只是 outline,内容以原文为准:例子的细节、数字的语境、图的读法、论证的先后,都从原文取。 原文里有、清单里没有的要点,先补进 inventory(标注“rN 补”)并定好优先级,再写进分镜。
先写旁白,再为每一拍设计画面。一拍一行:
拍号 | 旁白(1–2 句,口语)| 画面动作(动词开头:出现/移动/变色/排序/放大…)| 屏幕文字(≤ 15 字)| 要点 ID | 工具
- 每拍 3–8 秒,每一拍画面都要有变化;超过 6 秒没有变化,就是该加动作或该拆拍的信号。
- 旁白像讲给同事听:短句,先结论后细节,术语第一次出现时给中英对照。
- 数字放在画面里,并让它“有感觉”:换算成日常尺度,或和另一个数字对比。
- 结尾一拍回扣钩子问题;需要时加一拍“停下来想一想”。
- 写完之后,只读旁白检查一遍:要点全吗、逻辑顺吗;只读画面列再检查一遍:能看出机制吗。
空白模板见 references/templates.md;一个从要点清单到两个单元完整分镜的示例见 references/example-unit.md。
4. 工具路由
| 内容 | 工具 |
|---|---|
| 节点、消息、请求流、拓扑、状态变化、时序、表格和数据结构变换 | Motion Canvas |
| 坐标系、函数曲线、概率和分布、公式推导、几何和集合论证 | Manim |
| 机制 + 定量结论(如“扇出 N 个后端” → “1−0.99ᴺ 曲线”) | MC 演机制,切到 Manim 出曲线,两段共用同一组配色和数字 |
| 纯文字 | 尽量不用。引言、小结可以用 card.tsx,每单元最多 1 张,并配旁白 |
细节见 references/tool-routing.md。
5. 配音与时间轴
- 把 beats.md 的旁白抽成
beats.json([{id, text}]),用 TTS 生成每拍一个音频,放进audio/<unit>/<拍号>.wav。 TTS 引擎随环境选(云端 TTS、本地开源模型都可以),要求只有两条:全书同一个音色;输出同采样率的 PCM wav。 第一次用某个引擎前,先合成一两拍试听:多音字、英文术语、数字(“p99”“1.2 秒”)的读法要单独检查。 - 运行
python <skill>/scripts/audio_timeline.py audio/<unit> --beats beats.json -o timeline/<unit>.json --srt subs/<unit>.srt --concat-list audio/<unit>.txt, 得到每拍时长、字幕和音频拼接清单。 - 场景代码用
beat(id, 动画):先跑动画,再补等到该拍音频的时长(MC 用lib/beats.ts,Manim 用beats.py)。 不要手写waitFor(23.1)这样的魔法数字。 还没有音频时,beat()会按旁白字数估算时长,可以先把节奏搭起来。 - 视频静音渲染,拼接时用 ffmpeg 把音频混进去(命令见
references/motion-canvas.md的“拼接与混音”一节)。
6. 实现与渲染
- 先读
references/motion-canvas.md或references/manim.md里的“坑”一节。 - 写每个场景前,再对照一遍这些拍对应的原文段落和图。 标签、数字、图表的坐标和读法以原文为准, 不凭分镜里的转述;分镜和原文对不上时,以原文为准,并回头改分镜。
- 颜色、字体从 theme 引用;文字一律设
maxWidth+textWrap(Manim 用theme.py的txt(),会自动缩到安全区内)。 - 渲染前:MC 跑
npx tsc --noEmit,再跑python <skill>/scripts/lint_scenes.py <场景目录> --manim <manim 目录>。 - 渲染:MC 在
motion-canvas/下node scripts/render.mjs <场景名>;Manimmanim -qm <文件> <场景类>。 - 渲染后:ffprobe 核对时长;每拍抽一帧拼成联系表(contact sheet),审查时用。
7. 审查与多轮迭代(rounds//rN/)
完整清单、每轮流程和报告模板见 references/review-rubric.md。每轮做四道审查,缺一不可:
- 忠实审(正向):拿 inventory 对成片,P0/P1 要点逐条打勾;数字、例子、图的读法和原文一致; 没有原文之外的论断(引申必须标注)。
- 反查原文(反向):反过来拿原文对成片,逐段读这个单元覆盖的原文页(含图、图注、侧栏、脚注), 找成片里没有、清单里也没有的内容。正向审只能查出“清单有、成片没有”,清单本身的遗漏只有这一道能发现。 查到的先补进 inventory(标注“rN 补”)并定级,再按级别处理。
- 语义审:逐拍对照“画面在说什么”和“旁白在说什么”——静音只看画面会得出什么结论?会不会和旁白相反? 标签、颜色、箭头方向是否和概念一致?新手会不会学错?
- 观感审:lint 门槛(见下表)、节奏、叙事顺序、有没有重复的收尾句;最后做一次新手测试: 让没读过这一章的人(或者另开一个没有上下文的 agent 会话,只给它旁白和抽帧)回答设计阶段写的学习目标问题。
问题分级:P0 讲错或误导(必须修)、P1 缺漏或明显影响理解(应修)、P2 观感瑕疵(顺手修)。
每一轮怎么走:
- 建快照目录
rounds/<unit>/rN/,放入本轮的 beats.md、timeline.json、成片、联系表、lint 输出。 - 做四道审查,写
review.md。从 r2 起,开头先写与上一轮的对比:改了什么;上一轮的问题哪些修掉了、哪些还在;有没有新冒出来的问题。 修改不能引入新问题,所以上一轮已经通过的检查项也要重跑。 - 还有 P0 或 P1:修改 inventory、分镜、代码,生成 r(N+1),回到第 1 步。
- 没有 P0 和 P1:把本轮成片、联系表、review 摘要和“与上一轮的差异”交给用户看。 用户的反馈原样记进 review.md 的“用户反馈”一节,逐条分级(用户明确要求改的至少算 P1)、写好修法, 按反馈修改后生成 r(N+1),回到第 1 步。
- 用户确认满意、不再要求修改:写
rounds/<unit>/FINAL(定稿轮次、日期、用户确认的原话),这个单元定稿。
已经存好的轮次目录不再修改,任何修改都进入下一轮;需要回退时,从对应轮次的快照恢复。
质量门槛(lint_scenes.py 检查前五项)
| 指标 | 门槛 |
|---|---|
| 文字卡时长占比 | ≤ 15% |
| 非卡片场景静止占比(空拍或字面量等待 / 场景时长) | ≤ 40% |
| 单次静止 | ≤ 6s |
| 文字宽度 | 不超出安全区(1280 宽画布左右各留 60px) |
| 文字卡行数 | ≤ 3 行 |
| P0 要点 | 100% 有画面动作 |
| 单元长度 | 3–6 分钟,每个单元能独立看懂 |
不要做的事
- 不要为了“覆盖”加文字卡:缺了一条要点,先问它该进旁白还是该进画面。
- 不要追加补丁段:要么重写这个单元的叙事,要么把内容编织进已有的拍。
- 不要按模板给固定时长:时长由旁白决定。
- 不要把工作备注、页码指引放上画面。
- 不要把原书没有的数字或公式当作书的内容;示意模型也不要用错数学术语(例如说 1/(1−ρ) 有“拐点”)。
- 不要在一张图里混用两种坐标语义;要变换,就用动画把变换演出来。
- 不要只照着清单或分镜生成,也不要只拿清单审查:生成和审查都要回到原文。
- 不要覆盖或修改已经存好的轮次产物;不要在用户确认之前宣布定稿。
文件索引
| 文件 | 什么时候读 / 用 |
|---|---|
references/failure-modes.md | 第一次用本 skill 时;或想知道某条规则为什么存在时 |
references/pedagogy.md | 第 2、3 步:钩子、误区、深度演示模式库、通俗化手法 |
references/tool-routing.md | 第 4 步拿不准用哪个工具时 |
references/motion-canvas.md | 写 MC 场景、组件、渲染、拼接混音 |
references/manim.md | 写 Manim 场景(无 LaTeX 环境、确定性数据、计时) |
references/review-rubric.md | 第 7 步:四道审查的完整清单、每轮流程、轮次对比和报告模板 |
references/templates.md | inventory / design / beats / timeline / 轮次快照的空白模板 |
references/example-unit.md | 完整示例:一节内容 → 要点清单 → 两个学习单元的设计和分镜 |
scripts/lint_scenes.py | 渲染前的静态检查 |
scripts/audio_timeline.py | 音频 → timeline.json + SRT + 拼接清单 |
assets/ | theme、beat、文字卡、无头渲染管线(复制位置见“搭建”一节) |