分享一个我写的绘制流程图和架构图的 Skill

为什么写这个 Skill

写技术文章或整理项目文档时，经常需要画流程图或架构图，把组件之间的关系和数据流转讲清楚。

流程图或架构图看起来只是摆放节点、画出连线，真正动手时却经常需要反复调整：关系要准确，连线不能接错，文字不能被遮挡，节点大小和整张图的比例还要适合博客阅读。图越复杂，这些检查和修改就越耗时间。

我把这些绘图和检查要求写成了一个 Skill：draw-technical-diagrams。

兼容性说明： 这个 Skill 目前只在 macOS 上通过 Codex 完成了实际测试，因此当前只保证在 macOS 上可用。Windows 和 Linux 尚未经过验证，可能会因为依赖、路径或脚本差异而无法直接运行。理论上，能够读取 Skill 说明并执行本地脚本的 Agent 都可以使用，但安装目录和触发方式可能不同。

Skill 地址：

https://github.com/eventhorizon-cli/skills/tree/main/draw-technical-diagrams

它能做什么

draw-technical-diagrams 用来绘制和修改技术流程图、系统架构图、组件图和数据流图。

输入可以是一段文字、项目代码、技术文章，也可以是一张已经画好但布局不合理的 Mermaid 图。Agent 会根据内容选择流程图或时序图，并尽量保留组件名称、连接方向、系统边界，以及数据流和控制流之间的区别。

默认会保留两类产物：

• Mermaid .mmd 源文件，方便 Agent 和开发者继续阅读、修改。
• 白色背景的高分辨率 PNG，用于博客和普通文档。

根据使用场景，也可以输出 SVG 或 PDF。

当 Mermaid 连续调整后仍然无法稳定排线时，Agent 会按照 Skill 中的规则自动生成显式 SVG，再将它渲染成白底 PNG。使用者不需要提前判断，也不需要单独要求生成 SVG。

这里的“自动”是指 Agent 负责判断布局是否合格并执行兜底流程。render-mermaid.sh 只负责渲染，不会自行理解图中的关系。

如何安装

如果当前 Agent 支持从 GitHub 安装 Skill，可以直接把 Skill 地址交给它：

请安装并使用下面的 Skill：
https://github.com/eventhorizon-cli/skills/tree/main/draw-technical-diagrams

也可以手动克隆仓库，再把 draw-technical-diagrams 目录复制到 Agent 支持的 Skills 目录：

git clone --depth 1 https://github.com/eventhorizon-cli/skills.git

当前的 macOS 渲染脚本依赖 Node.js、npx 和 Google Chrome。第一次渲染时，可能需要联网下载 Mermaid CLI。

Skill 里包含什么

安装后的目录结构并不复杂：

draw-technical-diagrams/
├── SKILL.md
├── agents/
│   └── openai.yaml
├── assets/
│   ├── mermaid.config.json
│   └── puppeteer.macos.json
├── references/
│   └── layout-patterns.md
└── scripts/
    └── render-mermaid.sh

SKILL.md 是核心，它定义了从阅读材料、选择图形类型、生成图源，到渲染和检查最终图片的完整流程。

references/layout-patterns.md 保存常用布局和修复方法，例如系统架构图、双通道数据流、短流程，以及连线歧义和长宽比异常的处理方式。

scripts/render-mermaid.sh 是渲染入口。它使用固定版本的 Mermaid CLI，通过无头浏览器将 .mmd 输出为 PNG、SVG 或 PDF。

assets 目录保存统一的 Mermaid 样式和 macOS 下的浏览器配置，保证图片使用白色背景、可读字体和相对一致的配色。

agents/openai.yaml 保存 Skill 的展示信息和默认提示，不承载核心绘图逻辑。其他 Agent 可以使用自己的元数据格式，也可以忽略这个文件。

怎么用

第一次安装完成后，当前会话可能还没有识别到新的 Skill。如果直接提出绘图要求时没有触发，可以重启 Agent，或者重新打开一个会话。

正常安装并被 Agent 识别后，不需要每次都显式点名 Skill。直接提出“画一张流程图”或“画一张系统架构图”，Agent 会根据 Skill 的说明判断是否调用它。

如果希望明确指定，也可以使用当前 Agent 支持的显式调用方式。例如：

• 在 Codex 中使用 $draw-technical-diagrams。
• 在 Claude Code 中使用 /draw-technical-diagrams。

这些前缀只是显式选择 Skill 的方式，不是使用它的必要条件。

使用时也不需要先写 Mermaid。只要给出要表达的组件、连接关系和输出要求，Agent 就会生成图源、渲染图片并检查最终结果。

绘图不一定一次就能达到预期。 特别是复杂架构图，组件分组、箭头连接、阅读方向和图片长宽比通常还需要继续调整。

如果结果与预期不一致，可以继续和 Agent 沟通，并指出具体问题。例如“把主流程和重试细节拆成两张图”“这条箭头应该连接 Broker，而不是边界框”，或者“图片太宽，请重新分组”。由于图源会被保留，Agent 可以在现有基础上修改并重新渲染，不需要从头开始。

下面用三个由简到繁的例子说明。

例子一：简单业务流程

请画一张订单提交流程图：

用户提交订单 -> 校验订单 -> 写入数据库 -> 返回成功。
校验失败时直接返回错误。

请保留 .mmd，并输出白底高分辨率 PNG。

生成结果如下：

对应的 Mermaid 图源也会保留在 order-submit-flow.mmd 中。

例子二：系统架构图

请绘制一张订单系统架构图：

请按下面四个系统边界组织组件：

- 访问入口：ASP.NET Core Client 通过 API Gateway 访问系统。
- 订单服务：Order Service 将订单数据写入 PostgreSQL，
  并发布 OrderPlaced。
- 消息中间件：RocketMQ 负责投递 OrderPlaced。
- 库存服务：Inventory Consumer 消费 OrderPlaced，
  并将库存数据写入 PostgreSQL。

HTTP 请求、数据库写入和消息流使用实线，
跨边界连线必须连接到具体组件，不能停在边界框上。

保留 .mmd，输出适合博客正文的白底高分辨率 PNG。

生成结果如下：

提示词和图片现在使用相同的四个系统边界。每条连线也都对应提示词中明确给出的 HTTP 请求、数据库写入或消息投递关系。

这张图在生成过程中实际触发了 SVG 兜底。Mermaid 第一版的图片过宽，加入系统边界后，又出现跨边界连线看起来停在边框上的问题。

Agent 按照 Skill 中的规则保留了 order-system-architecture.mmd，生成显式布局文件 order-system-architecture.svg，再输出最终 PNG。

整个过程不需要在提示词中额外要求“如果排线失败就改用 SVG”。

例子三：从文章和代码中整理复杂链路

复杂系统通常不能只靠一串组件名称画清楚。Agent 还需要阅读文章或代码，区分主流程、状态记录和异常恢复等不同部分。

例如，可以这样描述 RocketMQ 5.x 的 gRPC/POP 消费重试流程：

请读取当前项目和文章，
绘制 RocketMQ 5.x gRPC/POP PushConsumer 的重试细节图。

包含业务 Topic、Broker POP、Proxy、gRPC PushConsumer、
检查点、ACK、Revive Topic、POP Revive 和 Retry Topic。

区分处理成功、明确失败、超时或连接中断三种结果，
并把消息投递、状态记录、到期判断与恢复分成三个区域。

保留 .mmd，输出白底高分辨率 PNG，并检查连线、文字和长宽比。

生成结果如下：

这张复杂图同样保留了 grpc-retry-topic-flow.mmd、grpc-retry-topic-flow.svg 和最终 PNG。

实际使用效果可以参考我写的《面向 .NET 开发者的 RocketMQ 入门指南（二）：RocketMQ 如何让业务消息更可靠》。

当前的边界

这个 Skill 不能替代技术事实核对。如果输入的文章或代码不完整，最终图中也可能遗漏关键组件，或错误地表达组件之间的关系。

复杂系统也不适合全部挤在一张图里。遇到这种情况时，Skill 会优先拆分概览图和细节图，而不是通过缩小文字把所有内容塞进同一张图片。

其他系统需要替换浏览器路径或 Puppeteer 配置，并重新检查渲染结果。

实现原理

这个 Skill 本身不是一个新的绘图引擎，而是给 Agent 提供了一套可以重复执行的绘图流程、布局规则和验收标准。

一次完整的执行过程可以分为五步：

1. Agent 阅读 SKILL.md、用户提供的文字、代码或已有图稿，整理组件、连接方向、系统边界和分支语义。
2. Agent 选择流程图或时序图，确定横向或纵向布局，并生成 Mermaid .mmd 图源。
3. render-mermaid.sh 调用固定版本的 Mermaid CLI 和无头浏览器，将图源渲染成白底图片。
4. Agent 打开实际生成的图片，检查文字、节点、箭头、分支、裁切和长宽比，而不是只检查 Mermaid 语法是否正确。
5. 如果图片不合格，Agent 会调整图源并重新渲染。经过两次有针对性的 Mermaid 调整仍无法稳定排线时，Agent 会自动生成显式 SVG，固定节点和连线位置，再输出 PNG。

对应的原理图源保存在 skill-workflow.mmd 中。

因此，这个 Skill 解决的不只是“把 Mermaid 转成图片”，而是让内容整理、图源生成、图片渲染、视觉检查和失败兜底形成一套相对稳定的工作流程。

欢迎关注个人技术公众号