draw-io-diagram-generator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Draw.io Diagram Generator

Draw.io图表生成器

This skill enables you to generate, edit, and validate draw.io (

.drawio

) diagram files with correct mxGraph XML structure. All generated files open immediately in the Draw.io VS Code extension (

hediet.vscode-drawio

) without any manual fixes required. You can also open the files in the draw.io web app or desktop app if you prefer.

本技能可用于生成、编辑和校验具有正确mxGraph XML结构的draw.io（

.drawio

）图表文件。所有生成的文件无需任何手动修复即可直接在Draw.io VS Code扩展（

hediet.vscode-drawio

）中打开。你也可以根据偏好选择在draw.io网页端或桌面端应用中打开文件。

1. When to Use This Skill

1. 何时使用本技能

Trigger phrases (load this skill when you see these)

"create a diagram", "draw a flowchart", "generate an architecture diagram"
"design a sequence diagram", "make a UML class diagram", "build an ER diagram"
"add a .drawio file", "update the diagram", "visualise the flow"
"document the architecture", "show the data model", "diagram the service interactions"
Any request to produce or modify a
```
.drawio
```
,
```
.drawio.svg
```
, or
```
.drawio.png
```
file

Supported diagram types

Diagram Type	Template Available	Description
Flowchart	`assets/templates/flowchart.drawio`	Process flows with decisions and branches
System Architecture	`assets/templates/architecture.drawio`	Multi-tier / layered service architecture
Sequence Diagram	`assets/templates/sequence.drawio`	Actor lifelines and timed message flows
ER Diagram	`assets/templates/er-diagram.drawio`	Database tables with relationships
UML Class Diagram	`assets/templates/uml-class.drawio`	Classes, interfaces, enums, relationships
Network Topology	(use shape library)	Routers, servers, firewalls, subnets
BPMN Workflow	(use shape library)	Business process events, tasks, gateways
Mind Map	(manual)	Central topic with radiating branches

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

"create a diagram", "draw a flowchart", "generate an architecture diagram"
"design a sequence diagram", "make a UML class diagram", "build an ER diagram"
"add a .drawio file", "update the diagram", "visualise the flow"
"document the architecture", "show the data model", "diagram the service interactions"
任何生成或修改
```
.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. Prerequisites

2. 前置要求

If running with VS Code integration enabled, Install the drawio extension: draw.io VS Code extension —
```
hediet.vscode-drawio
```
(extension id). Install with:
```
ext install hediet.vscode-drawio
```
Supported file extensions:
```
.drawio
```
,
```
.drawio.svg
```
,
```
.drawio.png
```
Python 3.8+ (optional) — for the validation and shape-insertion scripts in
```
scripts/
```

若启用了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. Step-by-Step Agent Workflow

3. Agent分步工作流

Follow these steps in order for every diagram generation task.

所有图表生成任务请按顺序遵循以下步骤：

Step 1 — Understand the Request

步骤1 — 理解需求

Ask or infer:

Diagram type — What kind of diagram? (flowchart, architecture, UML, ER, sequence, network...)
Entities / actors — What are the main components, actors, classes, or tables?
Relationships — How are they connected? What direction? What cardinality?
Output path — Where should the
```
.drawio
```
file be saved?
Existing file — Are we creating new or editing an existing file?

If the request is ambiguous, infer the most sensible diagram type from context (e.g. "show the tables" → ER diagram, "show how the API call flows" → sequence diagram).

询问或推断以下信息：

图表类型 — 需要什么类型的图表？（流程图、架构图、UML、ER、时序图、网络拓扑图等）
实体/角色 — 主要的组件、角色、类或表有哪些？
关联关系 — 它们之间如何连接？方向是什么？基数是多少？
输出路径 —
```
.drawio
```
文件需要保存到什么位置？
现有文件 — 是创建新文件还是编辑已有文件？

如果需求不明确，可根据上下文推断最合理的图表类型（例如："展示表结构"→ER图，"展示API调用流程"→时序图）。

Step 2 — Select a Template or Start Fresh

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

Use a template when the diagram type matches one in
```
assets/templates/
```
. Copy the template structure and replace placeholder values.
Start fresh for novel layouts. Begin with the minimal valid skeleton:

xml

<!-- Set modified="" to the current ISO 8601 timestamp when generating a new file -->
<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" />
        <!-- Your cells go here -->
      </root>
    </mxGraphModel>
  </diagram>
</mxfile>

Rule: ids
0
and
1
are ALWAYS required and must be the first two cells. Never reuse them.

当图表类型匹配
```
assets/templates/
```
中的模板时使用模板：复制模板结构并替换占位符内容即可。
对于新颖的布局可从零创建，从最小有效骨架开始：

xml

<!-- 生成新文件时请将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" />
        <!-- 你的cell内容写在此处 -->
      </root>
    </mxGraphModel>
  </diagram>
</mxfile>

规则：id为
0
和
1
的cell是必填项，必须作为前两个cell存在，不得重复使用。

Step 3 — Plan the Layout

步骤3 — 规划布局

Before generating XML, sketch the logical placement:

Organise into rows or tiers (use swimlanes for layers)
Horizontal spacing: 40–60px between same-row shapes
Vertical spacing: 80–120px between tier rows
Standard shape size:
```
120x60
```
px for process boxes,
```
160x80
```
px for swimlanes
Default canvas: A4 landscape =
```
1169 x 827
```
px

生成XML之前先规划逻辑排布：

按行或层级组织（分层可使用泳道）
水平间距：同一行形状之间保留40-60px间距
垂直间距：层级行之间保留80-120px间距
标准形状尺寸：流程框使用
```
120x60
```
px，泳道使用
```
160x80
```
px
默认画布：A4横向 =
```
1169 x 827
```
px

Step 4 — Generate the mxGraph XML

步骤4 — 生成mxGraph XML

Vertex cell (every shape):

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>

Edge cell (every connector):

xml

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

Critical rules:

Every cell id must be globally unique within the file
Every vertex must have an
```
mxGeometry
```
child with
```
x
```
,
```
y
```
,
```
width
```
,
```
height
```
,
```
as="geometry"
```
Every edge must have
```
source
```
and
```
target
```
matching existing vertex ids — exception: floating edges (e.g. sequence diagram lifelines) use
```
sourcePoint
```
/
```
targetPoint
```
inside
```
<mxGeometry>
```
instead; see §4 Sequence Diagram
Every cell's
```
parent
```
must reference an existing cell id
Use
```
html=1
```
in style when the label contains HTML (
```

```
,
```

```
,
```
 
```
)
Escape XML special characters in labels:
```
&
```
=>
```
&amp;
```
,
```
<
```
=>
```
&lt;
```
,
```
>
```
=>
```
&gt;
```

顶点cell（每个形状）：

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>

边cell（每个连接线）：

xml

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

关键规则：

每个cell的id在文件内必须全局唯一
每个顶点必须包含
```
mxGeometry
```
子元素，且带有
```
x
```
、
```
y
```
、
```
width
```
、
```
height
```
、
```
as="geometry"
```
属性
每个边必须包含与现有顶点id匹配的
```
source
```
和
```
target
```
属性 —— 例外：浮动边（例如时序图的生命线）在
```
<mxGeometry>
```
中使用
```
sourcePoint
```
/
```
targetPoint
```
替代，详见第4节时序图部分
每个cell的
```
parent
```
必须引用存在的cell id
当标签包含HTML（
```

```
、
```

```
、
```
 
```
）时，样式中需要添加
```
html=1
```
标签中的XML特殊字符需要转义：
```
&
```
→
```
&amp;
```
、
```
<
```
→
```
&lt;
```
、
```
>
```
→
```
&gt;
```

Step 5 — Apply Correct Styles

步骤5 — 应用正确样式

Use the standard semantic color palette for consistency:

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

Common style strings by diagram type:

undefined

使用标准语义化调色板保证一致性：

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

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

undefined

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

UML类框

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

ER表容器

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

Orthogonal connector

直角连接线

edgeStyle=orthogonalEdgeStyle;html=1;

ER relationship (crow's foot)

ER关联（乌鸦脚）

edgeStyle=entityRelationEdgeStyle;html=1;endArrow=ERmany;startArrow=ERone;


> See `references/style-reference.md` for the complete style key catalog and `references/shape-libraries.md` for all shape library names.

edgeStyle=entityRelationEdgeStyle;html=1;endArrow=ERmany;startArrow=ERone;


> 完整的样式键目录请查看`references/style-reference.md`，所有形状库名称请查看`references/shape-libraries.md`。

Step 6 — Save and Validate

步骤6 — 保存与校验

Write the file to the requested path with
```
.drawio
```
extension

Run the validator (optional but recommended):

bash

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

Tell the user how to open the file:
"Open
```
<filename>
```
in VS Code — it will render automatically with the draw.io extension. You can use draw.io's web app or desktop app as well if you prefer."
Provide a brief description of what is in the diagram so the user knows what to expect.

写入文件到指定路径，后缀为
```
.drawio
```

运行校验器（可选但推荐）：

bash

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

告知用户打开文件的方式：
"在VS Code中打开
```
<filename>
```
即可，draw.io扩展会自动渲染。你也可以根据偏好使用draw.io网页端或桌面端应用打开。"
提供简短说明介绍图表内容，方便用户快速了解。

4. Diagram-Type Recipes

4. 不同图表类型的实现示例

Flowchart

流程图

Key elements: Start (ellipse) => Process (rounded rectangle) => Decision (diamond) => End (ellipse)

xml

<!-- Start node -->
<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>

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

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

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

核心元素：开始（椭圆）→ 流程（圆角矩形）→ 判断（菱形）→ 结束（椭圆）

xml

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

<!-- 箭头：开始到流程节点p1 -->
<mxCell id="e1" value=""
        style="edgeStyle=orthogonalEdgeStyle;html=1;"
        edge="1" source="start" target="p1" parent="1">
  <mxGeometry relative="1" as="geometry" />
</mxCell>

Architecture Diagram (3-tier)

架构图（3层）

Use swimlane containers for each tier. All service boxes are children of their swimlane.

xml

<!-- Tier swimlane -->
<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>

<!-- Service inside tier (parent="tier1", coords are relative to tier) -->
<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>

Connectors between tiers use absolute coordinates with
parent="1"
.

每层使用泳道容器，所有服务框都是对应泳道的子元素。

xml

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

时序图

Key elements: Actors (top), Lifelines (dashed vertical lines), Activation boxes, Message arrows.

Lifelines:
```
edge="1"
```
with
```
endArrow=none
```
and
```
dashed=1
```
, no source/target — use
```
sourcePoint
```
/
```
targetPoint
```
in geometry
Synchronous message:
```
endArrow=block;endFill=1
```
Return message:
```
endArrow=open;endFill=0;dashed=1
```
Self-call: loop the edge via two Array points to the right and back

Minimal XML snippet:

xml

<!-- Actor (stick figure) -->
<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>

<!-- Service box -->
<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>

<!-- Lifeline — floating edge: uses sourcePoint/targetPoint, NOT source/target attributes -->
<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>

<!-- Activation box (thin rectangle on lifeline) -->
<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>

<!-- Synchronous message -->
<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>

<!-- Return message (dashed) -->
<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>

Note: Lifelines are floating edges that use
sourcePoint
/
targetPoint
in
<mxGeometry>
instead of
source
/
target
attributes. This is the standard draw.io pattern for sequence diagrams.

核心元素：角色（顶部）、生命线（垂直虚线）、激活框、消息箭头。

生命线：
```
edge="1
```
，带有
```
endArrow=none
```
和
```
dashed=1
```
，无source/target属性，在geometry中使用
```
sourcePoint
```
/
```
targetPoint
```
同步消息：
```
endArrow=block;endFill=1
```
返回消息：
```
endArrow=open;endFill=0;dashed=1
```
自调用：通过两个数组点向右再折回实现环形边

最小XML片段：

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

ER图

Use

shape=table

containers with

childLayout=tableLayout

. Rows are

shape=tableRow

cells with

portConstraint=eastwest

. Columns inside each row are

shape=partialRectangle

Relationship arrows use

edgeStyle=entityRelationEdgeStyle

One-to-One:
```
startArrow=ERone;endArrow=ERone
```
One-to-Many:
```
startArrow=ERone;endArrow=ERmany
```
Many-to-Many:
```
startArrow=ERmany;endArrow=ERmany
```
Mandatory:
```
ERmandOne
```
, Optional:
```
ERzeroToOne
```

使用

shape=table

容器，带有

childLayout=tableLayout

属性。行是

shape=tableRow

的cell，带有

portConstraint=eastwest

属性。每行内的列是

shape=partialRectangle

。

关联箭头使用

edgeStyle=entityRelationEdgeStyle

：

一对一：
```
startArrow=ERone;endArrow=ERone
```
一对多：
```
startArrow=ERone;endArrow=ERmany
```
多对多：
```
startArrow=ERmany;endArrow=ERmany
```
mandatory：
```
ERmandOne
```
，可选：
```
ERzeroToOne
```

UML Class Diagram

UML类图

Class boxes are swimlane containers. Attributes and methods are plain text cells. Dividers are zero-height swimlane children.

Arrow styles by relationship type:

Relationship	Style String
Inheritance (extends)	`edgeStyle=orthogonalEdgeStyle;html=1;endArrow=block;endFill=0;`
Realization (implements)	`edgeStyle=orthogonalEdgeStyle;dashed=1;html=1;endArrow=block;endFill=0;`
Composition	`edgeStyle=orthogonalEdgeStyle;html=1;startArrow=diamond;startFill=1;endArrow=none;`
Aggregation	`edgeStyle=orthogonalEdgeStyle;html=1;startArrow=diamond;startFill=0;endArrow=none;`
Dependency	`edgeStyle=orthogonalEdgeStyle;dashed=1;html=1;endArrow=open;endFill=0;`
Association	`edgeStyle=orthogonalEdgeStyle;html=1;endArrow=open;endFill=0;`

类框是泳道容器，属性和方法是纯文本cell，分隔线是高度为0的泳道子元素。

按关联类型区分的箭头样式：

关联类型	样式字符串
继承（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. Multi-Page Diagrams

5. 多页图表

Add multiple

<diagram>

elements for complex systems:

xml

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

Each page has its own independent cell id namespace. The same id value can appear in different pages without conflict.

复杂系统可添加多个

<diagram>

元素：

xml

<mxfile host="Electron" version="26.0.0">
  <diagram id="overview" name="Overview">
    <!-- 概览页的mxGraphModel -->
  </diagram>
  <diagram id="detail" name="Detail View">
    <!-- 详情页的mxGraphModel -->
  </diagram>
</mxfile>

每个页面有独立的cell id命名空间，相同id值可在不同页面出现，不会冲突。

6. Editing Existing Diagrams

6. 编辑现有图表

When modifying an existing

.drawio

file:

Read the file first to understand existing cell ids, positions, and parent hierarchy
Identify the target diagram page — by index or
```
name
```
attribute
Assign new unique ids that do not collide with existing ids
Respect the container hierarchy — children of a swimlane use coordinates relative to their parent
Verify edges — after repositioning nodes, confirm edge source/target ids remain valid

Use

scripts/add-shape.py

to safely add a single shape without editing raw XML:

bash

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

修改已有

.drawio

文件时：

先读取文件，了解现有cell id、位置和父级层级
确定目标图表页 —— 通过索引或
```
name
```
属性定位
分配新的唯一id，避免与现有id冲突
遵守容器层级 —— 泳道的子元素使用相对于父级的坐标
校验边 —— 重新定位节点后，确认边的source/target id仍然有效

可使用

scripts/add-shape.py

安全添加单个形状，无需编辑原始XML：

bash

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

7. Best Practices

7. 最佳实践

Layout

Align shapes to the 10px grid (all coordinates divisible by 10)
Group related shapes inside swimlane containers
One diagram topic per page; use multi-page files for complex systems
Aim for 40 or fewer cells per page for readability

Labels

Add a title text cell (

text;strokeColor=none;fillColor=none;fontSize=18;fontStyle=1

) at top of every page

Always set
```
whiteSpace=wrap;html=1
```
on vertex shapes
Keep labels concise — 3 words or fewer per shape where possible

Style consistency

Use the semantic color palette from Section 3 Step 5 consistently across a project
Prefer
```
edgeStyle=orthogonalEdgeStyle
```
for clean right-angle connectors
Do not inline arbitrary HTML in labels unless necessary

File naming

Use kebab-case:

order-service-flow.drawio

database-schema.drawio

Place diagrams alongside the code they document:
```
docs/
```
or
```
architecture/
```

布局

形状对齐到10px网格（所有坐标可被10整除）
相关形状放在泳道容器中分组
每页对应一个图表主题，复杂系统使用多页文件
每页cell数量控制在40个以内，保证可读性

标签

每页顶部添加标题文本cell（

text;strokeColor=none;fillColor=none;fontSize=18;fontStyle=1

）

顶点形状始终设置
```
whiteSpace=wrap;html=1
```
标签保持简洁，每个形状尽量控制在3个词以内

样式一致性

项目内统一使用第3节步骤5中的语义化调色板
优先使用
```
edgeStyle=orthogonalEdgeStyle
```
实现干净的直角连接线
除非必要，不要在标签中内联任意HTML

文件命名

使用短横线命名法：

order-service-flow.drawio

、

database-schema.drawio

图表放在对应文档的代码目录旁：
```
docs/
```
或
```
architecture/
```

8. Troubleshooting

8. 问题排查

Problem	Likely Cause	Fix
File opens blank in VS Code	Missing id=0 or id=1 cell	Add both root cells before any other cells
Shape at wrong position	Child inside container — coords are relative	Check `parent` ; adjust x/y relative to container
Edge not visible	source or target id does not match any vertex	Verify both ids exist exactly as written
Diagram shows "Compressed"	mxGraphModel is base64-encoded	Open in draw.io web, File > Export > XML (uncompressed)
Shape style not rendering	Typo in shape= name	Check `references/shape-libraries.md` for exact style string
Label shows escaped HTML	html=0 on a cell with HTML label	Add `html=1;` to the cell style
Container children overlap container edge	Container height too small	Increase container height in mxGeometry

问题	可能原因	解决方法
文件在VS Code中打开为空白	缺少id=0或id=1的cell	在所有其他cell之前添加这两个根cell
形状位置错误	容器中的子元素坐标是相对值	检查 `parent` 属性，相对于容器调整x/y坐标
边不可见	source或target id与现有顶点不匹配	确认两个id与现有值完全一致
图表显示"已压缩"	mxGraphModel是base64编码的	在draw.io网页端打开，文件>导出>XML（未压缩）
形状样式不渲染	shape=名称拼写错误	查看 `references/shape-libraries.md` 获取准确的样式字符串
标签显示转义后的HTML	带HTML标签的cell的html=0	在cell样式中添加 `html=1;`
容器子元素超出容器边缘	容器高度太小	增大mxGeometry中的容器高度

9. Validation Checklist

9. 校验清单

Before delivering any generated

.drawio

file, verify:

File starts with
```
<mxfile>
```
root element
Every
```
<diagram>
```
has a non-empty
```
id
```
attribute
```
<mxCell id="0" />
```
is the first cell in every diagram
```
<mxCell id="1" parent="0" />
```
is the second cell in every diagram
All cell
```
id
```
values are unique within each diagram
Every vertex cell has
```
vertex="1"
```
and a child
```
<mxGeometry as="geometry">
```
Every edge cell has
```
edge="1"
```
and either: (a)
```
source
```
/
```
target
```
pointing to existing vertex ids, or (b)
```
<mxPoint as="sourcePoint">
```
and
```
<mxPoint as="targetPoint">
```
in its
```
<mxGeometry>
```
(floating edge — used for sequence diagram lifelines)
Every cell (except id=0) has a
```
parent
```
pointing to an existing id
```
html=1
```
is in the style for any label containing HTML tags
XML is well-formed (no unclosed tags, no unescaped
```
&
```
,
```
<
```
,
```
>
```
in attribute values)
A title label cell exists at the top of each page

Run the automated validator:

bash

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

交付任何生成的

.drawio

文件之前，请校验：

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

运行自动校验器：

bash

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

10. Output Format

10. 输出格式

When delivering a diagram, always provide:

The
.drawio
file written to the requested path
A one-sentence summary of what the diagram shows
How to open it:
"Open
```
<filename>
```
in VS Code — the draw.io extension will render it automatically. Or you can open it in the draw.io web app or desktop app if you prefer."
How to edit it (if the user is likely to customise):

"Click any shape to select it. Double-click to edit the label. Drag to reposition."
Validation status — whether the validator script was run and passed

交付图表时，请始终提供以下内容：

写入到指定路径的
```
.drawio
```
文件
图表内容的一句话摘要
打开方式：
"在VS Code中打开
```
<filename>
```
即可，draw.io扩展会自动渲染。你也可以根据偏好使用draw.io网页端或桌面端应用打开。"
编辑方式（如果用户可能需要自定义）：

"点击任意形状即可选中，双击可编辑标签，拖拽可调整位置。"
校验状态 —— 是否运行了校验脚本且通过

11. References

11. 参考资料

All companion files are in

.github/skills/draw-io-diagram-generator/

File	Contents
`references/drawio-xml-schema.md`	Complete mxfile / mxGraphModel / mxCell attribute reference, coordinate system, reserved cells, validation rules
`references/style-reference.md`	All style keys with allowed values, vertex and edge style keys, shape catalog, semantic color palette
`references/shape-libraries.md`	All shape library categories (General, Flowchart, UML, ER, Network, BPMN, Mockup, K8s) with style strings
`assets/templates/flowchart.drawio`	Ready-to-use flowchart template
`assets/templates/architecture.drawio`	4-tier system architecture template
`assets/templates/sequence.drawio`	3-actor sequence diagram template
`assets/templates/er-diagram.drawio`	3-table ER diagram with crow's foot relationships
`assets/templates/uml-class.drawio`	Interface + 2 classes + enum with relationship arrows
`scripts/validate-drawio.py`	Python script to validate XML structure of any .drawio file
`scripts/add-shape.py`	Python CLI to add a new shape to an existing diagram
`scripts/README.md`	How to use the scripts with examples

所有配套文件都在

.github/skills/draw-io-diagram-generator/

目录下：

文件	内容
`references/drawio-xml-schema.md`	完整的mxfile/mxGraphModel/mxCell属性参考、坐标系、保留cell、校验规则
`references/style-reference.md`	所有样式键的允许值、顶点和边样式键、形状目录、语义化调色板
`references/shape-libraries.md`	所有形状库分类（通用、流程图、UML、ER、网络、BPMN、原型、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 CLI工具
`scripts/README.md`	脚本使用说明及示例
",