1. 项目缘起与核心定位第一次看到 archify 这个项目标题的时候我的直觉是这东西解决的是一个长期被忽视的痛点。做过后端开发或者系统设计的人都知道架构图这玩意儿画起来费时间维护起来更费时间。代码改了架构图没改过两个月再看那张图跟考古似的完全对不上。archify 的思路很直接——既然 AI 代理已经能写代码、能读代码、能理解项目结构了那为什么不让它顺手把架构图也画了而且不是画一张死图是画一张可交互的图。这个项目的核心定位是一个技能模块也就是说它不是独立运行的软件而是挂载在 AI 代理体系下的一个能力单元。你可以把它理解成给 AI 代理装了一双专门看架构的眼睛和一双专门画架构的手。它做的事情是读取你的项目代码或配置分析模块之间的依赖关系、调用链路、数据流向然后自动生成一张可交互的架构图。这张图不是静态图片而是可以在浏览器里缩放、拖拽、点击查看节点详情的 HTML 页面。适合谁来用我梳理了一下大概三类人最需要第一类是中小团队的技术负责人手里管着几个微服务每次汇报都要重新画架构图烦得不行第二类是刚接手遗留项目的开发者面对一坨代码不知道从哪看起需要一张全局视图来建立认知第三类是做技术文档或技术分享的人需要频繁更新架构图但不想每次都手动调整。如果你属于这三类中的任何一类archify 值得花时间研究一下。我实测下来的感受是它最大的价值不在于画得多好看而在于“自动”和“可交互”这两个词。自动意味着你不需要手动维护代码变了重新跑一遍就行可交互意味着看图的人可以自己探索不用你在旁边解释“这个框代表什么”。这两点结合起来架构图的维护成本从“每次都要重画”降到了“每次重新生成”。2. 核心机制拆解AI 代理如何理解并生成架构图2.1 技能模块的运作原理archify 作为一个技能模块它的运作方式跟传统的架构图工具完全不同。传统工具比如 Draw.io、PlantUML、Mermaid本质上是你告诉它画什么它就画什么它不理解你的代码。archify 的逻辑是反过来的它先去理解你的代码然后自己决定画什么。具体来说这个技能模块的工作流大致分三步。第一步是扫描与解析AI 代理会遍历你指定的项目目录识别出关键文件——比如微服务项目里的 pom.xml、build.gradle、package.json、Dockerfile、docker-compose.yml以及各个服务的主入口文件和配置文件。第二步是关系推断代理会根据文件内容推断出服务之间的调用关系、依赖关系、数据存储关系。比如它看到服务 A 的配置文件里引用了服务 B 的地址就会在图上画一条从 A 到 B 的连线。第三步是图结构生成与渲染代理把推断出的关系转换成图数据结构然后生成一个可交互的 HTML 页面。这里有个关键点archify 不是简单地做静态代码分析。它借助了 AI 代理的语义理解能力能处理一些模糊的情况。比如你的配置文件里写的是环境变量而不是硬编码的地址传统工具可能就识别不出来了但 AI 代理可以根据上下文推断出这个环境变量指向的是哪个服务。这是它比传统工具聪明的地方。2.2 为什么选择可交互 HTML 而不是静态图片这个问题我一开始也想过静态图片不是更简单吗但实际用下来可交互 HTML 的优势非常明显。静态图片的问题在于信息密度和可读性之间的矛盾图画得太细字小得看不清图画得太粗又丢失了关键信息。可交互 HTML 解决了这个矛盾——默认展示全局概览点击某个节点才展开详细信息。从技术实现角度看可交互架构图通常基于 SVG 或 Canvas 渲染配合 JavaScript 做交互逻辑。archify 生成的页面我拆开看过用的是 SVG D3.js 或者类似的图形库节点和连线都是 DOM 元素支持缩放、拖拽、点击事件。这意味着你可以把它直接嵌到内部文档系统里也可以单独部署成一个静态页面团队里任何人打开浏览器就能看。还有一个容易被忽略的好处可交互 HTML 是文本格式的可以纳入版本管理。每次代码变更后重新生成的架构图可以通过 git diff 看到具体哪些节点和连线发生了变化。这对于追踪架构演进非常有价值。静态图片做不到这一点二进制文件的 diff 没有意义。2.3 与主流架构图工具的对比我把 archify 和几种常见的方案做了个对比方便你判断它适不适合你的场景。对比维度archifyPlantUML/MermaidDraw.io手动 Visio生成方式AI 自动分析代码手动编写描述文件手动拖拽手动拖拽维护成本极低重新生成即可中等需同步更新描述高每次手动改极高交互能力支持缩放拖拽点击静态渲染有限交互无学习曲线低配置好就能用中等需学语法低但费时间低但费时间适合场景代码频繁变更的项目架构稳定的项目一次性汇报传统企业文档版本管理文本格式可 diff文本格式可 diffXML 可 diff二进制不可 diff从表里可以看出来archify 的核心优势场景是“代码频繁变更且需要持续维护架构图”的情况。如果你的项目架构半年不变一次那用 PlantUML 手写可能更可控。但如果你的项目每周都在加服务、改接口那 archify 的自动化能力就是刚需。3. 从零搭建实操过程与关键配置3.1 环境准备与前置条件在开始之前你需要确认几件事。首先你得有一个可用的 AI 代理环境。archify 是作为技能模块挂载的所以它依赖宿主代理的能力。目前主流的 AI 代理平台都支持自定义技能模块的加载具体方式各平台略有差异但核心逻辑都是把技能描述文件和执行脚本放到指定目录然后在对话中触发。其次你的项目代码需要有一定的结构化程度。什么意思呢如果你的项目是一个巨大的单体应用所有代码都在一个目录里那 archify 能分析出的架构信息会比较有限。但如果你的项目是微服务架构或者至少是按模块划分了清晰的目录结构那 archify 就能发挥出最大价值。我实测下来微服务项目、前后端分离项目、多模块 Maven/Gradle 项目效果最好。第三你需要准备一个输出目录。archify 生成的 HTML 文件需要有个地方存放建议单独建一个docs/architecture/目录方便后续管理和部署。注意在运行 archify 之前建议先确认你的项目依赖描述文件是完整的。比如 Maven 项目的 pom.xml 里是否声明了所有内部依赖docker-compose.yml 里是否列出了所有服务。这些文件是 archify 推断关系的主要依据如果它们本身就不完整生成的架构图也会缺胳膊少腿。3.2 技能模块的加载与触发加载 archify 技能模块的过程不同 AI 代理平台的操作方式不太一样但大体思路是一致的。你需要把技能的描述文件通常是一个 Markdown 或 YAML 格式的说明放到代理的技能目录下描述文件里要写清楚这个技能叫什么、做什么用、接受什么参数、输出什么结果。触发方式一般有两种。一种是在对话中直接说“帮我生成这个项目的架构图”代理识别到意图后会调用 archify 技能。另一种是显式调用比如输入/archify --path ./my-project --output ./docs/architecture/。我建议用显式调用因为参数可控不容易出错。这里有个实操心得第一次运行的时候建议先在一个小项目上测试确认整个流程跑得通。不要一上来就拿一个几十个服务的大项目去跑万一中间某个环节卡住了排查起来很麻烦。我一开始就是拿一个只有三个微服务的小项目试的跑通之后再逐步扩大范围。3.3 参数配置与输出定制archify 支持一些参数来定制输出结果虽然不同版本的参数名可能略有差异但核心配置项大致如下# 基本用法 archify --path ./project-root --output ./docs/architecture/ # 指定分析深度 archify --path ./project-root --depth 3 --output ./docs/architecture/ # 排除特定目录 archify --path ./project-root --exclude node_modules,dist,test --output ./docs/architecture/ # 指定输出格式 archify --path ./project-root --format html --output ./docs/architecture/--depth参数控制分析深度。深度为 1 时只分析顶层服务之间的关系深度为 2 时会展开到服务内部的模块深度为 3 时会进一步展开到关键类或函数级别。我一般用深度 2既能看清服务间关系又不会因为节点太多而眼花缭乱。--exclude参数很重要。默认情况下 archify 会扫描所有目录但像node_modules、dist、test这些目录里的内容对架构分析没有帮助反而会增加噪音。建议在配置里把这些目录排除掉。输出格式目前主要是 HTML但有些版本也支持导出为 JSON 或 Mermaid 格式。JSON 格式适合做二次开发比如你想把架构数据接入自己的监控系统。Mermaid 格式适合嵌入 Markdown 文档。3.4 生成结果的解读与验证archify 跑完之后你会得到一个 HTML 文件。用浏览器打开应该能看到一张可交互的架构图。但这里有个关键步骤不能省验证生成的图是否准确。AI 推断出来的关系不一定全对。我遇到过几种典型情况一是把测试代码里的依赖也画进去了导致图上多了一些不该有的连线二是某些通过消息队列异步通信的服务代理没有识别出来图上缺了连线三是环境变量指向的服务代理推断错了目标。验证的方法很简单拿生成的图和你的实际架构对照一遍。重点看几个地方——服务之间的调用方向对不对数据存储节点有没有遗漏外部依赖有没有标出来。发现错误后可以调整配置重新生成或者在生成的 HTML 上手动修正如果 archify 支持编辑功能的话。提示建议把验证这一步固化到流程里。每次重新生成架构图后花五分钟对照检查一下。特别是当项目有重大架构调整时AI 的推断可能会出错人工验证能避免把错误的架构图传播出去。4. 实战中的常见问题与排查技巧4.1 生成结果不准确怎么办这是最常见的问题也是我踩坑最多的地方。生成结果不准确通常有几个原因对应的排查思路也不一样。第一个原因是项目结构不清晰。如果你的项目目录层级混乱文件命名没有规律AI 代理很难准确推断出模块边界。解决办法是先整理项目结构至少做到按功能或按服务划分目录。这不是为了 archify是为了整个项目的可维护性。第二个原因是依赖声明不完整。比如你的服务 A 通过 HTTP 调用服务 B但配置文件里只写了 B 的地址没有说明这是服务间调用。AI 代理可能会把它当成一个普通的外部链接。解决办法是在配置文件里加上注释或元数据帮助代理理解。比如在 docker-compose.yml 里给服务加上labels说明。第三个原因是代理的推断逻辑有偏差。这种情况比较难排查因为你看不到代理的思考过程。我的经验是先检查输入数据项目文件是否完整如果输入没问题但输出还是不对那就可能是代理的推断逻辑需要调整。有些版本的 archify 支持自定义推断规则可以针对特定模式做配置。4.2 架构图节点过多导致不可读当项目规模较大时生成的架构图可能会包含几十甚至上百个节点这时候图就变得不可读了。解决这个问题有几个思路。第一个思路是分层展示。不要试图在一张图里展示所有细节而是分成多个层次。顶层图只展示服务之间的关系点击某个服务后再展开该服务内部的模块图。archify 的可交互特性天然支持这种分层展示关键是要配置好层级关系。第二个思路是过滤。通过--exclude参数排除掉不重要的节点或者通过--focus参数只展示与某个服务相关的子图。我一般会生成两张图一张全局概览图只展示核心服务一张详细图展示某个特定服务的内部结构。第三个思路是分组。把功能相关的服务归为一组在图上用不同的颜色或边框区分。这样即使节点很多读者也能快速定位到自己关心的部分。4.3 与现有文档系统的集成生成的架构图如果只是孤零零一个 HTML 文件价值有限。更好的做法是把它集成到现有的文档系统里。我试过几种集成方式各有优劣。最简单的方式是把 HTML 文件放到静态文件服务器上然后在文档里加个链接。这种方式零成本但架构图和文档是分离的更新不同步。进阶一点的方式是用 iframe 嵌入。在文档页面里用 iframe 引入架构图 HTML这样架构图更新后文档页面自动更新。但 iframe 在移动端的体验不太好而且有些文档平台不支持 iframe。最彻底的方式是把架构图数据接入文档生成流程。比如用 archify 生成 JSON 格式的架构数据然后用自定义脚本把数据渲染成文档平台支持的格式。这种方式最灵活但需要一定的开发工作量。4.4 常见问题速查表问题现象可能原因排查方法解决思路图上缺少某些服务依赖声明不完整检查配置文件是否列出了所有服务补全 docker-compose.yml 或 pom.xml连线方向错误调用关系推断错误对照实际代码检查调用方向调整配置或手动修正节点过多不可读分析深度过大检查 --depth 参数降低深度或使用过滤参数生成速度慢项目文件过多检查扫描范围用 --exclude 排除无关目录HTML 打开空白浏览器兼容性问题换浏览器试试检查控制台报错确认 JS 加载正常中文显示乱码编码问题检查 HTML 的 charset 声明确保输出文件为 UTF-8 编码5. 进阶玩法与扩展思路5.1 结合 CI/CD 实现架构图自动更新archify 最让我兴奋的一点是它可以和 CI/CD 流程结合。思路很简单在 CI 流水线里加一个步骤每次代码合并到主分支后自动运行 archify生成最新的架构图并部署到文档站点。这样架构图就永远是新的不需要任何人手动维护。具体实现方式取决于你用的 CI 工具。以常见的 GitHub Actions 为例你可以在 workflow 文件里加一个 job在代码检出后运行 archify 命令然后用 deploy 步骤把生成的 HTML 推到静态站点。关键是要把 archify 的运行环境配置好确保 CI 环境里有必要的依赖。这个玩法有一个前提你的项目结构要足够规范AI 代理能稳定地推断出架构关系。如果每次生成的图都差异很大那自动更新反而会造成混乱。建议先在本地稳定运行一段时间确认输出结果一致后再接入 CI。5.2 多项目架构图的统一管理如果你手里有多个项目每个项目都生成一张架构图管理起来会比较分散。一个扩展思路是做一个统一的架构图门户把所有项目的架构图聚合到一个页面上。实现方式可以是这样每个项目在 CI 里生成架构图 HTML 后推送到一个统一的目录目录结构按项目名组织。然后做一个索引页面列出所有项目的架构图链接。更进一步可以做一个搜索功能输入服务名就能找到它在哪个项目的架构图里。这个玩法适合技术负责人或架构师需要对自己管辖的所有项目有一个全局视图。我试过用简单的静态站点生成器来做这个门户效果还不错成本也低。5.3 架构变更追踪与告警架构图不仅能看当前状态还能用来追踪变更。思路是每次生成架构图时把图数据JSON 格式存档一份然后对比前后两次的数据找出新增、删除、修改的节点和连线。这个能力在微服务架构下特别有价值。比如某个服务突然多了一个对其他服务的依赖这可能是开发人员无意中引入的耦合通过架构变更追踪就能及时发现。再比如某个服务被意外删除了架构图上会少一个节点也能触发告警。实现这个功能需要一些开发工作写一个对比脚本解析两次生成的 JSON 数据输出差异报告。然后把差异报告接入告警系统比如发到团队群里或邮件通知。我目前还在摸索阶段但初步效果已经能看出价值了。5.4 与 AI 代理的其他技能联动archify 作为 AI 代理的一个技能模块理论上可以和其他技能联动。比如结合代码审查技能在审查代码时自动检查是否引入了新的架构依赖结合文档生成技能在生成 API 文档时自动嵌入相关的架构图片段。这种联动的价值在于把架构意识融入到日常开发流程中而不是等到专门画图的时候才想起来。开发人员在提交代码时就能看到自己的改动对架构的影响这比事后补图要有意义得多。不过联动的前提是各个技能之间的数据格式要统一。如果 archify 输出的 JSON 格式和其他技能期望的格式不一致就需要做一层转换。这是目前比较麻烦的地方希望后续版本能在这方面做改进。6. 个人实操体会与建议用了这段时间我最大的体会是archify 这类工具的价值不在于替代人工画图而在于把架构图的维护成本降到足够低低到你可以把它当成代码的一部分来管理。以前架构图是“文档”写完就过时现在架构图是“构建产物”每次代码变更都会重新生成。如果你打算尝试 archify我的建议是从小项目开始先跑通流程再逐步扩大范围。不要一上来就追求完美的架构图先接受一个“大致准确”的版本然后在实际使用中逐步调整配置。架构图这东西有用比好看重要得多。另外不要完全依赖 AI 的推断结果。AI 代理再聪明也不如你自己了解你的项目。把 archify 当成一个起点它帮你画出 80% 的框架剩下的 20% 靠人工修正。这个分工方式目前来看是最务实的。