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

架构图这件事画过的人都懂那种痛。需求评审前夜对着白板拍照的草图硬生生要在绘图工具里一个框一个框地拖一条线一条线地连改一版布局全乱再改一版配色又崩。我做过统计一张中等复杂度的系统架构图从梳理关系到最终导出纯手工操作平均要花掉两到三个小时而这其中真正用于思考架构的时间可能不到三分之一剩下的全耗在拖拽和对齐上。这两年大模型能力上来了我一直在琢磨能不能让 AI 直接把这件事干掉——我把想法落地成了一套可复现的方案用 Codex 这类代码生成模型配合 Draw.io 的 MCP 接口让 AI 读懂需求描述后自动产出可编辑的架构图文件。这套东西解决的核心问题就一个把画图这个体力活从架构设计流程里剥离出去人只管描述和审阅。适合谁看如果你是会写点代码的架构师、技术负责人或者单纯被画图折磨过的开发者这篇内容应该能帮你省下大量时间。下面我把自己踩过的路、调过的参数、翻过的车原原本本拆开讲。1. 方案整体设计与技术选型拆解1.1 为什么是代码模型 绘图工具接口这个组合先把这套方案的骨架说清楚。核心链路是自然语言描述 → Codex 生成结构化图形描述 → 通过 MCP 协议调用 Draw.io 能力 → 输出可编辑的图表文件。这里有两个关键决策点我逐个解释为什么这么选。第一个决策是用代码生成模型而不是纯对话模型。架构图本质上是一种结构化数据Draw.io 的底层文件格式是 XML具体是 mxGraphModel 那套结构节点、边、坐标、样式全是标签和属性。让一个擅长写代码的模型去生成 XML比让一个只会聊天的模型去描述一张图靠谱得多。Codex 系列模型对标记语言的结构感很强生成嵌套标签时不容易漏闭合这是实测下来的明显优势。我试过用普通对话模型直接输出 XML闭合标签错漏率大概在三成以上而代码模型能压到个位数百分比。第二个决策是走 MCP 而不是直接拼 XML 字符串。MCP 是 Model Context Protocol 的缩写你可以把它理解成AI 和外部工具之间的标准插座。为什么不直接让模型吐一段 XML 存成文件因为直接拼字符串有几个硬伤一是模型对坐标计算不敏感容易把框叠在一起二是没法做增量修改改一个节点要重新生成整份文件三是缺少校验环节生成的 XML 语法错了要到打开时才发现。走 MCP 的话绘图工具侧可以提供创建节点连接两个节点自动布局这类原子能力模型只需要决定画什么、连什么具体的坐标和样式交给工具侧处理职责分离稳定性高一个量级。提示MCP 的本质是工具调用的标准化协议不同绘图工具的实现细节不同但模型决策 工具执行这个分工模式是通用的理解了这一点换任何绘图后端都能套用。1.2 整体架构分层与数据流向我把整套方案分成四层从下往上说。最底层是绘图引擎负责实际的图形渲染和文件序列化Draw.io 的桌面版和网页版都内置了这套引擎我们通过它的文件格式和接口来对接。往上一层是 MCP 服务层这一层是我自己写的适配器把绘图引擎的能力包装成 MCP 工具比如create_node、create_edge、auto_layout、export_file这几个核心方法。再往上是模型编排层负责把用户的自然语言需求拆解成一系列工具调用序列Codex 在这里扮演总指挥的角色。最顶层是交互层可以是一个命令行脚本也可以是一个简单的 Web 界面用户在这里输入需求、查看结果。数据流向是这样的用户在交互层输入画一个包含网关、三个微服务、一个数据库的架构图编排层把这句话连同工具清单一起发给模型模型返回一串工具调用指令MCP 服务层逐条执行绘图引擎实时构建图形对象最后导出成.drawio文件。整个过程里模型不碰坐标只碰语义引擎不碰语义只碰几何。这个边界划清楚后面所有的调试都会轻松很多。1.3 选型对比几种常见路线的取舍在定方案之前我横向试了几条路列个表对比一下方便你判断自己该走哪条。方案路线实现方式优点缺点适用场景纯提示词生成 XML模型直接输出 mxGraphModel零依赖最快上手坐标易重叠语法错误率高难增量修改一次性草图、简单图模型 绘图 DSL模型生成简化的图形描述语言再转 XML结构清晰易校验需要自己设计 DSL 和转换器中等复杂度、需批量生成模型 MCP 工具调用模型决策工具执行几何操作稳定性高支持增量修改需要写 MCP 适配层前期投入大复杂架构图、需反复迭代模型 图像生成直接出位图视觉效果好不可编辑文字易错乱演示配图非工程用途我最终选 MCP 路线核心原因是架构图是要改的。评审会上领导一句这个服务拆成两个纯 XML 方案就得推倒重来而 MCP 方案只需要追加两条工具调用。前期多花两天写适配层后面每次修改省半小时这笔账怎么算都划算。如果你只是偶尔画一张图纯提示词方案也够用别过度设计。2. 核心细节解析与实操要点2.1 Draw.io 文件格式的关键结构要吃透这套方案得先搞明白 Draw.io 的文件长什么样。它的核心是mxGraphModel这个根节点下面挂rootroot里固定有两个基础单元格id0的根单元格和id1的默认父级。所有你画的图形都是mxCell节点带vertex1的是图形矩形、圆形这些带edge1的是连线。每个mxCell必须有唯一的idparent指向父容器图形还要有mxGeometry子节点描述位置和尺寸。这里有个新手特别容易踩的坑连线的 source 和 target 必须指向已存在的 vertex id。模型生成时如果 id 对不上打开文件就是一堆断线或者干脆报错。我的做法是在 MCP 服务层维护一个 id 注册表每次创建节点时分配一个语义化 id比如svc_order、db_main创建连线时校验两端 id 是否存在不存在就拒绝执行并返回错误给模型让它重新决策。这个校验环节把断线率从两成压到了几乎为零。另一个细节是样式属性。Draw.io 的样式是一串分号分隔的键值对比如rounded1;fillColor#dae8fc;strokeColor#6c8ebf;。手写这串东西很反人类但模型生成起来反而顺手因为它就是文本。我在适配层预置了几套样式模板服务节点、数据库节点、外部系统节点模型只需要指定用数据库样式适配层负责展开成完整样式串。这样既保证了视觉一致性又降低了模型的输出负担。2.2 MCP 工具接口的设计原则写 MCP 适配层的时候接口设计直接决定了模型好不好用。我总结了三条原则都是踩坑换来的。第一条工具粒度要语义级而非像素级。什么叫语义级create_node(type, label, group)是语义级set_x(id, 100)是像素级。前者模型能理解后者模型会疯掉——它根本不知道 100 该给谁。我一开始设计了细粒度的坐标设置接口结果模型要么乱给坐标要么反复调用把图搞乱。改成语义级之后模型只需要说在网关组里加一个订单服务位置由布局算法决定输出质量立刻稳定。第二条每个工具都要有明确的失败反馈。MCP 工具执行失败时返回的错误信息要足够具体模型才能自我纠正。比如连线时 target 不存在不要只返回失败要返回target id svc_xxx 不存在当前可用 id 列表[...]。模型拿到这个信息下一轮就能改对。我实测过带详细错误反馈的版本任务一次成功率比只返回布尔值的版本高出四成。第三条提供批量操作接口。模型一次决策往往涉及多个节点如果只能一个一个建调用轮次会爆炸。我加了create_nodes_batch(nodes)和connect_batch(edges)两个批量接口一次调用建十个节点轮次从十几次降到两三次响应速度和稳定性都上来了。2.3 提示词工程怎么让模型看懂架构需求模型再强提示词写不好也白搭。我的系统提示词里固定包含四块内容角色设定你是一个架构图生成助手、工具清单每个工具的用途和参数说明、输出规范先规划再执行每次调用前说明意图、约束条件节点数量上限、必须包含图例、连线不能交叉等。其中先规划再执行这条特别关键。我要求模型在第一次工具调用前先用一段文字列出它打算画哪些节点、怎么分组、连哪些线。这段规划文字不消耗工具调用但能显著提升后续执行的连贯性。实测下来有规划步骤的版本生成的图结构合理度明显更高因为模型在想的时候把关系理顺了执行时就不容易漏。还有一个技巧是给模型喂示例。我在提示词里放了一个完整的输入需求 → 工具调用序列的示例模型会模仿这个模式。示例不用长一个包含五六个节点的小架构就够但效果立竿见影。这其实就是少样本学习的老套路在结构化输出任务上依然好用。注意提示词里的工具说明要和实际接口严格一致参数名、类型、必填项一个都不能错。我吃过这个亏提示词里写的是label接口实际要的是name模型一直传错参数排查了半天才发现是文档和实现对不上。3. 实操过程与核心环节实现3.1 环境搭建与依赖准备动手之前先把环境理清楚。我用的技术栈是 Python 做 MCP 服务层因为生态成熟、调试方便。核心依赖就三个mcp官方 SDK 负责协议通信lxml负责 XML 的解析和生成requests负责和模型 API 通信。装依赖这一步没什么坑pip install mcp lxml requests一把梭就行。目录结构我建议这样组织mcp_server/放适配层代码prompts/放提示词模板output/放生成的图表文件examples/放测试用例。这个结构看着简单但后面调试时能帮你快速定位问题——出图不对先看 prompts文件损坏先看 mcp_server 的序列化逻辑需求理解偏差先看 examples 里的对照。配置模型 API 的时候把密钥放环境变量里别硬编码进代码。我见过有人把密钥提交到代码仓库虽然及时删了但历史记录里还留着这种低级错误不值得犯。用os.environ.get(MODEL_API_KEY)读取本地开发用.env文件配合python-dotenv加载干净利落。3.2 MCP 服务层的核心代码实现服务层是整个方案的心脏我挑最关键的三个函数讲。第一个是节点创建函数核心逻辑是分配 id、构建 mxCell 结构、注册到 id 表。代码大概长这样def create_node(node_type, label, groupNone): node_id generate_semantic_id(node_type, label) style STYLE_TEMPLATES.get(node_type, STYLE_TEMPLATES[default]) cell { id: node_id, value: label, style: style, vertex: 1, parent: group or 1 } id_registry[node_id] cell return {status: ok, id: node_id}这段代码里generate_semantic_id是个小设计它把类型和标签拼成 id比如svc_order、db_user好处是调试时一眼能看出这个 id 对应什么比cell_001这种强太多。STYLE_TEMPLATES就是前面说的样式模板字典预置了七八种常用样式。第二个是连线函数重点是校验def create_edge(source_id, target_id, label): if source_id not in id_registry: return {status: error, message: fsource {source_id} 不存在可用: {list(id_registry.keys())}} if target_id not in id_registry: return {status: error, message: ftarget {target_id} 不存在可用: {list(id_registry.keys())}} edge_id fedge_{source_id}_{target_id} # 构建 edge 结构并注册 ...错误信息里带上可用 id 列表这个细节前面提过是提升模型自我纠正能力的关键。第三个是导出函数把 id 注册表里的所有 cell 组装成完整的 mxGraphModel用 lxml 序列化成 XML再按 Draw.io 的压缩格式可选不压缩也能打开写入.drawio文件。这里要注意 XML 声明和命名空间漏了的话文件打不开。我一开始就漏了xmlns属性生成的图在 Draw.io 里一片空白排查了半小时才定位到。3.3 一次完整的生成流程实录拿一个真实需求走一遍。需求是画一个电商下单链路包含 API 网关、订单服务、库存服务、支付服务、订单数据库、库存数据库网关调用三个服务订单服务写订单库库存服务写库存库支付服务调用外部支付渠道。第一步编排层把需求连同工具清单发给模型。模型返回规划文字我将创建 7 个节点网关、订单服务、库存服务、支付服务、订单库、库存库、外部支付渠道创建 6 条连线……这段规划我一般会打印出来人工扫一眼结构不对就中断重来比等图画完再改省事。第二步模型发起批量创建调用create_nodes_batch一次传入 7 个节点定义适配层逐个创建并返回 id 列表。模型拿到 id 后发起批量连线调用6 条边一次建完。这里有个细节模型需要把网关调用三个服务翻译成三条具体的边它得知道三个服务的 id所以批量创建接口的返回值必须包含 id 映射模型才能正确引用。第三步调用auto_layout做自动布局。我用的是分层布局算法按节点类型分层网关在最上层服务在中间层数据库在最下层外部系统放侧边。布局算法会计算每个节点的坐标避免重叠。这一步是纯几何计算和模型无关稳定性很高。第四步导出文件用 Draw.io 打开检查。第一次跑的时候我发现支付服务和外部渠道的连线穿过了库存服务视觉上很乱。解决办法是在布局算法里给外部系统单独分配一个列并且连线走正交路由edgeStyleorthogonalEdgeStyle拐直角弯而不是斜穿。改完之后图面清爽多了。整个流程从输入需求到出图实测耗时约 40 秒其中模型推理占大头工具执行不到 5 秒。对比手工两三个小时效率提升是数量级的。当然生成的图还需要人工微调比如调整某个框的大小、改个颜色但这些都是分钟级的操作大头已经省掉了。3.4 参数调优布局与样式的关键配置布局这块有几个参数值得单独说。层间距layer spacing我设的是 80 像素太小了连线挤在一起太大了图显得松散80 是试出来的甜点值。节点间距node spacing设 40 像素同层节点之间留这个空隙视觉上不拥挤也不空旷。连线路由统一用正交样式斜线在架构图里几乎总是显得乱。样式方面我定了套配色规范服务节点用浅蓝填充配深蓝边框数据库用浅黄配深黄外部系统用浅灰配深灰网关用浅绿。这套配色不是随便选的浅色填充保证文字可读深色边框区分类型整体饱和度低打印出来也不刺眼。模型只需要指定节点类型配色由模板决定这样生成的图风格统一不会出现一张图里七八种颜色的灾难。提示布局参数没有绝对最优值和图的规模有关。节点少于 10 个时间距可以小一点超过 20 个就要适当放大否则连线会密集交叉。建议把间距做成可配置参数按节点数量动态调整。4. 常见问题与排查技巧实录4.1 生成结果不符合预期的排查路径出问题别慌按固定路径排查效率最高。我总结了一个排查顺序先看规划文字再看工具调用日志最后看生成的文件。规划文字错了说明需求理解有偏差改提示词规划对但调用日志里有失败说明接口或参数有问题查适配层规划和调用都对但文件打开不对说明序列化有 bug查导出逻辑。举个真实例子。有次生成的组织架构图所有节点都堆在左上角重叠在一起。看规划文字没问题看调用日志发现auto_layout返回成功但文件里坐标全是 0。定位到布局函数里有个 bug计算完坐标后忘了写回 cell 的 geometry。这种问题看日志看不出来必须打开文件对比。所以我的建议是调试阶段每次生成后都用脚本解析一下输出文件打印每个节点的坐标异常一眼就能发现。4.2 模型调用失败与重试策略模型 API 调用失败是常态网络抖动、限流、超时都会遇到。我的策略是指数退避重试第一次失败等 1 秒第二次等 2 秒第三次等 4 秒最多重试三次。超过三次就中断并报错不要无限重试否则可能触发更严格的限流。还有一种失败是模型返回了无法解析的内容。比如它本该返回工具调用却返回了一段解释文字。这种情况我的处理是把错误信息连同原始返回一起塞回给模型让它重新决策通常第二次就能纠正。如果连续两次都这样说明提示词可能有问题得人工介入看看。4.3 常见问题速查表把高频问题整理成表方便对照排查现象可能原因排查方法解决方案文件打不开或空白XML 缺命名空间或根节点用文本编辑器看文件头补全xmlns和mxGraphModel根节点节点全部重叠布局未执行或坐标未写回解析文件打印坐标检查布局函数是否写回 geometry连线断裂source/target id 不存在查 id 注册表加强连线前校验返回可用 id文字显示为方块字体未指定或编码问题检查 style 里的 fontFamily指定通用字体如 Helvetica生成速度慢工具调用轮次过多看调用日志统计轮次改用批量接口减少轮次图形风格不统一模型自创样式检查 style 属性强制使用样式模板禁止模型自定义4.4 几个血泪教训最后分享几个我踩过的坑都是文档里不会写的。第一个坑是 id 冲突。早期我用自增数字做 id结果模型在增量修改时自己编了个 id和已有的撞了导致节点被覆盖。后来改成语义化 id 加随机后缀冲突概率降到可忽略。第二个坑是中文标签的转义。XML 里某些字符要转义模型生成时偶尔会漏导致文件损坏。解决办法是在序列化前统一做一次转义处理别指望模型每次都记得。第三个坑是过度依赖自动布局。自动布局对规整的层次结构效果好但对网状结构比如微服务之间互相调用就力不从心容易画出蜘蛛网。我的经验是网状结构超过一定密度时手动指定几个关键节点的位置剩下的交给算法效果比全自动好。这个一定密度大概是平均每个节点超过三条连线的时候。第四个坑是忽略了图例。架构图没有图例读者看不懂颜色和形状的含义。我在提示词里强制要求生成图例节点虽然模型偶尔会忘但加上这条约束后出图的专业度明显提升。图例本身也是几个节点加文字用同一套工具就能画成本很低。这套方案我用了大半年从最初的纯提示词方案一路迭代到现在的 MCP 版本中间推翻重来了两次。现在它已经成了我日常工作的固定环节需求评审前十分钟输入描述图就出来了剩下的时间全用来打磨架构本身。如果你也在被画图困扰建议从最简单的纯提示词方案起步跑通了再往 MCP 迁移别一上来就搞全套容易在适配层里迷失。真正值钱的不是工具本身而是你对哪些该交给 AI、哪些必须人来把关这个边界的判断这个判断只能靠一次次实操喂出来。