HarleyCoops/Math-To-Manim 源代码：https://github.com/HarleyCoops/Math-To-Manim # Math to Manim ### 提出问题 → 获得一段理性的影片 Python 3.10+（https://www.python.org/） Manim CE（https://www.manim.community/） OpenAI Agents SDK（https://openai.github.io/openai-agents-python/） Hermes 助手 许可证：MIT 动作展示 · 架构 · Prime RL · 路线图 · 代理指南 Math-To-Manim 将严肃的数学和物理提示转化为 Manim 解释视频及其产生的可复用构件：意图、前置知识图谱、教案、数学包、故事板、场景规格、生成的代码、验证报告、渲染证据、评审记录和阶段追踪。 浏览本地 GIF 画廊 → 基于代码的工作流：每次运行都可从提示到构件再到渲染进行全程检查。 — ## 这是什么 Math-To-Manim 始于唐纳德·特朗普第二次就职典礼的清晨。2025 年 1 月 20 日大约凌晨 4:30（我的时间），中国 AI 实验室 DeepSeek 在 Hugging Face 上发布了 R1（https://huggingface.co/deepseek-ai/DeepSeek-R1）。我认为这个时机是有意为之：一个斯普特尼克式的信号，表明开放推理模型现在已成为地缘政治现实。我的第一步是克隆 R1 并将其指向数学推理。有趣的地方不仅在于一个推理模型能解决数学问题，更在于通往一个好解释的路径变得可见。一个主题可以变成前置知识，然后变成教学顺序，再变成方程式，然后是屏幕节奏，接着是 Manim 代码，最后是一部影片。M2M2 正是从这个实验中生长出来的管道。 教师、家教、家长、学生、研究人员或代理可以提出一个简短的问题、一个课程想法或一份密集的技术笔记，然后获得一个可检查的解释：概念、缺失的前置知识、想法顺序、屏幕节奏、生成的 Manim 代码，以及可选的渲染视频。渲染结果可以是一个强力的初稿，时长约四到五分钟，使用 LaTeX 进行真实的数学和物理符号表示，而非装饰性的伪数学。 产品不仅仅是 MP4。每次运行的捆绑包保存了导致场景的推理工件和数学内容，这使得输出对调试、代理交接以及强化学习（如 Prime Intellect 修复环境）非常有用。 下一步方向是递归编辑。受递归语言模型（https://arxiv.org/abs/2512.24601）启发，目标是将一部完成的影片及其运行捆绑包视为一个可被代理检查和修订的环境。类似“重新渲染这个，但倾斜摄像机，使方程更易读”的请求，应能回溯到场景计划和 Manim 代码，重新计算正确的更改，验证它，再次渲染，并留下可用于训练下一个策略的新痕迹。 这个仓库就是那个循环的构建日志：代理学习推理复杂主题、保留其工作成果，并将推理转化为视觉解释。 —— Christian 如今，这意味着一个持久的代理管道，包含： - 受众感知的请求工件，从小学直觉到高级符号； - 受原始反向知识树启发的前置知识-故事管道； - 每个阶段之间的类型化 Pydantic 工件； - 适用于规划和生成的 OpenAI Agents SDK 适配器； - 可选的 Codex CLI 支持的代码生成，用于基于订阅验证的迭代； - 每次生成的可重现的 runs// 捆绑包； - 静态验证、渲染元数据、评审工件和清单，易于在 CI 或其他代理中检查。 设计原则很简单：故事先于符号，几何先于代数，工件先于副作用。 — ## 反向推理管道 普通的文本到代码演示会从请求直接跳到 Python。Math-To-Manim 有意绕远路：它从最终概念反向推理到前置知识，然后通过一个可教学的视觉序列向前推进。 代码路径在 math_to_manim/pipeline/runner.py 中明确给出。AnimationPipeline.generate() 运行一个固定的阶段链：IntentAgent、PrerequisiteGraphAgent、CurriculumAgent、MathAgent、StoryboardAgent、SceneSpecAgent、ManimCodeAgent、StaticReviewAgent、RenderAgent、VideoReviewAgent 和 PublisherAgent。 | 阶段 | 存在的原因 | 工件 | | — | — | — | | 意图 | 明确学习者真正在问什么。 | intent.json | | 反向前置知识 | 构建目标概念之前所需的知识图谱。 | knowledge_graph.json | | 课程 | 将图谱转化为可教学的顺序。 | curriculum.json | | 数学包 | 选择定义、方程、假设和示例。 | math_packet.json | | 故事板 | 在代码存在之前决定屏幕节奏。 | storyboard.json | | 场景规格 | 将视觉计划编译为 Manim 对象、动画、时间和摄像机注释。 | scene_spec.json | | 代码、验证、渲染、评审 | 生成可运行的 Manim，用静态检查门控，在允许时渲染，并打包证据。 | generated_scene.py、报告、清单 | 这样每次运行都有一个记忆：JSON 合约、生成的代码、渲染结果、评审注释和一个清单。输出不仅仅是一个视频；它是一个从问题到理解再到动画的可检查路径。 关于当前可编辑视频的状态以及计划中的提示/规格/代码编辑循环，请参见路线图。 — ## Prime Intellect RL 修复循环 Math-To-Manim 也正在成为 Prime Intellect 强化学习环境。第一个 RL 目标不是“一次性制作整个视频”。当生成的动画代码失败时，重要的修复动作是：拿类型化的场景计划、有问题的 generated_scene.py 以及验证/渲染证据，然后返回更安全、更简洁且更有可能渲染的修正版 Manim Python。 运行捆绑包作为环境 奖励函数作为评判机制 策略更新作为修复引擎 当前的中心环境是 harleycooper/math-to-manim。一个修复任务携带原始提示、类型化的 scene_spec、生成的 Manim Python、静态验证报告以及可用的渲染/恢复证据。模型必须返回一个严格的 GeneratedCode JSON 块。验证器（Verifiers）奖励检查提议的代码是否能解析、是否定义了预期的 Manim 场景、是否避免了不安全的导入和调用、是否保留了预期的数学术语，并减少了明显的文本/布局拥挤隐患。 text generated_scene.py + scene_spec + validation/render evidence -> Prime Intellect Verifiers environment -> model proposes corrected GeneratedCode JSON -> static reward checks parseability, scene shape, safety, terms, layout -> hosted RL updates the repair policy -> corrected, renderable Manim Python flows back into M2M2 recovery 这使得快速的 RL 循环基于文本和 AST，而较慢的 Manim 渲染器仍然作为审计门控。预期的结果是模型学会了这个仓库的 house style：电影感但可读的场景、稀疏的公式、分阶段字幕、安全的 Manim 代码，以及在第一次恢复尝试中更有可能渲染的脚本。 当前的托管训练状态：环境动作在 Prime 上通过，中心包已发布为 harleycooper/[email protected]，已完成 1 步烟雾测试，并已启动 25 步的 W&B 启用的试点，目标模型为 Qwen/Qwen3.5-35B-A3B。完整的集成说明见 docs/PRIME_INTELLECT_RL.md。 — ## 克隆并运行 ### 1. 克隆 Windows PowerShell： powershell git clone https://github.com/HarleyCoops/Math-To-Manim.git cd Math-To-Manim python -m venv .venv .\.venv\Scripts\Activate.ps1 python -m pip install -U pip python -m pip install -e ".[dev]" python -m pytest macOS / Linux / WSL： bash git clone https://github.com/HarleyCoops/Math-To-Manim.git cd Math-To-Manim python3 -m venv .venv source .venv/bin/activate python -m pip install -U pip python -m pip install -e ".[dev]" python -m pytest ### 2. 运行无 API 烟雾测试 这证明 CLI、工件合约和验证器已连接好，然后您再花费模型或渲染时间： bash math-to-manim generate "Explain why derivatives are slopes" --deterministic --no-render 等效模块形式： bash python -m math_to_manim.cli generate "Explain why derivatives are slopes" --deterministic --no-render ### 3. 使用模型调用生成 设置 OpenAI 密钥并根据需要选择模型： bash export OPENAI_API_KEY="sk-..." export OPENAI_MODEL="gpt-4.1" math-to-manim generate "Explain Fourier epicycles as rotating vectors" --no-render PowerShell： powershell $env:OPENAI_API_KEY = "sk-..." $env:OPENAI_MODEL = "gpt-4.1" math-to-manim generate "Explain Fourier epicycles as rotating vectors" --no-render ### 4. 当需要 MP4 输出时安装渲染扩展 Python 渲染依赖： bash python -m pip install -e ".[dev,render]" 还需要系统渲染依赖才能获得真实的 Manim 输出，特别是 FFmpeg 和 LaTeX（用于 MathTex）。在 Debian/Ubuntu/WSL 上： bash ./scripts/bootstrap-render.sh 包列表位于 requirements-system.txt 中。 — ## Codex CLI 代码生成路径 Math-To-Manim 可以保持类型化规划管道，同时将 Manim 代码生成和修复循环通过本地认证的 Codex CLI 会话发送。 首先检查 Codex： bash codex --version codex exec "Say ready from inside this repo" 然后通过 Codex 路由代码生成： bash math-to-manim generate "Explain derivatives as slopes with a cinematic tangent-line reveal" \ --codegen-provider codex-cli \ --codex-full-auto \ --style cinematic \ --quality l 早期的规划阶段仍保留在类型化适配器上；只有生成代码和修复阶段先移动。这使得迁移是渐进的，而非全有或全无。 — ## 写入磁盘的内容 一次生成会写一个自包含的运行捆绑包： text runs// request.json intent.json knowledge_graph.json curriculum.json math_packet.json storyboard.json scene_spec.json generated_code.json generated_scene.py validation_report.json render_result.json review_report.json trace.jsonl # 启用追踪时的阶段边界事件 recovery_manifest.json # 在 recover-render 后 draft_review/ draft_review.md contact_sheet.png frames/ animation_package.json manifest.json 在运行捆绑包内编辑 generated_scene.py 后，重新运行恢复路径： bash math-to-manim recover-render runs/ --quality l 该命令刷新验证、渲染、评审、草稿评审资产以及 recovery_manifest.json，而无需重新生成上游规划工件。 包布局： text math_to_manim/ agents/ # 阶段适配器 schemas/ # 版本化工件合约 tools/ # 图、验证、渲染、视频、工件助手 pipeline/ # 编排、追踪、修复循环 rendering/ # Manim 和 FFmpeg 封装 review/ # 静态和视觉评审评分 — ## Hermes Agent Hermes 是围绕此仓库的贡献者/操作员代理。它不被 Math-To-Manim 导入，也不是运行时依赖；它像开发者一样使用仓库：读取文件、搜索代码、修补文档和代码、运行终端检查、检查生成的工件、查看帧或 GIF、跟踪待办事项、委托更大的工作，并通过技能保持稳定的上下文。 这使得 Hermes 对于维护反向推理管道很有用，而不会成为其一部分。一个 Hermes 会话可以检查 AGENTS.md、pyproject.toml、模式、测试和 runs// 捆绑包；运行 pytest、CLI 烟雾命令、Manim、FFmpeg 和 git 检查；然后验证文档、代码和展示媒体是否仍然匹配工件合约。 仓库本地的 Hermes 技能位于 hermes/skills/ 下。旧的 Claude ./skill 路径已成为历史；当前的贡献者指南在 AGENTS.md 中，启动说明在 docs/HERMES_LEARNS_MANIM.md。 — ## 动作展示 十六个精选的 GIF 在 docs/showcase/assets/ 下跟踪，作为 Math-To-Manim 视觉解释的艺术方向目标。 几何作为奇观 拓扑作为编舞 混沌作为直觉 查看带有描述的完整画廊： docs/showcase/README.md。 ### 从渲染制作适合 README 的 GIF bash MP4="media/videos/your_scene/480p15/YourScene.mp4" ffmpeg -y -ss 95 -t 24 -i "$MP4" \ -vf "fps=12,scale=720:-1:flags=lanczos,split[s0][s1];[s0]palettegen=max_colors=96[p];[s1][p]paletteuse=dither=bayer:bayer_scale=5" \ docs/showcase/assets/your-clip.gif 调整 -ss 和 -t 以捕获您想要的教学节拍。 — ## 许可证 MIT.