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

awesome-copilot 中基于 mxGraph XML 的 draw.io 图表编写与校验规范【免费下载链接】awesome-copilotCommunity-contributed instructions, agents, skills, and configurations to help you make the most of GitHub Copilot.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-copilot在 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 声明。规范的核心目标有三机器可生成遵循固定骨架与规则Agent 可以直接写出合法 XML机器可校验结构错误缺根节点、悬空边、重复 id能被脚本自动检出人工可读语义化配色、网格对齐、命名约定让所有图表在项目内风格统一。从 SKILL.md 的触发词可以看出凡是出现「create a diagram」「generate an architecture diagram」「visualise the flow」等请求都应套用这套规范来产出.drawio文件。二、必选工作流从请求到可打开的图表文件每次绘制图表都应遵循以下六步对应 draw-io.instructions.md 的 Required Workflow识别图表类型flowchart流程图/ architecture架构图/ sequence时序图/ ER实体关系图/ UML / network网络拓扑/ BPMN选择模板从仓库的 模板目录 中选取对应.drawio模板并改造或从最小骨架起步纸面规划布局先确定层级tier、参与者actor或实体entity再写 XML生成合法 mxGraph XML遵循下文第三节的结构规则自动校验运行python skills/draw-io-diagram-generator/scripts/validate-drawio.py file确认渲染在 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 hostElectron modified version26.0.0 diagram idunique-id namePage Name mxGraphModel ... root mxCell id0 / !-- 必需必须第一个 -- mxCell id1 parent0 / !-- 必需必须第二个 -- !-- 其余所有 cell 放在这里 -- /root /mxGraphModel /diagram /mxfileSKILL.md 给出了更完整的mxGraphModel骨架其中网格、页面尺寸等关键属性值得逐一了解mxGraphModel dx1422 dy762 grid1 gridSize10 guides1 tooltips1 connect1 arrows1 fold1 page1 pageScale1 pageWidth1169 pageHeight827 math0 shadow03.1 核心结构规则不可协商id0与id1必须存在且必须是root中的前两个 cell没有例外每个 cell 的id在单个 diagram 内必须唯一每个顶点vertex1必须有子元素mxGeometry x y width height asgeometry每条边edge1必须通过source/target指向已存在的顶点 id ——唯一例外浮动边如时序图的生命线不写source/target而是在mxGeometry内部使用mxPoint assourcePoint与mxPoint astargetPoint除id0外每个 cell 的parent必须指向一个已存在的 id容器泳道内部子元素使用相对父容器的坐标而非画布绝对坐标。3.2 顶点Vertex与边Edge的写法顶点示例来自 SKILL.md 第四节mxCell idunique-id valueLabel stylerounded1;whiteSpacewrap;html1;fillColor#dae8fc;strokeColor#6c8ebf; vertex1 parent1 mxGeometry x100 y100 width120 height60 asgeometry / /mxCell边示例mxCell idedge-id valueLabel (optional) styleedgeStyleorthogonalEdgeStyle;html1; edge1 sourcesource-id targettarget-id parent1 mxGeometry relative1 asgeometry / /mxCell补充要点标签中含有 HTMLb、i、br时style 必须带html1XML 特殊字符必须转义→amp;、→lt;、→gt;。完整的mxfile/mxGraphModel/mxCell属性参考见 drawio-xml-schema.md。3.3 保留 cell 与分层机制id0是根 cell永不省略、不加属性id1是默认图层所有内容 cell 默认都是它的子元素。id0与id1是保留 id不得被其他 cell 复用。需要分层时可把id1替换为多个 layer cell并通过parent归属图层还可用visible0控制图层可见性详见 drawio-xml-schema.md 的 Layer Cells 一节。四、强制样式约定4.1 语义化配色项目内保持一致角色fillColorstrokeColor主色 / 信息默认#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 顶点必须带的样式whiteSpacewrap;html1;4.3 HTML 标签标签只要标签包含 HTML 标签b、i、brstyle 必须加html1。4.4 标准连接线edgeStyleorthogonalEdgeStyle;html1;五、各图表类型速查表类型容器关键形状连接线样式流程图无ellipse开始/结束、rounded1处理、rhombus判断orthogonalEdgeStyle架构图每层一个swimlanerounded1服务、cloud/DB 形状带标签的orthogonalEdgeStyle时序图无mxgraph.uml.actor、虚线生命线endArrowblock同步、endArrowopen;dashed1返回ER 图shapetable;childLayouttableLayoutshapetableRow、shapepartialRectangleentityRelationEdgeStyle;endArrowERmany;startArrowERoneUML 类图每个类一个swimlane属性/方法的文本行endArrowblock;endFill0继承、dashed1实现5.1 流程图配方流程图的骨架元素为开始椭圆→ 处理圆角矩形→ 判断菱形→ 结束椭圆。关键样式串# 圆角处理框 rounded1;whiteSpacewrap;html1;fillColor#dae8fc;strokeColor#6c8ebf; # 判断菱形 rhombus;whiteSpacewrap;html1;fillColor#fff2cc;strokeColor#d6b656; # 开始/结束端子 ellipse;whiteSpacewrap;html1;fillColor#d5e8d4;strokeColor#82b366; # 数据库圆柱 shapemxgraph.flowchart.database;whiteSpacewrap;html1;fillColor#f8cecc;strokeColor#b85450;5.2 架构图配方泳道分层用swimlane容器表示每一层层内服务 box 均为该泳道的子元素!-- 层级泳道 -- mxCell idtier1 valueClient Layer styleswimlane;startSize30;fillColor#dae8fc;strokeColor#6c8ebf;fontStyle1; vertex1 parent1 mxGeometry x60 y100 width1050 height130 asgeometry / /mxCell !-- 泳道内的服务parenttier1坐标相对泳道 -- mxCell idwebapp valueWeb App stylerounded1;whiteSpacewrap;html1;fillColor#dae8fc;strokeColor#6c8ebf; vertex1 parenttier1 mxGeometry x80 y40 width120 height60 asgeometry / /mxCell注意跨层连接线使用绝对坐标并parent1。5.3 时序图配方时序图的关键要素Actor顶部、生命线虚线竖线、激活框、消息箭头。其中生命线是浮动边——用sourcePoint/targetPoint而非source/target!-- Actor火柴人 -- mxCell idactorA valueClient styleshapemxgraph.uml.actor;pointerEvents1;dashed0;whiteSpacewrap;html1;aspectfixed; vertex1 parent1 mxGeometry x110 y80 width60 height80 asgeometry / /mxCell !-- 生命线浮动边使用 sourcePoint/targetPoint -- mxCell idlifA value styleedgeStylenone;dashed1;endArrownone; edge1 parent1 mxGeometry relative1 asgeometry mxPoint x140 y160 assourcePoint / mxPoint x140 y700 astargetPoint / /mxGeometry /mxCell !-- 同步消息 -- mxCell idmsg1 valuePOST /orders styleedgeStyleelbowEdgeStyle;elbowvertical;html1;endArrowblock;endFill1; edge1 sourceactA1 targetactorB parent1 mxGeometry relative1 asgeometry / /mxCell !-- 返回消息虚线 -- mxCell idmsg2 value201 Created styleedgeStyleelbowEdgeStyle;elbowvertical;dashed1;html1;endArrowopen;endFill0; edge1 sourceactorB targetactA1 parent1 mxGeometry relative1 asgeometry / /mxCell5.4 ER 图配方表容器使用shapetablechildLayouttableLayout行为shapetableRow并带portConstrainteastwest行内列用shapepartialRectangle。关系连线使用entityRelationEdgeStyle一对一startArrowERone;endArrowERone一对多startArrowERone;endArrowERmany多对多startArrowERmany;endArrowERmany强制ERmandOne可选ERzeroToOne5.5 UML 类图配方类框即 swimlane 容器属性与方法为普通文本 cell分隔线为零高度泳道子元素。关系箭头样式关系样式串继承extendsedgeStyleorthogonalEdgeStyle;html1;endArrowblock;endFill0;实现implementsedgeStyleorthogonalEdgeStyle;dashed1;html1;endArrowblock;endFill0;组合compositionedgeStyleorthogonalEdgeStyle;html1;startArrowdiamond;startFill1;endArrownone;聚合aggregationedgeStyleorthogonalEdgeStyle;html1;startArrowdiamond;startFill0;endArrownone;依赖dependencyedgeStyleorthogonalEdgeStyle;dashed1;html1;endArrowopen;endFill0;关联associationedgeStyleorthogonalEdgeStyle;html1;endArrowopen;endFill0;六、布局最佳实践所有坐标对齐到10 px 网格坐标值可被 10 整除水平方向同一行形状之间留 40–60 px 间距垂直方向层级行之间留 80–120 px 间距标准形状尺寸处理框120 × 60px判断菱形200 × 100px默认画布A4 横向1169 × 827px每页最多 40 个 cell更大的图拆分为多页每页顶部必须有标题文本 cellstyletext;strokeColornone;fillColornone;fontSize18;fontStyle1;aligncenter;此外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 id0 /与mxCell id1 parent0 /是前两个 cell所有 cell id 在其 diagram 内唯一所有边的source/target指向已存在的顶点所有顶点 cell 都有mxGeometry asgeometry除id0外所有 cell 都有合法的parentXML 格式良好——没有未闭合标签、属性值中没有未转义的、、语义化配色使用一致每页都有标题 cell8.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逐页检查id0、id1是否存在且id0必须是第一个 cell、id1必须是第二个 cellid1的parent必须为0源码 L83–L103标题 cell脚本要求每页存在 style 以text;开头或含;text;且包含fontSize18的顶点 cell源码 L104–L122——这与清单中的「标题 cell」要求一一对应顶点结构vertex1的 cell 必须有mxGeometry子元素边连接edge1的 cell 必须有source/target且指向已存在 id除非mxGeometry内含sourcePoint/targetPoint即浮动边例外源码 L150–L184 通过mxPoint的as属性识别父链除id0外所有 cell 的parent必须引用已存在的 id。退出码约定0表示全部通过1表示发现错误错误信息打印到 stdout。脚本还支持一次校验整个目录for f in docs/**/*.drawio; do python skills/draw-io-diagram-generator/scripts/validate-drawio.py $f; done8.3 用 add-shape.py 安全地增补形状当只想给既有图表加一个形状、又不想手改 XML 时可用配套的 add-shape.pypython skills/draw-io-diagram-generator/scripts/add-shape.py diagram.drawio label x y [options]主要参数与选项详见 scripts/README.md参数/选项默认值说明diagram、label、x、y必填文件路径、标签文本、坐标px--width/--height120/60形状尺寸--stylerounded1;whiteSpacewrap;html1;draw.io 样式串--diagram-index0目标页面索引0 起--dry-runfalse只打印新 cell 的 XML不写文件示例# 添加一个自定义样式的菱形判断节点 python skills/draw-io-diagram-generator/scripts/add-shape.py docs/flowchart.drawio Decision 400 400 \ --width 160 --height 80 \ --style rhombus;whiteSpacewrap;html1;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 中打开是空白缺少id0或id1cell在其它 cell 之前补上两个根 cell形状位置不对子元素在容器内坐标为相对坐标检查parent按容器原点调整 x/y边不可见source或target与任何顶点不匹配核实两个 id 与顶点 id 完全一致显示 CompressedmxGraphModel 被 base64 编码用 draw.io Web 打开File Export XML未压缩形状样式未渲染shape名称拼写错误对照 shape-libraries.md 精确样式串标签显示转义后的 HTML带 HTML 标签的 cell 未启用html1在 style 中加入html1;容器子元素越出容器边界容器高度不足在 mxGeometry 中增大容器高度十、可继续深入的文件本套规范在仓库中有完整的配套资源按需查阅文件用途skills/draw-io-diagram-generator/SKILL.md完整 Agent 工作流、各类型配方、排查指南skills/draw-io-diagram-generator/references/drawio-xml-schema.mdmxfile / 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.pyXML 结构校验器skills/draw-io-diagram-generator/scripts/add-shape.pyCLI向既有图表添加形状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 图、从单页到多页这套标准都给出了一致的答案。【免费下载链接】awesome-copilotCommunity-contributed instructions, agents, skills, and configurations to help you make the most of GitHub Copilot.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-copilot创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考