drawio-architecture

Draw.io 架构图 + MCP 集成

使用 draw.io 原生 .drawio XML 格式创建专业、可编辑的架构图，并集成官方 draw.io MCP 服务，使图表可直接在编辑器中打开。此技能整合了两个经过验证的来源：

1. 创作知识 — 如何为架构、网络、云、流程图和 ER 图编写正确的 .drawio XML（来自 Agents365-ai/drawio-skill 和 scarr05/claude-skills-pub）。
2. MCP 集成 — 如何配置和调用官方 @drawio/mcp 服务，使 Agent 能在行内或编辑器中打开图表，而不是将 XML 倒进文件（来自 jgraph/drawio-mcp，即供应商自己的参考资料）。

安全与信任边界

• 固定 MCP 服务版本：npx 可以下载并执行远程代码。不要直接运行 npx -y @drawio/mcp。请使用带明确版本号的 npx -y @drawio/mcp@<VERSION>，并通过 npm 或项目的锁文件进行验证。安装前请验证软件包名称和发布者（JGraph / drawio）。
• 优先使用本地 stdio 或可自托管方案：推荐的集成方式是将 @drawio/mcp 作为本地 stdio 进程运行。如果使用 DRAWIO_BASE_URL，请将其指向由你控制且可信的 draw.io 实例。
• 托管端点注意事项：https://mcp.draw.io/mcp 是由 draw.io 供应商运营的远程 MCP Apps 端点。它会接收图表 XML 并在行内渲染。只有在供应商、TLS 通道和数据敏感性均可接受时，才使用该端点处理图表。请勿向托管端点发送机密或受监管的架构数据。
• SVG/PNG 导出在本地进行：CLI 导出路径（drawio -x ...）会在本地运行桌面应用，除非你明确打开浏览器 URL，否则不会上传图表。

适用场景

• 用户要求绘制架构图 / 系统图 / 服务图 / 网络图 / 云图、流程图、ER 图、序列图 / UML 类图、C4 模型或任何 draw.io/diagrams.net 可视化图表。

• 用户希望图表自动在 draw.io 中打开（MCP），而不是保存为文件以便手动导入。

• 你正在为当前 Agent/IDE 配置 draw.io MCP 服务，需要获取各平台对应的准确配置块。

• 你希望 Agent 搜索官方形状库（AWS/Azure/GCP/Cisco/K8s/品牌徽标），而不是猜测 shape= 字符串。

• 用户用英语请求或提及此技能（例如：“use /drawio-architecture”、“run drawio-architecture”）。

• 用户用葡萄牙语请求或提及此技能（例如：“use /drawio-architecture”、“execute drawio-architecture”）。

不适用场景

• 随手手绘 / 白板风格 → 使用 excalidraw 或 tldraw。
• 在 git 中维护并以 Markdown 渲染的代码生成图表 → 使用 mermaid-architecture（通用）或 plantuml（UML）。
• 自由绘制的无限画布草图 → 使用 tldraw。

两种交付路径（选择一种，也可组合）

路径	功能	适用场景
A. MCP（推荐用于聊天 Agent）	Agent 调用 MCP 工具（open_drawio_xml）→ draw.io 编辑器在浏览器标签页中打开图表。无需在磁盘上创建文件。	Agent 是 MCP 客户端（Claude Desktop/Code、VS Code Copilot、Cursor、OpenCode、Windsurf）。适用于“给我看看图表”这类场景。
B. 本地 CLI	Agent 写入 .drawio 文件，然后使用 drawio -x -f png ... 在本地导出 PNG/SVG/PDF。	无头环境/CI、需要图像交付物或没有 MCP 可用。需要 draw.io 桌面版 CLI。

两种路径均遵循此技能中的相同 XML 创作规则，区别仅在交付步骤。你可以按照下方规则生成 XML，并将其传入 open_drawio_xml（路径 A），或写入本地文件后使用 CLI 导出（路径 B）。

---

路径 A — MCP 服务：配置与使用

A.1 配置服务

该服务以 npx @drawio/mcp（stdio）的形式分发。固定指定一个版本并在本地运行：

npx -y @drawio/mcp@<VERSION>

将 <VERSION> 替换为在 npm 上确认的最新稳定版本。不要直接运行 npx -y @drawio/mcp，因为它会在运行时解析到最新的远程版本。

将其添加到客户端的 MCP 配置中，路径为 mcpServers.drawio。各平台对应的具体 JSON 配置块以及可自托管实例的说明，请参阅 references/mcp-config.md（Claude Desktop、Claude Code、VS Code .vscode/mcp.json、Cursor ~/.cursor/mcp.json、OpenCode、Windsurf，以及用于可自托管实例的 DRAWIO_BASE_URL 环境变量）。

另有一种托管替代方案（https://mcp.draw.io/mcp），它通过 MCP Apps 协议（Claude.ai、VS Code、Cursor）内嵌渲染图表——无需安装，但它与上面的 stdio 服务是不同类型的服务，并且会将图表 XML 发送到 draw.io 供应商的服务器。仅在图表不含敏感信息且你信任该供应商端点时使用。

自动配置助手

运行随附的助手，自动检测 Agent／平台并添加正确的配置：

python3 scripts/setup_drawio_mcp.py --detect
python3 scripts/setup_drawio_mcp.py --target claude-code --dry-run
python3 scripts/setup_drawio_mcp.py --target vscode --global

所有 --target 值（claude-desktop、claude-code、vscode、cursor、opencode、windsurf、raw）和标志（--dry-run、--global、--force）请参阅 scripts/setup_drawio_mcp.py。

A.2 MCP 工具参考

该服务提供以下工具。在提示词中明确提及工具名称，让 Agent 使用 MCP，而不是手动编写文件（“始终使用 draw.io MCP 工具创建图表。”）。

open_drawio_xml — 架构图的主要工具

使用原生 draw.io/mxGraph XML 打开编辑器。参数：

参数	类型	必填	说明
content	string	是	完整的 <mxfile>…</mxfile> XML（按本技能的要求编写）
lightbox	boolean	否	只读视图（默认值为 false）
dark	string	否	"auto" / "true" / "false"（默认值为 "auto"）
routing	string	否	"libavoid" 会在打开前重新规划连接线，使其绕开形状（避开障碍物的正交路由）

open_drawio_mermaid

使用 Mermaid.js 图表打开编辑器。适用于无需自定义样式／图标的标准类型图表（流程图、时序图、类图、状态图、ER 图、甘特图、思维导图、桑基图等）：编写 Mermaid 文本，由 draw.io 渲染为可编辑图表。参数：content（必填）、lightbox、dark。

open_drawio_csv

使用转换为图表的 CSV 打开编辑器（组织结构图、表格）。参数：content（必填）、lightbox、dark。

search_shapes

搜索 draw.io 的约 10,000 个形状库（AWS、Azure、GCP、Cisco、Kubernetes、P&ID、电气、BPMN 等），并返回可直接用于 open_drawio_xml 的 style 字符串。该工具还集成了 draw.io 图标服务，可搜索品牌标识（react、slack、shopping cart）。参数：query（以空格分隔的关键词，必填）、limit（默认值为 10，最大值为 50）。

仅当图表需要特定行业／品牌图标（云架构、网络拓扑、P&ID、K8s、BPMN 细节、品牌标识）时使用 search_shapes。使用基本形状的流程图／UML／ERD／组织结构图／思维导图无需使用。

list_pages / get_page / set_page

对本地多页 .drawio／.xml 文件进行页面级访问。可通过从 0 开始的索引、准确名称或 id 指定页面。

工具	参数	结果
list_pages	path	[{index, id, name, approxSizeBytes}]
get_page	path, page	该页面的 <mxGraphModel> XML
set_page	path, page, content	替换该页面（单个 <mxGraphModel>）；其他页面不变

A.3 布局与路由处理（MCP open_drawio_xml）

声明逻辑结构（节点、边、标签、容器）。draw.io 的路由器和可选的后期布局负责放置。有两个可选的 open_drawio_xml 处理阶段：

• routing: "libavoid" — 保留节点位置，将边重新路由为正交路径，绕开形状。适用于经过精心布局的架构、网络、部署和泳道图，这类图中连线不应穿过方框。
• postLayout: "elk" — 完整重新布局（ELK layered）；重新放置节点并路由边。最适合有方向的分层流程（流程图、流水线、决策流程）。从左向右时，设置 direction: "horizontal"。不要与 routing 一起使用——二选一。

对于 Mermaid：复杂流程图（≥ 约 20 个节点、≥ 3 个菱形、反馈边或 ≥ 3 个端点）需要 postLayout: "elk"；简单流程图以及所有非流程图类型的 Mermaid 图都不需要。

---

路径 B — 本地 CLI 导出（备用方案／交付物）

首先确定二进制文件名（Homebrew／Linux .deb／.rpm／AUR 使用规范名称 drawio；旧版本使用 draw.io；macOS .app／Windows .exe 使用完整路径）。将所有图表文件存放在 docs/architecture/ 下：

# Ensure the architecture docs folder exists
mkdir -p docs/architecture

# Preview PNG (NO -e; required for vision self-check; width-capped under 2576px)
drawio -x -f png --width 2000 -o docs/architecture/diagram.png docs/architecture/diagram.drawio

# Final PNG (WITH -e; double extension keeps it editable; run repair_png after)
drawio -x -f png -e -s 2 -o docs/architecture/diagram.drawio.png docs/architecture/diagram.drawio

# SVG / PDF (final, -e safe)
drawio -x -f svg -e --embed-svg-images -o docs/architecture/diagram.svg docs/architecture/diagram.drawio
drawio -x -f pdf -e -o docs/architecture/diagram.pdf docs/architecture/diagram.drawio

每次使用 -e 导出 PNG 后，都要修复 draw.io 截断的 IEND 块：

python3 scripts/validate_drawio.py docs/architecture/diagram.drawio.png --repair-iend

如果 CLI 不可用，则回退到浏览器 URL（不上传——XML 存放在 # 片段中）：

python3 scripts/setup_drawio_mcp.py --viewer-url docs/architecture/diagram.drawio        # read-only
python3 scripts/setup_drawio_mcp.py --viewer-url --edit docs/architecture/diagram.drawio # editable editor URL

完整的 Linux 无头运行（xvfb-run、--no-sandbox、--disable-gpu、HOME）指南和回退流程，请参阅 references/mcp-config.md。

---

编写 .drawio XML — 规则（两种路径通用）

这些规则来自供应商自己的 shared/xml-reference.md（MCP 提示词的唯一事实来源）以及 Agents365/claude-skills-pub 编写指南。无论 XML 是提供给 open_drawio_xml 还是写入本地文件，都必须遵守。

文件框架

<mxfile host="app.diagrams.net" modified="2026-01-01T00:00:00" agent="agent" version="24.0.0" type="device">
  <diagram name="Page-1" id="page1">
    <mxGraphModel dx="1200" dy="800" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="1100" pageHeight="850" math="0" shadow="0">
      <root>
        <mxCell id="0" />
        <mxCell id="1" parent="0" />
      </root>
    </mxGraphModel>
  </diagram>
</mxfile>

规则：id="0" 和 id="1" 是必需的根单元格，不可省略。用户形状从 id="2" 开始，且 ID 必须唯一。顶层形状使用 parent="1"。如果文件要从磁盘打开，请设置 type="device"。

严格网格（适用于每张图）

• 列 x = col*180 + 40（col 0 = 40，col 1 = 220，……）
• 行 y = row*120 + 40（row 0 = 40，row 1 = 160，……）
• 节点尺寸：矩形 140×60、菱形 140×80、圆形 60×60、文档 120×80、圆柱体 100×70

将每个节点放在一个 (col,row) 位置；路由器会处理间距。不要手动添加 <Array as="points"> 路点或 exitX/entryY 覆盖项，除非有特定的几何布局需求。

核心形状（顶点）

<mxCell id="2" value="Label" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;" vertex="1" parent="1">
  <mxGeometry x="100" y="100" width="140" height="60" as="geometry"/>
</mxCell>


<mxCell id="3" value="Condition?" style="rhombus;whiteSpace=wrap;html=1;fillColor=#fff2cc;strokeColor=#d6b656;" vertex="1" parent="1">
  <mxGeometry x="100" y="200" width="140" height="80" as="geometry"/>
</mxCell>


<mxCell id="4" value="DB" style="shape=cylinder3;whiteSpace=wrap;html=1;fillColor=#f5f5f5;strokeColor=#666666;" vertex="1" parent="1">
  <mxGeometry x="350" y="100" width="100" height="70" as="geometry"/>
</mxCell>

边（连接器）

**重要：**每个边 mxCell 都需要一个展开的 <mxGeometry relative="1" as="geometry" /> 子元素。自闭合的边单元格不会渲染。

<mxCell id="e1" value="HTTP" style="edgeStyle=orthogonalEdgeStyle;rounded=1;html=1;" edge="1" parent="1" source="2" target="3">
  <mxGeometry relative="1" as="geometry"/>
</mxCell>

• 不要手动规划路由——只需声明 source／target。若要让连线整齐地以正交路径绕过方框，请设置 routing:"libavoid"（MCP），或在 CLI 文件中采用相同思路。
• **每张图的边样式应保持一致：**ER → entityRelationEdgeStyle；UML 类图 → 直线（不设置 edgeStyle）；思维导图 → curved=1；流程图／架构图／网络图 → orthogonalEdgeStyle。
• 边标签应简短（1–3 个词：Yes、async、reads）。更长的说明应放入节点文本或图例节点中。
• 动画数据流：添加 flowAnimation=1;。

容器与嵌套架构

使用真正的父子包含关系（不要将图形放在更大的图形上）。

类型	样式	适用场景
组（不可见）	group;pointerEvents=0;	无边框、无连接
泳道（带标题）	swimlane;startSize=30;	显示标题栏，或容器本身需要连接
自定义容器	添加 container=1;pointerEvents=0;	将任意图形用作容器

<mxCell id="vpc" value="VPC" style="swimlane;startSize=24;fillColor=#dae8fc;strokeColor=#6c8ebf;html=1;" vertex="1" parent="1">
  <mxGeometry x="0" y="0" width="720" height="360" as="geometry"/>
</mxCell>
<mxCell id="az1" value="AZ us-east-1a" style="swimlane;startSize=24;fillColor=#fff2cc;strokeColor=#d6b656;html=1;" vertex="1" parent="vpc">
  <mxGeometry x="20" y="36" width="320" height="300" as="geometry"/>
</mxCell>
<mxCell id="web1" value="web-1" style="rounded=1;whiteSpace=wrap;html=1;" vertex="1" parent="az1">
  <mxGeometry x="30" y="40" width="120" height="60" as="geometry"/>
</mxCell>

规则： 子元素的坐标相对于父元素。不同容器中的单元格之间的边必须设置 parent="1"（否则边会绘制在容器内部并被裁切）。除非容器本身必须可连接（此时由 swimlane 处理），否则每个容器都要设置 pointerEvents=0;。

分层架构（从上到下）与从左到右的流程

• 分层（TB）： 用户/客户端 → API/接口 → 业务逻辑 → 数据/存储。每一层使用一个泳道或圆角容器；组件放在其中；箭头表示流程；添加图例；添加元数据页脚。
• 从左到右（LR）： Source → Process → Target。使用 postLayout:"elk" + direction:"horizontal"（MCP），或使用固定网格从左到右排列各列。

完整的 XML 示例（包括分层服务架构、带事件总线的微服务、客户端/API/数据库，以及 C4-lite 上下文图），请参阅 references/architecture-patterns.md。

配色方案（语义化）

使用协调的填充色/描边色组合。出现 3 种或更多角色时，自动生成图例（参见 references/style-guide.md）。

角色	fillColor	strokeColor
服务 / 客户端	#dae8fc	#6c8ebf
成功 / 数据库	#d5e8d4	#82b366
队列 / 决策	#fff2cc	#d6b656
网关 / API	#ffe6cc	#d79b00
错误 / 警报	#f8cecc	#b85450
外部 / 中性	#f5f5f5	#666666
安全 / 身份验证	#e1d5e5	#9673a6

云服务提供商图标

对于 AWS/Azure/GCP/Cisco/K8s，优先使用官方图标。使用 MCP 时，调用 search_shapes 并粘贴返回的 style。手工编写的速查表（AWS shape=mxgraph.aws4.resourceIcon;resIcon=…、Azure image=img/lib/azure2/…svg、GCP 路径）见 references/cloud-icons.md。

HTML 标签、深色模式、标签、图层、元数据

• 始终为每个单元格样式添加 html=1 — 纯文本不受影响，但只有添加该属性，HTML（<b>、<br>、<font>）才会渲染。
• 换行：使用 
（无论是否设置 html=1 都有效），或 <br>（需要 html=1）。切勿使用 \n。
• 对属性值进行 XML 转义：& < > "。
• 深色模式： 在 <mxGraphModel> 上设置 adaptiveColors="auto"；strokeColor/fillColor/fontColor="default" 会自动适配。仅当反转效果不正确时才使用 light-dark(light,dark)。
• 标签（用于跨领域筛选）：将单元格包装在 <object id=… tags="critical v2"> 中；label 会替换 value。
• 图层（切换可见性）：使用不带 vertex/edge 的 mxCell parent="0"。
• 元数据 + 占位符： 使用 <object … component="X" status="Active" placeholders="1">，并设置 label="%component% — %status%"。

严重提示：XML 格式必须正确

• 切勿在图表输出中包含 XML 注释（``） — 它们会浪费令牌，还可能导致解析错误。
• 转义属性值中的特殊字符；始终使用唯一的 id。
• 交付前进行验证：python3 scripts/validate_drawio.py docs/architecture/diagram.drawio。

工作流（推荐）

1. 澄清（信息缺失时提 1–3 个问题）：图表类型、输出模式（在 MCP 中打开、文件 + CLI 或图像）、范围/保真度、具体技术。
2. 配置 MCP（如尚未配置，参见路径 A.1 / helper）——或解析 draw.io CLI 二进制文件（路径 B）。
3. 规划形状、关系、布局（LR/TB）、分组（层级/容器）和图标需求。
4. 编写 XML，并遵循上述规则（或为标准类型的图表编写 Mermaid）。
5. 交付：
   • MCP → 调用 open_drawio_xml/_mermaid/_csv。
   • CLI → 将源文件 .drawio 写入 docs/architecture/<diagram-name>.drawio，然后导出 PNG/SVG/PDF 到同一文件夹，可选择进行视觉自检。
6. 通过有针对性的 XML 编辑（更改 fillColor、移动 x/y、添加/删除节点或边）反复调整，直到获得认可。

常见错误

症状	修复方法
边未渲染	边单元格采用自闭合形式；添加 <mxGeometry relative="1" as="geometry" />
Vision API 返回 400“无法处理图像”	导出时使用了 -e；重新导出预览时不要使用 -e。（-e 生成的 PNG 中 IEND 被截断——运行修复）
连线穿过方框	设置 routing:"libavoid"（MCP），或添加路径点/增大间距
显示空白方框而不是图标	shape=mxgraph.* 名称错误——使用 search_shapes / references/cloud-icons.md
多条边堆叠在一个节点上	将 exitX/exitY/entryX/entryY 分散到该节点的不同侧
HTML 显示为纯文本	样式中缺少 html=1
嵌套容器交叉时被裁切	不同容器之间的边需要设置 parent="1"
CJK/URL 打开时报“URI 格式错误”	浏览器回退方案必须对 XML 使用 encodeURIComponent（helper 会处理）

参考资料（此技能）

• architecture — 统筹技能，负责 docs/architecture/，并将图表工作交由此引擎处理（协调器调用 /architecture，后者将可编辑的 .drawio 交付内容委派给此引擎）
• references/mcp-config.md — 各平台的准确 MCP 配置 JSON，以及自托管、无头/CLI 回退方案、自动化设置和验证步骤
• references/mcp-tools-reference.md — 完整的 MCP 工具参考，包含参数和示例（en）/ mcp-tools-reference.pt-br.md（pt-BR）
• references/usage-guide.md — 配置完成后如何使用此技能（en）/ usage-guide.pt-br.md（pt-BR）
• references/usage-examples.md — 端到端使用示例（en）/ usage-examples.pt-br.md（pt-BR）
• references/architecture-patterns.md — 分层 / 微服务 / 客户端-API-DB / C4-lite 的完整 XML 示例
• references/cloud-icons.md — AWS / Azure / GCP 图标速查表
• references/style-guide.md — 配色方案、排版、效果、图例生成
• scripts/setup_drawio_mcp.py — 检测平台 + 写入 MCP 配置 / 生成查看器 URL
• scripts/validate_drawio.py — XML 格式检查 + 结构校验 + IEND 修复

外部参考资料（分析过的来源）

• draw.io MCP 文档：https://www.drawio.com/docs/manual/generate/drawio-mcp-server/
• 供应商代码仓库（4 种集成模式 + XML 参考）：https://github.com/jgraph/drawio-mcp
• MCP 工具服务器 README（配置块）：https://github.com/jgraph/drawio-mcp/blob/main/mcp-tool-server/README.md
• XML 参考（权威来源）：https://github.com/jgraph/drawio-mcp/blob/main/shared/xml-reference.md
• 样式参考：https://github.com/jgraph/drawio-mcp/blob/main/shared/style-reference.md
• 技能（编写）：https://github.com/Agents365-ai/drawio-skill
• 技能（编写）：https://github.com/scarr05/claude-skills-pub
• 工作流文章：https://dev.to/rushier/how-to-use-claude-ai-drawio-to-create-architecture-diagrams-for-projects-17i1