LLM 输出讲解方法论（Karpathy Explainer Methodology）
让 LLM 成为更好的讲解者：在正确的时机，用正确的机制，把内容讲给正确的人。
核心信念（判断讲解质量的标尺）
讲解质量 = 受众能基于它正确行动的程度。 不是字数、不是格式、不是看起来聪不聪明。
工作流程（六步，不可跳步）
第 1 步：受众四问（必做，哪怕只在心里回答）
- 受众是谁？（CEO / 技术同行 / 新员工 / 客户 / 公众 / 未来的自己）
- 他们卡在哪？（缺背景知识？有错误先入之见？立场对立？时间不够？）
- 他们已经相信什么？（先对齐共识，再引入新信息；对抗姿态 = 讲解失败）
- 他们读完要做什么？（批准预算？学会操作？改变看法？仅仅是知道）—— 这个问题决定工件类型
第 2 步：决策矩阵选机制
| 受众/场景特征 | 首选机制 | 关键理由 |
|---|---|---|
| 跨语言、跨时间、精准度优先（给 agent 读、技术文档、合同、操作手册） | A 受控语言 | 消除歧义是唯一目标，不追求"好听" |
| 关系、流程、对比、结构、层级（方案架构、论文方法、因果关系） | B 图表 | 空间布局本身承载论证逻辑 |
| 有审美/交互/演示要求；非技术受众；内容需要"产品感" | C 单文件 HTML 工件 | 交互式阅读 + 视觉传达 + 零部署分享 |
| 概念有动态过程；培训/课堂场景；视觉通道收益 > 文字 | D 讲解视频 | 脚本先行，视觉为脚本服务 |
| 沟通受阻（距离/层级/立场）；演示优于讲述 | E 一次性演示工具 | 让受众自己操作，结论从操作中长出来 |
| 单一机制用了仍讲不懂 | 换机制或组合（常见：B→C，A→D 字幕） | 卡住不是受众笨，是机制错配 |
机制详情与写作规范见 references/module-a~e-*.md。矩阵只是默认推荐，可按受众判断覆盖。
第 3 步：分层拆解（讲解内容的通用结构）
任何讲解内容按此骨架组织（详细模板见 references/decision-matrix.md）：
- 一句话版本（电梯陈述，≤30 字）
- 三句话版本（背景 → 核心 → 意义）
- 分段版本（每层一个论点，层间有过渡句）
- 支撑层（证据、数据、例子、边界情况）
检查点：上一层讲不懂，才能加下一层。默认交付第 3 层，附上第 1 层作为开头摘要。
第 4 步：按模块规范生成
- 模块 A →
references/module-a-ste100.md - 模块 B →
references/module-b-diagram.md - 模块 C →
references/module-c-html.md（模板在assets/explain-page.html） - 模块 D →
references/module-d-video.md（脚本模板在assets/manim_scene_template.py） - 模块 E →
references/module-e-disposable.md
第 5 步：验收清单自检（交付前必过）
通用清单（任何输出）：
- 受众四问的答案能在输出中找到对应设计（不是通用模板腔）
- 开头 30 秒内出现"一句话版本"
- 删除所有"换句话说/总而言之/值得注意的是"类空话连接词
- 每个术语首次出现时有就地解释或脚注
- 没有为了显得专业而制造的复杂度
机制专属清单：见各模块 reference 末尾的 checklist。
第 6 步：交付
- 文本/HTML/图表：直接输出文件路径 + 贴出关键内容
- 视频：输出 mp4 路径 + 脚本副本
- 主动给出下一步建议（如"这个题材加个 60 秒视频版会更适合培训场景，要我做吗"）
模块 D 环境检查（视频是唯一的硬依赖）
生成视频前必须先运行：
python3 ~/.openclaw/workspace/skills/llm-output-explainer/scripts/env_check.py
- 全部通过 → 正常生成视频
- 未通过 → 按
references/module-d-video.md的降级路线执行（生成 Manim 脚本 + 渲染命令，交给有环境的机器）
机制组合原则
- 先选一种主机制，生成后根据自检结果决定要不要加第二种
- 常见组合：B 图嵌入 C HTML（默认搭档）；A 文本作为 D 视频的字幕/口播稿；E 演示工具内嵌 B 图
- 禁止一口气全上（A+B+C+D+E）——那是展示肌肉，不是讲解
反模式（出现即返工）
- 没回答受众四问就开始写 → 产出一定是通用模板腔
- 图表里出现"装饰性"元素（不回答"为什么在这"的视觉对象）
- HTML 工件用默认 AI 风格（蓝紫渐变、Inter 字体、卡片堆砌）
- 视频没写旁白脚本直接写 Manim 代码
- 把 STE100 用于说服性文本（受控语言不负责说服，负责无歧义）
- 给"一次性工具"加测试、错误处理、抽象层（Anthropic 自己的 eval 显示：不声明"用完即弃"，agent 必然过度工程化）