平时画架构图最烦什么？不是不知道怎么写代码，而是画图这件事本身就是个“高成本低产出”的活儿。需求一变，服务一拆，图就废了；图一废，后面接手的人又得重新读代码猜结构。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 模块、以及各类支持 MCP（Model 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 任务，都可以在这条通道上做文章。先扫描，再推理，后输出，这套工作流用在文档生成、代码走查、运维排障上，价值都会比单独画一张架构图大得多。
