第43章：架构图：让 Agent 把系统画给人看

"正如斧头必须适合人手才能有用，软件必须适合人脑才能有用。"

—— Coda Hale

第 42 章讲完了设计工具，第四部分还剩一个话题：架构图。需求理完（第 31 章），代码写完，中间和之后都需要一张图，告诉所有人这个系统长什么样。

架构图在 Agent 时代的位置变了。以前画图是手工劳动：打开绘图工具，拖框，拉线，调对齐，导出贴进文档。图和代码住在两个世界，代码改了图不会动，半年后没人信那张图。Diagrams-as-code 把图从二进制的绘图文件变成一段文本：图可以 diff，可以 review，可以进 git。写文本正好是 Agent 最擅长的事。

于是画图成了 skill 市场上热闹的赛道。archify 拿过 GitHub Trending 周榜全语言第一，diagram-design 半年攒了 4 万多 star，交易所 Bybit 也下场发了一个。这一章看三件事：静态图选哪个，交互式图选哪个，想从代码直接出图用哪个。

43.1 图是代码的一部分

先看一个前提变化。Markdown 里写一个 mermaid 代码块，GitHub 和 GitLab 会直接渲染成图。这意味着图和代码可以住在同一个 PR 里：改了架构，顺手改一段文本描述的架构，reviewer 在同一个 diff 里看到两件事。

这就是 diagrams-as-code 的核心好处。图变成了一段文本。文本有版本，能比较，能自动生成，也能被程序消费。Agent 读一遍代码库，输出一段 mermaid，架构图就有了。

传统画图工具没有消失，draw.io 还在，Excalidraw 也很好用。但它们的产物是文件，Agent 只能整文件读写，人只能手动拖拽。文本格式的图，人和 Agent 改的是同一种东西。下面看几个最知名的画图 skill。

43.2 diagram-design：先删到只剩必要的框

diagram-design（github.com/cathrynlavery/diagram-design）的作者 Cathryn Lavery 是写作者兼创业者，写博客，还经营消费品牌 BestSelf.co。她让 Claude 画图，得到的都是通用的圆角框，和网站的其余部分完全不搭。要么和 Figma 较劲半小时，要么干脆不放图。她把这个痛点做成了 skill，2026 年 4 月发布，到 9 月攒了 4.2 万 star，是画图类 skill 里安装量最高的一个。

README 里有一句自我定位：editorial diagrams your designer won't hate，设计师不会皱眉的编辑级图。

它内置 40 多种图型：架构、流程、时序、状态机、ER、时间线、泳道、象限、雷达、飞轮、树、组织架构、分层堆栈、韦恩图、金字塔、桑基图、鱼骨图、Wardley 地图、看板、用户旅程、部署、依赖图、UML 类图、故事地图、数据库 schema。v2.5.10 一个版本补了 10 种。每种图有三个静态变体：极简浅色、极简深色、全编辑风。输出是自包含的 HTML 和 SVG，没有构建步骤，不依赖 JavaScript。

它还会读你的网站，按站点现有的配色和字体给图配品牌，官方说法是 60 秒完成。

设计哲学浓缩在作者的一句话里：The highest-quality move is usually deletion（最高质量的动作通常是删除）。落到规则上是三条：每个节点都要挣到自己的位置；强调色只留给读者最先要看的一两处；目标密度 4/10。它对语义和版式也做了分离：队列、策略路径、信任边界这类行为描述，套到最接近的图型上就行，不用为每种行为新发明一个类型。现成的 draw.io、Mermaid、Excalidraw 图，它也能按指定的格式和细节级别重画。

安装走 Claude Code 的插件市场：/plugin marketplace add cathrynlavery/diagram-design。

43.3 archify：会动的图，能对账的图

archify（github.com/tt-a1i/archify）2026 年 4 月发布，到 9 月攒了 7.2 万 star，拿过 GitHub Trending 周榜全语言第一，量子位做过专访。Kimi Work 把它收进了自己的插件商店，名字改成 Interactive Architecture Diagram。

它的输出是交互式 HTML。预设几种风格（Signal Flow、Blueprint、Classic）；视图可以命名，一键跳到 happy path；路径可以高亮，点一下，从 Web 应用到数据库的整条链路亮起来；lens 可以聚焦，只看后端和数据库的关系；还有章节模式，像翻页一样把图讲一遍。

它的第二个卖点是 verifiable。它可以读一个真实的代码库，产出带出处的图。官方案例里，archify 追踪了 mco-org/mco 仓库的一个 commit，产出的系统图带类型化的 JSON 源文件和校验收据。Proof Lab 放了 11 个场景，每个都有 JSON 源和校验记录可查。

产物是单个自包含 HTML，发给同事，交互全部带过去，看的人不需要装任何东西。社区把它用在了意想不到的地方：有人把上海 CityWalk 攻略做成四天行程图，可以切换 D1 到 D4，点一个地点直接跳高德、小红书、大众点评。图是架构图还是旅行图，它不在乎，交互式地图这个形态是通用的。

安装一行：npx skills add tt-a1i/archify -g，支持 Claude Code、Cursor、Codex CLI、OpenCode。

同一条路线上还有个轻量的选择：architecture-diagram-skill（github.com/konraddzbik/architecture-diagram-skill）。也是单 HTML 文件，按场景分 tab，比如 RAG Query、Login、Ingest；动画数据包沿曲线在服务之间流动，侧栏显示当前这一步的 payload 和延迟、端口这类元数据；支持 dev/prod、v1/v2 模式切换；节点可以拖拽，布局存在 localStorage。作者把适用边界写在 README 里：要的是"点进去看数据怎么流"，用这个；只要静态框线图，mermaid 更简单。

43.4 svg-diagram：把版式写成算术

svg-diagram（github.com/bybit-exchange/svg-diagram）来自交易所 Bybit 的工程团队，思路和前面几家都不同：不让布局引擎排版，让 Agent 按一套家规手写 SVG。

家规管到像素。README 里有一张表，每一条都是算术：盒子高度从字号推导，一行是 font-size × 3，每多一行加 1.5 倍；文字基线在盒子高度的中点上再偏移 font-size × 0.35，正好居中；箭头离起点留 5px，离终点留 11px；直线连线旁的文字留 10px 净空，曲线旁留 15px；连线转弯不许走直角肘，必须用曲线。中文有单独的字符宽度表，一个汉字按整个字号算宽度，12px 就是 12px，不按拉丁字符的窄宽度估。字体栈强制带上 Noto Sans CJK SC，Linux 上不会把中文渲染成豆腐块。颜色固定五组，每组是填色、描边、文字色三元组，按语义选用。第一个元素永远是一块白色画布矩形，图嵌进 GitHub 的深色主题里依然可读。

家规配了一个 linter 来保证执行：svg-lint，纯 Node，零依赖，12 项检查，读的是最终的 SVG 文件本身，不经过任何中间格式。报错格式是"viewBox: 11 → 20-25"，现在的值和应该的值都直接给出来。

坚持手写坐标，换来的是可审查。每个坐标都是字面量，后面跟一行注释，解释这个值为什么成立。改图读起来是一个 diff。产物是纯 SVG，没有运行时，README、文档站、PDF、终端预览里都能直接渲染。

安装：npx skills add bybit-exchange/svg-diagram -g。官方 gallery 十张图全部 lint 通过，下图是其中一张：Agent、svg-lint 和文件系统的协作时序图。

43.5 从代码库出发：/insight-diagram

前面几个 skill 都偏"你描述，它画"。第 8 章的 goal-workflow 套件里有一个 Bonus skill 走了另一个入口：/insight-diagram（介绍页 https://goal.rpcx.io/index_cn.html#step-diagram ）。

它的流程是：分析代码库，识别关键组件和依赖；列出 17 种图供你选，8 种结构图加 9 种行为图，从系统架构图、类图到状态机图、序列图；选中的图渲染成 HTML+SVG，存到 docs/ 目录。

它默认推荐的组合是三张：架构图看整体，序列图看一次关键请求的旅程，流程图看业务分支。三张图各有分工，日常够用。

第 35 章用 goscapy 项目完整走过一遍它的流程和几何校验，这里不重复。只补一句定位：它从真实代码出发，图上每个框都对应代码里存在的东西。

43.6 本章小结

至此第四部分讲完，全书也到这里收尾。