最近有个做 diagram 的项目在 GitHub 上暴涨了 2.9 万 Star标题里直接写着“又一个神级 diagram skill”。说实话刚看到这个数字的时候我第一反应是“又一个套壳画图工具”但仔细扒了一下仓库和实现方式之后发现它跟以前那种“调 API 生成图片”的玩具完全不是一回事。这个项目本质上是把一个完整的图表生成能力封装成了标准 skill让 AI 可以直接根据自然语言描述产出结构化的 Mermaid 代码、PlantUML 代码甚至 SVG而且整个链路是可以在本地可控跑通的。我自己平时的工作流里经常要给项目画架构图、时序图、ER 图和业务流程图。过去最痛苦的就是图本身并不复杂但 AI 一旦开始“自由发挥”输出就很容易出现布局错乱、节点重复、语法非法这类问题改起来比自己手画还慢。所以看到这个项目的时候我主要关注的是它到底怎么解决“AI 画图不靠谱”这个老毛病的。用了几天之后我可以负责任地说它的设计思路确实踩在了正确的点上不是让模型记住一堆语法而是把图表这个领域的“规范和约束”做成了可执行的规则让模型在生成时始终被关在笼子里同时又保留了足够的创造力空间。这篇文章不打算复读 README而是按我自己的理解把这个 diagram skill 之所以能爆火的核心原因、内部设计逻辑、实操部署方法、效果调优技巧和常见问题排查完整拆开揉碎讲一遍。如果你正在做 AI Agent、自动化文档、代码生成这类方向或者你只是受够了“画图两小时改图一整天”的糟心事这篇文章都能给你一些可以直接落地的参考。1. 先聊聊背景为什么一个“画图技能”能在 GitHub 拿到 2.9 万 Star1.1 AI 画图的老大难看得懂但画不对过去一两年让 AI 生成图片早就不是什么新鲜事了但让 AI 生成“技术图”却一直是块硬骨头。所谓技术图指的是架构图、流程图、时序图、类图、状态机图、甘特图这类有严格逻辑关系的图。它们的难点在于节点之间要体现真实的依赖关系布局要有清晰的阅读顺序语义上不能有歧义。普通文本生成可以容忍“意思差不多”但图表不行——节点错了就是错了连线错了整张图就废了。我见过很多生成方案最常见的是直接丢给模型一段文字让它“画一张微服务架构图”。模型确实能输出一张看起来有模有样的图但你放大看细节服务 A 和服务 B 之间的箭头指向画反了负载均衡器和网关的角色搞混了数据库居然挂在边缘节点上。这些错误说明模型本质上只是在“模仿图表的形状”并没有真正理解图表背后的技术语义。也有些人选择让 AI 直接生成 HTML 加 CSS 的 SVG这样自由度很高但可控性更差。每生成一次样式都不一样维护成本极高。整个领域缺的是一个把“图表生成”这件事标准化、工程化、可复用化的中间层。1.2 从零散脚本到标准 skill 的进化这个 diagram skill 走了一条完全不同的路。它没有试图让模型凭空“画”出一张图而是把整个图表生成流程拆解成了几个明确阶段先理解用户意图再选择图表类型然后生成带约束的中间表示最后渲染成目标格式。这个过程很像一个真正的后端工程师在干活先搞清楚需求再做技术选型再写代码再测试上线。更关键的是它把所有图表领域的知识沉淀成了一个标准 skill 包。你只需要把它放到 AI 工具指定的 skills 目录里它就能自动被加载。skill 里面包含了非常详细的图表类型定义、语法规则、模板示例、检查条款和输入输出格式。以前要写几百行提示词才能让模型稳定输出的任务现在只需要一个精简的指令模型就会自查自纠地走完整个流程。这种“技能封装”的思路本质上是在复用大语言模型已有的代码理解能力。模型不需要真的记住 Mermaid 或 PlantUML 的所有语法细节因为它随时可以参考 skill 里内置的规则文件模型也不需要靠运气碰撞出正确的布局因为 skill 已经把高质量模板提供给它模仿了。我从第一次在 Agent 场景里体验到这种效果之后就意识到这可能是未来所有垂直领域工具的通用范式。1.3 为什么选 Mermaid 系作为核心渲染目标这个 skill 在渲染目标上做了大量取舍最终主攻方向仍然是 Mermaid 系语法。原因很简单Mermaid 是目前生态最成熟、工具链最完善、社区最活跃的文本化图表方案。它可以用几行代码生成出符合工业标准的流程图、时序图和甘特图而且主流的 Markdown 编辑器、代码托管平台、知识管理工具基本都原生支持预览。当然skill 里也不只支持 Mermaid。它还预留了 PlantUML、D2、SVG 等多种输出格式的接口但核心链路是围绕 Mermaid 优化的。这样做的实际好处是生成的代码可以直接粘贴到项目的文档里、编写到 README 中、甚至嵌入到自动化流水线中跨团队协作时零摩擦。很多时候我们把图贴进 GitHub、飞书文档或者 Obsidian交互和渲染都非常顺畅这在以前的生成方案里是做不到的。2. diagram skill 的核心设计拆解它到底做了什么2.1 Skill 的结构与执行链路我见过不少把“技能”做成一个纯提示词文件的项目单独把指令写得天花乱坠但没有工程化的执行逻辑。而这个 diagram skill 的仓库结构是一个非常规范的技能包严格遵循 Agent Skill 的目录规范。核心文件包括一个 SKILL.md 主文件、多个参考模板、初始化脚本和校验工具。理解这个结构非常重要因为它的执行效率正是来源于这种分层设计。我来把关键部分展开说SKILL.md 是技能入口它定义了技能的触发条件、能力边界和使用流程模板文件是成品图表的“字帖”模型在生成时不是从零开始而是从最接近需求的字帖开始修改这样就极大降低了语法错误率校验工具则负责在最终输出前跑一遍语法检查发现错误会自动让模型重新修正。整个执行链路可以简单描述为用户用自然语言描述需求AI 判断该用哪种图表类型读取对应模板生成 Mermaid 代码再用校验器检查语法最后把渲染建议返回给用户。每一步之间都有明确的数据接口而不是像以前那样一股脑丢给模型去猜。2.2 图表类型识别与动态规划能力这个 skill 最让我惊艳的地方是它的图表类型识别能力。你给它一句“帮我画一个用户下单的流程”它不会默认输出流程图而是先分析这个需求里包含哪些元素。如果涉及多个角色和交互它可能会选时序图如果涉及分支判断它可能调整为流程图如果涉及模块间依赖它可能会建议 C4 架构图。这种能力来自 skill 内建立的一个决策树。决策树会根据关键词、句法结构和实体类型来推断用户需求。举个例子文本里出现“谁、什么时候、做了什么”这样的结构会倾向实体之间的交互生成时序图的概率就高出现“如果、否则、循环”这类控制流关键词则会优先考虑流程图。更细节的一点是skill 要求模型在最终输出前必须先用一句话解释“为什么选择这个图表类型”再给出代码。这个“解释约束”在实际使用中非常有效。它逼着模型在动手前先思考一遍比直接输出代码稳定了很多。我自己在接入其他 Agent 工具时也借鉴了这个做法效果非常明显——让 AI 先给出选型理由能过滤掉大量拍脑袋的生成结果。2.3 支持的核心能力清单与适用范围从能力覆盖范围来看这个 skill 目前支持十四种以上的图表类型基本覆盖了一个研发团队日常能用到的所有技术图种类。我帮你梳理一下其中最常用的几类以及它们实际适用的场景流程图Flowchart最通用的过程表达方式适合描述业务流程、算法逻辑、操作步骤。时序图Sequence强调参与角色之间的消息顺序适合做接口调用链分析、协议交互设计。状态图State Diagram描述一个实体的状态迁移过程适合做订单状态机、设备生命周期管理。类图Class Diagram展示实体结构及其之间的关系适合做系统建模和领域模型设计。甘特图Gantt用来做项目排期和任务调度适合研发管理场景。实体关系图ER Diagram描述数据库表之间的关系适合做数据模型设计。C4 架构图从不同层级描述系统架构适合做系统设计和文档汇报。除了图表类型覆盖广它还支持从一段文本中直接抽取实体和关系生成可视化图谱。比如你把一段混乱的会议纪要丢给它它能自动提取关键人物、事件、状态生成一张关系图。这个能力在需求分析阶段非常实用我经常拿它做客户需求的快速结构化梳理极大节省了做信息整理的时间。3. 手把手实操5 分钟部署并生成第一张图3.1 环境准备与安装步骤这个 skill 的安装方式跟市面上的其他 Agent 插件不太一样它不走中心化的插件市场而是采用目录式安装。你需要手动把仓库克隆到本地的指定目录然后在 Agent 配置里添加对技能的引用。好处是完全开源隐私数据不会经过第三方服务器缺点是第一次配置时有一些细节要注意。我以目前最常用的两种方式分别说下操作流程。如果你用的是 Claude Agent SDK只需要在项目目录下创建一个.claude/skills文件夹然后把仓库里的diagram-skill目录整体复制进去。启动 Agent 后在对话里直接输入“帮我画一张类图”之类的指令它就会自动检测到这个技能的存在。如果你用的是本地需要显式声明的 Python Agent 方案流程会稍有不同要把 skill 目录路径写进你的 Agent 初始化配置里让系统启动时自动加载。具体代码如下from skills_manager import SkillsManager manager SkillsManager() manager.registry_path ./skills/diagram-skill manager.auto_load True这段代码做的事情就是显式告诉 Agent启动时要去./skills/diagram-skill目录加载技能。加载成功后你的工具列表里就会多出一个render_diagram的能力接口后续生成的 Mermaid 代码可以直接通过这个接口渲染。3.2 关键配置参数说明安装完技能之后第一次使用前建议先检查一下配置文件。项目的配置中心里有一系列控制行为模式的参数我用表格把核心的几项列出来方便你对照自己的需求调整参数名可选值/范围默认值作用说明default_formatmermaid / plantuml / svgmermaid指定默认输出的图表语法格式render_inlinetrue / falsefalse是否直接返回渲染后的图片流validate_before_outputtrue / falsetrue输出前是否执行严格的语法预校验style_themedefault / dark / forest / neutraldefault图表配色主题interaction_modeauto / confirmauto是否需要用户确认后才生成完整图表其中validate_before_output是我强烈建议一直保持开启的参数。它会在每一次输出前把生成的 Mermaid 代码扔进解析器确认语法没问题后才交付你。这个开关能挡住绝大多数低级错误。interaction_mode则是在复杂需求下用的如果你描述的图表信息不完整模型会先反问补充关键信息而不是自作聪明地脑补缺失的节点和连线。生成质量要求高的时候我建议改成 confirm 模式。3.3 实战案例从一句描述到一张合格架构图纸上谈兵没有意义我们直接跑一个完整的实战案例。假设我现在需要画一张某微服务架构的简化图需求描述是用户请求先经过 Nginx 网关再到认证服务、订单服务和商品服务认证服务连 Redis订单服务和商品服务连同一个 MySQL 集群。在没有 skill 的情况下直接让 AI 画这种图输出经常是节点位置错乱、箭头含义混乱。而加载了 diagram skill 后我只需要输入一句话“画一个微服务架构图用户请求经过 Nginx 网关后分发到认证、订单、商品三个服务认证服务依赖 Redis订单和商品服务共享 MySQL 集群。”skill 会先调用类型识别模块判断是 C4 架构图还是普通流程图然后选择内置的架构图模板生成下面这段 Mermaid 代码graph TD User[用户] -- Nginx[Nginx 网关] Nginx -- Auth[认证服务] Nginx -- Order[订单服务] Nginx -- Product[商品服务] Auth -- Redis[(Redis)] Order -- MySQL[(MySQL 集群)] Product -- MySQL对比一下实际生成的代码你会发现它比泛泛而谈的 AI 输出多了两层保障一是节点标签都加了合适的类型标注方括号和圆括号的语义关系清晰二是所有依赖关系都有明确的层级方向阅读顺序符合架构图的阅读习惯。你几乎不需要再手动调整直接复制到 Markdown 里就能渲染出一张可用的架构图。这就是 skill 化带来的核心体验差异不需要反复调整提示词它能一次给出像样且可直接使用的成果。4. 效果调优与实践技巧让生成结果从能用变好用4.1 用结构化描述提升识别准确率skill 虽然智能但它并不是读心术。使用体验上的好坏差距很大程度取决于你的描述方式。很多人习惯直接说“画个架构图”然后期望 AI 补全所有细节。这样做出来的图往往大而空缺少有效信息。我试下来效果最稳定的方式是“场景描述 元素清单 关系约束”三段式输入法。场景描述告诉 AI 你画这张图的目的是什么元素清单把图中必须出现的节点都列出来关系约束则说明节点之间是调用、依赖还是聚合关系。比如我要画一张登录时序图我不会只说“画个登录时序图”而是说“描述用户通过账号密码登录的过程参与方为客户端、服务端、数据库。用户提交凭证服务端校验校验成功后返回 Token失败则返回错误信息。注意这是同步调用。”这种输入方式下skill 内置的决策树能非常准确地匹配到时序图分支生成的图几乎零修改。如果你觉得每次写三段式描述太繁琐还可以把这些约束直接固化成自己的提示词模板。拿我自己的例子来说我把常用的几张图的描述都做成了模板用的时候只需要替换实体名称输出质量非常稳定。4.2 模板 定制样式的组合玩法使用内置模板是最稳的生成路线它的优点是好用、不易错但缺点是所有图看起来长得一样。好在 skill 保留了很大程度的样式定制空间你可以通过注入自定义 CSS 主题来控制最终呈现效果。大多数技术图表工具都采用主题化的样式机制换主题就像换博客的皮肤一样简单。实际使用的时候我喜欢在输入中额外增加一句“图表风格使用暗色主题节点边框加粗字体使用系统默认即可”。这个 skill 会根据这句话在生成时设置对应主题参数并渲染出统一的视觉风格。尤其是做团队技术汇报时一套一致的图表风格会让整个文档专业度提升好几个档次不用再像以前那样每张图都手动跑到工具里改色。如果你还想更细致地控制某个节点的展示样式也可以在描述里直接指定比如“把 MySQL 节点画成圆柱体颜色标红表示核心依赖”。只要是 Mermaid 语法支持的样式能力skill 都能帮你落下。4.3 与 Agent 工作流和其他文档工具的配合经验这个 skill 之所以能让我爱不释手还有一个重要原因它能无缝嵌入我已有的 Agent 工作流。我现在的日常项目开发文档几乎全是先在 Agent 里用自然语言描述模块结构让它生成 Mermaid 代码再直接粘贴到项目的 Markdown 文档里。整个过程一气呵成完全不需要中间再开一个绘图软件。如果你用的是 Obsidian、Notion 这类知识管理工具也可以用同样的逻辑。在 Obsidian 里插入 Mermaid 代码块再配合这个 skill 生成代码只要粘贴进代码块就能实时预览比现在很多是在线白板上画图再截图的方式要高效得多。前端团队还可以在项目的持续集成流程里接入 Mermaid CLI让每次生成的图表代码在提交时自动渲染并更新图片版本。这里我特别想分享一个小经验强烈建议你在 Agent 配置里同时加载代码解释器工具。当生成的图表特别复杂涉及大量嵌套结构时代码解释器可以帮忙先执行一遍语法检查甚至在渲染前对布局做预处理。这样等于给图表生成加了一道双保险大幅降低后期手动修正的时间成本。5. 常见问题与排查实录5.1 生成的图表语法校验失败怎么办这是所有用户在初次使用 skill 时最容易遇到的问题。明明描述已经很清楚了但输出就是过不了语法校验排查起来让人头大。根据我自己的使用经验大多数语法失败都集中在几个特定原因上。最常见的坑是特殊字符没有被正确转义。比如节点文本里带有括号、引号或者特殊符号时Mermaid 解析器会直接报错。你描述需求时可能写的是“用户提交表单含备注信息”但中文标点里的括号在某些渲染器里会被当作非法结构符。解法是在描述阶段就尽量用纯文本描述实体名也可以在生成后手动检查节点标签中是否有英文半角括号发现后改成全角或删除。其次是反向连接符号误用。很多人在描述关系时会说“A 调用 B”和“B 被 A 调用”模型如果没有正确理解会把两个方向都画成单向箭头。这虽然不是语法错误但有时候会因为生成了不合理的逻辑而触发校验器警告。解决方式是尽量采用一致的描述习惯比如统一说“谁依赖谁”“谁调用谁”避免使用被动语态。5.2 中文乱码与字体渲染问题部署本地方案时中文乱码问题可以说是最容易劝退新手的拦路虎。Mermaid 本身对中文的支持其实还可以但如果你是在命令行环境里用渲染工具导出图片很可能因为系统中缺少中文字体而导致所有中文节点显示成豆腐块。排查思路分两步。先确认你系统里安装了中文字体比如思源黑体、文泉驿正黑这类常规字体再用命令行重启渲染进程。如果系统里有字体但渲染出来还是乱码那就要检查渲染工具的字体配置把defaultFontFamily手动改为系统中实际存在的中文字体名。以常用的 Mermaid CLI 为例你可以在项目根目录建立一个.mmdc.json配置文件写入这样一段配置{ theme: default, fontFamily: Noto Sans CJK SC }这样设置之后所有通过 CLI 导出的图片都会使用指定的中文字体来渲染。如果你日常是在支持 Mermaid 的网页端看预览那么一般只需要保证代码中的中文标点没有被转码即可。5.3 复杂图表布局错乱与优化策略当你画的图包含的节点超过三十个时布局错乱的现象就开始出现了。这种情况跟 skill 本身的生成质量关系不大更多是 Mermaid 布局引擎在全自动模式下的经典瓶颈。节点多了之后线条会出现重叠、交叉、绕行整个图看起来非常乱。我的实战经验是做分层与子图划分。设计节点描述时提前把相关功能模块放进不同的子图容器中。Mermaid 对子图内部和外部的连线会分开布局极大降低线条交叉概率。比如架构图里你可以把“基础设施层”和“业务服务层”分别定义成两个子图再在子图之间建立连线关系最终出来的图明显更清爽。还有一个非常实用的调优技巧是强制指定节点相对位置在 Mermaid 里用direction声明子图内部是按上下排列还是左右排列。遇到特别复杂的流程图可以将箭头方向统一为上下结构减少自动布局引擎的负担。适当的布局约束不是限制反而会给最终效果带来质的提升。5.4 热门问题速查表现象常见原因推荐解法图表整体渲染失败节点文本含未转义特殊字符检查半角括号、引号改全角或删除特殊符号中文显示为方块渲染环境缺少中文字体系统安装字体并在 CLI 配置文件中显式指定箭头方向不对描述里用了被动语态统一使用“谁调用谁”“谁依赖谁”的主动描述节点布局过密节点数量多且缺少分组使用 subgraph 按层次拆分子图表格信息无法识别描述过于笼统使用“元素清单 关系约束”的结构化描述输出代码被截断图表规模过大超出单次输出长度拆分成多张子图分批次生成后再汇总这个速查表是我自己三个月高强度使用下来沉淀的成果。绝大多数问题你都能在这里找到对应解法。如果碰到表格之外的问题也建议先检查一下你的 Agent 版本和 skill 仓库版本不少渲染问题其实是版本不一致导致的。最后再分享一个小经验我实际用下来这个 diagram skill 最适合拿来处理日常 80% 的常规图表需求。遇到极其复杂的系统全景图我会先让它生成主干结构再手动补充关键细节而不是期待一次描述就能得到完整终稿。它最大的价值是把“从零开始画图”这个事变成了“从高质量草稿开始改图”省掉的时间才是 2.9 万 Star 背后真正让人上瘾的地方。
