写这篇文章的起因其实很简单最近在做一个有状态流转的回单系统时纯靠文字跟 AI 对齐需求来回改了七版每次它都自信满满地给我一段逻辑完整的代码一跑就翻车。后来我把交互流程先用 Mermaid 画成图再让 AI 照着图写一次就过。从那以后我的 AI 编程习惯彻底变了——凡是涉及分支选择、状态流转、多模块协作的需求我都先把思维画成Mermaid再拿图去跟 AI 对话。这套做法我把它叫做可视化的思维协议。Mermaid 本身不是什么新东西一个把文本转成图表的工具而已但在 AI 编程这个场景里它的价值被完全放大了。它弥补了人类空间化思维与大语言模型线性文本处理之间最致命的那道鸿沟。这篇内容我会把完整的应用范式拆开讲清楚从为什么需要它到核心落地模式再到一个能直接抄走的实操项目最后是几个我踩过的坑和对应的排查技巧。适合正在用 AI 辅助开发、但总觉得差点意思的工程师参考。1. 为什么 AI 编程需要可视化的思维协议先说一个被很多人忽略的事实大语言模型本质上是一个文字接龙机器。你给它一段文字它预测下一个词再预测下一个词。这决定了它对整体结构的感知是隐式的、逐步推算出来的。而人脑不一样人理解一个系统时脑子里出现的是图方框、箭头、分支、循环、依赖关系。这是结构化的、空间化的思维。这两者之间天然存在一个表达带宽问题。你用文字描述一个流程比如用户下单后要先校验库存库存够的话再走支付支付成功后发送消息失败则回滚库存并返回错误提示这句话 AI 能听懂但它理解的是线性推进关系而不是带状态、带分支、带并发条件的流程图。一旦逻辑复杂到十几个节点、四五个分支条件文字描述就会产生歧义——这个分支到底是从哪个状态出来的异常路径和正常路径会不会重叠顺序敏感还是状态敏感Mermaid 在这里扮演的就是一个思维翻译层。它把人类脑子里的图用一套严格的、文本化的语法表达出来。这套语法足够简单人写起来不费劲AI 读起来也无歧义。更重要的是Mermaid 是文本text 是可以进 prompt、可以进上下文、可以被 diff 的。你不需要贴一张截图给 AI 看——直接贴上 Mermaid 源码它就能精确解析出节点、边、分支、循环、状态关系。我拿同一个需求做过对比实验。需求是一个带超时确认的审批流程。用纯文字描述让 AI 写代码它给出的方案里超时逻辑和人工审批逻辑经常会出现竞争条件甚至在超时后用户还能操作。但把同样的需求画成 Mermaid 状态图丢给它AI 生成的代码结构直接就对了超时是一个独立的状态迁移事件和人工审批互斥边界非常清晰。这就是我最想强调的第一件事跟 AI 协作写代码不是你说话它就能懂而是要给它一个它天然擅长解析、且能无损保留你空间思维的结构化中间表示。Mermaid 恰好就是这个中间表示。它相当于你和 AI 之间约定好的一套思维协议。1.1 文字、代码、Mermaid三者的信息密度对比为了说清楚这个协议为什么有效我列过一个简单的对比表达方式信息密度歧义程度AI 友好度人可读性自然语言描述低高中高伪代码中中高中Mermaid 图源码高极低极高高注意Mermaid 可读性高有一个前提它必须是源码形式而不是渲染出来的图片。图片给人看很直观但给 AI 看就没法直接解析了。所以我的习惯是凡是给 AI 看的图一律贴源码渲染好的 PNG 只留给自己做人眼确认。还有一个细节很多人没意识到Mermaid 源码进 git 之后每次改动了哪些节点、哪些路由diff 清清楚楚。你用文字描述需求改没改、改成啥了只能靠人脑对比——但图不一样图的演进历史就是项目的演进历史。这个特性在长周期项目里价值极大后面我会专门讲到。2. 我把 Mermaid 用进 AI 编程的五种核心模式经过一段时间实践我总结出五种最值得拿 Mermaid 跟 AI 协作的场景。不是所有代码都适合画图但这五类画图和不画图的效果天差地别。2.1 流程图拆解业务流程让 AI 按图生成代码骨架这是最基础、也最常用的模式。当你拿到一个需求第一件事不是在编辑器里招架构而是把业务流程画成 flowchart。流程图的每个节点对应一个函数或一个模块每条边对应一次调用或一个返回。举个例子。一个模拟订单退款系统核心流程是用户发起退款申请系统校验订单状态校验通过走财务回调财务回调失败进入重试队列重试超过三次标记人工介入画成 Mermaid 就是flowchart LR A[用户发起退款] -- B{订单状态校验} B --|有效| C[财务回调] B --|无效| Z[返回错误] C --|成功| D[退款完成] C --|失败| E[进入重试队列] E --|重试次数 3| C E --|重试次数 3| F[人工介入标记]这段源码丢给 AI配合一句按这个流程图生成服务端代码每个节点对应一个独立函数它生成的代码就是模块化的、单向依赖的、边界清晰的。而如果你只写一句话帮我写个退款功能你得到的就是一大坨 if-else 糊在一起的代码。2.2 状态图处理状态机类逻辑专业的事交给专业的图流程图能表达先后顺序但表达不了状态之间如何迁移。比如订单有待支付、已支付、已发货、已完成、已取消这些状态从已支付能不能到已取消哪些事件触发哪些迁移这种逻辑用 flowchart 硬画会很别扭这时候要用 stateDiagram-v2。AI 在解析状态图方面简直就是天赋异禀。因为状态迁移本质上就是事件 - 条件 - 新状态的三元组这跟软件工程里的状态模式、状态机引擎、甚至数据库中的状态字段流转是同构的。你给它一张状态图它写出来的状态机代码几乎不需要改。我给你看一个新版状态图的写法stateDiagram-v2 [*] -- 待支付 待支付 -- 已支付: 支付成功 待支付 -- 已取消: 用户取消 已支付 -- 已发货: 商家发货 已支付 -- 退款中: 用户申请退款 已发货 -- 已完成: 确认收货 已发货 -- 退款中: 售后发起 退款中 -- 已退款: 退款成功 退款中 -- 待人工处理: 退款异常 已取消 -- [*] 已退款 -- [*]注意里面每一条迁移都带了一个事件标签。我给 AI 的指令是把这张状态图翻译成 TypeScript 类型定义加一个状态机实现迁移事件作为 action 命名。这个组合拳打下来状态机相关的 bug 基本绝迹。以前用文字描述这种逻辑AI 经常自己脑补出一些不存在的迁移关系比如待支付直接到退款中有了状态图它想脑补都补不出来——边上就那么几条它不会乱加。2.3 时序图搞定跨模块协作减少接口对齐来回拉扯多模块、多系统协作的时候最大的痛点是每个模块之间怎么调用、谁先谁后、回调怎么处理。这种场景时序图比任何文字描述都管用。Mermaid 的 sequenceDiagram 可以轻松表达参与者、消息、嵌套调用和返回。举个例子模拟一个对接第三方支付渠道的场景sequenceDiagram participant U as 客户端 participant S as 服务端 participant P as 支付渠道 U-S: 创建支付订单 S-S: 生成订单号落库 S-P: 发起支付请求 P--S: 返回支付凭证 S--U: 返回支付链接 U-P: 打开支付页面完成支付 P-S: 异步通知支付结果 S-S: 校验签名更新订单状态 S--U: 推送支付成功消息把这段源码丢给 AI它就能清楚每个接口该由谁提供、谁消费、是同步还是异步。我实际测过用这种时序图驱动编写接口层代码AI 生成的接口签名和调用顺序基本一次就对了。而用文字描述它经常把回调接口的实现体乱分配该服务端做的逻辑塞给了客户端。2.4 类图/架构图定义领域模型与依赖关系涉及领域建模、模块拆分的时候classDiagram 派得上用场。虽然 Mermaid 的类图能力比不上专门的 UML 工具但对 AI 编程来说已经完全够用。classDiagram class Order { string id string status money totalAmount calculateTotal() completePayment() } class OrderItem { string productId int quantity money subtotal } class Payment { string channel string txnId refund() } Order 1 -- n OrderItem Order 1 -- 1 Payment这个类图直接驱动 AI 生成数据模型和领域对象。我一般会让 AI按这个类图生成数据库表结构设计和对应的实体类代码。由于类图自带关系、自带属性AI 生成的表结构往往连外键关系都合理。以前纯文字让它设计表它总是忘记加关联索引有了类图这个概率大大降低。2.5 思维导图用 Mermaid 做需求拆解与任务规划最后一种模式比较跳脱但非常实用——用 mindmap 来拆解需求、做任务规划。有了它AI 编程不再局限于代码生成还能延伸到项目规划。mindmap root((订单退款模块)) 退款入口 申请表单 校验规则 业务逻辑 库存回滚 财务回调 消息通知 失败处理 重试队列 人工介入 数据变更 退款记录 订单状态这种图的用法很特别不是给 AI 当 prompt而是给自己当思维脚手架。我会先在 Mermaid 里把需求拆成树状结构然后再基于这棵树去写 prompt。这样做的好处是需求拆解和代码生成分离先想清楚要做什么再让 AI 想办法怎么做。很多 AI 编程翻车的原因不是 AI 能力不行而是你自己也没想清楚要什么。思维导图帮你把没想清楚的问题前置暴露出来。3. 深度实操一个完整的 Mermaid 驱动 AI 编程项目示例理论说得再多不如完整走一个项目。我用一个模拟的库存扣减与回滚功能来做演示。这是一个非常典型的、又容易出错的逻辑非常适合拿来讲 Mermaid AI 编程的完整链路。3.1 第一步把需求拆成流程图需求背景用户购买商品后系统需要扣减库存。如果后续支付失败或用户取消订单需要回滚库存。我一开始先在白板或者说 Mermaid 编辑器里画出流程图重点标出三个关键分支库存足够、库存不足、并发冲突。Mermaid 源码如下flowchart TD A[收到订单创建请求] -- B{库存查询} B --|库存充足| C[预占库存] B --|库存不足| Z[返回库存不足错误] C -- D{支付调用} D --|支付成功| E[确认扣减] D --|支付失败| F[回滚预占库存] F -- Z E -- G[完成]画图的过程本身就是思考的过程。我在画的时候就会发现一个之前忽略的问题预占库存和确认扣减是两个动作它们之间如果程序崩溃了怎么办这就引出了一个关键的容错设计问题。这个洞见如果我没有画图直接写 prompt是绝对暴露不出来的。3.2 第二步把 Mermaid 图作为核心上下文构造精确驱动指令有了图接下来就是写 prompt。我总结出一个高复现率的提示词模板你是资深的后端工程师。下面是一个库存扣减与回滚的流程图每个节点代表一个明确的业务动作每条边代表调用关系与条件分支。 请按以下要求生成 TypeScript 代码 1. 图里的每个节点对应一个独立函数函数名自拟但必须在注释里标注对应节点编号。 2. 图里的每个分支条件对应一个明确的返回值类型用联合类型表达。 3. 预占库存和确认扣减之间需要能应对进程崩溃的情况请设计一个补偿机制。 4. 并发扣减时确保库存不会变成负数。 流程图源码 flowchart TD A[收到订单创建请求] -- B{库存查询} B --|库存充足| C[预占库存] B --|库存不足| Z[返回库存不足错误] C -- D{支付调用} D --|支付成功| E[确认扣减] D --|支付失败| F[回滚预占库存] F -- Z E -- G[完成]注意几个关键点。一是每个节点对应一个独立函数。这句话极其重要。如果不加这句AI 会把整个流程图压缩成一个函数里面一堆 if-else。加了这句它自然就会把代码模块化。二是把补偿机制单独作为硬性要求。这不是流程图里有的内容而是我画图时暴露出来的设计盲区。流程图负责表达业务流程prompt 里的额外要求负责表达非功能性需求。二者各司其职。三是注意给 AI 一个自由发挥的许可它需要在节点之外自行补充异常处理逻辑。实操中我发现如果你过度强调照着流程图写AI 会变得畏首畏尾该加的 try-catch 也不加了。所以 prompt 里最后要加一句允许在图中未显示的边界情况下增加防御性代码。3.3 第三步校验 AI 产出代码与图的对应关系AI 生成代码之后最关键的环节来了必须校验代码和流程图之间的映射关系。我一般会让 AI 自己生成一份映射清单请为刚才生成的代码输出一份节点对照表格式为表格函数名 | 对应节点 | 职责说明这一步非常有效。AI 在输出对照表的过程中会自己发现自己哪里对不上很多时候它甚至会主动修正代码。这个过程我称之为让 AI 自省。它比你自己一行行读代码找问题高效得多。最终生成的代码函数结构大致会是createOrderAndCheckStock()对应节点 BreserveStock()对应节点 CconfirmDeduction()对应节点 ErollbackReservedStock()对应节点 F每一个函数的职责边界清晰到不可思议。你甚至会怀疑这是不是 AI 写的代码——不它只是忠实地把你的流程图翻译成了 TypeScript。3.4 第四步用状态图补充边界情况流程图画完了代码也能跑了但我觉得还不够。因为流程图表达的是主要路径 部分异常路径它没覆盖系统在运行过程中发生状态迁移这层逻辑。尤其是库存扣减它的状态不是流程跑完了就结束而是在不同状态之间跳转。所以我又补了一张状态图stateDiagram-v2 [*] -- 待预占 待预占 -- 已预占: 预占成功 待预占 -- 预占失败: 库存不足 已预占 -- 已扣减: 支付成功 已预占 -- 预占回滚: 支付失败/超时 预占失败 -- [*] 预占回滚 -- [*] 已扣减 -- [*]把这张状态图也丢给 AI让它根据状态图检查生成的代码是否覆盖所有迁移并补齐缺失的状态处理。这一步直接让它抓出了一个 bug原来的代码在支付超时场景下没有触发预占回滚因为超时本质上是个异步事件流程图里根本没法表达这种事件驱动的迁移。状态图一给它就老老实实补了一个定时任务来兜底。这就是我在第 2 节说的流程图解决顺序状态图解决迁移。二者配合使用才能形成完整的思维协议。4. 常见问题与排查技巧实录任何方法论落到实操里都会冒出一堆问题。这套 Mermaid AI 编程打法我自己也踩了不少坑挑几个典型的分享一下。4.1 AI 不遵守图的约束擅自添加不存在的路径最开始我最烦的就是这个。我明明给了一张只有三条边的状态图AI 生成的代码里居然出现了一个图上完全没有的状态迁移。后来我琢磨明白了这不是 AI 不听话是我给的 prompt 不够封闭。AI 有一个默认行为——它会主动补全它认为应该有的逻辑哪怕图里没有。解决办法是在 prompt 里加一句约束只实现图中明确出现的节点与边不得新增图中不存在的状态或迁移关系。若必须新增需先用文字向我说明理由。这句强调之后AI 就老实多了。它仍然保留了一部分提出异议的能力但不再擅自加代码逻辑了。4.2 图太大超出上下文窗口AI 开始遗漏关键节点当流程图节点超过二十五个到三十个的时候AI 就开始忘记最前面的节点了。这不是玄学是上下文注意力分布的自然限制。解决办法不是让 AI 一次处理完整张图而是分层拆图。我会先让 AI 看一张顶层概要图理清模块关系然后再把每个模块对应的子图分别发给它让它细化实现。举个例子。一个完整的电商交易流程顶层图可能有十二个节点其中支付模块是一个聚合节点。我不会把这十二个节点全塞给 AI 一次生成而是先发顶层图让它生成模块骨架。再单独发支付模块的子流程图让它细化支付模块内部。最后发接口对接的时序图让它生成模块间的调用层。这种金字塔式的图组织结构既能保证整体不失焦又能保证细节不遗漏。4.3 迭代开发时代码改了图没改两者逐渐脱节这是最隐蔽、也最有破坏性的问题。某次迭代你让 AI 改了一个函数逻辑但你没同步更新对应的 Mermaid 图。几天后这个图已经不能反映真实代码了。到时候你再拿旧图去驱动 AI它就会生成一堆跟现有代码冲突的内容。我现在对自己的要求是凡是落入 git 的 Mermaid 图必须和代码同步更新。如果代码改了图不改那这个图宁愿删了也不要留在仓库里误导人。因为过时的图比没有图更糟糕——它会给 AI 传递错误的思维协议。我推荐的做法是把 Mermaid 图源码存放在代码库的 docs 目录下并在代码文件顶部加一行注释变更此文件逻辑时请同步检查 docs/xxx-flow.md 中的对应图。这是一个很简单的约定但能避免大部分同步问题。4.4 Mermaid 语法复杂写不对AI 又不会帮我修这是很多人一开始最容易卡住的地方。Mermaid 虽然简单但新手写 flowchart 经常搞混节点形状、箭头方向、标签语法。特别是给 AI 的 prompt 里语法错误越多AI 理解越偏。我的建议是写图的时候不要纠结语法先用最朴素的写法把节点和连线画出来再让 AI 帮你修成合法 Mermaid。A - B - C B - D这四行虽然简陋但意思清楚。然后你加一句 prompt把下面这个粗糙的流程图改写成合法的 Mermaid flowchart 语法并为每个节点命名名词使用描述性命名。 这招在大多数情况下都好用AI 对 Mermaid 语法的掌握比普通人熟多了。另外强烈建议装一个本地 Mermaid 预览插件或者在线的 Mermaid 编辑器写图的过程中随时渲染、随时检查。所见即所得能帮你省掉大量语法错了但没发现的时间。4.5 同样的图给不同的 AI产出的代码风格差异巨大不同模型的代码风格确实有差异。有的喜欢啰嗦的防御性编程有的喜欢简洁的样板代码。我的解决办法是在 prompt 里固定一套代码风格契约比如使用 TypeScript类型必须显式声明。错误处理返回 Result 联合类型不直接抛异常。日志每个节点函数入口必须打印结构化日志。把风格契约加在 Mermaid 图源码之前AI 的输出稳定性立刻提升一个档次。因为图的语义约束帮你解决了做什么风格契约帮你解决了怎么做、长什么样。5. 让 Mermaid 成为 AI 协作的思维基础设施最后再分享一点个人体会。我过去一年最大的变化不是学会了用更多工具而是改变了跟 AI 协作时的思维方式。以前拿到一个需求第一反应是直接让 AI 写写出来不对再让它改来回拉锯效率极低。现在我的第一反应是先画图再让 AI 写——把思考的时间前置把返工的时间消掉。这个过程其实是在建立一种思维协议你把自己的逻辑结构化用 Mermaid 表达出来形成一份人和 AI 都能读懂、都能改、都能 diff 的中间产物。这份产物既是需求文档又是设计文档还是与 AI 对话的提示词原材料。它不依赖任何具体的 AI 工具不需要多复杂的工程体系只需要你愿意多花十分钟画一张图。我自己实测下来这个习惯让复杂需求的 AI 生成代码一次通过率从不到一半提升到了七成以上。哪怕有时候图还没给 AI 看光是画图这个动作本身就已经把设计盲区暴露得差不多了——这在以前是不可想象的。撇开工具本身我觉得更深层的好处是Mermaid 让设计这件事重新变得廉价和自由。你不需要是架构师才能画出系统关系图也不需要掌握 UML 那些繁重的规范。用不到十行文本就能把脑子里的想法变成一张不会撒谎的图。然后 AI 再把这张图变成不会撒谎的代码。这两件事加在一起就是 Mermaid 在 AI 编程中最深的应用范式——它不是很多人以为的文档美化工具而是一种让人类思维与机器智能对齐的协议层。这套打法未来还会有更多演变空间但核心的那一步永远是动手之前先把图铺开。