看到这个标题的时候我第一反应是GitHub 日榜冠军4万星专治 mermaid slop。这几个词凑在一起说明它踩中的不是小众需求而是过去一年多里几乎所有用 AI 画架构图的人都经历过的那种“看着哪都不对、又说不清哪里不对”的憋屈感。mermaid 本身是好东西能把文字变成图但 AI 生成的 mermaid 图长期处在一种“能看但很水”的状态——节点乱飞、箭头逻辑混乱、子图嵌套随便、方向感全无这就是社区里说的 mermaid slop。这个项目解决的恰恰就是这个问题而且它不是靠一个新的渲染引擎而是靠一套给 AI 的规则。这篇文章我想从 mermaid slop 到底是怎么来的、这个项目做了什么、以及我们普通人如何照搬这套思路画出真正像样的架构图三个层面来拆。如果你平时用 AI 画过系统架构图、拓扑图、流程图或者你的项目文档里有一堆“看着像图但根本没法看”的 mermaid 代码这篇文章值得你花十分钟读完。写作风格会偏“实际操作过的人说话”的味道该给代码给代码该讲坑讲坑。1. 先搞明白mermaid slop 是怎么来的1.1 什么是 mermaid slopmermaid 是一种用纯文本描述图表的语法你写graph TD; A--B它就渲染出一个 A 指向 B 的方框图。mermaid 能做流程图、时序图、状态图、甘特图、架构图尤其是配合各种 AI 代码助手很多人都习惯了直接在对话里说“给我画个订单系统的架构图”AI 就吐出一段 mermaid 代码然后粘贴到编辑器里渲染。问题是AI 给出的图大多经不起细看。节点横七竖八、线条交叉得像一团乱麻、子图里面套子图套了三层、颜色没有任何语义、箭头方向一会儿从左到右一会儿从上到下。我把这种图叫做“mermaid slop”——它看起来像一张图实际上只是一堆节点和线的随机排列。slop 这个词在技术社区本来指 AI 生成的“看起来合理实则废话”的内容套到 mermaid 上特别贴切图照样能渲染但信息传达效率极低。为什么会这样核心原因在于AI 模型对这个任务的认知是“我在生成一段符合 mermaid 语法的文本”而不是“我在设计一张能让人 30 秒内理解系统结构的图”。语法对了图不对格式对了语义不对。这就好比让一个没受过排版训练的人写 PPT他能写出一页一页的字但做出来的东西没有任何视觉逻辑。1.2 为什么这个项目能“专治”它这个项目能短时间冲上 GitHub 日榜冠军、拿到 4 万星不是说它发明了什么魔法算法而是它切中了一个此前几乎没人认真对待的空白AI 画架构图这件事缺的不是生成能力缺的是约束规则。仔细想想mermaid 本身是确定性的——同样的代码永远渲染出同样的图。但 AI 生成 mermaid 代码的过程是概率性的。它猜你的意图然后从概率分布里采样出一段代码。如果你只告诉它“画一个架构图”它自由发挥的空间太大自然会画飞。而这个项目做的事情说穿了就是把“自由发挥空间”压缩到极小告诉你应该给 AI 提供哪些上下文、哪些布局约束、哪些命名规则、哪些样式规范让 AI 的输出从“随机漫游”变成“按图施工”。我在实际使用中最大的感受是4 万星背后不是偶然的营销事件而是需求被精准验证的信号。过去两年的实践里几乎所有团队里那个负责画图的人都经历过“AI 画完我手改两小时”的痛苦。这个项目解决的就是这个问题与其事后修图不如事前约束。2. 这个开源项目到底做了什么2.1 核心定位它不是绘图引擎而是一套“绘图 prompt 规范”要理解这个项目得先放下一个预设不是每个爆火的开源项目都一定是个工具库或框架。这个项目的形态更接近一份“给 AI 的绘图设计规范”外加一批高质量的示例和可直接复制的提示词模板。它的核心资产不是代码而是写在文档里的规则。这套规则最大的特点是它把“画架构图”这件事拆成了几个有先后顺序的阶段先规划信息层级再设计布局再选节点类型再连线最后统一风格。这个顺序很重要因为大多数 AI 生成图的过程是反过来的——它先想到要画哪些节点然后随便排列。这就像盖房子先砌墙再画图纸不塌才怪。还有个细节值得玩味项目里大量提示词不是“请画一张漂亮的架构图”这种模糊指令而是包含了非常具体的要求。比如“节点数量不超过 15 个”“子图嵌套不超过两层”“所有箭头必须有文字标签”“背景色使用统一的色板”。你一看就知道这些都是被真实踩过坑的人总结出来的经验。2.2 四个层次的输出规范这套规范如果压缩成四个层次去看理解起来会清晰很多。第一层是信息层级规划。画图前先问这张图你要表达什么是系统模块之间的依赖关系还是部署环境的关系是业务流程流转还是数据流入库不同目的图的骨架完全不同。项目里反复强调“图的类型决定图的语法”就是这个道理。很多人让 AI 画图翻车是因为自己都没想清楚要画什么图AI 当然只能给一锅大杂烩。第二层是布局方向设计。mermaid 支持TD自上而下、LR从左到右、BT从下到上等方向。这个方向不是随便选的它决定了读者读图的视线路径。一个订单流程的图用TD符合“从上往下走流程”一个微服务调用关系图用LR可能更贴近“从左到右的请求流向”。规范里专门讲了什么时候用哪个方向以及方向错了会带来什么灾难性后果。第三层是语义化命名和分组。节点 id 不要用 a、b、c 这种代号要用user-service、auth-service这种能看懂的表达分组要用subgraph表达清楚边界。AI 输出时经常把所有节点全平铺没有边界概念项目规范要求把属于同一域、同一团队、同一层级的节点明确放到一个子图里。这解决的问题是图一下就能被看懂而不是需要读三遍才能对号入座。第四层是样式与连线的统一。颜色不是装饰是信息编码。用统一色板区分不同类型的节点比如外部系统用灰色、核心服务用蓝色、存储层用绿色箭头表达数据流向虚线表达异步消息实线表达同步调用。样式规范到位之后图的美观度并不是靠“画得好”而是靠“每根线、每个颜色都有含义”。这四个层次本质上是一套“信息设计原则”。我在自己画图时把这四个层次当作清单逐条检查实测下来效果非常明显甚至不需要背诵任何具体的代码模板只要记住这四个层次就能显著提升 AI 出图质量。3. 照着这套思路手把手画一张不 slop 的架构图3.1 动手之前先给 AI 一份“图纸说明”很多人一上来就丢一句“画一个电商系统架构图”给 AI然后期待一颗珍珠。我的经验是在让 AI 画图之前先用文字描述“这张图必须表达什么”。举个例子如果你描述的是“用户从浏览器发起请求经过网关再到订单服务订单服务调用库存服务和支付服务数据写入 MySQL 和 Redis”AI 就有足够的信息规划节点和连线了。你甚至可以在描述后面加上一句把以上描述整理成一个层级清单再生成 mermaid。这一步很关键因为 AI 先生成文字层级、再翻译成图比它直接生成图要稳定得多。这背后的原理很简单语言模型天生擅长处理文本序列信息层级用文字表达是它的主场而 mermaid 代码虽然也是文本但它同时承担了空间布局这个额外维度任务复杂度直接翻倍。我之前做过一个小实验同一个描述只给一句“画架构图”和给了完整层级清单之后前者生成的图中将近三分之一的节点位置是随意的后者基本一次成型。结论很直接AI 画图质量的上限取决于你给它信息的下限。3.2 五条必须写进提示词的金科玉律如果你不想完全照搬那个开源项目的模板又想快速看到效果至少要把以下五条加进你的提示词里。这些是从项目规范和我的实测中总结出来的条条都是硬约束。第一条指定图的方向。在 mermaid 代码第一行写清楚graph TD还是graph LR不要让 AI 自己选。实测中TD是最通用的流程型架构图基本首选LR适合展示请求链路。第二条用classDef统一节点样式。给不同层级的节点定义不同的填充色和边框色。AI 默认生成的节点全是白底黑框图一复杂根本分不清层次。有了颜色图的信息量立刻提升一个档位。第三条用subgraph表达系统边界。凡是属于同一个模块、同一个部署环境、同一个业务域的节点必须放进同一个子图。子图标题就是这张图的第一层阅读索引。第四条每条连线都必须加文字标签。没有标签的箭头只表达了“有关系”有标签的箭头才表达“什么关系”——是调用、是写入、是依赖、是消息通知。这个信息差值非常大图读起来完全不是一个体验。第五条控制节点总数。一张图里不要超过 20 个节点最好控制在 12 到 15 个以内。节点超过这个数量mermaid 自动布局几乎一定会乱。这时候正确的做法是拆分图或者抽象掉非关键节点。下面是一段我常用的模板你可以直接复制改一改就能用graph TD classDef core fill:#e3f2fd,stroke:#1565c0,stroke-width:2px; classDef data fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px; classDef external fill:#f5f5f5,stroke:#616161,stroke-width:1px; subgraph client_layer[客户端层] U[浏览器/APP] end subgraph app_layer[应用层] GW[API网关] US[用户服务] OS[订单服务] PS[支付服务] end subgraph store_layer[存储层] DB[(MySQL)] RD[(Redis)] end U --|HTTPS| GW GW --|路由| US GW --|路由| OS OS --|调用| PS OS --|读写| DB OS --|缓存读写| RD class U external; class GW,US,OS,PS core; class DB,RD data;这段代码清晰地表达了一个典型电商下单链路客户端层、应用层、存储层的边界很明确箭头都有语义颜色做了类型区分方向是自上而下的流程顺序。同样的系统如果用 AI 默认方式生成大概率是十几个节点横七竖八堆在一张图里根本没有这个效果。3.3 从 slop 到能看的改造实验为了让你更直观地感受差异我给你描述一下“slop 版”的典型代码是什么味道节点 id 用 A、B、C、D全部平铺在一个层级里没有子图方向是 AI 随机挑一个默认值节点之间用没有标签的箭头随便连整个图渲染出来就像一张蜘蛛网。改造思路就三步。第一步把 A、B、C、D 改成语义化 id比如auth-service、order-service。第二步把逻辑上属于同一组的节点用 subgraph 包起来比如把两个服务放进“应用层”把数据库放进“存储层”。第三步给主要连线加标签注明“调用”“写入”“读取”。三步做完哪怕节点数量完全没变图的可读性都会有质的飞跃。改造后的 mermaid 代码就是这个项目规范最核心的价值——它不给 AI 自由发挥的空间而是用规则限定出一条最优路径。我在一次实际文档整理中用这套方法把一张原本 30 分钟都看不懂的旧图重构成了 10 秒能看懂的新图当时就觉得这套方法值回我全部的关注和学习时间。4. 容易踩的坑AI 画图时常见翻车现场4.1 节点 id 用中文还是英文这是我一上来就踩过的坑。让 AI 画图时很自然就写了中文节点名比如“订单服务”。渲染没问题但一旦图复杂起来问题就出来了中文 id 在 mermaid 语法中需要引号包裹而且很多 mermaid 版本对中文 id 的链接支持不好会导致某些关系连线断掉。更关键的是id 是图内部的唯一标识如果你后面还想修改、还想要代码可维护性用中文 id 会很难受。在项目规范的启示下我的习惯是id 用英文语义化命名如order-service展示文本 label 用中文如订单服务。这样既保证了代码层面的稳定又保证了图读起来符合中文读者的直觉。说出来你可能不信就这一个改动就把我生成的图出问题概率砍掉了一大半。mermaid 代码里写法是graph TD OS[订单服务] -- DB[(MySQL)]节点变量名是英文双引号里是显示出来的中文名。这个习惯一定要养成。4.2 子图嵌套太深就是灾难subgraph 是分组利器但嵌套层级一深布局就很容易乱。我在实践中反复遇到AI 喜欢在一个大的 subgraph 里面再套 subgraph套到三层四层渲染出来一团乱麻。这不是 AI 的问题是 mermaid 引擎本身对深层子图的布局支持没那么强。经验法则子图嵌套不要超过两层。如果确实需要表达三层结构那就拆成两张图来表达或者通过节点前缀模拟层级关系。另外subgraph 的 id 也不能用中文和节点 id 一个道理。我见过太多因为 subgraph 命名不规范导致渲染错乱的案例基本都属于这一类。还有一个隐藏细节subgraph 之间的连线方向性经常不可控。比如你想表达跨子图的调用关系从子图 A 的节点指向子图 B 的节点渲染出来可能会横穿多个其他子图线条绕来绕去。我的解决方式是把跨子图连线数量降到最低能通过边界表达的信息不要在连线里重复。4.3 连线交叉是后话先看数据流向很多人在画图时纠结“怎么让线条不交叉”我的答案是这个纠结顺序反了。架构图的第一要务是信息表达清晰线交叉是次要问题。如果图的信息层次本身合理线条交叉带来的视觉干扰基本可控。mermaid 的布局引擎是自动的你不能手动去挪节点位置。但你可以通过调整节点的书写顺序来影响布局结果。一般来说mermaid 会按代码里出现的顺序进行排布先写的节点靠上/靠左后写的靠下/靠右。利用这个特性你可以把主链路的节点写在前面把辅助节点写在后面这样主链路会更显眼。如果图实在复杂到无法避免交叉请记住这不是 mermaid 的能力上限是你信息设计的问题。回到第三节说的——把图拆细或者抽象节点。我试过把一个 40 个节点的图拆成 4 张 10 个节点的子图阅读体验完全变成了两回事。4.4 常见问题速查表拿一张表格帮你快速排查都是我实测里反复出现的坑建议截图收藏现象原因解决方案节点全部平铺、没有层级没有加 subgraph给同域节点加 subgraph 分组线条交叉严重节点数量太多或书写顺序混乱控制节点数、主链路先写箭头没有文字没有给连线加 label给关键连线加|调用|标签所有节点一个颜色没有定义 classDef用 classDef 区分类型id 是中文导致渲染断连mermaid 对中文 id 支持不稳id 用英文、label 用中文子图嵌套深层布局错乱子图层级太多保持最多两层或拆图图上方向看不懂没有明确 graph 方向第一行写死graph TD或graph LR节点大小不一、很乱没有统一样式定义全局样式或 classDef以上问题里90% 只要改变生成时的提示词就能规避。这就是这个开源项目给整个圈子最大的启发——解决问题不是靠容忍生成结果再手动修而是靠前置约束让生成结果从一开始就是对的。5. 这个项目给我带来的启发5.1 AI 辅助设计的本质约束比创意更重要用过一段时间 AI 画图之后我悟到一个可能跟主流直觉相反的道理和 AI 协作时约束比创意重要得多。你给 AI 的每一句限制都能换来一档稳定的质量提升反过来你给 AI 越多自由它就越多犯错。这背后的逻辑不复杂。AI 模型本身已经是“绕开约束”的专家了它在你给出的内容领域内进行各种语言模式组合组合的多样性由你提供的上下文决定。如果你画图时的上下文只有“画一张架构图”这一句话AI 只能从它见过的浩瀚图种里随机选一个模板自然就变成了 slop。反过来你把五条金科玉律写进提示词AI 就没有发挥空间了它只能在十几个节点、两层子图、几个颜色的框架里做文章——这个空间是足够小的小到每次输出都在合格线以上。这个项目的火爆本质上就是这种“约束思路”的胜利。4 万星的讨论量级代表的不只是 mermaid 用户的需求更是整个 AI 辅助创作用户群体对“可控输出”的普遍渴求。5.2 别让收藏夹吃灰试着动手做一次我见过太多这样的场景刷到这个仓库点了个 star然后收藏夹里吃灰。4万个 star 里可能有一半用户没有真正打开过文档。这太可惜了因为这项目是那种“十分钟就能见效”的类型不需要搭建、不需要安装、不需要修改环境依赖你只需要打开一个新的对话把它的规范丢进去然后画一张图看看。想快速验证这套思路的价值只需要三步。第一步找一张你过去画得很烂的架构图不限 mermaid 都行。第二步用第三节的五个约束把它翻译成一段有规范意识的 mermaid 代码。第三步对比前后差异。做完这三步你自然就理解了为什么这套规范值得收藏。如果连旧图都不想找就拿一个最熟悉的东西练手你负责的系统、你们部门的内部服务或者一个普通的电商下单流程。用模板加进出处理异常情况马上就能感受到差别。5.3 下一步值得研究的延伸方向这个项目给我的另一个启发是它可以延伸到很多领域。比如把它的规范沉淀成团队的“绘图编码规范”让所有写文档的人统一风格。比如配合 CI 系统做一个文档里 mermaid 图的质量检查器——mermaid 本身是文本文本是可以 lint 的如果节点数超过 20 就告警如果子图嵌套超过两层就提示。听起来很像代码检查工具确实就是这个方向。还有一个方向是和其他可视化工具结合。现在很多人用 AI 生成各种图表不局限于 mermaid还有 Python 的可视化库、前端图表库。如果把这套“先规划、再布局、再样式、再语义”的方法论迁移过去同样能提升出图质量。我在实际实验中也发现把这种约束式提示词套用到前端数据可视化上生成的图表质量也明显高于“画一个好看的折线图”这种模糊指令。我个人在实际操作中的体会是这个项目火不是因为它有什么深不可测的东西而是因为它提供了一种可复制的、人人都能用的确定性。它让你从“AI 画的图能不能用就看命”变成“AI 画出来的一定合格”。确定性这个东西在 AI 时代是稀缺资源谁掌握了它谁就掌握了生产力。所以如果非要给一条建议我的建议是别只盯着那个 star 数看花十五分钟照着规范画一张图你对 AI 画架构图这件事的认知就会彻底不一样。