| name | mechanism-figure |
| description | 先理解用户问题并定向研究论文、附录与代码，还原方法的具体实现，再把机制转译成信息密度可调、图形优先的教学图；支持确定性 SVG、ImageGen 构图探索与混合矢量化。用于“讲清论文方法怎么实现”“画机制图”“可视化算法”“把公式或训练流程画出来”“解释 code mid-training、数据构造、监督信号、训练与推理差异”等任务。区别于实验结果图 paper-figure、普通流程图 mermaid-diagram 和图像描述 figure-description。 |
mechanism-figure — 先研究清楚，再把机制画懂
把用户关心的论文或算法机制还原成具体、通俗、可核查的实现过程，再将其编码成信息密度合适的教学图。
核心原则：
没有把“它具体怎么实现”讲清楚，就不要开始画图。
绘图只是后半程。前半程必须完成问题定位、资料研究、实现还原、具体示例和事实边界。
1. 完整工作流
1️⃣ 理解用户问题
明确用户真正想知道的机制，不泛泛总结整篇论文。
2️⃣ 定向阅读论文与代码
重点查正文、附录、Prompt、算法、官方代码和数据处理流程。
3️⃣ 还原具体实现
梳理原始输入、处理步骤、中间结果、模型输入、标准答案和验证方式。
4️⃣ 区分关键边界
分清训练与推理、独立与串行、共享与分离，以及事实、推论和未知细节。
5️⃣ 构造贯穿示例
使用一个忠实的具体样本，把实现过程从头到尾走一遍。
6️⃣ 生成通俗解释
先用普通人能理解的语言讲清“输入什么、做什么、得到什么”。
7️⃣ 形成机制说明书
沉淀一句话答案、完整步骤、监督来源、具体示例和常见误解。
8️⃣ 设计视觉叙事
确定读图主线和信息密度，用图形编码替代段落文字。
9️⃣ 选择绘图方式
精确内容用 SVG，视觉探索用 ImageGen，正式复杂图优先采用混合流程。
🔟 检查并交付
检查能否一眼看懂、是否符合来源事实，再导出预览图和可编辑源文件。
2. 第一硬门槛：理解用户问题
先把用户原话改写成一个可回答的 Mechanism Question，并写出读图后用户应该能回答的问题。
Mechanism Question 必须保持中性，不得把用户使用的口语直接当成论文中的正式模块。例如用户说“技能拆分”，不代表论文一定执行了“技能识别器 → 技能拆分器 → 结果汇总器”。先问“论文从什么来源构造了哪些训练任务，这些任务如何被使用”，再由来源决定真实步骤和术语。
例如用户问“技能拆分具体怎么做”，不要扩写成整篇论文综述；应聚焦：
- 原始数据是什么？
- 一条数据如何变成训练样本？
- 模型每一步实际看到什么？
- 标准答案或奖励从哪里来？
- 子任务独立构造还是串行执行？
- 最后训练一个模型还是多个模型？
若用户的问题仍含糊，但可以通过论文或代码定位，先研究再做合理聚焦；只有不同解释会导致完全不同的交付物时才向用户确认。
研究完成前不要预设流水线、模块名、串并行关系或最终合成步骤，也不要先写“预计主线”。视觉拓扑必须从 Mechanism Brief 推导，而不是从标题或用户措辞猜测。
3. 定向研究：从来源还原实现
遇到具体论文、网页、代码仓库或用户要求“详细实现”时，必须读取来源，优先使用一手资料：
- 论文方法正文与算法；
- 附录、Prompt、数据格式和训练细节；
- 官方代码、配置和数据处理脚本；
- 作者项目页或补充说明；
- 二手解读仅用于发现线索，不作为关键机制的唯一依据。
围绕用户问题定向检索，不为“读完整篇论文”而读。至少还原以下内容中与问题有关的部分：
| 维度 | 必须回答的问题 |
|---|
| 原始输入 | 系统一开始拿到什么？ |
| 数据处理 | 输入经过哪些筛选、转换或拆分？ |
| 执行步骤 | 每一步具体做什么，先后或并行关系是什么？ |
| 模型视角 | 模型实际收到哪些上下文？ |
| 监督来源 | ground truth、标签、奖励或验证信号从哪里来？ |
| 训练目标 | SFT、RL、损失或规则奖励如何使用这些信号？ |
| 推理流程 | 推理时与训练时哪里相同，哪里不同？ |
| 共享关系 | 参数、模型、数据和模块哪些共享，哪些独立？ |
| 未知细节 | 论文或代码没有交代什么？ |
不要用一句高层概括替代实现过程。例如“拆成四种能力”不够，必须继续追问“每种样本的输入、答案和构造方式分别是什么”。
优先采用来源中的正式对象和动作名称。若用户使用的是便于理解的概括词，先判断它在论文中对应“数据任务”“模型模块”“训练阶段”还是“推理步骤”，不要把概括词实体化成不存在的组件。
4. 构造一个贯穿全图的具体示例
为抽象机制选择一个忠实、简单、可跟随的样本，并让同一个样本走完所有步骤。优先使用论文样例；没有样例时，可做忠实简化，但必须标注“示意”或“简化示例”。
示例必须满足：
- 输入与论文的数据格式一致；
- 每个中间结果都能从前一步得到；
- 不为好看而编造论文没有的阶段或数字；
- 图中的术语、变量、代码和最终解释一致；
- 若某一步是推论而非论文原话，明确标注。
5. 生成 Mechanism Brief
开始画图前，先在内部完成以下说明书；必要时先把通俗解释发给用户确认。
user_question: 用户真正想理解什么
one_sentence_answer: 一句话直接回答
raw_input: 原始输入与数据来源
step_by_step: 具体步骤及先后/并行关系
model_view: 每一步模型实际看到什么
ground_truth: 标签、答案或奖励从哪里来
training_vs_inference: 训练与推理的差异
shared_vs_separate: 哪些共享，哪些独立
concrete_example: 贯穿流程的具体样本
fact_boundaries:
explicit: 来源明确说明的事实
inferred: 根据来源得到的合理推论
unknown: 来源未交代的细节
common_misunderstandings: 用户最容易误解什么
must_show: 图中不能省略的关系
Implementation-ready gate
以下问题全部能回答后，才允许进入绘图：
- 能否不用论文术语，把机制讲给不了解论文的人？
- 能否说清每一步的输入、动作和输出？
- 能否说清监督信号或答案从哪里来？
- 能否用一个例子走完整流程？
- 能否区分训练与推理、并行与串行、共享与独立？
- 能否标出事实、推论和未知细节？
任一项不满足：继续查论文、附录或代码，不要用漂亮图形掩盖理解缺口。
6. 把通俗解释转成视觉叙事
先选择最能表达机制关系的布局拓扑：
| 机制关系 | 优先视觉编码 |
|---|
| 按步骤计算 | 左到右或上到下的逐步展开 |
| 多任务独立构造 | 从同一来源并行分支，禁止画成流水线 |
| 从粗到细定位 | 嵌套框、放大镜、目录→函数→代码行 |
| 多种数据共同训练 | 多路样本合流到同一个模型 |
| 两种方法差异 | 左右分屏、相同位置对齐比较 |
| 状态迭代或反馈 | 明确闭环，并标出更新对象 |
| 数值/向量计算 | 方格深浅、长度、面积或逐算子展开 |
每个主要模块优先画出：
给模型看什么 → 做什么判断/变换 → 标准答案或输出是什么
不要把说明段落原封不动塞进方框。使用目录树、符号骨架、代码高亮、Diff、Search/Replace、向量格、分支、合流和嵌套关系替代文字。
功能性图标可以使用；纯装饰图标应删除。每个图形至少承担一种信息：对象、动作、层级、数量、方向、状态或正确性。
7. 控制信息密度
根据用户意图选择密度，而不是固定追求“越少越好”或“越满越好”：
| 密度 | 适用场景 | 保留内容 |
|---|
| low | 概念速览、封面图 | 一句话机制、主对象、主路径 |
| medium | 普通教学解释 | 输入、动作、输出、一个具体例子 |
| medium-high | “具体怎么实现”、论文解读 | 每步上下文、监督答案、边界、训练/推理关系 |
| high | 公式推导、实现复现 | 变量、公式、数值示意、验证规则和必要注释 |
默认规则：用户说“详细”“具体实现”“怎么训练”时使用 medium-high；不要为了极简而删除监督来源、训练/推理差异或关键边界。
解决“细节多 ↔ 文字少”的办法是换编码，不是缩小字号：
- 深浅表示数值或强度；
- 高亮表示选中或修改；
- 位置与嵌套表示层级；
- 分支与合流表示独立和共享；
- before/after 表示编辑；
- 同一示例的重复视觉元素表示数据来源一致。
8. 选择绘图引擎
确定性 SVG
以下情况优先使用 SVG：
- 中文、代码、公式和数字必须完全准确；
- 图需要可编辑、可复现或用于论文；
- 需要严格对齐、统一颜色或多轮精确修改；
- 图形主要由流程、变量、代码和几何元素组成。
ImageGen
以下情况使用 ImageGen：
- 用户明确要求使用；
- 需要探索更自然的构图、视觉密度或插画语言；
- 主要价值是视觉概念，而非逐字准确的公式和代码；
- 编辑目标是已有位图，且需要风格或构图级改造。
ImageGen 输出必须检查中文、代码、箭头方向、模块数量和事实关系。不要因为画面漂亮而接受错误文字或虚构步骤。
混合模式
复杂教学图优先考虑：
Mechanism Brief → SVG/线框草图 → ImageGen 探索构图
→ 选择有效视觉结构 → SVG 精确复刻 → 最终审查
ImageGen 负责构图探索，SVG 负责最终准确性。若生成图文字已经可靠且用户只需预览，可直接交付位图，但说明其不可编辑属性。
9. SVG 制作规范
把本文件所在目录记为 SKILL_DIR，使用：
$SKILL_DIR/scripts/svgkit.py$SKILL_DIR/scripts/render_check.py
生成自包含 Python 脚本并输出 SVG：
import sys
sys.path.insert(0, "<SKILL_DIR>/scripts")
from svgkit import *
doc = Svg(1280, 720, bg="#ffffff")
print(doc.render())
必须遵守：
- 用变量、
col_x、row_y 和循环计算坐标，不散落手摆数字；
- 正文与标签字号默认不小于 14；宁可换编码、拆图或删次要文字，不缩字；
- 抽象算子的动作必须画出来，不能只靠虚线暗示；
- 一张图只保留一条主叙事，多个独立问题拆成 2–3 张渐进图；
- 充分利用空间，但不要为了“填满”加入无关面板；
- 术语、维度、颜色和示例全图一致。
常用工具：
vvecbox：用方格深浅表达向量；dotprod：把点积动作展开；arrow：表达方向和变换；formula_row：展开公式步骤；note：只放一句关键边界；render_check.py：使用浏览器渲染高清 PNG。
渲染后必须使用图像查看工具亲眼检查，不能只凭 SVG 源码判断。
10. 质量审查
事实审查
- 图中每个关键结论都能对应论文、附录或代码；
- 图中的模块名和动作来自来源，不是由用户问题中的口语臆造；
- 推论明确标注，不伪装成作者结论；
- 具体示例没有改变原方法的输入输出关系；
- 训练与推理、并行与串行、一个模型与多个模型没有画反；
- ImageGen 没有写错中文、代码、数字或模块数量。
视觉审查
- 3 秒测试：能否立即看出主对象、主路径和最终结论？
- 遮正文测试：只看图形和短标签，能否走一遍机制？
- 动作测试：每个关键变换是否真的被画出来？
- 密度测试：是否既没有段落堆积，也没有因极简而丢失实现细节？
- 阅读顺序测试：箭头、编号和位置是否给出唯一清晰的阅读路径？
- 渲染测试：是否存在文字溢出、遮挡、裁切、错位或大片无意义留白？
重要图完成后，使用独立 reviewer 审查事实与教学清晰度。给 reviewer 原始来源和图，不泄漏预期结论；视觉问题仍由主 agent 亲自查看渲染图判断。
11. 失败模式
- 过早开画：尚未理解实现就开始排框。
- 论文段落装框：事实很多，但图只是排版后的文字。
- 过度极简：画面漂亮，却看不到输入、监督和关键边界。
- 关系画错：把独立任务画成串行，把共享模型画成多个 agent。
- 装饰替代解释：图标很多，但没有表达动作或数据关系。
- ImageGen 盲信：接受错误中文、代码或虚构模块。
- 字号换空间：靠缩字解决布局，导致图无法阅读。
- 示例漂移：不同模块使用互不对应的输入和答案。
12. 多图与交付
当一个问题包含“数据构造、训练过程、推理过程”等多个独立认知目标时，拆成渐进图：
- 总体机制；
- 最容易误解的关系；
- 训练或计算细节。
多图可并行生成脚本，但主 agent 必须统一渲染、视觉检查和事实审查。
默认交付：
- PNG 预览；
- SVG 可编辑图；
- 生成脚本；
- 必要时附一句事实边界或来源；
- 使用 ImageGen 时说明生成方式，并保留最终提示词或提示词摘要。
最终回答先讲图解决了什么，再给文件，不复述完整制作过程。
