Obsidian Excalidraw

Excalidraw Diagram Generator

Create Excalidraw diagrams in Obsidian-ready .md files. Optimized for AI/ML model architecture diagrams (encoders, fusion modules, policy heads, controllers, multi-system pipelines), but supports general flowcharts, mind maps, and concept diagrams.

🛠️ 核心工具：references/builder_template.py — 提供 Builder 类（封装 rect/text/arrow/ellipse/subbox/parent_box/module 7 个 helper），自动处理索引分配、双向绑定、JSON 序列化，并在 .write() 前跑 7 项 sanity check（覆盖 §7 所有已知踩坑）。画图首选用它，不要手写 JSON。配色直接用 PALETTE 字典。

Workflow

1. Identify diagram class — AI architecture vs. general (flowchart / mind map / hierarchy / etc.). Architecture diagrams use the AI Specialization rules in §3.
2. Plan structure before code:
   • Modules and their type (encoder / fusion / policy / controller / output / annotation)
   • Data flow direction (left→right for forward pass, top→bottom for hierarchy)
   • Tensor shapes at every dimension change
   • Subsystems to group (System 1/2, train/inference, perception/action)
   • Per-module decision: simple module (Builder.module()) vs. parent + sub-boxes (Builder.parent_box() + .subbox()) — see §3.3 升级触发条件
3. Generate via Python builder — use references/builder_template.py:

   from builder_template import Builder, PALETTE
   b = Builder()
   px, fx, sx, sf, _ = PALETTE["llm"]
   b.parent_box("dit", "dit_t", 920, 220, 360, 140, px, fx, "Wan 2.1-14B DiT")
   b.subbox("sub_a", "txt_a", 930, 252, 165, 50, sx, sf, "VAE 8x8/4x4")
   # ... arrows, more modules
   b.write("MyDiagram.architecture.md")  # validates before write
   

   Builder.write() runs all 7 sanity checks (index, dup id, container binding, arrow binding, overflow, curly braces, dangling refs) and aborts on any issue. Never write JSON by hand.
4. Save as [主题].[类型].md in cwd (e.g. InternVLA-N1.architecture.md). Builder writes Obsidian-wrapped markdown directly.
5. Confirm to user — file path, diagram type, 1-line rationale. If user reports rendering issues, see §7 Error Prevention.

手写 JSON 仅当：调试现有图、用户给了已有 JSON 要修。其他场合一律用 builder。

1. Diagram Types

2. Output Format (Obsidian Wrapper)

严格按以下结构输出：

---
excalidraw-plugin: parsed
tags: [excalidraw]
---
==⚠  Switch to EXCALIDRAW VIEW in the MORE OPTIONS menu of this document. ⚠== You can decompress Drawing data with the command palette: 'Decompress current Excalidraw file'. For more info check in plugin settings under 'Saving'

# Excalidraw Data

## Text Elements
{文本1} ^id1

{文本2} ^id2

...

%%
## Drawing
\`\`\`json
{完整 Excalidraw JSON}
\`\`\`
%%

Text Elements 部分必须列出每个文本元素，格式：

• 文本内容 + 空格 + ^uniqueId（block reference）
• ^id 必须与 JSON 中对应 text element 的 id 字段完全一致
• 多行文本直接换行写，最后一行末尾贴 ^id
• 元素之间用空行分隔
• 这是 Obsidian Excalidraw 插件的双向同步源 — markdown 视图编辑文本会同步到 JSON，反之亦然
• 留空也能渲染（插件会从 JSON 反填），但列出来更稳，且符合用户现有文件惯例

其他规则：

• 顶层 frontmatter 仅 excalidraw-plugin: parsed + tags: [excalidraw]
• ## Drawing 下的 JSON 必须用 %% 包围（隐藏 markdown 渲染）
• code fence 只用 json，绝不用 compressed-json。compressed-json 是插件运行时格式，手写 base64 必坏
• JSON 必须单行紧凑 — 顶层 {...} 一行开头一行结尾，每个 element 单独占一行。禁止对 element 对象进行多行缩进（pretty-print）。原因：Obsidian 插件首次打开会触发 auto-compress 把 JSON 压成 base64，多行 + 中文 + 长字符串容易在压缩输出中插入意外换行，导致 base64 损坏 → 整图无法渲染。

✅ 推荐写法（每 element 一行）：

{"type":"excalidraw","version":2,"source":"...","elements":[
{"id":"box1","type":"rectangle",...全部字段在同一行...},
{"id":"text1","type":"text",...全部字段在同一行...},
{"id":"arr1","type":"arrow",...全部字段在同一行...}
],"appState":{"gridSize":null,"viewBackgroundColor":"#ffffff"},"files":{}}

❌ 禁止写法（element 跨多行）：

{
  "id": "box1",
  "type": "rectangle",
  "x": 100,
  ...
}

2.1 Raw JSON Mode（罕用）

仅当用户明确要求 "纯 JSON"、"excalidraw.com"、"raw"、"裸 JSON"、.excalidraw 文件时使用。 跳过 Obsidian 包裹，直接输出（不带 markdown code fence）：

{
  "type": "excalidraw",
  "version": 2,
  "source": "https://excalidraw.com",
  "elements": [...],
  "appState": {"gridSize": null, "viewBackgroundColor": "#ffffff"},
  "files": {}
}

默认仍然走 Obsidian 模式（§2 主格式）。设计规则、配色、AI 架构特化（§3-§5）两种模式均适用。

3. AI Model Architecture Specialization

核心原则（来自 NN-diagram 最佳实践）：

• 张量形状必须标注 — 每个维度变化点都写形状，否则读者要猜
• 颜色按模块类型分配 — 功能性，不是审美。同类模块同色
• 视觉对应架构 — Transformer 堆叠用 ×N、残差用 bypass 箭头、Diffusion 画噪声→去噪管线
• 真实命名 — 写 Qwen-VL-2.5 7B 而不是 LLM，写 DepthAnythingV2 而不是 Depth Encoder

3.1 模块色彩语义表

每类模块固定色对，便于跨图一致：

配对规则：父框深描边 + 浅填充；子框是父的"调浅一档"（stroke 浅 ~10%，fill 几乎纯白带一丝色调）。文字色统一 #1f2937（暗灰）。 这套配色已固化在 references/builder_template.py 的 PALETTE 字典里，画图直接 from builder_template import PALETTE。

3.2 标准流水线布局（VLA/VLM 模型）

横向 6 段式 — 自左向右，每段 200–240px 宽（早期 180 太窄，文字易溢出），模块间距 20–30px（窄间距给箭头）：

┌─输入层─┐ ┌─编码层─┐ ┌─融合层─┐ ┌─规划层─┐ ┌─执行层─┐ ┌─控制层─┐
│ RGB-D  │→│  ViT   │→│ Q-Form │→│  LLM   │→│ Policy │→│  MPC   │
│ Text   │ │ LLM enc│ │   +    │ │  CoT   │ │  Diff  │ │  PID   │
└────────┘ └────────┘ └────────┘ └────────┘ └────────┘ └────────┘
   180       200        200        220       240(hero)   180

含子框的 hero 模块（如 LLM/DiT）通常用 300–360px 宽 来容纳 2×2 子网格。 垂直方向（y 轴）用于多模态并列输入或 System1/System2 分层。

3.3 模块盒规范

每个模块 = 矩形容器 + container-binding 居中文本（Builder.module() 一行搞定）。文本格式：

[模块名]
=====
- 模型/算法名
- 维度/参数量
- 关键属性

• 标题用 [名称]（不再用 ━━━━━━ 分隔线 — 容易在压缩 JSON 时破坏；用 ===== 5–10 个等号代替更稳）
• bullet 用 -（container-binding 文本不会被 markdown 解析，连字符没问题）
• 必须用 container binding（rect 的 boundElements ↔ text 的 containerId）— Excalidraw 自动垂直+水平居中。自由文本垂直居中常顶部对齐
• 盒尺寸看内容定（由 §3.3「文字宽度估算」反推）：
  • 3–4 行短内容（fs=13）：width ≥ 180, height 120
  • 5 行内容（fs=13）：width ≥ 200, height 140
  • ≥6 行：直接升级子框（见下文「内容多怎么办」）
• roundness: {type: 3}（圆角矩形）

参考已有图：OpenVLA.md 的 Vision Encoder 盒、NavDP架构.md 的 RGB编码器盒。

文字宽度估算（避免溢出）

Excalifont（fontFamily: 5）平均字宽 ≈ fontSize × 0.6 像素。每行能放多少字符：

max_chars_per_line ≈ (box_width − 20) / (fontSize × 0.6)

自检脚本（生成前必跑）：

for e in elements:
    if e['type']=='text' and not e.get('autoResize', False):
        max_chars = (e['width'] - 12) / (e['fontSize'] * 0.6)
        longest = max(len(line) for line in e['text'].split('\n'))
        if longest > max_chars + 1:
            print(f"OVERFLOW {e['id']}: {longest} > {max_chars:.0f}")

内容多怎么办：优先用子框，而不是塞文字

📌 核心规则：当某个模块文字超过 5–6 行 / 单行超过容纳上限，不要通过缩小字号或硬塞来解决。把它升级成「父容器 + 标题 + 多个子框」的结构，每个子框承担一类信息。这同时解决溢出问题 和 可视化模块内部组成。

升级触发条件（满足任一即升级）：

• 文字 ≥ 6 行
• 任何一行字符数 > §文字宽度估算上限
• 内容天然可拆成 2+ 个独立小组件（如 VAE + Flow Matching + FramePack + Plücker rays）
• 模块是 hero（核心组件），需要视觉权重

子框模式构造（含数据流箭头 — 子框间有依赖必须画）：

┌─Wan 2.1-14B DiT────────────────────────────┐  ← 父框（粗描边、深色 stroke）
│                                            │
│  [VAE 8x8/4x4]  ─→  [Flow Match 35/DMD 4]  │  ← 主流：实线箭头
│        ↑                   ↑                │
│        │ (dashed)          │ (dashed)       │  ← 条件注入：虚线箭头
│  [FramePack hist]   [Plücker rays inj.]    │
│                                            │
└────────────────────────────────────────────┘

子框生成用 Builder.subbox(rect_id, txt_id, x, y, w, h, stroke, fill, text)：自动绑定 + 居中 + 索引分配。

字段规范：

子框文字必须用 containerId 绑定（不能用自由文本）

子框里的多行文字如果用自由文本（containerId: null），即便设了 verticalAlign: "middle" 也常常顶部对齐 — Excalidraw 对自由 text 的垂直居中支持不稳。正确做法是 container binding，让 Excalidraw 自动水平+垂直居中。

# rect: 必须有 boundElements 反向引用 + customData
rect = {
    "id": "sub_a",
    ...,
    "boundElements": [{"type": "text", "id": "txt_sub_a"}],  # 必须
    "customData": {"legacyTextWrap": True}                   # 必须，让多行文字按 box 宽度 wrap
}

# text: 必须有 containerId 指向 rect
text = {
    "id": "txt_sub_a",
    ...,
    "containerId": "sub_a",      # 必须
    "textAlign": "center",
    "verticalAlign": "middle",
    "x": <rect.x>, "y": <rect.y>, "width": <rect.w>, "height": <rect.h>  # 与 rect 同尺寸（Excalidraw 会忽略并自动布局）
}

双向引用必须一致（§5 反复警告过）：rect 的 boundElements 里有 text 的 id，text 的 containerId 指 rect 的 id。任何一方写错整张图可能拒绝渲染。

helper 函数模板：

def subbox(rect_id, txt_id, x, y, w, h, stroke, fill, text_content, idx_rect, idx_text, fs=11):
    add(rect(rect_id, x, y, w, h, stroke, fill, idx_rect, sw=1,
             bound=txt_id))  # 自动加 boundElements + customData
    add(text(txt_id, x, y, w, h, text_content, idx_text, fs,
             container=rect_id))  # 自动加 containerId

哪些场景用 container binding：

• ✅ 子框（必用）
• ✅ 简单单盒模块（Input / Output 等只有 4–5 行，希望整体居中）
• ✅ Recon 模块（DAv3 / Mesh Ext 等）
• ❌ 父框（父框只放标题在顶部 + 子框在下方，不能整体居中）
• ❌ 自由标签（侧栏、张量形状、loop 标注）— 这些就是要靠位置控制布局

典型尺寸：

• 2 平行子框：父 220 × 140，子 95 × 100，间隔 10px
• 2 串行子框（带箭头）：父 220 × 140，子 90 × 100，箭头 20px
• 3 串行子框：父 240 × 140，子 64 × 100，箭头 14px
• 2×2 网格：父 360 × 140，子 165 × 50，箭头穿插其间

子框间数据流箭头（必加）

子框不是装饰 — 是模块内部的数据流分解。只要子框之间有先后顺序或依赖关系，就必须加内部箭头，否则读者无法判断流向。

箭头规范（与外部主流箭头区分）：

• strokeWidth: 1（外部主流是 2）
• 颜色与父框 stroke 一致（不是默认灰）— 视觉绑定到所属模块
• 实线表 forward flow，虚线表 conditioning / 注入
• 字号若加标签则 fontSize: 10

常见内部拓扑：

实例（Lyra 2.0 DiT，2×2 + 主流 + 条件注入）：

┌─Wan 2.1-14B DiT────────────────────────────┐
│  [VAE 8x8/4x4]  →  [Flow Match 35/DMD 4]   │  ← 实线主流
│         ↑                  ↑                │
│  [FramePack hist]    [Plücker rays]        │  ← 虚线条件注入
└────────────────────────────────────────────┘

该升级哪些模块？（不要只升级一个）

经验法则：当一张图里有 任意 模块满足升级条件，所有同等复杂度的模块都该升，否则视觉权重失衡。

何时不该用子框（避免过度设计）：

• ❌ Input/Output 这类只是 I/O 描述的端点 — 子框反而显得 over-engineered
• ❌ 内容是同质的列表（如"成功率 / 速度 / 数据规模"三个指标）— 子框暗示"流程关系"，但这里只是并列条目，用单盒 bullet 列即可
• ❌ 一张图整体复杂度低（≤5 个模块、各自 3–4 行）— 全用单盒更清爽
• ❌ Side panel（创新点 / 指标 / 推理流程）— 这些是叙述性内容，不是模块结构

典型分布（VLA/VLM 论文）：

• 简单单盒：Input / Output / 标注框 / 侧栏
• 子框升级：Vision Encoder / LLM / Diffusion DiT / Policy Head / Memory Cache / Retrieval / Fusion 等核心模块

常见拆分模式：

• VLM/VLA backbone（2×2 网格 + 主流横线）：[Vision Encoder] → [Cross-Attn] / [Text Encoder] ↑ [Decoder] ↑
• Diffusion DiT（2×2 + 条件注入）：[VAE enc] → [Flow Match] / [FramePack] ↑ [Plücker] ↑
• 3D Cache（2 平行）：[Depth Map] ‖ [Point Cloud]
• Geo Retrieval（2 串行）：[Score φ(i)] → [Greedy select]
• Canonical Warp（3 串行）：[FwdWarp] → [Build map] → [Inject Q,K]
• Policy Head（2×2）：[Action Decoder] ‖ [Value Head] / [Loss] [Optim]

禁止：

• ❌ 把已经溢出的文字硬挤进原盒，靠减字号到 10 以下
• ❌ 用 containerId 让 Excalidraw 自动 wrap（虽然能 work，但 wrap 出来的中文/英文混排很丑）
• ❌ 子框层数 > 2（再深就成思维导图了，画不下）
• ❌ 一张图里只升级一个 hero 模块、其他同等复杂度的模块塞文字 → 视觉失衡
• ❌ 子框之间有数据依赖却不画内部箭头 → 读者必须靠位置和先验猜流向

3.4 张量形状与元数据标注

形状标注（free-floating，不带容器）：

• 格式：(B, seq_len, dim) 或 [N, 256] 或 B × N × 256
• 字号 14–16，颜色 #b45309（金棕色），fontFamily: 5
• 位置：贴在产生该张量的箭头中段或目标模块上方
• 示例：(B, 128, 512)、[M, 3] 轨迹、N×256 tokens
• 禁止用花括号上下标 R^{H×W×3}、x_{ij} — Obsidian markdown 解析与 ^block-ref 语法冲突，且某些字符组合会让插件压缩 JSON 后无法解码。改用平铺写法 R³、(B, H, W, 3)、x_ij。

频率/延迟标注：

• 「30 Hz」、耗时: ~30ms、Latency: 0.7s
• 与速率相关的箭头/模块旁，用虚线小框包裹（strokeStyle: dashed，backgroundColor: #fef3c7）

参数量标注：模块名后小字，例 Qwen-VL-2.5「7B」、U-Net「12M」

3.5 子系统分组（System 1/2 风格）

将多模块用大半透明矩形框住：

• width 跨多个子模块，height 包含所有内容 + 上下 50px padding
• backgroundColor: #f8fafc（极浅灰）或 transparent
• strokeStyle: dashed，strokeWidth: 2，roughness: 0
• opacity: 60（不抢戏）
• z 轴：分组框用最早的索引（如 a1），子模块用之后的（a2, a3, ...）。禁止用末字符为 0 的索引（见 §7.4）
• 顶部贴标题文本：System 2: 高层规划「Slow, 2 Hz」

参考：InternVLA-N1.md 的 DualVLN 双系统框。

3.6 重复块与跳连

• 堆叠重复（Transformer Encoder × N）：单个块 + 右下贴 ×N 标签
• 残差/Skip Connection：bypass 弧形箭头，strokeStyle: dashed，标 + 或 residual
• 共享权重：两个块之间画双向虚线 + Shared 标签
• 数据并行/模态并行：分叉箭头从同一锚点出发到多个目标

3.7 流向箭头规范

箭头中段贴张量形状或操作名（+、⊙、concat、cross-attn）。颜色绑定原则：箭头颜色应"跟随"它属于的子系统 — 子框内部箭头跟父框走，跨模块主流用中性灰。

3.8 侧栏元信息

右侧或下方留 200–300px 给侧栏卡片：

• 🔑 关键创新点 — 3–5 条，#dc2626 标题
• 📊 性能指标 — 成功率、速度、数据规模
• 🚀 推理流程 — 多阶段步骤（Stage 1/2/3）
• ⚙️ 训练（可选）— 损失函数、数据集

每张图保留 ≥1 个侧栏（参考 NavDP架构.md）。

3.9 AI 架构图常用图标库

将这些字符直接放入 text 元素：

• 📥 输入 📤 输出 🧠 LLM 👁️ Vision 🎯 Goal
• 🔁 循环 ⏱️ 时延 📊 指标 🔑 创新 🚀 推理
• 箭头：→ ↑ ↓ ↔ ⇒ ⇄
• 数学：× ÷ ± ⊙ ⊕ ⊗ ∑ ∇
• 装饰：✓ ✗ • ・ ━ ┃ ┏ ┓ ┗ ┛

3.10 架构家族速查

4. Universal Design Rules

4.1 容器纪律（避免「全是矩形」）

只在以下情况用矩形容器：

• 是某个区域的焦点元素
• 需要被箭头连接
• 与其他元素视觉分组
• 形状本身有语义（菱形=决策、椭圆=起止/输出）

否则用自由文本 — 标签、注释、张量形状、侧栏内容都不要装在矩形里。目标：被装进容器的文本占比 < 50%。

形状语义：

4.2 布局与间距

• 画布：所有元素在 0 ≤ x ≤ 2000, 0 ≤ y ≤ 1000。横向 6 段流水线 + 子框 + 右侧面板常达 1700–1850 宽，原 1600 上限不现实。超过 2000 应考虑分屏或重设计。

• 网格对齐：所有 x, y 用 10 或 20 的倍数（视觉对齐；子框内部精度可放宽）

• 重要性 = 留白：核心元素四周 ≥80px 空白（含子框时模块间距给小，模块组之间留白给大）

• 尺寸层级（高度按"装得下 4–5 行 fs=13 文字 + container padding"反推）：

  层级	用途	宽×高	示例
  Hero+	含 2×2 子框的核心模块	320–360 × 140–160	DiT、双系统父框
  Hero	主流水线核心	220–240 × 140	LLM、Vision Encoder
  Primary	普通流水线模块	180–200 × 120–140	Input、Output、Decoder
  Sub-box	父框内部子组件	64–165 × 50–100	见 §3.3 子框尺寸表
  Tag	自由文本标签	autoResize=true	张量形状、频率标注

4.3 文字规范

• fontFamily: 5（Excalifont，手写感）— 所有文本默认
• lineHeight: 1.25
• 字号：标题 24–28、副标题 18–20、正文 14–16、张量/标注 12–14
• 颜色按 §3.1 模块类型；通用文字 #1f2937
• 文本替换规则（解决 Obsidian 解析冲突）：
  • 中文自然语句中的 (...) → 「...」
  • 中文自然语句中的 "..." → 『...』
  • 例外：技术注解中的张量形状 (B, 128, 512)、单位 (Hz)、英文短语保留原样

4.4 视觉风格

• roughness: 1（手绘感，与现有图一致）；如需严肃汇报用 0
• strokeWidth: 2；关键流用 3，标注用 1
• opacity: 100（除分组背景框可降至 60）
• roundness: {type: 3}（圆角矩形）

5. Element Schema (Required Fields)

通用字段（所有 element）

⚠️ index 字段必须是合法 fractional-indexing 字符串，末字符不能是 0（见 §7.4 — 违反会让插件静默丢弃整个 elements 数组）。安全模板：a1..a9, aA..aZ, aa..az。

{
  "id": "module_vit",
  "type": "rectangle | text | arrow | ellipse | diamond | line",
  "x": 200, "y": 240,
  "width": 200, "height": 100,
  "angle": 0,
  "strokeColor": "#1e40af",
  "backgroundColor": "#dbeafe",
  "fillStyle": "solid",
  "strokeWidth": 2,
  "strokeStyle": "solid",
  "roughness": 1,
  "opacity": 100,
  "groupIds": [],
  "frameId": null,
  "index": "a1",
  "roundness": {"type": 3},
  "seed": 123456789,
  "version": 1,
  "versionNonce": 987654321,
  "isDeleted": false,
  "boundElements": [{"type": "text", "id": "txt_vit"}],
  "updated": 1751928342106,
  "link": null,
  "locked": false,
  "customData": {"legacyTextWrap": true}
}

boundElements + customData：作为 text container 时必填。空数组 + 无 customData 也 OK，但 text 没法靠 container binding 居中。

text 额外字段

模式 A — Container-binding（推荐用于盒内文字）：

{
  "text": "[Vision Encoder]\n=====\n- DINOv2 ViT-L\n- (B, N, 1024)",
  "rawText": "...",
  "fontSize": 14,
  "fontFamily": 5,
  "textAlign": "center",
  "verticalAlign": "middle",
  "containerId": "module_vit",
  "originalText": "...",
  "autoResize": false,
  "lineHeight": 1.25
}

容器（rect/ellipse）和 text 必须双向引用，否则整图可能拒绝渲染：

• rect: boundElements: [{"type":"text","id":"<text-id>"}] + customData: {"legacyTextWrap": true}
• text: containerId: "<rect-id>" + autoResize: false

模式 B — 自由文本（用于标签、张量形状、侧栏内容）：

{
  "text": "(B, 128, 512)",
  "fontSize": 12,
  "fontFamily": 5,
  "textAlign": "left",
  "verticalAlign": "top",
  "containerId": null,
  "autoResize": true,
  "lineHeight": 1.25
}

autoResize: true 让文本框自动贴合内容尺寸；containerId: null 不绑定。禁止用此模式装多行盒内文字 — 垂直居中不稳。

arrow 额外字段

默认：不绑定的浮动箭头（推荐，最稳定）：

{
  "points": [[0, 0], [120, 0]],
  "startArrowhead": null,
  "endArrowhead": "arrow"
}

只设 points 和箭头样式，由作者手动放对位置。这样箭头是"哑"的，不依赖任何元素 ID，几乎不会触发渲染失败。

高级（易碎）：绑定箭头：

{
  "points": [[0, 0], [120, 0]],
  "startArrowhead": null,
  "endArrowhead": "arrow",
  "startBinding": {"elementId": "module_a", "focus": 0, "gap": 5},
  "endBinding": {"elementId": "module_b", "focus": 0, "gap": 5}
}

绑定箭头会自动随源/目标盒子移动而吸附。但必须保证双向引用一致：

• 箭头的 startBinding.elementId 指向的盒子，其 boundElements 数组里也必须有 {"id":"<arrow_id>","type":"arrow"}
• endBinding 同理
• 任何一方拼错或漏写，整张图可能直接拒绝渲染

⚠️ 如果不需要吸附行为，永远优先选浮动箭头。本 skill 默认浮动。仅当用户明确要求"可拖动连接线"时才用绑定。

顶层结构

{
  "type": "excalidraw",
  "version": 2,
  "source": "https://github.com/zsviczian/obsidian-excalidraw-plugin",
  "elements": [...],
  "appState": {"gridSize": null, "viewBackgroundColor": "#ffffff"},
  "files": {}
}

完整字段定义见 references/excalidraw-schema.md。 AI 架构图复用片段（模块盒/子系统框/标注气泡/侧栏卡片）见 references/ai-architecture-patterns.md。

6. Quality Checklist

6.1 设计层（人脑判断 — builder 查不出来）

AI 架构图必检：

• 每个张量变形点都标了形状
• 同类模块用了同色（按 §3.1）
• 子系统用大框框住、加标题
• 用了真实模型名（不是 "Encoder 1"）
• 重复堆叠用 ×N 标记
• 至少一个侧栏（创新点 / 指标 / 推理流程）
• 子框间数据依赖都画了内部箭头（见 §3.3）
• 同等复杂度的模块统一用子框 or 单盒（不混搭，否则视觉失衡）

通用设计必检：

• 容器占比 < 50%（其余用自由文本）
• 中文自然语句的 () "" 已转义为 「」 『』
• 关键元素周围有适当留白
• 整体宽度 ≤ 2000

6.2 兼容性层（用 Builder.validate() 自动跑 — 不用人工查）

Builder.write() 默认调 validate(strict=True)，覆盖以下 7 项。失败立即 abort，不会写出坏文件：

1. ✅ 所有 id 唯一
2. ✅ 所有 index 末字符不是 0（fractional-indexing 合法）
3. ✅ 所有 index 唯一
4. ✅ container binding 双向一致（rect.boundElements ↔ text.containerId）
5. ✅ arrow binding 双向一致（如果用了）
6. ✅ 自由文本不溢出（按 §3.3 公式估算）
7. ✅ 文本无 ^{...} _{...} 花括号上下标

如果你不用 builder（手写 JSON）：把 references/builder_template.py 的 Builder.validate() 函数抠出来跑一遍。禁止没跑自检就写文件。

7. Error Prevention「常见踩坑与根因」

记录已发生过的故障 + 根因 + 永久规避方式：

7.1 图生成后无法显示「空白 / 转 Excalidraw 视图后报错」

根因：Obsidian Excalidraw 插件首次打开 .md 文件时会自动把 json 压缩为 compressed-json base64。压缩输入若违反任一条件，输出 base64 会损坏（出现意外换行、=== 多余 padding、截断）：

7.2 Text Elements 段与 JSON 不同步

根因：^id 与 JSON 中 text element 的 id 字段不一致，插件会重生成 Text Elements 段并破坏原内容。

规避：每个 text element 在 Text Elements 段必须有对应 ^id 行，且字符串完全一致。生成前自检 ^xxx 与 JSON "id":"xxx" 一一对应。

7.3 重新打开后 Text Elements 出现重复条目

根因：插件 round-trip 时，原 Text Elements 段没被清理，新内容追加在后面。

规避：用户改动后若发现重复，让用户在命令面板执行 Excalidraw: Decompress current Excalidraw file，再手动清理重复段，或直接重新生成整个文件覆盖。

7.4「最坑」打开后画布完全空白，但 JSON 看起来没问题

症状：

• 文件用 Python json.loads 校验通过
• Obsidian 自动压缩为 compressed-json 没报错
• 用 lzstring 解压压缩内容后 → "elements": []（整个数组被插件丢弃）
• 画布空白，没有任何错误提示

根因：每个 element 的 index 字段必须是合法的 fractional-indexing 字符串。Excalidraw 用此字段决定 z-order，插件会在加载时对所有 element 调用 validateFractionalIndex，任何一个不合法整个 elements 数组就会被静默丢弃（不抛错，不警告）。

合法规则（base-62 字母表 0-9A-Za-z）：

• 第一字符是排序桶（通常 a）
• 末字符不能是 0（fractional-indexing 禁止"尾部零"，因为 a0 与 a00 在数值上等价 → 不规范）
• 中间字符可以是任何 base-62 字符
• ✅ 合法：a1, a2, aA, aZ, aa, az, b1, aOg
• ❌ 非法：a0（注意 a0 本身也不合法因为以 0 结尾）、a00, a10, a20, aB0, b0

等等 a0 不合法？ 严格来说 a0 在 fractional-indexing 规范里是「base case」可用，但很多实现（包括 Excalidraw 用的版本）拒绝末字符是 0 的任何字符串。安全做法：永远不用末字符是 0 的索引。

生成规则（推荐）：N 个元素按 z-order 顺序分配 a1, a2, ..., a9, aA, aB, ..., aZ, aa, ab, ..., az（共 9+26+26 = 61 个安全值，够大多数图用）。超过 61 个就用 b1, b2, ...。

自检脚本（生成前必跑）：

indices = [e['index'] for e in elements]
bad = [i for i in indices if i.endswith('0')]
assert not bad, f"Trailing-zero indices: {bad}"
assert len(set(indices)) == len(indices), "Duplicate indices"

调试技巧：怀疑画布空白时，用 lzstring 解压 compressed-json，如果看到 "elements": [] 但你明明写了几十个，99% 是 index 问题。

# 一行式解压调试脚本
import re, json, lzstring
c = open('YourDiagram.md', encoding='utf-8').read()
m = re.search(r'```compressed-json\s*\n(.*?)\n```', c, re.DOTALL)
data = json.loads(lzstring.LZString().decompressFromBase64(m.group(1).replace('\n','').replace(' ','')))
print(f"elements: {len(data['elements'])}")  # 0 = index 问题；正常数 = 别处坏

7.5 子框 / 单盒里多行文字顶部对齐，没有居中

症状：sub-box 或 simple module 里的多行文字（如 [Title]\n=====\n- item1\n- item2）渲染时贴顶部，垂直方向没居中。

根因：自由文本（containerId: null）的 verticalAlign: "middle" 在 Excalidraw 的渲染逻辑里只对单行可靠，多行常被忽略。Excalidraw 内置的 container binding 才会真正"测量文本块高度并垂直居中放进容器"。

规避：

• 盒内多行文字必须用 container binding：rect 加 boundElements: [{type:"text", id:"<txt>"}] + customData: {legacyTextWrap: true}，text 加 containerId: "<rect>" + autoResize: false。
• Builder.module() 和 Builder.subbox() 默认就是这套。永远用它们，别手写。
• 父框的标题（顶部 y=parent.y+4）反而应该用自由文本 + valign: "top"（要的就是顶部对齐）。

7.6 用户提了小修改后，要重跑 builder 还是手改 JSON？

永远重跑 builder。理由：

• 文件已被 Obsidian 压缩成 compressed-json base64 — 手改 JSON 必须先解压（Excalidraw: Decompress current Excalidraw file 命令面板），改完插件可能再压缩一次，每次 round-trip 都是潜在的损坏点。
• 手改容易漏更新 Text Elements 段，触发 §7.2 不同步问题。
• builder 重跑保证所有自检都过、双向引用一致。

唯一例外：用户只改文字内容（不动结构）+ 文件还在 ```json fence（没被插件压缩过）。这种情况可以 Edit。否则一律重跑 Python builder。

8. 用户反馈消息（生成后简短报告）

✅ 已生成：{filename}
📍 路径：{absolute_path}
🎨 类型：{diagram_type} — {one-line rationale}
📖 在 Obsidian 中打开 → MORE OPTIONS → Switch to EXCALIDRAW VIEW

不要堆砌 emoji 段落。如对方需要调整（布局/配色/细节），等他提出再迭代。