企业官网建设流程全解析

开工前先把话挑明：这个“diagram skill”不是又一个靠酷炫前端界面凑出来的开源玩具，它是真正把“让 AI 画出一张准确、可迭代、可直接交付的图”这件事做明白了的项目。上个月我在 GitHub 上刷到它时，star 还在噌噌往上涨，转眼已经到了 2.9 万这个量级。评论区里有人用它画架构图，有人拿去画数据库 ER 图，还有嵌入式工程师用它直接输出芯片引脚图，整整齐齐地对应 datasheet。这篇文章不讲虚的，我会从它为什么能火、内部怎么设计、怎么装怎么用、有哪些坑，一路拆到你能基于这个思路做自己的 skill。

1. 现象级 star 背后：为什么偏偏是“画图”这个场景被引爆

1.1 从“AI 写文字”到“AI 画图”，中间隔了一个确定性鸿沟

先说你我都遇到过的问题。让大模型写一段方案、写一段代码，它基本能给出不错的结果，因为语言是它的主战场。但一旦让它“画一张系统架构图”，不管是让 ChatGPT 直接输出图，还是让它生成 Mermaid 代码，结果经常很微妙：方向箭头胡乱指、节点布局重叠、图例和内容对不上。你催它“再调整一下”，它甚至会在下一版把上一版正确的连接线改错。这不是模型不够聪明，而是图表本身就要求强约束：每个节点有位子，每条边有拓扑方向，每个 label 不能重叠。大模型天然擅长模糊推理，不擅长解决强约束下的几何与拓扑问题。

diagram skill 这个项目的核心思路，说白了就是把“画图”这件需要确定性的事情从大模型的自由发挥里剥出来：模型只负责生成结构化的图形描述文本，渲染交给确定的引擎去完成。引擎不会“灵机一动”，你给它什么语法，它就不打折扣地画出什么图。这一步拆分，直接让“AI 画图”从碰运气变成了流水线作业。

1.2 2025 年 Agent 生态大爆发，让 skill 成了最好的分发单位

你可能注意到，最近一年 GitHub 上冒出一堆以 “skill” 结尾的仓库，比如 superpower skill、codex skill、claude code skill 之类的。这里有个大背景：Claude Code、Codex CLI、Trae 这些 AI agent 工具，都开始支持一种叫“技能/Skill”的扩展机制。你可以把 skill 理解成给 agent 提前装好的一套“岗位说明书 + 操作手册 + 工具脚本”。一个 skill 往往就放在一个目录里，里面有SKILL.md描述触发条件和执行步骤，有可能带几个辅助脚本，agent 在对话中会根据场景自动读取并调用。这种分发形式极轻，clone 下来往配置目录一放，你的 agent 就多了一项职业能力。

画图这件事天然就是 agent 工作流里的一块洼地。你让 agent 帮你梳理代码模块、给新服务画个链路图，它要做的工作可不仅仅是“会写点 Mermaid”，而是要：先理解上下文 → 判断该画什么图 → 组织正确的图语法 → 调用渲染器 → 生成文件 → 验证结果。把这一整套流程编成一个 skill，agent 就能自动执行，而不是每次都在 prompt 里反复强调。diagram skill 在 star 数上暴涨，本质上是吃到了这波 Agent 生态红利：大家在同一个时间节点发现，原来技能市场里最缺的不是“会聊天的”，而是“会干活的”。

1.3 skill 和 agent 到底有什么边界

不少人在社区问“skill 和 agent 的区别”。按我自己的理解，agent 是负责“想”的，它负责拆解大目标、编排步骤、决定下一步调用什么；skill 则是负责“做”的，它是一份已经被验证过的过程化知识，agent 只要照着执行就可以拿到固定质量的结果。拿画图举例：agent 看到你给它下发“画一下订单服务依赖图”的任务，它会拆成“读取代码→抽取依赖→生成 mermaid→调用渲染器”，其中“怎么生成 mermaid、怎么选类型、怎么渲染”这部分既有经验沉淀了下来，打包成一个 skill。以后任何 agent 装上这个 skill，画图就不用重新踩坑。所以别把两者对立，它们是大脑和经验手册的关系，不是竞争关系。

2. skill 的底层设计：把 LLM 的画图短板交给确定性引擎

2.1 流程图、时序图、架构图、ER 图：一次覆盖四种高频场景

diagram skill 的价值不仅在于“会画图”，还在于它把工程研发中最常用的图表类型全部收纳了。我看它的设计，至少覆盖了四类主流场景：流程图、时序图、架构图、ER 图。每一类图背后对应一种不同的建模思路。画流程图时你要梳理清楚分支和汇聚节点；画时序图时要严格表达消息顺序和生命周期；画架构图时要处理模块分层和依赖关系；画 ER 图时要准确把握实体、属性和一对多/多对多关系。如果没有 skill 预先帮你约束这些规则，让大模型裸奔去画，它会在“画流程图”时莫名给你加一堆泳道，在“画 ER 图”时把外键关系描述得模棱两可。而 skill 里通常会写明每种图的适用模板、语法规则和“避免做什么”的红线。

像我前阵子给一个小型电商系统画服务依赖图，直接让 agent 画，它给了一堆嵌套节点，语义上很丰富，but 渲染出来像一锅粥。换成在 prompt 里声明让它调用 diagram skill 之后，它自动先判断“这是一张偏分层的架构图”，然后按照 skill 里定义的模板，输出节点分组、依赖连线和外部边界，渲染出来基本可以直接放进方案文档里。这个差别，用过的人会非常明显。

2.2 Mermaid、Graphviz、D2、Python Diagrams：渲染引擎怎么选

既然要把确定性交给引擎，那引擎本身的选择就很关键。实际情况中，不同 skill 项目会在渲染层做不同取舍。我分类说一下，后面你自建 skill 时也用得上：

diagram skill 能这么火，很大一部分原因是它没有盲目押注单一渲染引擎，而是把 Mermaid 作为默认、Graphviz 和 D2 作为可选项。Mermaid 最大的优势是门槛低：你让模型生成的文本，人也能直接看懂；GitHub、Notion 这类工具直接渲染.mmd文件，交付后别人不用装任何软件就能看。而 Graphviz 则用来兜底那些 Mermaid 排版确实搞不定的复杂依赖图。这种“主引擎 + 备用引擎”的设计，给了 skill 极高的场景适配性。

2.3 模型只写描述，引擎负责渲染：工作流怎么拆

好的 skill 不仅定义“用什么工具”，它还会定义“先做什么、再做什么、最后怎么验证”。diagram skill 的工作流我拆开看大概是五步：

1. 根据用户请求和上下文，确定图表类型（流程图、时序图、架构图、ER 图等）。
2. 在内存/暂存文件里，先用结构化的“文字草稿”描述图的含义，比如有哪些节点、节点之间是什么关系。
3. 把这份文字草稿翻译成目标引擎语法，比如 Mermaid 的graph TD; A-->B;。
4. 把语法文本写入.mmd文件，调用渲染器生成 SVG/PNG 等最终产物。
5. 回读产物并验证：如果渲染失败，根据报错信息修正语法后重新渲染；如果渲染成功，向用户报告产物路径。

这个流程看起来简单，实际上把“思考”和“制图”解耦了。模型负责推理结构，渲染器负责几何处理。我见过不少失败的 prompt 工程，问题就出现在让模型“一步到位直接生成成品图”，这等于既让它当建筑师又让它当施工队，它显然干不好。diagram skill 的做法就是强制加了一道“文本草稿”的中间层。说出来你可能觉得平淡，但这个设计正是 2.9 万 star 的技术底气。

3. 从零接入：目录结构、安装与一次绘图实测

3.1 装 skill 的两种标准姿势

要上手 diagram skill，先把项目源码或者打包好的目录放到 agent 会扫描的 skills 目录里。以当前主流 agent 的目录约定为例，一般是~/.claude/skills/或者项目内的.claude/skills/；如果用的是其他兼容 agent，就放到它对应的skills目录。装法通常有两种。

第一种，直接用 git clone：

mkdir -p ~/.claude/skills cd ~/.claude/skills git clone https://github.com/xxx/diagrams-skill.git diagrams

第二种，如果你不想整个仓库挂进来，也可以手动复制相关文件：

mkdir -p ~/.claude/skills/diagrams cp SKILL.md render.py config.yaml ~/.claude/skills/diagrams/

装完以后，重启你的 agent 客户端，让 skill 清单重新加载。一个比较常见的误区是装完不重启，导致 agent 看不到新技能，于是对话里还是走“裸奔”流程。如果你不确定装没装上，直接问一句“你现在有哪些 skill”，它会把它能感知到的技能列表列出来。

3.2 看明白 SKILL.md：skill 的心智核心

一个 skill 能不能用得好，SKILL.md的编写质量占 80%。diagram skill 的SKILL.md大概是这种结构：

--- name: diagrams description: 根据上下文创建或修改各种图表，包括流程图、时序图、架构图、ER 图。当用户需要可视化概念、流程、架构或数据关系时启用。 --- # Diagrams Skill ## 适用场景 - 系统架构梳理 - 业务流程可视化 - 数据库模型设计 - 接口调用时序 ... ## 图表类型选择 1. 如果是描述业务流程，使用 flowchart 2. 如果是描述消息交换过程，使用 sequenceDiagram 3. 如果是描述系统模块，使用 architecture 4. 如果是描述数据关系，使用 erDiagram ... ## 执行步骤 1. 识别需求 2. 先写节点关系草稿 3. 再生成目标格式语法 4. 写入文件并用 renderer 渲染 5. 验证输出 ...

重点在于 frontmatter 里的description，它决定了 agent 什么时候会主动想起启用这个 skill。描述写得越具体，触发时机越准。如果你发现 agent 在该画图时没调用 skill，十有八九是description写得过于泛化，模型无法把它和当前任务关联起来。

3.3 一次完整的实测：画电商下单链路

光说不练假把式，我来跑一个实际案例。假设我要让 agent 画一张“用户下单到支付完成”的时序图，prompt 大概是：

请用 diagram skill 画一张订单支付时序图： 用户创建订单 -> 调用库存服务扣减库存 -> 创建支付单 -> 调用支付网关 -> 回调通知 -> 更新订单状态

agent 识别到这是时序图场景，会执行 skill 里的步骤，大概率生成一个sequenceDiagram文件。它内部的渲染脚本会把.mmd文件转成 SVG：

npx -y @mermaid-js/mermaid-cli -i ./order_payment.mmd -o ./order_payment.svg

我实测跑下来，整个过程大约十几秒。出图效果符合预期，消息箭头从上到下排列清楚，生命周期虚线也在该出现的位置出现。这一步的体验非常扎实，是因为渲染引擎替模型兜了底：模型即使把某些节点的相对顺序写乱，Mermaid 的布局引擎也不会把节点叠成一团，它会在有限区域内尽量平衡排列。对最终用户来说，这种“稳定可控”的体验，远比偶尔惊艳但常常翻车的裸奔画图要好得多。

3.4 没有装 Mermaid CLI 怎么办：备好两条路线

npx @mermaid-js/mermaid-cli是个挺实用的渲染方案，但有个现实问题：它内部要启 Puppeteer 去渲染 HTML，第一次跑的时候要下 Chromium，网络不好的环境下经常卡半天，还会因为系统缺依赖报错。我们的思路是准备好两条备选路线：

• 路线 A：本地全局安装@mermaid-js/mermaid-cli，省去每次 npx 拉包的延迟。
• 路线 B：如果画的是简单架构图，直接把生成的.mmd内容粘贴到支持 Mermaid 的在线工具或者 IDE 插件里查看，不一定非要本地渲染成 SVG。很多团队文档平台天然支持 Mermaid 代码块，那连本地渲染都省了。

我个人的建议是：本地能装则装，因为自动化链路里最后一步“验证渲染成功”需要本地有渲染器。如果你在安全受限环境里装不了 puppeteer，也可以考虑配置远程渲染服务器，或者退回到 Graphviz 这类不需要浏览器的二进制渲染器。

4. 这个 skill 到底做对了什么：拆解它走红的技术原因

4.1 它把“精确”从模型的幻觉手里抢了回来

一个 repo 能在 GitHub 冲到 2.9 万 star，绝不是靠刷屏营销。diagram skill 最核心的竞争力在于：它用系统设计消灭了大模型的“图上幻觉”。所谓图上幻觉，就是模型一本正经地画出与事实不符的连接关系，比如把 A 服务调 B 服务画成 B 调 A，甚至凭空多出两个不存在的中间件。

为什么会有这种幻觉？因为模型训练数据里，类似架构图的描述太多，它是在“预测下一个 token”，不是在“测量系统接口”。要避免这种问题，唯一可靠的办法是给模型一个明确的证据来源。diagram skill 的工程化设计里通常会要求模型先列出节点和边的“证据链”，比如“来自哪个文件的哪段代码”“和哪张表的外键对应”。有了这个证据链，再让模型把这些信息转换成图形语法，图形的正确率就高得多。这个“证据链优先”的设计，比任何花哨的 prompt 都管用。

4.2 自动动手，而不是让用户 Copy 代码块

普通 AI 画图工具给你一段 Mermaid 代码，然后就结束了，剩下的复制粘贴、保存文件、手动渲染全靠你自己。diagram skill 打破了这个体验：它会让 agent 直接在当前工作区创建文件，调用脚本渲染出成品，甚至自动打开预览。这个从“给你代码块”到“帮你生成文件”的跳跃，看似只有一步，却极大降低了使用成本。GitHub 上能得到开发者青睐的项目，往往都是能丝滑吃进已有工作流的，而不是让你再单独开一个工具。

4.3 与 Claude Code / Codex / Trae 等生态无缝兼容

再看它为什么能趁势而起，而不是早两年出现。2023 年那阵子，市面上还没有成熟的 agent 工作流，你就算写出一个 skill 目录也没有载体去执行。到 2025 年，Claude Code、Codex CLI、Trae 这些 agent 相继支持“读目录里的 SKILL.md → 按步骤执行 → 调用外部脚本”的机制，这个 skill 的基本功才能发挥出来。换句话说，它吃到的是 agent 基础设施成熟的第二波红利。你把它装进 Claude Code，它会遵守 Claude 的 skill 协议；安装到支持相同目录规范的其他工具里，执行效果也大差不差。生态兼容面广，star 数自然就容易滚起来。

4.4 对比普通“Superpower Skill”：垂直纵深 vs 提示词堆叠

我留意到热词里也有 superpower skill，它属于另一派：把大量“方法论提示词”打包成一个超大 skill，覆盖写作、编程、思考、Plan 等方方面面。这类 skill 乍看很爽，实际用起来经常出现“什么都会但什么都不精”的情况。diagram skill 走的路线明显不同：它只在“画图”这一个垂直场景里做深做透，定义清楚图表类型选择、工作流、调用的渲染引擎、产出的文件位置，还顺带给出验证机制。垂直纵深比横向堆叠更有生命力，这是它能在细分场景拿到大量 star 的另一个原因。

5. 定制、踩坑和实战经验：从 74LS00 引脚图到生产级产出

5.1 一个硬核案例：用 diagram skill 画 74LS00 引脚图

热词里有个“74ls00pinout diagram”，我看到时差点笑出来，因为这正是我踩过坑的场景。74LS00 是经典的 TTL 二输入与非门芯片，14 个引脚，要让 AI 准确画它的引脚图并不容易：模型经常把 7 脚 GND 和 14 脚 VCC 搞反，甚至把 1A、1B、1Y 的对应关系画乱。

我用 diagram skill 试了一下，让它生成一个用于快速理解接线逻辑的表格化图形，而不是真正意义上的物理封装图。由于 skill 会强制模型“先列结构化信息，再转图形语法”，它就能先列出一张准确的事实表：

然后再把这张表转换成流程图里那种“左侧输入 → 中间与非门 → 右侧输出”的示意图。虽然 Mermaid 画不了工业级封装图，但画逻辑连接关系已经足够了。这个用例说明：diagram skill 最适合的其实是“信息结构化图”，只要先把数据表列对，图就差不到哪去。

5.2 踩坑实录：Mermaid 渲染失败、中文字体、乱序输出

我用 diagram skill 跑了不少图，也踩了不少坑，挑三个最典型的分享。

第一个坑是 Mermaid 语法里的特殊字符。模型画时序图时，消息内容里如果带引号、冒号、括号，特别是中文括号“（（））”，渲染器很容易直接报语法错误。后来我发现 skill 里其实写了“如果消息文本包含特殊字符，请用双引号包裹或去掉括号”，但模型偶尔还是不听。所以我在自己的定制版本里加了一条更强制的要求：任何消息文本一律不允许出现英文括号，中文文本里该用引号的必须成对。

第二个坑是渲染器字体问题。Mermaid CLI 跑出来的 SVG，在中文环境下偶尔会出现豆腐块。这是因为 puppeteer 渲染时找不到合适的中文字体。解决办法也不复杂，装个中文字体包到系统里，或者用-f参数指定字体文件。我本地用 Linux 环境，执行过一次apt install fonts-noto-cjk之后，中文渲染就正常了。你要是用 Windows 或者 macOS，通常系统自带的中文字体已经够用，问题不大。

第三个坑是执行顺序被模型打乱。skill 明明写了“先写草稿，再渲染”，模型碰到复杂任务时却经常想走捷径，草稿写到一半就急着调渲染器，结果画出来缺节点。为了纠正这个行为，我在 SKILL.md 的步骤描述里故意加了两行：第一步用“必须输出节点清单”，第二步用“等待用户确认后继续”。强制它把结构化草稿当作一个独立交付物，而不是随手一写的过程变量。加了这一招之后，出图稳定性明显提升。

5.3 想自建 skill？一套经过验证的“最小可跑模板”

diagram skill 的模式完全可以复用到别的垂直场景。我自己搭技能包的时候，总结了四条经验，你可以直接抄：

1. SKILL.md 里必须有清晰的description，并且带上触发关键词，例如“画图”“图”“diagram”“flowchart”“架构图”“ER 图”。
2. 执行步骤必须“可勾选”，每一步的输入输出都要有明确凭证。就像 skill 里第一步生成节点清单，第二步生成语法文件，第三步渲染并验证。
3. 渲染错误要有“自动修复循环”。skill 里可以写：检测到渲染器返回非零退出码时，读取错误信息并再生成修正版语法文件，最多重试两次。
4. 把默认输出路径固定下来，比如docs/diagrams/。这样生成的图会统一收进目录，方便你事后整理，也让 agent 在后续对话中能准确找到历史产物。

5.4 跑偏的风险：别让 skill 做它不擅长的事

最后给个提醒。diagram skill 再强，也不是万能画笔。我见过有人拿它画深度定制的专业电路原理图，也有人想让它输出符合出版级排版的复杂 UML 图。Mermaid 和大部分确定性渲染引擎，都不支持像素级精确控制。遇到这种高度定制需求，老老实实用对应专业工具，而不是拿 hammer 拧螺丝。skill 适合的是“结构清晰、可描述、可复用”的图形生成，它带来的最大价值是节省了你从“想法”到“第一版图”的时间。至于你要不要在这张图基础上继续精修，那是另一段工作。

回到 star 数这件事，2.9 万本身当然重要，但更值得关注的是它验证了一个产品逻辑：在 agent 时代，专注、可复用、带确定性保障的“技能包”，正在成为开发者生产力的放大器。装上这个 skill 后，我自己的体验是：以前一个上午画不出一张满意的架构图，现在十分钟能产三版带迭代痕迹的图。可能你也该试试。