Manimai - AI 多Agent驱动的 Manim 动画生成器

一个多 Agent 协作的 Manim 动画生成器，按 Planner → Coder → Reviewer → Renderer 的流程，把自然语言提示转成 3B1B 风格的数学动画。

快速开始

环境要求

• Python 3.10+
• LaTeX 发行版（用于数学公式渲染）
• FFmpeg（用于视频处理）

安装

git clone https://github.com/yourusername/manimai.git
cd manimai
pip install -r requirements.txt

运行

GUI 模式（默认）：

python main.py

CLI 模式：

python main.py --cli "创建一个旋转的立方体"

多Agent架构

用户输入
    │
    ▼
┌─────────────┐
│   Planner   │  分析需求，分解任务
└──────┬──────┘
       │ PLAN_CREATED
       ▼
┌─────────────┐
│    Coder    │  生成 Manim 代码
└──────┬──────┘
       │ CODE_GENERATED
       ▼
┌─────────────┐
│   Reviewer  │  审查代码质量
└──────┬──────┘
       │ CODE_APPROVED ──┐
       │                 │
       │ CODE_NEEDS_FIX  │ (循环修复)
       ▼                 │
┌─────────────┐           │
│    Coder    │◄──────────┘
└─────────────┘
       │ CODE_APPROVED
       ▼
┌─────────────┐
│   Renderer  │  渲染视频
└──────┬──────┘
       │ RENDER_COMPLETED
       ▼
    输出视频

项目结构

manimai/
├── src/
│   ├── core/                  # 核心框架
│   │   ├── events.py          # 事件定义
│   │   ├── message_bus.py     # 异步事件总线
│   │   ├── agent.py           # Agent 基类
│   │   ├── context.py         # 任务上下文
│   │   └── coordinator.py     # 中心协调器
│   ├── agents/                # Agent 实现
│   │   ├── planner.py         # 需求分析 Agent
│   │   ├── coder.py           # 代码生成 Agent
│   │   ├── reviewer.py        # 代码审查 Agent
│   │   └── renderer.py        # 渲染执行 Agent
│   ├── services/              # 服务层
│   │   ├── ai_clients.py      # AI 客户端（DeepSeek/Gemini）
│   │   ├── config.py          # 配置定义
│   │   ├── database.py        # 数据库操作
│   │   └── manim_runner.py    # Manim 渲染引擎
│   ├── gui/                   # GUI 界面
│   │   ├── main.py            # GUI 入口
│   │   ├── main_window.py     # 主窗口
│   │   └── workers.py         # 后台线程
│   └── cli/                   # CLI 界面
│       └── main.py            # CLI 入口
├── tests/                     # 单元测试
├── data/                      # 运行时数据
│   ├── jobs/                  # 工作区数据
│   └── manimai.db             # SQLite 数据库
├── assets/                    # 静态资源
├── main.py                    # 统一入口
└── requirements.txt           # 依赖清单

技术栈

组件	技术
GUI 框架	PySide6 (Qt for Python)
动画引擎	Manim Community Edition
AI 接口	DeepSeek, Gemini (OpenAI SDK 兼容)
异步框架	asyncio
数据存储	SQLite
事件驱动	EventBus

Agent 说明

Agent	职责	输入事件	输出事件
Planner	分析需求，分解为任务列表	TASK_RECEIVED	PLAN_CREATED
Coder	生成或修复 Manim 代码	PLAN_CREATED, CODE_NEEDS_FIX	CODE_GENERATED
Reviewer	静态检查 + AI 审查代码	CODE_GENERATED	CODE_APPROVED, CODE_NEEDS_FIX
Renderer	执行 Manim 渲染	CODE_APPROVED	RENDER_COMPLETED, CODE_NEEDS_FIX

配置

AI 模型

在 GUI 设置或通过数据库配置：

# DeepSeek
deepseek_api_key = "your-api-key"
deepseek_base_url = "https://api.deepseek.com"
deepseek_model = "deepseek-chat"

# Gemini
gemini_api_key = "your-api-key"
gemini_model = "gemini-1.5-flash"

输出参数

• 分辨率: 320x240 ~ 3840x2160
• 帧率: 1-120 FPS
• 质量: l (低) / m (中) / h (高) / k (4K)

示例

# CLI 模式生成动画
python main.py --cli "创建一个3x3矩阵，展示它的转置过程"

# 指定输出参数
python main.py --cli --width 1280 --height 720 --fps 30 "旋转的球体"

评测与可靠性验证

仓库里放了一份数学动画 prompt 评测集，路径是 data/evaluation/math_animation_prompts.json。现在一共有 40 条，覆盖函数图像、几何、线性代数、概率统计、微积分、数论、离散数学等类型。

评测 runner 会同时输出 JSON 和 CSV，方便直接看下面这些指标：

• 首次渲染成功率
• 自动修复后最终成功率
• 平均修复轮数
• 平均端到端耗时
• 平均 API 成本估算
• Provider 调用序列与失败类型

如果只是想先把流程跑通，可以先用 fake provider / fake render，不会消耗真实 API：

python -m src.evaluation.runner --fake-providers --fake-render --limit 2 --variant baseline --variant deepseek_timeout

调试时建议开快速预览，把一次评测的渲染和模型调用时间先压下来：

python -m src.evaluation.runner --limit 5 --variant baseline --fast-preview --skip-planner --no-ai-review --stream --max-output-tokens 1600 --no-save-sections --max-iterations 1 --render-timeout 20 --case-timeout 60 --deepseek-key <key>

正式跑评测时，再换成真实 API key，并让 Manim 真正渲染：

python -m src.evaluation.runner --limit 40 --variant baseline --deepseek-key <key>

下面只放真实跑过的数据，fake provider 的结果不计入。

日期	Provider	实验变体	Prompt 数	范围	首次渲染成功率	自动修复后成功率	平均修复轮数	平均端到端耗时	平均 API 成本	首 token	Provider 耗时
2026-05-11	DeepSeek V4 Flash	baseline_stream_fast	1	function-001 快速预览	100.00%	100.00%	0.00	28.42s	$0.000075	1.24s	23.62s
2026-05-11	DeepSeek	baseline	5	function_graphs 前 5 条	80.00%	100.00%	0.40	107.42s	$0.001567	-	-
2026-05-11	DeepSeek	baseline	1	function-001 烟测	100.00%	100.00%	0.00	219.04s	$0.001385	-	-

工程质量

CI 已接到 GitHub Actions，默认会跑 lint、type check 和 pytest。对应命令：

ruff check src tests
mypy src tests
pytest -q

许可证

MIT License

相关链接

• Manim Community
• DeepSeek API
• Google Gemini