论文风模型架构图

这个技能固定两样东西：版式默认是论文式三段、自下而上；风格是五色语义、块和连线的画法、字号和文字上限。 目标是让不同模型的图放在一起像同一篇论文里的一套图。每个块都要能指到源码行。

金样板：默认就画成这样

assets/examples/ 里这 6 张由 six_edit_models.py 生成，是本技能的验收标准：

它们的共同骨架：

• 左段·整体：最底一排原始输入，按 2–4 列对齐，每列竖直向上经过编码、打包，汇成一条序列条； 往上是白底黑边的「Block × N」，再往上是输出头。被放大的 block 用虚线连到中段面板。
• 中段·一个 block：黑边主面板，内部同样自下而上；残差走外侧回线进 ⊕；调制总线从左下角的调制源上行； 否定性结论（「无 adaLN」「没有 shift」）用右上角橙色短词。
• 右段·独有机制：灰边次面板，画成格子、表、树或 ①②③ 步骤，不写成段落；底部一行灰色出处行号。
• 每段底下一行图注；蓝框只给独有做法，一张图 3–6 个。

写 spec 前必须打开结构最接近的金样板 PNG，并读 six_edit_models.py 里对应的函数，从复制它开始改。 不要从空白画布用 row / box 手排。交付时把自己的 PNG 和所参照的金样板并排对比。

一条命令

archfig build my_models.py --palette paper --fit-width 1664 --gallery

• archfig 是 scripts/archfig.py，通常软链在 ~/.local/bin/；没有软链就用 python3 <本技能>/scripts/archfig.py。
• 依赖：Python ≥ 3.9（只用标准库），draw.io 桌面版（导出用；archfig doctor 检查）。
• 产物在 spec 同级的 figs/：每张图一个 .drawio（可在 diagrams.net 里继续拖改）、.svg、.png， --gallery 另出 index.html 逐张看、切配色。画布大小由内容决定，不用预设。
• archfig new my_models.py 生成一个能直接跑的最小 spec（三段模板，按需删改）。

版式：默认三段，例外要说理由

一张好的架构图回答三问：数据怎么流（左）、关键单元里面发生什么（中）、这个模型和别家哪里不一样（右）。 默认三段都画；只有某一问确实没有内容时才减段。主干方向一律自下而上，输入在底、输出在顶。

横向主干只允许用于上表「经典结构」一行；其他情况要改成横向，必须在交付时写明理由。 只有两三个块的示意，说明它是否真的需要一张架构图，能用文字或表格讲清楚的就别画。

文字上限

架构图不是讲稿，解释性的句子放进 slide 讲稿或正文，不进图。

规则要画成图形（格子、表、时间轴、路由树），不要写成一句话贴在面板里。

工作流

1. 定范围：画哪几个模型，最终放在哪里（论文、16:9 deck、竖屏图文）。显示宽度决定 --fit-width，也决定要不要拆页。
2. 取证：按 references/fact-sourcing.md 从源码拿整体路径、关键单元的执行顺序、独有机制和配置数字，每条带 文件:行号。 多个模型时每个 subagent 负责一到两个，并行跑，模板在该文件里。查不到的写 not found，不画进图。 派 subagent 画图时，任务描述里要写明参照哪张金样板，子 agent 通常只读到 SKILL.md 这一层。
3. 对样板：打开最接近的金样板 PNG，读 assets/examples/six_edit_models.py 里对应函数和 references/style.md。
4. 写 spec：从复制那个函数开始改，API 见 references/layouts.md。
   • 左段：保留输入怎么汇合、主干经过哪些模块；重复的 block 只写种类、层数、宽度。
   • 中段：画数量最多或最关键的那个单元。有调制就画出 t 进入的每一处；没有就写明「无 adaLN」这类否定。
   • 右段：画成能看懂规则的样子（mask 矩阵、坐标表、路由图、时间轴），附近写出处行号。
   • 蓝框只给独有做法，一张图 3–6 个。
5. 导出、查连线、量字号：连线检查失败时产物照样写出，先对着报错行号改 spec。archfig build ... --fit-width <显示宽度>。输出里标「偏小」的，先想版式（拆页、全宽），不要删成几个大字方块。

6. 看图：打开 PNG，和金样板并排，逐项回答：

   • 主干是不是自下而上？有没有三段（或写了减段理由）？
   • archfig build 的连线检查有没有报错？（默认报错即失败，按 style.md「连线」挪块，不许加折点绕过）
   • 箭头有没有穿过文字？（把标签放进 sub 或挪块）
   • 有没有超出「文字上限」的块和注释？
   • 有没有同一模块画了两遍？共享部分应只画一次。
   • 面板里有没有大块空白、放大虚线有没有穿过别的块？
   • 蓝框是否只落在独有做法上，数量 3–6？

   自动修改最多两轮，还不对就把问题列给用户。

7. 交付：给出 .drawio 和 SVG / PNG 路径，说明参照了哪张金样板、版式有无偏离及理由、哪些字号偏小、出处 commit。

配色

• 默认 paper：五色语义（灰 IO、蓝 Norm 与注入、紫 时间步 / 条件 / 调制、橙 注意力、绿 FFN），和版式无关，任何结构都按语义上色。 非 Transformer 的模块怎么归类见 references/style.md。
• deck：全灰块 + 单一强调蓝，只在整套材料必须严格单色时用。--palette both 两版都出，方便对比。
• 两套都遵守「蓝框 = 独有做法」。颜色、字体都是 figlib.PALETTES / figlib.FONT 里的可替换默认值。

放进 slide 的字号

图越宽，缩进 slide 后字越小。三段图约 1460 × 740，放进 1920×1080 slide 时正文最多约 15px，放进左图右注释的版式只有约 9.5px。 所以宽图要么拆页（整体一页，放大一页），要么全宽放图、注释挪进讲稿。不要缩进小框里凑版式。

什么时候读哪个参考

已知的坑

• draw.io 导出的 SVG 会给每个文字块塞 PNG 兜底图，还用 light-dark() 让暗色系统变黑底。archfig 导出后会自动清掉并锁成浅色，别跳过它直接用 draw.io 导出。
• draw.io 的 value 属性里的 HTML 要转义，否则整张图导出空白；用 figlib 不会遇到，手写 XML 时注意。
• draw.io 按画的先后决定上下层：panel 要先画，否则底色会盖住里面的块。
• 已有的 .drawio 在 diagrams.net 里手改过之后，不要再用 spec 重新生成覆盖。要改就另存新文件名。