| name | tikz-figure-code |
| description | 写出高质量、一次过编译、编辑安全的 TikZ/LaTeX 配图代码的工程基础技能。
教 agent 用「按构造布局」(positioning/fit/chains/anchor) 而非「手填绝对坐标」，
附 8 条硬约束、canonical 箭头、before/after 范例、一个静态检查入口 (lint.sh)。
Use when: 写/审 TikZ 或 LaTeX 图代码、修图的排版/对齐/溢出/箭头问题、
tikz layout、latex figure code、tikz 编译报错、CJK 中文图渲染成色块。
|
TikZ Figure Code — 写对 + 编辑安全的工程基础
这是确定性地基：怎么写出编译干净、不重叠、改一处不崩的 TikZ 代码。
它不管"画什么图才美"——那是设计/编排层（见 thesis-figure-skill）的事。
本技能管的是：无论画什么，代码本身得写对、扛得住编辑。
一句话定位：thesis-figure-skill 决定画什么，本技能保证怎么写不出错。
为什么需要它（问题的根）
模型写 TikZ 的默认习惯是**"坐标凭感觉"——\node at (5.2, 3.1)、\fill rectangle (x0,y0)(x1,y1)，
一格一格手摆。这是业余写法**，导致两类必然的痛：
- 盲写：你写到第 800 行时不知道渲染出来什么样，碰撞/溢出/箭头不贴框只能编译后看图才发现 → 被迫进昂贵的"渲染→审查→修"循环。
- 编辑即崩：同一个间距/中心被手抄在多处（zone 边界、内容中心、箭头坐标、底栏…）。改一个 stage 宽度要同步 5 处，漏一处就崩——而静态 checker 抓不到（实测：一个加宽 hero 的编辑把 zone 压重叠、边框切穿内容，validator + overlap-checker 全报 0 硬 bug，只有看图才发现）。
解法不是加更多检测，是换写法。 专家写 TikZ 是写一张约束图（相对定位 + fit + matrix），
让布局引擎算位置——碰撞按构造不可能发生，图correct by construction，不是 correct-after-review。
证据：references/examples/ 里同一张 5-stage pipeline，绝对坐标版 (BAD) 和按构造版 (GOOD)
渲染视觉等价；但施加同一个最自然的编辑（加宽 hero / 加长 label），BAD 崩、GOOD 自动重排。
见 proof-edit-safety-hero-widen.png。
核心原则：LAYOUT BY CONSTRUCTION，不是 BY COORDINATE
作用域：按构造纪律施加在宏观骨架层（模块/zone 彼此怎么放、怎么连）。
嵌入 viz 内部（热力图一格格、柱状图）可以继续局部手画——它自包含、坐标错了不级联——
但要用 \begin{scope}[shift={(parent.center)}] 挂到父节点 anchor，让它随父节点移动。
5 条 idiom（必须照做——散文指南传不了布局技能，照抄这些代码）
① 布局节奏只放一处
同一个间距/行高/列宽只定义一次，到处引用。永不把同一个数字抄在多处。
\newlength{\stagew}\setlength{\stagew}{4.5cm} % 改一处，全图跟着变
\def\gap{0.5cm}
\tikzset{node distance=\gap}
② 模块用相对定位摆，不用绝对 at (x,y)
第一个锚定，其余 right=of / below=of 前一个。间距活在 node distance 一处。
\node[zone] (s1) at (0,0) {};
\node[zone, right=of s1] (s2) {}; % ✅ 间距由 node distance 决定
\node[zone, right=of s2] (s3) {}; % 加宽 s2 → s3 自动右移
% ❌ \node[zone] (s2) at (5,0) {}; % 手填 5 = 改 s1 宽度就得改这里
网格/表格用 \matrix of nodes，流水线用 chains——别手动给 x 加 2cm。
③ 连线走节点 anchor，永不重抄边界坐标 ← 单点最大收益
\draw[arrow] (s1.east) -- (s2.west); % ✅ 任何重排下都不会错位
% ❌ \draw[arrow] (4.5,5) -- (5.0,5); % 把 zone 边界又抄了一遍 = 改布局就断
箭头引用节点，就永远不可能 misalign。这一条单独就能消灭评审环里一大半 bug。
④ 容器用 fit，标签用 text width（换行）不用 minimum width（撑大）
\node[fit=(a)(b)(c), draw, rounded corners] {}; % zone 自动包住内容
\node[box, text width=3.2cm, align=center] {长标签会换行不会溢出};
% ❌ minimum width=3.2cm → 长标签把框横向撑大、顶破 zone
text width 让超长内容换行（保持框宽），minimum width 让框长出去（溢出邻居）。
前者把"碰撞 bug"（硬，必修）降级成"挤一点"（软，审美）。
⑤ 整体居中用 calc 中点，不手算
\coordinate (c) at ($(first.north west)!0.5!(last.north east)$);
\node[anchor=south] at ($(c)+(0,0.5)$) {标题}; % 行变宽，标题自动跟着居中
8 条硬约束（违反必失败——加载 references/hard-constraints.md 看全）
最高频的几条（很多是 CJK / xelatex 静默坑）：
- ⚠️ CJK 节点上
rotate=90 → 渲成不可读色块。所有中文标注必须水平。
- ⚠️
\texttt{…中文…} → 报错。\texttt 只包纯英文代码。
- ⚠️ xelatex 对缺失字体静默失败 → 编译后必须
grep "Missing character" *.log，非 0 = 字体没解析（常是 CJK）。
- ⚠️ 直线单段
-- 上加 rounded corners → 端点鬼影弧。只在 ≥2 段折线 / |- 用。
- ⚠️ 路径有弯折但没
\usetikzlibrary{bending} → 弯路上箭头 tip 必然 mis-align。
- ⚠️
(A.south) |- (B.west) 当 A.x 落在 B 的 x 范围内 → 横线穿过 B 内部 (pierce)。用 waypoint 绕开或换 anchor。
Canonical 箭头（别手写 -{Stealth[scale=X]}）
用预定义 style，只调 line width（0.6/1.0/1.6pt 三档），tip 自动跟随。详见
../thesis-figure-skill/references/tikz-template.tex 的 6 个 canonical styles。铁律：
- < 1.5cm 短箭头必用
arrow short（tip 3pt），否则默认 6.5pt tip 把 stem 吃光 = "只剩个头"。
- fan-out 分叉的 stub 用
fan_stub（shorten <=0pt，紧贴 spine 无 gap），不用 arrow。
\usetikzlibrary{bending} 必加载。
工作流：写 → lint → 看图
bash references/lint.sh figure.tex
一个入口跑完：① tikz-validator（编译前静态：微斜线/溢出/碰撞）→ ② xelatex 编译 →
③ missing-char 闸门 → ④ pdf-overlap-checker（硬 bug vs 候选分开报）→ ⑤ design-linter（advisory）。
退出码 0 = 无硬 bug，1 = 有硬 bug。
checker 是地板不是天花板。 它消灭便宜的 20%（编译错、重叠、已知坑），抓不到贵的 80%
（图记不记得住、跨面板数字自洽、新几何对不对）。lint 过了仍必须亲眼看渲染 PNG——
很多崩坏（zone 重叠、边框切穿内容）static 全盲，只有看图才发现。
何时用本技能 vs thesis-figure-skill
| 你要做的 | 用 |
|---|
| 写/审任何 TikZ 图代码、修排版/对齐/溢出/箭头 bug、CJK 渲染问题 | 本技能 |
| 把论文文案/参考图变成成品配图（设计 + 编排 + 视觉迭代 + skeleton 复用） | thesis-figure-skill（它在代码正确性层 compose 本技能） |
thesis-figure-skill 的 6 个 example-skeleton-*.tex 已全部按这 5 条 idiom 重写，是本技能最好的 worked examples。
按需加载
| 触发 | 文件 |
|---|
| 要看 5 idiom 的完整代码模式 | references/by-construction.md |
| 要看全部 8 条硬约束 + 修法 | references/hard-constraints.md |
| 要对照 before/after | references/examples/（BAD vs GOOD + 编辑安全证明图） |
| 要跑静态检查 | references/lint.sh（执行即可，不用 Read） |
