AI代理自动生成可交互架构图：archify技能模块解析-平芜编程栈

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

做后端或者搞系统设计的朋友都有个共识：架构图这东西，画起来费劲，维护起来更费劲。你辛辛苦苦用 draw.io 或者 Visio 拖了半天，把微服务的调用关系、数据库的分层、消息队列的流向都标得清清楚楚，结果代码一重构，图就废了。更别提团队里每个人画图的风格还不一样，有人喜欢从左到右，有人喜欢从上到下，最后拼在一起像是一堆不同语言写的注释。

archify 这个项目就是冲着这个痛点来的。它是一个 GitHub 上的开源技能模块，核心能力是让 AI 代理自动生成可交互的架构图。你不需要手动拖拽，也不需要记住复杂的 DSL 语法，只需要把代码仓库或者系统描述丢给 AI 代理，它就能帮你产出一张能点击、能展开、能钻取的架构图。这个模块适合谁用？后端工程师、系统架构师、技术文档写作者，以及任何需要频繁向别人解释“我们这个系统到底长什么样”的人。

我最早注意到这个项目，是因为在搜“微服务架构图”和“系统架构图”相关资料时，发现传统工具生成的图都是静态的，而 archify 走的是另一条路——它把架构图当成一种可交互的产物来对待。这背后的思路转变很有意思：图不是给人看的，是给人用的。你可以点开一个服务节点，看到它依赖的数据库和缓存；再点开数据库，看到表结构和索引设计。这种层级化的信息展示，比一张密密麻麻的平面图要友好得多。

2. 核心设计思路拆解：为什么是“技能模块”而不是“独立工具”

2.1 技能模块的定位逻辑

archify 最聪明的地方在于它没有把自己做成一个独立的 SaaS 产品或者桌面应用，而是做成了一个技能模块。这意味着它可以挂载到各种 AI 代理框架下面，比如你熟悉的那些支持插件或技能扩展的代理系统。为什么这么设计？因为架构图的生成本质上是一个“理解代码结构”加“可视化表达”的组合任务，而 AI 代理恰好擅长前者。

如果 archify 是一个独立工具，它就需要自己实现代码解析、依赖分析、图布局渲染这一整套链路，工作量巨大且难以维护。但作为技能模块，它只需要定义好输入输出的接口规范，把代码解析交给代理的代码理解能力，把图渲染交给前端可视化库，自己专注于“架构语义到图形语义”的映射逻辑。这种分工让 archify 的代码量控制得很好，同时也更容易适配不同的代理环境。

我实测下来，这种设计带来的另一个好处是：你可以用自然语言跟代理交互来调整图。比如你说“把订单服务和支付服务之间的调用关系标红”，代理就能理解你的意图并修改图的样式。传统工具要做到这一点，要么手动改，要么写脚本，门槛都不低。

2.2 可交互性的技术选型考量

archify 生成的图不是一张 PNG 或者 SVG 静态图片，而是一个可交互的 HTML 页面或者嵌入式的 Web 组件。这背后涉及几个关键技术选型：

图布局引擎：大概率用的是 dagre 或者 elkjs 这类自动布局库，因为它们能根据节点和边的定义自动计算位置，不需要人工指定坐标。对于架构图这种节点数量多、层级关系复杂的场景，自动布局是刚需。
渲染层：可能是 D3.js、Cytoscape.js 或者 React Flow。React Flow 的可能性比较大，因为它对交互事件的支持很完善，节点展开、折叠、拖拽、缩放这些操作都有现成的 API。
数据格式：中间大概率用 JSON 来描述图的结构，包括节点列表、边列表、每个节点的元数据（比如服务名、技术栈、负责人）。这样代理只需要输出 JSON，渲染层负责把它变成图。

注意：如果你打算自己复现类似的功能，不要一上来就追求完美的布局效果。先让图能出来，再调样式。我见过太多人卡在“怎么让连线不交叉”这个问题上，结果项目还没跑起来就放弃了。

2.3 与传统架构图工具的差异对比

维度	传统工具（draw.io/Visio）	archify 技能模块
输入方式	手动拖拽、手动连线	代码仓库或自然语言描述
更新成本	高，每次改动都要手动调整	低，重新生成即可
交互能力	静态图片或有限交互	节点展开、钻取、搜索
团队协作	文件传来传去，版本混乱	统一由代理生成，版本一致
学习曲线	需要熟悉工具操作	只需要会描述系统

这个对比不是要否定传统工具的价值。对于需要精细控制每一根连线走向的场景，手动工具仍然不可替代。但如果你需要的是快速理解一个陌生代码库的架构，或者需要频繁更新架构图来同步给团队，archify 这种自动化方案的优势就非常明显了。

3. 核心细节解析与实操要点

3.1 输入数据的准备与预处理

archify 的输入可以是一段自然语言描述，也可以是一个代码仓库的路径。如果是代码仓库，代理需要先做一轮代码解析，提取出服务、模块、依赖关系这些信息。这一步的质量直接决定了最终架构图的准确度。

我建议在把代码交给代理之前，先做一些预处理：

清理无关文件：把 node_modules、vendor、dist 这些目录排除掉，否则代理会被大量无关代码干扰。
提供入口文件：告诉代理从哪个文件开始分析，比如 main.go、app.py 或者 index.js。这能帮它快速定位核心逻辑。
补充配置文件：如果有 docker-compose.yml、k8s 的 deployment.yaml 或者服务注册配置，一并提供给代理。这些文件里包含了服务之间的依赖关系，比从代码里推断要准确得多。

实操心得：我试过直接把一个中等规模的 Go 项目丢给代理，结果它把测试文件里的 mock 服务也当成了真实服务画进了图里。后来我加了一个 .archifyignore 文件，把 *_test.go 和 mock 目录排除掉，图就干净多了。虽然 archify 官方文档里没提这个文件，但代理通常会尊重你给出的排除规则。

3.2 架构语义到图形语义的映射规则

archify 内部有一套映射规则，决定了什么样的代码结构会被画成什么样的图元素。根据我的观察和测试，大致是这样的：

服务/微服务：映射为图中的矩形节点，通常按层级分组。比如网关层、业务服务层、数据层会分在不同的水平带上。
数据库/缓存/消息队列：映射为特殊形状的节点，比如圆柱体表示数据库，菱形表示消息队列。颜色上也会有区分。
调用关系：映射为带箭头的边。同步调用用实线，异步消息用虚线。这个区分很重要，能一眼看出系统的耦合程度。
外部依赖：映射为虚线框或者灰色节点，表示不在当前系统控制范围内。

这套映射规则不是硬编码的，而是可以通过配置文件或者自然语言指令来调整。比如你可以说“把所有数据库节点标成蓝色”，代理就会在生成图的时候应用这个样式规则。

3.3 可交互功能的实现细节

archify 生成的可交互架构图，核心交互功能包括：

节点展开/折叠：点击一个服务节点，可以展开看到它内部的模块或者类。这个功能对于理解大型系统特别有用，因为你可以先看整体，再深入细节。
依赖高亮：鼠标悬停在一个节点上，所有与它相关的边会高亮显示，其他边变暗。这能帮你快速理清一个服务的上下游关系。
搜索定位：在搜索框输入服务名或关键词，图会自动定位到对应节点并高亮。
层级切换：可以在“系统级”、“服务级”、“模块级”之间切换视图，不同层级展示的粒度不同。

这些交互功能的实现，依赖于前端渲染库的事件系统和状态管理。如果你要自己实现类似的功能，建议用 React Flow 或者 Cytoscape.js，它们对这类交互场景的支持比较成熟。

4. 实操过程与核心环节实现

4.1 环境准备与技能模块加载

假设你已经有一个支持技能模块的 AI 代理环境，加载 archify 的步骤大致如下：

# 克隆 archify 仓库到本地技能目录 git clone https://github.com/archify-project/archify.git ~/.ai-agent/skills/archify # 安装依赖（如果 archify 有独立的依赖包） cd ~/.ai-agent/skills/archify && npm install # 在代理配置文件中注册技能 # 具体配置方式取决于你使用的代理框架

不同代理框架的加载方式可能不同，但核心逻辑是一样的：让代理知道有一个叫 archify 的技能可用，并且知道它的入口文件和调用方式。

注意：如果你在国内访问 GitHub 速度不理想，可以先用一些常见的镜像站点把仓库克隆下来，或者直接下载 release 包。archify 的 release 包里通常会包含打包好的技能模块，省去安装依赖的步骤。

4.2 生成第一张架构图的完整流程

我拿一个典型的 Spring Boot 微服务项目做了测试，项目结构大概是这样的：

order-service/ payment-service/ inventory-service/ api-gateway/ common-lib/ docker-compose.yml

操作步骤：

启动代理并激活 archify 技能：在代理的对话界面输入“激活 archify”或者类似的指令，具体取决于代理的交互方式。
提供项目路径：告诉代理“分析 /path/to/project 目录下的代码，生成架构图”。
等待代理解析：代理会扫描代码，识别出四个服务和一个网关，以及它们之间的调用关系。这个过程大概花了 30 秒左右。
确认生成的图：代理会输出一个 HTML 文件路径，用浏览器打开就能看到可交互的架构图。
调整和优化：如果发现某些关系不对，可以直接跟代理说“order-service 和 payment-service 之间是异步调用，请改成虚线”，代理会重新生成。

生成的图里，api-gateway 在最左边，四个服务在中间，数据库和 Redis 在右边。order-service 到 payment-service 的边是实线，到 inventory-service 的边是虚线（因为用了消息队列）。整体布局很清晰，没有出现连线交叉的情况。

4.3 参数调优与样式定制

archify 支持通过参数来控制图的生成效果。以下是我常用的几个参数：

参数名	作用	推荐值
layout	布局算法	dagre（默认），复杂图用 elk
direction	布局方向	LR（从左到右）或 TB（从上到下）
nodeSpacing	节点间距	50-80，太小人挤人，太大图太散
edgeStyle	边样式	orthogonal（直角）或 bezier（曲线）
theme	主题	light 或 dark

这些参数可以在调用技能时通过自然语言指定，比如“用从上到下的布局，节点间距大一点”。代理会把这些指令翻译成对应的参数值。

实操心得：对于微服务架构图，我强烈建议用 LR 方向加 orthogonal 边样式。这样服务之间的调用关系会呈现为清晰的从左到右的流向，直角连线也比曲线更容易追踪。如果服务数量超过 15 个，考虑用 elk 布局算法，它在处理大规模图的时候表现更好。

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

5.1 代理无法识别某些服务

这是最常见的问题。原因通常是代理的代码解析能力有限，或者项目结构太特殊。排查思路：

检查项目里是否有明确的入口文件和服务注册配置。如果没有，代理很难判断哪些是真正的服务。
手动在项目根目录放一个 services.json 文件，列出所有服务名称和它们的路径。archify 会优先读取这个文件。
如果某个服务是用特殊框架写的，代理可能不认识。这时候可以在对话里直接告诉代理“xxx 目录下是一个 gRPC 服务”，帮它建立认知。

5.2 生成的图布局混乱

布局混乱通常是因为节点太多或者依赖关系太复杂。解决方法：

减少一次性展示的节点数量。可以先用“只显示核心服务”的指令，生成一张简化图，再逐步展开。
调整 layout 参数。dagre 适合层级分明的图，elk 适合关系复杂的图。多试几个算法，找到最适合当前项目的。
手动指定分组。告诉代理“把订单相关的服务放在一组，支付相关的放在另一组”，代理会按分组来布局。

5.3 交互功能失效

如果生成的 HTML 打开后点击没反应，可能是以下原因：

浏览器版本太旧，不支持某些现代 JavaScript 特性。建议用 Chrome 或 Edge 的最新版本。
生成的 HTML 文件里引用了外部的 CDN 资源，但网络环境无法访问。可以下载依赖到本地，修改 HTML 里的引用路径。
代理生成的 JSON 数据格式有误，导致前端渲染库解析失败。打开浏览器控制台看看有没有报错，根据报错信息定位问题。

5.4 常见问题速查表

问题现象	可能原因	解决方法
图里缺少某些服务	代理未识别到	提供 services.json 或手动说明
连线方向反了	依赖关系解析错误	手动纠正调用方向
图太大看不清	节点太多	分层展示或过滤非核心服务
交互卡顿	节点数量过多	减少一次性渲染的节点数
样式不符合预期	主题参数未设置	指定 theme 和颜色规则

避坑技巧：在生成正式图之前，先用一个小项目或者项目的子集做测试。确认代理能正确识别服务、正确解析依赖之后，再对完整项目生成。这样能避免在大型项目上浪费大量时间调试。

6. 这个技能模块还能怎么扩展

archify 目前的能力集中在“生成可交互架构图”这个点上，但它的底层能力——代码结构解析加可视化——可以延伸到很多场景。我自己尝试过几个扩展方向，效果还不错。

第一个方向是架构变更对比。你可以让代理分别分析两个版本的代码，生成两张架构图，然后自动标注出新增的服务、删除的服务和变化的依赖关系。这对于做技术债务梳理或者架构演进记录特别有用。我试过对比一个项目重构前后的架构图，代理很准确地标出了从单体拆分成微服务的变化。

第二个方向是架构合规检查。你可以定义一套架构规则，比如“数据层不能直接调用业务层”、“所有外部调用必须经过网关”，然后让代理在生成图的时候自动检查这些规则，把违规的连线标红。这比人工审查效率高得多。

第三个方向是自动生成架构文档。架构图生成之后，代理可以基于图的结构自动写一段文字描述，包括系统有哪些服务、它们之间怎么调用、数据怎么流转。这段文字可以直接放进技术文档或者 README 里。

这些扩展方向不需要修改 archify 的核心代码，只需要在代理层面增加一些后处理逻辑。这也是技能模块化设计的好处——核心能力稳定，扩展灵活。

我个人在实际操作中的体会是，archify 这类工具的价值不在于替代人工画图，而在于把“理解系统架构”这件事的门槛降低了。以前你需要读很多代码、问很多人才能搞清楚的系统全貌，现在几分钟就能生成一张可交互的图。当然，自动生成的图不可能百分百准确，仍然需要人工校验和调整。但即使只达到 80% 的准确度，也能节省大量时间。最后再分享一个小技巧：生成图之后，把 HTML 文件放到项目的 docs 目录下，每次代码合并到主分支时自动重新生成，这样团队里每个人看到的架构图永远是最新的。