drawio-generator

Draw.io 图表生成器

生成有效的 draw.io XML，创建专业图表。每个请求都会经过四个阶段——理解、提议、生成、验证——之后才会写入文件。正文刻意保持精简，以控制 Agent 的上下文预算；详细内容见 references/。

属于 diagram-generator 套件。若要绘制手绘／草图风格的图表，请改用 excalidraw-generator；diagram-generator 总入口会在两者之间进行路由。

环境检查

如果 Agent 工具可用，大型图表请按照 子 Agent 架构 使用子 Agent；在全新上下文中进行验证，可避免单次处理导致上下文溢出。若不可用（例如 Claude.ai），则在当前上下文中完成所有阶段，并依据 9 项检查进行自我审查。

编辑前同步仓库（必须）

运行一次：如果要读取现有 .drawio 文件（迭代），则在读取前运行；否则在第 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–6 并记录 sync: skipped (no origin)。
3. 运行 branch="$(git -C "$repo" rev-parse --abbrev-ref HEAD)"。若输出 HEAD，则跳过步骤 4–6 并记录 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 "drawio-generator pre-sync"，然后运行相同的 fetch 和 pull 命令，再运行 git -C "$repo" stash pop。
6. 如果 rebase 发生冲突，运行 git -C "$repo" rebase --abort；若步骤 5 创建了 stash，则随后运行 git -C "$repo" stash pop。如果 stash pop 发生冲突，保留 stash。在这两种情况下都不要写入文件；停止并询问用户如何继续。若用户没有回复，状态为 BLOCKED。

此技能只写入一个文件，不会提交任何内容。

核心工作流

阶段 1：理解

生成内容前，先确认要绘制的图表。

• 请求明确——简要复述，并提出一种可视化类型：

  “我将创建一张采用分层布局的 C4 容器图：顶部是 API 网关，中间是服务，底部是数据库。这样可以吗？”

• 输入含糊——针对性询问：主要实体、关系、流程方向，以及是否需要多页。
• 提供了代码、架构或配置——提取结构：
  • 代码 → 类／依赖／架构
  • SQL／架构 → ER 图
  • JSON／YAML 配置 → 架构、部署
  • 步骤／流程 → 流程图、时序图

阶段 2：提议

展示以下编号计划。

• 如果请求指定了图表类型和所有元素，用一行说明所选默认设置，然后进入阶段 3。
• 否则，等待用户确认或修改计划。用户回复前不要生成 XML。

1. 图表类型（若有多种适用类型，请提供备选项）
2. 关键元素——列出节点／形状
3. 布局——例如 (A) 自上而下、(B) 从左到右、(C) 分层
4. 风格——(1) 专业、(2) C4 官方、(3) 单色
5. 多页？——对于 C4，可选择每个级别单独一页
6. 预计复杂度——小型（<10）、中型（10–30）、大型（30+）

阶段 3：生成

在内存中生成 draw.io XML。阶段 4 将写入文件。

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

阅读 references/xml-authoring.md，了解形状／边／容器语法、尺寸规则、多页结构和文件命名。阅读 references/drawio-format.md，了解完整的 XML 架构和调色板。

每个形状都必须遵循以下关键规则：

• 样式字符串中始终包含 html=1;whiteSpace=wrap;
• 使用描述性的 kebab-case ID（node-api-gateway）
• 提供 <mxGeometry x y width height as="geometry"/>，尺寸应足以容纳标签
• 边需要 source、target 和 <mxGeometry relative="1" as="geometry"/>

阶段 4：验证

写入文件前运行全部 9 项检查。完整检查清单及修复模式请参阅 references/validation-checks.md。

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

9 项检查：（1）XML 结构和系统单元，（2）必需的形状属性，（3）每页 ID 唯一，（4）边绑定，（5）边几何，（6）无超过 10 px 的重叠，（7）容器层级，（8）语义完整性，（9）文本可读且形状尺寸合适。

---

预期输出

将有效的 .drawio 文件（原始 XML）写入磁盘，然后提供 最终报告。最小完整文件见 references/xml-authoring.md → 最小完整文件。

最终报告

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

Result: COMPLETE. Wrote flow.drawio (1 page, 2 shapes, 1 edge, 0 containers).
Evidence: /abs/path/flow.drawio. Validation 9/9 checks passed (inline, 1 cycle). sync: skipped (not a git repo)
Uncertainty: Rendering in draw.io untested. Assumed top-to-bottom flow; the request gave no direction.
Decision: No approval needed.

验收标准

每次运行都要验证以下内容：

• 已将 .drawio 文件写入磁盘，且其 XML 可解析；状态为 BLOCKED 时除外。
• references/validation-checks.md 中的检查 1–7 和 9 在每一页上均通过，否则最终报告需列出每项失败检查。
• 用户请求中的每个实体和关系都已在输出中体现（检查 8）。
• 最终报告以 Result: 和状态开头，并包含 Evidence:、Uncertainty: 和 Decision: 行。Evidence: 只能引用已运行的检查；只有全部 9 项检查通过时才可出现 9/9。
• 最终报告通过 references/final-report.md 中的四项读者检查（结果易于查找、事实与假设分开、主张可追溯、下一步决策明确）。未经人工审核者作答，无法确认其理解。

边缘情况

• 输入为空或含糊（“make a diagram”）：生成前提出有针对性的澄清问题——绝不生成占位内容。
• 图表非常庞大（>50 个元素）：提醒用户单页会显得拥挤；提供多页或分层 C4 方案。
• 不支持的图表类型（例如，带真实日期轴刻度的甘特图）：说明限制，并提出最接近的受支持替代方案（例如，泳道时间线）。
• 用户提供了现有的 .drawio 文件：先读取文件，保留现有单元格 ID，并追加新元素——绝不从头重新生成。
• 布局约束冲突：指出冲突，并询问用户哪项约束优先。
• 跨页面 ID 冲突：每个 <diagram> 都有独立的 ID 命名空间；每页都必须分别包含系统单元格 id="0" 和 id="1"。
• 文本超出形状容量：每多一行就自动将形状高度增加约 20px，而不是任由文本悄然溢出。

---

阶段完成报告

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

样式和图表类型

默认样式为 Professional；C4 请求使用官方 C4 调色板。颜色规则和支持的图表类型见：references/xml-authoring.md → 样式指南和支持的图表类型。

迭代

迭代现有图表时，读取文件并在内存中修改 XML。保留未更改元素的 ID。重写文件前，对结果运行第 4 阶段；若结果为 BLOCKED，则保持原文件不变。

---

子 Agent 架构

使用第 2 阶段的复杂度估算：大型图表（30 个或更多元素）运行此子 Agent 循环；小型和中型图表则在主流程中运行。

第 3 阶段 — agents/xml-generator.md

• 接收：图表类型、元素、边、样式、复杂度
• 输出：包含所有必需属性的完整 draw.io XML
• 约束：形状尺寸应足以容纳文本标签

第 4 阶段 — 审查循环（最多 3 轮）

1. 验证 — 启动 agents/xml-validator.md。输出全部 9 项检查的 PASS/FAIL。
2. 修复 — 若结果为 NEEDS_FIX，则根据报告启动 agents/xml-fixer.md。它会修补 XML，而不是重新生成。跳过语义或结构问题（这些需要修改生成器）。
3. 重新验证，并将 cycle 加 1，直到结果为 PASS 或 cycle == 3。如果修复器返回 ready_for_validation: false（检查 1 或 8），则根据验证器报告重新启动 agents/xml-generator.md；这计为一轮。
4. 将 XML 和最后一份验证器报告返回给主 Agent，由主 Agent 执行第 4 阶段的步骤 1–4（写入、PARTIAL 或 BLOCKED）。