你可能也有过这种体验需求评审会上大家争一个流程你当场打开画图软件拖了一堆框线和箭头结果还是说不清产品文档里全是文字流程逻辑要花十分钟才能看明白。画图这件事真正的成本不在动手而在把脑子里已经成型的逻辑翻译成图上的框线、箭头和布局——这个“翻译”动作极其琐碎。后来我把工作流改成了AI - Mermaid - 图形可视化UI我用自然语言把要表达的关系描述给 AIAI 生成 Mermaid 代码语法校验通过之后再交给渲染器在网页或应用界面里变成一张可交互的图。这套链路帮我省下了大量时间也让我所有图表都变成了“源代码”可以审查、可以 diff、可以放进仓库里。如果你也经常要画架构图、时序图、状态图或者想在应用里内嵌图表展示这篇文章应该能给你一套现成的、能落地的方案。1. 画图的痛点不在“画”而在“转换”为什么 Mermaid 能卡住 AI 和 UI 之间的位置1.1 传统画图流程里时间究竟浪费在哪我以前是 draw.io 和 Visio 的重度用户后来转型到 PlantUML 和 Mermaid 也经历过一段适应期。回头去看最耗时的不是鼠标拖拽本身——拖一个框三秒钟调整一条线可能半分钟但最致命的是每次需求变更后和图对应的那部分逻辑要重新“手工对账”。比如产品说“登录失败时要判断是否锁定账号锁定了就跳转找回密码没锁定就返回错误码”你要在图里增加判断节点、连线、分支标签。这个过程本质上是在做信息转换把结构化的一组逻辑条件变成图形元素的相对位置和连线关系。人脑做这种事情效率极低特别是一次性画几十个节点的架构图时往往画着画着就忘了某个依赖关系。而且传统画图工具的产物是“一张图”图里的信息和原始描述之间没有任何可追溯的绑定关系。画错了改起来费劲画对了别人也没法通过 diff 看出你改了哪里。这些才是画图真正的隐性成本。1.2 Mermaid 的中间语言属性文本化之后 AI 才能真正帮上忙Mermaid 之所以能成为这条链路里的核心是因为它不是图片格式而是一种类似 Markdown 的文本描述语言。你写一行flowchart LR下面跟着几个节点定义和连线规则剩下的布局计算、箭头曲线、子图排布都由渲染器处理。这带来两个关键好处。第一个好处是可生成性既然 Mermaid 是文本那么大语言模型最擅长的“文本生成”就正好能用上。你不需要让 AI 直接画像素只需要让 AI 生成一段有语法规则的字符串。第二个好处是可编辑性文本天然支持版本管理、支持逐字 diff、支持在 CI 里做语法检查。也就是说图表从一个“视觉成果”变成了“代码资产”。AI 直接生成图片看起来更酷但图片没法做局部修改也没法保证图中文字和逻辑完全一致。而 Mermaid 生成的是结构化的文本AI 输出的哪怕有逻辑错误你也能精准地改某一行然后在渲染器里立刻看到变化。这就是它卡在 AI 和 UI 之间的位置AI 负责把自然语言翻译成结构化文本UI 负责把结构化文本渲染成图形Mermaid 恰好是两边都能沟通的中间格式。1.3 这条链路适合哪些场景不适合哪些场景我用下来比较舒服的场景包括业务流程图、系统架构图、时序图、状态机图、甘特图、思维导图。尤其是时序图手画非常麻烦但用 Mermaid 写起来几乎像记事一样AI 也特别容易理解“谁在什么时候调用了什么方法”。不太适合的场景也有比如需要高度自定义视觉风格、需要像素级控制布局、或者需要与特定设计稿保持完全一致的架构图。这类场景用 Mermaid 会有点拧巴我还是会退回传统画图工具。另外如果图里节点超过一两百个Mermaid 的自动布局会开始吃力界面交互也会变卡这时候你可能需要考虑拆分图而不是硬堆。2. 最小可用链路模型选型、提示词模板、离线兜底方案2.1 模型怎么选在线大模型、API、本地小模型各自适合什么把 AI 接入 Mermaid 流程第一步是选模型。我自己的原则是不让模型思考让模型翻译。因为 Mermaid 语法本身并不复杂真正的难点是你需要把业务逻辑描述准确。所以哪怕模型推理能力弱一些只要会套模板也能输出能用的图。我平时最常用的组合是这样的日常对话和快速验证用在线通用模型比如 GPT、Claude、DeepSeek 这类做自动化工具或 Agent 的时候走官方 API把温度设低一点最好直接指定temperature0减少它自由发挥的概率在离线环境或者处理敏感数据时用本地小模型搭配 Mermaid 离线编辑器。下面是我个人感受的横向对比方案优点缺点适合场景在线通用模型Mermaid 知识相对完整能处理复杂逻辑数据会出公网不适合敏感信息临时画图、探索结构API 接口可以写入脚本/Agent批量生成需要调参成本会累积自动化流程、批量转换本地小模型数据不出内网稳定性可控Mermaid 专项知识较弱容易语法错误内网办公、涉密需求离线编辑器mermaid-cli完全不依赖模型但你不能用自然语言画图效率提升有限模型不可用时的兜底如果你只是自己画图在线模型完全够用。但如果你要做一个面向团队的自动化图表工具我建议直接用 API并且在 Prompt 里写死输出模板否则模型一“自由发挥”就会输出一堆 Markdown 文本或者 HTML接进 UI 的时候你会很痛苦。2.2 一套能稳定出图的提示词模板很多人让 AI 出 Mermaid 图会直接说“帮我画一个登录流程图”然后 AI 可能给出一段不完整的话或者带上解释文字。我的做法是把 Prompt 拆成四段角色定义、目标格式、输入内容、输出约束。比如我最近做了一个用户注册的流程实际 Prompt 大致是这样你是一个擅长绘制流程图的助手。请根据下面的业务描述生成 Mermaid 的 flowchart 语法代码。 业务描述 用户输入手机号先判断是否已注册。如果已注册直接走登录如果没有注册发送验证码。用户输入验证码校验通过后创建账号否则提示验证码错误并允许重新发送。 输出要求 1. 只输出 Mermaid 代码不要输出任何解释性文字。 2. 节点文字用双引号包裹防止特殊符号导致语法错误。 3. 使用中文节点名称连线标签用斜杠分隔关键词。 4. 逻辑条件写在连线标签上不要写成独立节点。模型通常会给出一段类似这样的代码flowchart TD A[开始] -- B{手机号是否已注册} B -- 已注册 -- C[登录流程] B -- 未注册 -- D[发送验证码] D -- E[用户输入验证码] E -- F{验证码是否正确} F -- 正确 -- G[创建账号] F -- 错误 -- D你可能会想为什么要求“节点文字用双引号包裹”因为 Mermaid 的语法里节点文字如果包含()、[]、{}这类字符会直接导致解析失败。让 AI 养成加引号的习惯可以省掉后面排查的功夫。这是我踩过很多次坑之后总结出来的。2.3 没有网络时的兜底mermaid CLI 与本地编辑器团队里偶尔有内网环境不能连在线模型。我的兜底方案是mermaid-cli 本地界面。mermaid-cli是一个 Node 包可以用mmdc命令把.mmd文件渲染成 SVG 或 PNG。哪怕没有 AI你手工把流程图写成 Mermaid 文本也比用鼠标拖拽快很多。安装和最基本的使用大概是npm install -g mermaid-js/mermaid-cli mmdc -i input.mmd -o output.svg如果你想要一个带预览的本地编辑器可以用 VS Code 插件“Mermaid Preview”或者找一个离线版编辑器页面下载到本地打开。这样在完全没有公网的情况下工作流从“AI 生成”退化成“手工写 Mermaid 文本”依然保持“文本 - 图形”的核心链路。至少你不会被绑定在某个在线画图平台里。3. 把 Mermaid 变成真 UIWeb 集成、主题和交互增强3.1 从一段 Mermaid 文本到页面上的图mermaid.js 集成步骤如果只是偶尔看一张图用在线编辑器就够了。但如果你希望图表出现在自己的管理后台、文档系统或者数据产品页面里那就要把 Mermaid 接进前端 UI。我在实际项目里用得最多的是 Web 端集成方式很简单核心依赖是mermaid这个 npm 包。大致分三步。第一步在页面里引入mermaid初始化并指定一个容器div idchart/div script srchttps://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js/script script mermaid.initialize({ startOnLoad: false, theme: base, themeVariables: { primaryColor: #f0f7ff, primaryBorderColor: #1e5eff, fontSize: 14px } }); /script第二步把 AI 生成的 Mermaid 文本放到一个pre或 JS 变量里调用mermaid.render(id, code)。注意render是异步的会返回一段 SVG 字符串你再把 SVG 塞进容器const code flowchart TD\nA--B; mermaid.render(myChart, code).then((svg) { document.getElementById(chart).innerHTML svg; });第三步如果你的 Mermaid 代码可能是从用户输入或 AI 输出直接拿来的一定要先做语法校验。用mermaid.parse(code)可以提前判断能不能解析避免直接渲染时页面报错。我习惯在解析出错时给用户一个可读的提示而不是把大段异常抛在 UI 上。3.2 样式和体验主题、缩放、节点点击事件Mermaid 的默认主题不一定适合所有产品风格。theme可以设置成default、neutral、dark、forest、base。base模式最好用因为它允许你通过themeVariables单独设置节点背景色、边框色、文本大小能和 UI 设计稿对上。如果你集成的是深色模式后台直接在初始化时切换themeVariables就行不需要改业务代码。交互方面Mermaid 本身支持在节点上绑定点击事件。比如流程图里某个节点代表服务名称我可以点击它跳转到对应服务的监控面板。做法是在 Initialize 时开启securityLevel: loose然后在节点定义里加上click指令flowchart LR A[订单服务] -- B[库存服务] click A https://monitor.example.com/order-service 查看订单服务监控到了 UI 层我还会做两件增强一是给容器加缩放和拖拽能力图大了以后用户可以直接平移查看不至于被容器裁剪掉二是给图增加“导出 PNG”按钮。因为 Mermaid 渲染出的是 SVG导出 PNG 最简单的方式是放到 Canvas 里再转或者直接用svg-to-png库处理。这些操作在 UI 里都很成熟但如果不在前端做过第一次接的时候还是会有不少边界问题。3.3 非 Web 界面里的 Mermaid桌面端平台和 Unity 的延伸有些朋友在 C# 桌面端里也想展示流程图或者想放到 Unity 的 UI 框架里。Mermaid 官方库主要是 JavaScript 生态但桌面端项目可以绕一段路先使用mermaid-cli把 Mermaid 文本渲染成 SVG 或 PNG 文件再在运行时加载图片资源。这里有一个容易踩的坑如果是在 C# 的 Task 线程里动态生成图表不要把生成过程直接塞进 UI 线程去做。我在 WPF 里试过一旦图表较大UI 线程会被占住整个界面会出现明显的卡顿感。正确做法是让 Task 在后台完成渲染或图片生成把最终的文件路径或字节流回传再通过Dispatcher.Invoke更新界面上的 Image 控件。Unity 里的处理也类似UI 相关操作只能在主线程执行图片生成过程应该丢给异步方法。这个思路和前端“主线程别做重活”其实是同一个原则。4. 踩坑实录从 AI 输出到 UI 渲染之间的六道坎4.1 第一道坎AI 把 Markdown 围栏也当成答案输出这是最基础也最烦的问题。当你问“请生成 Mermaid 代码”时很多模型会习惯性把代码放在 triple backtick 里也就是 Markdown 代码块。如果你的前端脚本直接把那段文本交给mermaid.render()它会把开头的mermaid和结尾的当作字符串的一部分导致解析失败。解决方式有两个。一是把“只输出 Mermaid 代码不要 Markdown 围栏”明确写进 Prompt二是在代码里做清洗比如把三个反引号行去掉再 trim 掉首尾空白。我在自动化流程里习惯同时做这两件事因为模型不一定每次都听话清洗逻辑本身就是一道兜底保障。4.2 第二道坎中文、特殊字符和括号引起的语法错误Mermaid 对中文的支持其实不错但前提是节点文字用双引号包住。如果你写A[开始]中文情况下通常没问题但如果节点文字里有冒号、逗号、括号、斜杠解析器就会发疯。比方说“订单已支付”不处理的话括号会被 Mermaid 解析成子图语法。我总结了一个规则所有节点文字一律用双引号包裹。同时让 AI 在输出时也遵循这个规则。因为一旦形成模板输出稳定性高很多前端不用做各种转义处理。4.3 第三道坎一个图太大UI 渲染卡到怀疑人生节点数量一旦超过 50 个特别是频繁初始化主题变量、还开着动画时页面会出现明显卡顿。这个问题的根源不是 Mermaid 本身不行而是 SVG 在浏览器里的 DOM 操作有开销。我在一个后台项目里放过一张接近 200 个节点的网络拓扑图结果把页面拖得基本没法操作。优化手段我按收益排序先去掉全局初始化动画startOnLoad: false并且手动控制渲染时机再考虑拆分图把一张大图拆成几个小图通过交互切换显示最后才是部署前端路由级懒加载等用户滚动到图表容器附近再渲染。这三个手段组合起来基本能解决大多数“UI 卡顿”投诉。4.4 第四道坎AI 生成的图“看起来对”逻辑却是错的这是 AI 生成代码的共性问题。Mermaid 不会校验业务语义它只保证语法正确。你可能让 AI 画一个“在下单后检查库存”的时序图结果它把库存检查画在了下单之前而语法完全没问题。所以我现在的习惯是把 AI 生成的 Mermaid 当成初稿而不是成稿。特别是跨系统交互的链路我会在生成之后花一分钟扫一遍关键节点和箭头方向再交给 UI 或发到文档里。在自动化场景里我会让 Agent 做两遍生成——一遍画图一遍把图还原成自然语言描述然后和原始需求做一致性比对。这个方法成本不高但能拦下不少低级逻辑错误。4.5 第五道坎渲染时出现“方向不是想要的方向”画一个组织架构图或者调用链AI 经常会输出flowchart TD自上而下但你的本意可能是横向关联或者是LR从左到右。图的方向影响很大有时候同一段逻辑用 LR 会清晰很多用 TD 就挤成一团。解决办法就是在 Prompt 里明确指定方向比如“请使用 flowchart LR”。如果模型没有听懂你手动改第一行代码也就一秒钟的事。4.6 第六道坎前端初始化时重复报错“unknown tag”这个报错一般是在mermaid.initialize之后又重复初始化或者加载了多个版本的 mermaid 脚本。我在老项目里遇到过原因是页面里既有全局 CDN 引入又通过 npm 打包了一份两个实例打架就会不断报错。解决方式是统一收口要么全局 CDN要么 webpack 引入不要两边都放。5. 再往前走一步把 Mermaid 当“中间语言”让 Agent 自动维护图表5.1 用 Agent 从代码库和需求文档里生成架构图既然 AI 能根据一段话生成 Mermaid那它也就能根据一个仓库的代码结构、或者一份几千字的需求文档生成对应架构图、时序图、类图。我最近一直在做一个内部小工具Agent 读取某个服务的关键类文件和路由定义然后输出一张服务模块图。Prompt 里会要求“只保留主要模块不要穷举所有类否则图没法看”。这个思路的核心在于不要让 AI 直接生成最终图片而是生成 Mermaid 中间代码。Mermaid 代码可以放进仓库可以走代码评审可以自动检查语法。之后的任何改动都通过修改代码来完成图片只是“编译产物”。这让我觉得 AI 不是在做一次性的“画图”而是在维护一份会演化的架构文档。5.2 Mermaid 作为中间表示的价值可 diff、可审查、可测试传统画图工具导出的 PNG 是完全不可 diff 的。即使两个人只是挪动了一个节点输出文件可能就变了几百字节Git 看过去一片红绿。但 Mermaid 代码是完全文本化的任何结构变化都能以行为单位呈现。团队里这个优势特别明显有同事改动架构图评审时只需看 Mermaid 代码的 diff就知道改动影响了哪些关联关系。更进一步你可以在 CI 里加一道“Mermaid 语法检查”。只要仓库里某个.mmd文件语法错误流水线就直接失败从源头上避免坏图流到线上文档。这个做法和代码 lint 非常像成本极低收益却很直观。5.3 实用技巧让图表和文档共用同一个数据源最后分享一个我自己的习惯在项目的文档里建一个diagrams/目录所有图表统一放成.mmd文本文件然后用自动化脚本批量渲染成 PNG再内嵌到 Markdown 文档里。这样需求方看到的文档是图工程师维护的是文本AI 修改的也是文本。如果文档平台支持 Mermaid 原生渲染更省事——直接把代码块嵌进去就不需要维护图片产物了。比如内部 Wiki、GitLab、GitHub 都原生支持 Mermaid 代码块选中“Mermaid”语言后会自动显示图形。这个“文档和图表同源”的做法让我在几个跨团队项目里都明显减少了“对图不一致”的扯皮。因为大家维护的是同一份文本改完必然同步不存在某个人的本地图片没上传这种事故。在我实际体验中这条 AI - Mermaid - UI 的链路真正解决了“逻辑表达”和“视觉呈现”之间的转化耗散。它不适合作为大型专业制图的替代方案但作为日常业务流程图、时序图、架构图的生产方式已经稳定地帮我剩下了一大块时间。如果你打算在项目里落地可以先从最细的一根线开始让 AI 画一张你手头最常用的流程图把它放进 Git 里然后感受一下在文本世界里改图是什么体验。