前天下午我对着屏幕发了二十分钟呆。AI画出来的那张架构图节点像摊了一地的麻将牌箭头互相打架核心服务藏在角落我这个画图的人自己都没看懂。更糟的是这种状况在最近半年越来越常见圈里人给这种“AI生成、看起来能用、实际上结构混乱”的图起了个专门的名字mermaid slop。直到朋友甩了个链接给我说有个开源项目专治这个问题上线没多久就拿了代码托管平台日榜冠军仓库星标一路涨到4万。我抱着怀疑态度把它跑了一遍结果第一次就把我那张废图洗干净了。这篇博文就把我从问题到原理、从上手到接入工作流的完整过程写下来给同样被AI画图折磨的读者一条现成的路。1. mermaid slop到底犯了什么病AI画架构图的四个典型问题“slop”这个词最早是从海外开发社区传出来的泛指AI生成内容里那种“量很大、看着合理、实际上没什么营养”的部分。落在Mermaid上就是AI画出来的流程图、架构图、时序图怎么看怎么别扭。语法没错逻辑也基本通但就是让人看不下去。我总结了一下AI产出的这类烂图大概逃不出四个典型问题。1.1 面条式连线看得懂起点找不到终点大模型画Mermaid的时候本质上是在做“token预测”它根本看不到最终渲染出来的画布坐标。所以它理解节点A和节点B之间“有关系”但不会考虑这条线画出来之后会不会穿过其他节点、会不会和别的线叠在一起。我见过最离谱的一张图一个核心模块被连出了十六条边分别指向认证、缓存、日志、告警、消息队列……渲染出来活像一盘煮过头的意大利面。箭头朝哪个方向都有几条长连线从图的最左边一路横穿到最右边中间把两个子图拦腰截断。这种图的致命伤在于你明明知道每个节点都有意义可你就是找不到一条能顺着走完的路径。阅读成本奇高等于图白画了。1.2 节点语义失衡所有东西都堆在同一个平面真正的架构图是有层次的入口在前面网关在中间核心服务在底层基础设施在最下面。但AI不太具备这种分层意识它更习惯按照依赖顺序把所有东西平铺出来。用户请求、登录鉴权、权限判断、订单服务、支付回调、数据库、Redis、日志采集……从头到尾排一条长龙谁也不属于谁。结果就是整张图没有任何边界感读者分不清什么是主链路、什么是旁路支持、什么是底层设施。尤其是一张图超过三十个节点之后人脑根本处理不了这种扁平的信息流。好的架构图应该是能“分层阅读”的先看大框再钻细节而AI画出来的大多是一马平川。1.3 标签比节点还长细节全塞进图里这个我特别有体会。我让AI画一张订单处理流程图它写出来的节点名长成这样“对用户提交的订单数据进行规则校验并且返回校验结果给上层服务”。打印出来之后光这一个节点就占了图上一大块地方边框里塞满了字字号被压缩到看不清。Mermaid的节点标签本来就适合放短语不适合放句子。详细说明可以用注释、可以用附注甚至可以放在正文里展开但AI偏偏喜欢把所有描述性内容都堆进节点里。渲染出来的图信息密度过高等于每个节点都成了一个小文档拼在一起就是一场灾难。1.4 语法层的暴力施工subgraph和style用得不像话还有一种更隐蔽的烂出现在代码层面。AI为了显得“层次分明”会大量使用subgraph、classDef、style这些语法但用得毫无章法。有的图里subgraph嵌套了四层边框一个套一个渲染完了根本看不清里面是谁有的图里style指定了几十种颜色不同模块用了一堆深浅不一的蓝色毫无统一性可言。这种图放在文档里就是一颗定时炸弹你想调整一个模块的颜色改动一处可能连带炸掉三个子图的样式。维护成本比重新画一张图还高。这也是为什么大家越来越觉得这类输出是“slop”——它不是不能用而是你一旦想拿它做事就得花成倍的时间去擦屁股。2. 这个开源项目的底层逻辑把架构图当成代码来审查和重写理解了上面四种病再看这个项目你才会明白它为什么能火。它做的事不是“再出一张新图”而是“把现有图当成代码做一次代码审查和重构”。整个设计分三层思路非常清楚。2.1 为什么不能简单交给“AI再改一遍”按直觉想到的第一个方案肯定是把AI画出来的图再丢回给AI让它自己改。我试过效果非常不稳定原因是大模型重写一次就等于重新生成一遍它可能把之前的错误改好同时也可能把之前正确的语义改歪。而且多跑几轮经常碰到输出格式变化、层级被重排、子图结构丢失这些事。一次生成的图拿给另一个模型修改结果几乎不可控。所以这个开源项目选了另外一条路基于规则引擎做确定性修复。也就是说同样的输入给进去永远得到同样的输出。这个确定性对工程环境极其重要。你要把它接进文档流水线或者CI里做自动化检查就必须保证工具的行为是可预期的。2.2 第一层AST解析保住语义再动手它处理Mermaid代码的第一步是把文本解析成抽象语法树也就是AST。这一步用的是Mermaid官方解析器不是正则暴力匹配。为什么要强调这个因为只有真正理解了“哪个节点连接哪个节点”、“哪个子图包含哪些节点”后续的重写才可能在语义不丢失的前提下进行。我一开始也担心这种自动化工具会不会把用户的手写注释、自定义样式全部抹掉。实测下来不会因为在AST层面注释和样式都是独立的语法节点工具只操作它认准的那几个类型其他内容原样保留。这比用正则替换的老式脚本靠谱一个量级。你写一句“这里负载均衡需要特别关注”它不会给你删掉。2.3 第二层可读性诊断给slop打分它内置了一套可量化指标专门用于评估一张Mermaid图“烂到什么程度”。我印象比较深的有这么几个指标名称判定逻辑对应问题节点出度/入度超过阈值就标记为枢纽节点面条式连线边节点比例超过一定比例说明图中边过多连线纠缠标签平均长度超过预设值提示拆分标签过长子图嵌套深度超过两层提示过度嵌套语法滥用分层断裂点找不出清晰层级关系节点语义失衡诊断阶段会输出一份报告告诉你哪些区域属于“重度slop区”哪些可以保留。这一步我觉得特别有价值因为它把“丑”这件事量化了。有了得分你就可以把它接进自动检查流程里而不是靠人眼一张张看图去判断。说句实话在代码评审里加一条“这张图slop分数超过75请重新生成”比让同事写八百字的好看多了。2.4 第三层规则化重写改得干净而且能算账诊断完成之后重写策略也是规则驱动的常见操作包括把出度过高的核心节点拆成子图把过长的标签截断成短语并把详细描述挪到注释里统一整张图的布局方向清理冗余的样式定义。因为每一步都是可解释、可配置的所以你可以通过调整参数来控制重写力度。比如我本地就把“最大出度”设成6超过6的节点全部建议拆分“最大标签长度”设成20个字符超过自动截断。这种透明性让整个工具用起来很安心你知道它动你图的哪些地方不知道就翻配置。相比之下你让AI再改一遍它改了哪里你根本无从追踪。3. 亲自上手把我被AI画废的架构图交给它修复前面讲完原理下面说实操。我用一张真实场景里被AI画废的订单系统架构图做测试完整走一遍安装、诊断、重写、检查的流程。这套流程你现在打开电脑就能照做。3.1 安装和第一条命令从npx开始最快这项目是Node生态的所以我最推荐的方式是直接用npx跑不用全局安装也不用为版本冲突头疼。命令长这样npx mermaid-slop-cleaner --input messy.md --output clean.md只要本机有Node环境这一条就能跑通。我建议第一次用的时候先加一个--dry-run参数只让它输出诊断报告不实际写文件。这样你能先看到问题清单再决定要不要让它重写。对于不想折腾命令行的人它还有个网页版入口把Mermaid代码粘进去直接出诊断结果和优化建议适合偶尔用一次的场景。3.2 完整修复流程输入、诊断、重写、检查我测试用的图是一张四十多个节点、上百条边的老式微服务调用图。AI生成的时候还自作聪明加了大量subgraph结果整个图几乎没法看。跑完诊断报告得分惨不忍睹核心模块出度16标签平均字数接近35子图嵌套三层边节点比例超过1.8。真正执行重写之后输出文件变成了十八个节点、二十三条边整个结构被重组为“入口层、网关层、核心服务层、数据层”四个子图。长标签被替换成短词详细说明被移到每段后面的注释里一眼能看出主链路是用户请求、鉴权、订单处理、支付、回写数据库。修复前后的代码文本差异我用普通文本方式截一段给你感受一下修复前大概是这样的flowchart TD A[用户发起下单请求到达订单服务前置网关] -- B[身份认证服务模块] A -- C[权限控制中间件] B -- D[从用户信息缓存中获取当前用户基础资料] C -- D D -- E[订单服务调用库存服务完成库存预扣] ...修复后变成flowchart TD A[用户请求] -- B[网关层] B -- C[认证服务] C -- D[订单核心服务] D -- E[库存预扣] E -- F[(数据库)]这个对比放在眼前你立刻能明白这款工具的价值。最重要的是它没有改变原始语义节点和边的关系还是那套只是换了一种更有层次、更克制的表达方式。3.3 把工具接入日常写作流程AI出图后自动清洗跑通了单次修复之后我很快把它接进了自己的文档工作流。现在我的标准操作是让AI先生成Mermaid原文然后跑一遍--dry-run看诊断报告成绩合格才允许直接使用不合格就自动重写再把重写后的版本丢回编辑器里检查一眼。整套过程用一条脚本就能串起来mermaid-slop-cleaner --check docs/**/*.mmd --threshold 75这个命令会扫描目录下全部Mermaid文件任何slop得分超过75的文件都会直接让脚本返回非零状态码。在文档项目的CI流水线里加上这条等于给AI生成的架构图装了一道门禁不合规就不允许合入。我实际跑到现在团队里新出现的“丑图”数量下降得非常明显人工review的工作量至少少了一半。3.4 想少产出slop提示词里可以写什么工具再强也只是补救我更建议从源头减少slop的产生。这里分享一段我反复在用的提示词模板实测能让AI第一次输出的图就顺眼很多“用不超过6个核心节点描述整体架构层次”“每个节点标签不超过12个字详细说明写在注释里”“只允许两层subgraph嵌套禁止第三层”“只画主链路不要把所有细节都画进去”“节点方向保持一致从入口到出口单向流动”这几条的本质是给AI限定生成范围。架构图最忌贪多求全范围越小越容易画清楚。我切身体会事先限制生成范围比事后拿工具清洗更省事两件事配合起来效果最好。4. 冲上日榜冠军不是运气这波热潮背后的三个信号项目能火当然有技术因素但更值得聊的是它爆火背后透露出的行业信号。一个专门处理“AI画图太难看了”的工具凭什么能拿到4万星凭什么能冲上日榜第一我复盘下来原因至少有三层。4.1 AI工具铺开带来的“新式脏活”现在主流AI助手基本都会生成Mermaid了用户群体也从资深开发者一路扩展到产品经理、运营、数据分析师。会画图的人多了图的质量却参差不齐因为大部分人把AI生成的Mermaid当成成品直接贴进文档根本没有二次整理的意识。一个本来应该靠人来把关的环节现在变成了无人照看的盲区于是mermaid slop开始泛滥。这个开源项目恰好踩中了时间窗口。它解决的不是一个被讨论很久的老问题而是AI工具普及之后刚冒出来的“新式脏活”。在代码托管平台上这类紧跟时代痛点的工具本来就容易获得传播因为它让大量用户产生了“这就是在说我”的共鸣感。4.2 开源仓库的雪球效应用户提的问题比star更像路线图项目冲上日榜之后star数量涨得飞快但真正让它稳住的是用户持续反馈的需求。很多人第一次用完之后会在issue里追加自己的真实场景有人要把清洗后的结果导出成SVG有人想让它支持时序图和状态图有人需要更细粒度的规则配置以便贴合自家文档规范。这种反馈循环对开源项目特别重要。用户提的需求越具体项目维护者就越清楚该往哪个方向发力版本更新也更有针对性。你会发现star只是一个数字真正撑起这个项目的是围绕“mermaid slop”形成的用户共识。大家并不是为了点赞而点赞而是真的希望这个工具能在自己的场景里继续发光。4.3 我的结论把这个工具当质检员别当设计师我不建议你把它当成一个能“设计出好架构”的工具。它做不到也不会做。它能做的是守住下限不让那些结构混乱、标签冗长、连线纠缠的图进入你的文档仓库。真正的架构设计、分层权衡、模块划分还得靠人自己动脑。现在它对我的定位就是一个质检员站在AI和正式文档之间专门拦那些不合格的半成品。这个位置刚好是AI工作流里最缺的一环也是所有被AI画图折磨过的人最需要的功能。对一个上线没多久的项目来说能精准卡住这个位置它能冲上日榜冠军我一点也不意外。我现在的习惯是所有AI生成的Mermaid文本先过一遍工具再渲染等于给AI输出加了道质检工序。那条提示词模板也存成了常用片段每次让AI画架构图之前先丢给它。如果你也经常被项目文档里的架构图折磨这套流程应该够你用了。最后提醒一句架构图好不好看只是表象文档和系统里真正难以维护的复杂性才是需要长期治理的东西。工具能帮你把图变干净但真正画出一张“有重点”的图终究要靠你对系统的理解。这句话送给所有用AI画图的人。