| name | MathLens |
| description | 专业的数学老师辅导技能，用于深入浅出的解答数学题，生成HTML讲解文档和带配音的Manim动画视频， 解答细致，深入浅出，浅显易懂，比较适合一般学情的学生。
核心工作流：数学分析 → HTML可视化 → 分镜脚本 → TTS音频 → 验证更新 → 脚手架 → Manim代码 → 渲染验证
触发条件：学生粘贴数学题图片、需要教学视频、需要HTML讲解资料
|
数学分析
核心工作流
WORKFLOW = [
{
"step": 1,
"name": "analyze_problem",
"input": "题目图片/文本",
"output": "math_analysis.md",
"tasks": ["推导数学事实", "建立几何模型", "确定图形构建方法"]
},
{
"step": 2,
"name": "html_visualization",
"input": "math_analysis.md",
"output": "数学_{日期}_{题目}.html",
"tasks": ["SVG画图形", "展示画图过程", "标注关键要素"]
},
{
"step": 3,
"name": "storyboard",
"input": "HTML内容",
"output": "{日期}_{题目}_分镜.md",
"tasks": ["定义幕结构(不限制幕数)", "设计画面/字幕/读白", "音频清单(时长留空)"]
},
{
"step": 4,
"name": "generate_tts",
"input": "分镜脚本",
"output": "audio/audio_{三位幕号}_{幕名}.wav + audio_info.json(含sync_points)",
"command": "python scripts/generate_tts.py audio_list.csv ./audio --voice xiaoxiao"
},
{
"step": 5,
"name": "validate_audio",
"input": "分镜.md + audio/",
"output": "更新后的分镜.md(填充时长) + 同步点摘要(供步骤7参考)",
"command": "python scripts/validate_audio.py 分镜.md ./audio",
"check": ["音频存在性", "时长>0", "数量匹配", "sync_points完整性"]
},
{
"step": 6,
"name": "scaffold",
"input": "分镜.md + audio_info.json(含sync_points)",
"output": "script.py (伪代码框架)",
"template": "templates/script_scaffold.py",
"must_include": [
"calculate_geometry() - 几何建模",
"assert_geometry() - 几何验证(题目条件+精度) + 画布范围检查(边界+中心)",
"COLORS - 颜色定义",
"SCENES[] - 幕信息数组(从audio_info.json加载时长)",
"start_scene_with_audio(scene_num) - 每幕起点（播放音频+记录起始时间）",
"end_scene_with_audio(expected_duration, safety_margin=0.2) - 每幕收尾（自动补齐等待）",
"wait_for_narration(keyword) - 等到读白说出关键词时刻再触发动画",
"wait_until_scene_time(seconds) - 等到幕内指定时刻",
]
},
{
"step": 7,
"name": "implement",
"input": "script.py脚手架 + 分镜.md + audio_info.json(含sync_points)",
"output": "完整的script.py",
"rules": [
"根据分镜实现每幕动画",
"使用 wait_for_narration(keyword) 对齐读白和高亮",
"禁止 self.wait(max(..., duration - N)) 手动兜底",
"画面时长由 end_scene_with_audio() 自动补齐",
"calculate_geometry()必须完整实现"
]
},
{
"step": 8,
"name": "check_and_render",
"input": "script.py",
"output": "视频文件 + 关键帧截图",
"command": "python scripts/render.py",
"check": ["代码结构检查(check.py)", "几何正确性", "高亮同步", "字幕清晰", "动画流畅"],
"on_fail": "回到步骤7修改代码"
}
]
步骤1：分析题目，推导数学事实
目标：建立正确的数学计算方法和流程，形成画出符合数学的图形的方法。
输出格式
## 数学事实分析
### 已知条件
- 条件1：...
- 条件2：...
### 推导的事实
1. **事实名称**: 描述
- 计算过程: ...
- 数学表达: ...
### 图形构建方法
- 点的坐标: ...
- 边的关系: ...
- 圆/弧的定义: ...
### 需要证明的结论
- 结论1: ...
注意：所有证明题需要证明的结论，在分镜中都可以作为已确立的事实来使用。
步骤2：HTML + SVG 可视化
目标：用 HTML + SVG 画出图形，展示画图过程和解答流程，为分镜做规划。
补充：如果用户已经提供了准确的HTML文件，描述了画图过程，可以按文件名要求复制一份，跳过生成文件。
输出要求
- 文件命名：
数学_{日期}_{题目简述}.html
- 包含：题目陈述、SVG 图形、分步解答、关键要素标注
- SVG 需要展示画图过程（如：先画三角形 → 再画圆 → 标注点）
步骤3：生成分镜脚本
目标：定义视频结构，不限制幕数，结尾预留音频文件名（时长为空）。
文件命名
{日期}_{题目}_分镜.md
分镜脚本结构
# 分镜脚本 - {题目名称}
## 分镜设计
### 第1幕：{幕名}
**画面**: ...
**字幕**: ...（简洁，≤20字）
**读白**: ...（详细，口语化，容易理解，适合普通学情的学生）
**动画**: ...
**目的**: ...
---
## 音频生成清单（步骤4填写）
| 幕号 | 文件名 | 读白文本 | 时长 | 说话人 | 情感 |
|------|--------|----------|------|--------|------|
| 1 | audio_001_{幕名}.wav | "读白文本" | | xiaoxiao | 热情 |
| 2 | audio_002_{幕名}.wav | "读白文本" | | xiaoxiao | 平和 |
关键规范
- 幕号从1开始连续编号
- 文件名格式：
audio_{三位幕号}_{幕名}.wav
- 时长列为空，由步骤5填充
- 不限制幕数，根据内容需要决定
- 每幕读白建议 1
3 句，每句 820 字，避免单幕文本过长导致动画拥挤
- 动作节奏采用「句子拍点」：每句读白对应 1~2 个核心动画，不要一口气堆叠大量 Create/Transform
动画描述：使用读白关键词锚点（重要）
分镜的动画部分使用 @[关键词] 锚定读白中的句子，步骤4 TTS 生成后会自动产生每句话的精确时间戳（sync_points），步骤7中代码通过 wait_for_narration("关键词") 精确对齐。
不要写硬编码秒数（如 0.0s, 3.0s），因为 TTS 生成前无法预知准确时刻。
**动画**:
- @[勾股定理]: 字幕"勾股定理"淡入
- @[正方形]: 正方形高亮 → 字幕退场
- @[所以]: 结论公式淡入，持续到幕末
@[关键词] 规则：
- 关键词取自读白文本中某句话的特征词（2~6字）
- 同一幕内关键词不要重复
- 步骤5验证后，可在同步点摘要中确认每个关键词的实际时间
- 如果某动画不需要对齐读白（如幕首淡入），可以省略锚点
字幕退场约定
为了避免动画中文字忘记退场，在动画部分使用退场标记：
退场标记方式（三选一）：
→ 箭头符号表示退场（推荐，最简洁）退场: 或 淡出: 显式标记持续X秒 指定显示时长
示例：
**动画**:
- @[正方形性质]: 字幕淡入，持续3秒 → 自动退场
- @[勾股定理]: 标题淡入 → @[所以] 时退场
- 幕末：所有文字退场
参考示例
见 references/storyboard_sample.md - 第九十九题：证明四点共圆
音画节奏预算（必填）
每一幕必须包含节奏预算（写在分镜的动画末尾）：
**节奏预算**:
- 音频时长 D: ___s（步骤5回填）
- 读白句数: 3 句
- 核心动画数: 3 个（每句读白对应 1~2 个动画）
- 关键同步词: "三角形ABC", "内切圆", "切点"
执行原则：
- 单幕内重动画（Create/Transform 大对象）连续不超过 3 个
- 每个关键结论后至少留
0.2~0.4s 的视觉停顿
- 幕末收尾由
end_scene_with_audio() 自动补齐，不需要手动兜底
- 禁止
self.wait(max(..., duration - N)) 模式
步骤4：TTS 生成语音文件（含句级同步点）
使用脚本：scripts/generate_tts.py（Edge TTS）
脚本通过 Edge TTS 的 WordBoundary 事件自动捕获每句话的起始时间，生成 sync_points。
执行命令
python scripts/generate_tts.py audio_list.csv ./audio --voice xiaoxiao
输出文件
audio/
├── audio_001_开场.wav
├── audio_002_展示图形.wav
├── audio_003_定理证明.wav
├── ...
└── audio_info.json ← 含 sync_points
audio_info.json 格式（含 sync_points）
{
"files": [
{
"scene": 1,
"file": "audio_001_开场.wav",
"duration": 8.5,
"sync_points": [
{"idx": 0, "text": "大家好，今天我们来讲解一道经典的平面几何问题", "time": 0.0},
{"idx": 1, "text": "证明四点共圆", "time": 3.2},
{"idx": 2, "text": "这道题综合运用了切线长定理和双曲线的性质", "time":
sync_points 说明：
idx：句子在本幕中的序号（从 0 开始）text：句子前 40 字（用于关键词匹配）time：该句话在音频中的起始秒数（由 TTS WordBoundary 精确计算）- 在步骤7中通过
self.wait_for_narration("关键词") 查找 text 包含关键词的条目
步骤5：验证音频并查看同步点
使用脚本：scripts/validate_audio.py
功能
- 读取
audio/audio_info.json 获取音频时长
- 验证所有音频文件存在且时长正常（>0秒）
- 更新分镜脚本的"音频生成清单"中的时长列
- 打印同步点摘要：列出每幕的句级同步点及其时间戳
- 如果缺少音频或时长异常，报错提醒
执行命令
python scripts/validate_audio.py 分镜.md ./audio
输出示例（含同步点摘要）
🎯 同步点摘要（用于 wait_for_narration）
==================================================
第1幕 (8.5s):
0.00s │ "大家好，今天我们来讲解一道经典的平面几何问题"
3.20s │ "证明四点共圆"
4.80s │ "这道题综合运用了切线长定理和双曲线的性质"
第2幕 (15.2s):
0.00s │ "首先，我们来看题目给出的图形"
2.10s │ "三角形 ABC 的内切圆 I"
7.40s │ "三角形内一点 K"
此摘要是步骤7中选择 wait_for_narration() 关键词的依据。
验证失败情况
- 缺少音频文件 → 报错："缺少第X幕音频文件"
- 时长为0或异常 → 报错："第X幕音频时长异常，请检查格式"
- 分镜与音频数量不匹配 → 报错："分镜X幕，音频Y个，数量不匹配"
步骤6：生成 script.py 脚手架
使用模板：templates/script_scaffold.py
输出：script.py（伪代码框架，由 AI 在步骤7完善）
脚手架核心方法一览
| 方法 | 作用 | 调用位置 |
|---|
calculate_geometry() | 几何建模 | construct() |
assert_geometry() | 几何验证 + 画布范围 | construct() |
define_elements() | 定义 Manim 图形对象 | construct() |
start_scene_with_audio(n) | 播放音频 + 记录起始时间 | construct() 循环 |
end_scene_with_audio(d) | 自动补齐等待 | construct() 循环 |
wait_for_narration(keyword) | 等到读白说出关键词 | play_scene_X() |
wait_until_scene_time(sec) | 等到幕内指定时刻 | play_scene_X() |
get_sync_time(keyword) | 查找关键词时间（不等待） | play_scene_X() |
脚手架必须包含的部分
from manim import *
import json
import os
class MathScene(Scene):
"""
数学教学视频场景 - 脚手架
根据分镜脚本和音频信息生成完整动画
"""
COLORS = {
'background': '#1a1a2e',
'primary': '#4ecca3',
'secondary': '#e94560',
'highlight': '#ffc107',
'text': '#ffffff',
'grid': '#2a2a4e',
}
ZONES = {
'title': {'y_min': 3.0, 'y_max': 3.8, 'x_min': -6.5, 'x_max': 6.5, 'desc': '标题区（顶部）'},
'geometry': {'y_min': -2.2, 'y_max': 2.8, 'x_min': -5.0, 'x_max': 3.0, 'desc': '几何图形主区域（中偏左）'},
: {: -, : -, : -, : , : },
: {: -, : , : , : , : },
}
Z_LAYERS = {
: ,
: ,
: ,
: ,
: ,
: ,
: ,
: ,
}
SCENES = [
(, , , ),
(, , , ),
]
():
().__init__(**kwargs)
.audio_timings = ._load_audio_timings()
():
():
geometry = {
: {},
: {},
: {},
: {},
}
geometry
():
():
elements = {
: {},
: {},
: {},
: {},
}
elements
():
geometry = .calculate_geometry()
.assert_geometry(geometry)
elements = .define_elements(geometry)
.camera.background_color = .COLORS[]
scene_num, scene_name, audio_file, duration .SCENES:
.play_scene(scene_num, scene_name, audio_file, duration, elements, geometry)
():
():
():
():
步骤7：AI 生成最终代码
输入：
- 分镜脚本（已更新时长）
audio/audio_info.json（含 sync_points）script.py 脚手架- 步骤5输出的同步点摘要
输出：完整的 script.py
AI 生成指导：
- 根据分镜的"动画"描述实现具体动画代码
- 使用
wait_for_narration("关键词") 对齐读白和高亮（参考步骤5的同步点摘要选择关键词）
- 实现
calculate_geometry() 的具体计算
- 实现
assert_geometry() 的验证逻辑
- 为每幕实现
play_scene_X() 方法
- 音频集成（必须，防重叠）：
- 在
construct() 的每幕循环中统一执行：
expected_duration = self.start_scene_with_audio(scene_num)play_scene_X(...)self.end_scene_with_audio(expected_duration, safety_margin=0.2)
play_scene_X() 内专注视觉动作，不手工累计总时长
- 验证音频文件路径正确：
audio/audio_001_XXX.wav
- 字幕显示与退场（关键）：
- 使用
show_subtitle_timed(text, duration) 或 show_subtitle_with_audio(text, audio_duration)
- 分镜中的
→ 或 退场: 标记表示文字退场
- 必须确保所有文字元素都有退场动画
禁止事项（步骤7）
| 禁止 | 替代方案 |
|---|
self.wait(max(..., duration - N)) | 删除手动兜底，由 end_scene_with_audio() 自动补齐 |
硬编码 self.wait(3.7) 对齐读白 | 使用 self.wait_for_narration("关键词") |
在 play_scene_X() 中调用 add_sound() | 由 start_scene_with_audio() 统一管理 |
手动估算 animation_time 判断切幕 | 由 end_scene_with_audio() 自动处理 |
防遮挡规范（步骤7必须遵守）
动画元素相互遮挡是最常见的视觉问题。以下规则必须严格执行。
规则1：画布分区 — 不同类型元素各归其位
脚手架中的 ZONES 定义了默认分区（可根据题目微调坐标，但必须保证各区互不重叠）：
| 区域 | 放置内容 | 核心约束 |
|---|
| 标题区（顶部） | 幕标题 | 幕切换时替换旧标题 |
| 几何区（中偏左） | 图形、点、线、圆、标签 | 主图形区，偏左留出右侧公式空间 |
| 字幕区（底部） | 字幕文字 | 字幕必须在底部（y ≈ -3.3），禁止放画布中央 |
| 公式区（右侧） | 公式、推导、结论 | 禁止与几何图形重叠；图形偏右时可将公式区换到左侧 |
规则2：z_index 层级 — 每个 Mobject 必须设置
使用脚手架 Z_LAYERS 常量，创建后立即调用 set_z_index()：
line_AB = Line(A, B, color=WHITE)
line_AB.set_z_index(self.Z_LAYERS['geometry'])
label_A = Text("A", font_size=28).next_to(dot_A, UR, buff=0.15)
label_A.set_z_index(self.Z_LAYERS['label'])
层级从后到前：背景(0) → 填充(1) → 几何(2) → 标签(3) → 高亮(4) → 字幕/公式(5) → 标题(6)
规则3：点标签防碰撞
- 方向偏移：
next_to(dot, 方向, buff=0.15~0.25)，禁止把标签放在点的精确坐标
- 方向选择：标签朝远离密集线段/元素的方向（如三角形内角处标签朝外）
- 背景衬底：标签可能与线段接近时，加
label.add_background_rectangle(color=bg_color, opacity=0.85, buff=0.06)
- 间距检查：两标签间距 < 0.3 时，调整方向或增大 buff
规则4：元素生命周期 — 及时退场防堆叠
self.play(FadeIn(subtitle))
self.wait_for_narration("关键词")
self.play(FadeOut(subtitle))
self.play(FadeOut(old_formula), FadeIn(new_formula))
self.play(line_AB.animate.set_color(YELLOW))
self.play(line_AB.animate.set_color(WHITE))
幕末清理：每幕结束前，将不需要带入下一幕的元素统一 FadeOut。
规则5：同区域冲突预防
- 多公式纵向排列：
VGroup(...).arrange(DOWN, buff=0.3)
- 字幕排队：多条字幕依次显示（先退场再入场），禁止同时可见
- 同一位置禁止堆叠 2 个及以上可见文字元素
步骤8：代码检查与渲染
8.1 代码结构检查（必须）
使用脚本：scripts/check.py
在渲染之前，必须先检查代码是否包含必要的函数和结构：
python scripts/check.py
python scripts/check.py my_script.py
检查内容：
- ✅
calculate_geometry() - 几何计算函数是否存在
- ✅
assert_geometry() - 几何验证函数是否存在
- ✅
define_elements() - 图形元素定义函数是否存在
- ✅ 字幕类
Subtitle / TitleSubtitle 是否存在
- ✅ 是否有
add_sound() 调用（音频集成）
- ✅ 是否有继承
Scene 的类
- ✅ 是否使用了
wait_for_narration() 或 wait_until_scene_time() 同步方法
- ✅ 是否存在
self.wait(max(..., duration - N)) 反模式
- ⚠️ 防遮挡（需人工审查代码）：Mobject 是否设置了
set_z_index()、字幕是否在底部、字幕是否配对 FadeOut、标签是否用 next_to() 偏移
检查结果：
- ❌ 错误：必须修复，否则无法渲染
- ⚠️ 警告：建议修复，但不会阻止渲染
8.2 渲染视频
方式1：使用渲染脚本（推荐，包含检查）
python scripts/render.py
python scripts/render.py -f script.py -s MathScene
python scripts/render.py -q h
python scripts/render.py -q k
python scripts/render.py -q m
python scripts/render.py --no-check
方式2：直接使用 manim（跳过检查，不推荐）
manim -pqh script.py MathScene
提取关键帧验证
python scripts/extract_frames.py media/videos/script/1080p60/MathScene.mp4 --interval 5
验证内容
- 几何图形是否正确（点、线、圆位置）
- 高亮是否与讲解同步
- 字幕是否清晰可读
- 动画是否流畅
- 防遮挡检查（关键帧逐帧确认）：
- 点标签是否被线段/圆弧遮挡？
- 字幕是否与几何图形重叠？
- 多个文字元素是否堆叠在同一位置？
- 公式/结论是否侵入几何区域？
- 音频是否正确添加：
- 每幕都有声音（没有静音幕）
- 音频与分镜中的读白内容一致
- 每幕末
elapsed >= audio_duration + safety_margin（没有抢跑切幕）
- 没有出现上一幕音频未结束就进入下一幕的重叠
渲染后必须执行
import shutil
import os
from pathlib import Path
video_src = Path("media/videos/script/1920p60/SquareTriangleProblem.mp4")
video_dst = Path("最终视频.mp4")
if video_src.exists():
shutil.copy2(video_src, video_dst)
print(f"✓ 视频已拷贝到: {video_dst}")
规则：渲染完成后必须将视频拷贝到项目根目录，不要留在media/深处。
如果发现问题
数学解题原则（绝对重要）
❌ 禁止使用坐标系
绝不用坐标系来求解，应该用各种定义和推理。
错误示例（坐标法）：
设B=(0,0), C=(5,0), A=(1.8, 2.4)...
面积 = ½ × 底 × 高
正确示例（几何推理）：
1. 由勾股定理：BC = √(AB² + AC²) = 5
2. 正方形性质：BE = BC = 5
3. 等积变换：S△ABE = S△ABC × (EB/BC) × sin(∠ABE)/sin(∠ABC)
4. 或用向量叉积、海伦公式等纯几何方法
允许的可视化辅助：
- 为了动画展示可以显示坐标，但解题过程不能用坐标计算
- 可以用几何画板的思路：旋转、平移、对称等变换
推荐的几何推理方法
- 等积变换 - 同底等高、等底同高
- 相似三角形 - 比例关系
- 勾股定理 - 边长关系
- 向量/叉积 - 纯几何意义的运算
- 旋转/对称 - 几何变换
文件结构
tutor/
├── SKILL.md # 本文件 - 工作流程定义
├── requirements.txt # Python 依赖
├── references/
│ └── storyboard_sample.md # 分镜脚本示例（参考）
├── templates/
│ └── script_scaffold.py # Manim 脚手架模板（含字幕类）
├── scripts/
│ ├── generate_tts.py # TTS 生成脚本
│ ├── validate_audio.py # 音频验证脚本
│ ├── check.py # 代码结构检查脚本（渲染前必执行）
│ └── render.py # 渲染流水线脚本（检查+渲染+拷贝）
└── sample/ # 示例项目（保留参考）
└── geometry_proof/
依赖管理
使用 uv 管理依赖：
uv venv .venv
uv pip install -r requirements.txt
source .venv/bin/activate
绕过LaTeX依赖（重要）
Manim默认需要LaTeX来渲染数学公式。如果不想安装LaTeX，全部使用Text替代MathTex：
MathTex(r"BC^2 = AB^2 + AC^2")
MathTex(r"\frac{1}{2} \times 5")
MathTex("A")
Text("BC² = AB² + AC²", font_size=36)
Text("½ × 5", font_size=30)
Text("A", font_size=32)
常用替换对照表：
| 数学符号 | LaTeX写法 | 无LaTeX写法 |
|---|
| 上标 | x^2 | x² (直接输入Unicode) |
| 分数 | \frac{1}{2} | ½ 或 1/2 |
| 度数 | 90^\circ | 90° |
| 平方厘米 | \text{cm}^2 | cm² |
| 根号 | \sqrt{25} | √25 |
| 角度 | \angle A | ∠A |
脚手架默认不使用MathTex，如需数学公式请直接输入Unicode字符。
关键原则总结
| 原则 | 说明 |
|---|
| 数学先行 | 先建立正确的数学模型，再画图 |
| 音频必填 | 每幕必须调用 self.add_sound()，否则视频无声音 |
| 句级同步 | 使用 wait_for_narration("关键词") 精确对齐读白和高亮（精度 ±0.3s） |
| 高亮对应 | 配音提到什么，画面高亮什么 |
| 自动补齐 | 幕末由 end_scene_with_audio() 自动补齐，禁止 duration - N 手动兜底 |
| 最小验证 | assert_geometry 验证题目条件(带精度) + 画布范围(边界+中心) |
| 防遮挡 | 画布分区(标题/几何/字幕/公式) + z_index层级 + 标签偏移 + 及时退场 |
| 逐步抽象 | 从 HTML 可视化 → 分镜脚本 → Manim 代码 |
