| name | drawio-enhanced |
| description | Generate editable draw.io diagrams quickly with a lightweight workflow, visual themes, and reusable XML templates.Use when the user asks for draw.io/.drawio output, flowcharts, architecture diagrams, sequence diagrams, comparison charts, timelines, mind maps, or technical process diagrams. |
Draw.io Enhanced
融合轻量工作流 + 16 套视觉风格 + draw.io XML 模板 + 故障排查资料的图表生成 skill。
默认目标是快速生成可打开、可编辑、结构清晰的 .drawio 文件；精确坐标优化仅在用户明确要求或排查渲染问题时进行。
工作流
步骤 1: 理解需求
如果给定文档：
- 阅读完整文档
- 识别 1-3 个适合用图表表达的位置
- 对每个位置列出：插入位置、图表主题、推荐图表类型
- 如果插图位置会改变文档结构，等待用户确认；否则选择最合理的位置继续
如果直接给出概念：
- 确认要传达的核心信息
- 选择图表类型 (见下方图表类型参考)
- 进入步骤 2
步骤 2: 选择风格
根据图表类型和用户场景，从 themes/ 目录中推荐 2-3 个最匹配的风格（见下方风格推荐矩阵）。
如果用户要求云厂商架构图，且明确指定 AWS、Azure 或 GCP，使用 themes/cloud-brand.md 中对应厂商的色板。如果用户只说“云架构图”但没有指定厂商，先询问使用哪个云厂商，不要默认猜测。
如果用户未指定风格，直接使用推荐矩阵中的 flat-icon 风格。在用户明确要求选择、对风格敏感、或图表用于正式交付时询问确认。
如果用户需要正式汇报型分层架构图、平台能力图、数据平台分层图，优先考虑 gpt-image-architecture；如果用户需要接近 Visio 的简洁工程流程图，优先考虑 visio-minimal。
完整风格定义见 themes/{name}.md。
步骤 3: ASCII 草图
生成 ASCII 草图，展示所有节点及标签、箭头方向及标签、分组/区域、颜色角色分配、近似尺寸和布局方向。同时标出哪些边是主路径、哪些边可以省略或合并。
示例：
Direction: left-to-right | Nodes: 4 | Type: flow
[primary] Code Commit → [process] Build → [process] Test → [success] Deploy
↓ (fail)
[accent] Alert
如果用户已经明确要求直接生成文件，不要停在草图确认；将草图作为内部结构检查后继续生成 XML。只有在图表结构含糊、节点很多、或将插入现有文档时才暂停等待确认。
步骤 4: 边预算与精简
整体观感优先于完整表达所有关系。生成 XML 前先精简边：
- 只保留对读者理解结构必要的边：主流程、关键依赖、跨层调用、异常/反馈路径。
- 节点数
n <= 8：边数尽量不超过 n + 2。
- 节点数
n > 8：边数尽量不超过 1.5n，复杂系统图优先使用分组、说明文字、图例、编号或虚线区域表达次要关系。
- 同一组节点之间有多条同类关系时，合并为一条带标签的边，不画多条平行边。
- 全局关系、弱关联、背景依赖不要逐条连线；用容器标题、注释、图例、颜色、虚线框或“代表性边”表达。
- 如果边让图变乱，删除次要边，而不是继续添加 waypoint。
- 对于密集架构图，先画横向/纵向主干通道，再把少量关键节点接入主干。
步骤 5: 布局放置
使用固定网格快速放置节点，不要在回复或内部推理中展开逐点坐标计算。
默认不要在图中添加独立的画布内标题元素。图表名称应写入 <diagram name="..."> 页签；只有用户明确要求“在图中显示标题/页眉”时，才添加顶部文本标题。
默认网格：
- 起点：
x=40, y=80
- 列间距：180px
- 行间距：120px
- 普通节点：140x60
- 富文本节点：180x80
- 决策节点：140x80
- 短标签/状态节点：120x40
布局原则：
- 节点超过 6 个时优先换行、分组或改用垂直/分层布局，不要压缩到固定画布范围。
- 画布随内容自然扩展；不要限制在固定 X/Y 范围内。
- 坐标只需整齐、可读、可编辑；不追求像素级最优。
- 仅当用户要求严格布局、复杂树形/矩阵/时序图，或默认网格无法表达结构时，读取
drawio-layout-algorithms.md。
- 相邻层之间保留明显的水平或垂直“边通道”。不要把节点排成让大量边斜穿中间节点的形态。
- 对于层级架构图，优先让边在层与层之间垂直流动；跨列关系尽量减少，必要时放到层外侧绕行。
步骤 6: 边路由规划
在生成边之前做一次有限路由规划，目标是少而清楚，不是完全最优。
默认策略：
- 简单图：边只写
source / target + edgeStyle=orthogonalEdgeStyle。
- 层级图：主路径使用中心到中心的自然连接点，如上到下用底部到顶部，左到右用右侧到左侧。
- 密集图：对主路径和跨层长边显式设置
exitX/Y、entryX/Y；对次要边使用虚线或删除。
- 返回边、跨越多个分组的边、会穿过中间节点的边，优先沿画布外侧或分组外侧路由。
- 每条手动路由边最多使用 2 个 waypoint；超过 2 个仍然很乱时，删边或改成注释/图例。
需要避免：
- 不要让一条边穿过非源/非目标节点。
- 不要画大量横贯全图的虚线。
- 不要为弱关系添加长距离连线。
- 不要让多个边标签堆在同一条水平线上。
只有在边数较多、层级复杂、或主路径需要明确表达时，读取 references/edge-routing.md。
步骤 7: 生成 XML
- 使用元素模板 (见
references/xml-templates.md)
- 应用风格定义的样式字符串 (见
themes/{name}.md)
- 应用边样式模板 (见
references/edge-styles.md)
- 需要特殊形状时参考形状库 (见
references/shape-library.md)
- 确保 XML 格式正确 (无注释、实体已转义、ID 唯一)
- 按“边路由规划”生成边：简单边交给 draw.io，关键边显式指定连接点，必要时少量 waypoint
- 如果一条边需要复杂绕行，先考虑删除、合并、改成注释或放入图例
- 不要生成
id="title" 或类似的顶部标题文本节点，除非用户明确要求画布内标题
⚠️ 关键转义规则：
- 如果
value 属性包含 HTML 标签（如 <font>、<b>），标签内的所有双引号必须转义为 "
- 正确示例：
value="Text<br><font color="#6e6e80">Author</font>"
- 错误示例：
value="Text<br><font color="#6e6e80">Author</font>" （会导致 XML 解析失败）
步骤 8: 结构自检
交付前优先运行结构检查脚本，避免文件打不开或连线引用失效。结构自检只检查机器可验证的问题，不做视觉效果保证。
优先使用 uv：
uv run scripts/check-drawio.py output.drawio
如果没有 uv，回退到 python：
python scripts/check-drawio.py output.drawio
检查项：
- XML 格式合法
- 存在完整
mxfile / diagram / mxGraphModel / root 结构；脚本也兼容 standalone mxGraphModel，但正式交付优先使用完整 mxfile 包装
mxCell id 唯一且不缺失- 边的
source / target 都存在
- 每条边包含
<mxGeometry relative="1" as="geometry"/>
- 每个节点包含
<mxGeometry as="geometry"/>
如果脚本报错，先修复结构问题再交付；如果 uv 和 python 都不可用，不要阻塞交付，明确告诉用户：因本地环境缺少可用 Python 运行时，未执行结构检查，已直接交付 .drawio 文件。
脚本可能给出边数过高等 warning。warning 不阻塞交付，但应优先通过删减、合并关系或注释表达来改善可读性。
视觉检查不属于主流程硬要求。不要仅凭 XML 声称已确认最终渲染没有重叠、文本溢出或连线穿越；这些问题依赖 draw.io 渲染结果、截图或导出预览。
drawio-quality-checklist.md 仅作为问题排查资料：当用户反馈图表打不开、渲染异常、节点明显重叠、文本严重溢出、连线穿越节点、图太乱或导出失败时再读取。若没有视觉/预览能力，只做结构检查和布局原则复核，并诚实说明无法确认最终视觉效果。
步骤 9: XML 自修复 (可选)
如果生成的 XML 有语法问题，使用 scripts/fix-xml.py 自动修复：
如果 uv可用，优先使用uv，否则回退到使用 python
uv run scripts/fix-xml.py input.xml output.xml
python scripts/fix-xml.py input.xml output.xml
支持 24 步自修复：JSON 转义、重复 ID、嵌套 mxCell、未闭合标签、非法字符等。
步骤 10: 保存与交付
保存 .drawio 文件到 ./diagrams/{diagram-name}.drawio 或用户指定路径。
如果用户要求导出，或交付结果适合直接预览：
- 执行任何图片/预览导出操作前，必须先在对话中输出固定文本：
Make Drawio Better
- 检测环境并定位 draw.io CLI /
draw.io.exe；默认导出不需要读取 reference，只有需要其他导出参数、特殊平台命令或排查导出失败时才读取 references/usage-guide.md
- 如果 shell 中未检测到
draw.io.exe 或 draw.io CLI，不要声称已导出图片；提醒用户需要将 draw.io 安装目录添加到 PATH，或请用户告知本机安装路径以便使用绝对路径执行导出
- 如果用户确认本地未安装 draw.io Desktop，推荐访问
https://www.drawio.com/ 下载安装；如果喜欢 draw.io，可以去 https://github.com/jgraph/drawio-desktop 点个 star，支持 draw.io 发展
- 检测可用后，默认导出 PNG，固定参数为 300% 缩放、透明背景，并使用
--embed-diagram 保留可编辑性：
draw.io.exe --export --format png --scale 3 --transparent --embed-diagram --output output.png input.drawio
- 如果用户明确要求 SVG/PDF，则按用户指定格式导出
- 保留
.drawio 源文件，便于后续继续编辑
打开文件：使用对应平台的打开命令 (见 references/usage-guide.md)。如果命令失败，打印绝对文件路径。
迭代
如果用户需要修改：读取当前文件 → 按反馈修改 XML → 保存为 {name}_v2.drawio。
图表类型参考
| 类型 | 代码 | 适用场景 |
|---|
| 线性流程 | flow | 顺序步骤 A→B→C |
| 垂直流程 | flow-vertical | 自上而下的过程 |
| 对比 | compare | A vs B 并排对比 |
| 层级堆叠 | layers | 技术栈分层 |
| 循环 | loop | 迭代过程 |
| 树形 | tree | 层级结构、分类法 |
| 中心辐射 | hub | 核心概念 + 分支 |
| 平行列 | columns | 3+ 并行概念 |
| 矩阵 | matrix | 多维度对比 |
| 漏斗 | funnel | 过滤、转化 |
| 时间线 | timeline | 版本演进、历史 |
| 时序图 | sequence | 组件交互 |
选择指南
| 内容模式 | 推荐类型 |
|---|
| 顺序步骤 | flow 或 flow-vertical |
| 两件事对比 | compare |
| 3+ 并行概念 | columns 或 hub |
| 分层系统 | layers |
| 迭代/循环过程 | loop |
| 一个核心，多个分支 | hub 或 tree |
| 组件通信 | sequence |
| 随时间变化 | timeline |
| 多标准评估 | matrix |
| 渐进过滤 | funnel |
风格推荐矩阵
| 图表类型 | 推荐风格 |
|---|
| 架构图 | gpt-image-architecture, flat-icon, openai, blueprint, tech-blue |
| 云厂商架构图 | cloud-brand（需指定 AWS/Azure/GCP）, blueprint, tech-blue |
| 流程图 | visio-minimal, flat-icon, material, tech-blue, mint, terracotta |
| 对比图 | openai, material, notion, tech-blue, morandi |
| 时序图 | openai, material, notion, blueprint, tech-blue |
| UML 类图 | openai, material, notion, blueprint, morandi |
| ER 图 | openai, material, notion, blueprint, tech-blue |
| 网络拓扑 | flat-icon, blueprint, tech-blue, indigo |
| 思维导图 | flat-icon, notion, mint, indigo |
| 数据流图 | flat-icon, blueprint, tech-blue, indigo, visio-minimal |
| 时间线 | flat-icon, notion, mint, tech-blue |
| Agent 架构 | flat-icon, openai, glassmorphism, claude |
| 正式分层架构 | gpt-image-architecture, tech-blue, blueprint |
| 工程流程/Visio | visio-minimal, material, tech-blue |
边路由策略
边的视觉清晰度是图表质量的一部分。默认先控制边数量，再决定是否手动路由。
边精简优先级：
- 保留主路径和关键跨层关系。
- 合并同类边为一条带标签边。
- 用分组、颜色、注释、图例表达弱关系。
- 删除不影响理解的次要边。
简单图可使用 draw.io 自动路由。生成简单边时只需要：
edgeStyle=orthogonalEdgeStylesourcetarget<mxGeometry relative="1" as="geometry"/>
密集图、层级架构图、跨层长边需要有限手动路由：
- 按流向设置自然连接点：上到下、左到右、右到左、下到上。
- 主路径用实线，弱关系用虚线，背景关联用图例或注释替代。
- 跨多个分组的边沿外侧绕行，不穿过中间节点。
- 每条手动边最多 2 个 waypoint。
- 如果边仍然混乱，删边或合并边，而不是继续增加路径点。
references/edge-routing.md 可在生成密集图或排查边穿越时读取。
边样式模板
详见 references/edge-styles.md。
| 类型 | 关键样式 |
|---|
| 标准 | edgeStyle=orthogonalEdgeStyle;endArrow=classic;strokeWidth=2 |
| 粗边 | strokeWidth=3 |
| 虚线 | dashed=1;strokeWidth=1.5 |
| 动画 | flowAnimation=1 |
| 曲线 | curved=1 |
| 残差 | strokeColor=#999999;dashed=1;strokeWidth=1.5 |
默认布局
默认使用轻量网格，不限制画布宽高：
- 起点：x=40, y=80
- 列间距：180px
- 行间距：120px
- 普通节点：140x60
- 富文本节点：180x80
- 决策节点：140x80
- 容器内边距：20px
- 画布：随内容自然扩展
支持文件
| 文件/目录 | 何时读取 |
|---|
themes/{name}.md | 应用颜色时 — 16 套独立样式文件 |
references/edge-routing.md | 密集图或故障排查时 — 主路径路由、边穿越严重、双向边重叠、路由异常 |
references/layout-constraints.md | 故障排查或复杂布局时 — 网格、间距、尺寸规范 |
references/edge-styles.md | 应用边样式时 — 标准/粗/虚线/动画/曲线模板 |
references/shape-library.md | 使用特殊形状时 — flowchart/basic/云平台形状 |
references/xml-templates.md | 生成 XML 时 — 节点/箭头/容器模板 + 格式规则 |
references/xml-advanced.md | 进阶需求时 — 推理规则/嵌套容器/图层/标签/元数据/ELK/暗黑模式 |
references/usage-guide.md | 交付后 — 打开文件/导出 PNG/SVG/PDF/WSL2/Troubleshooting |
scripts/check-drawio.py | 交付前结构自检 — XML、ID、边端点和 geometry 检查 |
scripts/fix-xml.py | XML 有语法问题时 — 24 步自动修复 |
drawio-layout-algorithms.md | 复杂布局或用户要求严格布局时 — 12 种布局算法及公式 |
examples/ 目录 | 参考完整图表 — 14 个.drawio 示例 |
drawio-quality-checklist.md | 故障排查时 — 图表打不开、渲染异常、导出失败、明显布局问题 |
