Archify：用对话生成专业级技术图的 AI Agent Skill

想象一个场景：你刚接手一个陌生的微服务项目，想要快速了解它的运行时架构。以往的做法是翻代码、画草图、反复修改，一上午就过去了。而 Archify 的做法是：你在 Cursor 或 Claude Code 里输入一句「用 archify 梳理这个仓库的架构」，几秒钟后，一个可交互、可缩放、可导出的专业架构图就出现在你面前——不是截图，是真正可操作的 HTML 文件。

这就是 Archify 解决的核心问题：把 AI Agent 的语言理解能力，转化为工程师可以直接交付的技术图。

背景：技术图为什么一直是痛点

技术图（架构图、流程图、时序图等）长期处于「知道重要但懒得画」的状态。市面上的方案要么太重（Draw.io 需要手动排版），要么太轻（Mermaid 语法写出来的图难以交付），要么太贵（专业图表 SaaS 平台）。更关键的是，在 AI 编码时代，Agent 的上下文窗口里有大量结构化信息——但 Agent 却没有顺手生成可视化产物的能力。

Archify 的作者 tt-a1i 敏锐地捕捉到了这个缺口。Archify 脱胎于 Cocoon-AI/architecture-diagram-generator（MIT, v1.0），从 v1 起步至今已迭代到 v2.12，在一年内积累了超过 7200 个 GitHub Stars，是当前 AI Coding Agent 生态中增长最快的技能工具之一。

核心功能：五种图，覆盖技术表达全场景

Archify 不是单一功能的绘图工具，它是一个多图种技术可视化引擎，支持以下五种核心图类型：

每种图类型都基于 Typed JSON IR（中间表示）作为渲染输入，而非直接渲染用户原始文本。这意味着 Archify 会对输入做校验（deterministic validation），保证生成的图与输入语义一致——不是凭空想象的图，是有据可查的技术地图。

关键特性：不只是画图，是生产可交付物

Archify 的产品哲学体现在一系列精心设计的细节中：

确定性校验（Deterministic Validation）：Archify 在生成图之前，会验证输入的 JSON IR 是否符合 schema，确保图的每个节点和边都有据可查。如果校验失败，会给出精确的错误信息，指导用户修正输入，而不是生成一张可能与代码不符的图。

多图对比（Delta / Before-After）：这是 Archify v2 的杀手级功能。你可以对两张架构快照（base.json vs head.json）进行对比，生成 Before / Delta / After 三联视图，精确展示新增、删除、语义变化和路径重路由。对于 Code Review 和架构演进讨论，这个功能的价值难以替代。

交互式探索：生成的 HTML 不是静态图片，而是内置了丰富的交互能力：Semantic Lens（按角色过滤关系）、Route Probe（追踪上下游可达路径）、Semantic Radar（鸟瞰图）、Named Chapter Rail（按叙事章节导航）、Story Beat Navigator（带播放器的故事模式）。用户可以按需钻取细节，也可以直接导出为 PNG、SVG、WebM 或 1200×630 分享卡片。

Repository Evidence 追踪：当图需要反映真实代码时，Archify 可以直接分析指定仓库的源码（通过 repo-root 参数），从真实代码中提取模块关系，而不是凭 prompt 凭空编造。这解决了 AI 绘图工具「脱离实际代码」的核心诟病。

深浅双主题 + 四套视觉预设：内置 Signal Flow（信号流风格）、Blueprint（蓝图风格）、Classic（经典风格）、Dark Mode/Light Mode，兼顾展示与阅读需求。

技术架构：模块化 JSON-IR 渲染引擎

从代码结构来看，Archify 的核心是一个基于 Node.js 的 JSON-IR 渲染引擎：

• bin/archify.mjs：CLI 入口，处理 render / compare / deliver / preview / validate 五大命令
• renderers/：各图类型的渲染器（architecture、workflow、sequence、dataflow、lifecycle）
• schemas/：JSON IR 的校验 schema，基于 AJV（JSON Schema validator）
• recipes/：预置图配方（如何从自然语言生成 JSON IR）
• scripts/：构建脚本（gallery 展示页、guide 指南页、start 快速开始页）
• test/：golden test + smoke test 双重测试保障
• .impeccable/design.json：产品设计规范（颜色、字体、排版）

整体采用 JSON IR + Renderer 分离的设计：输入层（自然语言 / Mermaid / JSON）→ IR 层（统一 JSON 中间表示）→ Renderer 层（各图类型专用渲染器）→ Output（HTML/SVG/PNG/WebM）。这种架构保证了图类型的可扩展性，也便于做统一校验。

主要依赖为 ajv（^8.17.1）用于 JSON Schema 校验，零外部 UI 依赖保证了输出的独立性和轻量化（HTML 文件体积约 600KB 左右）。

图1：Archify 主视觉——深色主题下的架构图作品

图2：三个真实生成的成品（Signal Flow · Blueprint · Classic），均经过校验验证

部署体验：零门槛，但需要 AI Agent 环境

Archify 本身是纯 CLI 工具，没有 Web UI，也不需要 Docker 或云服务。安装方式极其简单：

npx skills add tt-a1i/archify -g

这条命令将 Archify 注册为 Agent Skill，集成到 Cursor Agent、Claude Code、Codex CLI 或 OpenCode 中。安装完成后，在 Agent 对话里直接说「用 archify 梳理项目架构」即可。

关键限制：Archify 需要运行在 AI Agent 环境中（Cursor Agent、Claude Code 等），不能脱离 Agent 独立使用。这既是它的使用门槛，也是它存在的意义——它是 Agent 的技能包，而非独立应用。

硬件需求极低：Node.js >= 18 即可，512MB RAM、50MB 磁盘即可运行。无需 GPU。

争议与局限

Archify 也存在一些值得注意的局限：

1. 输出质量依赖输入质量：Archify 的 JSON IR 校验保证了图与 IR 一致，但不保证 IR 与真实代码一致。如果用户用自然语言描述了错误的架构，Archify 会忠实地把这个错误画出来。Repository Evidence 追踪功能可以缓解这个问题，但需要用户主动指定 --repo-root。

2. 复杂的自然语言输入可能生成不理想的图：虽然 Archify 支持自然语言输入，但对于边界情况（如循环依赖、非常规架构模式），JSON IR 的表达力可能不足以完美还原用户的意图。此时需要用户手动微调 JSON IR。

3. 非 Agent 用户使用门槛较高：如果用户不使用 AI Agent，而是希望直接通过 CLI 调用 Archify，需要了解 JSON IR schema 规范，学习成本不低。对于只想「画个图」的普通用户，工具并不友好。

行业意义：从「文档滞后」到「实时同步」

Archify 的出现代表了一个趋势：AI 时代的技术文档应该是由 AI 实时生成的。传统的架构文档往往是项目后期的补充物，与实际代码渐行渐远。Archify 让架构图成为开发过程中的一等公民——每次代码提交后，Agent 可以自动更新架构图，确保文档始终与代码同步。

从增长数据看，Archify 在一年内获得 7200+ Stars，且在 GitHub Trending 上持续上榜，反映了 AI Coding Agent 生态的快速扩张。随着 Claude Code、Cursor Agent、Codex CLI 等工具的普及，Agent Skill 正在成为 AI 编程工具链的关键基础设施。Archify 率先占据了「技术可视化」这个垂直赛道，未来有望成为 AI 编程的标配技能之一。