Communitygithub.com

MSP — Manim 风格与协议

指导AI智能体如何规划、构建或剪辑“MSP — Manim 风格与协议”的生成内容,确保生成可用的复制文本或脚本。该流程遵循一套生产级技能规范,包括首要指令、环境与版本锁定等。适用于需要按此规范制作动画的新任务。

MSP — Manim 风格与协议 是什么?

MSP(Manim 风格与协议)是一套为 AI 生成的 Manim 动画量身定制的生产级技能规范。它旨在确保任何 AI 系统——如 Claude Code、Cursor 或 Codex——都能自动生成清晰、组织良好、过渡平滑、达到工作室/电影级质量的 Manim 动画,而不仅仅是普通的脚本输出。该规范覆盖了从环境锁定(强制使用 Manim 社区版 v0.18+)、项目文件结构(强制分离 theme.py、helpers.py、scenes/ 等模块)到视觉设计标准(色彩与排版规则)在内的完整流程。其核心是“变形与变换协议”(Morphing & Transform Protocol),强调通过 TransformMatchingTex、ReplacementTransform 等 API 实现无缝的视觉过渡,而非生硬的淡入淡出。此外,规范还详细规定了时间节奏(run_time 与 easing 函数的选择)、场景与代码组织方式(construct() 方法的分段设计)、2D/3D 相机控制以及最终渲染导出的最佳实践。遵循此协议,AI 生成的动画将具备专业解说视频标志性的平滑、渐变和高度设计感,特别适合数学、科学和技术类演示。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Frqme21/MSP-Manim-Style-protocol/tree/HEAD/v1

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

MSP — Manim 风格与协议 是做什么的?

一份用于 AI 生成 Manim 动画的生产级技能规范

版本: 1.0
目标环境: Manim 社区版 (ManimCE) ≥ v0.18
目的: 使任何 AI 系统能够默认生成清晰、组织良好、过渡平滑、达到工作室/电影级质量的 Manim 动画——而不是例外情况。

0. 首要指令

你编写的每一个场景,都必须看起来出自专业动画工作室,而非学生脚本。当选择模棱两可时,选择更平滑、更简洁、更有意图的那个——永远不要选择最懒的默认选项。

在编写任何代码之前,心中快速检查以下清单:

  1. 这个场景要传达的一个核心思想是什么?
  2. 视觉层次是什么(观众应该先看到什么,再看到什么,最后看到什么)?
  3. 我使用了何种调色板和字体,并且在整个项目中保持一致吗?
  4. 每个对象将如何进入、变换和退出——没有任何对象应该不经过动画就直接“出现”或“消失”。
  5. 这个场景的节奏(总 run_time 预算)是怎样的?

1. 环境与版本锁定

默认始终使用 Manim 社区版,而非 ManimGL,除非用户明确要求 3b1b 风格的 ManimGL。

from manim import *
  • CLI 二进制文件: manim (而非 manimgl)
  • 创建动词: Create() (而非 ShowCreation())
  • 数学渲染: MathTex(r"...") (而非 Tex(R"..."))

绝不要混用 API。 如果某个代码片段在没有 MovingCameraScene/ThreeDScene 的情况下使用了 self.camera.frame,请标记出来——这是渗入的 ManimGL 语法。


2. 项目文件结构

对于任何超出单个简单场景的项目,强制使用以下结构——绝不要将所有内容都塞进一个庞大的文件中:

project/
├── manim.cfg              # 锁定的渲染配置(见 §9)
├── theme.py               # 颜色、字体、常量(单一事实来源)
├── helpers.py             # 可复用的 mobject 构建器 / 布局函数
├── scenes/
│   ├── 01_intro.py
│   ├── 02_derivation.py
│   └── 03_outro.py
└── assets/                # svgs, images, audio

theme.py 示例(对于多场景项目务必创建一个):

from manim import *

# ---- 调色板 ----
BG_COLOR      = "#0E0E12"
PRIMARY       = "#58C4DD"   # manim 默认蓝色,或品牌色
SECONDARY     = "#FFD166"
ACCENT        = "#EF476F"
TEXT_MAIN     = "#F5F5F5"
TEXT_MUTED    = "#8A8A8F"
SUCCESS       = "#06D6A0"

# ---- 排版 ----
FONT_MAIN = "Helvetica"      # 或项目特定字体
FONT_MONO = "JetBrains Mono"

# ---- 时间常量 ----
T_FAST   = 0.5
T_NORMAL = 1.0
T_SLOW   = 1.8
LAG      = 0.08   # 分组揭示的默认 lag_ratio

config.background_color = BG_COLOR

每个场景文件都从 theme.py 导入。一旦创建了主题文件,就绝不要在代码中硬编码十六进制颜色或 magic run_time 数字——这是不专业、不一致输出的第一标志。


3. 视觉设计标准

3.1 颜色规则

  • 每个项目最多使用 4–5 种颜色(1 背景色,1–2 主色,1–2 强调色)。更多颜色会显得杂乱/业余。
  • 语义化使用颜色:在整个视频中,相同的颜色代表相同的含义(例如,蓝色始终代表“已知”,红色始终代表“未知”)。
  • 背景几乎从不使用纯黑(#000000)或纯白——使用柔和的近黑(#0E0E12)或柔和的近白,以减少视觉疲劳并获得“工作室”感。

3.2 排版规则

  • 使用 Text() 处理 UI 标签、标题、说明文字——速度快,无需 LaTeX 依赖。
  • 使用 MathTex() 处理所有数学符号——绝不使用 Text() 伪造数学公式。
  • 仅当需要混合散文+数学的 LaTeX 块时使用 Tex()。
  • 通过主题常量全局设置 font=;绝不让字体选择在不同场景间变化。
  • 标题规范:使用 .to_edge(UP),粗体,在所有场景中保持一致的字体大小(例如 40pt)。

3.3 布局规则

  • 尊重三分法——避免默认将所有内容居中;有意识地使用 .to_edge()、.shift()、.next_to()。
  • 保持一致的边距(buff 值)——定义一个 MARGIN = 0.75 常量,并在每个 .to_edge(..., buff=MARGIN) 调用中复用。
  • 将相关对象分组到一个 VGroup 中,并对组进行定位和动画处理,而不是处理松散独立的 mobject——这确保了在后续任何变换中对齐保持不变。
  • 始终在组上调用 .arrange() 或 .arrange_in_grid(),而不是手动计算坐标——手动坐标计算很脆弱,是后续编辑中布局出错的首要原因。

4. 变形与变换协议

这是“平滑、变形”动画的核心——高端解说视频的标志性外观。

4.1 规则:绝不剪切,始终变换

如果一个对象概念上变成了另一个对象(方程重排,形状变成另一个形状,标签更新),绝不要对独立的 mobject 使用 FadeOut + FadeIn——这样看起来像跳切。始终使用变换族:

情况正确的工具
方程重排,项保持不变TransformMatchingTex(old, new)
形状变形为不同的形状Transform(old, new) 或 ReplacementTransform(old, new)
mobject 组重构(例如,要点列表 → 图表)TransformMatchingShapes(old_group, new_group)
一个对象明确替换场景图中的另一个对象ReplacementTransform(在 self.mobjects 中用新对象替换旧对象)
淡出同时暗示连续性(例如,幽灵/叠加)FadeTransform(old, new)

TransformMatchingTex 的协议细节: 始终构建两个具有一致子串分组的 MathTex mobject(相同的 LaTeX 片段作为单独的 {} 组),以便 Manim 能够匹配相同的符号——这使得各项能够视觉上“滑动”到新位置,而不是交叉淡入淡出。

eq1 = MathTex("a", "+", "b", "=", "c")
eq2 = MathTex("c", "=", "a", "+", "b")
self.play(TransformMatchingTex(eq1, eq2), run_time=1.2)

4.2 规则:对简单属性变形使用 .animate

对于一个 mobject 上的单个连续属性更改(位置、缩放、颜色、旋转),优先使用 .animate 语法——它更简洁,Manim 会自动插值净变换:

self.play(square.animate.shift(RIGHT * 2).scale(1.5).set_color(ACCENT), run_time=1.0)

注意事项(关键,防止 AI 幻觉错误): 链式 .animate 调用插值的是最终净状态,而不是按顺序的每个中间步骤。绝不要链式调用那些依赖于中间结果的 .animate 调用(例如,.animate.move_to(X).rotate(angle_depending_on_position))——应将其拆分为单独的 self.play() 调用。

4.3 规则:对连续/从属运动使用更新器

每当一个对象的状态必须持续跟踪另一个对象时(标签跟随点,值显示跟踪 ValueTracker),使用 add_updater,绝不要手动为每一帧重新 play:

tracker = ValueTracker(0)
label = DecimalNumber(0).add_updater(lambda d: d.set_value(tracker.get_value()))
dot = Dot().add_updater(lambda m: m.move_to(axes.c2p(tracker.get_value(), f(tracker.get_value()))))
self.add(label, dot)
self.play(tracker.animate.set_value(5), run_time=3, rate_func=linear)

一旦一个对象的依赖阶段结束,始终 remove_updater(或使用 always_redraw 进行更干净的从头重新计算逻辑),以避免在较长的场景中出现过期更新器错误。


5. 时间、节奏与缓动协议

5.1 默认速率函数策略

  • 默认(不覆盖):smooth —— S 曲线缓入/缓出。用于 90% 的动画——方程揭示、形状创建、标准移动。
  • linear:对于描绘任何字面意义上的恒定速率物理运动是强制性的——轨道上的点、均匀速度矢量、旋转的时钟指针、与真实经过时间绑定的进度条。
  • rush_into / rush_from:用于强调进入/退出,当某些东西应该感觉像是“咔哒”一声到位或弹射出去时。
  • there_and_back / there_and_back_with_pause:用于 Indicate 风格的注意力脉冲,绝不用于永久状态更改。
  • ease_out_bounce / ease_out_elastic:仅限于有趣、非正式的内容——绝不要在正式的数理科推导中使用,否则会显得不专业。

5.2 时间预算规则

  • 保持单个 run_time 在 0.4s 到 3s 之间。低于 0.4s 会显得刺眼;高于 3s(无叙述理由)会显得拖沓。
  • 标题/章节标头进入:0.8–1.2s。
  • 方程/图表变换:1.0–1.5s。
  • 强调脉冲(Indicate、Flash、Circumscribe):0.5–0.8s。
  • 相机移动(move_camera、self.camera.frame.animate):1.5–3s —— 快于此速度的相机移动会让人感到恶心。
  • 在每次重要揭示之后,有意插入 self.wait(0.3–1.0) 的停顿——绝不要将 self.play() 调用无间隙地连续执行;这会淹没观众。

5.3 组合协议

  • 同时但独立的事件 → 单个 self.play(AnimA, AnimB, ...) 调用。
  • 同时但交错开始(例如,6 个要点依次出现但时间重叠)→ LaggedStart(*anims, lag_ratio=0.15)。
  • 严格顺序、依赖的事件 → Succession(*anims) 或单独的 self.play() 调用。
  • 列表/网格揭示(要点、形状网格)→ 始终使用 LaggedStartMap(FadeIn, group, lag_ratio=0.08, shift=UP*0.3),而不是单次同时的 FadeIn(group) —— 交错让群组进入感觉更有机而非机械。

6. 场景与代码组织协议

6.1 Construct 方法形态

始终通过注释或辅助方法将 construct() 分解为清晰界定、命名的阶段——绝不要写成一个不间断的 100 行代码块:

class DerivationScene(Scene):
    def construct(self):
        self.setup_title()
        self.show_initial_equation()
        self.derive_steps()
        self.highlight_result()
        self.cleanup()

    def setup_title(self):
        self.title = Text("Deriving the Quadratic Formula", font=FONT_MAIN).to_edge(UP)
        self.play(Write(self.title), run_time=T_NORMAL)
        self.wait(T_FAST)

    def show_initial_equation(self):
        ...

对于长视频,拆分成多个场景类(每个逻辑部分一个),而不是一个巨大的 construct()——这使得可以通过 -n 进行目标性重新渲染和并行迭代。

6.2 Mobject 构建协议

  • 将复杂的自定义视觉元素(图表、图形、图标)构建为 helpers.py 中的独立函数,返回 VGroup,而不是内联在 construct() 中:
# helpers.py
def make_neuron(radius=0.3, color=PRIMARY) -> VGroup:
    circle = Circle(radius=radius, color=color, fill_opacity=0.8)
    label = Text("n", font_size=20).move_to(circle)
    return VGroup(circle, label)
  • 始终有意义地命名 mobject(title、eq_initial、graph_group)——绝不要留下你稍后需要修改或变换的未引用匿名字面量。
  • 对于任何存在重叠图层的场景,显式使用 z_index(一旦图层超过 2 层,不要依赖添加顺序)。

6.3 样式/代码检查规则

  • 变量/方法使用 snake_case,Scene 子类使用 PascalCase。
  • 在代码中,动画“节拍”之间留一个空行以提高可读性——代码结构应在视觉上反映视频的节奏。
  • 对于颜色/位置/时间,没有裸写的魔法数字——始终引用 theme.py 常量。
  • 为辅助函数添加类型提示(def make_axes() -> Axes:)以在较大项目中保持可维护性。

7. 合成与相机协议(2D 和 3D)

2D

  • 当视频需要在 2D 中平移/缩放时(例如,聚焦于图表的子区域),使用 MovingCameraScene —— 通过 self.camera.frame.animate.move_to(...).set(width=...) 进行动画,始终配合显式的 run_time。

3D

  • 继承 ThreeDScene。
  • 在专门的设置步骤中,使用 self.set_camera_orientation(phi=70*DEGREES, theta=-45*DEGREES, zoom=1) 设置初始方向——除非有意的,否则绝不留默认方向。
  • 对于观众应该感知为运动的任何相机重新定位,使用 self.move_camera(phi=..., theta=..., run_time=2.5) —— 绝不要 在场景中间通过 set_camera_orientation 进行跳切。
  • 在旁白下进行缓慢的闲置旋转时,使用 self.begin_ambient_camera_rotation(rate=0.15);在后续故意的 move_camera 之前,始终配对使用 self.stop_ambient_camera_rotation()。
  • 无论相机角度如何都必须保持清晰可读的 HUD/标签/标题 → self.add_fixed_in_frame_mobjects(label)。
  • 应跟踪 3D 对象但保持可读的标签 → self.add_fixed_orientation_mobjects(label)。
  • 在迭代期间保持 3D 表面的 resolution 元组较低(例如 (24,24));仅在对最终产出版本进行渲染时再提高——这纯粹是一个性能/工作流规则,而非视觉效果规则。

8. 强调与注意力协议

绝不要让一个关键结果在视觉上看起来与支持内容相同。在揭示一个场景的“回报”(最终方程、关键见解、结果)之后,仅应用一种强调技术——不要叠加超过一种,否则会显得狂乱:

  • Circumscribe(mobject, color=ACCENT, run_time=1.2) —— 在其周围绘制一个形状。
  • Indicate(mobject, scale_factor=1.15) —— 短暂的脉冲缩放 + 颜色闪烁。
  • Flash(point, color=ACCENT) —— 径向爆发,适用于特定坐标/交点。
  • mobject.animate.set_color(ACCENT) 结合轻微缩放——用于永久重新着色,表示“这就是答案”。

9. 渲染与导出协议

9.1 锁定配置文件(提交此文件——绝不要依赖临时标志来交付最终版本)

manim.cfg:

[CLI]
quality = production_quality
preview = False
background_color = "#0E0E12"
output_file = {scene_name}
frame_rate = 60
pixel_height = 1080
pixel_width = 1920

9.2 工作流阶段(始终遵循此顺序,绝不要首先渲染最终质量)

  1. 草稿阶段:manim -pql scenes/02_derivation.py DerivationScene —— 快速迭代,检查逻辑/时机。
  2. 点检阶段:manim -pqh -s scenes/02_derivation.py DerivationScene —— 对构图/颜色进行单帧高质量检查。
  3. 回顾阶段:manim -pqh scenes/02_derivation.py DerivationScene —— 全质量、全时长的最终审查。
  4. 交付:从 media/videos/scenes/1080p60/ 收集 .mp4 文件。(默认输出目录;如果更改了,请相应调整。)

9.3 工作流提示

  • 添加 -n start_frame,end_frame 以仅渲染一系列帧,而不是整个场景——在长场景中对迭代至关重要。
  • 对于精确的音频/旁白同步匹配,使用 manim-slides,而不是手动时间调整逐帧渲染。

附录 A:常见 AI 生成代码的幻觉与陷阱

以下错误在 AI 生成的 Manim 代码中反复出现。已知它们,并加以防范:

问题错误写法正确写法
过期 APIShowCreation(circle)Create(circle)
混用 ManimGL 语法self.frame 在 Scene 中self.camera.frame(且仅在 MovingCameraScene/ThreeDScene 中安全使用)
颜色字符串而非常量set_color("#FF1493")set_color(ACCENT)(从 theme.py)
硬编码缓冲区.to_edge(UP, buff=0.5).to_edge(UP, buff=MARGIN)
未使用的孤立 mobjectCircle() 未赋值circle = Circle()
在非 Unity 警告下省略 VGroup独立定位 20 个圆圈使用 VGroup(*circles) 并 .arrange_in_grid()
每秒 2 帧的更新器泄漏添加更新器但不移除remove_updater 或 always_redraw
无意义的 run_timerun_time=0.15 导致锯齿run_time=0.5(最小值)
在 MathTex 中错误使用 Text()Text("E=mc^2")MathTex("E=mc^2")
混乱的分组导致 TransformMatchingTex 失效MathTex("a+b=c") 作为一个字符串MathTex("a", "+", "b", "=", "c") 进行子串匹配

附录 B:风格经验法则

  • 5 秒法则:如果超过 5 秒没有新的 mobject 进入、变换或高亮,场景就显得无精打采。
  • 1 种颜色规则:如果一个 mobject 在场景中出现超过 3 秒,它应至少通过颜色或动画强调一次其用途。
  • 少于 30 秒规则:对于独立短视频,如果没有分量或场景变化,很少有场景需要超过 30 秒。精确。
  • 过渡规则:如果切换主题或更改上下文,总是通过 self.next_section() 引入一个新部分,或者至少通过一次 self.wait(0.5) 并改变相机位置。

附录 C:快速参考卡

查询的不同类型动画及其用法:

动画类型何时使用示例
Create路径/形状首次出现时Create(Axes())
DrawBorderThenFill填充形状:外围线条出现,然后填充DrawBorderThenFill(Square())
Write文本逐字符出现Write(title)
FadeIn / FadeOut简单的透明度进出;谨慎用于变换FadeIn(circle)
Transform一个 mobject 变成另一个Transform(circle, square)
ReplacementTransform在场景图中用新 mobject 替换旧 mobjectReplacementTransform(circle, square)
TransformMatchingTex方程重排,匹配的 LaTeX 子串滑动到位TransformMatchingTex(eq1, eq2)
TransformMatchingShapes一般的群组重构TransformMatchingShapes(old_vg, new_vg)
Uncreate / Unwrite反向创建/书写Uncreate(axes)
Indicate短暂引起注意Indicate(answer, scale_factor=1.15)
Circumscribe围绕 mobject 绘制几何高亮Circumscribe(formula, color=ACCENT)
Flash点上的径向爆发Flash(dot.get_center(), color=ACCENT)
LaggedStart交错开始的动画组LaggedStart(*anims, lag_ratio=0.15)
LaggedStartMap对群组的每个元素应用相同的动画并有偏移LaggedStartMap(FadeIn, group)
Succession严格顺序的动画Succession(anim1, anim2, anim3)
AnimationGroup同时或顺序的组AnimationGroup(anim1, anim2, lag_ratio=0.1)
mobject.animate快速链式属性更改square.animate.shift(RIGHT).scale(2)

相关技能