excalidraw-generator

Excalidraw 图表生成器

生成有效的 Excalidraw JSON 格式的专业图表。每个请求在写入文件前都会经过四个阶段：理解、提议、生成、验证。正文保持精简，以节省 Agent 的上下文预算；详细内容见 references/。

属于 diagram-generator 套件。若需生成精确且可在 draw.io 中编辑的输出，请改用 drawio-generator；diagram-generator 总入口会在两者之间进行路由。

适用场景

frontmatter 中的 description 用于设定触发条件和排除项。输出：一个 .excalidraw 文件；仅在用户提出要求时，才额外生成配套的 .md 文件。

环境检查

如果 Agent 工具可用，则对于大型图表，按照 Subagent Architecture 使用子 Agent；通过全新上下文进行验证可避免单次处理时上下文溢出。如果不可用（例如 Claude.ai），则在行内运行每个阶段，并根据 10 项检查进行自我审查。

编辑前同步仓库（强制）

在读取现有 .excalidraw 文件之前（迭代），或者在第 4 阶段写入文件之前，执行一次此操作。同步目标是输出文件所在的目录。

1. 运行 repo="$(git -C "<output dir>" rev-parse --show-toplevel)"。如果失败，则跳过同步并记录 sync: skipped (not a git repo)。
2. 运行 git -C "$repo" remote get-url origin。如果失败，则跳过步骤 3–7 并记录 sync: skipped (no origin)。
3. 运行 branch="$(git -C "$repo" rev-parse --abbrev-ref HEAD)"。如果输出为 HEAD，则跳过步骤 4–7 并记录 sync: skipped (detached HEAD)。
4. 运行 git -C "$repo" status --porcelain。如果输出为空，则运行 git -C "$repo" fetch origin && git -C "$repo" pull --rebase origin "$branch"。
5. 如果输出不为空，则运行 git -C "$repo" stash push -u -m "excalidraw-generator pre-sync"，随后运行相同的 fetch 和 pull 命令，然后运行 git -C "$repo" stash pop。
6. 如果 fetch 或 pull 在 rebase 开始前失败（网络、身份验证或远程分支不存在），不要重试。如果步骤 5 执行了 stash，则运行 git -C "$repo" stash pop，记录 sync: failed (<first error line>)，然后继续。最终报告应在 Uncertainty: 行中重复此记录。
7. 如果发生 rebase 冲突，运行 git -C "$repo" rebase --abort，然后在步骤 5 执行了 stash 时运行 git -C "$repo" stash pop。如果 stash pop 发生冲突，请保留 stash。在这两种情况下，都不要写入文件；停止并询问用户如何继续。若用户未回复，状态为 BLOCKED。

此技能不会提交任何内容。

核心工作流

阶段 1：理解

在生成任何内容之前，确认要绘制的内容。

• 请求明确 — 用一句话复述请求，并提出一种可视化类型。
• 输入含糊 — 询问实体、关系、流程方向和样式。
• 代码、数据、架构或文件 — 提取结构（SQL → ER，步骤 → 流程图；完整映射见 references/diagram-types.md）。

阶段 2：提议

展示下面的编号计划。

• 如果请求指定了图表类型和所有元素，或者用户说“直接做”，则用一行说明所选默认项，并进入阶段 3。默认项：手绘风格、roughness: 1、Virgil 字体（fontFamily: 1）、最合适的布局。
• 否则，等待用户确认或修改计划。在用户回复之前，不要生成 JSON。

1. 图表类型 — 参见 references/diagram-types.md 中的目录；如果有多种合适类型，则提供带编号的选项。
2. 关键元素 — 列出节点和形状。
3. 布局 — 例如 (A) 从上到下、(B) 从左到右、(C) 放射状。
4. 样式 — 渲染风格（手绘、草图、简洁）以及适合用途的配色方案；变体见 references/style-and-iteration.md。没有固定调色板。
5. 预计复杂度 — 小型（<10 个元素）、中型（10–30 个元素）、大型（>30 个元素）。

阶段 3：生成

在内存中编写 .excalidraw 文档（原始 JSON，不加包装）。阶段 4 会写入文件。

输出路径：使用用户提供的路径；否则在当前工作目录中使用以 .excalidraw 结尾的描述性 kebab-case 名称（auth-flow.excalidraw）。如果该文件已存在，且用户没有要求更新它，请在覆盖前向用户确认；如需更新，请遵循 迭代。

从 references/excalidraw-format.md → 顶层结构 中的封装结构开始（type、version、source、elements、appState、files）；根据图表设置 theme 和 viewBackgroundColor。该文件包含完整的元素架构和字段默认值。

每个元素都必须遵循以下关键规则：

• 包含 references/validation-checks.md → 检查 2 中的所有必填字段。
• 使用描述性的 kebab-case ID（node-api-gateway）。
• 调整每个容器的尺寸，使其能容纳所绑定的文本（检查 10）；扩大形状，切勿将文本缩小到低于 fontSize: 16。
• 双向绑定文本和箭头（containerId ↔ boundElements；startBinding/endBinding ↔ boundElements）。

**嵌入 Markdown：**仅在用户提出要求时，先写入 .excalidraw 文件，再创建一个配套的 .md 文件，在标记为 excalidraw 的围栏代码块中放入相同的 JSON。

阶段 4：验证

写入文件前，对内存中的 JSON 执行全部 10 项检查。检查项、检查 10 的公式以及修复方法，参见 references/validation-checks.md。

1. 执行 10 项检查。如果全部通过，则运行 仓库同步、写入文件，并以状态 COMPLETE 提供 最终报告。
2. 如果检查失败，修复后重新执行全部 10 项检查。检查 1 或 8 失败时，需要重新执行阶段 3 生成内容，不能只打补丁。最多进行 3 轮修复。
3. 如果检查 1–6 通过，但第 3 轮后检查 7–10 中仍有失败，则运行 仓库同步、写入文件，并报告 PARTIAL，同时列出失败的检查编号。
4. 如果第 3 轮后检查 1–6 中仍有失败，则不要写入文件。报告 BLOCKED，并列出失败项。

10 项检查：（1）JSON 封装；（2）必填字段；（3）ID 唯一；（4）文本绑定；（5）箭头绑定；（6）箭头点；（7）重叠；（8）语义完整性；（9）文本可读性；（10）形状与文本适配——最常见的失败项。

---

预期输出

对于“绘制用户登录流程的流程图”，应将 login-flow.excalidraw 文件（原始 JSON）写入磁盘，然后提供 最终报告。绑定的形状和标签示例见 references/excalidraw-format.md → 最简文本绑定示例。

最终报告

每次运行结束时（包括停止的情况），都以以下简短文本块收尾。等待用户回答的阶段 1–2 问题不算运行结束；如果用户结束运行但没有回答，则报告 BLOCKED。状态为 COMPLETE（文件已写入，10/10 项检查全部通过）、PARTIAL（文件已写入，但检查 7–10 中有失败项）或 BLOCKED（未写入文件）。填写规则、PARTIAL 和 BLOCKED 示例以及读者检查，参见 references/final-report.md。示例：

Result: COMPLETE. Wrote login-flow.excalidraw (6 shapes, 6 text labels, 5 arrows).
Evidence: /abs/path/login-flow.excalidraw. Validation 10/10 checks passed (inline, 1 cycle). sync: skipped (not a git repo)
Uncertainty: Rendering in Excalidraw untested. Assumed top-to-bottom flow; the request gave no direction.
Decision: No approval needed.

验收标准

每次运行都要核实以下内容：

• 已将 .excalidraw 文件写入磁盘，且其 JSON 可解析，顶层包含 type、version、elements、appState、files；状态为 BLOCKED 时除外。
• references/validation-checks.md 中的检查 1–7、9 和 10 均通过，或最终报告逐项列出所有失败的检查。
• 用户请求中的每个实体和关系都已体现在输出中（检查 8）。
• 最终报告以 Result: 和状态开头，并包含 Evidence:、Uncertainty: 和 Decision: 行。Evidence: 只能引用已执行的检查；只有 10 项全部通过时才可出现 10/10。
• 最终报告通过 references/final-report.md 中的四项读者检查（结果易于找到、事实与假设分开、主张可追溯、下一步决策明确）。未获得人工审阅者的回复时，无法确认人工理解情况。

边界情况

• 输入为空或含糊不清（“制作一个图表”）：先提出有针对性的澄清问题，再生成内容；绝不生成占位内容。
• 大型图表（>30 个元素）：运行 Subagent Architecture 循环；最多进行 3 轮修复。
• 超大型图表（>50 个元素）：提醒用户单个画布会显得拥挤；提出使用多个画框、拆分为多个文件或先生成概览，并等待用户选择。
• 关系含义不明确：生成前询问方向和基数。
• 不支持的图表类型（例如需要真实坐标轴刻度的图表）：说明限制，并从 references/diagram-types.md 中提出最接近的受支持类型。
• 用户提供现有的 .excalidraw 文件：遵循 Iteration；绝不从头重新生成。

更多边界情况：references/style-and-iteration.md。

---

阶段完成报告

每个阶段结束后，打印一份简短的状态报告，列出该阶段的检查项；模板和各阶段的检查项见 references/step-reports.md。Validate 报告必须先于 Final Report；它不能取代后者。

迭代

迭代现有图表时，读取文件并在内存中修改 JSON。保留未更改元素的 ID（请求模式：references/style-and-iteration.md → Iteration）。将结果写回文件前，先对其运行 Phase 4；若结果为 BLOCKED，则保持原文件不变。

---

子 Agent 架构

大型图表（>30 个元素）运行此循环；其他图表则以内联方式处理。详情：references/style-and-iteration.md → Subagent Architecture。

1. 生成 — 根据已确认的计划启动 agents/json-generator.md。
2. 验证 — 启动 agents/json-validator.md；它会针对全部 10 项检查报告 PASS/FAIL。
3. 修复 — 若结果为 NEEDS_FIX，启动 agents/json-fixer.md；它会打补丁，而不是重新生成。若其返回 ready_for_validation: false（检查项 1 或 8），则重新启动生成器。每次修复或重新生成计为一轮；最多进行 3 轮。
4. 主 Agent 对返回的 JSON 和验证器的最新报告执行 Phase 4 的第 1–4 步。