draw-io-diagram-generator

Draw.io 图表生成器

此技能使你能够生成、编辑和验证 draw.io（.drawio）图表文件，并确保其 mxGraph XML 结构正确。所有生成的文件都能直接在 Draw.io VS Code 扩展 （hediet.vscode-drawio）中打开，无需任何手动修复。如果你愿意，也可以在 draw.io 网页应用或桌面应用中打开这些文件。

---

1. 何时使用此技能

触发短语（看到这些内容时加载此技能）

• "创建图表"、"绘制流程图"、"生成架构图"
• "设计时序图"、"制作 UML 类图"、"构建 ER 图"
• "添加 .drawio 文件"、"更新图表"、"可视化流程"
• "记录架构"、"展示数据模型"、"绘制服务交互图"
• 任何要求生成或修改 .drawio、.drawio.svg 或 .drawio.png 文件的请求

支持的图表类型

图表类型	可用模板	描述
流程图	assets/templates/flowchart.drawio	包含决策和分支的流程流
系统架构	assets/templates/architecture.drawio	多层 / 分层服务架构
时序图	assets/templates/sequence.drawio	参与者生命线和带时序的消息流
ER 图	assets/templates/er-diagram.drawio	带关系的数据库表
UML 类图	assets/templates/uml-class.drawio	类、接口、枚举、关系
网络拓扑	（使用形状库）	路由器、服务器、防火墙、子网
BPMN 工作流	（使用形状库）	业务流程事件、任务、网关
思维导图	（手动）	中心主题及向外辐射的分支

---

2. 前提条件

• 如果在启用 VS Code 集成的情况下运行，请安装 drawio 扩展：draw.io VS Code 扩展 — hediet.vscode-drawio（扩展 id）。使用以下命令安装：

  ext install hediet.vscode-drawio
  

• 支持的文件扩展名：.drawio、.drawio.svg、.drawio.png
• Python 3.8+（可选）— 用于 scripts/ 中的验证和形状插入脚本

---

3. Agent 分步工作流

对于每个图表生成任务，请按顺序执行以下步骤。

步骤 1 — 理解请求

询问或推断：

1. 图表类型 — 需要哪种图表？（流程图、架构图、UML、ER、时序图、网络图……）
2. 实体 / 参与者 — 主要组件、参与者、类或表是什么？
3. 关系 — 它们如何连接？方向是什么？基数是多少？
4. 输出路径 — .drawio 文件应保存到哪里？
5. 现有文件 — 我们是创建新文件还是编辑现有文件？

如果请求含义不明确，请根据上下文推断最合理的图表类型（例如 "展示这些表" → ER 图，"展示 API 调用如何流转" → 时序图）。

步骤 2 — 选择模板或从头开始

• 当图表类型与 assets/templates/ 中的某个模板匹配时，使用模板。复制模板结构并替换占位符值。
• 对于新颖的布局，从头开始。从最小有效骨架开始：

<mxfile host="Electron" modified="" version="26.0.0">
  <diagram id="page-1" name="Page-1">
    <mxGraphModel dx="1422" dy="762" grid="1" gridSize="10" guides="1"
                  tooltips="1" connect="1" arrows="1" fold="1"
                  page="1" pageScale="1" pageWidth="1169" pageHeight="827"
                  math="0" shadow="0">
      <root>
        <mxCell id="0" />
        <mxCell id="1" parent="0" />
        
      </root>
    </mxGraphModel>
  </diagram>
</mxfile>

规则：id 0 和 1 始终是必需的，并且必须是前两个单元格。切勿重复使用它们。

步骤 3 — 规划布局

在生成 XML 之前，先勾勒出逻辑布局：

• 组织成行或层级（使用泳道表示层）
• 水平间距：同一行形状之间为 40–60px
• 垂直间距：层级行之间为 80–120px
• 标准形状尺寸：流程框为 120x60 px，泳道为 160x80 px
• 默认画布：A4 横向 = 1169 x 827 px

第 4 步 — 生成 mxGraph XML

顶点单元格（每个形状）：

<mxCell id="unique-id" value="Label"
        style="rounded=1;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;"
        vertex="1" parent="1">
  <mxGeometry x="100" y="100" width="120" height="60" as="geometry" />
</mxCell>

边单元格（每个连接线）：

<mxCell id="edge-id" value="Label (optional)"
        style="edgeStyle=orthogonalEdgeStyle;html=1;"
        edge="1" source="source-id" target="target-id" parent="1">
  <mxGeometry relative="1" as="geometry" />
</mxCell>

关键规则：

• 每个单元格 id 在文件内必须全局唯一
• 每个顶点必须有一个 mxGeometry 子元素，包含 x、y、width、height、as="geometry"
• 每条边必须带有与现有顶点 id 匹配的 source 和 target——例外：浮动边（例如序列图中的生命线）改为在 <mxGeometry> 中使用 sourcePoint/targetPoint；参见 §4 序列图
• 每个单元格的 parent 必须引用一个现有的单元格 id
• 当标签包含 HTML（<b>、<i>、<br>）时，在 style 中使用 html=1
• 转义标签中的 XML 特殊字符：& => &，< => <，> => >

第 5 步 — 应用正确的样式

使用标准语义色板以保持一致：

用途	fillColor	strokeColor
主要 / 信息	#dae8fc	#6c8ebf
成功 / 开始	#d5e8d4	#82b366
警告 / 判断	#fff2cc	#d6b656
错误 / 结束	#f8cecc	#b85450
中性	#f5f5f5	#666666
外部 / 合作方	#e1d5e7	#9673a6

按图表类型划分的常用 style 字符串：

# Rounded process box (flowchart)
rounded=1;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;

# Decision diamond
rhombus;whiteSpace=wrap;html=1;fillColor=#fff2cc;strokeColor=#d6b656;

# Start/End terminal
ellipse;whiteSpace=wrap;html=1;fillColor=#d5e8d4;strokeColor=#82b366;

# Database cylinder
shape=mxgraph.flowchart.database;whiteSpace=wrap;html=1;fillColor=#f8cecc;strokeColor=#b85450;

# Swimlane container (tier)
swimlane;startSize=30;fillColor=#dae8fc;strokeColor=#6c8ebf;fontStyle=1;

# UML class box
swimlane;fontStyle=1;align=center;startSize=40;fillColor=#dae8fc;strokeColor=#6c8ebf;

# Interface / stereotype box
swimlane;fontStyle=3;align=center;startSize=40;fillColor=#f5f5f5;strokeColor=#666666;

# ER table container
shape=table;startSize=30;container=1;collapsible=1;childLayout=tableLayout;

# Orthogonal connector
edgeStyle=orthogonalEdgeStyle;html=1;

# ER relationship (crow's foot)
edgeStyle=entityRelationEdgeStyle;html=1;endArrow=ERmany;startArrow=ERone;

完整的 style 键目录参见 references/style-reference.md，所有形状库名称参见 references/shape-libraries.md。

第 6 步 — 保存并验证

1. 写入文件到指定路径，扩展名为 .drawio
2. 运行验证器（可选但推荐）：

   python .github/skills/draw-io-diagram-generator/scripts/validate-drawio.py <path-to-file.drawio>
   

3. 告诉用户如何打开该文件：

   "在 VS Code 中打开 <filename>——它会借助 draw.io 扩展自动渲染。如果你愿意，也可以使用 draw.io 的 Web 应用或桌面应用。"

4. 提供简要描述，说明图表中的内容，让用户知道预期会看到什么。

---

4. 各类型图表配方

流程图

关键元素：开始（椭圆）=> 处理（圆角矩形）=> 判断（菱形）=> 结束（椭圆）

<mxCell id="start" value="Start"
        style="ellipse;whiteSpace=wrap;html=1;fillColor=#d5e8d4;strokeColor=#82b366;"
        vertex="1" parent="1">
  <mxGeometry x="500" y="80" width="120" height="60" as="geometry" />
</mxCell>


<mxCell id="p1" value="Process Step"
        style="rounded=1;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;"
        vertex="1" parent="1">
  <mxGeometry x="500" y="200" width="120" height="60" as="geometry" />
</mxCell>


<mxCell id="d1" value="Condition?"
        style="rhombus;whiteSpace=wrap;html=1;fillColor=#fff2cc;strokeColor=#d6b656;"
        vertex="1" parent="1">
  <mxGeometry x="460" y="320" width="200" height="100" as="geometry" />
</mxCell>


<mxCell id="e1" value=""
        style="edgeStyle=orthogonalEdgeStyle;html=1;"
        edge="1" source="start" target="p1" parent="1">
  <mxGeometry relative="1" as="geometry" />
</mxCell>

架构图（三层）

为每一层使用泳道容器。所有服务框都是其泳道的子元素。

<mxCell id="tier1" value="Client Layer"
        style="swimlane;startSize=30;fillColor=#dae8fc;strokeColor=#6c8ebf;fontStyle=1;"
        vertex="1" parent="1">
  <mxGeometry x="60" y="100" width="1050" height="130" as="geometry" />
</mxCell>


<mxCell id="webapp" value="Web App"
        style="rounded=1;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;"
        vertex="1" parent="tier1">
  <mxGeometry x="80" y="40" width="120" height="60" as="geometry" />
</mxCell>

层与层之间的连接线使用绝对坐标，并设置 parent="1"。

序列图

关键元素：参与者（顶部）、生命线（垂直虚线）、激活框、消息箭头。

• 生命线：edge="1"，配合 endArrow=none 和 dashed=1，没有 source/target——在 geometry 中使用 sourcePoint/targetPoint
• 同步消息：endArrow=block;endFill=1
• 返回消息：endArrow=open;endFill=0;dashed=1
• 自调用：通过两个 Array 点让边向右绕行再折返

最小 XML 片段：

<mxCell id="actorA" value="Client"
        style="shape=mxgraph.uml.actor;pointerEvents=1;dashed=0;whiteSpace=wrap;html=1;aspect=fixed;"
        vertex="1" parent="1">
  <mxGeometry x="110" y="80" width="60" height="80" as="geometry" />
</mxCell>


<mxCell id="actorB" value="API Server"
        style="rounded=1;whiteSpace=wrap;html=1;fillColor=#fff2cc;strokeColor=#d6b656;"
        vertex="1" parent="1">
  <mxGeometry x="480" y="100" width="160" height="60" as="geometry" />
</mxCell>


<mxCell id="lifA" value=""
        style="edgeStyle=none;dashed=1;endArrow=none;"
        edge="1" parent="1">
  <mxGeometry relative="1" as="geometry">
    <mxPoint x="140" y="160" as="sourcePoint" />
    <mxPoint x="140" y="700" as="targetPoint" />
  </mxGeometry>
</mxCell>


<mxCell id="actA1" value=""
        style="fillColor=#dae8fc;strokeColor=#6c8ebf;"
        vertex="1" parent="1">
  <mxGeometry x="130" y="220" width="20" height="180" as="geometry" />
</mxCell>


<mxCell id="msg1" value="POST /orders"
        style="edgeStyle=elbowEdgeStyle;elbow=vertical;html=1;endArrow=block;endFill=1;"
        edge="1" source="actA1" target="actorB" parent="1">
  <mxGeometry relative="1" as="geometry" />
</mxCell>


<mxCell id="msg2" value="201 Created"
        style="edgeStyle=elbowEdgeStyle;elbow=vertical;dashed=1;html=1;endArrow=open;endFill=0;"
        edge="1" source="actorB" target="actA1" parent="1">
  <mxGeometry relative="1" as="geometry" />
</mxCell>

注意： 生命线是浮动边，在 <mxGeometry> 中使用 sourcePoint/targetPoint，而不是 source/target 属性。这是 draw.io 中序列图的标准做法。

ER 图

使用 shape=table 容器，配合 childLayout=tableLayout。行是 shape=tableRow 单元格，带有 portConstraint=eastwest。每行内部的列是 shape=partialRectangle。

关系箭头使用 edgeStyle=entityRelationEdgeStyle：

• 一对一：startArrow=ERone;endArrow=ERone
• 一对多：startArrow=ERone;endArrow=ERmany
• 多对多：startArrow=ERmany;endArrow=ERmany
• 强制：ERmandOne，可选：ERzeroToOne

UML 类图

类框是泳道容器。属性与方法均为纯文本单元格。分隔线是高度为零的泳道子元素。

按关系类型划分的箭头样式：

关系	样式字符串
继承（extends）	edgeStyle=orthogonalEdgeStyle;html=1;endArrow=block;endFill=0;
实现（implements）	edgeStyle=orthogonalEdgeStyle;dashed=1;html=1;endArrow=block;endFill=0;
组合	edgeStyle=orthogonalEdgeStyle;html=1;startArrow=diamond;startFill=1;endArrow=none;
聚合	edgeStyle=orthogonalEdgeStyle;html=1;startArrow=diamond;startFill=0;endArrow=none;
依赖	edgeStyle=orthogonalEdgeStyle;dashed=1;html=1;endArrow=open;endFill=0;
关联	edgeStyle=orthogonalEdgeStyle;html=1;endArrow=open;endFill=0;

---

5. 多页图

为复杂系统添加多个 <diagram> 元素：

<mxfile host="Electron" version="26.0.0">
  <diagram id="overview" name="Overview">
    
  </diagram>
  <diagram id="detail" name="Detail View">
    
  </diagram>
</mxfile>

每一页都有自己独立的单元格 id 命名空间。相同的 id 值可以出现在不同页面中而不会冲突。

---

6. 编辑现有图

修改现有 .drawio 文件时：

1. 先 读取 文件，以了解现有单元格 id、位置和父级层级
2. 确定目标图页面 —— 通过索引或 name 属性
3. 分配不与现有 id 冲突的新唯一 id
4. 遵循容器层级 —— 泳道的子元素使用相对于其父级的坐标
5. 验证连线 —— 在重新定位节点后，确认连线的 source/target id 仍然有效

使用 scripts/add-shape.py 安全地添加单个形状，而无需编辑原始 XML：

python .github/skills/draw-io-diagram-generator/scripts/add-shape.py docs/arch.drawio "New Service" 700 380

---

7. 最佳实践

布局

• 将形状对齐到 10px 网格（所有坐标都能被 10 整除）
• 将相关形状分组到泳道容器内
• 每页一个图主题；复杂系统使用多页文件
• 为便于阅读，每页控制在 40 个或更少的单元格

标签

• 在每一页顶部添加标题文本单元格（text;strokeColor=none;fillColor=none;fontSize=18;fontStyle=1）
• 始终在顶点形状上设置 whiteSpace=wrap;html=1
• 保持标签简洁 —— 每个形状尽量不超过 3 个词

样式一致性

• 在整个项目中一致使用第 3 节第 5 步中的语义色板
• 优先使用 edgeStyle=orthogonalEdgeStyle 以获得整洁的直角连接线
• 除非必要，不要在标签中内联任意 HTML

文件命名

• 使用 kebab-case：order-service-flow.drawio、database-schema.drawio
• 将图放在其所记录代码的旁边：docs/ 或 architecture/

---

8. 故障排除

问题	可能原因	修复
文件在 VS Code 中打开为空白	缺少 id=0 或 id=1 单元格	在添加任何其他单元格之前，先添加两个根单元格
形状位置错误	子元素位于容器内 —— 坐标是相对的	检查 parent；相对于容器调整 x/y
连线不可见	source 或 target id 与任何顶点都不匹配	验证两个 id 是否完全按书写形式存在
图显示为 "Compressed"	mxGraphModel 采用 base64 编码	在 draw.io web 中打开，File > Export > XML（未压缩）
形状样式未渲染	shape= 名称中有拼写错误	查看 references/shape-libraries.md 以获取准确的样式字符串
标签显示转义后的 HTML	带有 HTML 标签的单元格上 html=0	向单元格样式添加 html=1;
容器子元素与容器边缘重叠	容器高度太小	在 mxGeometry 中增加容器高度

---

9. 验证清单

在交付任何生成的 .drawio 文件之前，请验证：

• 文件以 <mxfile> 根元素开头
• 每个 <diagram> 都有非空的 id 属性
• <mxCell id="0" /> 是每个图中的第一个单元格
• <mxCell id="1" parent="0" /> 是每个图中的第二个单元格
• 每个图中的所有单元格 id 值都唯一
• 每个顶点单元格都有 vertex="1" 和子元素 <mxGeometry as="geometry">
• 每个边单元格都有 edge="1"，并且满足以下任一条件：(a) source/target 指向已存在的顶点 id，或 (b) 在其 <mxGeometry> 中包含 <mxPoint as="sourcePoint"> 和 <mxPoint as="targetPoint">（浮动边——用于序列图生命线）
• 每个单元格（id=0 除外）都有指向已存在 id 的 parent
• 任何包含 HTML 标签的标签，其样式中都有 html=1
• XML 格式良好（没有未闭合的标签，属性值中没有未转义的 &、<、>）
• 每个页面顶部都有一个标题标签单元格

运行自动验证器：

python .github/skills/draw-io-diagram-generator/scripts/validate-drawio.py <file.drawio>

---

10. 输出格式

交付图表时，始终提供：

1. 写入请求路径的 .drawio 文件
2. 一句话摘要，说明该图表展示了什么
3. 如何打开它：

   "在 VS Code 中打开 <filename> —— draw.io 扩展会自动渲染它。如果你愿意，也可以在 draw.io Web 应用或桌面应用中打开它。"

4. 如何编辑它（如果用户可能会自定义）：

   "点击任意形状即可选中它。双击即可编辑标签。拖动即可重新定位。"

5. 验证状态 —— 是否运行了验证器脚本并通过

---

11. 参考资料

所有配套文件都在 .github/skills/draw-io-diagram-generator/ 中：

文件	内容
references/drawio-xml-schema.md	完整的 mxfile / mxGraphModel / mxCell 属性参考、坐标系、保留单元格、验证规则
references/style-reference.md	所有样式键及其允许值、顶点和边样式键、形状目录、语义调色板
references/shape-libraries.md	所有形状库类别（General、Flowchart、UML、ER、Network、BPMN、Mockup、K8s）及其样式字符串
assets/templates/flowchart.drawio	可直接使用的流程图模板
assets/templates/architecture.drawio	4 层系统架构模板
assets/templates/sequence.drawio	3 个参与者的序列图模板
assets/templates/er-diagram.drawio	包含鸦脚式关系的 3 表 ER 图
assets/templates/uml-class.drawio	接口 + 2 个类 + 枚举及其关系箭头
scripts/validate-drawio.py	用于验证任意 .drawio 文件 XML 结构的 Python 脚本
scripts/add-shape.py	用于向现有图表添加新形状的 Python 命令行工具
scripts/README.md	如何通过示例使用这些脚本