Explainer Engine

先看三段成果

引用校验门 · 76 秒 / 证据预算 · 62 秒 / 较早样例：Harness-Field · 57 秒

verified 徽标究竟担保什么？ · 76 秒

用引用校验门自己的代码，说明拿到 verified 徽标要满足什么：普通 token 要按整词匹配，证据要落在引用范围的首行和末行；脚本固定了 commit 时，HEAD 还必须与之一致，工作区也必须干净（除非显式允许）。也说明这个徽标不担保什么。阅读脚本。

公开 9a59b3f 样例；脚本与引用源码可查。脚本未固定提交，verified 徽章不带提交号。旁白为英文，提供中英字幕。打开视频（MP4）

视频第52秒：verifier.py 第328–342行。若实际提交与声明的提交不符，门禁记录“commit_mismatch”；若不允许未提交改动而工作区有改动，则记录“dirty_tree”。下方标注 simplified 与 verified。 — 第52秒画面 · 点开看原图

引用需要多少证据？ · 62 秒

用曲线和代码说明规划器允许一条引用带多少证据 token，以及它为什么丢弃证据过弱的引用。

公开 c345e66 样例；脚本与引用源码可查。脚本未固定提交，verified 徽章不带提交号。旁白为英文，提供中英字幕。打开视频（MP4）

视频第12秒：每行两个证据token的直线，下方标注TOKENS_PER_LINE = 2及evidence.py:56引用。 — 第12秒画面 · 点开看原图

较早样例：Harness-Field · 57 秒

用引擎较早的本地快照制作。把影响 AI Agent 行动的五种因素画成力与路径，尝试让抽象关系更容易理解。

较早的本地样例；历史校验结果无法独立核验。旁白为英文，提供中英字幕。打开视频（MP4）

页面支持把字幕放在画面下方，避免遮住代码。全屏或未启用 JavaScript 时使用播放器原生字幕。视频内嵌文字没有重做，在手机上仍偏小；查看细节可用全屏，或对照脚本。

从脚本到画面

输入是一份 YAML 视频的声明式脚本：一列有序的 beat——图示、带引用的代码标注、概念图——每个都配旁白文本。它是引擎唯一的输入；它没写的东西不会出现在画面上。，写明镜头、旁白和源码引用，不是上传任意代码就能自动得到可靠讲解。下面节选第二段视频中 per-line 镜头的真实脚本，对应画面取自现有视频的第 12 秒。

输入：真实 YAML 节选

code_callout:
  display: "TOKENS_PER_LINE = 2"
  language: python
  cite: "explainer/plan/evidence.py:56"
  evidence: ["TOKENS_PER_LINE", "2"]

这段脚本规定画面上的代码、引用的文件行和必须找到的证据；同一镜头的曲线写为 2 * x。画面代码是标注为 simplified 的简化视图，不冒充逐字源码。查看完整脚本。

检查引用引用校验门检查引用行中是否包含脚本声明的证据：普通 token 按整词匹配，引用范围的首行和末行都要有证据。只要有一条引用不通过，就在生成场景代码之前停止渲染。
按固定规则生成场景脚本编译成用代码生成数学、技术类动画的库。场景是代码而不是时间线剪辑——正因如此，生成器才能确定性地产出这些场景。场景代码，这段代码不由语言模型编写。
渲染与配音由 Manim 渲染画面，旁白由语音合成服务生成；这里的样例同时提供中英字幕轨。

另外，可选的 explainer plan 会调用语言模型，从指定源码范围起草脚本。它是前面的准备步骤，草稿仍需通过同一道引用校验门；校验门检查的是引用，不是旁白。模型不在渲染阶段临时生成画面。

能核对哪些证据

两份公开脚本都能在 v0.2.0 上通过校验。核对时只需轻量安装，不装 manim，也不需要系统库：

pip install -e ".[verify]"
explainer verify examples/evidence-budget.story.yaml

这条命令只检查引用，不会重新渲染视频。它不证明讲解语义正确，也不证明教学效果。通过校验门之后，verify 还会检查代码生成器能否接受这份脚本；整个过程只读文件，不渲染、不合成旁白，也不联网。换成 examples/citation-gate.story.yaml 也一样能跑。

渲染需要完整安装 pip install -e ".[explainer]"，另外要装仓库 README 列出的 cairo/pango、ffmpeg 和 LaTeX 系统包，合成旁白时还要联网。桌面 GUI 单独安装：pip install ".[gui]"。

explainer verify 和 explainer render 的退出码：

0：成功。
2：脚本无法加载或格式校验不通过，或者代码生成器拒绝了它。
3：引用校验门未通过。
4：渲染失败。没装 manim 时，render 会在写出任何文件之前停在这里，并给出安装命令。

证据预算视频从公开 commit c345e66 渲染；该 commit 中的脚本与被引用源码：

规划器的证据预算是每行两个 token 的位置，下限五个、上限二十四个；少于两个 token 或没有强 token 的引用，会被规划器丢弃。引用校验门本身不执行这套预算；它在被引用的行里核对声明的证据。证据预算视频从 c345e66 渲染、引用校验门那段从 9a59b3f 渲染，出处都由本站说明，画面本身不能证明这一点。此后源码改动让部分被引用的行换了位置，v0.2.0 上的脚本改引新行号，证据不变，所以视频里的引用标注可能与现在的脚本不同。两份脚本都引用所在仓库，没有固定 commit，因此徽标只写 verified，不带 commit。

关于较早的 Harness-Field 样例

Harness-Field 视频来自更早的 diagram-canvas 本地快照，是引擎实际输出。五种力来自研究知识库；画面上的 simplified 标签与 verified @ commit 徽标，标出简化视图以及「memory force」所引用的源码行和 commit。当时在渲染前通过了引用校验门，但历史校验结果缺少公开运行证据，无法由外部独立核验。它的脚本没有公开。视频能展示产物与这些标记，不能替代那份运行证据。

取舍与约束

动画可以让关系更直观，也可能让一个错误说法显得更可信。这里的校验只能约束引用，不能代替对讲解本身的判断。

引用对不上，就停止渲染。引用校验门检查声明的证据是否按整词出现在源码中、是否落在首行和末行，所以引用范围一旦错位，通常会直接不通过，而不是继续挂着徽标；若脚本固定了 commit，还会检查仓库 HEAD 是否匹配，并拒绝未显式允许的脏工作区。 代价：写脚本时需要维护可解析的引用，源码变动后可能要重新调整。在 v0.1.0 上能通过的脚本，到 v0.2.0 可能不再通过。

简化视图保留出处标记。simplified 与 verified 徽标呈现的是校验门的结论，不是讲解正确性的保证。 代价：画面要留空间给标签和引用，实际可用于图与代码的区域更小。

模型起草，固定规则生成代码。相同脚本通过确定性代码生成得到相同场景代码；实际视频仍受渲染环境、字体和旁白资源影响。 代价：新的镜头类型需要修改引擎，不能只靠改提示词；规划器也不能绕过校验门。

与桌面工具共用渲染核心。同一套与 Qt 无关的核心也供批量渲染 GUI 使用，GUI 有单独的安装选项。 代价：核心改动需兼顾两个使用方，不能为了脚本运行方便而阻塞 GUI。

实现记录：「共用代码」和「共用一个包」，是两个决定

目前进展

源码公开，处于预发布阶段。当前 tag 是 v0.2.0。它的引用校验门比首个公开 tag v0.1.0（2026-10-15，UTC）更严格，具体改动见仓库的更新日志。教学效果没有经过验证。目前没有承诺到里程碑的计划；仍待回答的问题是：哪些关系适合用动画解释，以及怎样让讲解更容易理解、引用更容易核对。

角色: 个人项目
状态: 源码公开、预发布
tag: v0.2.0
关键结果: 已有三段实际视频；引用校验不代表讲解语义正确或教学效果已验证。
技术栈: PythonManim带引用的代码生成
链接: 源码

使用边界

不是上传任意代码就能生成可靠讲解的工具；输入仍是一份明确的脚本。
不是渲染时由 LLM 即兴生成视频；AI 规划器只负责可选的脚本起草。
图示画布能把关系做成动画，但视频是否有助于学习，还没有验证。
画面代码是有引用的简化视图，不是逐字源码查看器。
引用校验不证明讲解语义正确。徽标给出校验结论，需要核对具体说法时仍应看源码链接与证据。
Harness-Field 视频的脚本没有公开，因此它的历史校验结果无法独立核验。

← 全部作品

把代码和技术概念，讲得更直观。