| name | ah-excalidraw-layout |
| description | Excalidraw 流程图排版引擎。输入结构化内容，输出零重叠的 Excalidraw 文件。
内嵌错题本规则，自动规避文字重叠/圆角挤压/容器撑破/箭头交叉等问题。
触发方式：/excalidraw、/画流程图、「帮我画Excalidraw」「用Excalidraw排版」「把这个做成图」
Not for: 自由绘图、手绘风格草图
|
ah-excalidraw-layout：Excalidraw 流程图排版引擎
你不是画图工具，你是排版引擎。每次排版前先读完本文件的错题本规则。所有规则来自真实翻车案例。
错题本（MUST READ FIRST）
错误 1：文字与图形重叠
- 错误：多个文字元素放在同一个
(x, y)，或文字和矩形使用相同坐标但未绑定
- 正确：使用
box() 工厂函数自动绑定文字到矩形；独立文字必须确保距容器边框 >= 8px
错误 2：Group Frame 标签徽章与内部文字重叠
- 错误：在 group frame 边框上放置标签徽章（
y - 12），与内部标题重叠
- 正确：取消标签徽章。Group 标题作为框内首行文字，放在
y + PAD 位置
错误 3：容器使用固定高度
- 错误：
rect(x, y, w, 350) 硬编码高度
- 正确：
groupH = PAD + HEADER_H + 6 + items * (ITEM_H + ITEM_GAP) + PAD
错误 4：内容向右无限扩展
- 错误：传记卡片放在右侧边栏，总宽度超出屏幕
- 正确：所有内容纵向排列，最大宽度 900px。需要并排时最大两列，单列 <= 400px
错误 5：箭头交叉混乱
- 错误：左右两组各有独立箭头直接连向下一节点
- 正确：左右两组先汇聚到"汇总节点"，再从汇总节点连向下一段
错误 6：大圆角挤压文字
- 错误：
roundness: { type: 3 }（大圆角）+ 文字贴近边框
- 正确：使用
{ type: 2 }（中小圆角），文字区相对边框内缩 >= 24px
错误 7：中文弯引号导致 JS 解析错误
- 错误：JS 双引号字符串内包含中文弯引号
""
- 正确：包含中文引号的字符串用单引号包裹，或替换为直角引号
「」
错误 8：同一卡片内不同内容区块无分隔
- 错误：传记卡片把基本信息和创作金句堆在一起
- 正确：不同区块之间加水平分隔线或 16px 以上空行
错误 9：不同体系的分组之间强行连线
- 错误：在两个独立体系的分组之间添加多条交叉虚线（如借势 pillars 和主角 pillars 之间 4 条 dot 连线）
- 正确：两个独立体系不需要在 pillar 级别建立关联。如果确实有关联，在更上层（汇总节点）统一交汇，不在细粒度节点之间拉线
错误 10：字体不统一 — 手写体与印刷体混用
- 错误：「AI 风口」「能力一」「能力二」等节点使用标准印刷字体（fontFamily: 2），与标题和正文的 Virgil 手写体（fontFamily: 1）风格割裂，像两套视觉系统拼在一起
- 发现轮次：第 7 轮（字体/边框/箭头/连线四维统一化调整）
- 正确：全图所有文字元素
fontFamily: 1（Virgil 手写体），生成后逐元素扫描确认无遗漏
- 自检：
grep -c '"fontFamily":2' 返回 0
错误 11：边框风格不统一 — 直角细边与圆角粗边混用
- 错误：顶部节点（如三风口框）使用
strokeWidth: 1 + 直角边框，下方色块使用 strokeWidth: 2 + roundness: {type: 2}，视觉上像两套系统拼接
- 发现轮次：第 7 轮
- 正确：全图所有矩形统一
strokeWidth: 2、roundness: {type: 2}、strokeStyle: "solid"、roughness: 2
错误 12：箭头样式不统一 — 双线/单线/粗线/细线混用
- 错误：部分箭头是双线夹角样式，部分是普通细线箭头，部分是粗线，视觉噪音大
- 发现轮次：第 7 轮
- 正确：主流程箭头
strokeWidth: 1.5、辅助/汇聚箭头 strokeWidth: 1，全部使用 strokeStyle: "solid"、endArrowhead: "arrow"、startArrowhead: null，禁止双线或虚线样式
- 自检：所有 arrow 元素的
strokeStyle === "solid" 且 endArrowhead === "arrow"
错误 13：Mermaid 转换残留锚点 — 无意义的灰色控制点
- 错误：mermaid-to-excalidraw 转换器在多对多连接时自动插入 waypoint/anchor point（灰色圆点），这些不是有含义的内容节点，但视觉上看起来像"有东西"
- 发现轮次：第 5 轮（灰点/锚点/交叉线清理）
- 正确：直接生成 Excalidraw JSON 时（本 skill 的模式），永远不创建中间锚点。箭头路径为直接起点→终点，最多一次折弯
- 自检：不存在 type 非 arrow/rectangle/text 的中间节点
错误 14：文字溢出画布 — 节点宽度小于文字所需宽度
- 错误：节点设置了固定宽度，但文字行长度超出容器宽度，导致文字被截断或溢出到画布外
- 发现轮次：第 3 轮（文字溢出/分组重叠/连线交叉/宽度失控四合一）
- 正确：为每个节点计算所需宽度，公式：
nodeW = max(各文字行估算宽度) + 2 × PAD。中文字符估算 fontSize × 1.0 px，英文/数字估算 fontSize × 0.6 px
- 自检：对每个 rect+text 组合，检查文字最长行的估算宽度 <= rect.width - 2 × PAD
错误 15：连接线被分组边框遮盖 — z-index 顺序导致线条不可见
- 错误：细的连接线（strokeWidth 0.8-1.2）被粗的分组边框（strokeWidth 2+）压在下面，导致关键连线在视觉上消失
- 发现轮次：第 5 轮
- 正确：连接线元素在 JSON elements 数组中的位置必须排在所有分组框矩形之后（后渲染 = 在上层）。分组框 strokeWidth 不超过连接线 strokeWidth + 1.0
错误 16：连接线斜向交叉 — 左节点连右目标、右节点连左目标
- 错误：「真实案例」到「能力一/能力二」的连线斜向穿插，以及「汇合」到「怎么练/核心洞察」的橙色线和紫色线交叉
- 发现轮次：第 7 轮（四维统一化调整中的连线部分）
- 正确：左右一一对应路由 — 左侧来源 → 左侧目标，右侧来源 → 右侧目标。从左侧节点出发的箭头终点绝不出现在右侧节点上，反之亦然
- 自检：对每组并排节点，验证左侧组的箭头终点 x 坐标 < 页面中线，右侧组的箭头终点 x 坐标 > 页面中线
错误 17：container 绑定 ID 错位 — rect 和 text 互相引用不存在的 ID
- 错误：
box() 工厂函数使用 tid = rid() 生成一个 ID，然后 text(..., containerId=tid) 和 rect(..., boundElements=[tid])——但 text() 和 rect() 内部各自通过 rid() 生成自己的真实 id，tid 既不是 text 的 id 也不是 rect 的 id。结果：rect 的 boundElements 指向不存在的元素，text 的 containerId 指向不存在的容器。渲染出来是空壳矩形，文字消失或错位。
- 发现轮次：第 8 轮（2026-07-22 三棱镜定位法 Excalidraw 生成，用户发现橙色案例框内每行前面的圆角框是空的）
- 正确：禁止使用 containerId / boundElements 绑定。所有 text 和 rect 用绝对坐标分别放置，text 坐标 = rect 坐标 + 内边距偏移。如必须用工厂函数，函数必须返回并正确关联两个元素的真实 id。
- 自检：
grep -c '"containerId":null' 等于 text 元素总数；grep -c '"boundElements"' 返回 0
已验证模式（正例）
以下模式经 6 轮调试验证有效，生成时优先使用：
模式 1：游标推进布局
所有 y 坐标通过 curY 累进，禁止硬编码。每个 section 结束后 curY += sectionH + GAP。
模式 2：箭头汇聚路由
多来源 → 单汇总节点 → 下一段。禁止 N 条独立箭头从不同来源直接连向同一目标。
模式 3：左右一一对应路由（防交叉）
双列并排时，左侧列的箭头只连接左侧目标，右侧列只连接右侧目标。
模式 4：语义颜色体系
| 角色 | 主色 | 背景色 | 用于 |
|---|
| 核心主张 | #f08c00 | #ffec99 | 标题/论点/判断力 |
| AI/技术 | #1971c2 | #d0ebff / #e7f5ff | AI 能力/工具 |
| 案例/验证 | #2f9e44 | #d3f9d8 | 真实案例 |
| 终点/结论 | #e03131 | #ffc9c9 | 最终结论 |
| 洞察/升华 | #9c36b5 | #e599f7 | 核心洞察 |
| 训练/行动 | #e8590c | #ffe8cc | 怎么练/行动 |
| 历史/辅助 | #868e96 | #f8f9fa | 历史案例 |
| 汇聚标记 | #adb5bd | #e9ecef | 箭头汇聚节点 |
模式 5：节点宽度自适应公式
估算宽度 = 中文字符数 × fontSize × 1.0 + 英文/数字字符数 × fontSize × 0.6
nodeW = max(各行估算宽度) + 2 × PAD
模式 6：双列 + 单列混合布局
- 标题/核心主张/案例/终点 → 单列全宽，居中
- 对比项/并列能力/两个分支 → 双列并排
- 汇聚节点 → 窄条居中
质量检查清单（生成后逐项自检）
| # | 检查项 | 标准 | 对应错题 |
|---|
| 1 | 字体统一 | 所有 text 元素 fontFamily: 1 | #10 |
| 2 | 边框统一 | 所有 rect 元素 strokeWidth: 2, roundness.type: 2 | #11 |
| 3 | 箭头统一 | 所有 arrow 元素 strokeStyle: solid, endArrowhead: arrow | #12 |
| 4 | 无残留锚点 | 不存在 type 非 arrow/rectangle/text 的节点 | #13 |
| 5 | 文字不溢出 | 每行估算宽度 <= 容器宽度 - 2 × PAD | #14 |
| 6 | 连接线可见 | 连接线排在分组框之后 | #15 |
| 7 | 无交叉连线 | 左源→左目标，右源→右目标 | #16 |
| 8 | 容器自适应 | group frame 高度 = 计算值，无硬编码 | #3 |
| 9 | 内边距充足 | 文字距容器边框 >= 20px | #6 |
| 10 | 圆角安全 | roundness.type <= 2，文字区内缩 >= 24px | #6 |
| 11 | 引号安全 | JS 字符串无不匹配引号 | #7 |
| 12 | 区块分隔 | 不同内容区块间有分隔线或 16px+ 间距 | #8 |
| 13 | 宽度不超限 | max(x + width) <= 960 | #4 |
| 14 | 箭头先汇聚 | 多来源 → 单汇总 → 下一段 | #5 #9 |
| 15 | 无标签重叠 | Group 标题在框内首行，不在边框上 | #2 |
| 16 | 文字不重叠 | 非绑定文字元素各有独立坐标 | #1 |
| 17 | 无 container 绑定 | 所有 text.containerId = null，rect.boundElements 不存在 | #17 |
任一检查项未通过 → 回退修复对应元素，禁止带着缺陷交付。
排版规范
全局常量
PAD = 24 // 容器内边距
HEADER_H = 22 // 分组标题高度
GAP = 20 // 段间距
ITEM_GAP = 4 // 同组条目间距
MAX_W = 880 // 最大页面宽度
布局模式
- 单列全宽（标题、金句区、总结）：PAGE_W = 880
- 双列并排（对比项、并列能力、两个分支）：左列 LEFT_X = 60，右列 LEFT_X + 400，单列 COL_W = 380
游标推进
所有 y 坐标通过 curY 逐行累进，禁止硬编码：
curY = 30
section1: curY += h1 + GAP
section2: curY += h2 + GAP
颜色体系
| 用途 | 主色 | 背景色 |
|---|
| 借势 | #c92a2a | #fff5f5 |
| 主角 | #6741d9 | #f8f0ff |
| 金句/交汇 | #e8590c | #fff9db |
| 总结/启示 | #2b8a3e | #ebfbee |
| 生平/辅助 | #495057 | #f8f9fa |
完整语义颜色体系见上方「已验证模式 → 模式 4」。
箭头规范
- 主流程箭头：strokeWidth 1.5, strokeStyle solid, endArrowhead arrow
- 汇聚辅助箭头：strokeWidth 1.0, strokeStyle solid, endArrowhead arrow
- 禁止：双线夹角样式、虚线样式、startArrowhead（见错题 #12）
- 多来源先汇聚到单节点，再统一流向下段（见错题 #5 #9 #16）
迭代记录
v1.3.0：container 绑定 bug 修复（2026-07-22）
- 新增错题 #17：container 绑定 ID 错位
box() 工厂函数的 tid = rid() 模式被证明在 text() 和 rect() 各自生成内部 id 时无法正确关联- 全局规则：禁止使用 containerId / boundElements，统一用绝对坐标定位
- 质量清单新增第 17 项检查
v1.2.0：错题本从 9 条扩至 16 条 + 新增正例模式库（2026-07-22）
来源：6 轮 Excalidraw 排版调试验证对话记录
对话覆盖的问题领域：
- Round 2：Mermaid 语法 → Excalidraw 转换原理
- Round 3：布局溢出四合一（文字溢出/分组重叠/连线交叉/宽度失控）
- Round 4：容器撑爆（固定高度/大圆角挤压/区块无分隔/标题贴边）
- Round 5：锚点清理（灰色 waypoint/连接线被遮盖/跨体系交叉）
- Round 7：四维统一化（字体/边框/箭头/连线风格不一致）
新增错题 7 条（#10-#16）：
| # | 错误 | 根因 | 解决方案 |
|---|
| 10 | 字体不统一 | 部分节点使用印刷体 fontFamily:2 | 全图 fontFamily:1（Virgil 手写体） |
| 11 | 边框不统一 | 顶部用直角细边 vs 下方圆角粗边 | 统一 strokeWidth:2 + roundness.type:2 |
| 12 | 箭头不统一 | 双线/单线/粗线/细线混用 | 主流程 1.5 / 辅助 1.0 |
| 13 | Mermaid 残留锚点 | 转换器自动插入 waypoint | 直接生成 JSON 时不创建中间节点 |
| 14 | 文字溢出画布 | 节点宽度 < 文字所需宽度 | 宽度自适应公式 |
| 15 | 连接线被遮盖 | 分组框 strokeWidth 大于连接线 + z-index 在前 | 连接线排在分组框之后 |
| 16 | 连线斜向交叉 | 左源→右目标 / 右源→左目标 | 左右一一对应路由 |
新增正例（已验证模式 6 个）：游标推进 / 箭头汇聚 / 左右对应 / 语义颜色 / 宽度自适应 / 混合布局
质量检查清单：从 9 项扩至 16 项，每项标注对应错题编号
v1.1.0：初版错题本（2026-07-22）
- 9 条错题：#1-#9（文字重叠/标签重叠/固定高度/无限右扩/箭头交叉/圆角挤压/引号错误/无分隔/跨体系连线）
- 排版规范、颜色体系、箭头规范初始版
