Archify × Codex 实战：让 AI 读懂代码，画出可验证的架构图

引言：为什么 AI 画的架构图总是“差点意思”？

用 Mermaid 画过复杂架构图的人都有体会：节点一多，箭头就开始乱飞，最后还是要手动调整。更麻烦的是，代码更新后，架构图很快就过期了，维护成本极高。

2026 年 8 月，一个名为 Archify 的开源项目冲上 GitHub Trending 榜首，狂揽 3.14 万 Star。它做的事情很简单：在对话里，把代码仓库或系统描述变成漂亮、可靠、可交互的系统地图。

更关键的是，Archify 的开发者“也无风雨也雾晴”并非名校出身，而是专升本考入重庆邮电大学软件工程专业。他在字节、猿辅导等大厂面试中屡次因学历被拒，最终用 Archify 证明了自己。这个项目不只是一款工具，更是一个关于“用作品说话”的故事。

本文将带你完成 Archify 与 Codex CLI 的集成，并通过一个真实的 Go 微服务项目，演示如何让 Codex 读懂代码，生成一张经过完整校验、可搜索、可交互的架构图。

一、Archify 的设计哲学：为什么它不只是“更好看的 Mermaid”

1.1 核心分工：Agent 理解，Archify 渲染

Archify 最聪明的设计在于职责分离。

传统的 AI 画图工具，让大模型直接生成 Mermaid 或 PlantUML 代码。模型既要做“理解代码”这件它擅长的事，又要做“精确布局”这件它并不擅长的事。结果就是：模型可以画得很快，但不一定画得对。

Archify 的做法完全不同。它把画图这件事交给了一个确定性程序，只让大模型干它真正擅长的事：读代码、抽信息。

整个过程分为三步：

代码或系统描述 → Agent 理解并生成 JSON IR → Archify 校验并渲染 HTML

Agent 生成的是一个带类型的 JSON 中间表示（IR） ，而不是最终图形。Archify 收到 JSON 后，会执行 Schema 校验、布局检查、节点冲突检测，只有全部通过才会渲染成最终的 HTML/SVG 成品。

1.2 五种图型，覆盖技术沟通核心场景

Archify 目前支持五类技术图：

1.3 可验证性：交付前先检查

这是 Archify 区别于其他工具的核心特性。在交付最终 HTML 之前，Archify 会执行一套完整的校验流程：

• Schema 校验：JSON 结构是否符合规范

• 布局检查：节点是否重叠、连线是否冲突

• 质量档案检查：showcase 模式下必须通过全部 9 项 artifact 检查，且 0 错误 0 警告

如果校验失败，Archify 会指出具体问题和可采用的修复方式，而不是直接交付一张“看起来漂亮、实际有错”的图。

二、环境准备与安装

2.1 前置条件

• Node.js ≥ 18（推荐 22+）

• Codex CLI 已安装并可用（codex –version 验证）

2.2 安装 Archify Skill

Archify 通过 skills CLI 安装，兼容 Codex、Claude Code、Cursor 等 70+ Agent：

# 全局安装（推荐）
npx skills add tt-a1i/archify -g

如果你只想临时体验，不实际安装，可以用 use 命令：

# 以 Codex 为例，临时运行
npx skills use tt-a1i/archify@archify –agent codex

安装完成后，重启 Codex，输入 $ 即可在技能列表中看到 archify。

2.3 验证安装

在 Codex 对话中执行：

codex
> $archify 描述一下你能做什么

如果 Codex 正确加载了 Archify Skill 并返回其能力说明，说明安装成功。

三、实战：用 Codex + Archify 分析一个 Go 微服务项目

3.1 场景设定

假设你接手了一个开源的 Go 微服务项目，代码库有 50+ 个 Go 文件，包含 API 网关、用户服务、订单服务和数据库层。你需要快速理解它的运行时架构，以便决定从哪里开始做优化。

传统做法是手动翻阅代码、画草图，耗时且容易遗漏。现在，我们让 Codex 来完成这件事。

3.2 第一步：让 Codex 分析代码仓库

在项目根目录下启动 Codex：

codex
> 分析这个代码仓库，然后用 archify 生成一张高层运行时架构图。
> 展示 8-12 个核心组件、一条主要请求路径、外部依赖和信任边界。

Codex 会首先执行发现阶段：读取 go.mod 了解依赖、扫描目录结构、识别入口文件（main.go）和关键模块。

为了节省 Token，Codex 可以采用两阶段发现策略：第一阶段只提取文件路径、依赖名称和目录结构；第二阶段针对核心文件提取导入关系和导出符号。

3.3 第二步：Codex 生成 JSON IR

发现阶段完成后，Codex 会按照 Archify 的 Schema 生成 JSON IR。一个典型的架构图 JSON 结构如下：

{
"schema_version": 2,
"type": "architecture",
"meta": {
"title": "Order Service Runtime Architecture",
"quality_profile": "showcase"
},
"nodes": [
{
"id": "api-gateway",
"label": "API Gateway",
"role": "primary",
"card": { "details": "gin + JWT auth" }
},
{
"id": "order-svc",
"label": "Order Service",
"role": "primary",
"card": { "details": "gRPC, 3 replicas" }
},
{
"id": "postgres",
"label": "PostgreSQL",
"role": "external",
"card": { "details": "Primary + read replica" }
}
],
"edges": [
{
"from": "api-gateway",
"to": "order-svc",
"label": "gRPC"
},
{
"from": "order-svc",
"to": "postgres",
"label": "SQL"
}
]
}

Codex 会遵循 Archify 的 SKILL.md 规则：从一个清晰的主路径开始，保持短侧分支，标签精简，最多 12 个主节点。

3.4 第三步：Archify 校验并渲染

Codex 自动调用 Archify 的校验命令：

node bin/archify.mjs validate architecture candidate.json –quality showcase –json

校验通过后，执行最终交付命令：

node bin/archify.mjs deliver architecture candidate.json order-arch.html –quality showcase –json

生成的 order-arch.html 是一个自包含的独立文件，可以直接在浏览器中打开。

3.5 最终产出：可交互的系统地图

打开生成的 HTML 文件，你会看到一张完全可交互的架构图：

• 搜索节点：输入 “order” 快速定位订单服务

• 追踪路径：点击任意节点，查看它的上下游调用链

• 切换主题：一键在深浅模式间切换

• 导出分享：支持 PNG、SVG、WebM 和 1200×630 分享卡片

如果对结果不满意，可以直接在对话中继续指挥 Codex：“把数据库移到左边”、“突出缓存失效后的回退路径”、“加入 Redis 节点”——Codex 会更新 JSON IR，Archify 重新校验并渲染。

四、Archify 的差异化能力

4.1 架构变更对比

这是 Archify 在工程实践中非常有价值的能力。在合并 PR 之前，你可以生成两份已校验的快照，让 Archify 对比为 Before / Delta / After 视图，精确区分新增、删除、语义变化、移动和重路由。

这意味着，架构图不再是一张“静态文档”，而是可以纳入代码评审流程的版本化资产。

4.2 版本校验的源码溯源

Archify 支持在图中点击节点，直接打开经过 revision 校验的源码。图中展示的拓扑有据可查，不是模型“编造”出来的。

4.3 不止于“好看”

Archify 的四套视觉预设（Signal Flow、Blueprint、Classic 等）和内置品牌徽标，让生成的图可以直接用于 README、Release Notes 或社交分享。但它真正的价值不在视觉，而在确定性校验：每一张交付的图都经过了完整的一致性检查，不会出现“箭头指错方向”或“节点重叠”这类低级错误。

五、最佳实践与注意事项

5.1 控制 Token 消耗

对于大型代码库，Codex 直接读取所有文件会消耗大量 Token。推荐在 AGENTS.md 中定义一个两阶段发现流程：先提取文件路径和依赖关系，再针对核心文件做深度分析。社区已经验证了这种策略的有效性。

5.2 明确图型选择

在触发 Archify 时，尽量明确你需要的图型。虽然 Archify 会从问题中推断类型，但显式指定可以避免误判：

# 明确指定架构图
> 用 archify 生成一张架构图，分析这个仓库的运行时拓扑

# 明确指定时序图
> 用 archify 生成一张时序图，展示登录请求的完整调用链

5.3 与 Grill Me 组合使用

Archify 解决的是“看清系统”的问题，Grill Me 解决的是“想清楚要做什么”的问题。两者可以形成互补：

Grill Me（需求澄清） → Archify（系统可视化） → Codex（代码实现）

先用 Grill Me 把需求问透，再用 Archify 把现有系统或目标架构可视化，最后让 Codex 执行代码变更。

六、总结

Archify 的走红并非偶然。它抓住了 AI 编程时代的一个核心矛盾：模型擅长理解，但不擅长精确渲染。通过将“理解”和“渲染”分离，Archify 让大模型专注于它真正擅长的事，同时用确定性程序保证了输出的可靠性和可验证性。

Codex + Archify 的工作流可以概括为：

描述意图 → Codex 读代码生成 JSON IR → Archify 校验 → 交付可交互 HTML

对于软件产品和项目开发而言，这套组合的价值在于：

如果你正在维护一个中等规模以上的代码库，不妨花 10 分钟安装 Archify，然后在 Codex 里试一次：

npx skills add tt-a1i/archify -g

然后对 Codex 说：

> 用 archify 分析这个仓库的运行时架构，生成一张架构图。

你可能会发现，理解自己（或同事）的代码，从来没有这么轻松过。