7万星 Archify 上手：一句大白话让 AI 画出可交互系统架构图

给客户讲系统架构的时候，最怕对方来一句「你再讲一遍，刚才那个请求怎么走的」。你在白板上画了三张图，他还在问数据到底存哪儿。Archify 这个项目就是专门治这个的。

今天要聊的项目叫 Archify，作者 tt-a1i，在 GitHub 上已经积累了 7 万星。一句话说清：你给 AI 用大白话描述一段系统流程，它给你生成一张能交互的网页图，不是死图。

先说它跟普通画图工具的根本区别在哪。

先搞清楚它不是啥

作者在说明文档里特意写了一句划清界限的话，我按原意翻译过来：

Archify 不是通用绘图编辑器，也不是 Mermaid 的一个换肤主题。它做的是把技术意图变成沟通产物。

这句话的分量在这儿：Mermaid 那种工具是你写代码它画图，它没有判断力。你写什么它画什么，画出来好不好看、层次清不清楚、箭头绕不绕，它不管。

Archify 里有个智能体在做判断：谁该在上面、谁该在下面、间距给多少、走线怎么走、哪个节点该加重。

01 上手试试

说明文档里的第一个例子特别简单。原话是这么一句：

Use Archify to diagram a web request: Browser calls the API,
the API checks Redis, and a cache miss queries PostgreSQL and fills the cache.

翻过来就是：「用 Archify 画一个网页请求的图，浏览器调接口，接口去查 Redis，缓存没命中就去查 PostgreSQL 并把结果填回缓存。」这句话你直接发给它就行。

这个例子挑得有点意思。它刻意留了一条缓存未命中的分支路径，不是为了画得好看，而是因为真实系统里最需要被讲清楚的恰恰是异常路径，不是主流程。

然后你还能接着往下加：

Add authentication
Highlight the cache-miss path
Switch to the light theme

翻过来就是「加上鉴权」「高亮缓存未命中那条路」「换成浅色主题」。这几句都是自然语言，你不用学它什么语法。

我把它真装下来跑了一遍

光看官方说明不算数，我把它拉到本地真跑了一遍。它的本体是个用 Node 写的命令行工具，archify/bin/archify.mjs，先自检：

node archify/bin/archify.mjs doctor

十八项全绿，最后一行吐出来一句 Archify is ready.。然后拿它自带的 RAG 例子生成图：

node archify/bin/archify.mjs render architecture \
  examples/rag-pipeline.architecture.json rag.html

出来的就是一个 768 KB 的单文件网页。跑完之后还能让它自查：

node archify/bin/archify.mjs check rag.html --json

八项检查全过：单一矢量图、箭头正交、标签避让、关系交叉、走廊不重叠。这些不是画完就完事了，是真的按几何规则验了一遍。

这张就是真跑出来的图。左边用户进来，Guardrail 先过滤，Orchestrator 编排，Retriever 检索，Reranker 重排，最后 LLM 出答案；上面 Semantic Cache 那一圈是命中缓存的快路，下面 Ingestion Pipeline 是文档入库那条线。六个颜色图例对应后端、数据库、云服务、安全、外部系统五类角色。

同一个引擎还能画别的类型。这是我用它的时序图模式跑的缓存未命中时序图，七个参与者、按阶段分带、六种箭头语义，比架构图更适合讲「一个请求按什么顺序走」。

这是工作流模式，泳道分组加节点，适合讲一个流程分几个阶段、哪一步可能被拦下来。

不需要有代码库也能用

官方说明里明确写了：不需要有代码库。你可以从一个描述开始，也可以让它去读一个仓库，生成带源码依据的架构图。

02 适用场景

它把自己定位得挺宽。作者说，从旅行行程、学习地图到复杂系统，只要是你想搞明白、想规划、想分享的东西，都能画成交互式的网页。

最常见的是这几类：

• 系统架构：代码库或描述变成图。节点上能标「源码」标记，点开直接跳到 GitHub 上对应文件和行号。
• 工作流：端到端流程拆解。持续集成、审批、部署、回滚这种，一条链画下来最清楚。
• 学习地图：知识点的依赖关系。哪个概念得先学、哪个是前置，摆出来一目了然。
• 方案说明：给客户或同事讲清楚。生成的网页能直接分享链接。

03 工程实现

这部分是我觉得它比同类项目更值得说的地方。作者摊了不少工程细节出来。

• 版式判断优先于自动布局：它不用通用自动布局那套。层次、间距、走线、重点，它自己判断。多个箭头指向同一处时，端点会按确定规则散开，不会全堆在一个中点上。
• 带类型的 JSON 中间表示：每一种图都有固定格式，有可复现的源文件。不是让模型自由发挥直接生成网页。
• 交付前原子校验：格式、版式、网页与矢量图、走线、标签与走线的避让，全部通过才替换上一个已知可用的产物。
• 失败给你一份「修复单」：校验失败时不甩一个程序报错栈出来。它返回稳定的规则编码、具体对象、量化的证据，还只给你受支持的修复手段。
• 保留上一个好版本：桌面预览模式下，源文件改坏了、存成非法的了，屏幕上还是显示上一个验证过的好图，不会唰地一下变成空白。

最后两条是我最看重的工程习惯。绝大多数生成类工具只管生成不管兜底，改错一下就给你个白屏或者一堆报错。它做了「上一次已知可用」这个状态保留，这是当成正经软件在做，不是当玩具在做。

04 设计思路

作者列了这么几条，我挑两条翻译过来。

第一条是关于「真实性」的：焦点、上下游可达范围、精确路径、角色对比，这些都复用作者画好的节点和关系，不会自己去发明一个拓扑结构、也不会声称有什么运行时影响。

第二条是关于「证据」的：带源码依据的架构节点会自己标上源码第 n 行的标记，点开就是钉在某个公开提交上的 GitHub 文件和行号。不带源码依据的普通产物就没有这个。

这是它跟「AI 瞎画一张漂亮图」最大的区别

瞎画的图看着漂亮，但你一追问「这个模块在哪行代码里」，就露馅了。能给出行号、还钉在具体提交上，这图拿去给客户看就不虚了。

05 安装使用

一条命令，主流的几个 AI 编程工具都支持：

npx skills add tt-a1i/archify -g

装完之后你正常跟它说话就行。不需要学它的命令语法，说明文档里那几行命令是给想直接操作的人用的。

输出就是一个网页文件，自成一体，能直接分享。想导出的话图、视频、分享卡片都有。MIT 开源协议，作者还配了简体中文的说明文档。

06 说点实话

三点。

• 第一，七万星这个数字得掂量：这类技能项目星数涨得都特别快，成本低、传播快。它真实的质量比星数给人的印象要低一些。别拿星数当验收标准，自己试一遍最准。
• 第二，简单图别用它：画个三节点的流程图、画个简单的时序图，Mermaid 十秒钟写完，比装一套技能快。它的价值在复杂系统上，简单场景属于杀鸡用牛刀。
• 第三，图好看不等于系统对：它画的是你描述的那个系统，你描述得不全、理解得有偏，它画得越漂亮越容易误导人。给客户看之前，自己得先把逻辑过一遍。

07 写在最后

为什么单独讲这个项目。

现在让 AI 生成代码、生成文档的工具一大堆，但「让 AI 帮你把复杂的东西讲清楚」这一类，做得好的不多。这个方向的价值是实打实的：把系统讲明白，是干技术活儿里最耗人、最难外包出去的一件事。

要是你也经常碰上「我得给人讲清楚一个系统」这种活儿，装一个试试，从说明文档里那个浏览器调接口的例子开始。类似的话题，在 云栈社区 上也常有开发者一起讨论。