AI代理自动生成可交互架构图：archify技能模块实战与避坑指南

1. 架构图这件事，为什么一直让人又爱又恨

做后端或者搞系统设计的朋友都有体会，架构图这东西，画的时候嫌烦，不画的时候又不行。新同事入职要一张全局图，技术评审要一张部署图，给老板汇报还得来一张业务架构图。问题是，每次系统一改，图就过期，改图的时间比写代码还长。我见过太多团队，架构图停留在某个远古版本的 Visio 文件里，谁也不敢动，谁也不想动。

archify 这个项目就是冲着这个痛点来的。它是一个给 AI 代理用的技能模块，核心能力是让 AI 代理根据你的代码仓库或者文字描述，自动生成可交互的架构图。注意这里有两个关键词：一个是“AI 代理”，一个是“可交互”。前者意味着它不是那种你填表单然后点生成的死板工具，而是能理解上下文、能追问、能迭代的智能助手；后者意味着产出的不是一张静态 PNG，而是能点击、能展开、能钻取的动态视图。

这个技能模块适合谁用？我梳理了一下，大概三类人收益最大。第一类是中小团队的技术负责人，没预算买昂贵的架构管理平台，但又需要维护一份能看的架构文档；第二类是独立开发者或者接私活的朋友，交付项目时附一张清晰的架构图，专业度直接拉满；第三类是正在学习系统设计的新人，拿它来分析开源项目的结构，比干啃代码快得多。

我花了几天时间把这个技能模块的玩法摸了一遍，下面把整个思路、实现细节、踩过的坑都摊开讲。文章会比较长，但每一段都是实操里攒出来的，不是那种翻译 README 的水文。

2. 整体设计思路：为什么是“技能模块”而不是“独立工具”

2.1 技能模块的定位逻辑

先说说为什么 archify 选择做成技能模块，而不是一个独立的 SaaS 或者桌面应用。这个选择背后有很实际的考量。

独立工具的问题是，你得单独打开它，单独输入信息，单独导出结果，然后再切回你的工作流。这个切换成本看着小，实际上很致命。而技能模块是挂载在 AI 代理身上的，你在跟代理讨论代码的时候，随口一句“帮我把这个服务的架构画出来”，它就调用了 archify 的能力，直接在当前对话里产出图。这种“无感调用”才是它真正的价值。

从技术架构上看，技能模块本质上是一组封装好的提示词模板、工具调用定义和输出渲染逻辑。AI 代理负责理解意图和提取信息，archify 负责把信息转成结构化的图描述，最后前端负责渲染成可交互的图形。三层各司其职，耦合度低，这也是为什么它能适配不同的代理平台。

2.2 可交互架构图的技术选型

“可交互”这三个字说起来轻巧，实现起来有好几条路。我研究了一下 archify 的思路，它没有走传统的图片生成路线，而是输出结构化的图数据，再由前端渲染。这个决策很关键。

如果生成静态图片，那交互性就无从谈起，而且图片体积大、不可搜索、不可访问。如果生成 SVG，虽然能交互，但复杂架构下节点一多，性能会崩。archify 选择的是输出类似节点-边关系的结构化数据，前端用图形库渲染。这样做的好处是，缩放、拖拽、点击展开、搜索节点这些操作都是原生支持的，而且数据可以增量更新，改一个节点不用重画整张图。

提示：如果你打算自己复现类似方案，图形渲染库的选择很关键。节点数在 100 以内的，大部分库都能扛；超过 500 个节点的，一定要选支持虚拟化或者 Canvas 渲染的方案，否则浏览器会卡到怀疑人生。

2.3 与本地模型配合的考量

热词里提到了“AI 代理助手加本地模型”，这个组合在 archify 的场景下特别有意义。架构信息往往涉及公司内部系统，很多人不愿意把代码结构发给云端模型。这时候本地模型就派上用场了。

archify 的技能定义是平台无关的，也就是说，你把它挂到云端代理上能用，挂到本地跑的模型上也能用。本地模型的优势是数据不出内网，劣势是理解能力可能弱一些。我的经验是，对于结构清晰、命名规范的代码库，本地模型完全够用；对于那种命名混乱、历史包袱重的老项目，云端大模型的理解准确率会高不少。这个取舍要根据你的数据敏感度来定。

3. 核心细节拆解：从代码到架构图中间发生了什么

3.1 信息提取阶段的关键动作

AI 代理拿到“生成架构图”这个指令后，第一步是搞清楚要画什么。这里有个容易被忽略的细节：架构图分很多种，是画部署架构、业务架构、还是数据流架构？archify 的技能定义里应该包含了意图澄清的逻辑。

如果用户只说“画个架构图”，代理会先扫描项目结构，识别出这是单体应用还是微服务，用了哪些中间件，然后给出一个默认的架构视角。如果用户明确说了“我要看服务之间的调用关系”，那代理就会聚焦在服务依赖上。这个澄清过程看似简单，实际上决定了后面所有工作的方向。

信息提取的具体手段包括：读取项目根目录的配置文件（比如 pom.xml、package.json、docker-compose.yml），分析目录结构推断模块划分，扫描关键注解或装饰器识别服务边界。对于微服务架构，还会去读服务注册配置和网关路由规则。

3.2 图结构生成的参数与规则

从提取到的信息到最终的图结构，中间要经过一层转换。这层转换的规则直接决定了图的质量。我实测下来，有几个参数特别影响效果。

这些参数不是拍脑袋定的。节点粒度选服务级，是因为大部分场景下大家关心的是服务之间的边界，而不是某个服务内部的类关系。分层策略按调用层级，是因为这样最符合阅读习惯，从上到下就是请求的流向。折叠阈值定在 5 到 8，是实测下来屏幕空间和可读性的平衡点。

3.3 可交互能力的实现要点

可交互不是加个缩放就完事了。真正好用的交互设计，要解决几个具体问题。

第一个是渐进式披露。一张完整的微服务架构图可能有几十个服务，全展开根本看不清。好的做法是默认只显示核心服务，点击某个服务才展开它的内部模块。archify 的输出结构里应该包含了层级信息，前端据此实现展开折叠。

第二个是上下文关联。点击一个节点，应该能高亮所有跟它直接相关的节点和边，其他的淡出。这个功能在排查依赖问题时特别好用，一眼就能看出某个服务挂了会影响谁。

第三个是信息浮层。鼠标悬停或者点击节点时，弹出该节点的详细信息，比如技术栈、负责人、部署环境。这些信息如果全画在图上会乱成一锅粥，放在浮层里按需查看才合理。

注意：交互设计有个反直觉的点，功能不是越多越好。我见过一些架构图工具，右键菜单里塞了二十个选项，结果没人用。核心交互控制在三到四个就够了：展开折叠、高亮关联、查看详情、搜索定位。

4. 实操过程：手把手把 archify 跑起来

4.1 环境准备与技能挂载

假设你已经有一个能用的 AI 代理环境，接下来要做的是把 archify 技能挂上去。不同平台的挂载方式不一样，但核心步骤大同小异。

首先得拿到 archify 的技能定义文件。这类技能模块通常包含一个描述文件（说明技能名称、触发条件、输入输出格式）和若干提示词模板。拿到之后，按照你所用代理平台的文档，把技能注册进去。注册的时候要注意触发词的设置，太宽泛会误触发，太窄了又叫不出来。我的建议是设置成“画架构图”“生成架构图”“架构可视化”这几个明确的短语。

挂载完成后，做个简单的验证。随便找个项目目录，对代理说“帮我分析这个项目的架构并画出来”。如果代理开始读取文件、分析结构，说明技能已经生效。如果它反问你“什么是架构图”，那就是没挂上，回去检查注册步骤。

4.2 从代码仓库生成第一张图

验证通过后，来走一遍完整流程。我拿一个典型的 Spring Cloud 微服务项目做测试，目录结构大概是这样的：一个网关服务、一个注册中心、三个业务服务、一个公共模块。

第一步，让代理扫描项目。它会读取各个服务的配置文件，识别出服务名、端口、依赖关系。这个过程大概需要十几秒，取决于项目大小。

第二步，代理会输出一份中间结果，通常是一段结构化的描述，列出它识别到的所有服务和它们之间的关系。这一步很关键，你要仔细核对，看看有没有漏掉的服务或者识别错的依赖。我测试的时候就发现，代理把某个通过消息队列异步通信的服务误判成了直接调用关系。这种错误在自动生成里很常见，手动修正一下就好。

第三步，确认无误后，让代理生成图。它会输出一份图数据，前端渲染出来就是可交互的架构图。第一次生成可能需要调整布局参数，比如节点间距、连线样式，这些都可以通过追加指令来微调。

4.3 手动修正与迭代优化

自动生成的东西，一次就完美的概率很低。我总结了几类常见问题和对策。

服务漏识别的情况，通常是因为配置文件格式不标准，或者服务注册信息藏在代码里而不是配置里。解决办法是手动补充信息，告诉代理“还有一个叫 xxx 的服务，它依赖 a 和 b”。

依赖关系画错的情况，多半是代理把间接依赖当成了直接依赖。这时候需要明确告诉它“只画直接调用关系，不要展开传递依赖”。

布局混乱的情况，一般是节点太多导致的。可以调整折叠阈值，让部分节点默认收起。或者换一种布局算法，分层布局搞不定的，试试力导向布局。

提示：迭代的时候，不要每次都从头生成。让代理记住上一版的结果，只修改需要调整的部分。这样既快又不会把之前调好的部分搞乱。

5. 常见问题与排查技巧实录

5.1 代理不触发技能怎么办

这是最常见的问题。你说了“画架构图”，代理却跟你聊别的。原因通常有三个：技能没注册成功、触发词不匹配、或者代理的意图识别把架构图理解成了别的意思。

排查顺序是这样的：先确认技能列表里能看到 archify，看不到就是注册失败；再看触发词设置，试着用技能定义里写的原话去触发；如果都正常但还是不触发，那就是意图识别的问题，可以换一种说法，比如“把这个项目的结构可视化一下”。

5.2 生成的图节点太多看不了

节点爆炸是自动生成架构图的通病。一个中等规模的微服务项目，自动展开后可能有上百个节点。这时候不要硬看，先调折叠阈值，把非核心服务收起来。然后按业务域分组，把相关的服务聚在一起。最后用搜索功能定位你关心的部分。

如果调整参数后还是太乱，那说明这个项目的架构本身就需要梳理。自动生成只是把现状画出来，现状乱说明架构该重构了。这时候图反而成了一个诊断工具。

5.3 本地模型生成质量差怎么提升

本地模型在理解复杂代码结构时确实会力不从心。提升质量有几个实操技巧。一是给模型提供更明确的上下文，比如先让它读一遍项目的 README 和主要配置文件，再让它画图。二是分步走，先让它列出所有服务，确认后再让它分析依赖关系，最后再生成图。三是降低期望，本地模型适合结构清晰的新项目，老项目还是老老实实用云端模型或者手动画。

5.4 图数据能导出和版本管理吗

可以。archify 输出的图数据是结构化的，通常是 JSON 格式。你可以把它存到代码仓库里，跟代码一起做版本管理。每次架构变更，重新生成一次，对比 diff 就能看出改了什么。这个用法在技术评审时特别有用，评审材料直接附上架构图的 diff，谁改了什么一目了然。

6. 这套玩法还能怎么扩展

archify 这个技能模块本身是个起点，围绕它还能做不少延伸。我想到几个方向，有的已经试过，有的还在琢磨。

第一个方向是跟 CI 流水线集成。每次代码合并到主分支，自动触发一次架构图生成，把结果推到文档站点。这样架构图永远是新的，再也不会出现过期问题。实现上就是在流水线里加一个步骤，调用代理的 API 生成图数据，然后部署到静态站点。

第二个方向是做架构变更影响分析。把历史版本的图数据存下来，对比两个版本，自动识别出新增的服务、删除的依赖、变更的调用关系。这个在微服务治理里价值很大，能提前发现不合理的依赖引入。

第三个方向是结合芋道这类开源系统的架构图做学习辅助。拿一个成熟的开源项目，让代理生成架构图，然后对照着图去读代码，理解效率会高很多。特别是对于刚接触某个技术栈的人来说，先看图再看代码，比直接扎进代码里要快得多。

第四个方向是多视图切换。同一套系统，可以生成业务架构视图、部署架构视图、数据流视图，用户按需切换。这个对代理的信息提取能力要求更高，需要它从不同维度去理解同一份代码。

注意：扩展功能的时候要控制复杂度。我见过一些团队，给架构图工具加了太多花哨功能，结果核心的画图能力反而退化了。先把基础的生成和交互做扎实，再考虑锦上添花。

7. 我踩过的几个坑，你大概率也会遇到

第一个坑是过度依赖自动生成。刚开始用的时候觉得太爽了，什么图都让代理画。后来发现，代理画出来的图适合做初稿和沟通，但真正要归档的架构文档，还是得人工审核和润色。自动生成解决的是从零到一的问题，从一到十还得靠人。

第二个坑是忽略了图数据的维护。图生成出来就不管了，过两个月再看，跟代码完全对不上。后来我养成了习惯，每次大的架构调整后，顺手重新生成一次，花不了几分钟，但能省掉后面很多扯皮。

第三个坑是参数调得太激进。为了让图好看，把节点粒度调得很细，结果生成出来的图密密麻麻，自己都看不懂。后来学乖了，默认用服务级粒度，需要看细节的时候再单独展开某个服务。

第四个坑是没做版本对比。有一次排查一个线上问题，怀疑是某个依赖关系变更导致的，但谁也说不清什么时候改的。要是有架构图的版本记录，翻一下 diff 就清楚了。从那以后，我把图数据纳入了版本管理。

这几个坑说到底都是一个原因：把自动生成当成了终点，而不是起点。工具再好用，也得配上合理的流程和习惯，才能真正发挥价值。archify 这类技能模块的意义，是把你从重复劳动里解放出来，让你有精力去关注架构本身是否合理，而不是纠结于怎么把线画直。