archify 架构可视化探索：把代码库与业务逻辑自动转化为交互式架构图

接手一个陌生代码库时，最耗时的往往不是读代码本身，而是搞清楚“这些东西到底怎么连在一起”。模块之间的调用关系散落在 import 语句、配置文件和环境变量里，靠人脑拼接出一张架构图，既慢又容易漏掉关键路径。更麻烦的是，图画完之后代码还在变，文档很快变成历史遗迹。archify 试图解决的正是这个问题：让 AI 代理直接读代码或听描述，生成一张可交互、可追溯、可继续修改的架构图。

它到底是什么

archify 是一个面向 AI 编程代理的技能模块（Agent Skill），支持 Claude Code、Codex、Cursor 等主流代理环境。它的核心能力可以概括为一句话：把系统描述或代码仓库转换成带交互的 HTML 架构图。

和传统绘图工具不同，archify 不要求你手动拖拽节点。你只需要在代理对话里说“分析这个仓库，生成 8 到 12 个核心组件的高层架构图，包含主路径和外部依赖”，代理会读取代码，提取结构信息，然后 archify 负责把结构渲染成图。如果你还没有代码仓库，也可以直接用自然语言描述系统，比如“浏览器到 API，经过 Redis 缓存，回源到 PostgreSQL”，它同样能生成对应的图。

项目采用 MIT 协议开源，官方入口是 archify.si，GitHub 仓库在 tt-a1i/archify。当前版本为 v3.0.1，在 GitHub Trending 上曾引起不少关注。

核心机制：为什么它比“让 AI 画 Mermaid”靠谱

让大模型直接输出 Mermaid 或 PlantUML 代码，再用渲染器出图，这条路很多人试过，问题也很明显：同样的描述每次生成的图可能不一样，箭头交叉混乱，节点位置随机，改一个地方可能整张图重排。

archify 的做法多了一层中间表示。代理生成的不是最终的图形代码，而是一套类型化的 JSON IR（中间表示）。这套 schema 定义了节点、边、分组、路径、信任边界等结构，然后由 archify 确定性地编译成 HTML 和 SVG。同样的 JSON 输入，永远产出同样的图。这一点对工程文档来说很关键——架构图不应该有“随机特效”。

确定性渲染带来的另一个好处是可验证。archify 的 README 中展示了一个“Proof Lab”，收录了基于公开仓库生成的架构图及其 JSON 源和校验回执。这意味着图不是“看起来像”，而是有源码依据的。

在图表类型上，archify 支持流程、序列、数据流等多种图型，生成的 HTML 是自包含的单文件，支持深色/浅色主题切换，也可以导出为 PNG、JPEG、WebP 或 SVG。

安装与首次使用

archify 的安装通过 npx skills 完成，不需要全局安装复杂的依赖。以 Claude Code 为例：

npx skills add tt-a1i/archify -g

如果是 Cursor，可以使用非交互模式：

npx -y skills add tt-a1i/archify --skill archify --agent cursor --global --copy --yes

安装完成后，在代理对话中直接描述需求即可。分析现有仓库时，可以给出更具体的指令，比如“生成 10 个核心组件的高层架构图，标注主路径、外部依赖和信任边界”。archify 会保留 JSON 源文档，后续的修改——加一个缓存层、调整模块位置、高亮某条调用路径——都基于同一份源文档进行增量更新，而不是重新生成一张完全不同的图。

实际用起来怎么样

在技术评审场景中，archify 的价值比较直观。传统方式是有人提前画好 PPT，评审时大家对着静态图讨论，遇到“这个调用到底走不走消息队列”这类问题，只能靠记忆或现场翻代码。archify 生成的图可以点击节点追踪下游，可以点亮某条路径，讨论到哪个模块就展开哪个模块。如果评审中决定加一个缓存层，当场让代理修改 JSON 源，图会实时更新，评审结束后的文档就是最新版本。

新成员接手项目时，让代理读一遍仓库，生成一张带信任边界和外部依赖的架构图，比直接扔给对方一个 README 要有效得多。社区里已经有用户把 archify 生成的图带进飞书或钉钉做团队讨论，也有人从手绘的多智能体架构出发，通过对话逐步加入新的执行池。