archify：让AI读代码库生成可交互架构图

接手不熟悉的代码库，最花时间的往往不是改代码，而是先搞清整体结构。开源项目 archify 提供了一种新的做法：把它作为 Agent Skill 装进 Cursor、Claude Code 等 AI 编程工具后，AI 会直接读取代码仓库，生成一张可交互的架构图，并输出为 HTML 文件。图中的节点还能跳回源码核对，安装只需一条命令。

项目简介

archify 在 GitHub 上已有 1.3 万多 Star。它不是一个独立软件，而是给 Cursor、Claude Code、Codex CLI、OpenCode 这类 AI 编程工具使用的技能包。装好以后，用户只需说一句话，AI 就会去读仓库里的代码，把系统的运行时架构整理成图，输出 HTML 文件。浏览器打开即可查看，分享给同事也无需对方安装任何额外工具。

正如其 README 所说：这些图是从真实仓库里读出来的，不是只靠提示词画出来的。

它能做什么

1. 直接读代码仓库，不需要描述

多数 AI 画图工具需要先用文字描述系统，再据此画图，这要求你事先把架构搞清楚，等于本末倒置。

archify 自己去读仓库：入口在哪、路由怎么分发、模块之间谁调谁，都从代码里翻出来并整理成图。用户只需说一句「梳理这个仓库的运行时架构」。

2. 节点可跳回源码

因为图直接来自代码，节点可以带 SRC 标记，点开即可跳转到对应的文件和行号。这些位置经过 Git 校验，固定在具体 commit 上，不会漂移。

这保证了图上的内容与代码真实存在的东西对得上，而不是 AI 根据目录结构猜出来的。给同事讲解某个模块逻辑时，点开标记即可，不用现场翻代码。

3. 五种图，从不同角度看系统

同一个仓库可以生成不同类型的图，按需选择：

• 架构图：组件、服务、数据库、云资源、安全边界等系统整体结构。
• 工作流：泳道式流程图，适合 CI/CD、审批流、异常分支等顺序性流程。
• 时序图：API 调用链、缓存回源、鉴权检查等，展示调用顺序与返回值。
• 数据流图：数据来源、处理过程、存储位置，以及敏感数据边界。
• 生命周期图：状态机、重试、等待、终态，如订单从创建到完结的全过程。

4. 可交互的图，不是死图片

输出的 HTML 自带查看器：按 / 搜索节点，点中组件查看上下游，按 R 探查两个节点间的完整路径。还可以播放引导故事，像幻灯片一样讲解系统。开会投屏时按 F 进入演示模式，图会自动适配屏幕。

重要的是，所有交互都基于图里真实存在的节点和连线，不会编造不存在的调用关系。

5. 出图质量稳定

以前让 AI 直接写 SVG 或 Mermaid，结果不稳定。archify 改为分工协作：模型负责产出结构化 JSON（节点、连线），布局和渲染交给专门程序，最后还有自动检查，不通过不会交付。

检查失败时会提示具体问题，如某个标签和连线冲突，并给出修改建议，不用从头再来。

6. 导出与分享

图有深色、浅色两套主题，一键切换。PNG 按 4 倍分辨率渲染，适合 PPT 或打印；SVG 同时嵌入两套样式，放到 GitHub README 里会自动跟随读者系统主题。此外还支持导出 WebM 动态图和 1200×630 分享卡片。

7. 架构调整可先对比再合并

做架构调整时，可以生成 Before / Delta / After 三个视图，把新增、删除、变更的组件和连线逐条列出，评审时比口头描述清楚很多。

上手方式

直接运行下面的命令安装：

npx skills add tt-a1i/archify -g

安装时会询问你使用哪个 AI 工具，照实选择即可。若只想临时体验，不长期安装，可用：

npx skills use tt-a1i/archify@archify --agent codex

装完后打开项目，在对话框里说一句：「使用 archify 梳理这个仓库的运行时架构。」第一版图出来后，也可以用大白话调整，比如「加一个 Redis 进去」「把鉴权模块挪到左边」。它只会改动你提到的部分，不会推翻整张图重画。

一些看法

archify 最值得肯定的地方，是让架构图与代码保持同步。凭文字描述画出的图，画完那一刻可能已经过时，因为你描述的是脑中的系统，不一定是代码中的真实系统。让 AI 读代码、节点可跳回源码，图就成了能核对的文档。

它也妥善处理了分工：理解需求、组织信息交给模型，布局、渲染、检查交给程序。这样出图质量的下限，比单纯让 AI 画 SVG 高了不少。

需要说明的是，它不是绘图编辑器，不能拖拽改图，也不做 Mermaid 转换，只负责把代码库变成能拿出去讲的图。如果你正接手新项目，或经常需要给别人讲系统结构，值得装一个试试。

开源地址

https://github.com/tt-a1i/archify