drawio-diagram-forge

Draw.io Diagram Forge

使用 AI 驱动的工作流生成 draw.io 可编辑图表。

何时使用

• 创建架构图（Azure、AWS）
• 将文本描述转换为流程图
• 将图片/截图转换为可编辑格式
• 生成泳道图、时序图
• 编辑现有 .drawio 文件中的 Azure/AWS 图标

当结果后续需要在 draw.io 中进行 GUI 编辑、需要云图标，或作为面向文档的图表资产时，请选择此技能。

何时不使用

• 更适合以 Mermaid 形式保留在 README 或 Markdown 中的快速内联图表
• 预期无需手动 GUI 调整的一次性文本原生图表
• 需要精确坐标轴、数据绑定、排版或脚本化重新生成的图表或信息图
• 字体渲染必须在各平台间完全一致的大型多语言标签集
• 交互式或动画 HTML 图表，或 Mermaid 美化（超出范围）

前提条件

工具	必需
VS Code	是
Draw.io Integration	是
GitHub Copilot	是

快速开始

Create a login flow diagram

Generate an Azure Hub-Spoke architecture diagram

From inputs/requirements.md, create a system diagram

输出格式

扩展名	描述	何时使用
*.drawio	原生格式	推荐
*.drawio.svg	SVG + 元数据	Markdown/Web
*.drawio.png	PNG + 元数据	可编辑的图片

输出：outputs/

如果用户要求可编辑图表，请将 *.drawio 作为主要交付物。不要让普通 SVG 或预览产物成为用户预期编辑的文件。

推荐的交付模式

面向文档时，请成对输出 name.drawio（可编辑）+ name.drawio.svg（嵌入）。多语言变体、发布到 Qiita、以及本地预览脱出的流程 → references/delivery-patterns.md。

工作流

将生成的图片视为可选的布局参考，而非需求依据。在清单中确定标签、节点、分组和边的方向；标记歧义，而不是臆造内容。重建原生 mxCells 和连接线；将位图包裹在 draw.io 元数据中并不会使其元素可编辑。

USER INPUT → ORCHESTRATOR → MANIFEST GATEWAY → SVG FORGE → COMPLETED

质量门禁

分数	操作
85-100	继续
70-84	修复并重试
50-69	简化
0-49	询问用户

当交付物用于印刷时，在进行任何视觉审查之前，请先通过 style-guide.md 中的 Monochrome Print Profile 和 Pre-delivery Geometry Sweep 进行门禁检查。

限制

限制	值
清单修订	2
SVG 修订	2
总超时	45min

云图标

使用 Cloud Icons Reference。Azure 图表必须使用经验证的 img/lib/azure2/**/*.svg 图片路径，保留简短的服务标签，并且仅在图标缺失或具有误导性时回退到中性方框。

参考

文件	描述
mxcell-structure.md	mxCell XML 结构
cloud-icons.md	Azure/AWS 图标指南
style-guide.md	节点、边样式
delivery-patterns.md	可编辑嵌入配对、Qi、多语言、troubleshooting.md](references/troubleshooting.md)

脚本

脚本	描述
scripts/validate_drawio.py	校验 mxCell 结构

故障排查

常见问题前 4 项如下。完整列表（框架/边距/PDF 输出、图例位置、转义层、CLI 的 export 选项等 21 项）见 references/troubleshooting.md。

问题	解决方案
draw.io 中显示空白	检查 content 属性
边不可见	验证节点
图标缺失	启用 Azure/AWS 形状（+ More Shapes → Azure / AWS）
文本靠近边缘	顶部内边距 16–24px，增加高度、换行至 3–4 行，按实际嵌入宽度复查

完成标准

• 已生成 .drawio 或 .drawio.svg
• 图表可在 VS Code Draw.io 中正常打开
• 若交付物包含可编辑的 .drawio.svg，已使用 --embed-diagram 导出并包含 mxfile
• 所有节点均可见
• 面向用户的指向处指向可编辑的 .drawio，预期可编辑
• 决策避免过长的返回/合并线将分支输出汇回一处
• 质量评分达到 85 分
• 若图表被文档引用，则同时包含可编辑源文件和可嵌入图片
• 已完成目标嵌入宽度下的渲染复查：无文本重叠、遮挡或边框碰撞，无多条边重叠于同一直线，无边的端点埋入填充框内，无标签压在框或其他标签上，无节点超出页面
• 任何边或标签布局变更后，重新导出目标媒介的交付资源（Web 用 SVG，打印用 PNG 或最终 PDF）并检查；仅结构校验不足以证明视觉走线质量