OpenMontage manim-composer 技能详解：把模糊想法编排成可落地的 Manim 分镜脚本

OpenMontage manim-composer 技能详解：把模糊想法编排成可落地的 Manim 分镜脚本

【免费下载链接】OpenMontageWorld's first open-source, agentic video production system. 12 production pipelines, 100+ tools, 700+ agent skill and production-knowledge files. Turn your AI coding assistant into a full video production studio.项目地址: https://gitcode.com/GitHub_Trending/op/OpenMontage

导读

manim-composer是 OpenMontage 项目中一个面向数学/科学讲解视频的"动画编剧"技能（Agent Skill）：它不负责写 Manim 代码，而是在写代码之前完成最难的工作——把用户一个模糊的概念，通过"深度研究 → 澄清提问 → 输出逐场景规格说明（scenes.md）"三阶段工作流，转化成一份可直接交给 ManimCE / ManimGL 实现的详细分镜脚本。本文将以该技能的 SKILL.md 为主干，完整还原其工作流、scenes.md 模板、3Blue1Brown 风格原则，并结合 OpenMontage 仓库中math_animate工具、Manim 使用规范与安全测试，说明这份分镜脚本如何落到真实渲染管线中。

一、技能定位：先规划，后编码

manim-composer的核心定位可以用 SKILL.md 开头的一句话概括："Use this BEFORE writing any Manim code. This skill plans the video; use manimce-best-practices or manimgl-best-practices for implementation."即它是视频生产的"前期编剧阶段"，与负责代码实现的manimce-best-practices/manimgl-best-practices技能形成前后接力关系。

技能自身的触发条件（description 字段）界定了适用场景：

• 用户想制作教育类 / 讲解类视频；
• 用户只有一个模糊概念需要被可视化；
• 用户提到 "3b1b style" 或 "explain like 3Blue1Brown"；
• 用户想规划一段 Manim 视频或动画序列；
• 用户要求 "compose" 或 "plan" 一个数学 / 科学可视化。

从仓库的注册关系看，这个技能并非孤立存在：在 tools/graphics/math_animate.py 中，MathAnimate工具的agent_skills = ["manimce-best-practices", "manim-composer"]字段把本技能与渲染工具直接关联起来——也就是说，在 OpenMontage 的 Agent 工作流中，manim-composer负责输出规划文档，math_animate工具负责把规划落实为scene_code并渲染成视频。

二、三阶段工作流：从概念到分镜

SKILL.md 将整个规划过程划分为三个明确的阶段，每个阶段有独立的产出物。

Phase 1：理解概念（Understand the Concept）

在向用户提问之前，Agent 必须先做足功课：

1. 深度研究主题：使用网络搜索理解核心概念，识别这个主题"有趣"的关键洞见，找到让学习者"恍然大悟"的 aha moment，并记录需要澄清的常见误解。
2. 确定叙事钩子（narrative hook）：这个视频回答什么问题？观众为什么要在意？有什么令人惊讶或反直觉的元素？

这一阶段遵循"先研究、后提问"的原则——问题质量取决于对主题的理解深度，这正是做出高质量数学讲解视频与照本宣科式讲题的本质区别。

Phase 2：与用户澄清（Clarify with User）

SKILL.md 强调"不要一次性抛出所有问题，而是根据用户回答逐步适配"，并给出了三个维度的提问清单：

这些澄清项与后文 scenes.md 的Target Audience、Estimated Length、Color Palette、Narration Notes字段一一对应，确保收集到的信息最终都能沉淀进分镜文档。

Phase 3：输出 scenes.md

这是整个技能的核心产出物：一份结构完整的逐场景规格说明。SKILL.md 给出了标准骨架（后文第五节将完整展开），其设计目标是——"具体到足以让任何人照着实现这个场景"（references/scene-examples.md 中的表述）。

三、3Blue1Brown 风格原则：场景编排的心法

SKILL.md 用四大类原则约束"如何编排场景"，这是 manim-composer 区别于普通脚本大纲的关键。

视觉叙事（Visual Storytelling）

• Show, don't just tell——每个概念都需要一个视觉表达；
• 渐进揭示（Progressive revelation）——逐步构建复杂度，不要一次性展示全部；
• 视觉连续性（Visual continuity）——优先"变换"已有对象而非"替换"它。

其中"变换而非替换"在配套的 references/visual-techniques.md 中有直接代码体现：TransformMatchingTex(equation1, equation2)优于FadeOut(equation1), FadeIn(equation2)，因为前者保持了视觉连续性并揭示了两者之间的关系。

节奏与韵律（Pacing & Rhythm）

• 为洞见留白：给观众吸收关键瞬间的时间；
• 变化节奏：快速序列与慢速讲解交替；
• 场景以"解决"收尾：每个场景都应让人感到完整。

visual-techniques.md 进一步给出了可量化的节奏参考：简单形状创建 0.5-1s、文字/公式书写 1-2s、变换 1-2s、镜头移动 2-3s、复杂动画 2-4s，以及 "Fast-fast-SLOW-fast-fast-SLOW" 的韵律模式——快速动画用于铺垫，关键洞见处放慢。

数学之美（Mathematical Beauty）

• 强调优雅：突出数学出乎意料的简洁或优美之处；
• 连接多重表征：用代数、几何、直觉等多种方式展示同一概念；
• 渐进抽象：先具体，再推广。

参与感技巧（Engagement Techniques）

• 先提问再揭晓：让观众在揭晓答案前先产生好奇；
• 承认难度：例如"这可能一开始看起来令人困惑……"；
• 庆祝洞见：让 aha moment 显得"值得"。

四、叙事模式与情绪弧线：references 的深度支撑

SKILL.md 的 References 一节指向三个配套文档，它们共同构成了"3b1b 式叙事"的方法论库：

• references/narrative-patterns.md：常见叙事结构；
• references/visual-techniques.md：可视化模式；
• references/scene-examples.md：真实场景拆解示例。

六种叙事模式（narrative-patterns.md）

1. 谜团 → 调查 → 解答（Mystery → Investigation → Resolution）：先呈现令人困惑的结果或悖论，通过视觉探索调查原因，揭示底层原理，再展示其推广。适用于欧拉恒等式、贝叶斯定理、无穷级数悖论。
2. 搭建 → 回报（Build Up → Payoff）：引入简单积木，组合成复杂结构，展示优美/惊人结果，反思为何奏效。适用于傅里叶级数、神经网络、线性代数。
3. 双视角 → 统一（Two Perspectives → Unity）：从视角 A（如代数）与视角 B（如几何）分别展示同一概念，揭示二者是同一事物。适用于点积、行列式、复数乘法。
4. 错误 → 少错 → 正确（Wrong → Less Wrong → Right）：呈现常见误解或朴素方法，展示其为何失败，再精化，最终到达正确理解。适用于极限、概率分布、定义。
5. 特殊 → 一般（Specific → General）：先解具体例子，归纳模式，抽象出一般原理，再应用于新情境。适用于导数、群论、算法分析。
6. 历史即叙事（History as Narrative）：按历史原貌呈现问题，跟随发现之旅，展示带来突破的关键洞见，连接到现代理解。适用于微积分、密码学、量子力学。

文档还明确建议组合使用多种模式（如"谜团钩子 + 搭建式解释"、"双视角 + 特殊到一般"），并给出了基于视频时长的段落节奏表与五拍情绪弧线（好奇 → 困惑 → 部分清晰 → aha 时刻 → 满足）。

视觉技法库（visual-techniques.md）

该文档按四层组织：核心原则（渐进揭示、变换而非替换、颜色编码意义、空间关系编码）、动画技法（Indicate闪烁提示、Circumscribe圈注、FlashAround揭晓强调；set_color_by_tex隔离公式项、逐步推导MathTex、代入动画；Axes坐标系标注、TracedPath路径追踪、get_area面积可视化；3D 镜头环绕与切片投影）、常见视觉隐喻（向量即箭头、函数即机器、矩阵即变换、导数即斜率、积分即累积）、场景构图（黄金布局、并排对比、放大细节）与三套调色板（Classic 3b1b 深灰底#1C1C1C+ 蓝#58C4DD+ 绿#83C167+ 黄#FFFF00+ 红#FF6666；高对比黑白金；柔和学术风）。

场景示例（scene-examples.md）

文档给出了三组完整的场景拆解：点积解释（提问场景 → 几何投影 → 数值联系）、傅里叶级数导论（钩子场景 → 正弦波积木 → 叠加原理）、矩阵作为线性变换（网格变换 → 基向量决定一切）。每组场景都含 Duration、Purpose、Visual Elements、Content、Narration Notes、Technical Notes 六个字段，其中 Technical Notes 精确到Arrow、MathTex、ValueTracker、Updater、TransformMatchingShapes、apply_matrix()等具体 Manim 类与方法——这正是"可实施的分镜"与"空泛的描述"之间的差别。

五、scenes.md 标准结构：完整字段详解

SKILL.md 给出了 scenes.md 的完整骨架，而 templates/scenes-template.md 提供了可直接复制的空白模板（含 3 个场景示例槽位与更多字段）。综合两者，一份合格的 scenes.md 应包含：

Overview（总览）

• Topic：核心数学/科学概念
• Hook：吸引观众的开场问题或谜团
• Target Audience：前提条件（假定的数学/科学背景）
• Estimated Length：预计时长（分钟）
• Key Insight：核心 aha moment——观众应记住的那一件事

Narrative Arc（叙事弧线）

用 2-3 句话描述从困惑到理解的旅程，例如"我们从令人困惑的观察出发，调查它为何成立，最终发现一个连接看似无关概念的优美底层原理"。

每个 Scene 的六字段规格

• Duration：约 X 秒；
• Purpose：该场景在整体叙事中的职责；
• Visual Elements：mobject 列表（描述、颜色、位置）、动画序列、镜头移动；
• Content：视觉与概念上具体发生了什么——"具体到足以让任何人都能实现这个场景"；
• Narration Notes：要传达的要点、语气、节奏（注意：是指导而非完整台词稿）；
• Technical Notes：具体 Manim 类/方法、棘手的实现点、对前序场景的依赖。

结尾汇总区块

• Transitions & Flow：场景间如何连接（Scene 1 → Scene 2 的视觉承接）、贯穿全片的视觉母题；
• Color Palette：Primary / Secondary / Accent / Background 各色的用途（模板版本还给出 Hex 值表格，如#58C4DD蓝、#83C167绿、#FFFF00黄、#FF6666红、#1C1C1C深灰底）；
• Mathematical Content：需要渲染的公式（LaTeX）清单、函数图像与几何对象及其性质；
• Implementation Order：建议的实现顺序（标注依赖关系）与共享组件清单；
• Open Questions / Decisions Needed：待决问题清单；
• Reference Material：素材来源、灵感视频、学术论文链接。

六、场景间的转换模式

scene-examples.md 在示例之外还总结了四类场景过渡模式，供编排时选用：

• 缩放聚焦（Zoom Focus）：全景 → 放大细节 → 讲解 → 缩小还原；
• 并排构建（Side-by-Side Build）：左右两侧逐步添加内容并建立联系；
• 变换链（Transform Chain）：对象 A → 变换为 B → 变换为 C，全程保持视觉连续性；
• 重置重建（Reset and Rebuild）：复杂场景清场、聚焦单一元素、再构建新复杂度。

七、从分镜到渲染：与 OpenMontage 渲染管线的衔接

分镜规划完成后，OpenMontage 仓库提供了把 scenes.md 中 Technical Notes 落实为成片的完整闭环。

渲染工具 math_animate

tools/graphics/math_animate.py 是本地免费、无需 API key 的 ManimCE 渲染工具（provider = "manim"、runtime = LOCAL、estimate_cost() == 0.0）。其输入scene_code要求包含继承自Scene的类与construct()方法，from manim import *缺失时会自动补全；场景类名可自动检测（_detect_scene_name会匹配Scene / ThreeDScene / MovingCameraScene / ZoomedScene子类）。它提供与 SKILL.md 配套的质量预设：

同时支持 mp4 / gif / png / webm 格式、透明背景（--transparent）、自定义背景色（如#1a1a2e）与extra_args透传；渲染后通过ffprobe回读时长、分辨率、编码等信息。

渲染规范 manim-usage.md

skills/creative/manim-usage.md 给出了与 scenes.md 中 Timing / Color 字段衔接的工程化约定，例如：方程书写run_time1.5-2.0s、形状创建 0.8-1.2s、变换 1.5s、镜头缩放ease_in_out_cubic1.5-2.0s、列表揭示用LaggedStart且lag_ratio=0.1-0.2、每次重要揭示后至少self.wait(1.5)；每个场景最多同时揭示 3-4 个新视觉元素；默认 2D（Scene/MovingCameraScene），仅当空间关系本身就是概念（如曲面、叉积、法向量）时才用ThreeDScene（3D 走 CPU Cairo 渲染，比 2D 慢 5-10 倍）。配色上，未知量用黄色、矩阵/算符用红色、特征向量/结果用青色、已知常量用蓝色、标注用绿色，并强调避免红绿单色区分以保证可访问性。

安全边界：场景代码静态扫描

由于math_animate会在宿主机上执行调用方（通常由 LLM 生成）提供的 Python 代码，仓库把这一点视为本地代码执行边界，并实现了防御性静态扫描（_scan_scene_code，对应 issue #219）：通过 AST 遍历阻断危险导入（os、subprocess、socket、requests、urllib、ctypes、pickle等）、危险名字（eval、exec、open、__import__、getattr等）以及除__init__、__name__外的全部 dunder 属性访问；仅当调用方显式传入allow_unsafe_code=true时才会跳过扫描。

test_math_animate_safety.py 对这套边界做了系统验证：安全场景（Create(Circle(...))）必须通过扫描；危险导入、危险调用、__builtins__['open']索引绕过、getattr反射、别名绑定（f = open）、().__class__.__bases__[0].__subclasses__()沙箱逃逸、print.__self__到达 builtins 模块等均被拦截；而合法的super().__init__()与语法错误场景不被误伤。测试还确认：被拦截的代码在 Manim 子进程运行之前即被拒绝（monkeypatch 断言subprocess.run不会被调用），allow_unsafe_code=true才会放行到渲染阶段。

对使用manim-composer输出的分镜而言，这意味着场景中涉及的 mobject 与动画类均落在安全白名单内——规划文档越规范，越能顺畅通过扫描并完成渲染，形成"规划 → 编码 → 渲染 → 验证"的完整闭环。

八、使用建议与边界

结合 SKILL.md 与仓库实践，使用本技能时有几点值得注意：

1. 顺序不可颠倒：先运行manim-composer产出 scenes.md，再用manimce-best-practices/manimgl-best-practices实现，最后交给math_animate渲染；跳过规划直接写代码正是 SKILL.md 明确反对的做法。
2. 提问要适配：Phase 2 的澄清问题应根据用户回答动态调整，而不是一次性全量抛出。
3. 模板即检查清单：scenes-template.md 的每个字段都有用途，尤其不要省略Narration Notes（它决定最终成片的节奏）与Implementation Order（它决定工程效率）。
4. 安全边界内创作：渲染侧的代码扫描是防线而非束缚，规范的 Manim 场景代码天然在其允许范围内。

九、总结

manim-composer解决的是数学/科学动画视频生产中"想清楚再动手"的问题：它以三阶段工作流（研究 → 澄清 → 输出 scenes.md）把模糊概念转化为逐场景可实施的分镜规格，以 3b1b 风格原则与六种叙事模式保证内容的讲解质量，并通过 references 与 templates 两套配套文档让方法论可复制、可执行。在 OpenMontage 中，它与math_animate渲染工具、manim-usage.md渲染规范及安全扫描测试共同构成了一条从想法到成片的完整生产链路——这份 SKILL.md，就是这条链路的起点。

【免费下载链接】OpenMontageWorld's first open-source, agentic video production system. 12 production pipelines, 100+ tools, 700+ agent skill and production-knowledge files. Turn your AI coding assistant into a full video production studio.项目地址: https://gitcode.com/GitHub_Trending/op/OpenMontage