draw-io-diagram-generator

Draw.io Diagram Generator

本 Skill 赋予你生成、编辑和校验具有正确 mxGraph XML 结构的 draw.io (.drawio) 图表文件的能力。所有生成的文件均可在 Draw.io VS Code 插件 (hediet.vscode-drawio) 中直接打开渲染，无需任何手动修正。你也可以根据偏好在 draw.io 网页版或桌面端应用中打开它们。

1. 何时使用本 Skill

触发词（当看到以下需求时加载本 Skill）

"create a diagram"、"draw a flowchart"、"generate an architecture diagram"（"画个图"、"画流程图"、"生成架构图"）
"design a sequence diagram"、"make a UML class diagram"、"build an ER diagram"（"设计时序图"、"做个 UML 类图"、"建个 ER 图"）
"add a .drawio file"、"update the diagram"、"visualise the flow"（"添加 .drawio 文件"、"更新图表"、"流程可视化"）
"document the architecture"、"show the data model"、"diagram the service interactions"（"梳理架构文档"、"展示数据模型"、"画出服务交互图"）
任何创建或修改 .drawio、.drawio.svg 或 .drawio.png 文件的请求

支持的图表类型

图表类型	可用模板	描述
流程图 (Flowchart)	`assets/templates/flowchart.drawio`	包含决策判断与分支的业务流程
系统架构图 (System Architecture)	`assets/templates/architecture.drawio`	多层 / 分层服务架构
时序图 (Sequence Diagram)	`assets/templates/sequence.drawio`	角色生命线与时序消息流
ER 图 (ER Diagram)	`assets/templates/er-diagram.drawio`	带有关联关系的数据库表
UML 类图 (UML Class Diagram)	`assets/templates/uml-class.drawio`	类、接口、枚举及其相互关系
网络拓扑图 (Network Topology)	（使用图形库）	路由器、服务器、防火墙、子网
BPMN 工作流 (BPMN Workflow)	（使用图形库）	业务流程事件、任务、网关
思维导图 (Mind Map)	（手动编写）	核心主题及向外放射的分支

2. 前置条件

若启用了 VS Code 集成环境，需安装 drawio 插件：draw.io VS Code extension — hediet.vscode-drawio（插件 ID）。可通过以下命令安装：
```
ext install hediet.vscode-drawio
```
支持的文件扩展名：.drawio、.drawio.svg、.drawio.png
Python 3.8+（可选）— 用于运行 scripts/ 目录下的校验与图形插入脚本

3. Agent 逐步工作流

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

步骤 1 — 理解需求

向用户确认或根据上下文推断：

图表类型 — 属于哪种图表？（流程图、架构图、UML、ER 图、时序图、网络拓扑图...）
实体 / 角色 — 核心组件、角色、类或数据库表有哪些？
关系 — 它们之间如何连接？连接方向是什么？基数关系（cardinality）如何？
输出路径 — .drawio 文件应该保存到哪里？
现有文件 — 是新建文件还是编辑已有文件？

如果需求较为模糊，请根据上下文推断最合理的图表类型（例如："展示数据库表" → ER 图，"展示 API 调用流程" → 时序图）。

步骤 2 — 选择模板或从头创建

使用模板：当图表类型匹配 assets/templates/ 中的现有模板时，直接复制模板结构并替换其中的占位符内容。
从头创建：对于全新的自定义布局，使用以下最小有效骨架起步：

<!-- 生成新文件时，将 modified="" 设为当前的 ISO 8601 时间戳 -->
<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 的单元格为必需项，且必须作为前两个单元格出现，切勿重复使用这两个 id。

步骤 3 — 规划布局

在生成 XML 之前，先构思好逻辑排布：

按行或层级划分区域（使用泳道 swimlanes 来标识架构层）
水平间距：同行图形节点之间保持 40–60px
垂直间距：不同层级行之间保持 80–120px
标准图形尺寸：流程节点框常用 120x60 px，泳道容器常用 160x80 px
默认画布规格：A4 横向 = 1169 x 827 px

步骤 4 — 生成 mxGraph XML

节点单元格 (Vertex cell)（所有图形节点）：

<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>

边/连线单元格 (Edge cell)（所有连接线）：

<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 在整个文件内部必须全局唯一
每个节点 (vertex) 必须包含一个 mxGeometry 子元素，并带有 x、y、width、height 以及 as="geometry" 属性
每条边 (edge) 的 source 和 target 属性必须对应已存在的节点 id —— 例外情况：悬空边/自由线（例如时序图中的生命线）需在 <mxGeometry> 内部使用 sourcePoint/targetPoint 代替；详见 §4 时序图
每个单元格的 parent 属性必须引用已存在的单元格 id
当文本标签中包含 HTML 标签（如 <b>、<i>、<br>）时，需要在 style 中显式设置 html=1
文本标签中的 XML 特殊字符必须进行转义：& => &，< => <，> => >

步骤 5 — 应用正确的样式规范

为了保持视觉一致性，请统一使用标准语义化配色方案：

适用场景	fillColor (填充色)	strokeColor (边框色)
主色 / 信息节点 (Primary / Info)	`#dae8fc`	`#6c8ebf`
成功 / 起始节点 (Success / Start)	`#d5e8d4`	`#82b366`
警告 / 条件判断 (Warning / Decision)	`#fff2cc`	`#d6b656`
错误 / 结束节点 (Error / End)	`#f8cecc`	`#b85450`
中性节点 (Neutral)	`#f5f5f5`	`#666666`
外部系统 / 合作伙伴 (External / Partner)	`#e1d5e7`	`#9673a6`

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

# 圆角流程节点（流程图）
rounded=1;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;

# 判定菱形
rhombus;whiteSpace=wrap;html=1;fillColor=#fff2cc;strokeColor=#d6b656;

# 起始/结束端点
ellipse;whiteSpace=wrap;html=1;fillColor=#d5e8d4;strokeColor=#82b366;

# 数据库圆柱体
shape=mxgraph.flowchart.database;whiteSpace=wrap;html=1;fillColor=#f8cecc;strokeColor=#b85450;

# 泳道容器（分层）
swimlane;startSize=30;fillColor=#dae8fc;strokeColor=#6c8ebf;fontStyle=1;

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

# 接口 / 原型框 (Interface / Stereotype)
swimlane;fontStyle=3;align=center;startSize=40;fillColor=#f5f5f5;strokeColor=#666666;

# ER 实体表容器
shape=table;startSize=30;container=1;collapsible=1;childLayout=tableLayout;

# 正交连接线
edgeStyle=orthogonalEdgeStyle;html=1;

# ER 实体关系线（乌鸦脚 notation）
edgeStyle=entityRelationEdgeStyle;html=1;endArrow=ERmany;startArrow=ERone;

完整的样式属性目录请参阅 references/style-reference.md，所有图形库名称请参阅 references/shape-libraries.md。

步骤 6 — 保存与校验

将文件保存至指定路径，并确保使用 .drawio 扩展名

运行校验脚本（可选，推荐执行）：

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

告知用户如何打开该文件：

"已在 VS Code 中生成 <filename> —— 安装 draw.io 插件后即可自动渲染预览。你也可以根据需要使用 draw.io 网页版或桌面端打开。"
提供简要说明，概述图表包含的核心内容，以便用户了解预期效果。

4. 各类型图表制作指南

流程图 (Flowchart)

核心元素：起点（椭圆） => 过程（圆角矩形） => 决策（菱形） => 终点（椭圆）

<!-- 起始节点 -->
<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>

<!-- 箭头：start 指向 p1 -->
<mxCell id="e1" value=""
        style="edgeStyle=orthogonalEdgeStyle;html=1;"
        edge="1" source="start" target="p1" parent="1">
  <mxGeometry relative="1" as="geometry" />
</mxCell>

系统架构图 (3-tier)

每个分层均使用泳道容器 (swimlane containers)。层内的所有服务节点均为对应泳道的子元素。

<!-- 分层泳道 -->
<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>

<!-- 泳道内部的服务（parent="tier1"，坐标相对于泳道） -->
<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"。

时序图 (Sequence Diagram)

核心元素：角色/参与者（顶部）、生命线（虚线垂直线）、激活条（控制焦点）、消息箭头。

生命线 (Lifelines)：edge="1" 并设置 endArrow=none 和 dashed=1，无需 source/target —— 需在 geometry 中使用 sourcePoint/targetPoint
同步消息 (Synchronous message)：endArrow=block;endFill=1
返回消息 (Return message)：endArrow=open;endFill=0;dashed=1
自调用 (Self-call)：通过右侧两个 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>

<!-- 生命线 — 自由连线：使用 sourcePoint/targetPoint，而非 source/target 属性 -->
<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;

你可能还喜欢

ads-attribution

7.8Kmcp-integrations

全面审查跨平台归因、转化定义、统计窗口、GA4、AdServices 及 AdAttributionKit、MMP、浏览器与服务端事件、离线转化和多平台数据对账。适用于归因审计、归因模型评估、转化窗口分析、处理合并 Meta 与 Google 转化数据的需求、解决不兼容统计窗口的数据汇总、GA4 归因、MMP 评估（如 AppsFlyer、Adjust、Branch、Singular）以及排查跨平台数据不一致等场景。