Archify：AI自动生成架构图的开源工具

在AI编程时代，让AI代理理解系统架构并不困难，但如何将冗长的文字描述转化为直观的可视化图表？开源工具Archify给出了答案——它能让AI代理自动生成、验证并交付交互式架构图，彻底改变技术文档的制作方式。

Archify是什么

Archify是一个采用MIT协议的开源架构图生成工具，专门为AI编程代理设计。它的核心能力在于：读取系统描述后，协助编码代理生成交互式HTML图表，并内置验证规则确保输出质量。

与传统绘图工具不同，Archify并非通用编辑器，而是专注于将AI的理解转化为标准化的视觉呈现。它支持主流AI编程工具，包括Codex、Claude Code、Cursor和OpenCode，通过简单安装即可为现有代理赋予图表生成能力。

目前Archify支持五种图表类型，每种都针对特定场景：

• 架构图：展示核心组件及相互关系，适合描绘系统整体结构
• 工作流图：呈现完整流程、决策节点及修复路径
• 时序图：按时间顺序追踪各参与者间的调用关系
• 数据流图：涵盖数据转换、存储及消费全流程
• 生命周期图：侧重状态流转，展示从启动到完成的各阶段

Archify底层依赖Mermaid或类似的声明式图表渲染引擎，通过JSON规范作为中间层，将AI输出的结构化描述转换为SVG矢量图形。这种「规范先行」的设计使得图表具有版本可控性——JSON文件可以像代码一样提交到Git仓库，方便追踪架构演进历史。与Lucidchart、draw.io等需要手动拖拽的传统工具相比，Archify的目标受众是希望在CI/CD流程或自动化脚本中嵌入文档生成步骤的开发团队。MIT协议意味着可以在商业项目中免费使用，并可自由修改和二次分发。

智能的生成与验证机制

Archify最巧妙之处在于其完整的生成-验证-修复闭环。整个流程分为三个关键阶段：

规范生成阶段

代理首先生成JSON规范文件，为组件命名并分配唯一标识符，定义组件关系与渲染配置。这份规范文件可随时检查、存入项目并用于后续维护。

JSON规范作为「设计意图的单一事实来源」是现代文档即代码（Docs-as-Code）理念的体现。在这一模式下，图表不再是孤立的静态截图，而是可被程序读取和修改的结构化数据。每个组件拥有唯一标识符（通常是字符串ID），使得后续修复阶段能够精确定位到具体节点，而非对整张图重新生成。这也意味着多人协作时，可以通过diff工具直观看出两个版本之间哪些组件被添加、移除或关系发生了变化，大幅降低架构评审的沟通成本。

渲染验证阶段

Archify读取规范后执行渲染，同时进行多达9项制品校验，包括：

• 有效的SVG结构
• 几何关系正确性
• 交叉路径处理
• 标签与节点间距
• 图例布局合理性

若检测到标签重叠、连线错误等问题，系统会返回精准的诊断反馈，明确指出问题区域和像素级偏差。

自动修复循环

这是最有价值的环节。当校验发现问题时，反馈会传回编码代理，由代理修改规范并再次尝试。在实际测试中，架构图因工具调用标签与协调器重叠，经过两次针对性修正后通过全部校验；工作流图因标签宽度超出节点（需要1002像素但只有92像素可用），代理自动将节点加宽至1032像素并调整布局。

整个过程中，你不仅能看到失败的候选方案，还有具体的解释和代码变更记录，使得审查流程一目了然。

实战表现与局限性

在演示中，三个独立任务展示了Archify的实际能力：

架构图任务：构建AI编码助手的架构，包含用户、协调器、模型、工具执行器、工作区等组件，清晰展示请求如何进入系统、模型如何提出行动、工具路径如何贯穿工作区。

时序图任务：模拟产品查询流程，涉及浏览器、目录API、Redis和Postgres。图表逐步展示了缓存未命中、数据库查询、结果写入缓存的完整调用序列，每一步都有明确的先后顺序。

工作流图任务：拆解Archify自身的创作过程，包含请求者、编码代理和Archify工具三个泳道，展示从请求JSON编写、验证到交付的全过程，以及修复分支的决策归属。

说个细节，制品验证与浏览器测试是两个独立步骤。初始生成的时序图虽通过了构建验证，但在四种桌面尺寸下均出现溢出（1440×900页面实际高度达到1200像素）。通过缩减消息间距并调整图表高度，最终适配了全部尺寸。

离线能力验证

生成的HTML查看器具有出色的可移植性。测试表明，在拦截HTTP请求后，图表仍能正常显示，搜索、主题切换、SVG导出等功能在离线状态下运行正常且无控制台报错。这对于需要在受限网络环境中使用的场景尤为重要。

生成的HTML查看器之所以能够离线运行，是因为所有依赖（包括渲染库、样式表和交互脚本）均在构建时被内联（inline）到单一HTML文件中，无需从CDN加载外部资源。这种打包策略与PWA（渐进式Web应用）的离线缓存思路类似，但实现更简单直接。对于金融、医疗、政府等对网络访问有严格管控的行业，或者需要在无网络的客户现场演示系统架构的场景，这一特性具有实际价值。SVG导出功能则进一步允许将图表嵌入Word文档、Confluence页面或PDF报告，而不依赖任何在线服务。

明确的局限性

Archify并非万能工具，它存在几个关键限制：

1. 无托管共享功能：工具本身不提供在线协作平台
2. 非通用编辑器：定位于解析和规范化，而非自由绘图
3. 无法反映实时状态：图表展示的是设计意图，非生产环境的实际流量
4. 需要人工审查：若代理凭空捏造了依赖关系，渲染再精美也无法保证事实正确性

因此，针对真实仓库必须让代理检查相关文件，并说明各项关联的代码依据；若是探索设计方案，应明确标注为草案。

「图表展示设计意图而非实际流量」这一限制揭示了静态架构文档的根本性挑战：系统会随时间演进，而文档往往滞后。这一问题在微服务和云原生架构中尤为突出。解决思路通常有两条：其一是引入服务网格（如Istio）的可观测性数据，自动生成「活文档」；其二是像Archify这样接受静态快照的局限性，通过降低文档更新成本（让AI代理一键重新生成）来减少文档与现实的偏差。Archify属于后者，其价值主张是「足够便宜的重新生成成本」，而非「自动同步的实时状态」。

成本与使用建议

Archify本身采用MIT开源协议，渲染工具无需订阅费用，但你的AI代理调用仍可能产生成本。运行多个子代理会增加API调用费用，因此建议：

优先使用精准指令：与其让多个代理梳理全局，不如先发布清晰的单一任务。一张图表胜过千言万语，只有在处理架构、时序等独立问题时，并行工作才真正有价值。

推荐的初次提示模板：

让Archify解释API缓存未命中问题，涉及浏览器、API、Redis和Postgres，
展示响应调用序列。要求：
1. 明确主题和业务逻辑
2. 利用验证配置档案确保质量
3. 留存原文件与溯源记录
4. 生成包含8-12个核心组件的高阶架构
5. 提供对应的代码依据

随后可以逐步优化：让代理理清关系、调整重叠标签、解释出错路径，让修改过程透明化，简化审查流程。

总结

Archify的价值在于将AI代理的抽象理解转化为可审查、可编辑、可分享的视觉资产。其结合了易读的输出、可编辑的JSON源码，以及出错时的精准反馈，形成了完整的质量保障机制。

尽管它无法替代人工审查，也不适合所有场景，但对于需要快速生成技术文档、演示系统设计或进行架构讨论的团队来说，Archify是一个值得尝试的效率工具。它让AI编程不仅停留在代码层面，更延伸到了文档和沟通领域。