AI生成架构图总翻车？4万星项目从源头驯服Mermaid乱象

说实话第一次让 AI 帮我画架构图我的心情是很复杂的。代码它写得挺利索但图一出来整个页面像被打翻的彩色毛线团节点挤成一堆、箭头交叉乱窜、分层概念完全看不清。后来我刷到一个 4 万星的开源项目专门治这种“mermaid slop”核心思路不是去修图而是教 AI 在生成阶段就画出结构清晰、层次分明、能直接放进技术文档里的架构图它甚至一度冲上 GitHub 日榜第一名。这篇文章就把这个项目到底做了什么、我实际怎么用它、以及那些文档里不会写的坑一次性讲清楚。适合被 AI 画图折磨过的后端、架构师、文档工程师以及所有想让图表真正“能看”的人。1. mermaid slop 不是审美问题是工程信任问题1.1 先回忆一次“图比没有图还糟糕”的经历我接手过一个模拟项目 X 的技术方案评审时间紧就让 AI 先生成了一张系统调用示意图准备放进方案文档。生成速度很快十几秒就给了我一串 mermaid 代码。我当时还挺高兴觉得省了大功夫。结果渲染出来的那一刻会议室里所有人的表情都不太对二十多个节点全挤在画布中央字号小得可怜连线和标签叠在一起几乎分不清谁指向谁。更麻烦的是评审的时候我根本没法指着图讲清楚“流量从哪里进来、依赖往哪里走”只能一边口头解释一边用手在屏幕上比划。最后我干脆把图删了换回一张手工画的大框套小框图。那一刻我突然意识到一件事AI 生成的烂图不只是难看它会直接消解文档的可信度。读者看到这种图的第一反应不是“作者想表达什么”而是“这图是不是随便糊弄的”。mermaid 这类基于文本的绘图语法本来是为了降低画图门槛。用文字描述节点和关系渲染引擎负责布局。理论上这真的很适合 AI 生成。但问题恰恰出在这里AI 擅长生成“看上去正确的文本”却并不真正理解排版和空间关系。当它没有约束的时候它会倾向于堆节点、堆连线、堆样工因为它的训练数据里充满了这种“什么都想往里塞”的图。1.2 四个典型症状我管它们叫 slop 四件套我看过很多 AI 生成的架构图总结下来slop 的出现基本上逃不出四个问题。第一个是节点失控。一张图动辄一二十个节点所有节点都是一个大小、一个形状看不出模块和模块之间的层级关系。哪怕原始系统逻辑并不复杂画出来之后也像是故意把信息密度拉满。第二个是箭头乱飞。明明可以用graph TD沿着主流程一路向下结果因为缺乏方向约束依赖关系满天乱画两条线之间可以有十几个交叉点读图的人连顺着箭头跟踪调用链路都费劲。第三个是子图缺失。所有节点平铺在一张白纸上服务分组、数据库归属、基础设施边界这些关键信息全都得靠读者自己脑补。第四个是样式噪音。有的模型会在一张图里同时用上五颜六色的节点、加粗字体、多重边框乍一看很“丰富”实际上信息层级反而被完全抹平了。这四个症状单独出现可能还能忍但它们往往是同时出现的。我见过一张号称“订单系统架构图”的渲染结果十六个节点全部挤在一起背景还有一层半透明的底色打印出来根本没法看。我后来把节点数、交叉线数量、子图数量和样式类数量做了个对比问题一目了然维度及格线AI 生成的典型情况节点数建议不超过 12~15经常 18甚至 25子图分组按子系统划分边界几乎没有 subgraph方向一致性主流程方向统一向上向下来回跳标签长度一目了然10 字以内一句话塞进节点样式数量2~3 种即可每个节点一种颜色1.3 病根生成模型根本不理解“空间”为什么 AI 写代码很少出这种“乱麻”状况画图却这么容易翻车因为代码是逐行执行的逻辑AI 只要保证语法和语义基本正确结果就不会太离谱。但图形是二维空间里的排布模型在生成 mermaid 文本的时候对每个节点最终落在画布的哪个位置根本没有概念。它只是根据概率逐个“蹦”出一个又一个节点名再“蹦”出它们之间的连线。mermaid 本身的布局是交给渲染器完成的渲染器会把文本解析成图结构然后按照某种布局算法去做排布。问题是当节点数量激增、连线关系复杂、方向混乱时布局算法的优化空间已经很小了。它只能尽量把交叉减少一点但救不回信息架构上的混乱。也就是说slop 的根源不在渲染器而在生成阶段。这也解释了为什么你让 AI“重新生成一张”大概率得到的是另一种乱法换了个姿势乱得依旧。那个 4 万星项目正是从这一层入手。它不碰渲染器也不要求训练大模型而是强行改变 AI 在生成前的“思考路径”让它先把信息结构理清楚再动手画图。2. 这个 4 万星仓库的破解思路不是修图而是驯化生成源头2.1 项目到底做了什么这个项目我下面统一简称“图净”。它给我的第一印象是“轻”轻到你可以在一小时内读完所有内容但它的价值密度很高。它不是那种需要你引入重量级 SDK 的框架而是一套以规则和提示词为核心的工程方案外加一个轻量校验器。最核心的假设是烂图不是模型能力不够而是模型根本没有被明确告知“什么样的图才算好图”。开发者平时给模型下指令只会说“画一个订单系统的架构图”模型就自由发挥。图净的做法是把画图行为拆成可执行的硬约束先限制信息范围再规定布局策略最后规范样式表达。每一层都给模型几条明确的量化指标而不是“请画得漂亮点”这种模糊短语。让我比较意外的一点是它刻意保持了模型无关。无论你用的是商业模型、开源模型还是本地私有化部署只要模型能理解中文或英文指令理论上都可以接入这套规范。这意味着它不会因为某个模型升级而失效反而成了一种稳定的“中间层”。2.2 三层规则语义层、布局层、样式层图净把画架构图拆成了三个层次我实际用下来觉得每一层都有很强的针对性。第一层是语义层。这个层只回答一个问题图上到底需要出现什么大多数 slop 图之所以乱是因为 AI 把无关细节也塞了进来。比如画用户登录链路模型可能顺手把日志系统、监控系统、消息队列全部拉进来图面不炸才怪。语义层的规则是先列出核心实体和核心依赖剔除旁支细节如果一个实体对主线流程没有直接影响就删掉。第二层是布局层。这个层负责决定“长什么样”。它要求生成前先确定用graph TD还是graph LR并保持主流程方向一致要求把同域概念的节点放进同一个subgraph还要求把节点总数控制在合理范围。第三层是样式层。这个层负责“视觉秩序”主张用统一的classDef定义少量样式而不是让每个节点各穿各的衣服。我把三层规则整理成了一张自查表后续团队接入时可以直接当模板用层次规则示例解决的问题语义层节点数不超过 15删掉旁支节点避免信息过载语义层每个节点标签 3~10 字避免标签堆积布局层先选 TD 或 LR方向统一避免箭头乱飞布局层同域节点必须放进 subgraph明确层级边界样式层全局最多 3 种颜色避免视觉噪音样式层用底色分组代替花哨背景让边界可一眼识别这套规则看起来很朴素但真按它去约束 AI出来的图会明显清爽。它解决的是“生成前没有标准”的问题。以前我们面对的是“碰运气”现在是把运气变成了大概率事件。2.3 校验器从“让 AI 自己看着办”变成“机器可验证”规则说再多模型也不一定每次都遵守。图净特别聪明的一点是配了一个轻量校验器专门用来检查生成的 mermaid 代码有没有违反前面那些硬约束。我记得第一次跑校验器的时候它直接给我报了一堆警告总节点数 21建议不超过 15方向标签混用了 TD 和 LR有 4 个节点没被任何 subgraph 包含。我原本以为“结构乱”是主观审美问题没想到它可以用脚本量化。这很关键因为一旦量化就可以自动化。你完全可以在 CI 流程里加一步让每次变更都自动校验文档里的架构图不合格就拦截合并请求。这种思路让我挺感慨的。它把一种原本靠人肉眼检查的事变成了可重复执行的工程规范。换句话说它提供的不只是一套画图建议而是一个可以内嵌进项目流水线的标准化闸门。3. 顺着这套规范把架构图改到“能直接进文档”的实操过程3.1 第一步先放弃“一张图画完所有系统”的执念很多烂图的源头不在模型而在需求本身。需求方经常希望“一图看懂整个系统”这个愿望可以理解但不太现实。当系统规模超过十几二十个节点时一张图承载不了那么多信息硬塞进去只会变成一张密密麻麻的蜘蛛网。图净给我的第一个启发就是拆。不要试图把调用链、部署关系、数据流全部画到一张图里。一张图只干一件事画调用链就专注画调用链画部署拓扑就专注画部署拓扑。我后来把一个二十多节点的“大全家福”图拆成了入口链路图、服务依赖图、数据存储图三张每张都清爽得多读者也更容易定位自己关心的部分。拆图的时候有一个小技巧先列出所有候选实体然后问自己“如果这张图删掉某个节点读者会不会对主线流程产生误解”如果不会就删。大多数过度膨胀的图删掉三四个旁支节点之后质量会立刻上一个台阶。3.2 第二步在系统提示词里注入结构性约束使用图净的时候不需要额外写太多代码关键是改造你给模型的提示词。我现在的标准做法是在生成 mermaid 之前先让模型输出一段“三行分析”第一行列出核心实体第二行说明实体间的主要依赖方向第三行标记哪些实体属于同一个子系统。分析通过之后再让它开始画图。我会在提示词里明确加上这些约束请用 mermaid 语法生成架构图。生成前先输出三行分析 1. 核心实体有哪些并给每个实体一个不超过 10 字的中文标签 2. 实体之间的主要依赖方向是什么主流程方向选 TD 还是 LR 3. 哪些实体属于同一子系统必须用 subgraph 包裹。 硬性要求 - 总结点数不超过 15 - 子图数量不超过 5 - 全图颜色风格最多 2 种主题色 - 节点标签禁止超过一行。这套提示词我第一次用的时候效果是立竿见影的。同一套系统、同一个模型出来的图从“一锅粥”变成了“有层次的结构图”。没有动用任何高级技巧只是把模糊要求变成了量化条件。这也验证了那个核心观点模型画不好很多时候是因为我们没说清楚什么叫“好”。3.3 第三步渲染自查不要肉眼看代码mermaid 的源码本身不直观一段看上去结构清楚的代码渲染出来可能仍然会有连线交叉。所以我的习惯是生成之后立即用渲染工具转成 SVG然后直接看图判断。我目前用得最多的是mermaid-cli的命令行模式一行命令就能把.mmd文件渲染成 SVG 或者 PNGmmdc -i architecture.mmd -o architecture.svg -b transparent渲染之后我通常会检查三个点第一节点标签有没有被裁切或重叠第二主流程箭头是否大体沿同一方向流动第三相邻子图之间是否还有视觉边界。如果这三个点都没问题基本可以放心放进文档了。在 CI 场景里还可以把校验器和渲染命令接到一起先跑图净的校验脚本检查节点数和子图覆盖再跑渲染确认没有语法错误。这两步加起来通常不到十秒钟但能拦住绝大多数不合格的架构图。3.4 前后对比同样的系统两种完全不同的观感纸上谈兵不如直接看例子。我用一个简化的订单调用链来讲。“未经约束”的典型生成结果会是这样graph TD A[网关] -- B[认证服务] A -- C[用户服务] A -- D[订单服务] B -- E[(用户库)] C -- E D -- F[(订单库)] D -- G[支付服务] H[消息队列] -- C H -- D I[日志系统] -- B I -- C I -- D J[监控系统] -- A J -- B J -- C J -- D K[配置中心] -- C K -- D这段代码视觉上最大的问题是什么节点数量已经接近二十方向一会儿向右一会儿向下所有服务平铺在同一个平面完全看不出哪些属于业务层、哪些属于基础设施层。眼睛盯着它超过十秒就开始走神了。同样内容加入图净的三层约束之后会变成graph TD subgraph 入口层 A[API 网关] end subgraph 业务层 C[用户服务] D[订单服务] end subgraph 基础设施层 E[(用户库)] F[(订单库)] G[支付服务] MQ[消息队列] end A -- C A -- D C -- E D -- F D -- G D -- MQ初看变化不大但你仔细对比就会发现问题节点的数量从十几个降到了核心八个子系统有了明确边界依赖关系全部从网关联动到业务服务再下沉到基础设施。删掉了日志、监控、配置中心这些“旁支”主线逻辑一目了然。两种图在信息表达上差了多远我做了个直观对照项目未经约束经过图净约束节点数量188subgraph 分组03标签长度部分超过 10 字全部处于 4 字以内主流程方向TD/LR 混用统一为 TD阅读成本需要 1~2 分钟理顺约 10 秒读懂我第一次跑完这个对比就把它直接做成了团队内部规范页的封面示例用来告诉所有人“我们要把图画成右边那样而不是左边那样”。4. 这个项目凭什么登顶日榜它击中的是通点更是提效杠杆4.1 从“能出图”到“出好图”这里存在巨大缺口过去两年大家基本都能接受“AI 帮我们写点代码、写点文档”这个设定。但提到 AI 画架构图很多人的反应是“图不太靠谱还得自己调”。这种印象之所以普遍蔓延根源在于大家都默认 AI 能生成图却很少有人把“生成好图”当作一种需要刻意设计的能力。图净从发布到短时间内冲上日榜第一恰好说明这个缺口有多么明显。它解决的不只是一个人画图难看的问题而是把 AI 绘图从“碰运气”变成了“有标准”。当你有了一套标准的时候AI 生成的图不只能看还可以直接作为交付物。这种从“能用”到“可靠”的转变才是它能在开发者社区里迅速传播的真正原因。我身边有一位做技术文档维护的同事以前每周要花大量时间重画各版本接口调用图。接入这套规则之后他把画图任务交给了模型自己只负责审核和分类一周在这件事上的投入一下子从几个小时降到了十几分钟。这种效率变化是最能打动工程师的。4.2 社区把它玩成了“文档基础设施”这个项目最让我惊喜的并不仅仅是它自带的那套规则而是社区拿到它之后的各种“二次创作”。有人把它做成 CI 插件让每次提交代码时自动检查 README 里的架构图有人把它打包成 VS Code 扩展写文档的时候一边写 mermaid 一边得到实时提示还有人把它接到内部系统命名服务上自动把服务名和调用关系喂给模型输出系统拓扑草稿。我一直觉得一个好的开源项目不只是“自己好用”而是要能成为别人手里的积木。图净的规则部分非常薄几乎没有侵入性所以你可以在任何环节引用它、扩展它。这大概也是它能快速在日榜登顶的原因之一它不强迫你改变技术栈而是嵌入你已有的工作流。4.3 我自己的使用边界它不是万能神器热度归热度我还是想说清楚它的边界。图净这套规则对架构图、流程图、时序图这几种常见技术图效果非常明显但它并不是万能的。如果你要画的图超过五十个节点建议先拆图硬套规则也没用如果你要做的是一张美感极强的对外宣传图那我更推荐专门的矢量设计工具因为那涉及审美和品牌风格不是几条硬规范能解决的如果你的内容本身就是复杂运维拓扑需要保留大量基础设施细节那也要谨慎删节点不能为了“好看”把关键信息删丢了。我自己在用的过程中也发现过一个问题模型的“听话程度”不是 100%有时候明明提示词里写了“不超过 15 个节点”它还是会浅露出 17 个。这时候校验器就派上用场了——它不会跟你商量审美只会严格按照阈值给出警告。有几次我盯着警告想了很久才发现它提示得对那几个多出来的节点确实对主线没有增量价值。所以我的定位是把图净当成一个“画图前的思维框架 画图后的质量闸门”。它负责降低噪底真正要对图和系统负责的最后还是人。回头讲一点个人的使用体会。我以前画架构图总想先把布局想好再动手但每次渲染出来还是会这里歪一点、那里挤一点。现在我的思路变了先把“信息边界”和“结构逻辑”告诉模型让它生成一版渲染之后再以读者的视角读一遍只做最小幅度的修正。这一套流程走下来画图的时间反而比过去最熟练的时候还快。如果你也被 AI 画的图折磨过建议别急着换新工具先从控制节点数量和子分组开始把一套最简单直接的画图规范灌进提示词里。改一张最常用但又最乱的架构图你很快就能感受到差别。