平时画架构图最烦什么不是不知道怎么写代码而是画图这件事本身就是个“高成本低产出”的活儿。需求一变服务一拆图就废了图一废后面接手的人又得重新读代码猜结构。GitHub 上最近被开发者反复转发的一个项目archify走的就是另一个路子它不让你动手画而是直接把“生成可交互架构图”做成一个 AI 代理能够调用的技能模块——你只需要告诉你的 AI 助手“帮我看一下这个项目的架构”剩下的扫描代码、识别依赖、渲染交互式图谱全自动完成。我第一时间拉下来试了试前后折腾了两天期间踩了不少文档里没写的坑。这篇就把它的工作原理、接入方式、实操过程和问题排查从头到尾捋清楚如果你也在搞 AI 代理、代码分析或者架构可视化这篇应该能让你少走很多弯路。1. 项目概述archify 到底解决了一个什么问题1.1 传统架构图维护的痛点先说一个所有维护过老项目的人都经历过的场景你接手一套代码几百个文件几十个微服务注释约等于没有。领导说“你出个架构图”你打开 Visio 或者 Draw.io对着代码文件一个一个找依赖关系。画完了交付两周后服务拆分图又过期了。这种文档漂移问题在软件工程里一直是老大难——图一旦跟代码脱节就彻底失去参考价值。archify 的想法很简单架构图不该由人手动去维护因为代码本身就是最权威的架构事实来源。与其人去读代码然后画图不如让程序去扫描代码、解析依赖、聚类模块边界然后自动生成一张图。而且它还不止生成静态图而是输出一张可交互的网页版架构图——你可以点开某个服务节点看它依赖了谁折叠不想看的分支甚至直接定位到对应的源码文件。1.2 为什么做成“AI 代理的技能模块”这是 archify 和普通的代码可视化工具最不一样的地方。它不是给你一个按钮让你上传代码而是暴露了一个可以被大语言模型直接调用的工具接口。所谓技能模块就是给 AI 代理增加一种“能做特定动作”的能力——agent 在对话过程中如果发现需要理解代码结构它可以自动调用 archify把扫描请求发出去然后拿结果继续推理。这个设计思路非常务实。现阶段的 AI 助手虽然能读懂代码片段但面对整个仓库时受限于上下文窗口它对全局依赖关系的感知是零散的。如果给代理配一个专门的架构扫描工具它就能在分析大型项目时先获取一张全局结构图再带着这张图去做代码解释、重构建议、影响面分析。等于给了大模型一副“全景眼镜”不再局限于看哪算哪。1.3 archify 的定位与适用人群如果你正在做下面这几类事情archify 大概率对你有用给老项目补架构文档需要快速生成一张可以交付的架构图搭建个人 AI 编程助手希望它能理解你本地项目的结构做微服务治理或者系统设计评审需要一张能交互、能下钻的依赖关系图或者单纯就是觉得手动画图太浪费时间。项目本身以 Python 为主依赖管理用的是标准 pyproject 方式本地环境下通过 pip 就能安装。生成的交互式 HTML 页面完全离线运行不依赖任何第三方 CDN 或在线服务这一点对很多公司内网环境来说非常友好。2. 核心设计思路AI 代理如何完成自动扫描与图谱生成2.1 从代码目录到架构节点的解析流程我把 archify 的执行链路拆成四步来看代码扫描、依赖分析、模块聚类、渲染输出。代码扫描层负责遍历目标仓库的文件识别支持的语言类型目前对 Python、TypeScript/JavaScript、Java 的支持最完整同时跳过构建产物、虚拟环境、node_modules 这类无关目录。这个阶段的关键是速度——archify 使用了多进程并行遍历实测一个两万文件的中型仓库全量扫描大概在十秒级别。依赖分析层读取不同语言的模块引用关系Python 包里的 import 语句、TypeScript 项目里的 import/export、Java 里的包引用等。archify 没有走运行时字节码分析的老路而是做静态引用采集好处是快且不依赖项目能编译通过代价是动态导入、反射调用这类场景会漏掉一部分隐性依赖遇到这种情况人工补一下关系即可。模块聚类层做的事情非常像一次简化版的逆向外推根据代码目录结构和包名把解析出来的模块关系聚合成服务或组件级别的节点。比如services/order目录下的所有模块会被归到 “订单服务” 这个节点再把这个节点跟它实际调用的数据库、消息队列、下游服务建立边关系。渲染输出层的产物有两种一种是标准 Mermaid 格式方便直接在 Markdown 文档里预览另一种就是核心卖点的交互式 HTML——节点可以拖拽、点击聚焦、按层级折叠展开还支持搜索定位。2.2 为什么大模型直接生成 Mermaid 不可行有人可能会问现在大模型本身就会写 Mermaid让 GPT 直接画一套微服务架构图不就行了这事儿我试过效果真的不稳定。大模型对代码库的全局结构没有真实感知它只能根据你提供的片段和它的先验知识去“猜”架构一旦项目里存在非典型目录结构、自定义框架封装、或者复杂的跨服务调用它画出来的图往往跟真实代码对不上。而 archify 走的是“先扫描事实再让模型参与组织与表达”的路线。它提供的图数据是真实依赖关系的采样结果AI 代理拿到这些结构化数据后可以沿着真实的结果去做解读、提炼、绘图参数调整。比起让模型自己编这相当于先给了它一份“标准答案”错误率天然低了很多。2.3 技能模块与大模型工具调用的关系从 AI 代理的角度看archify 就是一个标准的工具注册单元。现在主流代理框架都支持工具注册像 Claude 的 tool use、OpenClaw 的 action 模块、以及各类支持 MCPModel Context Protocol的客户端。archify 提供了两种接入方式一种是作为命令行工具被代理通过 shell 方式调用另一种是通过 MCP 接口注册为标准工具。MCP 方式我个人比较推荐。它把工具描述、输入参数 Schema 和调用执行封装成统一协议代理在需要获取项目结构信息时自行决定是否调用不需要你在 prompt 里写一堆调用规则。接入后你可以在对话里直接说“分析一下当前仓库的模块依赖画一张交互架构图”代理会自己完成从目录定位、扫描调用、结果接收、再到把 HTML 文件路径返回到对话里的完整闭环。2.4 生成的数据结构与图谱表达archify 内部用的是节点-边node-edge数据结构来组织架构关系节点记录了名称、类型service/database/mq/module、描述、源码路径边上记录了关系类型depends_on/calls/contains和描述。这个结构和 Neo4j 这类图数据库的模型很像所以如果后续要做更复杂的架构分析直接把导出的 JSON 灌进图数据库做查询也是可行的。交互式 HTML 侧用的是类似力导向图的渲染方案重依赖但不是 D3.js整体包体做了精简单个页面在 400KB 左右。每个节点都绑定了源码跳转链接点击后会在新标签页打开对应文件这一点对代码走读写报告特别顺手。3. 实操篇把 archify 接入到本地 AI 代理工作流3.1 环境准备与安装先说环境要求。archify 基于 Python 3.11 开发建议在干净的虚拟环境里安装避免污染全局 Python 环境python3.11 -m venv .venv source .venv/bin/activate pip install archify如果是 macOS 用户建议用 Homebrew 里的 Python 3.12 版本系统自带 Python 比较容易踩权限坑。安装完之后跑一下版本验证archify --version看到版本号输出就算成功。如果你打算走 MCP 方式接入还需要确保你用的代理客户端支持 MCP 协议我用的是 OpenClaw配置文件里声明一下即可。3.2 快速扫描生成第一张交互图进入一个你想分析的项目目录直接执行archify scan --input /path/to/your/project --format html --output ./arch.html第一次跑的时候它会全量扫描过程中终端会打印已识别的模块数量和依赖关系条数。跑完之后打开arch.html你会看到一张带力导向效果的交互图节点颜色区分了服务、数据库、外部 API 等类型图上方有一个搜索框用来定位节点。如果只想生成 Markdown 友好的 Mermaid 格式archify scan --input /path/to/your/project --format mermaid --output ./arch.md生成的 Mermaid 代码可以直接粘贴到支持 Mermaid 的文档平台展示。我的习惯是先跑 HTML 格式用于交互分析确认整体结构没问题后再补一份 Mermaid 放进设计文档。3.3 通过 MCP 将 archify 注册为代理技能MCP 方式接入的配置非常简单以 OpenClaw 示例在其配置文件中添加{ mcpServers: { archify: { command: archify, args: [mcp] } } }重启代理后用类似“请生成当前项目的交互式架构图”的指令测试。代理会自动感知到已注册的工具并在对话中调用。实测下来从发出指令到收到 HTML 文件路径整个过程通常在 20 秒内取决于仓库规模与磁盘读写速度。3.4 面向大型仓库的配置建议大型仓库直接全量扫描生成的图会变成一团乱麻没法看。archify 提供了裁剪参数来处理这种情况在实际项目里我用了这样的配置archify scan --input ./ --format html --output ./arch.html \ --ignore build,dist,.git,.venv,tests \ --focus services,api,core \ --depth 2--ignore指定跳过目录--focus指定重点分析目录--depth控制解析递归深度。它解决了一个画图经典问题只展示你关心层级的架构而不是把每个函数都铺在图上。配合模块聚类参数还能进一步合并同类节点让架构图的抽象层级更合理。比例控制上我拿一个电商后端项目测过完整扫描有 800 多个节点加上--depth 2和--focus之后压缩到 40 个核心节点这已经非常接近一张人工绘制的架构概要图了。4. 案例实操从零生成微服务架构交互图4.1 目标项目结构介绍我用一个模拟的电商后端项目做完整演示项目目录是这样布局的ecommerce/ ├── api-gateway/ # 网关服务 ├── services/ │ ├── user/ # 用户服务 │ ├── order/ # 订单服务 │ ├── payment/ # 支付服务 │ └── inventory/ # 库存服务 ├── shared/ │ ├── mq/ # 消息队列客户端封装 │ └── db/ # 数据库访问层 ├── docs/ └── scripts/这个结构比较典型有网关层、业务服务层、基础设施层正好能展示 archify 在分层聚类上的表现。4.2 扫描过程的完整记录执行archify scan --input ./ecommerce --format html --output ./ecommerce-arch.html扫描期间终端输出的信息反映了它的解析进度[archify] scanning 186 source files... [archify] detected git repo, using ref HEAD [archify] module clusters found: gateway(1), service(4), db(2), mq(2) [archify] edges resolved: 23 [archify] rendering interactive canvas...注意第二行detected git repo——archify 会读取 Git 历史来辅助判断模块归属如果不在 Git 仓库里运行有的高级聚类功能会降级。边缘关系只解析出了 23 条主要因为模拟项目服务间调用本来就不算密集真实的微服务系统会多得多。4.3 生成的交互架构图解读打开输出的 HTML 后默认视图按模块边界展开。画面上五个主要节点——网关、用户服务、订单服务、支付服务、库存服务是最大的一级节点分布在画布中央连线表示它们之间的调用关系。操作细节做得很到位。鼠标悬停一条边会显示这条依赖对应的实际代码位置点击后跳转到源码。双击某个服务节点整个画布会以它为焦点展开剩下的节点全部收缩成侧边栏列表。这种交互逻辑对排查“这个服务到底被谁调用了”这类问题特别有效比传统静态架构图效率高太多了。订单服务的下钻视图值得单独说一下。它能看到内部的控制器层、领域服务层、仓储层各自依赖的组件以及它对消息队列和生产者的引用情况。这就是交互式架构图对比静态图的优势——宏观和微观切换变得完全无感。4.4 增量更新与 CI 流程结合的思路架构图要长期保鲜就必须在每次代码变更后更新。archify 提供了--ref参数支持基于 Git 引用的增量分析可以结合 CI 流水线实现自动更新archify scan --input ./ecommerce --format html \ --output ./docs/architecture/index.html \ --ref origin/main每次主分支有合并流水线跑一次任务自动刷新架构图产物。然后通过团队的文档平台把更新后的 HTML 发布出去。这样做到“有代码变更有图变更”架构文档跟着代码走的体验比强调“我们定期维护文档”靠谱多了。5. 踩坑记录实测中的问题与排查思路5.1 扫描速度过慢我第一次在真实项目里跑 archify直接对仓库根目录全量扫描结果卡了近三分钟才出结果。排查发现虚拟环境.venv、前端依赖目录node_modules、打包产物目录都被当成了源码内容解析了。后来添加了全局忽略配置# ~/.config/archify/ignore.toml [ignore] dirs [.venv, node_modules, build, dist, target, __pycache__]再跑速度从三分钟降到十几秒。如果你的仓库里混入了大体积的 SQL 脚本或者数据文件也建议在忽略列表里加一下避免无意义的磁盘读取。5.2 交互式 HTML 在浏览器里白屏白屏问题多数不是 archify 生成的 HTML 有 bug而是浏览器版本过旧不支持 ES6 语法和 Canvas 相关 API。公司内网环境里员工用的浏览器版本往往滞后得厉害遇到白屏先别怀疑项目切换一个 Chrome 内核浏览器试试。另外有些电脑配置了严格的 Content-Security-Policy 或防火墙策略拦截了页面内嵌脚本执行。建议直接检查浏览器 Console 的报错信息是脚本执行被拦截还是资源加载被拦截对症处理。5.3 MCP 注册后代理无法发现工具如果你通过 MCP 注册了 archify但代理始终不调用它大概率是两个原因。一个是 MCP 服务启动失败命令行方式能跑但 MCP 模式下起不来另一个是工具描述信息太模糊代理不知道这个工具在什么场景下该用。排查第一项直接在终端跑archify mcp看是否正常监听。排查第二项我建议把工具描述写得足够明确例如{ name: generate_project_architecture, description: 扫描代码仓库并生成可交互架构图。当用户询问项目架构、模块依赖、服务关系时调用此工具。, parameters: {} }工具描述越明确代理的调用触发越可靠。5.4 大型项目生成的 HTML 文件过大在小微服务上 archify 表现很好但一旦扫描整个中大型单体仓库生成的 HTML 可能达到 2-3MB打开显慢。解决方案是在生成时增加裁剪参数控制参与渲染的节点数量。我在实际使用中形成的规则是单次渲染超过 150 个节点就开始影响浏览体验。配置--max-nodes 120并调整--depth 1到合适的层级可以让 HTML 文件体积控制在 500KB 以下交互流畅度也会明显改善。5.5 与 AI 代理组合时的隐性成本archify 作为技能模块接入 AI 代理后还需要留意上下文开销。代理调用工具之后拿到的是一份包含节点、边、描述的 JSON这个数据对象本身不大但如果在一次对话里反复让代理生成多张不同项目的架构图上下文里叠加的 JSON 会越来越多导致后续对话变慢。解决办法是每次分析完只保留关键结论把完整的 JSON 数据写入本地缓存文件而不是留在对话里。我通常让代理只回传“发现 4 个服务节点和 23 条依赖关系”这类摘要需要细节时再读文件整体效率高出很多。6. 我对 archify 的看法与后续扩展方向6.1 项目现状的客观评估从我这两天的实际体验来看archify 目前的成熟度介于“能用的工具”和“好用的产品”之间。它最核心的扫描-聚类-渲染链路已经跑通了交互式 HTML 的体验在同类开源工具里算得上第一梯队。但分支支持、异常处理、新语言适配这些环节还有不少缺口代码里能看到一些实验性质的模块划分项目的日常维护活跃度也在变化中。对于一个面向 AI 代理的工具来说当前阶段最大的价值在于把“理解架构”这个能力从人转移到了机器。即使你只把它当 CLI 工具用不接任何代理它也能大幅压缩画图的时间。6.2 延展方向可交互架构图之上的更多可能性交互式架构图只是第一步基于图数据的扩展玩法其实很多。比如结合代码指标在节点上展示复杂度、提交频率、缺陷率就变成了一张“架构体检图”把架构数据与运行时指标关联起来就能做依赖健康度透视分析哪些节点是故障扩散的源头。跟 AI 代理结合最值得期待的方向是“架构评审助手”。让代理定期调用 archify 生成基线与本次变更两张架构图自动对比新旧结构差异然后从依赖增加、循环引用、模块膨胀等维度输出评审意见。这一步如果能走通就等于把代码架构守护变成了自动化流水线的一部分而 archify 正好补上了“让代理获得真实结构感知”的关键环节。我在实际操作中体会最深的一点是工具本身能不能自动化画图其实不是最关键的关键是它让 AI 代理与真实代码库之间建立了一条可靠的、结构化的信息通道。以后凡是需要“理解项目全貌”的 AI 任务都可以在这条通道上做文章。先扫描再推理后输出这套工作流用在文档生成、代码走查、运维排障上价值都会比单独画一张架构图大得多。