awesome-copilot 中基于 mxGraph XML 的 draw.io 图表编写与校验规范

在 GitHub Copilot 生态中，图表往往与代码一样需要被「可生成、可校验、可版本管理」。本文基于本仓库 draw-io.instructions.md 确立的 draw.io 图表编写标准，结合配套 Skill 的实现（SKILL.md）与两个实用脚本（validate-drawio.py、add-shape.py），系统讲解如何以规范一致的 .drawio 文件承载流程图、架构图、时序图、ER 图与 UML 类图。读完本文，你将掌握一套可直接落地的 mxGraph XML 编写规则、语义化配色约定，以及提交前自动校验的完整工作流。

一、为什么需要一套 draw.io 编写规范

.drawio 文件本质上是 mxGraph 导出的 XML，它能被 draw.io 桌面端、Web 端以及 VS Code 的 hediet.vscode-drawio 扩展直接渲染。正因它是纯文本，团队才能把它纳入版本控制（Git diff 可读）、交给 Agent 自动生成，并用脚本做结构校验。

本仓库对 .drawio、.drawio.svg、.drawio.png 三类文件统一生效（见 draw-io.instructions.md 的 front matter 声明）。规范的核心目标有三：

1. 机器可生成：遵循固定骨架与规则，Agent 可以直接写出合法 XML；
2. 机器可校验：结构错误（缺根节点、悬空边、重复 id）能被脚本自动检出；
3. 人工可读：语义化配色、网格对齐、命名约定让所有图表在项目内风格统一。

从 SKILL.md 的触发词可以看出，凡是出现「create a diagram」「generate an architecture diagram」「visualise the flow」等请求，都应套用这套规范来产出 .drawio 文件。

二、必选工作流：从请求到可打开的图表文件

每次绘制图表都应遵循以下六步（对应 draw-io.instructions.md 的 Required Workflow）：

1. 识别图表类型：flowchart（流程图）/ architecture（架构图）/ sequence（时序图）/ ER（实体关系图）/ UML / network（网络拓扑）/ BPMN；
2. 选择模板：从仓库的 模板目录 中选取对应 .drawio 模板并改造，或从最小骨架起步；
3. 纸面规划布局：先确定层级（tier）、参与者（actor）或实体（entity），再写 XML；
4. 生成合法 mxGraph XML：遵循下文第三节的结构规则；
5. 自动校验：运行 python skills/draw-io-diagram-generator/scripts/validate-drawio.py <file>；
6. 确认渲染：在 VS Code 中安装 draw.io 扩展（ext install hediet.vscode-drawio）打开文件，确认渲染无异常。

仓库为每种主流图表都提供了现成模板：flowchart.drawio、architecture.drawio、sequence.drawio、er-diagram.drawio、uml-class.drawio。

三、mxGraph XML 结构规则（硬性要求）

一个合法的 .drawio 文件，顶层结构必须如下（原文骨架）：

<!-- 生成新文件时，将 modified 设为当前 ISO 8601 时间戳 -->
<mxfile host="Electron" modified="" version="26.0.0">
  <diagram id="unique-id" name="Page Name">
    <mxGraphModel ...>
      <root>
        <mxCell id="0" />                          <!-- 必需：必须第一个 -->
        <mxCell id="1" parent="0" />               <!-- 必需：必须第二个 -->
        <!-- 其余所有 cell 放在这里 -->
      </root>
    </mxGraphModel>
  </diagram>
</mxfile>

SKILL.md 给出了更完整的 mxGraphModel 骨架，其中网格、页面尺寸等关键属性值得逐一了解：

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

3.1 核心结构规则（不可协商）

• id="0" 与 id="1" 必须存在，且必须是 root 中的前两个 cell，没有例外；
• 每个 cell 的 id 在单个 diagram 内必须唯一；
• 每个顶点（vertex="1"）必须有子元素 <mxGeometry x y width height as="geometry">；
• 每条边（edge="1"）必须通过 source/target 指向已存在的顶点 id —— 唯一例外：浮动边（如时序图的生命线）不写 source/target，而是在 <mxGeometry> 内部使用 <mxPoint as="sourcePoint"> 与 <mxPoint as="targetPoint">；
• 除 id="0" 外，每个 cell 的 parent 必须指向一个已存在的 id；
• 容器（泳道）内部子元素使用相对父容器的坐标，而非画布绝对坐标。

3.2 顶点（Vertex）与边（Edge）的写法

顶点示例（来自 SKILL.md 第四节）：

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

补充要点：标签中含有 HTML（<b>、<i>、<br>）时，style 必须带 html=1；XML 特殊字符必须转义：& → &、< → <、> → >。完整的 mxfile / mxGraphModel / mxCell 属性参考见 drawio-xml-schema.md。

3.3 保留 cell 与分层机制

id="0" 是根 cell（永不省略、不加属性），id="1" 是默认图层，所有内容 cell 默认都是它的子元素。id="0" 与 id="1" 是保留 id，不得被其他 cell 复用。需要分层时，可把 id="1" 替换为多个 layer cell，并通过 parent 归属图层，还可用 visible="0" 控制图层可见性（详见 drawio-xml-schema.md 的 Layer Cells 一节）。

四、强制样式约定

4.1 语义化配色（项目内保持一致）

角色	fillColor	strokeColor
主色 / 信息（默认）	#dae8fc	#6c8ebf
成功 / 开始 / 正向	#d5e8d4	#82b366
警告 / 判断	#fff2cc	#d6b656
错误 / 结束 / 危险	#f8cecc	#b85450
中性 / 接口	#f5f5f5	#666666
外部 / 合作伙伴	#e1d5e7	#9673a6

这一调色板在 SKILL.md 中被称为 semantic color palette，并建议「跨项目一致使用」。暗色主题图表可替换为深色填充与浅色描边（如填充 #1e4d78、描边 #4aa3df、文字 #ffffff），参考 style-reference.md。

4.2 顶点必须带的样式

whiteSpace=wrap;html=1;

4.3 HTML 标签标签

只要标签包含 HTML 标签（<b>、<i>、<br>），style 必须加 html=1。

4.4 标准连接线

edgeStyle=orthogonalEdgeStyle;html=1;

五、各图表类型速查表

类型	容器	关键形状	连接线样式
流程图	无	ellipse（开始/结束）、rounded=1（处理）、rhombus（判断）	orthogonalEdgeStyle
架构图	每层一个 swimlane	rounded=1 服务、cloud/DB 形状	带标签的 orthogonalEdgeStyle
时序图	无	mxgraph.uml.actor、虚线生命线	endArrow=block（同步）、endArrow=open;dashed=1（返回）
ER 图	shape=table;childLayout=tableLayout	shape=tableRow、shape=partialRectangle	entityRelationEdgeStyle;endArrow=ERmany;startArrow=ERone
UML 类图	每个类一个 swimlane	属性/方法的文本行	endArrow=block;endFill=0（继承）、dashed=1（实现）

5.1 流程图配方

流程图的骨架元素为：开始（椭圆）→ 处理（圆角矩形）→ 判断（菱形）→ 结束（椭圆）。关键样式串：

# 圆角处理框
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;

5.2 架构图配方（泳道分层）

用 swimlane 容器表示每一层，层内服务 box 均为该泳道的子元素：

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

5.3 时序图配方

时序图的关键要素：Actor（顶部）、生命线（虚线竖线）、激活框、消息箭头。其中生命线是浮动边——用 sourcePoint/targetPoint 而非 source/target：

<!-- Actor（火柴人） -->
<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>

<!-- 生命线：浮动边，使用 sourcePoint/targetPoint -->
<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="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>

5.4 ER 图配方

表容器使用 shape=table + childLayout=tableLayout，行为 shape=tableRow 并带 portConstraint=eastwest，行内列用 shape=partialRectangle。关系连线使用 entityRelationEdgeStyle：

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

5.5 UML 类图配方

类框即 swimlane 容器，属性与方法为普通文本 cell，分隔线为零高度泳道子元素。关系箭头样式：

关系	样式串
继承（extends）	edgeStyle=orthogonalEdgeStyle;html=1;endArrow=block;endFill=0;
实现（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;

六、布局最佳实践

• 所有坐标对齐到 10 px 网格（坐标值可被 10 整除）；
• 水平方向：同一行形状之间留 40–60 px 间距；
• 垂直方向：层级行之间留 80–120 px 间距；
• 标准形状尺寸：处理框 120 × 60 px，判断菱形 200 × 100 px；
• 默认画布：A4 横向 1169 × 827 px；
• 每页最多 40 个 cell，更大的图拆分为多页；
• 每页顶部必须有标题文本 cell：

style="text;strokeColor=none;fillColor=none;fontSize=18;fontStyle=1;align=center;"

此外，drawio-xml-schema.md 还给出建议间距：形状最小间距 40px、舒适间距 80px、泳道内边距 20px、页面边距 40px、连线绕行留白 10px。

七、文件与命名约定

• 扩展名：版本管理的图表用 .drawio；嵌入 Markdown 的用 .drawio.svg；
• 命名：kebab-case，例如 order-flow.drawio、database-schema.drawio；
• 存放位置：与所描述的代码同处一地的 docs/ 或 architecture/ 目录；
• 多页：在同一 <mxfile> 中用多个 <diagram> 元素表示不同逻辑视图。每个 <diagram> 拥有独立的 cell id 命名空间，不同页之间允许出现相同 id（见 SKILL.md 第五节与 drawio-xml-schema.md）。

八、提交前校验清单与自动化脚本

8.1 校验清单（每次提交前逐项核对）

• [ ] <mxCell id="0" /> 与 <mxCell id="1" parent="0" /> 是前两个 cell
• [ ] 所有 cell id 在其 diagram 内唯一
• [ ] 所有边的 source/target 指向已存在的顶点
• [ ] 所有顶点 cell 都有 <mxGeometry as="geometry">
• [ ] 除 id="0" 外，所有 cell 都有合法的 parent
• [ ] XML 格式良好——没有未闭合标签、属性值中没有未转义的 &、<、>
• [ ] 语义化配色使用一致
• [ ] 每页都有标题 cell

8.2 运行自动校验

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

该脚本基于 Python 标准库（xml.etree.ElementTree），无需第三方依赖，要求 Python 3.8+。从源码 validate-drawio.py 可以看出，它实际执行的检查比清单更深：

• XML 良构性：解析失败直接返回 XML parse error；
• 根元素：必须为 <mxfile>，且 <mxfile> 内至少有一个 <diagram>；
• 根 cell：逐页检查 id="0"、id="1" 是否存在，且 id="0" 必须是第一个 cell、id="1" 必须是第二个 cell，id="1" 的 parent 必须为 "0"（源码 L83–L103）；
• 标题 cell：脚本要求每页存在 style 以 text; 开头（或含 ;text;）且包含 fontSize=18 的顶点 cell（源码 L104–L122）——这与清单中的「标题 cell」要求一一对应；
• 顶点结构：vertex="1" 的 cell 必须有 <mxGeometry> 子元素；
• 边连接：edge="1" 的 cell 必须有 source/target 且指向已存在 id，除非 <mxGeometry> 内含 sourcePoint/targetPoint（即浮动边例外，源码 L150–L184 通过 mxPoint 的 as 属性识别）；
• 父链：除 id="0" 外所有 cell 的 parent 必须引用已存在的 id。

退出码约定：0 表示全部通过，1 表示发现错误（错误信息打印到 stdout）。脚本还支持一次校验整个目录：

for f in docs/**/*.drawio; do python skills/draw-io-diagram-generator/scripts/validate-drawio.py "$f"; done

8.3 用 add-shape.py 安全地增补形状

当只想给既有图表加一个形状、又不想手改 XML 时，可用配套的 add-shape.py：

python skills/draw-io-diagram-generator/scripts/add-shape.py <diagram.drawio> <label> <x> <y> [options]

主要参数与选项（详见 scripts/README.md）：

参数/选项	默认值	说明
diagram、label、x、y	必填	文件路径、标签文本、坐标（px）
--width / --height	120 / 60	形状尺寸
--style	"rounded=1;whiteSpace=wrap;html=1;"	draw.io 样式串
--diagram-index	0	目标页面索引（0 起）
--dry-run	false	只打印新 cell 的 XML，不写文件

示例：

# 添加一个自定义样式的菱形判断节点
python skills/draw-io-diagram-generator/scripts/add-shape.py docs/flowchart.drawio "Decision" 400 400 \
  --width 160 --height 80 \
  --style "rhombus;whiteSpace=wrap;html=1;fillColor=#fff2cc;strokeColor=#d6b656;"

# 先预览再落地
python skills/draw-io-diagram-generator/scripts/add-shape.py docs/architecture.drawio "Service X" 600 200 --dry-run

从源码看，脚本通过 _generate_id()（label + 坐标 + 纳秒时间戳的 SHA1 前 8 位）生成 auto_ 前缀的全局唯一 id，并自动回退到非 "0" 的第一个 cell 作为 parent，从而在插入新形状时天然规避重复 id 与悬空 parent 问题。注意：脚本同样不支持被 base64 压缩的 mxGraphModel（会提示 Compressed diagrams are not supported）。

九、常见问题排查

以下对照表来自 SKILL.md 的 Troubleshooting 一节，覆盖了绝大多数手写 XML 时遇到的渲染异常：

问题	可能原因	修复
VS Code 中打开是空白	缺少 id="0" 或 id="1" cell	在其它 cell 之前补上两个根 cell
形状位置不对	子元素在容器内，坐标为相对坐标	检查 parent；按容器原点调整 x/y
边不可见	source 或 target 与任何顶点不匹配	核实两个 id 与顶点 id 完全一致
显示 "Compressed"	mxGraphModel 被 base64 编码	用 draw.io Web 打开，File > Export > XML（未压缩）
形状样式未渲染	shape= 名称拼写错误	对照 shape-libraries.md 精确样式串
标签显示转义后的 HTML	带 HTML 标签的 cell 未启用 html=1	在 style 中加入 html=1;
容器子元素越出容器边界	容器高度不足	在 mxGeometry 中增大容器高度

十、可继续深入的文件

本套规范在仓库中有完整的配套资源，按需查阅：

文件	用途
skills/draw-io-diagram-generator/SKILL.md	完整 Agent 工作流、各类型配方、排查指南
skills/draw-io-diagram-generator/references/drawio-xml-schema.md	mxfile / mxGraphModel / mxCell 完整属性参考、坐标系、保留 cell、校验规则
skills/draw-io-diagram-generator/references/style-reference.md	全部样式键、形状目录、箭头类型、语义调色板
skills/draw-io-diagram-generator/references/shape-libraries.md	形状库目录（General/Flowchart/UML/ER/Network/BPMN/Mockup/K8s）及样式串
skills/draw-io-diagram-generator/assets/templates/	按图表类型提供的现成 .drawio 模板
skills/draw-io-diagram-generator/scripts/validate-drawio.py	XML 结构校验器
skills/draw-io-diagram-generator/scripts/add-shape.py	CLI：向既有图表添加形状
skills/draw-io-diagram-generator/scripts/README.md	脚本用法与示例
skills/drawio/SKILL.md	若需把 .drawio 导出为可嵌入文档的 PNG（含 CLI/浏览器双渲染后端）

结语

把「图」当作「代码」来对待，是这套 draw.io 规范的核心思想：固定骨架保证结构合法，语义化配色保证视觉一致，validate-drawio.py 把规则落成可重复执行的检查，add-shape.py 则让增量编辑不必手写 XML。按本规范产出的每个 .drawio 文件，都能直接拖入 VS Code 的 draw.io 扩展渲染，也能被后续的 Agent 继续安全地增删改。从流程图到 ER 图、从单页到多页，这套标准都给出了一致的答案。