edu-math-video

数学题讲解视频 (edu-math-video)

把一道数学题做成 16:9、1920×1080、带中文配音的讲解视频：先生成能直接在浏览器里播放的网页预览，用户看过后再问要不要导出 MP4。五种画面模板、五种配音引擎可选（配音在第 0 步定；板书风格自动选，预览页里可随时切换；只有导出 MP4 时才问用哪种风格）。

模板	画面	做法	适合
handdrawn 手绘动画	手绘笔记本风 canvas 动画，中英双语字幕，背景音乐+音效	每题手写 anim.js，动作最自由（滑动重合、展开、拼接、动点）	推理要靠"动"才看得懂的题、行程/动点、需要英文字幕
chalk 粉笔黑板	黑板粉笔字、圈画强调、公式用 LaTeX（KaTeX）排版	写声明式 lesson.json，引擎自动排版	通用、老师讲题感
lab 几何实验室	深色发光、步骤条、缓慢摆动的 3D 图	同上	高中立体几何、函数图像
whiteboard 白板马克笔	白板、红色标签、便利贴提示	同上	初中
notebook 方格本	方格纸、猫头鹰助教、印章	同上	小学、初一

四种板书模板共用 lesson/ 引擎（同一份 lesson.json 随时切换风格），立体图自动旋转并实时计算虚实线。板书模板比手绘快得多（写几百行 JSON，而不是从零写动画），是默认推荐。

配音引擎（两种流水线共用 shared/tts.py，见 reference/tts-setup.md）：glm 智谱 GLM-TTS（GLM_API_KEY）、doubao 豆包语音合成 2.0（DOUBAO_API_KEY，带逐字时间戳）、minimax MiniMax（MINIMAX_API_KEY，带逐字时间戳）、兜底 edge（免费）/ say（macOS 离线）。

文件与约定

• lesson/：板书模板引擎、构建脚本（scripts/make.mjs）、lesson.json 文档（lesson/reference/）和范例（lesson/examples/）。
• template/ + examples/cone-parallel/ + scripts/：手绘模板的项目模板、示例和工具。
• shared/tts.py（五种配音引擎）、shared/pron.py + pron.json（读音控制，两种模板共用）。
• 本技能自带全部代码，不要从别的项目复制文件。

SKILL = 本文件所在目录，WS = 用户当前所在的目录（$PWD）：视频文件夹 PROJ = WS/<ascii_folder_name>/ 建在这里。不要因为别的目录（包括本技能所在的项目）已经有 .env、node_modules、pron.json 就把 WS 换过去。 PY = 装了 numpy、requests、pypinyin 的 python（macOS 上一般是 /usr/bin/python3；PATH 里的 python3 可能没有 numpy）。

通用规则

1. 退出码不是 0 就是没完成。 检查报错、warnings、截图里有问题，都不能写"只是警告、不影响"然后继续。修好再往下走。
2. API Key 只能由用户提供，只放在 WS/.env，在第 0 步就检查。 所选引擎缺 key 时：bash SKILL/scripts/init_env.sh "$PWD" <引擎> 建好 .env，告诉用户填哪一行、去哪申请，然后结束这一轮，等用户填好回来（详见 reference/tts-setup.md）。用户不想配，可以换已配置的引擎或兜底引擎。不要编造 key、模型名、音色或接口地址，不要把 key 打印出来或写进项目文件夹。
3. 先预览再花钱。 两种模板都有不调 TTS 的预览模式，版面和读音没问题再生成真配音。
4. 看图验证，但先看拼图。 截图审查先看一张拼图（sheet.png），有疑问再打开单张原图；汇报时写你实际看到了什么。能由程序报告的问题（文字出界、标签重叠）以命令输出为准，不必逐张找。
5. 命令输出只读汇总。 构建脚本只打印问题和一行汇总，完整报告在文件里，需要时再看。
6. MP4 是可选项，不要默认导出。 生成网页预览（板书 preview.html、手绘 index.html）并打开给用户看之后，用 AskUserQuestion 只问"要不要导出 MP4？"，用户选导出才渲染（板书这时再问导出用哪种风格）。交付内容（路径、时长、答案、请用户试听）在打开预览的那条消息里就说完；用户选不导出，任务就此结束，不再跑命令、不再重复交付。用户在请求里已明确要 MP4 文件（要发给别人、上传）时才可以直接导出。
7. 板书里的公式一律写成 LaTeX（$…$）。 根号、分数、上下标、向量、希腊字母都不要用纯文本符号（4√3、x²、n₁、1/2、θ）；构建会报 公式请用 $…$ 并拒绝通过。

步骤

第 0 步：定配音，并确认配音 key 可用（最先做，未通过前不做别的）

这一步通过之前不要读题解题、不要建项目、不要写 lesson.json / script.json 或任何代码（init_env.sh 建的 .env 除外）。key 缺了就在这一步停下等用户，免得做完一大半才发现不能配音。这一步不问画面风格：风格在第 1 步自动定，预览页里可以随时切换，只有导出 MP4 时才问。

1. 在 WS 下跑 PY SKILL/shared/tts.py info（读 WS/.env）：显示会用的配音引擎、哪些 key 已配置（只显示 set/-），以及用户保存的默认模板 VIDEO_TEMPLATE。
2. 定配音引擎。 用户在请求里指定了，或 .env 有 TTS_ENGINE，或只配了一家的 key，就直接用，不要问。否则用 AskUserQuestion 问一个问题，推荐项放第一位并标注"（推荐）"：
   • 已配置 key 的引擎排前面并推荐；没配的也列出；最后是免费的 edge / say。
   • 一个 key 都没配（info 里三个都是 -）时，选项就是："填写 key（推荐）"（选了再问用哪家）和"用系统自带的 say"（装了 edge-tts 时再加"用 edge-tts"）。兜底选项的说明里要写清效果可能不太好：机械感明显，断句和读音不如 GLM / 豆包 / MiniMax，只适合先看效果。
3. 检查 key： PY SKILL/shared/tts.py check --tts <选定的引擎>（在 WS 下运行）。
   • 打印 READY 且退出码 0：通过，进入第 1 步。
   • 退出码 1（缺 key）：bash SKILL/scripts/init_env.sh "$PWD" <引擎> 建好 WS/.env，告诉用户 .env 的完整路径、填哪一行、去哪申请（reference/tts-setup.md），然后结束这一轮。用户回来说填好了，再跑一次 check，READY 才进入第 1 步；还不行就请用户检查（等号后面、没有多余空格或引号、已保存）。
4. 选定的引擎记下来，第 2 步起写进项目：手绘写 episode.json 的 "tts"，板书写 lesson.json 的 meta.tts（选了兜底更要写，否则配音脚本会停下要求再问）。

• 用户是被问了才选的：交付时顺带告诉用户，可以在 WS/.env 加 TTS_ENGINE=<引擎>，以后就不再问（VIDEO_TEMPLATE=<模板> 可固定模板/风格）。
• 通过标准： 引擎已确定，且 tts.py check --tts <引擎> 打印 READY。

第 1 步：弄清题目，自己先把题解对，再定模板

• 拿到题目文字（有截图就先读图）。先自己完整解一遍并验算，写下：已知条件清单、所求、关键思路（1~2 个）、每一步计算、最终答案、验算方法。
• 答案不确定或题目看不清时，问用户，不要猜。
• 定模板（一般不问）：
  • 用户在请求里指定了模板/风格，或 .env 有 VIDEO_TEMPLATE，就用它。
  • 否则默认用板书，风格按题自动选：小学/初一 notebook，初中 whiteboard，高中立体几何/函数 lab，其他 chalk。不要问风格——四种板书共用同一份 lesson.json，预览页右下角能即时切换；只有用户要导出 MP4 时才问用哪种（lesson-flow.md 的 L6）。
  • 只有推理非靠图形运动才讲得清（动点、行程、图形平移/旋转重合、展开拼接），或用户要英文字幕时，才用 AskUserQuestion 问一句"板书（推荐，快）/ 手绘动画（动作更自由，但制作慢得多）"。板书和手绘是两条流水线，换的话要重做，所以这一项必须在动手前定。
• 通过标准： 你能用 3~6 个"幕"讲完，每一幕一句话说清目的；答案已验算；模板已定。

第 2 步起：按模板走对应流程

• 板书模板（chalk / lab / whiteboard / notebook）：reference/lesson-flow.md。
• 手绘模板（handdrawn）：reference/handdrawn-flow.md。
• 只读你选的那一份，另一份不用看。

参考文件

• reference/tts-setup.md：五种配音引擎的 key、.env、音色、语速、报错处理。引导用户配置时读这个。
• reference/lesson-flow.md：板书模板流程；格式细节在 lesson/reference/。
• reference/handdrawn-flow.md：手绘模板流程（第 2~11 步、常见错误），以及它用到的 script-writing / pronunciation / visual-design / animation / troubleshooting。