drawio

Draw.io 图表技能

将 draw.io 图表生成为原生 .drawio 文件。每个图表既可以用 Mermaid 编写（简洁文本，由 draw.io 桌面 CLI 转换并自动布局），也可以直接编写 draw.io XML。还可以选择使用 ELK 自动布局以 XML 编写的图表，将图表 XML 嵌入 PNG/SVG/PDF 导出文件（这样导出的文件仍可在 draw.io 中编辑），或生成可直接在 draw.io 编辑器中打开图表的浏览器 URL。

优先使用内嵌查看器。 此技能会写入文件，并通过 shell 命令打开文件。如果在可内嵌显示图表的聊天环境（VS Code 或 Cursor 自带的聊天、Claude.ai、ChatGPT）中，draw.io MCP 服务的 create_diagram 工具可用，且用户没有要求提供 .drawio 文件、导出文件或 URL，则改用 create_diagram：图表会显示在对话中，无需文件或 shell 命令。Claude Code、Codex 和 Copilot CLI 不会内嵌显示图表，即使是在其 VS Code 或 JetBrains 扩展中也不行：在那里，create_diagram 只会返回链接，因此请使用此技能。

编写方式：Mermaid 还是 XML？

桌面 CLI 会将 Mermaid 转换为原生 .drawio 文件并自动布局，其可靠性远高于手动在 XML 中定位单元格。

编写方式	适用场景	需要桌面 CLI？
Mermaid	流程图、时序图、类图、状态图、ER 图、甘特图、思维导图、时间线、用户旅程图、象限图、C4、Git 图、饼图及其他标准类型	是——用于转换为 .drawio
XML	自定义样式、精确定位／手动定位、特定形状库（AWS、Azure、网络、UML 细节……），或未安装桌面 CLI 时	否（可选的 ELK --layout 需要 CLI）

• 桌面 CLI 可用且请求属于上述标准类型时，优先使用 Mermaid。
• 需要精确控制时使用 XML，也可将其用作通用备用方案：XML 无需 CLI，因此在未安装桌面应用时是唯一选项（交付 .drawio 文件或 url）。对于 XML，可以让 CLI 应用 ELK 自动布局，而不是自行计算坐标。

如果不确定是否已安装桌面 CLI，请先检测（参见查找 CLI）。

流程

每个图表都会先生成原生 .drawio 文件，然后再以请求的输出格式交付，无论使用 Mermaid 还是 XML 编写。

1. 编写 → .drawio
   • Mermaid：将 Mermaid 写入 .mmd 文件，然后使用 CLI 转换：

     drawio -x -f xml -o diagram.drawio diagram.mmd
     

     之后删除 .mmd；.drawio 才是最终产物。
   • XML：将 mxGraphModel XML 写入 diagram.drawio（参见 XML 格式），然后对其运行修复步骤。还可选择应用 ELK 布局。
2. 交付（两种来源的处理方式相同）：
   • （未指定格式） → 保留 diagram.drawio 并打开。
   • png / svg / pdf → 从 .drawio 导出并嵌入 XML，然后删除源 .drawio：

     drawio -x -f png -e -b 10 -o diagram.drawio.png diagram.drawio
     

   • url → 根据 .drawio XML 构建浏览器 URL 并打开，同时将 .drawio 保留为本地副本（参见浏览器 URL 输出）。
3. 打开结果——导出的文件、URL 或 .drawio（参见打开结果）。如果打开命令失败，请打印绝对路径（或 URL），方便用户手动打开。

始终先将 Mermaid 转换为 .drawio，然后再导出——在当前版本的 draw.io Desktop 中，直接将 Mermaid 导出为 PNG 并使用 -e 会出错（嵌入 XML 的步骤会崩溃）；两步流程可靠，并能生成可编辑的嵌入内容。

如果用户要求使用 Mermaid，但桌面 CLI 不可用，请用 XML 编写同一个图表。

XML 的 ELK 布局

CLI 的 --layout 步骤会自动为 XML 编写的图表定位，使用与编辑器的 Arrange ▸ Layout 菜单和 draw.io MCP 应用服务器相同的 ELK 布局。生成单元格时使用近似位置（甚至 0,0），并确保图形的结构——节点和边——正确。流程图使用 verticalFlow / horizontalFlow，网络图使用 organic。Mermaid 编写的图表已经完成布局——不要添加 --layout。

写入文件后在原处进行布局（支持读取和覆盖同一路径），也可以在一次调用中将布局与导出结合：

drawio -x -f xml --layout verticalFlow -o diagram.drawio diagram.drawio
drawio -x -f png -e -b 10 --layout verticalFlow -o diagram.drawio.png diagram.drawio

布局预设

名称	布局
verticalFlow	分层，自上而下——流程图、流水线
horizontalFlow	分层，从左到右
verticalTree	树形，自上而下——层级结构、组织架构图
horizontalTree	树形，从左到右
radialTree	径向树
organic	力导向——网络、类似思维导图的图形

自定义布局 JSON

如需更精细的控制，请传入一个 JSON 数组（以 [ 开头），而不是预设名称；格式与编辑器的自定义布局对话框相同：

drawio -x -f xml --layout '[{"layout":"elkLayered","config":{"elk.direction":"RIGHT"}}]' -o diagram.drawio diagram.drawio

每个条目都是 {"layout": <algorithm>, "config": { … }}。算法：elkLayered、elkTree、elkRadial、elkOrganic、elkStress、elkBox。以 elk. 开头的配置项是 ELK 选项，例如 elk.direction（UP / DOWN / LEFT / RIGHT）、elk.spacing.nodeNode、elk.layered.spacing.nodeNodeBetweenLayers；edgeStyle（例如 orthogonal）和 corners（例如 rounded）用于控制连接线的渲染方式。

正交边路由

--layout libavoid 会让边绕过形状进行正交路由（Arrange ▸ Layout ▸ Orthogonal Routing），而不移动任何顶点。对于连接线穿过形状的手动定位 XML，请在原处运行此命令；对于流程图／树形布局预设则无需运行，因为这些预设已为边完成路由：

drawio -x -f xml --layout libavoid -o diagram.drawio diagram.drawio

Mermaid 语法参考

编写 Mermaid 时，请获取并遵循共享的 Mermaid 参考（包含所有受支持的图表类型以及流程图样式设置——style、classDef、linkStyle）：

https://raw.githubusercontent.com/jgraph/drawio-mcp/main/shared/mermaid-reference.md

图表标签的语言应与用户使用的语言一致。

选择输出格式

检查用户的请求，确认是否指定了格式。示例：

• /drawio:drawio create a flowchart → Mermaid → flowchart.drawio
• /drawio:drawio png flowchart for login → Mermaid → login-flow.drawio.png
• /drawio:drawio svg: ER diagram → Mermaid → er-diagram.drawio.svg
• /drawio:drawio pdf AWS architecture overview → XML（需要 AWS 形状）→ architecture-overview.drawio.pdf
• /drawio:drawio url flowchart for user login → 在浏览器中打开包含图表的 app.diagrams.net，并在本地保留 login-flow.drawio

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

PNG、SVG 和 PDF 使用 -e（--embed-diagram）导出：文件中包含完整的图表 XML，因此在 draw.io 中打开时可以恢复为可编辑图表。jpg 是有损格式，无法嵌入 XML。

浏览器 URL 输出

对于 url 格式，请将 .drawio 文件保留在磁盘上，使用 Node.js 内置的 zlib 压缩其中的 XML，生成 https://app.diagrams.net/#R... URL，并在默认浏览器中打开——查看图表不需要 draw.io Desktop。

生成 URL

运行以下 node -e 单行命令以读取 .drawio 文件并输出 URL（将 DIAGRAM.drawio 替换为实际文件名）：

URL=$(node -e '
const fs = require("fs");
const zlib = require("zlib");
const xml = fs.readFileSync(process.argv[1], "utf8");
const compressed = zlib.deflateRawSync(encodeURIComponent(xml)).toString("base64");
console.log("https://app.diagrams.net/?grid=0&pv=0&border=10&edit=_blank#R" + encodeURIComponent(compressed));
' "DIAGRAM.drawio")

这是 MCP Tool Server 的 XML 链接格式。对于 XML，请勿使用 #create= URL：draw.io 加载 XML 后会重写该哈希；当重写后的哈希与链接不一致时（Node 的 zlib 输出与 draw.io 的 pako 并非逐字节相同，因此确实会不一致），它会提示“所有更改都将丢失！”。

打开 URL

环境	命令
macOS	open "$URL"
Linux（原生）	xdg-open "$URL"
WSL2	写入临时 .url 文件，通过 cmd.exe 打开（见下文）
Windows（原生）	写入临时 .url 文件，通过 start 打开（见下文）

cmd.exe 的 start 命令会将 & 视为命令分隔符，并删除 # 之后的所有内容，而图表就位于此处，因此在 Windows 和 WSL2 上，应改为将 URL 放入 .url 快捷方式文件中。

WSL2：

TMPFILE=$(mktemp --suffix=.url)
printf '[InternetShortcut]\r\nURL=%s\r\n' "$URL" > "$TMPFILE"
cmd.exe /c start "" "$(wslpath -w "$TMPFILE")"

Windows（原生）：****不要使用 echo URL=%URL% 创建 .url 文件——& 字符（?grid=0&pv=0&...）会截断快捷方式，导致图表丢失。让 Node 写入文件，并且只打开文件路径，因为路径中不会包含 &：

TMPFILE=$(node -e '
const fs = require("fs");
const os = require("os");
const path = require("path");
const p = path.join(os.tmpdir(), "drawio.url");
fs.writeFileSync(p, "[InternetShortcut]\r\nURL=" + process.argv[1] + "\r\n");
process.stdout.write(p);
' "$URL")
cmd.exe /c start "" "$TMPFILE"

然后打印 URL 和本地文件，以便用户分享或重新编辑：

Opened in browser: <URL>
Local file: DIAGRAM.drawio

非常大的图表可能会超出浏览器的 URL 长度限制（根据浏览器不同，约为 32K–2MB）；此时请直接在本地打开 .drawio 文件。

draw.io CLI

draw.io 桌面应用的命令行界面可将 Mermaid 转换为 .drawio、应用 ELK 布局（--layout），并导出为 PNG/SVG/PDF。这三项功能都需要安装桌面应用。

定位 CLI

先检测环境，然后定位 CLI。在 Windows（原生和 WSL2）上，安装程序不会将 draw.io 添加到 PATH，且安装目录由用户选择，因此在判定 CLI 不存在之前，请按顺序完成整套备用查找流程。

WSL2（适用于 Linux 的 Windows 子系统）

当 /proc/version 包含 microsoft 或 WSL 时，即可判定为 WSL2：

grep -qi microsoft /proc/version 2>/dev/null && echo "WSL2"

在 WSL2 上，通过 /mnt/c/... 使用 Windows 版 draw.io Desktop 可执行文件：

DRAWIO_CMD="/mnt/c/Program Files/draw.io/draw.io.exe"

请用双引号括起路径，以确保 Program Files 中的空格保留在路径内。不要用反引号括起路径——在 bash 中反引号表示命令替换，会导致执行二进制文件，而不是保存其路径。

如果 draw.io 安装在非默认位置，请检查常见的其他路径：

# Default install path
"/mnt/c/Program Files/draw.io/draw.io.exe"

# Per-user install (if the above does not exist)
"/mnt/c/Users/$WIN_USER/AppData/Local/Programs/draw.io/draw.io.exe"

如果两处都不存在，则说明它安装在其他驱动器或自定义目录中——扫描其他已挂载的驱动器，然后查询注册表：

# Program Files on the other drives (D:, E:, …)
ls /mnt/*/Program\ Files/draw.io/draw.io.exe 2>/dev/null | head -1

# Registry — the installer records the directory the user picked
for REG_PATH in 'HKCU\Software\Microsoft\Windows\CurrentVersion\Uninstall' \
                'HKLM\Software\Microsoft\Windows\CurrentVersion\Uninstall' \
                'HKLM\Software\WOW6432Node\Microsoft\Windows\CurrentVersion\Uninstall'; do
  WIN_DIR=$(reg.exe query "$REG_PATH" /s /v InstallLocation 2>/dev/null |
            grep -i 'REG_SZ.*draw\.io' | head -1 |
            sed 's/.*REG_SZ[[:space:]]*//' | tr -d '\r')
  [ -n "$WIN_DIR" ] && DRAWIO_CMD="$(wslpath -u "${WIN_DIR%\\}")/draw.io.exe" && break
done

macOS 和 Linux

• Linux（原生）：drawio，通常通过 snap/apt/flatpak 添加到 PATH——使用 which drawio 确认
• macOS：此命令会按顺序查找 PATH 中的 drawio（Homebrew）、/Applications、用户目录下的 ~/Applications 和 Spotlight，并打印第一个找到的路径；如果 draw.io 不存在，则不输出任何内容：

{ command -v drawio; ls /Applications/draw.io.app/Contents/MacOS/draw.io ~/Applications/draw.io.app/Contents/MacOS/draw.io
  mdfind "kMDItemCFBundleIdentifier == 'com.jgraph.drawio.desktop'" | sed 's|$|/Contents/MacOS/draw.io|'; } 2>/dev/null | head -1

请调用 .app 内的二进制文件；在其外部的副本或符号链接会因 Unable to find helper app 而失效。

Windows（原生，非 WSL2）

请按顺序检查——PATH 条目缺失或安装在非 C: 驱动器上都很常见，并不代表 draw.io 不存在：

1. PATH：where.exe draw.io（注意其中的点——可执行文件名是 draw.io.exe，不是 drawio.exe）
2. 默认安装路径：先查 C:\Program Files\draw.io\draw.io.exe，再查用户级安装路径 %LOCALAPPDATA%\Programs\draw.io\draw.io.exe
3. 注册表中的卸载项，其中记录了用户选择的目录
4. 其他驱动器：查找 D:、E: 等驱动器上的 Program Files\draw.io\draw.io.exe

将以下内容保存为 find-drawio.ps1，即可一次性运行整套查找流程——它会打印找到的第一个可执行文件；如果确实没有安装 draw.io，则不会输出任何内容：

$c = @()
$c += (where.exe draw.io 2>$null)
$c += "$env:ProgramFiles\draw.io\draw.io.exe", "$env:LOCALAPPDATA\Programs\draw.io\draw.io.exe"
$c += Get-ItemProperty 'HKCU:\Software\Microsoft\Windows\CurrentVersion\Uninstall\*',
                       'HKLM:\Software\Microsoft\Windows\CurrentVersion\Uninstall\*',
                       'HKLM:\Software\WOW6432Node\Microsoft\Windows\CurrentVersion\Uninstall\*' -ErrorAction SilentlyContinue |
      Where-Object { $_.DisplayName -like '*draw.io*' } |
      ForEach-Object { if ($_.InstallLocation) { Join-Path $_.InstallLocation 'draw.io.exe' } else { ($_.DisplayIcon -split ',')[0] } }
$c += (Get-PSDrive -PSProvider FileSystem).Root | ForEach-Object { Join-Path $_ 'Program Files\draw.io\draw.io.exe' }
$c | Where-Object { $_ -and (Test-Path $_) } | Select-Object -First 1

在 bash 或 cmd shell 中，运行：

powershell.exe -NoProfile -ExecutionPolicy Bypass -File find-drawio.ps1

每次调用都要将结果路径括在引号中——路径几乎总是包含空格：

& "D:\Program Files\draw.io\draw.io.exe" -x -f xml -o diagram.drawio diagram.mmd

只有在所有步骤都没有找到结果后，才应判定 CLI 不存在，并改用 XML 编写方式，输出 .drawio / url。如果在 PATH 之外找到了它，请说明将其所在文件夹（例如 D:\Program Files\draw.io）添加到 PATH 后，下次即可直接找到。

导出命令

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

在 WSL2 上，调用 Windows 可执行文件，例如 "/mnt/c/Program Files/draw.io/draw.io.exe" -x -f png -e -b 10 -o "diagram.drawio.png" "diagram.drawio"。转换和布局命令见处理流程和 XML 的 ELK 布局。

主要标志：

• -x / --export：导出模式（也用于 Mermaid 转换和布局）
• -f / --format：输出格式（xml、png、svg、pdf、jpg）——使用 xml 可从 Mermaid 或布局生成 .drawio 文件
• --layout：写入输出前先运行布局——ELK 预设名称、libavoid 边路由，或自定义布局 JSON 数组
• --mermaid-image 1：将 Mermaid 转换为单个静态 SVG 图像单元格（Mermaid 源码仍保留在单元格中，以便重新编辑），而非可编辑图表——仅在用户明确要求不可编辑的图像单元格时使用
• -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 开始）
• --disable-gpu：跳过 GPU 初始化——当命令因 GPU process isn't usable 错误而退出时添加此标志（Windows 远程桌面会话、虚拟机、CI 运行器）；转换、布局或导出均不需要 GPU

打开结果

在 VS Code 中（也适用于 Cursor 或 Windsurf，只需将 code 替换为对应的 cursor / windsurf 命令），在聊天旁边的编辑器标签页中打开文件：安装 Draw.io Integration 扩展后，VS Code 会将 .drawio、.drawio.svg 和 .drawio.png 文件显示为可编辑图表。一个命令即可检查扩展是否已安装；若未安装，则回退到下方对应平台的命令（macOS 上使用 open）：

code --list-extensions 2>/dev/null | grep -qi '^hediet.vscode-drawio$' && code <file> || open <file>

PDF 和 url 模式始终使用对应平台的命令：

环境	命令
macOS	open <file>
Linux (native)	xdg-open <file>
WSL2	cmd.exe /c start "" "$(wslpath -w <file>)"
Windows	start <file>

在 WSL2 上，wslpath -w 会将路径转换为 Windows 路径，因为 cmd.exe 无法解析 /mnt/c/...；空字符串 "" 可避免 start 将文件名识别为窗口标题。

文件命名

• 使用能体现内容的描述性名称，全部小写并以连字符分隔（例如 login-flow、database-schema）
• 导出文件使用双扩展名——name.drawio.png、name.drawio.svg、name.drawio.pdf——以表明其中嵌入了图表 XML
• 对于 url 模式，保留 .drawio 文件（不要使用双扩展名）——URL 是用于查看或编辑的句柄，本地文件是持久副本

XML 格式

.drawio 文件是原生 mxGraphModel XML 格式，与 CLI 将 Mermaid 转换成的格式相同。

基本结构

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

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

• 单元格 id="0" 是根图层
• 单元格 id="1" 是默认父图层
• 除非使用多个图层，否则所有图表元素都使用 parent="1"
• 容器内的单元格使用 parent="<container_id>"，坐标相对于该容器
• 边属于同时包含两个端点的最内层容器——同一容器（任意嵌套深度）→ 该容器的 id；某一端位于所有容器之外 → parent="1"。自动布局会在边的父级坐标系中读取边的坐标，因此，将边放置在比其端点更外层的位置会导致布局位置错误

重要：XML 格式良好性

• 输出中绝不包含任何 XML 注释（``）。 严禁使用 XML 注释——它们会浪费令牌、可能导致解析错误，对图表 XML 毫无用处。
• 转义属性值中的特殊字符：&、<、>、"
• 为每个 mxCell 使用唯一的 id 值
• 每条边都需要一个子元素 <mxGeometry relative="1" as="geometry" />——自闭合的边 mxCell 无法渲染

修复步骤

将 XML 写入 .drawio 文件后，立即运行此步骤，然后再进行任何布局、导出或 URL 操作。它会修复导致 draw.io 拒绝图表的机械性疏漏：图表周围的文本（代码围栏、句子、多余的结束标签）、属性值中的 < 或多余的 &（未转义的 HTML 标签、“R&D”、 ），以及被写成独立父级的默认图层（<mxCell id="1" parent="1"/>，这会隐藏所有内容）。对于格式良好的文件，它不会做任何更改；并且只需要 Node.js（如果未安装 node，则跳过此步骤）。将 DIAGRAM.drawio 替换为实际文件名：

node -e '
const fs = require("fs");
const file = process.argv[1];
let xml = fs.readFileSync(file, "utf8");
const diagram = xml.match(/<mxfile[\s\S]*?<\/mxfile>|<mxGraphModel[\s\S]*?<\/mxGraphModel>/);
if (diagram && xml.trim() !== diagram[0]) xml = diagram[0];
xml = xml.replace(/="([^"]*)"/g, function(m, v)
{
  return "=\"" + v.replace(/</g, "&lt;").replace(/&(?!(?:amp|lt|gt|quot|apos|#[0-9]+|#x[0-9a-fA-F]+);)/g, "&amp;") + "\"";
});
xml = xml.replace(/<mxCell id="([^"]+)" parent="\1"\s*\/>/g, "<mxCell id=\"$1\" parent=\"0\"/>");
fs.writeFileSync(file, xml);
' "DIAGRAM.drawio"

XML 参考

编写 XML 之前，请获取并遵循精简版 XML 规则——骨架、顶点和边模板、标签、形状、布局网格、容器、泳道和边样式： https://raw.githubusercontent.com/jgraph/drawio-mcp/main/shared/xml-essentials.md

这些规则涵盖大多数图表。只有当图表需要图层、标签、元数据和占位符、表格、跨职能网格或深色模式颜色时，才同时获取完整的 XML 参考（其中介绍了 draw.io MCP 服务：对于它们的 search_shapes 工具，请使用下方的查找方法；对于 postLayout / routing，请使用 CLI 的 --layout）： https://raw.githubusercontent.com/jgraph/drawio-mcp/main/shared/xml-reference.md

形状和图标

当图表需要云、网络或品牌图标（AWS、Azure、GCP、Cisco、Kubernetes、GitHub、Slack 等）时，切勿猜测 mxgraph.* 名称：在此技能文件夹中的 scripts/find-shapes.js 里一次性查询（Node.js 18+，需要网络），每个图标查询一次，并按库缩小范围（aws4、azure2、cisco19）。它会搜索 draw.io 的形状库，然后搜索其图标服务，并输出 title width×height style 格式的行；请原样使用样式：

node <skill-folder>/scripts/find-shapes.js "aws4 lambda" "github" "slack"

故障排查

问题	原因	解决方案
找不到 draw.io CLI	未安装桌面应用，或其不在 PATH 中	按照查找 CLI中的说明操作；如果确实找不到，则以 XML 格式编写并提供 .drawio 文件或 url，并告知用户，安装 draw.io 桌面应用即可启用 Mermaid 转换、布局和图像导出
将 Mermaid 导出为 PNG 时崩溃	当前版本的 draw.io Desktop 无法直接使用 -e 将 .mmd 导出为 PNG	先将 Mermaid 转换为 .drawio（使用 -f xml），然后再导出 .drawio
Mermaid 生成的图表为空白	类型关键字拼写错误，或存在语法错误（节点 ID 无效、标签未加引号）	查看 Mermaid 参考；第一行非指令行中的关键字用于选择图表类型
布局不起作用或报错	预设名称未知、自定义 JSON 不是数组，或桌面版过旧，不支持 --layout / .mmd 输入	使用预设或以 [ 开头的 JSON 数组；如果桌面版较旧，则以 XML 格式编写并明确指定位置，同时告知用户，更新 draw.io Desktop 即可启用 Mermaid 转换和布局
导出生成空文件或损坏文件，或图表显示为空白	XML 无效，或缺少根单元格 id="0" 和 id="1"	执行修复步骤，并检查基本结构
转换、布局或导出时出现 GPU process isn't usable. Goodbye.	Electron 无法启动 GPU 进程，在 Windows 远程桌面会话、虚拟机和 CI 运行器中较为常见。此前打印的 os_crypt / Failed to decrypt 行与此无关	使用添加了 --disable-gpu 的同一命令重试；draw.io Desktop 自带的 --disable-acceleration 开关效果相同
url 模式下浏览器打开后图表为空白	cmd.exe 删除了 #R... 片段	在 Windows/WSL2 上使用 .url 文件解决方法（参见打开 URL）——切勿将 URL 直接传给 cmd.exe /c start