给新同学讲系统架构我习惯先甩过去一张用 Draw.io 画的图。说实话画图这件事我抵触了很久不是不会画而是觉得“画”这个动作本身太廉价又太耗时。一张像样的时序图光是拖框、拉线、对齐、改颜色半小时就没了。上周在 GitHub 上翻到一个 4.8k Star 的 AI 加持 Draw.io 开源项目试用了一周最大的感受是——画图的正确打开方式变了不再是拖拽方框而是直接说人话让 AI 先把草图画出来我负责改。这篇文章就把这一周从安装、实操到踩坑的完整记录分享出来给同样被画图折磨的人一个参考。1. 画图十分钟、改图一小时传统绘图工具的痛点1.1 拖拽只是门槛排版才是噩梦Draw.io 的定位一直很清晰免费、开源、免登录打开浏览器就能画。相比 Visio 和 ProcessOn它胜在轻量和对 git 友好——图以 XML 文件形式存储可以直接进代码仓库走 Review 流程这是很多研发团队选它的核心理由。但它的使用成本并没有想象中那么低。我建模时最怕三件事从零画图时的“空白画布焦虑”脑子里明明有十个模块、四条链路但框往哪儿摆完全没有头绪光标悬在画布上半天落不下去。排版对齐的心智负担节点怎么摆、箭头怎么拐、泳道怎么分、颜色怎么统一这些本应该由工具解决的问题全压在画图人身上。反复修改的连锁返工需求一变改一条连线就要重新挪一堆框改到后面自己都不想看。对开发者和解决方案架构师来说画图的产出价值在于“表达模型”而不在“画工”本身。传统工具把太多注意力消耗在了后者。我之前甚至见过有人为了对齐一张部署图花掉半天最后图的逻辑还画错了这就是典型的工具绑架思维。1.2 这个 4.8k Star 的项目其实只做了三件事这个项目的核心思路是用大语言模型把“自然语言描述”直接转成可编辑的 Draw.io 文件。我实测下来它主要做了三件事内置 AI 对话面板在 Draw.io 界面右侧多了一个输入框你直接打字描述要什么图不需要写任何绘图语法。生成后可继续编辑AI 产出的是真正的 mxGraphModel XML不是一张截图所有节点、连线、样式都能在 Draw.io 里继续拖拽修改。支持改图指令不用重新生成整张图直接说“把网关拆成两个实例”或“给登录加一个验证码分支”它会在原图基础上增量修改。从产品形态上讲它没有另起炉灶做一个新画图工具而是给 Draw.io 装了一个“会画图的 AI 助手”。这个选择很聪明后文我会展开讲为什么——因为“AI 做语义、工具做布局”的分工才是它真正值钱的地方。2. 本地部署与初始化从拉代码到跑通第一张图2.1 依赖比想象中少项目本质上是“前端 Draw.io 嵌入 后端代理转发 LLM 请求”所以本地跑起来只需要两样东西Node.js 16 以上前端静态服务和代理服务都依赖它一个可用的 LLM API KeyOpenAI 兼容接口即可后面会说怎么接本地模型我在测试机上用的是 Node.js 18、Ubuntu 22.04Windows 和 macOS 同样能跑。仓库在 GitHub 上直接按标题关键词搜就能找到Star 数 4.8k 的那个就是。Clone 下来之后目录结构大概是项目根目录/ ├── client/ # Draw.io 前端嵌入层负责展示和交互 ├── server/ # 代理服务处理 API 请求和 XML 转换 ├── .env.example # 环境变量模板 └── README.md2.2 启动三步走第一步是装依赖。前端和服务端各自有 package.json所以需要在两个目录分别执行npm install。有些版本还带 Python 的转换脚本需要装 Python 依赖通常是 mermaid 语法解析相关的库按 README 提示操作即可。第二步是配置环境变量。拷贝.env.example为.env填入LLM_API_KEY你的key LLM_BASE_URLhttps://api.openai.com/v1 LLM_MODELgpt-4o-mini这里提示一个容易忽略的细节LLM_BASE_URL是可配置的意味着兼容 OpenAI 协议的任何服务都可以接入。我后来用 Ollama 在本地跑 Qwen2.5 也成功了只是速度和效果比付费模型差一些但胜在数据不出内网。第三步是启动服务npm run dev启动后浏览器打开本地地址看到 Draw.io 界面里多了一个 AI 面板就说明部署成功了。整个过程如果网络正常五分钟内能搞定。2.3 先别急着上大图画个框测链路跑通之后第一件事不是直接生成复杂架构图而是先画一个最简单的框再让 AI 改它的颜色或名称。这样可以确认网络请求、XML 回写链路都是通的。我见过有人一上来就生成 60 个节点的大图结果卡住最后排查半天发现是 API Key 填错白白浪费了一个小时。另外提一句项目本身有 Web 和桌面端两种用法。我习惯在 Web 端配合浏览器一起用因为改完可以直接截图贴到 PR 描述里团队协作时大家共用一套自托管服务也更方便版本管理。3. 核心玩法一句话生成架构图、时序图和流程图3.1 从需求描述到成品图完整流程演示我用它做的第一张图是订单系统的核心链路。在 AI 面板里输入生成一张订单系统的流程图用户下单、校验库存、锁定库存、调用支付、支付回调、扣减库存、更新订单状态。把失败分支也画出来库存不足时直接返回错误。大概过了十秒界面里就出现了一张带泳道和分支的流程图。节点位置虽然不算完美但整体结构完全正确失败分支用了不同的填充色一眼能看出来。关键点在于这张图不是“画”出来的而是描述出来的。我不需要知道每个框放哪里只需要把系统中的事实和关系讲清楚。这跟以前用 Visio 完全是两种思维模式——从“动手拼装”变成了“口头表达”表达越清楚图越准。3.2 让 AI 改图而不是重画真正的杀手功能是增量改图。我的实操例子第一轮生成用户登录时序图。第二轮输入“把 Redis 换成 MySQL并说明缓存失效时的降级逻辑”。第三轮输入“在网关层加一个限流过滤器放在最前面”。三轮下来我几乎没有手动拖过节点。它会在原来的 XML 基础上新增节点、调整连线然后重新排版。这对于需求频繁变动的场景非常实用——以前改一版架构图要重新挪半个画布现在一句话就搞定了改动范围还能在 git diff 里看得清清楚楚。3.3 我常用的 Prompt 模板经过一段时间使用我把效果最好的几种 Prompt 结构总结成了模板:目标Prompt 参考系统架构图生成 XX 系统的架构图前端、网关、微服务、数据库、消息队列注明各层之间的调用关系按分层布局时序图生成 XX 场景的时序图参与角色 X、Y、Z按调用顺序画出带返回箭头的交互标注关键参数流程分支生成 XX 流程图包含至少三个失败分支用红色标识异常路径泳道按角色划分运维拓扑生成 XX 部署拓扑Nginx、应用节点、主从数据库、缓存运维区域与开发区域用不同的容器框这里说一下我的经验Prompt 里最重要的不是“画好看一点”这样空泛的要求而是把节点清单和关系写清楚。AI 最擅长的是把结构转成图最不擅长的是猜你脑子里没说的模块。你漏掉的模块它会自以为聪明地补齐——所以首次生成后先检查有没有多余的节点再让它删掉比一开始写一堆要求更高效。4. 原理拆解LLM 和 Draw.io 是怎么“缝合”在一起的4.1 Mermaid 是中间语言不是最终答案这个项目让我觉得最有意思的部分是它的技术路径选择。LLM 直接输出 draw.io 的 XML 是很困难的——XML 里每个节点都有坐标、宽高、样式几十个节点动辄上千行模型很难一次性生成出正确且排版合理的 XML。所以它走了一条迂回路线先让 LLM 生成 Mermaid 语法再通过转换层把 Mermaid 解析成树结构最后由排版引擎计算坐标输出 mxGraphModel XML。Mermaid 在这里充当“中间语言”的角色。原因是 LLM 生成 Mermaid 时几乎不会出错语法足够简单节点和关系一目了然Token 消耗也低。让模型生成 30 行 Mermaid 的成本远低于让它直接生成 800 行 XML。举个例子生成“用户登录时序图”Mermaid 里就是先声明参与角色再用箭头符号表示调用和返回。模型对这种语法的掌握非常熟练几乎不存在格式错误而如果要求它直接输出 mxGraphModel光是每个节点的坐标和 style 字符串就够它晕头转向。4.2 转换层是如何工作的转换层拿到 Mermaid 后会做四步处理解析 Mermaid 文本识别出节点、连线、子图、泳道等元素。语义映射把 Mermaid 图的 node、edge 翻译成 mxCell——也就是 Draw.io 的基本元素。布局计算根据节点关系决定坐标位置这一步通常用类似 dagre 的算法做有向图分层布局。样式注入给不同类型的节点指定颜色、圆角、图标等样式让生成的图不是白底黑框。最终输出类似这样的 XMLmxGraphModel dx800 dy600 grid1 root mxCell id0 / mxCell id1 parent0 / mxCell id2 value用户 stylerounded1;fillColor#dae8fc; vertex1 parent1 mxGeometry x100 y80 width120 height40 asgeometry / /mxCell mxCell id3 value库存服务 stylerounded1;fillColor#d5e8d4; vertex1 parent1 mxGeometry x100 y220 width120 height40 asgeometry / /mxCell mxCell id4 styleedgeStyleorthogonalEdgeStyle; edge1 source2 target3 parent1 mxGeometry relative1 asgeometry / /mxCell /root /mxGraphModel这个 XML 就是 Draw.io 原生格式所以生成之后可以直接在编辑器里继续操作。整个链路最关键的工程决策是“AI 做语义工具做布局”——模型负责回答“画什么”算法负责回答“画在哪里”各干各擅长的活。如果反过来让 AI 直接干布局的活效果会非常差。4.3 为什么是基于 Draw.io 而不是新建轮子我一开始也想过直接做一个 AI 生成图的独立工具不是更省事吗但用下来发现基于 Draw.io 有三个实打实的好处。第一生态成熟。Draw.io 的 XML 格式文档齐全社区有大量自定义形状库生成结果可以直接复用这些资源。而且它的画布交互做得很完善缩放、网格对齐、连线拐角、导出 PNG/SVG/PDF 全是现成的省掉了渲染引擎的研发成本。第二对研发团队最友好的一点文件就是文本可以进 git 做差异对比。AI 生成的图要是直接存成图片评审时根本看不出改了什么存成 XMLReview 能看到每个节点的增删和连线的变化这比任何画图工具都贴近开发者的工作流。第三可嵌入性。Draw.io 本身支持 iframe 嵌入、VS Code 插件、Confluence 集成等于这个 AI 项目天然继承了这些入口不需要再做一遍适配。5. 实测中的坑中文显示、Token 超限和布局失控5.1 中文标签和字体问题先说最影响体感的中文乱码。AI 生成的中文标签在 Web 端 Draw.io 里基本正常但如果你用桌面客户端打开同一个文件有时候字体会变成方块或者挤在一起。原因不是 XML 编码出了问题而是桌面端的默认字体没有回退到中文字体。我的解决方案是在系统层面装一张开源中文字体比如 Noto Sans CJK SC并在需要共享的图里手动把全局字体重设一遍。如果团队里有人用 Windows、有人用 macOS最好在生成 Prompt 时加一句“所有节点文字使用微软雅黑/PingFang SC”让样式表里带上明确的字体声明。这个细节看着小但在跨平台协作时能省掉一堆“图在我这儿显示是好的”的纠纷。5.2 大图的 Token 消耗和生成质量问题生成超过 30 个节点的图时问题开始暴露要么响应变慢要么结构完整性下降。我实测生成 40 节点架构图单次请求可能要 20 秒以上而且偶尔会漏掉某个模块需要二次指令补全。回避的方式有两个方向。一是拆分生成先让 AI 画主链路再让它“基于现有图增加 XX 模块及关联连线”。二是用更强的模型处理复杂图便宜小模型适合单链路流程图架构图最好交给大参数模型。说白了AI 画图也是典型的“垃圾进垃圾出”描述时分不清颗粒度生成的就是一团浆糊。5.3 布局有时候会“发疯”布局算法不是万能的。嵌套子图多、跨泳道连线多的时候生成的图经常出现节点重叠、连线穿框。我的经验是不要手工一个个拖太累了直接选中部分节点后用 Draw.io 自带的“排列”功能整理或者让 AI 重新生成一次。如果某个跨泳道连线实在没法看就把上游拆成两条线绕开泳道区域再连视觉上会干净得多。另外我注意到请求里如果明确写了“按从左到右排列”或者“数据库放底层”布局效果会明显好于不指定方向的图。说到底算法再好也需要约束条件Prompt 里的方向词就是给布局引擎的免费约束。5.4 差点把 API Key 提交到仓库这是我最想提醒的一条。项目默认支持通过环境变量传 Key但总有人图省事把它写到配置文件里。我把.env加进.gitignore还不放心又配置了 pre-commit 钩子扫描敏感信息。团队协作时Key 应该放在 CI 的 secret 或本地环境变量里而不是跟着代码流转。自托管给团队用的时候还有两个规范一是服务要加访问鉴权避免内网裸奔二是记录 LLM 调用日志用来核算成本和排查问题。别等 Key 泄露了再后悔这类工具一旦被刷费用是按秒计的。6. 我的使用心得把 AI 画图嵌入日常研发流程6.1 适合的场景和不适合的场景用了一周之后我给自己总结了一张“什么图适合让 AI 画”的清单适合的架构示意图、模块关系图、数据流转图——重点是结构不强求精确坐标。需求讨论阶段的草图——快速产出多个方案用于评审比手画快十倍。接口时序图——把调用链描述清楚省去画框的重复劳动。不适合的需要严格走 UML 规范、带精确可见性的类图——AI 生成的细节容易出错改起来的成本比手画还高。超大网络拓扑、机房机架图——这类图信息密度高布局算法很难一次搞定。对外交付的正式架构文档配图——AI 产出终稿前你还是得手动调样式和字号。这个判断很重要。AI 画图的定位是“极速草稿 智能助手”不是“完全替代人工”。把它用在对的地方收益是倍数级的用错地方反而增加返工成本。6.2 让“图”活起来几个值得尝试的扩展方向项目本身是开源的我后来在本地做了一些小改动效果不错分享给大家参考接本地模型把LLM_BASE_URL指向本机的 Ollama 服务数据不出内网适合处理敏感系统架构。接入团队知识库在生成 Prompt 前先检索团队内部的架构决策记录把相关内容拼进去生成的图会更贴合现有规范。结合 CI 自动同步每次架构变更合并后自动调用接口重新生成架构图并附到 PR 描述里评审时一目了然。预设模板库把常见场景的 Prompt微服务架构、监控告警流程、部署拓扑存成模板团队成员直接复用产出风格高度一致。6.3 最后分享一个习惯我在实际操作中最后养成的习惯是每次画图前先花两分钟把“这张图想讲清楚什么”用文字写出来再丢给 AI 生成。这个习惯看起来多了一步实际上省掉了大量改图时间。文字没想清楚就去画图AI 生成得再快出来的也是没用的大杂烩。工具本身一直在迭代Star 数只代表社区关注度不代表它能替你思考。真正值得借鉴的是这种产品思路——把 AI 放在一个成熟工具的旁边而不是从头发明一个工具。这个思路比 4.8k Star 本身更有价值。
