drawio-diagram

Draw.io 网络图

使用以下两种方式生成网络图：

1. 原生文件模式 — 在磁盘上生成 .drawio XML 文件，可选通过 draw.io 桌面版 CLI（官方 jgraph skill-cli）导出为 PNG/SVG/PDF
2. 浏览器模式 — 通过 @drawio/mcp MCP 服务，在 Draw.io 浏览器编辑器中打开图表（输入格式可以是 Mermaid、XML 或 CSV）

---

安装说明：原生注册和文档中所述的 MCP_CALL 调用共用已安装的组件启动器。首次使用前，请检查 readiness.json；发现失败不代表设备状态有问题。现有的写入审批仍然适用。

模式 1：生成原生文件（官方 Skill-CLI）

直接生成原生 .drawio 文件。还可选择导出为 PNG、SVG 或 PDF，并在文件中嵌入图表 XML（这样导出的文件在 draw.io 中仍可编辑）。

如何创建图表

1. 生成 draw.io XML，使用 mxGraphModel 格式表示所需图表
2. 使用 Write 工具将 XML 写入当前工作目录中的 .drawio 文件
3. 如果用户要求导出格式（png、svg、pdf），使用 draw.io CLI 和 --embed-diagram 导出，然后删除源 .drawio 文件
4. 打开结果 — 如果已导出，则打开导出的文件；否则打开 .drawio 文件

选择输出格式

查看用户的请求，确认其格式偏好：

• /drawio create a flowchart → flowchart.drawio
• /drawio png flowchart for login → login-flow.drawio.png
• /drawio svg: ER diagram → er-diagram.drawio.svg
• /drawio pdf architecture overview → architecture-overview.drawio.pdf

如果未提及格式，则写入 .drawio 文件并打开。用户之后可以要求导出。

支持的导出格式

格式	嵌入 XML	备注
png	是（-e）	随处可查看，可在 draw.io 中编辑
svg	是（-e）	可缩放，可在 draw.io 中编辑
pdf	是（-e）	可打印，可在 draw.io 中编辑
jpg	否	有损格式，不支持嵌入 XML

PNG、SVG 和 PDF 均支持 --embed-diagram — 导出的文件包含完整的图表 XML，因此在 draw.io 中打开后可恢复可编辑的图表。

draw.io CLI

draw.io 桌面应用包含用于导出的命令行界面。

查找 CLI

先尝试 drawio（如果已在 PATH 中则可用），然后再使用特定于平台的路径：

• macOS：/Applications/draw.io.app/Contents/MacOS/draw.io
• Linux：drawio（通常通过 snap/apt/flatpak 安装在 PATH 中）
• Windows："C:\Program Files\draw.io\draw.io.exe"

回退到其他路径之前，使用 which drawio（Windows 上使用 where drawio）检查它是否在 PATH 中。

导出命令

drawio -x -f <format> -e -b 10 -o <output> <input.drawio>

关键标志：

• -x / --export：导出模式
• -f / --format：输出格式（png、svg、pdf、jpg）
• -e / --embed-diagram：在输出文件中嵌入图表 XML（仅 PNG、SVG、PDF）
• -o / --output：输出文件路径
• -b / --border：图表周围的边框宽度（默认值：0）
• -t / --transparent：透明背景（仅 PNG）
• -s / --scale：缩放图表尺寸
• --width / --height：适配到指定尺寸（保持纵横比）
• -a / --all-pages：导出所有页面（仅 PDF）
• -p / --page-index：选择特定页面（从 1 开始计数）

打开结果

• macOS：open <file>
• Linux：xdg-open <file>
• Windows：start <file>

文件命名

• 根据图表内容使用描述性文件名（例如 login-flow、database-schema）
• 多词名称使用小写字母并以连字符分隔
• 导出时使用双重扩展名：name.drawio.png、name.drawio.svg、name.drawio.pdf — 这表示文件包含嵌入的图表 XML
• 导出成功后，删除中间的 .drawio 文件 — 导出的文件已包含完整图表

---

模式 2：通过 MCP 服务使用浏览器编辑器

通过 @drawio/mcp MCP 服务，直接在 Draw.io 浏览器编辑器中打开图表。支持三种输入格式。

Mermaid 图表（最适合快速绘制拓扑图）

python3 $MCP_CALL "npx -y @drawio/mcp" open_drawio_mermaid '{"content":"graph TD\n  A --> B"}'

XML 图表（最适合绘制定位精确、样式丰富的详细图表）

python3 $MCP_CALL "npx -y @drawio/mcp" open_drawio_xml '{"content":"<mxGraphModel>...</mxGraphModel>"}'

CSV 图表（最适合绘制设备清单）

python3 $MCP_CALL "npx -y @drawio/mcp" open_drawio_csv '{"content":"## label: %name%\nname,refs\nA,B\nB,C"}'

这 3 种工具都接受可选参数 "lightbox": true，用于只读视图；以及 "dark": "auto"|"true"|"false"，用于深色模式。

工具会返回一个 Draw.io URL。直接分享即可——图表会在浏览器编辑器中打开，可在其中编辑、导出或保存。

---

XML 格式参考

.drawio 文件是原生 mxGraphModel XML。始终直接生成 XML——Mermaid 和 CSV 格式需要在服务端转换，且无法保存为原生文件。

基本结构

每个图表都必须采用以下结构：

<mxGraphModel>
  <root>
    <mxCell id="0"/>
    <mxCell id="1" parent="0"/>
    
  </root>
</mxGraphModel>

• 单元格 id="0" 是根图层
• 单元格 id="1" 是默认父图层
• 除非使用多个图层，否则所有图表元素都使用 parent="1"

常用样式

圆角矩形：

<mxCell id="2" value="Label" style="rounded=1;whiteSpace=wrap;" vertex="1" parent="1">
  <mxGeometry x="100" y="100" width="120" height="60" as="geometry"/>
</mxCell>

菱形（决策）：

<mxCell id="3" value="Condition?" style="rhombus;whiteSpace=wrap;" vertex="1" parent="1">
  <mxGeometry x="100" y="200" width="120" height="80" as="geometry"/>
</mxCell>

箭头（边）：

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

带标签的箭头：

<mxCell id="5" value="Yes" style="edgeStyle=orthogonalEdgeStyle;" edge="1" source="3" target="6" parent="1">
  <mxGeometry relative="1" as="geometry"/>
</mxCell>

实用样式属性

属性	值	用途
rounded=1	0 或 1	圆角
whiteSpace=wrap	wrap	文本换行
fillColor=#dae8fc	十六进制颜色	背景颜色
strokeColor=#6c8ebf	十六进制颜色	边框颜色
fontColor=#333333	十六进制颜色	文本颜色
shape=cylinder3	形状名称	数据库圆柱体
shape=mxgraph.flowchart.document	形状名称	文档形状
ellipse	样式关键字	圆形／椭圆
rhombus	样式关键字	菱形
edgeStyle=orthogonalEdgeStyle	样式关键字	直角连接线
edgeStyle=elbowEdgeStyle	样式关键字	肘形连接线
dashed=1	0 或 1	虚线
swimlane	样式关键字	泳道容器

---

网络工程图表类型

1. 物理拓扑图

显示设备、物理链路、接口名称、IP 地址和链路速度。

python3 $MCP_CALL "npx -y @drawio/mcp" open_drawio_mermaid '{"content":"graph TD\n  R1[\"R1\\nCore Router\\n10.255.255.1\"]\n  R2[\"R2\\nCore Router\\n10.255.255.2\"]\n  SW1[\"SW1\\nDist Switch\\n10.255.255.3\"]\n  R1 -->|\"Gi0/0 -- Gi0/0\\n10.1.1.0/30\"| R2\n  R1 -->|\"Gi0/1 -- Gi0/1\\n10.1.2.0/30\"| SW1\n  R2 -->|\"Gi0/1 -- Gi0/1\\n10.1.3.0/30\"| SW1"}'

2. 逻辑拓扑图

显示路由协议关系、区域、AS 编号和 VRF。

python3 $MCP_CALL "npx -y @drawio/mcp" open_drawio_mermaid '{"content":"graph TD\n  subgraph \"OSPF Area 0\"\n    R1[\"R1 ABR\"]\n    R2[\"R2 ABR\"]\n  end\n  subgraph \"OSPF Area 1\"\n    R3[\"R3\"]\n  end\n  R1 --- R2\n  R1 --- R3"}'

3. 安全区域图

显示防火墙、DMZ、信任边界和 ACL 强制执行点。

python3 $MCP_CALL "npx -y @drawio/mcp" open_drawio_mermaid '{"content":"graph LR\n  subgraph \"Untrusted\"\n    INET((Internet))\n  end\n  subgraph \"DMZ\"\n    WEB[\"Web Server\"]\n  end\n  subgraph \"Trusted\"\n    CORE[\"Core Switch\"]\n  end\n  INET --> FW[\"Firewall\"]\n  FW --> WEB\n  FW --> CORE"}'

---

重要：XML 格式正确性

• 切勿在 XML 注释中使用双连字符（--）。 根据 XML 规范，`` 内的 -- 属于非法内容，会导致解析错误。请使用单连字符或改写措辞。
• 对属性值中的特殊字符进行转义：&、<、>、"
• 始终为每个 mxCell 使用唯一的 id 值

---

何时使用各模式

场景	模式	原因
生成用于版本控制的 .drawio 文件	原生文件	在磁盘上生成实际文件
导出 PNG/SVG/PDF 用于文档	原生文件	使用 CLI 导出并嵌入 XML
根据发现数据快速预览拓扑	浏览器	在浏览器中即时可视化
基于 CSV 的清单图表	浏览器	只有通过 MCP 才能使用 CSV 格式
Mermaid 语法图表	浏览器	只有通过 MCP 才能转换 Mermaid
离线／隔离网络环境	原生文件	无需网络
分享图表链接	浏览器	返回可分享的 URL

与其他技能集成

• 使用 pyats-topology 发现网络，然后根据数据生成图表
• 使用 netbox-reconcile 根据协调状态（已记录／未记录／缺失）为链路着色
• 使用 markmap-viz 绘制层次视图，并使用 Draw.io 绘制拓扑视图
• 使用 aci-fabric-audit 数据生成 ACI 架构拓扑图
• 使用 gait-session-tracking 记录图表生成过程及其源数据引用