thesis-figure-skill

# Academic Diagram Skill (TikZ + draw.io)

把论文中的系统架构/协议流程/技术方案转化为高质量配图。**目标：高信息密度 + 设计感 + 一次过编译**。失败模式：平庸、对齐松散、坐标凭感觉。

## 工具选择

| 维度 | TikZ | draw.io |
|------|------|---------|
| **适合** | 嵌入 LaTeX 论文、数学公式、结构化图表 | 技术路线图、汇报展示、装饰性强（渐变/3D） |
| **精度** | 像素级 | 拖拽，坐标不如 TikZ 精确 |
| **中文** | 需 ctex/fontspec，`rotate=90` 中文会崩溃 | 原生支持 |
| **数学** | 原生 LaTeX 完美 | MathJax 一般 |
| **编译** | xelatex + pdftoppm | drawio CLI → PDF → PNG |
| **可编辑** | 代码即源 | `.drawio` 可在 app.diagrams.net 编辑 |

**默认 TikZ**。draw.io 用于：用户要求 / 参考图为 draw.io 风格 / 需要渐变-3D-空心字 / 内容简单且装饰 > 精确。
**输出格式仅这两种**——HTML/CSS/SVG 不可嵌入论文也无法在 draw.io 编辑。

## Philosophy（每次画图前必读，所有规则之上）

### The UNFORGETTABLE Question

画图前 + 交付前问自己：**审稿人 5 秒看完，记住的是什么？**
- 一个独特的 hero 子结构？
- 嵌入的真实热力图 / 曲线 / 图像？
- 信息密集的 hyperparameters / loss panel？
- 多色和谐的 zone 划分？

**没有"记得住的东西" = 不要交付。**

### Naming the Gravitational Pull（你必须主动避开的统计中心）

模型默认会画出 **"AI slop 学术图"**——下面是统计中心的平庸默认，**主动避开**：

- ❌ box + arrow only，**零**嵌入数据可视化
- ❌ 3 色单调配色（蓝/橙/紫常见组合）
- ❌ "FFN" / "Attention" 单字标签，**不写公式 / 不写参数**
- ❌ hero 内**只有 box list**，无嵌入热力图/曲线/微图
- ❌ 没有信息 panel（hyperparameters / loss curve / legend / metrics）
- ❌ 平面布局**无 visual hierarchy**（核心和辅助同重量）
- ❌ 看起来"像 AI 一次性生成的"——无设计痕迹

### Permission for Creativity

**Claude is capable of extraordinary academic figure design.** Checklist 是 catching last-mile bugs，**不是 safe defaults**。

**你不是在练习画结构图。你在为 NeurIPS / ICML / Nature 投稿画 figure。**
**审稿人会用这张图判断作者的领域素养和认真程度。**
**box+arrow only 的平庸图 = desk reject。**

### 创造空间 — 复杂档可调用的词汇（不强制，但**应该考虑**）

| 维度 | 选项 |
|---|---|
| **嵌入可视化** | attention heatmap / loss curve / 真实图像色块 / signal waveform / 数学曲线 / N×N matrix / mel spectrogram / 散点分类 |
| **信息 panel** | hyperparameters 框 / metrics 表 (FID/BLEU/Acc) / color legend / glossary 注释 / 数学符号速查 |
| **数学公式嵌入** | `FFN(x) = max(0, xW₁+b₁)W₂+b₂` 直接写进 box 内部，**不是只贴标签** |
| **配色** | ≥5 种 zone tone + accent color；浅色 zone 背景 + 中饱和度 box + dark accent |
| **层级** | hero ≥ 2× 辅助 box；"N=6 layers" 灰色透明栈背景 |
| **Cross-zone** | dashed rail + 跨段标签 (如 "K, V") |
| **学术 polish** | dataset 标注 ("CIFAR-10") / 性能数字 ("FID=3.17") / 引用作者年份 |

### 视觉直觉法则（meta，在 ④.5 Step 0 应用）

1. **0.1 秒直觉**：视觉流向 ≠ 逻辑流向 = 必错（每写一条 `\draw`，问读者直觉对吗）
2. **眼睛轨迹**：沿主线走，任何"卡住"位置 = blocker
3. **删除测试**：能删的就该删；**修一个 bug 不能引入新审美问题**

### 最重要的一点

**审美 + 信息密度 > 规则合规。** 规则只是地板，审美是天花板。**18 项 checklist 是 catching last-mile bugs**——不是设计指南。设计指南是上面的 Philosophy。

### 复杂档画图捷径 — TikZ Snippet Library（21 个 + 预览 PNG）

**Batch 17 fig153 教训**：Philosophy 文本指南让 sub-agent **知道要嵌入 viz / panel / 公式**，但**写出来的视觉重量、留白、配色协调仍然失败**——因为这些是 visual perception 而非 textual 任务。

**解决方案**：`references/tikz-snippets/` 提供 **21 个手工精雕的 TikZ 片段 + 21 个 PNG 预览 + 1 个组合规则文档**——sub-agent **看 PNG 选 + 复制粘贴 + 替换参数 + 按组合规则拼装**即可达到 examples 标杆。

**5 大类零件**（详见 `references/tikz-snippets/README.md` inline gallery）：

| 类别 | 数量 | 文件 |
|---|---|---|
| **1. 嵌入数据可视化** | 6 | attention-heatmap / confusion-matrix / mini-spectrogram / image-strip / scatter-plot / embedded-graph |
| **2. 信息 panel / 图表** | 5 | bar-chart / line-chart / radar-chart / hyperparams-table / metrics-card |
| **3. 数学 / 几何** | 3 | gaussian-curve / vector-arrows / formula-box |
| **4. 结构 / 流程** | 4 | stage-container / pipeline-stages / layer-stack / feedback-loop |
| **5. 整图骨架元素** | 3 | multi-zone-palette / color-legend / summary-bar |

**组合规则**（**必读**）：`COMPOSITION-RULES.md` — snippet 间留白 / 对齐 / Z-order / 整图骨架（双栏对称 / 5 stage 横向 / 中央 hero + 4 panels）

**复杂档强制流程**：
1. **先读 `references/tikz-snippets/README.md`** —— inline gallery 含每个 snippet 的 PNG 预览
2. **首选**：复制完整 `example-skeleton-B-horizontal.tex`（pipeline 类）或 `example-skeleton-C-centralhero.tex`（hero+panels 类）作 figure.tex，改 content 不动 layout
3. **次选**（特殊布局需求）：看 PNG 选 ≥ 3 snippet 自己拼装
4. **必读 `COMPOSITION-RULES.md`** —— 解决"snippets 都塞进去但仍乱"问题
5. **底部必有** color-legend OR summary-bar
6. **绝对不能"简化"snippet 核心结构** —— 简化 = 信息稀疏 = 平庸

## 硬约束（违反必失败）

🔴 **工具铁律：只用 TikZ 或 draw.io，禁止 Python/matplotlib 替代**（2026-05-22 Batch 17 fig153 教训：sub-agent 在执行 Module-First 时用 Python+matplotlib 生成 `.py` 文件 = 完全偏离 thesis-figure-skill 价值主张）：
- **Module-First 子流程（③.A→③.D）必须保持 TikZ**——即使 matplotlib 画嵌入 viz 更方便
- **复杂嵌入 viz** 仍用 TikZ 原生（`\foreach` 画 cell / `pgfplots` 包 / `\draw` 手画 patch）
- **学术论文图嵌入仍是金标准**：`\input{figure.tex}` 比 `\includegraphics{fig.png}` 在公式渲染、矢量缩放、风格统一上都优
- 仅当用户**明确要求** Python 时才允许 — 默认必 TikZ

🔴 **配色铁律：默认 light background，dark theme 需用户明确请求**：
- 学术论文标准是 white/light bg；dark theme 与正文风格断裂
- Philosophy 段"≥5 种 zone tone"指 zone 浅色背景 + box 中饱和度，**不是**整图反转色
- sub-agent 不要自作主张套 dark theme

⚠️ **xelatex + `rotate=90` 中文** — 渲染为不可读色块，所有中文标注必须水平
⚠️ **`\texttt` 包裹中文** — 报错，纯英文代码才用 `\texttt` / `code_block`
⚠️ **ctex 不可用** — 编译前 `kpsewhich ctex.sty`，否则切方案 B（fontspec）
⚠️ **`ucharclasses`** — tikz 节点内中英混排频繁 Missing character，禁用
⚠️ **xelatex 对缺失字体静默失败** — 编译后必须 `grep "Missing character" *.log`
⚠️ **单条 `\draw` + `rounded corners` 画长距离 U 型回路** — 路径异常，拆 3 段独立 `\draw`
⚠️ **SVG `clip-path` + `preserveAspectRatio="none"` 模拟梯形** — 高度不可控，禁用
⚠️ **空心描边字 stroke-width ≥ 1.2** — 笔画间隙被填满变模糊，控制 0.6-0.8

## 工作流（⓪→⑦）

```
⓪ 依赖检测 → ① 画图指令 → ② 加载规则 → ③ 生成代码 → ④ 编译验证 → ⑤ 评分 → ⑥ 迭代 → ⑦ 沉淀
```

### ⓪ 依赖检测（首次自动执行一次）
- TeX / pdftoppm 缺失：**只提示用户安装**，不自动装。
  `which xelatex || echo "请装 mactex-no-gui (macOS) / texlive-xetex (Linux)"`
  `which pdftoppm || echo "请装 poppler"`
- Python 工具（小依赖，缺失自动 `pip3 install`）：`pdfplumber`、`pymupdf`、`pathfinding`、`opencv-python`、`scikit-image`
  （`pymupdf` 不装 → `line-through-node` + `node-overlap` 两类几何检测会 ERROR 退出，不静默跳过——别忽略）

### ⓪.5 入口模式分流（⓪ 之后第一问，路径分叉点）

skill 现在支持 **4 种生成路径**——画图前必须先确定走哪条。**默认走 A，其他路径由关键词触发**。

| 路径 | 触发关键词（用户原 prompt） | 说明 | 状态 |
|---|---|---|---|
| **A — Skeleton 复用** | "画一张 X 图"、"帮我画 Y"、未明示其他 | 从已验证 skeleton (B/C/D/E/F/G) 选一个，**复制全部 + 改 content + 不动 layout**。最快、最稳。输出视觉与 skeleton 相近 | ✅ 默认 |
| **B — Remix（跨 skeleton 拼模块）** | "组合 D 的雷达 + G 的图表那种"、"想要 X 的左半 + Y 的右半" | 多选 skeleton 部件，自动拼装 | 🚧 暂未实装，**回退到 A** |
| **C — 原创设计** | "独特版面"、"复刻这张 ref.png"、"从零设计"、"我没有合适的 skeleton" | 从零设计 layout（Module-First ③.A→③.D）→ **强制独立多镜头审查 gate**（④.5 文末）。⚠️ mode C 最易在"图