Archify：让 AI 画出可信的架构图，而不是”看起来像”的架构图

> 原项目：tt-a1i/archify · 4260 stars/day · JavaScript

一个常见的翻车现场

你让 AI 帮你画一张系统架构图。它给你返回一张漂亮的 Mermaid 图——箭头整齐、配色舒服、节点命名也很专业。你把它贴进 PPT，开会时指着图讲：”这是我们的微服务架构。”

然后新来的同事问：”Kafka 到 payment-service 的消息是同步还是异步？”

你愣住了。图上画的是一条箭头，但 AI 不知道这是同步调用还是消息队列——它只是觉得”这两个节点之间应该有条线”。

这就是 AI 画图的核心问题：它画的是”看起来像架构图”的东西，而不是”经过验证的架构图”。线条的语义、节点的依赖、路由的真实性——全靠猜。

Archify 这个项目要解决的，就是这件事。

核心思路：把”画图”拆成两步——描述 + 编译

Archify 的设计哲学可以用一句话概括：

> 让 AI 做它擅长的（理解代码、提取结构），让它不擅长的（精确渲染、拓扑验证）交给确定性引擎。

具体来说，整个流程被拆成两步：

1. Agent 产出 typed JSON IR（中间表示）：AI 读你的代码库或系统描述，输出一份结构化的 JSON——节点是什么、边是什么类型、数据流向哪里。这一步 AI 做得很好，因为它是”理解语义”的活。 2. Archify 确定性地编译 JSON IR → HTML/SVG：一个 Node.js 渲染引擎拿过这份 JSON，按照严格的规则把它编译成交互式 HTML。每条边的起点终点、每个节点的角色、每条路由的路径——全部从 JSON 里来，不靠 AI”创作”。

这让我想到编译器的经典分层：前端负责理解语义，后端负责生成代码。AI 是前端，Archify 是后端。中间的 JSON IR 就是 AST。

这种分层的妙处在于：输出是可验证的。你可以 diff 两个版本的 JSON IR，精确看到”这次改动新增了 2 个节点、删除了 1 条边、改了 3 个角色”——而不是”图看起来不太一样了”。

五种图，不是一个万能图

Archify 支持五种图类型：

– 架构图（Architecture）：系统组件和依赖关系 – 工作流图（Workflow）：业务流程和状态转换 – 时序图（Sequence）：调用链和消息顺序 – 数据流图（Data-flow）：数据从哪来到哪去 – 生命周期图（Lifecycle）：实体状态随时间变化

为什么是五种而不是一种？因为不同的问题需要不同的视角。你想回答”支付失败会回滚吗”——看时序图；想回答”这个数据会被谁消费”——看数据流图。一张大而全的架构图回答不了任何具体问题。

这和软件工程里的”视图模型”传统一致——4+1 视图模型（Kruchten 1995）早就说过：逻辑视图、进程视图、开发视图、物理视图、场景视图，每个视图服务不同的 stakeholder。Archify 把这个理念落地到了 AI 生成图上。

Proof Lab：让每条线都说得清楚

Archify 最有意思的功能是 Proof Lab——一个交互式的”验证实验室”。在生成的 HTML 里，你可以：

– 搜索节点：输入一个服务名，高亮它的所有依赖 – 追踪上游/下游：选中一个节点，看”谁会影响它”和”它会影响谁” – 比较角色：对比两个服务在系统中的真实作用 – 播放引导故事：按预设剧本走一遍流程，每一步都有图示

这背后的设计理念是：图不是用来看的，是用来查的。一张静态架构图的价值有限，但一个可交互、可追溯、可验证的”系统地图”价值无限。

类比一下：这就像 Git 的 git log 和 GitHub 的 Network Graph 的区别。前者是数据，后者是可视化。但 GitHub 的 Network Graph 是从真实的 commit 数据生成的——它不会画一条”看起来合理”的线。Archify 对架构图做了同样的事。

Before / Delta / After：架构变更的可审计

Archify 还有一个杀手锏功能：对比两个验证过的快照。

你用 Archify 在 PR 合并前生成一张图，合并后再生成一张。Archify 会给你一份精确的差异报告：

– 新增了哪些节点 – 删除了哪些边 – 哪些角色变了 – 哪些路由被重定向

这不是”两张图看起来不一样”——这是”这次 PR 改了 3 个服务、新增了 2 条调用、删除了 1 条消息队列”。

在 code review 里，这种能力是革命性的。 你不再需要人工读 diff 猜”这次改动会影响哪些服务”——Archify 直接告诉你拓扑层面的变化。

为什么这个项目一天涨 4260 stars

Archify 火起来不是偶然。它踩中了三个趋势的交汇点：

1. Agent Skills 生态爆发：Cursor、Claude Code、Codex、OpenCode 都支持 skills，但大多数 skills 是”让 AI 写更好的代码”——Archify 是少数让 AI 产出非代码的结构化制品。 2. 架构可视化需求井喷：微服务、事件驱动、Serverless——系统越来越复杂，人脑已经画不动图了。但现有的 AI 画图方案都不可信。 3. “可验证性”成为新共识：从 LLM hallucination 到 AI 代码 bug，社区越来越意识到”看起来对”不够，必须”验证过”。

4260 stars/day 的背后，是开发者对”AI 画图不可信”这个痛点的长期积压。

一个更深的观察：AI 的输出正在从”文本”扩展到”结构化制品”

Archify 代表了一个更大的趋势：AI 的输出不再只是文字和代码，而是结构化的、可验证的、可 diff 的制品。

– 文章 → 可被引用、可被 fact-check – 代码 → 可被编译、可被测试 – 架构图 → 可被验证、可被 diff

每一种制品都需要自己的”验证层”。文章需要事实核查，代码需要单元测试，架构图需要拓扑验证。Archify 做的就是最后一件事。

这个项目的作者 tt-a1i 显然深谙编译器设计——typed JSON IR、确定性编译、前后端分离——这些全是编译器的经典概念。把编译器设计原则用到 AI 输出上，是一种很漂亮的跨界。

安装

npx skills add tt-a1i/archify -g

然后在 Cursor / Claude Code / Codex 里跟 agent 说：

> Use archify to map this repository’s runtime architecture.

它会读你的代码库，产出一份可交互的 HTML 架构图——每条线都查得到来源，每个节点都追得到上下游。

—

项目地址：github.com/tt-a1i/archify 文档：SKILL.md 在线演示：见项目页面的 Proof Lab

一句话总结：Archify 把”AI 画架构图”从”看起来像”升级到”验证过”——编译器的分层思想用在 AI 输出上，让每条线都说得清楚来源。