用Agent Skill自动化生成数学概念短片：开源项目实战解析

我做了个小调研，发现最近圈子里聊得最多的就是两件事：一类是各种 Agent 框架层出不穷，另一类是“Skill”这个概念被反复拿出来讨论。而 math-concept-film 这个开源项目恰好把这两件事叠在了一起——用 Agent Skill 的形式去生成数学概念短片。

先说结论：这个项目的思路很有意思。它不是又一个“输入一段文本，AI 帮你生成一段视频”的玩具，而是把“数学概念可视化”这件事，拆解成了一整套可以被 Agent 复用的标准化工作流。我花了一个周末把它跑通，又花了一个晚上把里面的设计思路翻了个底朝天。

如果你正在做 Agent 开发，或者你本身就是数学老师、科普作者、慕课视频生产者，又或者你只是好奇“开源项目里的 Skill 到底长什么样”，这篇文章应该能给你一些别的文档里读不到的实操经验。

1. 为什么“数学概念短片”值得做成 Agent Skill

1.1 从一段尴尬的科普视频说起

去年我想给公众号做一期关于“泰勒展开”的短视频，过程极其痛苦。我先用 PPT 画了一堆函数曲线，然后用录屏软件录讲解，最后剪辑时发现曲线动画和语音解说完全对不上。折腾了两天，出来的效果还是像课堂板书而不是可视化科普。

后来我尝试直接用 Python 的 Manim 库手写动画。Manim 确实是数学可视化的神器，渲染出来的效果非常专业，但问题在于——并不是每个人都愿意为了一个三分钟的短片去学一套动画框架。而且即使是熟练工，输出一个“积分几何意义”的短片，从构思分镜到渲染完毕，也得半天。

当时我就在想：如果这些东西能被封装成一个标准流程，让 AI 来主导一部分机械化工作，剩下的人类只负责概念选择和风格审核，那该多舒服。

1.2 Skill 本质：给 Agent 的一套“操作说明书”

这里面关键的一环，就是怎样把“生成数学短片”这件事变成 Agent 可执行的技能。

数据告诉你，当下 Agent Skill 开发已经成了一个非常典型的工作模式。把一个特定领域的任务流程、提示词约束、工具调用约定打包成一个目录，里面通常包含：

• 主说明文档（比如 SKILL.md），告诉模型这个技能是干嘛的、有什么边界、按什么步骤执行；
• 辅助脚本，负责和外部环境交互，比如调用渲染引擎、处理文件路径；
• 模板文件，提供标准化的输出格式。

math-concept-film 采用的就是这个套路。它把“数学概念 → 脚本 → 动画 → 成片”整条链路封装成一个标准 Skill，Agent 只需要理解这个技能的使用方法，就能自动完成从概念输入到成片输出的流程。

这样做的好处非常明显。第一，把专业性沉淀在 Skill 里，而不是靠模型“自由发挥”；第二，可复用性强，其他开发者可以直接拿来接自己的 Agent 框架；第三，因为流程被约束了，输出的稳定性远超裸奔提示词。

1.3 这项目最打动我的三个设计细节

我对 math-concept-film 做了拆解，有三个细节是我觉得值得借鉴的：

第一个细节是它对“输入边界”做了严格限定。它不是让 Agent 自由想象“先讲讲历史、再讲讲定义、最后来个例子”，而是规定了结构化的输入，比如数学概念名称、目标受众年龄段、期望的短片时长、画面风格。这种约束保证了生成的分镜脚本不会跑偏。

第二个细节是输出物被拆成两层。一层是给人看的文本脚本（解说词和画面描述），另一层是给 Manim 渲染器执行的可视化脚本。这两层分开生成，在调试时非常有用——如果画面出了问题，只需要改可视化层；如果讲解逻辑不对，只需要改文本层。

第三个细节是它有“失败兜底”的设计。任何自动生成的 Manim 脚本都不可能一次通过，所以 Skill 内部包含了异常捕获和重试机制。Agent 在渲染失败时能拿到报错信息，自动修复后重新渲染。

这三点综合起来，才是“开源项目里的 Agent Skill”真正有参考价值的地方。

2. 本地跑通 math-concept-film 前的环境准备与框架接入

2.1 环境清单：缺一个就等着哭

如果你想在本地折腾这个项目，建议先照着下面的清单把环境准备好。我是踩过坑的，有一半的时间都耗在了环境问题上。

重点说下 TeX 环境。很多同学平时写 Markdown、做开发根本用不到 LaTeX，所以很容易忽略这一步。但实际上 Manim 渲染带公式的画面时，后端是通过 LaTeX 编译数学表达式的。如果系统里没有 LaTeX，渲染到含公式的场景直接报错。

这里我建议有条件的话直接装 TeX Live 完整版，别看它体积大，但能省掉后续大量排查缺失宏包的时间。如果你只是跑最简单的 demo，也可以试试安装基础版的 TeXLive，但后续自定义公式时大概率会踩到缺包的坑。

2.2 接入不同 Agent 框架的通用方式

math-concept-film 的定位是“Skill”，不是“独立应用”，所以接入方式跟框架强相关。目前开源生态里主流的 Agent 框架都支持加载 Skills，无非是路径和配置三件事。

我实际测试下来的通用接入步骤是：

1. 把 math-concept-film 项目克隆或下载到本地任意目录；
2. 在 Agent 框架的配置里指定 Skills 的加载目录；
3. 重启 Agent，用自然语言描述“用数学短片技能生成一个关于 XXX 的概念短片”，看它是否响应。

由于 Skill 本身是“提示词 + 工具调用约定 + 模板”的组合，理论上任何支持工具调用的 Agent 框架都能接。我试过把它挂到自己的一个本地 Agent 上，运行得很顺畅，没有因为框架差异出现致命问题。

注意，如果你用的是自带 Skill 市场的产品级框架，加载第三方 Skill 时可能需要手动调整目录格式。

2.3 第一个最小验证：让 Agent 生成一集“毕达哥拉斯定理”短片

环境准备好之后，我做的第一个测试是让 Agent 生成一个关于“毕达哥拉斯定理”的 30 秒概念短片。

整个流程跑下来大概是这样的：

• 我先按 Skill 约定的输入格式，给出概念名称、时长和风格偏好；
• Agent 按 Skill 工作流先做概念语义拆解，生成了一份分镜脚本，包括旁白、画面描述、公式展示位置；
• 然后它把这些内容翻译成了 Manim 的 Python 代码；
• 代码自动提交到渲染队列，Manim 渲染输出视频文件；
• 整个流程结束，我在输出目录里拿到了一份 mp4 文件。

第一次跑通的时候我挺兴奋，但也立刻发现了不少问题。比如它生成的 Manim 代码里，某个场景的坐标参数写得不太合理，导致图形偏离画面中心；又比如公式排版和旁白的节奏没有完全对齐。这些问题在后面对话中让 Agent 自动修正过两次，最终效果还算及格。

我建议每个人拿到这个项目时，都先跑一个最小验证，把“输入到输出”的主链路走通，再考虑复杂功能。因为主链路一旦通了，后面排查问题会容易很多。

3. 核心工作流拆解：概念解析、分镜脚本与动画渲染

3.1 第一阶段：数学概念是怎么被拆成“可理解单元”的

很多自动生成视频的项目最容易翻车的环节，就是理解概念本身。模型拿到一个数学概念，如果用长篇大论解释一堆定义和定理，那生成出来的是“论文朗读”而不是“概念短片”。

math-concept-film 的处理方式是把概念拆成若干个“可理解单元”。举个例子，处理“极限”这个概念时，它不会直接上来讲 epsilon-delta 定义，而是先分解出：直观图像上的“逼近”感觉、数值表格里的趋势、严格定义的符号表达。

我看它在 Skill 的提示词里要求 Agent 针对目标受众（比如高中生、大学生）调整解释粒度。给高中生讲导数，更多强调“切线的斜率”这种直观理解；给大学生讲导数，则要补充“变化率的极限定义”和符号系统。

这一步的产出是一份结构化的“概念解释单元表”，每个单元包含：核心结论、直观类比、数学表达式、画面建议。有了这张表，后续的分镜脚本就水到渠成。

3.2 第二阶段：分镜脚本里暗藏的“信息密度”控制

分镜脚本这个环节，是最考验 Skill 设计水平的地方。我见过很多类似的生成项目，分镜阶段就是简单地把解说词打成一行行，配个“切换场景”的标注，精度很差。

math-concept-film 的分镜脚本要细得多。我贴一段它生成实际脚本的结构（我把具体内容做了简化脱敏）：

Scene 001 - 画面内容：坐标系中一条抛物线 y=x^2 逐渐绘制 - 旁白文本：我们从一个简单的函数开始观察 - 屏幕标注：y = x² - 动画动作：DrawAlong 绘制路径，速度曲线先慢后快 - 预期时长：4.5s Scene 002 - 画面内容：在抛物线上任取一点，动态展示切线逼近割线的过程 - 旁白文本：当两个点无限接近时，割线无限趋向于切线 - 屏幕标注：Δx → 0 - 动画动作：UpdateFromFunc 动态更新切线斜率 - 预期时长：6s

可以看出，这个脚本不只是“给用户看的提纲”，更是“给渲染引擎的执行指令”。每一个场景都对应 Manim 的动画方法，旁白和标注被严格区分。这样做最大的好处是：渲染阶段不需要 AI 再来“猜”画面，直接按脚本翻译成代码即可。

信息密度控制也隐藏其中。一段 30 秒的短片，拆成 4-6 个场景比较合理，每个场景只专注展示一个核心变化。如果概念太复杂，Skill 会要求 Agent 放弃某些细枝末节，优先保证主线清晰。

3.3 第三阶段：Manim 渲染的工程化调用

当 Agent 拿到了完整的分镜脚本，接下来的工作就是把它转换成 Manim 的 Python 代码，并交给渲染器。

math-concept-film 在这个环节做得很工程化。它不是简单地让 Agent 输出一个大的 Python 文件，而是把整个渲染过程拆成模板和动态参数两部分。模板是预先写好的 Manim 场景骨架，Agent 只需要往里面填具体的数学对象、动画类型、文本内容。

我看了下它的模板设计，大致是这样：

class ConceptScene(Scene): def construct(self): self.camera.background_color = "#1E1E1E" # 动态填充区：公式对象 equation = MathTex(r"{{expression}}") equation.scale(1.2) self.play(Write(equation)) self.wait({{wait_time}})

Agent 只需要替换{{expression}}和{{wait_time}}，就能生成一个可执行场景。这种方式的优势很明显：大大降低了代码生成错误率，同时方便做批量渲染。

渲染环节还有一些参数值得关注，比如分辨率、帧率、输出格式。math-concept-film 默认参数是 1080p、30fps，兼容性好且渲染速度适中。如果你想要更细腻的动画，可以改成 60fps，但渲染时间会翻倍。

4. 实测踩坑记录：公式渲染、脚本生成与资源峰值

4.1 LaTeX 公式乱码问题

我觉得每个拿到这个项目的人，遇到的第一个坑大概率都是公式渲染问题。

我当时第一次生成短片时，所有文字都正常，唯独到了带积分符号的画面，输出视频里公式区域是一堆红色报错信息。排查了一会发现，问题出在 Agent 生成的 LaTeX 代码里。它把\int写成了\int，经过 Python 字符串转义之后变成了无效的控制字符。肉眼很难看出问题，因为普通文本模式下看起来是一样的，但一旦交给 LaTeX 编译就直接报错。

这个问题的根源不是 math-concept-film 本身的问题，而是 Agent 在生成代码时对转义符号处理不够严谨。解决办法有两种：

• 在分镜脚本阶段，增加一个“公式语法校验”步骤，直接调用 LaTeX 编译检查公式能否通过；
• 在 Agent 的系统提示词里，明确要求所有 LaTeX 表达式必须放在$$或\(...\)包裹的原始字符串中，禁止使用普通转义。

我建议 Real 环境里两个方案都上，因为公式是数学短片的灵魂，任何一个公式渲染失败都会让整个片段翻车。

4.2 Agent 生成的 Python 脚本跑不通

另外一个频率较高的坑，是 Agent 从分镜脚本“翻译”成 Python 代码时，因为对 Manim API 的熟悉程度不够，生成了并不存在的类名或方法名。

举个例子，我测试时让 Agent 生成“双曲线渐近线”的动画，它用了一个叫DrawAsymptote的粒子，但实际上 Manim 没有这个方法，正确做法是用Line加Create动画组合实现。类似这种问题，如果没有兜底机制，整个渲染就会中断。

math-concept-film 里做了异常捕获，Agent 在渲染失败后能拿到 Python 的 Traceback，然后自我修正再次执行。我在测试中统计了一下，大概三分之一的首次生成的代码会有小问题，反馈修正后大部分都能跑通。但如果你用的 Agent 模型能力较弱，这个修正过程可能会反复多轮，甚至陷入死循环。

建议在写提示词时加一条硬性约束：如果同一个脚本修改超过三轮仍失败，需要重写整个场景而不是打补丁。

4.3 渲染时间和内存占用比想象中高

最后这类坑和代码无关，纯粹是工程层面——渲染资源的占用比大多数开发者预期的要高。

我第一次渲染一个两分钟的完整概念短片，选择了 1080p、30fps。结果渲染时长超过了一个小时。中途还遇到内存占用飙升到接近 4GB 的情况，差点把机器搞崩。

后来我总结了一套省资源的配置方案：

调试期先用低分辨率跑通流程、检查内容和节奏，等完全没问题了再切正式参数。这个习惯能帮你节省大量时间。

另外一个经验是，尽量把短片按场景拆分渲染，然后统一拼接，而不是一次渲染整个视频。Manim 本身就支持单场景渲染，拆开的好处是某个场景出错时，不需要重渲染所有内容。这个习惯我能救你很多次。

5. 二次开发：把 Skill 接进自己的 Agent 并定制专属数学专题

5.1 从使用到改造的切入点

如果你只是想拿它在实验室里生成几个短视频玩，前面的内容已经够用了。但如果你跟我一样是做 Agent 开发的，肯定会想把 Skill 字体拆开看看里面的结构，做二次改造。

我拿到 math-concept-film 项目后，看它就是一个标准的 Skill 目录结构。里面大概有这几个核心文件：

math-concept-film/ ├── SKILL.md # 技能说明与工作流定义 ├── config/ │ └── settings.yaml # 默认渲染参数 ├── templates/ │ ├── scene_template.py │ └── script_template.json ├── tools/ │ ├── renderer.py # Manim 渲染调用 │ └── validator.py # 脚本校验 └── assets/ └── styles/

最大的改造点基本上都在 SKILL.md 文件里，因为这里定义了 Agent 的主导行为。你可以调整里面的概念解析策略、分镜粒度和代码生成规范。templates 和 tools 是辅助执行的，一般不需要大改，除非你想换渲染引擎或者增加新的输出样式。

5.2 定制新数学专题的实战步骤

我以“给初中生做一期关于全等三角形判定”的短片为例，讲讲怎么定制。

首先，在 SKILL.md 里补充“初中几何专题”这个概念分类，让 Agent 知道这类概念需要更多的图形演示而非公式计算。其次，在模板里新增一个专门用于几何构图的场景模板，预设了三角形元素常出现的坐标量，避免生成的图形跑偏。接着，在代码生成的提示词中，补充约束条件：所有几何证明步骤必须用分步动画演示，每步之间要有暂停。

上面的改造并不复杂，总共改了几十个文件内容，大约花了下午便搞定了。生成的效果明显比默认模板更适合初中生观看，画面更干净、逻辑步骤更清晰。

5.3 本地模型与远程模型的选择建议

二开的过程中，一个绕不开的问题是“到底用哪个模型来加载这套 Skill”。

math-concept-film 本身不限制模型，所以你可以用云端大模型 API，也可以本地部署开源模型。我给一个选择参考：本地模型能用，但别选太小的。我试过把 7B 级别的本地模型接到这套 Skill 上，分镜文本生成没问题，但在“生成 Manim 代码”那个环节错误率很高，经常要用异常重试机制反复修正。到了 32B 甚至更大的本地模型时，代码生成质量才有显著提升。

如果你没有本地算力，直接用云端大模型的 API 是最省事的路径。注意因为 Agent 要基于分镜脚本生成 Manim 代码，这个环节对模型的代码能力和 API 熟悉程度要求比较高，尽量选择代码能力强的模型。

6. 这个项目还能继续扩展到哪些更远的地方

6.1 从“数学概念短片”扩展到“抽象概念可视化”

把 math-concept-film 跑通之后，我发现它的价值并不局限于数学。它本质上是一条“将抽象概念转译为可视化叙事”的通用流水线，可以被延伸到物理、经济模型，甚至是编程算法可视化。

比如我在它的模板基础上稍微改了一下输入定义，就让它生成了“快速排序算法过程演示”的短片。原本有序数组被画成柱状图，每次交换操作都被动画清楚地标出来。虽然输出的效果没有专门做算法可视化的引擎精细，但作为教学辅助视频，完全够用。

这也侧面验证了这个 Skill 架构的可扩展性确实很好。已有的“概念解析 → 分镜脚本 → 动效封装 → 渲染”链路不用动，只需要替换概念解析的规则和素材模板，就能适配新领域。

6.2 从“单集生成”到“系列化批量生产”

另一个值得探索的方向是做系列视频的批量生产。

我尝试用一套 SKILL.md + 多个数学概念列表作为输入，让它依次生成“极限”、“导数”、“积分”三集短片。由于 Skill 的工作流是标准的，每一集生成路径一致、画面风格统一、旁白语气相近，最终出来的是一个风格一致的系列课程，而不是东拼西凑的拼接视频。

要是配上模板里的章节编号和统一片头，基本上等于一条自动化视频生产线。对于在线教育机构的课程建设来说，这个方向的实用价值非常大。

6.3 把渲染引擎从 Manim 换成更轻量/更重量的方案

最后聊下引擎替换的问题。Manim 是当前开源数学动画的事实标准，但它不是唯一选择，也不是所有场景下的最优选择。

如果你只需要制作社交平台传播的 30 秒短视频，用 Manim 显得太重了，可以考虑把渲染底层替换成更轻量的 Plotly + FFmpeg，通过生成数学曲线的逐帧数据来合成视频。我在试过这个组合后，发现渲染速度快了非常多，配合简单的坐标轴和标注，足以完成网关的极简动画。

如果你想走更重度的方向，把底层替换成 Blender，则可以获得高质量的三维数学可视化效果，非常适合制作面向研究人员的复杂图形动画。代价是需要大幅修改渲染器的调用代码，但 math-concept-film 的 Saklar架构保证了“概念解析 → 分镜脚本”这两个阶段可以原样保留，你只需新增一个针对 Blender 的渲染器后端即可。

写在后面：一点不算总结的心得

项目摆在那里，代码跑通了是一回事，把它真正用到自己的场景里是另一回事。

我回过头来看，math-concept-film 这类的 Skill 项目，最值得学习的其实不是那段代码写得有多漂亮，而是它把“领域知识、AI 对话能力、工具链调用”三者捏合在一起的方法。数学概念本身是严谨的，动画生成是工程化的，而 Agent 提供的是连接两者的柔性智能。这三者缺一个，效果都会打折扣。

这几周我在它上面反复调试，最让我欣慰的是“修正模式”。遇到生成结果不对，不是推翻重来，而是定位到具体环节微观修正。这种迭代方式，才是工具类 Agent 技能应该有的样子。

如果你最近也在研究 Agent Skill 的工程化思路，建议你把这类项目下载下来跑一遍，一定要亲手折腾一遍渲染，才懂得那些设计有多么贴近真实工程场景。