让 Codex 生成可维护的 Draw.io 图表：MCP、Skill 与 CLI 如何分工

让 AI 画一张图并不难。真正麻烦的是第二天：图已经被放进文章，文字也改过一轮，却没人知道它的可编辑源文件在哪里；想挪一个节点，只能在旧截图上重画。

让 Codex 调用 Draw.io，最先解决的是成图速度；图表能否在几个月后继续编辑，则取决于是否同时保留三种产物：对话中的即时预览、仓库里的可编辑源文件，以及交付给文章和文档的图片或 PDF。三者的用途和寿命不同，缺少任何一层，后续维护都会受到限制。

预览解决“现在怎么看”，.drawio 源文件解决“以后怎么改”，SVG、PNG 或 PDF 解决“怎样交付”。

先区分三种产物

同一句“请帮我画一张架构图”，可能隐含三种完全不同的需求：

需求	需要留下的产物	更适合的能力
立刻打开图看看结构是否正确	Draw.io Editor URL	MCP Tool Server
把图作为项目资产长期维护	.drawio XML	Skill + 文件工具
放进文章、幻灯片或 PDF	.drawio.svg、.drawio.png、PDF	Draw.io Desktop CLI

只完成第一层时，图可以在浏览器里打开，却未必已经成为仓库中的文件；只保留一张普通 PNG 时，展示没有问题，后续修改却会重新回到“从截图猜结构”的状态。

MCP 返回的编辑器链接很适合预览，但链接本身不是长期图表资产。

本文的示例图也按这套流程生成，仓库同时保留 .drawio 源文件 和带可编辑数据的 SVG 导出物。

MCP、Skill 与 CLI 分别负责什么

MCP、Skill 与 CLI 对应图表生命周期中的三个环节：工具接入、流程约束和文件导出。将它们分开理解，后续配置、排错和维护都会容易很多。

MCP：把外部图表能力接进 Codex

MCP 负责向 Codex 暴露 Draw.io 工具。按照 OpenAI 当前的 Codex MCP 文档，Codex 是 host，内部连接是 client，外部 Draw.io 服务则是 server；server 可以提供打开编辑器、转换 Mermaid、搜索图形库或读取多页文件等工具。

Draw.io 官方目前提供两类 MCP server：

• MCP App Server：在支持 MCP Apps 的宿主里内联显示交互式图表；使用托管端点时，图表数据会发送到该服务。
• MCP Tool Server：通过本地 stdio 运行 @drawio/mcp，把 XML、CSV 或 Mermaid 压缩进 Draw.io URL 的 hash，再在浏览器中打开编辑器。

是否能够在对话中直接内联渲染，取决于宿主是否支持 MCP Apps。对 Codex 来说，当前更明确、也更容易验证的接入方式，是使用标准 stdio Tool Server 打开完整 Draw.io 编辑器。

当前 @drawio/mcp 已从最早的三个打开工具扩展出更多能力：

工具	用途
open_drawio_xml	打开原生 Draw.io XML，可选 libavoid 障碍避让
open_drawio_mermaid	把 Mermaid 转成可编辑 Draw.io 图
open_drawio_csv	按 Draw.io CSV 规则生成组织图等图表
search_shapes	搜索云服务、网络、电气、BPMN 等图形库
list_pages / get_page / set_page	按页检查和修改本地多页 .drawio 文件

这些工具完成了能力接入。文件放在哪里、应该怎样命名、导出前检查什么，仍需要项目自己的工作流约束。

Skill：把一次调用变成稳定流程

Skill 负责规定方法：优先生成未压缩 XML，保存 .drawio 源文件，校验节点和连线，采用一致的文件名，并在需要时调用 Desktop CLI 导出。

MCP 给 Codex 一组“能做什么”的工具，Skill 则说明这些工具应当按什么顺序使用，什么结果才算完成。

这延续了 AI Agent 的 Skill 是什么 中的分工：工具接口提供能力，Skill 保存可复用的格式知识和工作流经验。用于 Draw.io 时，一份合适的 Skill 至少应约定：

1. 单页图优先生成简化的 <mxGraphModel>；需要多页或文件变量时再使用完整 <mxfile>。
2. 源文件保存为描述清晰的 kebab-case .drawio。
3. 交付前验证 XML、根节点、唯一 ID、边的几何信息和 source/target 引用。
4. 导出图片时嵌入 diagram data，让导出物仍能回到 Draw.io 编辑。
5. Desktop CLI 不可用时，保留已经生成的源文件，并明确说明尚未完成导出，避免用不可编辑截图代替源文件。

Desktop CLI：把源文件变成可交付资产

Draw.io Desktop 提供导出命令行。它适合把仓库中的 .drawio 转成 SVG、PNG 或 PDF，而不需要人工重复点击导出对话框：

& "<draw.io.exe>" -x -f svg -e -b 10 `
  -o system-context.drawio.svg system-context.drawio

其中 -e / --embed-diagram 会把可编辑 XML 嵌入支持的导出文件。双扩展名属于命名约定，用于提醒维护者：system-context.drawio.svg 除了用于展示，还携带可恢复编辑的图表数据。

把 .drawio 视为事实来源，把 SVG、PNG 和 PDF 视为可重复生成的交付物。

Mermaid 和 Draw.io 怎么选

本站已经使用 Mermaid 在 Markdown 中表达流程。Draw.io 适合补充 Mermaid 难以处理的图形库、精细布局和人工编辑场景，两者应根据图表的维护方式分别使用。

判断维度	Mermaid	Draw.io
与正文共同编辑	很适合	需要独立文件
Git diff 可读性	较好	XML 较冗长
自动布局	强，适合快速成图	可自动，也适合手动微调
图标库和复杂排版	有限	更丰富
非代码读者继续编辑	门槛较高	图形界面更自然
正式架构图长期维护	视复杂度而定	更适合复杂资产

结构简单、贴近正文、经常随文字修改，用 Mermaid；需要图形库、精细布局或长期人工维护，用 Draw.io。

还可以先用 Mermaid 快速验证节点与关系，再通过 open_drawio_mermaid 转进 Draw.io 精修。转换为可编辑 shapes 后，后续修改的事实来源通常已经变成 Draw.io XML。此时若继续同时维护 Mermaid 文本，两个版本很容易出现结构偏差，因此应明确其中一个为事实来源。

在 Codex 中接入 Tool Server

可以通过 Codex CLI 注册 stdio server：

codex mcp add drawio -- npx -y @drawio/mcp

也可以在 ~/.codex/config.toml 或受信任项目的 .codex/config.toml 中显式配置：

[mcp_servers.drawio]
command = "npx"
args = ["-y", "@drawio/mcp"]
startup_timeout_sec = 30

Codex App 也可以通过 Settings > MCP servers > Add server 添加 STDIO 服务。保存后需要选择 Restart；在 CLI 或 App 中，可以用 /mcp 检查服务和工具是否已经出现。

一项最小验证任务可以写成：

使用 open_drawio_mermaid 打开一个包含登录、鉴权和回调的 OAuth2 流程图。

验证时应检查三个结果：浏览器确实打开 Draw.io，节点和连线完整，图表可以继续编辑。只看到“工具调用完成”无法证明编辑器端已经正确接收数据。

推荐的长期工作流

长期维护时，流程应从源文件开始：

flowchart LR
  Need[明确图表用途] --> Draft[Codex 生成未压缩 XML]
  Draft --> Validate[Skill 校验结构和命名]
  Validate --> Source[保存 .drawio 源文件]
  Source --> Preview[MCP 打开 Draw.io 预览]
  Preview --> Refine[人工微调]
  Refine --> Source
  Source --> Export[Desktop CLI 导出]
  Export --> Deliver[文章 / 文档 / 幻灯片]
  Source --> Git[Git 版本控制]

这条链路中，即使 MCP 被临时禁用，或 Desktop 暂时不可用，.drawio 源文件仍然可以继续进入版本控制。若只留下编辑器 URL 或普通 PNG，图表能否继续维护，就会取决于某次浏览器会话和一张无法还原结构的图片。

对于代码仓库，可以采用这样的文件组织：

docs/diagrams/
  system-context.drawio
  system-context.drawio.svg

提交时同时检查源文件和导出物。源文件便于继续编辑，SVG 方便代码评审和文档直接引用；如果导出命令稳定，还可以在 CI 中检查两者是否同步。

文件格式为什么值得了解一点

.drawio 使用结构化 XML。完整文件通常由 <mxfile>、<diagram> 和 <mxGraphModel> 组成；对于单页 AI 生成图，Draw.io 官方建议直接生成层级更少的 <mxGraphModel>，编辑器打开时会自动补齐外层结构。

最小骨架包含两个必要 cell：

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

生成时还应确保：ID 唯一，图形使用 vertex="1"，连线使用 edge="1"，边包含相对几何信息，属性中的特殊字符经过 XML 转义。AI 阶段优先保留未压缩 XML，因为它更容易检查、修复和比较。

日常使用无需手写整份 XML。了解这些结构，主要用于处理图表无法打开、连线丢失或模型只输出半截内容等问题；结构已知后，排查范围可以迅速缩小到根节点、cell ID、几何信息和连接引用。

网络与数据边界

不同接入方式的数据路径并不相同：

• 使用托管 MCP App Server 时，图表会随 MCP 请求发送到该服务；严格数据环境可以选择自托管。
• 本地 @drawio/mcp Tool Server 把内容放进 URL hash。浏览器不会把 hash fragment 发送给网页服务器，但仍需要加载 Draw.io 网页应用。
• 本地 Skill 和 Desktop CLI 可以把源文件生成、校验与导出留在本机。
• search_shapes 在 npm 包默认安装下会首次从 CDN 获取形状索引，因此首次使用仍会访问外部网络。

对于访问外部资源不稳定或图表内容敏感的环境，应优先保存本地源文件，并评估 DRAWIO_BASE_URL 自托管配置。工具进程运行在本地，只能说明 MCP server 的执行位置，无法证明网页应用、形状索引和其他依赖均处于离线状态。

出现 Transport closed 时查什么

stdio MCP server 使用标准输入输出传递 JSON-RPC。普通调试日志一旦写进 stdout，client 就可能把日志当成协议消息解析，最终表现为 Transport closed、JSON 解析错误或服务突然断开。

stdio server 的 stdout 只应承载协议消息；日志应写入 stderr 或保持静默。

当前官方 @drawio/mcp 已使用 console.error 输出启动信息，源笔记中针对旧版 postprocess.js 的手工补丁已经失去通用性。遇到问题时，可以按以下顺序排查：

1. 用 /mcp 或 codex mcp list 确认服务是否加载。
2. 在终端运行 npx -y @drawio/mcp --version，确认包能启动。
3. 检查 Node.js、npm cache、网络权限和 startup_timeout_sec。
4. 完整重启 Codex 或对应扩展，再在新任务中验证。
5. 查看 server 的 stderr，不要在同一条已断开的 transport 上反复重试。
6. 仍无法恢复时，先生成本地 .drawio，再用 Desktop CLI 导出，避免故障阻断源文件交付。

MCP 提供了方便的编辑入口，图表源文件仍应独立保存在仓库中。

结语

将 Draw.io 接入 Codex 后，仓库中至少应保留 .drawio 源文件。MCP 是否在线、桌面客户端是否可用，都不会影响图表继续维护；需要发布时，再从同一源文件生成 SVG、PNG 或 PDF，并由 Git 记录源文件与导出物的变化。

继续阅读：Codex 操作 Obsidian 的能力分层解释 MCP、Skills 与 CLI 的通用职责边界，AI Agent 的 Skill 是什么则进一步讨论如何把重复流程沉淀成可发现、可复用的能力。

参考资料

• OpenAI：Model Context Protocol
• OpenAI：Agent Skills
• draw.io：Generate and validate draw.io diagrams with AI
• jgraph/drawio-mcp
• Draw.io MCP Tool Server
• draw.io：Supported export formats