1. 从一张“会自己长出来”的架构图说起第一次看到 archify 这个项目的时候我正在给一个跑了三年多的老系统做重构评估。那套系统有十几个服务依赖关系全靠口口相传和几份早就过期的文档撑着每次开评审会都要花半小时先画一遍调用链路。当时我就在想要是能有个东西把代码仓库丢进去它自己把架构图吐出来还能点、能展开、能追到具体模块那得省多少事。archify 干的基本就是这件事——它是一个挂在 AI 代理身上的技能模块让代理在理解一个项目之后自动生成一张可交互的架构图而不是一张死板的静态图片。先把定位说清楚archify 不是那种独立的画图软件也不是让你手动拖拽节点的工具。它的核心形态是技能模块skill module也就是说它本身是一段被 AI 代理调用的能力代理负责读代码、理依赖、做归纳archify 负责把这些理解渲染成一张能交互的图。这个区别很关键因为它决定了你的使用姿势——你不是打开一个网页去画图而是让代理去“跑”这个技能然后拿到产物。它解决的问题也很明确。传统架构图有三个老大难一是画的时候费劲手动拖拽、对齐、连线一个中等系统画半天二是画完就过期代码改了图没改三个月后图就成了误导三是静态图信息密度低一张 PNG 塞不下所有细节想看某个模块内部还得另开一张图。archify 针对的正是这三点自动生成解决费劲跟着代码走解决过期可交互解决信息密度。适合谁看这篇内容如果你是后端或全栈工程师手上有几个自己都说不清依赖关系的项目那这个思路对你直接有用如果你是技术负责人需要频繁给团队或外部讲清楚系统结构那自动生成加可交互这两点能帮你省下大量重复劳动如果你只是对 AI 代理的能力边界好奇想看看代理除了写代码、改 bug 之外还能干点什么“重活”那 archify 这类技能模块正好是一个很好的观察样本。下面我会从设计思路、核心机制、实操流程到踩坑经验一层层拆开讲。2. 为什么是“技能模块”而不是“独立工具”2.1 代理时代的能力组织方式变了要理解 archify 为什么做成技能模块得先理解 AI 代理这类东西的能力是怎么组织的。早期的 AI 助手基本是“一个模型打天下”你问什么它答什么能力全压在模型参数里。但代理不一样代理是“模型 工具 记忆 规划”的组合体模型负责推理工具负责执行具体动作。技能模块就是工具层的一种封装形式——它把某一类特定任务的处理逻辑打包好代理在需要的时候调用它。这种组织方式的好处用过代理的人应该都有体会。你不需要让模型去“记住”怎么画架构图也不需要每次都在提示词里写一大段渲染规则。技能模块把“怎么把结构数据变成可交互图”这件事固化下来代理只需要负责它擅长的部分读代码、理解模块关系、提取依赖。分工清晰各干各的。我打个比方。以前的画图工具像是一整套厨房设备你得自己切菜、自己掌勺、自己摆盘。archify 这种技能模块更像是你请了个配菜师傅你只管告诉他今天做什么菜也就是让代理去分析哪个项目他把切好配好的料递给你甚至直接帮你把菜炒了端上桌。你付出的成本从“学会整套设备”变成了“说清楚你要什么”。2.2 可交互这个点被严重低估了很多人一听到“自动生成架构图”第一反应是“哦就是自动画个图呗”。但 archify 里“可交互”这三个字含金量比“自动生成”还高。静态架构图的问题在于它是二维平面的、信息是平铺的一个复杂系统塞进一张图要么节点挤成一团看不清要么就得做取舍、砍掉细节。可交互图不一样它可以是分层的、可折叠的、可下钻的。举个具体场景。一个微服务系统顶层你看到的是网关、几个业务服务、消息队列、数据库。你点开某个业务服务它展开内部的模块划分再点某个模块它显示这个模块对外暴露的接口和依赖的第三方库。这种“逐层下钻”的体验静态图根本做不到你得画好几张图然后来回翻。可交互图把这几张图合成了一张信息密度上去了理解成本反而下来了。这也是为什么 archify 选择生成可交互图而不是导出 PNG。PNG 是终点可交互图是起点——你可以基于它继续探索、继续追问。代理生成的不只是一张图而是一个可以持续对话的结构化视图。2.3 和传统架构图工具的差异在哪市面上画架构图的工具不少从老牌的 Visio、Draw.io到专门做云架构的各类在线工具各有各的定位。archify 和它们的差异我用一张表说清楚。维度传统画图工具archify 这类技能模块输入人工拖拽、手动连线代码仓库、项目结构生成方式全手动代理分析后自动生成更新成本高改一处要动多处低重新跑一次即可产物形态静态图片或文件可交互视图信息密度受画布限制分层下钻理论上无上限适用阶段设计期、汇报期理解期、维护期、评审期看这张表你会发现archify 并不是要取代传统工具。设计一个新系统的时候你还是得用画图工具去推演、去表达你的设计意图因为那时候代码还不存在代理没东西可分析。archify 真正发力的地方是已有系统的理解与维护——代码已经在那了你需要快速搞清楚它长什么样、依赖怎么走、改动会波及哪里。这个场景传统工具做起来很痛苦因为你要一边读代码一边画画完代码又变了。3. 拆开看archify 的核心机制与关键环节3.1 代理侧它到底“看”了什么archify 作为技能模块本身不负责读代码读代码是代理的活。但代理读什么、怎么读直接决定了最终架构图的质量。根据这类项目的常见实现代理通常会从几个层面去提取信息。第一层是目录结构与模块划分。这是最粗粒度的一层代理扫描项目根目录识别出哪些是源码目录、哪些是配置、哪些是测试然后根据目录层级和命名推断出模块边界。比如一个典型的后端项目controller、service、dao这种分层目录代理一眼就能看出这是三层架构。第二层是依赖关系。这层要细一些代理需要解析 import 语句、require 调用、pom.xml 或 package.json 里的依赖声明把模块之间的引用关系抽出来。这一步的难点在于处理动态引用和间接依赖比如通过反射调用的、通过配置文件注入的静态分析不一定能全覆盖。第三层是接口与数据流。如果代理能力够强它还会去识别对外暴露的 API、消息队列的收发点、数据库的读写操作把这些作为节点之间的“边”标注出来。这一层做得好不好直接决定了架构图是“好看”还是“有用”。提示代理读代码的深度是可以调的。如果你只是想要一张粗粒度的模块关系图让它扫目录和依赖声明就够了如果你要追到接口级别就得让它做更深的静态分析耗时也会相应增加。3.2 技能侧结构数据怎么变成可交互图代理把结构数据整理好之后交给 archify 这个技能模块。技能模块要干的事是把这些数据渲染成一张可交互的图。这里面有几个关键决策。布局算法。架构图不是随便摆的节点位置直接影响可读性。常见的有分层布局适合有明确上下层关系的系统、力导向布局适合关系复杂、没有明显层级的系统、环形布局适合展示循环依赖。archify 这类工具通常会根据图的特征自动选择或者提供几种布局让用户切换。交互设计。可交互图的核心交互无非几种缩放平移、节点展开折叠、点击查看详情、搜索定位。听起来简单但要做好不容易。比如展开折叠你得处理好展开后其他节点的重新布局不能让图一下子乱掉再比如搜索定位你得让用户搜到一个深层节点后能自动把它的所有父节点展开并高亮路径。数据格式。技能模块内部通常用一种结构化的图数据格式来描述节点和边比如常见的节点-边列表或者更结构化的树形加交叉引用。这个格式决定了图能表达多复杂的关系。如果只支持树形结构那循环依赖就没法表达如果支持任意有向图那布局和交互的复杂度都会上去。3.3 一个容易被忽略的点增量更新架构图这东西生成一次不难难的是持续保持更新。archify 这类技能模块如果只支持全量生成那用几次你就懒得用了因为每次都要重新跑一遍完整分析。所以增量更新能力很关键。增量更新的逻辑大概是这样的代理记住上一次分析的结果这次只分析变更的部分然后把变更合并到已有的图数据里。比如你只改了一个 service 的内部实现没有动对外接口那架构图上这个 service 节点就不需要变只是它内部的细节数据更新一下。这样重新生成的成本就低很多你也就更愿意在每次提交后跑一次。我实测下来的感受是增量更新做得好不好直接决定了这类工具是“玩具”还是“日常工具”。全量生成一次要几分钟甚至更久你不可能每次改代码都跑增量更新几秒钟出结果那就可以挂在 CI 里每次合并请求自动更新架构图真正做到“图跟着代码走”。4. 实操从零跑通一次 archify 生成流程4.1 环境准备与前置条件在动手之前先把前置条件理清楚。archify 是技能模块所以你得有一个能加载技能模块的 AI 代理环境。这类环境目前主流的有几种形态一种是命令行式的代理工具你在终端里跟它对话一种是集成在编辑器里的代理插件还有一种是独立运行的代理服务。具体用哪种取决于你手上的工具链。代理环境准备好之后还需要确认几件事。第一代理要能访问你的代码仓库本地路径或者远程仓库地址都行。第二代理要有执行技能模块的权限有些环境默认关闭了技能调用需要手动开启。第三如果架构图要渲染成网页形式本地得有能起静态服务的环境或者代理自带预览能力。注意不同代理环境对技能模块的支持程度不一样。有的只支持官方内置技能有的允许加载第三方技能。archify 属于第三方技能用之前先确认你的代理环境允许加载外部技能模块否则跑不起来。4.2 让代理分析项目结构环境就绪后第一步是让代理去分析项目。这一步的提示词很关键你得把意图说清楚。我一般会这样组织请分析当前项目 /path/to/your/project 的结构 识别出主要模块、模块之间的依赖关系、 对外暴露的接口以及使用的中间件数据库、消息队列、缓存等。 分析完成后调用 archify 技能生成可交互架构图。这段话里有几个信息点。第一明确告诉代理分析哪个路径避免它去猜。第二把要提取的信息列清楚模块、依赖、接口、中间件这四类基本覆盖了架构图的主要元素。第三明确要求调用 archify 技能不然代理可能分析完就给你一段文字描述不生成图。代理开始分析后你会看到它逐步输出中间结果。先是目录扫描然后是依赖解析接着是接口识别。这个过程耗时取决于项目大小小项目几十秒大项目可能几分钟。分析过程中如果发现代理漏掉了某些模块可以随时打断它补充说明。4.3 生成与调整架构图分析完成后archify 技能被调用生成可交互架构图。第一次生成的结果通常不会完美需要调整。常见的调整点有几个。节点粒度。默认粒度可能太粗或太细。太粗的话一个节点代表一整个服务看不出内部结构太细的话每个类都变成一个节点图会爆炸。我一般会调整到“模块级”或“包级”既能看出结构又不至于太乱。依赖边的取舍。一个复杂系统里依赖关系可能成百上千条全画出来图就没法看了。通常需要过滤掉一些弱依赖比如只保留跨模块的依赖模块内部的依赖折叠起来。或者按依赖类型分层显示强依赖实线、弱依赖虚线。布局切换。如果默认布局看起来乱可以换一种。分层布局适合有明确上下层关系的系统力导向布局适合关系网状的系统。多试几种选一个看起来最顺眼的。调整的方式一般是通过对话告诉代理比如“把粒度调到包级”“隐藏模块内部的依赖边”“换成力导向布局”。代理会重新调用技能模块生成新的图。这个过程可以反复进行直到图达到你想要的效果。4.4 把图用起来导出与集成图生成好了接下来是怎么用。几种常见用法。本地预览。大多数技能模块会生成一个 HTML 文件你本地起个静态服务就能在浏览器里打开缩放、点击、搜索都能用。这种方式适合自己看、自己研究。嵌入文档。如果图能导出成可嵌入的格式可以放进项目的 README 或者内部文档系统。这样团队其他人不用跑代理就能看到最新的架构图。不过要注意嵌入的图是生成时的快照代码变了图不会自动更新得重新生成再替换。挂到 CI 流程。这是最理想的用法。在合并请求的流水线里加一步跑代理分析加 archify 生成把生成的图作为构建产物存起来。每次合并请求都能看到架构图的变化评审的时候一目了然。这个用法对代理环境的稳定性要求比较高得确保 CI 环境里代理能正常跑。5. 踩坑记录那些文档里不会写的问题5.1 代理“看走眼”的几种典型情况代理分析代码不是万能的有几种情况它容易出错我踩过好几次。动态依赖识别不到。如果项目里大量使用反射、依赖注入框架、或者通过配置文件动态加载模块代理的静态分析很可能漏掉这些依赖。结果就是架构图上少了关键的边看起来模块之间没关系实际上运行时耦合很紧。遇到这种情况我一般会手动补充说明告诉代理“模块 A 通过配置文件加载了模块 B”让它把这条边加上。命名不规范导致模块划分错误。有些项目目录命名很随意utils、common、base这种目录里塞了各种东西代理很难判断它们属于哪个模块。这时候要么手动指定模块划分规则要么接受一个粗粒度的结果别指望它能自动分得很准。循环依赖处理不好。循环依赖在架构图上表现为环很多布局算法处理环的时候会显得很乱。代理有时候会把环拆开导致图上看不出循环关系。如果循环依赖是你关注的重点得专门告诉代理“保留循环依赖的完整表达”。5.2 图太大跑不动怎么办大项目生成的架构图节点和边可能成千上万浏览器渲染起来会卡。我遇到过一个项目生成的图有三千多个节点打开直接卡死。解决办法有几个。第一分层生成。不要一次性生成全量图而是先出一个顶层图只显示主要模块。需要看某个模块内部的时候再单独生成那个模块的子图。这样每张图的规模都可控。第二过滤弱依赖。把依赖按强度排序只保留前 N% 的强依赖弱依赖折叠或隐藏。大部分时候你关心的就是那几条核心依赖弱依赖不看也罢。第三服务端渲染。如果技能模块支持可以让它在服务端把图渲染好前端只负责展示减轻浏览器负担。不过这取决于技能模块的实现不是所有都支持。5.3 常见问题速查表问题现象可能原因排查与解决代理分析完不生成图技能模块未加载或未授权检查代理环境的技能配置确认 archify 已启用图上模块缺失代理漏扫目录或动态依赖未识别手动指定扫描路径补充动态依赖说明图打开卡顿节点边数量过大分层生成、过滤弱依赖、降低粒度依赖边方向反了代理对调用方向理解错误检查代理的依赖解析逻辑必要时手动纠正图更新后变化巨大全量重新生成导致布局重排开启增量更新只更新变更部分导出格式不支持交互导出成了静态图片确认导出格式为 HTML 或支持的交互格式5.4 几个提升效果的小技巧用了一段时间之后我总结了几个让 archify 效果更好的技巧。给代理提供上下文。在让它分析之前先简单介绍一下项目是干什么的、有哪些核心模块。这能帮代理更快抓住重点不至于在无关的目录里浪费时间。比如你可以说“这是一个电商后端核心模块是订单、库存、支付”代理就会优先分析这几个模块。分阶段分析。不要指望一次分析就得到完美结果。先粗后细第一轮出顶层图确认模块划分对不对第二轮深入某个模块看内部结构第三轮补充接口和中间件信息。每轮聚焦一个层面结果更可控。保留中间数据。代理分析出来的结构数据最好存一份。这样下次重新生成图的时候不用重新分析直接拿数据渲染就行快很多。而且数据在手你想换种布局、换个粒度都不用再跑一遍分析。定期重新生成。架构图这东西生成一次就放着不管很快就过期了。我一般会在每个迭代结束时跑一次或者挂在合并请求流程里自动跑。保持图的新鲜度它才有参考价值。6. 这类技能模块的边界与我的实际体会archify 这类技能模块能力边界其实挺清晰的。它擅长的是从已有代码中提取结构并可视化不擅长的是理解设计意图和业务语义。代理能告诉你模块 A 调用了模块 B但它不知道这个调用是为了什么业务目的。所以架构图能帮你快速建立结构认知但业务逻辑还得你自己读代码或者问人。另外自动生成的架构图永远只是“当前代码的反映”不是“应该有的架构”。如果代码本身写得乱依赖关系一团糟那生成的图也会是一团糟。这时候图的价值不在于好看而在于它把混乱暴露出来了——你看着那张乱糟糟的图就知道该从哪里下手重构了。从这个角度说archify 生成的图不仅是理解工具也是诊断工具。我在实际使用中最大的体会是别把它当成一次性任务要当成持续的过程。第一次生成图可能只值 60 分但配合增量更新和定期重新生成它会越来越准、越来越有用。就像给系统做体检一次体检说明不了什么持续体检才能看出趋势和问题。架构图也是一样单张图的价值有限图的变化过程才是真正有价值的信息。最后分享一个我常用的做法把每次生成的架构图按时间存起来形成一个“架构演进史”。过几个月回头看你能清楚地看到系统是怎么一步步长成现在这样的哪些模块膨胀了哪些依赖变复杂了。这种纵向的视角比任何单张图都有价值。
