1. 项目概述这个模块到底帮你干了件什么事前几天我在 GitHub 上翻项目一眼看到archify这个名字第一反应是“又来一个画架构图的工具”。但点进去仔细看完 README 之后我发现它跟普通的架构图生成器有个本质区别它不是给人用的而是给 AI 代理AI Agent用的一套技能模块。它能让你手底下的 AI 代理在分析代码、规划重构、回答问题的时候自动生成一张可交互的架构图并且把这张图作为上下文的一部分返还给代理本身。说白了过去我们让 AI 看一个项目要么给它贴一堆代码文件要么让它逐个目录去读它经常顾此失彼。archify的思路是先让工具把代码库的模块依赖、目录层级、关键接口梳理成结构化数据再用 Web 端可交互式图表呈现出来。这张图既能给人看也能作为结构化信息喂回给 AI让代理对项目全貌有更清楚的“空间感”。这个项目最吸引我的点在于它的定位非常克制。它没有做成一整套重量级的架构分析平台而是做成一个可以插到现有 AI 工作流里的技能包。不管你是用 Claude、GPT 这类云端模型还是本地部署的编码助手只要把archify的命令行工具和对应技能描述配置好代理就能在你需要的时候主动调用它生成架构图。对做代码审查、新人上手、技术债梳理、微服务治理的人来说这东西能省掉大量“人工读代码、画脑图”的时间。这篇文章我打算从原理、安装、实操到踩坑一条线讲完尽量让你照着就能把模块跑起来。2. 核心设计思路为什么 AI 代理偏偏需要“一张图”2.1 AI 代理看图不是“看图”是看结构化数据很多人会问AI 不是能读代码吗为什么还需要生成架构图这个问题我自己以前也想不通。后来在实际使用中我发现大模型对代码的阅读理解是“局部精准、全局稀烂”的。你给它一个函数它能讲得头头是道你给它一整个微服务仓库它很快会迷失在文件海的细节里给出的建议前后矛盾。archify解决这个问题的方式很直接它把代码库从文件级别抽象成模块、服务、依赖关系、调用方向这四种基本元素生成一份结构化描述。这份描述再渲染成可交互的 HTML 图表。对 AI 代理来说这张图本质上是一份带有坐标和连接关系的 JSON 数据它不是“图片”这么简单而是一份可查询、可引用、可裁剪的上下文。代理在回答“这个模块影响哪些服务”之前可以通过 archify 的查询接口拿到精确的依赖清单而不是靠猜。2.2 可交互不只是炫技是给代理留了“后门”常见架构图工具生成的是一张静态图看完了就完了。但archify生成的图支持缩放、拖拽、点击节点高亮关联关系还可以在节点上展开详细信息比如该模块对应的关键文件列表、对外接口数量、被哪些模块反向依赖。这套交互能力我是越用越觉得是关键设计。因为对 AI 代理来说“看图”不是终点它还需要基于图去定位具体代码文件。可交互图让代理能沿着某个节点做深度下钻拿到具体文件路径之后再决定下一步行动。比如代理发现orders服务被payment和notify同时调用它就可以直接展开这两个下游节点的文件清单结合图里的关联关系去做影响面分析。这就是静态图给不了的能力。2.3 技能模块这种形态比独立平台聪明在哪archify没有做成一个独立的 Web 服务而是以“技能模块”的形式存在这是我非常认可的一个决定。现在 AI 代理生态最大的痛点不是模型能力而是工具链太碎。你用 ChatGPT 写代码用另一套工具做架构分析还指望它们自动配合这基本不现实。archify做的事情是把自己伪装成一个“万能姿势”它既可以作为独立 CLI 用也可以接入支持 MCPModel Context Protocol的客户端还能通过提示词模板让代理自己学会调用它。我自己的体会是技能模块这种形态特别适合团队内部集成。你不必让每个人都改变使用习惯只要把 archify 的配置加到团队的 AI 助手里该生成图的时候它自然会生成不该生成的时候它也不会打扰你。这种“低侵入”的属性对一个工具能否在团队里落地影响很大。3. 安装部署与配置文件解析3.1 环境准备其实没什么特别要求安装archify之前我原本担心它依赖一套很重的运行环境。实测以后发现比想象中轻量得多。它核心的代码解析能力基于 tree-sitter 实现所以不需要像传统静态分析工具那样装编译器和完整 SDK。也就是说你不需要本地装 Java 环境才能分析 Java 项目也不需要装 Node.js 才能分析前端工程。我的建议是准备一个独立的 Python 虚拟环境来安装。如果你们的网络环境对 GitHub 访问不稳定可以通过国内代码托管平台的镜像仓库或者拉取压缩包再本地安装这个看个人习惯就好。官方提供的安装方式就一句pip install archify-skill装完以后优先跑一下版本验证确认命令行工具已经被正确加入 PATHarchify --version如果这条命令报“command not found”多半是虚拟环境的 bin 目录没进 PATH手动把虚拟环境的路径补上就行不必删了重装。3.2 最小配置三分钟跑出第一张架构图archify的设计思路是“开箱即用”默认情况下它会在当前目录里自动识别主流代码结构。我第一次测试就在一个 Spring Boot 项目根目录下直接执行archify scan --format html -o docs/architecture.html大概十几秒后docs/architecture.html就被生成出来了。用浏览器打开能看到左侧是目录树中部是模块依赖图右侧是节点详情面板。那一刻我确实有点意外因为整个过程没有写任何配置文件。它的默认策略是把所有源码目录按包名或目录层级自动拆分成模块抓取源码里的 import、require、include 这类语句来建立依赖关系。但默认配置只能覆盖比较标准的项目结构。如果你面对的是一个代码仓库里同时住着多个语言、或者一个巨型单体仓库那就需要好好研究配置文件了。3.3 核心配置项别被默认策略带偏archify的配置文件是archify.config.yml我强烈建议所有正式项目都显式配置它而不是依赖默认策略。下面这份配置是我在真实业务项目里调试过很多轮之后的简化版本scope: root: . include: - src/** exclude: - **/test/** - **/generated/** granularity: module: package dependency_depth: 3 render: theme: light interactive: true show_unreferenced: false layout: hierarchical export: formats: - html - json我一条条说下重点。scope.include和scope.exclude是必须优先确认的因为如果不排除测试目录和构建产物目录架构图里会出现大量垃圾节点代理也会被误导。granularity.module这个字段决定模块划分粒度可选值是package、directory、file。Java 项目用package会在语义上更接近代码作者的意图Python 项目我一般偏好用directory。granularity.dependency_depth控制依赖关系追踪到第几层。默认值是 3我测试过一个老项目如果设得太深图里的连线会多到没法看设成 2 到 3 之间的某个值信息量刚刚好。render.show_unreferenced是个容易忽略但很坑的选项。默认情况下它只展示被其他模块引用到的节点。如果关了它所有孤岛模块都会堆进图里。我建议一开始保持false等你想看全量模块清单时再临时打开也不迟。3.4 与 AI 工作流的三种接入方式archify之所以叫“技能模块”就是因为它给不同的 AI 客户端准备了不止一种接入方式。我试过的有三种这里按推荐度排序。第一种是 MCP 方式。如果你用的是支持 MCP 协议的客户端比如 Claude Desktop 或者一些开源的 Agent 框架可以直接把 archify 注册成一个 MCP 工具这样代理就能动态调用它的扫描和查询能力。在 MCP 配置文件里加一小段就行{ mcpServers: { archify: { command: archify, args: [mcp] } } }第二种是提示词注入方式更适合那些不支持 MCP 的通用聊天型工具。你只需要把下面这段能力描述放到系统提示词里你有一个可用的架构分析工具 archify可以通过命令行扫描项目并生成架构图。 当用户询问模块关系、影响面分析或架构梳理时请主动尝试运行 archify 并参考其输出。这种方式虽然粗暴但对代理能力的扩展非常有效。第三种是纯 CLI 方式适合你自己在终端里手动生成图表或者让 CI 脚本定时生成架构快照。4. 实战案例三个项目三种画法4.1 Java 微服务项目粒度用 package效果最稳我最早是在一个 Spring Boot 微服务仓库上跑的archify那个仓库大概有三四十个 Maven 模块。一开始我直接用默认参数生成的图很乱因为每个模块下面都展开了一堆第二层的内部子包导致同一个服务被拆成了好几个孤岛节点。后来我把granularity.module调整为package并且用render.layout: hierarchical效果立刻不一样了。最上层的服务节点按业务域排布中层的公共依赖包在下方集中展示代理在回答“订单服务依赖了哪些公共组件”时可以直接引用图里聚合好的信息准确率比纯靠读代码高很多。这次配置我还有个意外收获图里清晰地展示出某个服务反向依赖了一个应该属于基础设施层的模块。这种依赖方向倒置的问题原先埋在代码里很难被一眼发现被架构图展示出来以后团队很快就决定推动重构。4.2 前端 React 项目依赖方向比 Node 数重要第二个案例是一个前端中后台项目代码量两万多行主要是 React 和 TypeScript。对这种项目archify跑出来的节点数量要比后端项目多不少因为前端组件之间互相引用的关系非常复杂。我的做法是先用--max-nodes 200这类参数限制展示数量然后依赖交互式图里的过滤功能按组件目录分批次查看。前端项目里最值得看的是“循环依赖”的展示archify 会把 A 引用 B、B 又反向引用 A 这种关系用特殊颜色标出来。我实测发现它识别循环依赖比很多专用 lint 工具还直观因为它把循环路径画成了一条可见的环。对 AI 代理来说前端项目的架构图还有一个妙用当代理准备修改某个组件时它先用 archify 查询该组件的被引用列表避免改了一个组件结果导致五个页面崩掉。这种“改动前先看图”的习惯我后来也推荐给了团队里所有使用 AI 编码助手的同事。4.3 Python 数据工程仓库目录级粒度更适合流水线代码第三个案例更典型是一个 Python 数据清洗和特征工程仓库。这类仓库没有传统意义上的“模块”业务代码更多是按照cleaning/、features/、models/、utils/目录来组织。如果按照package粒度跑archify 会把一堆没有__init__.py的目录当成普通文件处理模块边界会很乱。这时候我建议granularity.module用directory同时把show_unreferenced设为true确保每个目录节点都出现。数据工程类项目里“哪些脚本没有被主流程引用”本身就是很关键的信息打开这个选项以后代理一眼就能看出哪些旧脚本其实已经是死代码后续清理任务就有着落了。下面我整理了三个场景的配置对照方便你按需参考项目类型模块粒度依赖深度布局方式必开选项Java/Go 后端服务package2-3hierarchical排除测试目录前端 React/Vuedirectory3force-directed循环依赖高亮Python 数据工程directory2layeredshow_unreferenced4.4 输出结果怎么和团队协作结合我们团队现在的做法是在 CI 流程里加了一个定时任务每天晚上自动跑一次archify scan把结果输出成 HTML 和 JSON 两份文件然后上传到内部文档站。日积月累之后你甚至可以对比前后两天的架构图变化谁偷偷加了一个新模块、谁的依赖又重了一层一目了然。JSON 格式的输出对 AI 代理特别友好。代理可以直接读取 JSON 文件不需要重新扫描代码库就能基于最新的架构快照做分析。这样一来即便仓库很大代理的响应速度也会很快。我通常会在每周的代码评审会议之前跑一次生成把架构图链接贴在评审文档里大家讨论问题时可以直接指图说话。5. 常见问题与排查技巧实录5.1 我踩过的四个典型坑第一个坑是安装后运行命令报缺少动态库。这个问题多发在 Python 3.11 以上的环境tree-sitter 的某些语言包需要编译原生扩展如果系统的编译器版本不对安装会失败。我的解决办法是安装预编译依赖版本或者退回 Python 3.9 的虚拟环境。第二个坑是生成出来的图空白一片。排查下来发现是scope.include写错路径了src/**这种写法要求启用了 YAML 的通配符解析如果项目结构里源码目录不在src下面就是空的。用root: .加include: [**/*.java]这种相对路径组合可以避免路径问题。第三个坑是节点太多导致浏览器卡死。有一次我扫描一个大型单体仓库生成的 HTML 有十几兆浏览器打开以后几乎无法交互。后面加了max_nodes和依赖深度限制图表体积缩减到两兆以内流畅度才恢复正常。第四个坑是代理调用时拿不到图里的数据。因为交互图默认把数据打包进 HTML 里不方便程序解析。后来我发现导出时应该把格式指定为htmljson代理读取同一个目录下的 JSON 文件就能拿到结构化数据这个坑算是我觉得最影响实际使用体验的一个。5.2 排查思路速查表现象可能原因处理办法图里缺少某些模块include 路径没覆盖检查 scope.include 通配符图里出现大量测试类没排除 test 目录在 exclude 里加**/test/**模块间连线特别多依赖深度过大调小 dependency_depth代理读不到图数据只导出了 HTML重新用 htmljson 导出运行报语言解析错误tree-sitter 语言包缺失更新 archify 到最新版本生成速度极慢旧项目文件过多用 exclude 排除构建产物遇到问题我建议按“配置优先、代码其次”的顺序排查。archify百分之七八十的异常都出在扫描路径配置和依赖深度的平衡上真正需要调解析逻辑的场景极少。5.3 性能优化仓库太大怎么破对于特别巨大的仓库我尝试过两个比较有效的性能优化。第一个是“先缩后扫”先通过排除规则把构建目录、第三方目录、静态资源目录都剔除掉让扫描范围尽可能小。第二个是“分段生成”一个大型仓库拆成几个子模块分别扫描分别导出 JSON 之后再用官方提供的小工具合并成一张总图。这里需要注意合并后的总图连接关系可能会损失一部分跨模块边的完整性。折中的方案是在父目录只展示模块级节点跨模块关系保留在各自的子图里不强行合并。与其让代理拿到一张几百兆的超级大图不如给它几张清晰的模块级图信息密度反而更高。6. 扩展玩法架构图还能怎么玩出花6.1 把架构图变成 AI 的长期记忆我现在做的一个比较有意思的尝试是把archify生成的 JSON 架构快照和项目文档一起提交到代码仓库里文件名加上日期比如architecture-20250115.json。这样 AI 代理在处理问题的时候可以直接从固定路径加载最新的架构快照而不是每次重新扫描。这个做法还有个额外好处它给代理提供了一份“不随代码而变的稳定视图”。因为有些项目在频繁改动代理现场扫描到的结果可能处于中间状态反而是上次提交的架构快照更能反映真正的设计意图。所以我的习惯是让 CI 每天更新这份快照代理优先参考快照只有发现文件缺失时才触发新的扫描。6.2 结合代码审查、变更影响分析做自动化团队里现在流传的一句口头禅是“先看图再改码”。我们在代码评审工具里接入了一个小脚本当 MR 涉及文件变更时自动找出这些文件落在架构图的哪些模块节点上然后列出所有受影响的下游模块把结果贴到 MR 描述里。这套流程跑起来以后新人提交代码时也能一眼看到自己的改动会影响什么不用像以前那样全靠老员工提醒。如果你团队的 AI 助手足够灵甚至可以让它基于架构图生成一段“变更影响说明”描述这次改动会不会引入依赖环、会不会造成重复依赖等潜在风险。6.3 一点个人经验不要为了画图而画图最后分享一个我自己的使用习惯。刚开始用archify的时候我喜欢到处生成架构图一个仓库能跑出好几种不同配置的图看着是挺热闹实际上没有太大指导意义。后来我慢慢收敛成一种固定规则每个月只生成两份图一份是模块级全景图一份是核心变更链路图其余细节全靠交互点击临时查看。这样带来的好处是团队讨论架构时不会因为图的形态太多而浪费精力AI 代理获得的上下文也比较稳定。另外一个建议是架构图生成以后一定花几分钟对照实际代码抽查几个关键依赖关系毕竟工具自动解析不可能保证 100% 准确关键决策还是得靠人最终把控。这个工具和很多开发辅助类能力一样用好了是效率放大器用不好也只会给你多增加一堆没人看的图表。