AI画图新利器：2.9万星diagram skill，让AI自动生成架构图与流程图

最近逛 GitHub 热榜的时候又看到一个 diagram 方向的 skill 项目Star 数直接飙到 2.9 万。坦白讲这两年AI 画图早已不新鲜能冲到这么高关注度的不多。我花了一个晚上把源码、示例和 issue 区翻了个遍又在自己常用的环境里完整跑了几遍今天把它的核心逻辑、实操方式和踩坑经验一次说清楚。如果你平时要给系统画架构图、给业务梳理流程图或者你正在做 AI 编程助理相关的工具链这个 skill 值得你花 10 分钟看完。它能做到的事情一句话总结你把需求丢给它它自己判断该用哪种图表、生成什么内容、排成什么结构最后输出一份可编辑、可二次修改的图表文件。适合开发者、运维、产品经理也适合任何脑子里有逻辑但画图手残的人。1. 这个 diagram skill 到底是什么为什么能涨 2.9 万 Star1.1 Skill不是插件是一套可复用的推理工作流先说一个容易混淆的概念。Skill 在 AI Agent 语境下并不是传统意义上的软件插件它是一整套**提示词规则 输出约束 工具调用逻辑**的组合。你可以把它想象成给 AI 一份非常详细的《画图作业规范》里面规定好了拿到需求先干什么、遇到模糊需求怎么问、选哪种图表、用什么语法、出图后怎么自检。这个 diagram skill 的核心就是在这一层做了大量工程化工作。它不只是告诉 AI你要画流程图而是把流程拆成多个环节第一步理解用户描述里的实体、关系和动作第二步根据内容复杂度判断图表类型第三步按选定的语法规范生成图表代码第四步自己检查一遍语法、布局、命名第五步输出给用户并附上修改建议。这个思路其实和之前各种prompt 模板有本质区别。模板只解决说什么skill 解决的是怎么做而且把每一步的判定规则都写死了。结果就是你给它一段很随意的话它画出来的图依然结构清晰、风格统一而不是那种一看就AI 味很重的随机产物。1.2 2.9 万 Star 背后戳中的是哪个痛点这个 Star 数在开发者工具类项目里绝对算现象级。为什么它能火拆开看核心命中了两类人群的痛点。第一类是**逻辑清楚但不会画图**的人。很多开发者在写方案、做汇报、写文档时脑子里对模块划分、数据流向都很清楚但一打开画图工具就卡在排版上。节点怎么摆、连线怎么拐、颜色怎么配这些美工活最耗时间。diagram skill 本质上是把思考结构和视觉呈现分离了你只需要讲清楚内容逻辑版式问题全部交给它。第二类是**会画图但嫌维护麻烦**的人。传统画图工具最大的问题不是画的时候累而是改的时候更累。需求一变更整个图推倒重画。而基于代码的图表方案Mermaid、D2、PlantUML 这类天然支持版本管理和 diff 对比配合 AI 生成能力改动成本从重画降到了改一句话。这两个痛点放在一起恰好构成了一个非常高频、非常刚性的需求场景。再叠加 GitHub 社区对AI 开发效率的天然追捧2.9 万 Star 就不难理解了。2. 从会画图到画对图核心技术方案拆解2.1 全部支持的图表类型与适用场景diagram skill 能做的事比大多数人想象中要多。它不止支持画一种图而是覆盖了日常开发几乎全部高频图表类型图表类型适用场景典型输出格式流程图业务审批流、状态机、操作步骤Mermaid flowchart / D2时序图API 调用链、消息交互、协议流程Mermaid sequenceDiagram架构图系统部署、微服务拓扑、网络分区D2 / Mermaid graph / Excalidraw类图领域模型、数据模型、代码结构Mermaid classDiagram状态图订单状态流转、任务生命周期Mermaid stateDiagram-v2甘特图项目排期、任务规划Mermaid gantt实体关系图数据库设计、表关系梳理Mermaid erDiagram用户旅程图产品体验梳理、交互流程分析Excalidraw / D2这个选型逻辑值得特别说一下它并不是把所有图表类型都做成平级的而是根据用户输入的内容特征去做判断。比如输入里出现用户在页面上点击登录然后系统校验账号密码再返回 token这类描述它不会画流程图而会优先考虑时序图因为这段描述强调的是交互顺序。从实用角度讲这种语义识别优先的机制极大减少了使用者来回调整图的次数。你不需要懂我的场景该用哪种图只需要把业务描述清楚它自己会判断。2.2 选型是门学问为什么盯上 Mermaid 这类 DSL这里藏着一个关键的架构决策为什么 diagram skill 生成的是 Mermaid / D2 这类代码文本而不是直接输出 PNG、SVG 图片答案有三层。第一层是可编辑性。图片是一次性的改一次就要重新生成代码是可持续迭代的你可以本地保存、改一个节点再渲染。第二层是可追踪性。代码文件可以进 Git两个版本之间改了哪里用 diff 一目了然。这在做技术方案评审、架构演进记录时非常重要。第三层是可移植性。不管是放 README、写内部 Wiki、还是嵌入 Notion / 语雀 / 飞书文档几乎所有现代文档平台都支持 Mermaid 渲染这意味着生成的图可以在任何地方直接用不绑定任何工具链。选 Mermaid 而不是 PlantUML我个人的观察是Mermaid 的语法对中文用户和初级用户都更友好而且生态更活跃VS Code 插件、在线编辑器、GitHub 原生渲染全都支持。D2 则是在复杂架构图上表现更强布局算法更智能。所以在实际使用时diagram skill 的默认策略其实是Mermaid 优先复杂架构切 D2手绘风格切 Excalidraw。这种多后端策略比死守某一个渲染器要聪明得多。2.3 整个工作流分四步走谁负责哪一块拆开看一次完整的出图过程分四个阶段。理解这个流程你才能真正用好它而不是把它当成玄学生成器。第一阶段是意图解析。AI 把用户输入打散成三部分实体有哪些对象、关系对象之间什么联系、动作流程怎么流转。如果输入信息不足它会先提问而不会瞎猜。第二阶段是方案匹配。根据第一阶段提取出的特征选择合适的图表类型和渲染器。这一步靠的是 skill 内置的规则库不是 AI 自由发挥。规则库是作者从大量真实用例里总结出来的这也是它比裸用大模型更靠谱的原因。第三阶段是生成与自检。按选定语法生成代码然后自动检查语法正确性、节点命名规范、是否有孤立节点、布局是否合理。这一步很像程序员写完代码后跑一遍 lint。第四阶段是交付与反馈。把生成的代码返回给用户同时附上预览和建议。用户修改某一行描述AI 基于现有代码做局部调整而不是整图重画。这个设计最聪明的地方是它把AI 生成从一次性的动作变成了一个可迭代的闭环。你可以逐步细化需求图也跟着逐步演进而不是每次生成一版全新的、只可远观不可修改的图片。3. 实操环节7 步跑通 diagram skill3.1 准备环境两个前置条件如果你只是想在对话里让 AI 画个图其实不需要装任何东西。但如果想把它当成日常开发工具链的一环我建议按下面的方式搭一套完整环境。前置条件一一个支持 skill 机制的 AI 编程助手环境。目前主流的做法是把 skill 文件放进对应的 skill 目录然后在对话里通过diagram之类的指令唤起。不同的客户端路径不一样但机制相同给 AI 定义能力边界和使用规范让它知道什么时候该调用、怎么调用。前置条件二本地安装 Node.js 和 Mermaid CLI。虽然很多平台自带渲染但本地跑一遍可以提前校验语法不用等提交到文档里才发现渲染失败。Mermaid CLI 是官方提供的命令行工具安装命令如下# 安装 mermaid-cli npm install -g mermaid-js/mermaid-cli # 安装后验证 mmdc --version装完依赖再把 skill 仓库 clone 到本地放进你自己项目的.ai/skills/diagram目录具体目录名取决于你使用的客户端约定。这一步做完环境就绪。我个人建议在这时候顺手装一个 VS Code 的 Mermaid 插件。它的好处是一边写代码一边实时看渲染效果不用每次改完都跑命令行导出图片。实测下来这个组合skill 生成 插件预览 CLI 导出是效率最高的一套流。3.2 第一次出图输入一段有信息量的描述环境就绪后第一次实战别直接丢一句画个架构图——这种输入神仙也画不出好东西。好的输入应该包含实体、关系和层次哪怕口语化也没关系。我测试时用的输入是帮我画一个简单的用户登录流程图。用户在前端页面输入账号密码点击登录按钮后请求发送到后端 API后端先校验验证码通过后查询数据库验证账号密码验证通过则生成 token 返回前端前端把 token 存到 localStorage 并跳转到首页。如果验证码错误或账号密码错误分别给出错误提示。然后触发 diagram skill它返回的 Mermaid 代码大致长这样flowchart TD A[用户] --|输入账号密码| B[前端页面] B --|点击登录| C[后端 API] C -- D{验证码是否正确} D --|否| E[返回验证码错误提示] D --|是| F[查询数据库验证账号] F -- G{账号密码是否匹配} G --|否| H[返回账号或密码错误提示] G --|是| I[生成 token 返回前端] I -- J[前端存储 token 并跳转首页]这一步的关键点在哪在于输入信息密度。你给的描述里有明确的处理步骤验证码校验、账号校验、分支逻辑错误处理、技术边界前端/后端/数据库所以它生成的图就会更准确。如果你只说画个登录流程它也能画但大概率只是最基础的输入-验证-成功三步缺少细节。AI 不会读心好输入才有好输出。3.3 出图后的标准三步预览、微调、导出代码生成只是第一步后续的校验和调整才是体现skill 思路的环节。第一步是预览。在 VS Code 里直接打开.mmd文件预览渲染效果。重点看分支方向是否符合直觉、节点之间的连线是否交叉严重、文字有没有被截断。第二步是微调。如果发现布局不合理不要直接手工去改坐标而是用描述性语言让 AI 调整。比如把验证码是否正确这个判断节点放到中间位置并让两个分支分别向左右展开。diagram skill 的好处是它能理解这种空间描述然后在你现有代码基础上做局部修改而不是重新生成一张可能还不如之前的图。第三步是导出。如果要放进文档用 CLI 导出为 SVG 或 PNG# 导出 SVG适合文档内嵌和二次编辑 mmdc -i login-flow.mmd -o login-flow.svg # 导出 PNG适合做汇报材料 mmdc -i login-flow.mmd -o login-flow.png -b white个人建议优先导出 SVG。一方面它是矢量图放大缩小都清晰另一方面 SVG 可以用工具直接修改文字和颜色。如果投放到 PPT 或 Word 里用SVG 也支持直接嵌入不会像位图一样放大发虚。3.4 画架构图时的几个关键参数流程图画顺了之后很多人会立刻遇到第二个需求画架构图。架构图和流程图不一样它更强调层次关系和模块边界。用 diagram skill 画系统架构图时我总结了一套比较顺的三层描述法先描述整体分层再描述每层内的模块最后描述层与层之间的调用关系。还是举真实例子我画出自己在跑的某个微服务项目时输入是这样的画一个电商系统的微服务架构图。顶层是 API 网关接收前端请求。中间层是业务服务包括用户服务、商品服务、订单服务、支付服务。底层是中间件包括 MySQL 数据库、Redis 缓存、RabbitMQ 消息队列。服务之间通过 HTTP 同步调用事件通知走 RabbitMQ。它输出的效果就是清晰的分层架构图网关在最上面中间四个服务横向排列底层三个中间件一字排开连线逻辑明确。这个过程中AI 做的最聪明的一件事是自动把 Redis 和 MySQL 归类为存储层把 RabbitMQ 单独归类为消息层——这种归类确实贴合真实架构说明它对技术语义是有理解的而不是机械地把名词堆上去。4. 最容易翻车的场景与排查速查表4.1 生成的图很丑先查布局和样式丑是个很主观的词但落到 Mermaid 代码上其实是可以分析的。最常见的原因有三个节点文字太长导致排列拥挤、分支方向混乱导致连线交叉、全图默认配色缺乏层次感。第一个问题靠换行解决。Mermaid 支持在节点文字里用br/强制换行比如把订单服务调用库存服务扣减库存换行成订单服务 / 调用库存服务 / 扣减库存渲染出来会清爽很多。第二个问题靠指定direction解决。Mermaid 的 flowchart 支持四种方向flowchart LR !-- 从左到右适合流水线 -- flowchart RL !-- 从右到左适合反向流程 -- flowchart TB !-- 从上到下适合分层架构 -- flowchart BT !-- 从下到上适合汇报场景 --很多新手画出的图很难看其实就是因为默认方向没有贴合内容特征。分层架构用 TB流水线用 LR状态流转用 TD这是基本的布局直觉。第三个问题的技巧是用 classDef 自定义样式。比如把核心服务、中间件、外部系统分别用不同颜色区分整个架构图的信息密度一下子就上来了classDef core fill:#e1f5fe,stroke:#01579b,stroke-width:2px; classDef middle fill:#fff3e0,stroke:#e65100,stroke-width:1px; classDef external fill:#e8f5e9,stroke:#2e7d32,stroke-width:1px;4.2 渲染直接报错八九成是这两个原因Mermaid 渲染报错的频率比想象中要高。我自己用下来的经验是90% 的报错都出在引号、特殊字符和编码上。第一个经典坑节点文字里包含中文引号或特殊符号。Mermaid 对引号的解析比较严格比如在节点里写了或者可能导致解析中断。解决方案是要么把文字里的引号去掉要么给节点加别名把文字单独定义。第二种方式更稳flowchart TD A[用户点击“提交订单”按钮]改为flowchart TD A[用户点击ldquo;提交订单rdquo;按钮]第二个经典坑节点 ID 重复或者为空。如果你明确指定了节点 ID一定要保证全图唯一。Mermaid 遇到重复 ID 时不会直接报错而是会把内容合并看起来就像图变奇怪了排查起来特别费劲。4.3 一张速查表解决 8 个高频问题问题现象根本原因解决方案节点文字折行混乱文字过长且无换行在指定位置插入br/手动换行连线交叉严重布局方向不合适调整flowchart LR/TB方向图太宽超出文档节点横向排列过多改用TB方向或拆分子图中文渲染乱码本地环境缺中文字体安装 Noto Sans CJK 或配置浏览器字体某节点内容被吞节点 ID 重复全局搜索 ID 唯一性提示错误仍能导出语法解析警告用mmdc -v查看详细错误信息分支方向不符合预期默认方向不是想要的在连接线上加-- |条件|标签引导导出 PNG 背景发黑透明背景叠加问题加-b white参数指定白色背景5. 往深了玩这个 skill 还能接什么5.1 接入自动化流水线文档随代码更新diagram skill 真正的想象空间是配合自动化流程让文档永远不过时。想一下这个场景你写了一个 Kafka 消费者接口变了注释更新了但架构图还是三个月前的版本。这种文档漂移在传统模式下几乎无解因为手动维护图表的成本太高人总会偷懒。有了 diagram skill 之后一个可行的方案是把 skill 集成到 CI 流程里每次代码合并时自动触发根据代码里的结构化注释生成对应的架构图并和上一次生成的结果做 diff。有变化就把新图提交到文档仓库通知相关人确认。这个玩法把画图从一个周期性的人工任务变成了一个随代码变更自动执行的动作。图的维护成本趋近于零文档漂移问题自然就不存在了。我估计后续会有越来越多团队走这个方向因为它解决的是工程协作里最顽固的文档维护惰性。5.2 用 diagram skill 做 AI 辅助架构评审还有一个很实用的场景是架构评审。以往做评审时大家带着各自的图、对着白板你画一笔我画一笔效率不说多高信息往往也不全。现在可以换个玩法把现有的代码目录结构、模块依赖关系贴给 diagram skill让它先自动生成一张现状架构图再基于这张图做讨论。这样做有一个非常明显的好处评审讨论的不再是谁脑海里的理想架构而是真实代码的现状架构。很多设计问题在抽象讨论时看不出来但一画成图就看得很清楚比如某个模块被 20 个地方依赖、某个服务存在循环调用、有些模块的边界完全不符合分层规范。这也是 diagram skill 和普通画图工具最大的差异点它的工作流是围绕内容逻辑组织和沉淀的天然适合与代码库、研究文档、AI Agent 配合。5.3 从 Mermaid 到 D2 / Excalidraw 的横向扩展最后聊聊值得关注的横向扩展。diagram skill 目前的默认输出以 Mermaid 为主但架构选型上留了多个后端意味着你可以按需扩展到其他 DSL 或渲染器。D2 在复杂架构图上的布局算法明显优于 Mermaid如果你需要画那种带几十个节点、多层嵌套的网络拓扑图值得切到 D2。Excalidraw 则适合画手绘风格的用户旅程图和思想草图观感更轻松适合产品汇报、方案展示这类场合。在实际项目里我一般按这个规则做选择业务逻辑图、状态流转图用 Mermaid系统部署架构、网络拓扑用 D2对外汇报、产品方案配图用 Excalidraw。这样三类需求各用一个最顺手的后端覆盖几乎全部日常画图场景。我个人在使用中还有一个习惯把每次调整后的代码存进一个diagrams/目录按日期命名。这样近期所有图的历史版本都在想回退哪个版本随时可以。有一次评审会要展示三个月前的方案我直接从版本目录里翻出来比打开网盘翻找自动备份的导出的图片要顺滑太多。记得第一次在项目里把这个 skill 跑通的时候我就意识到这东西以后会跟代码格式化工具一样普及。它不炫技不花哨就是老老实实把画图这件事从技能活变成了聊天话。如果你的工作里也有一大堆永远懒得更新的架构图和流程图找一个晚上把这个 skill 装起来试一次。试试你平时最不想画的那张图从打开对话到导出成品你看看能省下多少时间。