最近逛 GitHub 热榜的时候，又看到一个 diagram 方向的 skill 项目，Star 数直接飙到 2.9 万。坦白讲，这两年"AI 画图"早已不新鲜，能冲到这么高关注度的不多。我花了一个晚上把源码、示例和 issue 区翻了个遍，又在自己常用的环境里完整跑了几遍，今天把它的核心逻辑、实操方式和踩坑经验一次说清楚。
如果你平时要给系统画架构图、给业务梳理流程图，或者你正在做 AI 编程助理相关的工具链，这个 skill 值得你花 10 分钟看完。它能做到的事情一句话总结：你把需求丢给它，它自己判断该用哪种图表、生成什么内容、排成什么结构，最后输出一份可编辑、可二次修改的图表文件。适合开发者、运维、产品经理，也适合任何"脑子里有逻辑但画图手残"的人。
1. 这个 diagram skill 到底是什么，为什么能涨 2.9 万 Star
1.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 skill
3.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["用户点击“提交订单”按钮"]第二个经典坑：节点 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 装起来试一次。试试你平时最不想画的那张图，从打开对话到导出成品，你看看能省下多少时间。
