Chalkcast

---

适用人群

• 教育工作者和学生 — 将“讲解傅里叶级数”变成简洁的动画讲解，无需学习 Manim，也不用手动编写 LaTeX。
• STEM 内容创作者 — 几分钟内制作出 3Blue1Brown 风格的动画，无需花费数小时编写代码和调试渲染结果。
• Agent 和工具开发者 — 提供类型化、可验证的 MCP 接口，AI 可从头到尾驱动，并能根据判定结果采取行动，而不是面对无法检查的视频束手无策。

为什么还要做另一个 Manim MCP？

现有的 Manim MCP 服务只给 Agent 一个工具：运行这段代码，返回视频。 Agent 只能盲写 Manim 并寄希望于结果正确——但 Manim 容错率很低（LaTeX 拼写错误、标签超出画面、两项内容重叠、目标对象尚不存在时就触发转场）。视频“渲染成功”了，却依然有误，而 Agent 无从得知。

Chalkcast 为 Agent 配备了视觉能力和修正循环：

author scene ──► render ──► inspect (verification lanes) ──► verdict
     ▲                                                          │
     └──────────────── fix obligations ◄──── needs_fix ─────────┘

每次渲染都会返回证据（产物和采样帧）以及结构化的判定结果。问题会转化为待解决事项，在解决之前阻止导出。完整设计请参阅 docs/SPEC.md。

安装

一条命令（Claude Code；需要 uv）：

claude mcp add chalkcast -- uvx --python 3.12 --from "chalkcast[render]" chalkcast serve

--python 3.12 很重要：Chalkcast 需要 Python ≥ 3.11；如果系统 Python 版本较旧，uv 会下载新版本（macOS 自带 Python 3.9）。之后只需用自然语言提出请求。

也可以使用 pip，安装到任意 Python ≥ 3.11 环境中：

pip install "chalkcast[render]"
claude mcp add chalkcast -- chalkcast serve

[render] 会安装 Manim 和随附的 ffmpeg。渲染公式还需要 LaTeX 发行版。chalkcast doctor 会检查所有依赖，并显示适用于你操作系统的准确修复命令：

chalkcast doctor               # Manim / LaTeX / dvisvgm / physics.sty / ffmpeg
chalkcast demo                 # builds + verifies + renders the demo scene

macOS： pycairo（由 Manim 引入）没有适用于 macOS 的 wheel，需要从源代码构建，因此必须先运行 brew install cairo pkg-config。如果 Manim 的原生依赖是手动构建的，请参阅 scripts/dev-env.sh 和 scripts/serve.sh。

Agent 能获得什么

分组	工具
会话	open_project · inspect_project · close_project
创作	add_scene · add_equation · add_plot · add_area · add_riemann · add_text · add_shape · add_parameter · add_step
编辑	update_object · remove_object（级联）· remove_step
验证	inspect_render（实测，不含视频）· fix_scene（自动修复）
渲染	render_scene · render_frame
导出	export_gif（仍有错误义务时会阻止导出）
发现	inspect_environment

• 连续动画：add_parameter("t")，在绘图表达式或形状锚点（at_x="t"）中使用 t，然后调用 add_step("tween", param="t", value=6.28)。 曲线、面积和锚定的点会逐帧跟随。with_previous=True 会让一个步骤与前一个步骤同时播放。
• **快速失败，不做隐式处理：**编写表达式时会立即验证（使用 AST 白名单：x、数学函数、np.<fn>、已声明参数）。颜色、范围、步骤目标、时间线顺序，以及不适用于某个形状或步骤的参数，都会被拒绝，并提示应如何处理。编辑要么全部成功，要么全部失败。副作用（级联删除、重新分组的步骤、重新声明的参数、默认范围）会在结果中报告。若 export_gif 的渲染早于最近一次编辑，则会拒绝导出。十七次独立审计（发现数依次为 22、17、14、8、4、9、4、7、5、5、7、8、5、8、7、7 和 10；最后八次从头到尾构建真实的讲解动画，并将判定结果与帧进行比较，最后一次通过真实的 MCP stdio 协议进行）中的每项发现，都在 tests/test_ergonomics.py 中由一个测试固定覆盖。
• **忠实绘图：**密集采样；在跳跃点和极点处分割曲线（不虚构垂直线段或过冲）；裁剪到坐标轴范围内。保真度通道会测量绘制曲线与真实函数之间的偏差。如果无法展示积分（函数未定义或超出坐标轴范围，或 y = 0 不可见），则会拒绝绘制面积和黎曼和。

验证如何工作

inspect_render 会构建真实的 Manim 对象，但不编码视频（1–3 s），并对它们进行测量：精确边界框、曲线和坐标轴的墨迹、每个图像中绘制结果与真实函数之间的误差，以及严格的 LaTeX 编译检查（Manim 的批处理模式会悄悄从 LaTeX 错误中“恢复”）。通道包括：构图 · 碰撞 · 易读性 · 时序 · 编译 · 保真度 · 范围。fix_scene 会修复机械性问题（移动、缩放、重新采样），并将其余问题留作 Agent 的待处理义务。

在已标注的场景上进行测量（chalkcast bench、chalkcast bench --holdout N）。 每个留出集都由一位从未看过验证器的作者编写并标注（并逐帧检查）。每个集合首次运行的结果才是真实的样本外数据：

集合	案例数	首次运行：检出率 / 误报率	该次运行暴露的问题
留出集 1	39（24 个有缺陷）	95.8 % / 7.7 %	安全边距要求过严；把混叠误判为跳跃
留出集 2	47（31 个有缺陷）	90.3 % / 12.8 %	编译错误后仍估算噪声；直箭头和方框边只在端点采样；根据边界框高度判断方程大小
留出集 3	44（26 个有缺陷）	96.2 % / 0 %	从未对箭头杆进行采样（只采样箭头尖端）
留出集 4	46（25 个有缺陷）	96.0 % / 0 %	将缩放过程中出现的标签当作有意裁剪而放过

修复每个集合暴露的问题后，所有集合（以及包含 40 个案例的开发集）的得分都达到 100 % / 0 %。此后它们成为回归测试（tests/test_measured.py），不再是独立测量。留出集 3 是在修复集合 1 和 2 的问题后编写的；留出集 4（连续补间、同时播放的节拍、变换、摄像机移动）是在十一轮易用性审计后编写的；每个集合都只运行一次，未做任何改动。留出集 4 是当前的样本外估算。

示例（Agent 的操作）

open_project(theme="chalkboard")
add_scene(title="Area under a parabola")
add_text("Area under y = x^2", y=3)
add_plot(functions=[{"expr":"x**2","color":"YELLOW"}], x_range=[0,2,1], y=-0.8)
add_equation(r"\int_0^1 x^2 \, dx = \tfrac{1}{3}", y=2)
add_step("write", targets=["text_1"])
add_step("write", targets=["plot_1"])
add_step("write", targets=["equation_1"])
add_step("highlight", targets=["equation_1"])
inspect_render()    # -> measured verdict in ~2 s, no video
fix_scene()         # -> repairs framing / collision / fidelity if needed
render_scene()      # -> video + frames + verdict + obligations
export_gif()        # -> shareable GIF (blocked if error obligations remain)

状态

Alpha。已通过数值测试验证科学正确性（tests/test_science.py）：阴影面积等于其积分，黎曼矩形面积等于其总和，绘制的曲线符合其函数（包括 sin 30x），吉布斯峰值等于其理论值。已发布到 PyPI 和 MCP Registry（io.github.FredMichel/chalkcast）。 下一步将进行基于视觉的 intent 验证（参见 docs/SPEC.md）。

许可证

MIT。