Codex + Draw.io MCP：AI自动生成可编辑架构图实战

架构图这件事画过的人都懂那种痛。需求评审前夜白板上画了三版拍照存下来第二天打开绘图工具准备重画发现连线怎么摆都不对图层怎么调都乱最后干脆截图凑合交差。我做了七八年后端和系统设计画过的架构图没有一千也有八百张真正让我觉得这张图值得存下来复用的不超过两成。剩下的都是画完就扔、扔了又要重画的消耗品。这两年情况有了变化。大模型能读懂代码结构、能理解模块关系之后我开始尝试让 AI 直接生成架构图的描述文件再交给绘图工具渲染。折腾了一圈最后稳定下来的组合是Codex 类代码智能体 Draw.io 的 MCP 服务。核心思路很朴素让 AI 负责想清楚结构让 Draw.io 负责画得好看中间用 MCP 协议把两边接起来。这套东西解决的不是画图好不好看的问题而是从想法到一张结构正确、可编辑、可迭代的图之间那段最耗人的翻译工作。适合谁看如果你是要频繁输出架构图的后端、运维、技术负责人或者单纯被画图折磨过的开发者这篇内容应该能帮你省下不少时间。1. 整体方案设计与选型思路拆解1.1 为什么是AI 生成描述 工具渲染而不是AI 直接出图先说清楚一个容易走偏的点。很多人第一反应是让 AI 直接生成一张 PNG 或者 SVG 图片看起来一步到位实际上是个坑。图片是死的改一个模块名字要重新生成整张图布局稍微不满意就得推倒重来而且 AI 生成的图片里文字经常糊成一团中英文混排更是灾难。我最终选择的路子是AI 输出结构化的图形描述绘图工具负责渲染。Draw.io 的原生文件格式本质上是 XML里面用mxCell节点描述每个图形、每条连线、每个标签的位置和样式。这个格式的好处是结构清晰、可读可改、完全可编辑。AI 只要生成合法的 XMLDraw.io 打开就是一张能继续拖拽调整的图。这个选择背后有三层考量。第一层是可迭代性XML 是文本改一个属性就是改一行字比重新生成图片靠谱得多。第二层是结构正确性AI 擅长的是理解服务 A 调用服务 B、B 依赖数据库 C这种关系把它翻译成节点和边是它的强项而让它去算像素坐标、避让重叠反而是弱项——所以布局这件事交给 Draw.io 的自动布局或者人工微调更合理。第三层是协作友好XML 文件能进版本库能 diff能 code review团队里谁改了哪根线一目了然这是图片格式做不到的。至于为什么用 MCP 而不是直接让 AI 吐 XML 文本这里有个实操层面的关键区别。直接吐 XMLAI 很容易在长文档里漏闭合标签、属性拼错、ID 重复生成出来的文件打不开。MCP 的价值在于它把生成图形这件事封装成了工具调用AI 不需要一次性输出几千行 XML而是通过调用create_node、create_edge这样的工具一步步把图搭起来每一步都有服务端校验出错能立刻发现并修正。这就像让一个新手直接手写 HTML 容易崩但给他一个可视化编辑器点按钮就稳得多。1.2 MCP 在这套链路里到底扮演什么角色MCP 全称是 Model Context Protocol你可以把它理解成 AI 和外部工具之间的标准插座。以前要让 AI 操作某个软件得为每个软件单独写适配代码接口五花八门。MCP 把这个事情标准化了工具方实现一个 MCP Server暴露一组能力比如创建矩形添加连线导出文件AI 侧作为 Client 去发现并调用这些能力。放到架构图这个场景里Draw.io 的 MCP Server 暴露的核心能力大概是这样几类能力类别典型工具方法作用说明画布管理初始化画布、设置页面尺寸建立绘图上下文确定整体尺寸节点操作创建矩形、圆形、数据库图标生成各类图形元素并设定标签连线操作创建带箭头的连线、虚线依赖表达调用、依赖、数据流关系样式设置设置填充色、边框、字体统一视觉风格区分层级导出能力导出 XML、导出图片落地成可编辑文件或预览图AI 侧的工作流就变成了先理解用户描述的架构规划出有哪些节点、哪些连线然后按顺序调用这些工具方法最后导出。整个过程 AI 不需要关心 XML 语法细节只需要关心我要画什么语法正确性由 MCP Server 兜底。这是这套方案能稳定跑起来的根本原因。1.3 分层架构把想和画彻底分开我把整套流程拆成三层这个分层是我踩了不少坑之后定下来的强烈建议照搬语义层用户用自然语言描述系统比如一个网关后面挂三个微服务每个服务连自己的数据库服务之间通过消息队列异步通信。这一层只关心业务语义不关心图形。结构层AI 把语义翻译成图结构——节点清单、边的清单、分组关系、层级归属。这一层输出的是纯逻辑结构可以用 JSON 表达跟具体绘图工具无关。渲染层MCP 工具把结构层的数据转成 Draw.io 的图形元素处理坐标、样式、连线走向。这么分层的好处是可替换。哪天想换成别的绘图工具只需要重写渲染层语义层和结构层原封不动。而且调试的时候能快速定位问题出在哪一层图结构错了是结构层的问题图能生成但布局难看是渲染层的问题分得清清楚楚。2. 核心细节解析与实操要点2.1 让 AI 稳定输出结构提示词里的三个硬约束AI 生成架构图最容易翻车的地方不是画不出来而是画得不对——漏掉关键组件、把依赖关系搞反、把同步调用画成异步。我摸索出一套提示词模板核心是三个硬约束。第一个约束是强制先列清单再画图。不要让 AI 直接开始调工具而是要求它先输出一份结构化的节点和边清单人工扫一眼确认无误再让它执行。提示词里我会明确写先用 JSON 列出所有节点id、名称、类型、所属分组和所有连线源、目标、关系类型确认后再调用绘图工具。这一步能拦掉八成低级错误。第二个约束是限定图形类型映射。AI 默认会乱用图形把数据库画成普通矩形。我会在提示词里给一张映射表数据库用 cylinder消息队列用带箭头的矩形外部系统用虚线框用户端用圆角矩形。明确映射之后出来的图语义一眼就能看懂。第三个约束是控制单次生成规模。一张图超过 30 个节点AI 的注意力就开始涣散连线容易错乱。我的做法是超过这个量级就拆图主图只画核心链路细节用子图或者单独的分层图表达。实测下来20 到 25 个节点的图AI 一次生成的成功率最高。提示提示词里一定要写明如果某个组件关系不确定宁可留空并标注待确认也不要臆造。AI 臆造出来的错误依赖比缺一根线危害大得多因为看图的人会当真。2.2 坐标与布局为什么不能全交给 AI 算这是实操里最容易被低估的环节。早期我让 AI 自己算每个节点的 x、y 坐标结果惨不忍睹节点重叠、连线穿过图形、整体歪歪扭扭。原因很简单AI 对二维空间布局的直觉很差它不知道两个节点间距 40 像素才不挤也不知道连线要绕开中间节点。后来我改成分层布局 相对定位的思路。具体做法是AI 只负责把节点按层级分组比如接入层、服务层、数据层每组内的节点按顺序排列坐标由 MCP 工具根据分组和序号自动计算。比如服务层有 4 个节点工具就按x 起始值 序号 × 间距来排间距固定 200 像素纵向按层级y 层号 × 180。这样出来的图至少是整齐的网格状不会重叠。对于连线我让 MCP 工具默认使用正交连线横平竖直的折线而不是直线。正交连线在架构图里可读性高得多尤其是跨层调用的时候。Draw.io 的 XML 里通过edgeStyleorthogonalEdgeStyle属性控制MCP 工具封装好之后AI 调用时只需要说从 A 连到 B样式自动套用。这里有个细节值得说连线标签的位置。AI 生成的连线如果带标签比如HTTP 调用异步消息标签默认会压在线上很难看。我的处理是在工具里给标签设置labelBackgroundColor#ffffff让标签有个白色底衬视觉上就清爽了。这种小细节纯靠 AI 生成 XML 是想不到的必须靠工具层兜底。2.3 样式规范一套配色让图立刻专业起来架构图专不专业配色占一半。我见过太多图每个框颜色都不一样红黄蓝绿乱飞看着像儿童画。我的做法是定一套语义化配色写进 MCP 工具的默认样式里AI 生成时按节点类型自动套用节点类型填充色边框色适用场景接入/网关浅蓝深蓝API 网关、负载均衡、CDN业务服务浅绿深绿微服务、应用服务数据存储浅黄橙黄数据库、缓存、对象存储消息中间件浅紫深紫消息队列、事件总线外部系统浅灰深灰第三方接口、遗留系统这套配色的逻辑是冷色表示计算、暖色表示存储、紫色表示异步、灰色表示边界外。看图的人不用看文字光凭颜色就能判断这个框大概是什么角色。字体统一用无衬线体字号 12 到 14标题加粗。这些规范一旦固化到工具层AI 每次生成的图风格都一致团队里多个人用 AI 画图也不会出现风格打架。注意配色不要超过五种主色。我试过用七八种颜色区分更细的组件类型结果图反而更乱读者要不停对照图例。五种以内靠形状和文字补充区分可读性最好。2.4 分组与边界把系统边界画明白架构图最容易被忽略、但信息量最大的元素是边界。哪些服务在同一个 VPC 里、哪些属于同一个业务域、哪些是外部依赖这些信息用分组框Draw.io 里的 container 或 group表达出来图的专业度立刻上一个台阶。在 MCP 工具层我封装了一个create_group方法参数包括分组名称、包含的节点 id 列表、边框样式实线表示内部系统虚线表示外部边界。AI 在结构层规划时会先确定分组再把节点分配到组里。工具执行时先创建分组框再把节点放进去最后调整分组框尺寸包住所有子节点。这里有个实操坑分组框的尺寸计算。如果先画节点再画分组框分组框要动态计算包围盒稍微算错就会盖住节点或者留白过多。我的做法是反过来——先根据组内节点的布局范围算出分组框的位置和大小再画节点。这样分组框永远严丝合缝。计算逻辑大概是取组内所有节点坐标的最小 x、最小 y 作为左上角最大 x 节点宽、最大 y 节点高作为右下角四周各留 20 像素 padding。3. 完整实操流程与关键环节实现3.1 环境准备把 MCP 服务接起来动手之前先把环境搭好。整体需要三样东西一个支持 MCP 的代码智能体客户端、Draw.io 的 MCP Server、以及一个能跑 Node 或 Python 的运行环境具体取决于你选的 MCP Server 实现。第一步是获取 Draw.io 的 MCP Server。这类服务通常是开源实现核心逻辑是把 Draw.io 的图形操作封装成标准 MCP 工具。拿到之后按它的说明安装依赖、启动服务。启动成功后服务会监听一个本地端口或者通过标准输入输出与客户端通信。第二步是在智能体客户端里配置 MCP Server 的连接信息。配置项一般包括服务名称、启动命令、参数。以常见的配置文件格式为例大概长这样{ mcpServers: { drawio: { command: node, args: [/path/to/drawio-mcp-server/index.js], env: { OUTPUT_DIR: /path/to/output } } } }第三步是验证连通性。在客户端里让它列出可用的绘图工具如果能返回工具清单创建节点、创建连线、导出等说明链路通了。这一步别跳过我见过不少人配置写错路径后面调半天以为是 AI 的问题其实是服务根本没起来。提示OUTPUT_DIR这类输出目录一定要配成绝对路径并且确保有写权限。相对路径在不同工作目录下启动会指向不同位置导出的文件找不着是常事。3.2 从一句话需求到结构清单第一次人机协作环境通了之后先别急着让它画完整架构。我的习惯是先拿一个小场景试水比如画一个包含网关、两个服务和两个数据库的简单架构。这一步的目的是校准 AI 对图形的理解看看它默认会怎么映射。实际操作时我会这样下指令请为以下系统生成架构图结构清单先不要调用绘图工具 系统包含一个 API 网关网关后面是两个业务服务订单服务、用户服务 每个服务各自连接一个数据库两个服务之间通过消息队列异步通信。 要求 1. 用 JSON 输出节点清单每个节点包含 id、名称、类型、分组 2. 用 JSON 输出连线清单每条连线包含源 id、目标 id、关系描述 3. 类型从以下枚举中选择gateway、service、database、queue、external拿到 JSON 之后人工检查一遍。重点看三件事节点有没有漏、连线方向对不对、类型映射准不准。确认没问题再让它根据上面的清单调用绘图工具生成图。这个先清单后执行的两段式操作是我目前觉得最稳的节奏。3.3 生成与微调让图从能看到好看工具执行完之后会导出一个.drawio文件。用 Draw.io 打开第一眼大概率是结构对了但布局一般。这时候别急着让 AI 重画先手动微调——因为 AI 重画可能把已经对的部分也改乱。微调的重点按优先级排先调整体布局把层级拉开、把拥挤的地方疏散再调连线走向把交叉的线理顺、把穿过节点的线绕开最后调样式细节统一字号、对齐标签。Draw.io 自带的对齐工具和自动布局功能这时候很好用选中一组节点一键等距分布比手动拖快得多。如果微调之后发现结构层面就有问题比如某个服务应该拆成两个那就回到结构清单那一步改 JSON 再重新生成。我的经验是结构问题回结构层改样式问题在渲染结果上改不要混着来否则越改越乱。3.4 参数计算实例间距和尺寸怎么定很多人问布局参数到底怎么定这里给一组我实测下来比较通用的数值可以直接抄节点标准尺寸宽 160、高 60。这个尺寸能容纳 8 到 10 个中文字符大多数服务名够用。水平间距同层节点之间留 80 像素。小于 60 会显得挤大于 120 又太散。垂直层间距相邻两层之间留 120 像素。这个距离刚好够正交连线拐两个弯而不显得局促。分组框 padding四周各 20 像素。画布边距整体内容距离画布边缘留 40 像素。举个具体例子一个三层架构接入层 1 个节点、服务层 3 个节点、数据层 3 个节点。服务层 3 个节点横向排列总宽度 3 × 160 2 × 80 640 像素。数据层同理。接入层 1 个节点居中放置x 坐标 服务层起始 x (640 - 160) / 2 起始 x 240。纵向三层总高度 3 × 60 2 × 120 420 像素。这些数值写进 MCP 工具的默认配置AI 调用时不用每次算直接套用。4. 常见问题与排查技巧实录4.1 生成的文件打不开或图形错乱这是最高频的问题表现是导出的.drawio文件用 Draw.io 打开报错或者打开后图形挤成一团。排查思路按这个顺序走现象可能原因排查与解决文件打开报 XML 解析错误标签未闭合、属性值含特殊字符未转义检查节点名称里是否有、、需转义为实体图形全部堆在左上角坐标未正确传入默认值为 0检查工具调用时 x、y 参数是否缺失连线不显示源或目标节点 id 不存在核对连线引用的 id 与节点 id 是否一致中文显示为方块字体未指定或字体不支持中文样式里显式设置支持中文的字体族我踩过最坑的一次是节点名称里带了一个符号订单支付服务生成的 XML 直接解析失败排查了半小时才发现是转义问题。后来在 MCP 工具层统一做了转义处理这类问题就绝迹了。所以如果你自己实现工具输入转义一定要在工具层做掉别指望 AI 每次都记得。4.2 AI 生成的图结构对但关系错这种情况比生成失败更隐蔽因为图看起来是好的但依赖关系画反了或者漏了。典型表现是把服务调用数据库画成了数据库调用服务或者把同步调用画成了异步消息。根因通常是提示词里对关系类型的描述不够明确。解决办法是在结构清单阶段就强制 AI 标注关系类型并且给出枚举sync_call同步调用、async_message异步消息、data_read数据读取、data_write数据写入。不同关系类型在渲染时用不同线型——同步用实线箭头、异步用虚线箭头、数据流用带圆点的线。这样即使 AI 标错了看图的人也能从线型上发现异常。注意让 AI 画图时关系方向的校验最好人工过一遍。我一般会对着结构清单逐条念A 调用 B箭头从 A 指向 B念一遍能发现大部分方向错误。4.3 大规模架构图怎么拆超过 30 个节点的系统一张图画完必然糊。我的拆图策略是按视角拆而不是按模块拆。常见的三个视角部署视角画物理部署关系哪些服务在哪个环境、哪个区域节点是机器和容器。逻辑视角画服务间的调用关系节点是服务边是接口调用。数据视角画数据流向节点是数据存储和处理组件边是数据流。每个视角一张图图与图之间用相同的节点命名保持对应关系。这样每张图控制在 20 个节点以内AI 生成质量高人看着也清楚。千万别试图用一张图表达所有信息那是给自己找罪受。4.4 实操心得三个让我少走弯路的习惯第一个习惯是版本化保存结构清单。每次生成的 JSON 结构清单单独存一份跟导出的图放一起。图改了但清单没更新下次想重新生成就对不上了。清单是源图是产物源要管好。第二个习惯是建立自己的图形模板库。常用的组件网关、数据库、消息队列在 Draw.io 里做成自定义形状或者样式模板MCP 工具直接引用模板 id。这样生成的图风格统一也省得每次调样式。第三个习惯是先画草图再让 AI 精修。复杂系统我会先在纸上或者白板上画个大概拍照然后把草图的结构描述给 AI让它生成规范版本。人负责想结构AI 负责出成品分工明确效率最高。纯靠 AI 从零想结构遇到复杂业务它容易想当然反而不如人先定框架。这套 Codex 加 Draw.io MCP 的组合我用下来最大的感受是它把画架构图从体力活变成了脑力活。以前大量时间花在拖框、连线、调对齐上现在这些交给工具我的精力集中在这个系统的边界划得对不对、依赖关系有没有遗漏这些真正需要判断的事情上。工具永远替代不了对系统的理解但它能把理解之后那段落地的苦活干掉这就够了。