Archify 实测：对话生成可交互架构图，Spring Boot 项目实践

画架构图这件事，大家应该都经历过。 draw.io 拖拖拽拽半天，代码一改图又得跟着改。 Mermaid 效率高一些，但颜值差点意思，想加个交互得翻半天文档。

最近我发现了一个叫 Archify 的 Agent Skill，确实有点东西。

简单说，Archify 干的事情就是：你在对话里告诉它系统的架构或者代码仓库，它直接给你生成一张可交互、颜值在线的专业技术地图。

不是那种糊弄事的示意图，是带校验、带主题切换、带路径追踪、能直接分享的独立 HTML 文件。

说实话，刚开始我是抱着怀疑态度的。 AI 画出来的图，很多时候看着漂亮，细节一塌糊涂，连线交叉、标签重叠太常见了。但 Archify 出来的效果，确实超出预期。

生成的 HTML 打开就能用，深色浅色一键切换，节点可以搜索聚焦，关系可以追踪高亮。

最牛的是所有的代码交互、数据流、下游关系分析都是动态可视化的，并且更新后支持版本跟踪，对比前后的变化。

安装与图表类型

安装一行命令：

npx skills add tt-a1i/archify -g

目前主流的 AI 智能体 都支持，MIT 协议，当前版本 v2.14.0。

装完之后跟 Agent 说一句：

"使用 archify 分析这个仓库的架构"

剩下的全自动。你不需要懂 JSON Schema，不需要知道渲染器怎么工作，描述你想要什么图，Agent 就会帮你搞定。

Archify 支持五种图表样例：

• Architecture：系统架构、组件关系、部署边界

  

• Workflow：CI/CD、审批流程、工具调用链

  

• Sequence：API 调用、缓存回源、鉴权时序

  

• Data Flow：数据管线、血缘、下游消费

  

• Lifecycle：状态机、重试、等待和终态

  

不知道选哪种，直接问它的 CLI：

node archify/bin/archify.mjs guide "展示带 Redis 缓存未命中的 API 请求用哪种图"

它会告诉你这种情况适合用 Sequence 图。这个指南对新手特别友好，不需要记住五种图表各自适合什么场景。

实战：分析一个 Spring Boot 项目

我拿 lingma-test 项目做了实测。这是一个 Spring Boot 项目，对接了阿里云灵码的 API，代码量不大，但分层结构很完整。有 Controller、Service、API Client、HTTP 工具类、全局异常处理、Swagger 配置，外加一个阿里云灵码 API 的外部依赖。

给 Agent 的指令就一句话："使用 archify 分析项目，画图"。

Agent 先读 pom.xml 看技术栈，再逐个读 Java 源文件分析调用关系，然后生成一份 architecture 类型的 JSON 规格文件。这份 JSON 定义了 10 个组件节点、2 个边界域、10 条连接关系、3 张总结卡片。整个过程我只做了一件事：描述我想要什么样的图。剩下的分析、布局、校验、渲染全是 Agent 自动完成的。

每个节点的类型决定了它在图上的视觉样式。连接关系上标注了 HTTP GET、@Autowired、doGetWithParams 这些语义信息，不是简单的箭头。

JSON 生成后跑 validate 校验：

然后 deliver 生成最终 HTML，约 640KB，包含完整的 SVG 图表和交互逻辑。

打开 HTML，从客户端到 Controller、Service、ApiClient、HttpClientUtil，再到外部的阿里云灵码 API，一条主链路从左到右非常清晰。 Swagger UI、GlobalExceptionHandler 这些横切关注点在上方用虚线连接。两个边界域把应用范围和 Token 认证范围圈了出来，一目了然。

中间有个小插曲。第一次 validate 报了 4 个标签重叠的错误，Agent 拿到诊断报告后只改了三条连接关系的 labelDy 偏移量，第二次就全部通过了。没有整图重写，精确改诊断指出的对象，这个修复过程让我印象挺深。

校验机制

Archify 和其他绘图工具最大的区别就在这个校验流水线。

Agent 生成的第一份产物是 Typed JSON（中间表示），不是 HTML。每种图表类型都有对应的 JSON Schema，validate 先做 Schema 校验确保结构合法，再做布局校验确保标签不重叠、连线不穿越无关节点、线段长度不低于最小阈值。

校验等级分 standard 和 showcase 两档。 showcase 要求更严格，9 项检查全部通过才算合格，包括单一 SVG 输出、正交箭头路由、标签净空距离、关系交叉数、容器边框连续性等。

校验失败的话，validate 返回结构化诊断：哪个对象出了问题、测量数据是什么、支持哪几种修复方式。 Agent 按诊断改完再校验，通过后 deliver 才渲染成 HTML 并原子替换输出文件。如果检查没通过，上一份验证过的文件不会被覆盖，你永远不会拿到一个半成品。

说白了，Agent 理解你要画什么，它知道哪个节点放哪里更合理，而不是交给一个通用算法去猜。校验失败也不会甩一堆报错让 Agent 自己猜，而是精确告诉它改哪里、怎么改。

这套流水线的好处是，每次交付的图都是经过验证的。不会出现标签压在一起、连线穿过节点这种视觉问题。

交互式 Viewer

生成的 HTML 不是一张死图，它是一个完整的交互式 Viewer。

按 / 搜索节点并聚焦，按 R 探查两个节点间的有向路径，按 L 对比语义角色（比如 backend 和 database 之间的流量），按 P 播放引导故事。如果你在 JSON 里定义了 views，Viewer 会按章节依次高亮对应的节点和关系，适合做技术方案演示。按 T 切换深浅主题，按 E 导出 PNG/SVG/WebM，还有 1200×630 的分享卡片。

分享卡片挺实用的。追踪了一条路径后，导出 Route Share Card 就是 1200×630 的 PNG，路径高亮，其余组件保留上下文。直接贴 README 或技术文档里，非常合适。

URL 可以带 #focus=controller 或 #route=client~lingma-api，打开就聚焦到对应位置，读者不用手动操作就能看到你想让他看的内容。

还有一个亮点功能：Architecture Delta。它能对比两份架构图的差异，生成 Before / Delta / After 三栏对比视图。新增了什么组件、删除了什么连接、哪些关系发生了变化，全部精确标注。 PR 评审的时候特别有用，合并代码之前先看看架构变化。

命令也很简单：

node archify/bin/archify.mjs compare architecture base.json head.json architecture-delta.html --json

对比过程是只读的，不会推断影响或者风险，只会精确展示作者写出的变更。这个设计很克制，也很可靠。当然直接交给 AI 也可以直接分析。

总结

用了 Archify 后，它解决了一个很具体的问题：不用花时间画架构图，也不用担心画出来的图不准确、不好看。对话里描述系统，拿到的就是一份经过校验的、可交互的技术地图。一个 HTML 文件就能分享，不用装任何软件。

我最喜欢的几个点：生成质量确实高，showcase 级别的校验不是盖的；交互式 Viewer 功能丰富，搜索、路径追踪、角色对比都有；Architecture Delta 在 PR 评审的时候太实用了。

Archify 不是通用绘图编辑器，也不是 Mermaid 的皮肤。它做的事情是把技术意图变成可以直接交流的成品。

GitHub 地址： https://github.com/tt-a1i/archify ，MIT 协议。 Proof Lab 页面收录了 11 个校验通过的示例场景，可以先看效果再决定要不要装。项目还有一个交互式的场景指南，帮你根据需求选择合适的图表类型。

对于经常需要画架构图、流程图、时序图的小伙伴来说，这个技能值得装一个。不用离开对话窗口就能拿到成品，这点真的很方便。