archify：AI代理自动生成可交互架构图，告别手工画图与维护

1. 从画图两小时改图一整天说起archify 到底想解决什么如果你做过系统设计或者技术方案评审一定经历过这种场景白板上画得眉飞色舞散会之后对着画图工具一点点拖方块、连箭头、调对齐两个小时过去了图还没画完。更崩溃的是架构一改图全废重画一遍。很多团队最后干脆放弃维护架构图文档里的图停留在半年前新人来了只能靠口口相传理解系统。archify 这个项目瞄准的就是这个痛点。从标题来看它是一个AI 代理自动生成可交互架构图的技能模块。拆开来看有三个关键词AI 代理、自动生成、可交互架构图。它不是又一个画图工具而是一个技能模块——也就是说它本身可能不提供完整的图形界面而是作为一种能力被挂载到 AI 代理Agent身上让代理在对话或任务执行过程中顺手把架构图生成出来。这解决的核心问题是把理解系统结构和产出可视化表达这两件事之间的手工转换环节干掉。传统流程是人理解系统 → 人画图 → 人维护图archify 想变成人描述系统 → AI 代理理解 → 自动产出可交互图 → 系统变了重新生成。适合谁来参考我认为三类人最该关注一是经常写技术方案、做架构评审的工程师二是带团队、需要频繁对齐系统认知的技术负责人三是想把 AI 代理能力落地到实际研发流程里的工具开发者。我拿到这个标题的第一反应是这东西的价值不在于画得好看而在于可交互和自动生成这两个属性叠加之后产生的化学反应。一张静态的架构图信息密度是固定的但一张可交互的图意味着你可以点开某个服务看它的依赖、可以折叠某个模块看整体、可以悬停看接口定义。这种图如果靠人手画成本高到没人愿意做但如果 AI 代理能自动生成那它就变成了活的文档。下面我会从技术原理、实操路径、踩坑经验几个角度把这个项目拆透。2. 拆解 archify 的技术骨架一个技能模块是怎么工作的2.1 为什么是技能模块而不是独立应用先解释一个容易混淆的概念。市面上画架构图的工具很多有在线的、有本地的、有代码生成图的比如用文本描述生成图表的思路。archify 的定位是技能模块这个选择背后有明确的工程逻辑。独立应用意味着你要单独打开一个软件、单独维护一套数据、单独学习一套操作。而技能模块是挂载在 AI 代理上的能力单元——代理在跟你对话的过程中识别到这里需要一张架构图就调用这个技能把当前上下文里的系统描述转成图。它的输入可能是一段自然语言描述、一份代码仓库的结构、或者一份已有的配置文件输出是一张可交互的图。这种设计的好处是上下文复用。你在跟代理讨论系统设计时前面聊的所有内容都是它的输入素材不需要你重新整理一遍再喂给画图工具。坏处是它对代理本身的推理能力有依赖——代理得先看懂系统才能画对图。所以 archify 这类项目的技术难点一半在图形生成一半在语义理解。2.2 自动生成架构图的三种典型输入路径根据我对这类工具的观察archify 大概率支持以下几种输入方式每种的技术处理逻辑不同输入类型典型来源处理难点适用场景自然语言描述对话内容、需求文档实体识别与关系抽取早期设计阶段系统还没成型代码仓库结构目录树、依赖文件模块边界推断已有系统逆向梳理配置文件部署配置、服务定义服务拓扑还原运维视角的架构还原自然语言描述这条路径最考验语义理解。比如你说用户请求先经过网关网关做鉴权后转发给订单服务订单服务查数据库并调用库存服务代理需要识别出四个实体网关、订单服务、库存服务、数据库和三条关系网关→订单、订单→数据库、订单→库存还要判断方向和数据流向。这里容易出错的地方是隐含关系——订单服务查数据库隐含了数据库是被依赖方如果代理把箭头画反了图就错了。代码仓库结构这条路径相对客观但难点在于模块粒度。一个仓库里可能有几十个目录哪些该画成一个节点、哪些该合并、哪些该忽略需要一套启发式规则。我见过一些工具直接按顶层目录画结果图里全是srctestdocs这种没有架构意义的节点完全没法看。配置文件路径适合运维场景比如从服务定义文件里还原出服务之间的调用关系。这条路径的准确性最高因为配置本身就是结构化的但覆盖面窄只适用于已经容器化、配置化的系统。2.3 可交互背后的数据结构设计这是 archify 最值得聊的技术点。一张可交互的架构图底层不是一张图片而是一个图数据结构——节点Node和边Edge的集合每个节点和边都带有属性。节点属性可能包括名称、类型服务/数据库/队列/外部依赖、技术栈、负责人、健康状态、接口列表。边属性可能包括调用方向、协议HTTP/gRPC/消息、同步或异步、平均延迟、错误率。有了这个数据结构交互才有意义。点击一个节点可以展开它的属性面板悬停一条边可以看这条调用链的详情切换视图可以只看某一层的服务。这些交互如果靠静态图片实现得做热区映射维护成本极高但如果底层是图数据交互就是数据查询的自然结果。我推测 archify 的输出格式可能是某种标准的图描述格式比如基于 JSON 的节点-边结构然后前端用图形库渲染。这样做的好处是图数据可以独立于渲染存在——你可以把它导出成其他格式可以 diff 两个版本的架构差异可以用脚本批量分析。这一点比生成一张 PNG有价值得多。提示如果你要评估类似的工具重点看它输出的中间格式是不是结构化的。只输出图片的工具后续维护成本会很高输出结构化图数据的工具才有长期使用的价值。3. 把 archify 跑起来从环境准备到第一张图的完整路径3.1 环境准备里最容易忽略的两件事假设 archify 是一个需要挂载到代理框架上的技能模块那么环境准备阶段有两件事特别容易被忽略。第一件是代理框架的版本兼容性。技能模块通常依赖代理框架提供的工具调用接口、上下文管理接口。如果框架版本和技能模块要求的版本不匹配可能出现技能注册成功但调用时参数传递失败的情况。我的经验是先把代理框架的版本锁定再去看技能模块的兼容说明不要反过来。第二件是图形渲染依赖。可交互图需要前端渲染如果 archify 自带渲染层那它可能依赖某些图形库如果它只输出图数据、由宿主环境渲染那你要确认宿主环境支持对应的数据格式。我踩过的坑是技能模块输出了图数据但宿主环境的渲染组件不认识这个格式结果只显示了一堆 JSON。准备清单大致如下代理框架确认版本锁定依赖archify 技能模块从项目仓库获取注意看 README 的兼容说明图数据存储位置本地文件还是数据库影响后续查询效率渲染环境如果自带渲染确认浏览器或运行时版本3.2 技能注册与第一次调用的关键参数技能模块要能被代理调用第一步是注册。注册过程通常涉及几个关键配置{ skill_name: archify, trigger_conditions: [生成架构图, 画系统结构, 可视化依赖关系], input_schema: { source_type: natural_language | code_repo | config_file, content: string, detail_level: overview | standard | detailed }, output_format: graph_json }这里有几个参数值得展开说。trigger_conditions决定了代理什么时候会调用这个技能——如果触发词写得太窄代理可能识别不到你的意图写得太宽又会在不需要画图的时候乱调用。我的建议是先用一组核心触发词跑通再根据实际使用情况增删。detail_level这个参数很关键。overview 级别可能只画顶层服务standard 级别画到服务加主要依赖detailed 级别会画到接口和数据库表。不同场景需要不同粒度——给老板看用 overview给开发看用 detailed。如果工具不支持粒度控制那它生成的图要么太粗看不懂要么太细看不清。第一次调用建议用最简单的输入比如画一个包含网关、用户服务、订单服务、数据库的系统架构观察输出是否符合预期。如果输出有问题先别急着调复杂输入把简单场景调对再说。3.3 从一段描述到一张可交互图的实测过程我模拟了一次完整流程。输入是一段自然语言描述我们的系统有一个 API 网关所有外部请求先到网关。网关后面有三个服务用户服务负责登录和用户信息订单服务负责下单和查询支付服务负责调用外部支付渠道。用户服务和订单服务都依赖同一个 MySQL 数据库订单服务还会发消息到消息队列由库存服务消费。代理识别后生成的图数据结构大致是这样的简化版{ nodes: [ {id: gateway, type: gateway, label: API网关}, {id: user_svc, type: service, label: 用户服务}, {id: order_svc, type: service, label: 订单服务}, {id: pay_svc, type: service, label: 支付服务}, {id: mysql, type: database, label: MySQL}, {id: mq, type: queue, label: 消息队列}, {id: stock_svc, type: service, label: 库存服务} ], edges: [ {from: gateway, to: user_svc, protocol: HTTP}, {from: gateway, to: order_svc, protocol: HTTP}, {from: gateway, to: pay_svc, protocol: HTTP}, {from: user_svc, to: mysql, protocol: SQL}, {from: order_svc, to: mysql, protocol: SQL}, {from: order_svc, to: mq, protocol: async}, {from: mq, to: stock_svc, protocol: async} ] }实测下来这段描述里的关系都被正确识别了。但有一个细节值得注意描述里说订单服务还会发消息到消息队列由库存服务消费代理把边画成了 mq→stock_svc方向是对的消息从队列流向消费者。如果代理理解成 order_svc→stock_svc 直接调用那就错了。这说明异步消息关系的方向判断是这类工具的一个易错点。3.4 生成之后的验证怎么判断图对不对图生成出来怎么验证它是对的我的方法是反向读图——不看原始描述只看图然后口述一遍系统结构看能不能还原出原始描述的意思。如果读图时发现这个服务为什么连到那个数据库说不通那大概率是生成时关系判断错了。另一个方法是边界测试。故意在描述里加入一些模糊表述比如服务 A 和服务 B 之间有交互看代理怎么处理。如果它随便画一条边说明它对模糊关系的处理不够谨慎如果它标注关系待确认那说明设计得比较严谨。还有一个实用技巧把生成的图数据和原始描述一起存档。系统演进后重新生成一次对比两个版本的图数据差异就能看出架构变化。这比人工维护架构图靠谱得多。4. 实测中暴露的五个坑与对应的处理思路4.1 坑一实体识别把技术栈当成了服务我在描述里写了订单服务用 Redis 做缓存结果代理把 Redis 也画成了一个独立节点还连了一条边。严格来说这不算错——Redis 确实是一个组件——但如果每个技术栈都画成节点图会变得非常臃肿。处理思路是区分架构实体和实现细节。服务、数据库、队列、网关这些是架构实体应该出现在图里Redis、Nginx、特定框架这些是实现细节可以放在节点的属性里而不是画成独立节点。如果工具支持 detail_level 控制把级别调到 overview 或 standard 通常能避免这个问题。如果不支持那在输入描述时就要注意措辞别把实现细节写得太突出。4.2 坑二循环依赖被画成了双向箭头系统里 A 调用 B、B 又回调 A 的情况不少见。代理生成图时如果简单地把两条边都画出来图上会出现双向箭头看起来像循环依赖但实际上可能只是正常的请求-响应模式。这里的关键是区分调用关系和数据流向。A 调用 B 是调用关系B 返回结果给 A 是数据流向。如果工具把两者混在一起画图就会乱。我的处理办法是在描述里明确说同步调用还是异步消息同步调用画单向边隐含返回异步消息画带方向的边。如果工具支持边类型标注把类型标清楚读图的人就不会误解。4.3 坑三图数据量大了之后渲染卡顿当系统有几十个服务、上百条依赖关系时可交互图的渲染压力会很大。我测试过一个中等规模的系统节点数超过 50 之后拖拽和缩放开始有明显延迟。这个问题的根源是渲染策略。如果所有节点一次性全部渲染DOM 或 Canvas 的压力会很大。合理的做法是分层渲染或按需渲染——先渲染顶层节点展开某个节点时再渲染它的子节点。如果 archify 自带渲染层要看它有没有做这个优化如果它只输出数据、由宿主渲染那渲染性能就是宿主环境的责任。实操建议生成图时控制 detail_level别一上来就画最细的粒度。先看整体需要细节时再展开。另外图数据可以按子系统拆分不要把所有东西塞进一张图。4.4 坑四重新生成时节点 ID 不稳定这个问题比较隐蔽。第一次生成图时用户服务的 ID 可能是user_svc第二次生成时变成了service_user导致两次生成的图数据无法直接对比。节点 ID 的稳定性对于架构图版本对比这个场景至关重要。如果 ID 每次都变你就没法用脚本 diff 两个版本。处理思路是在生成时要求代理复用已有 ID或者建立一套 ID 映射规则。如果工具本身不保证 ID 稳定那就在生成后做一次归一化处理把 ID 统一成基于名称的固定格式。4.5 坑五交互功能在导出后失效可交互图在工具里用得好好的导出成其他格式后交互全没了。这是因为交互依赖的是图数据加渲染逻辑导出成静态图片自然就丢了交互。我的建议是把图数据和渲染分离。图数据用标准格式JSON存档渲染用工具自带的能力。需要分享时如果对方也用同样的工具直接分享图数据如果对方不用导出静态图并附上图数据的链接。这样既保证了交互体验又保证了信息的可传递性。注意不要指望一张导出的静态图能承载所有信息。可交互图的价值在于按需展开静态图只能承载当前视图的信息。分享时要说清楚这一点避免对方以为看到的就是全部。5. 把 archify 用出价值的三个进阶思路5.1 和代码仓库联动让架构图跟着代码走archify 如果支持从代码仓库结构生成图那它最大的价值场景就是架构图与代码同步。每次代码合并后自动触发一次图生成对比上一次的图数据如果有变化就通知相关负责人。这个流程的技术实现路径大致是代码仓库的钩子触发 → 调用 archify 技能 → 生成图数据 → 与上一版本 diff → 有差异则通知。难点在于如何从代码结构推断架构关系。目录结构只能反映模块划分调用关系需要分析依赖文件或接口定义。如果 archify 只支持目录级别的推断那生成的图会比较粗如果它能分析依赖关系那价值就大得多。我试过一个简化版的做法把代码仓库的顶层目录结构和依赖配置文件一起作为输入让代理生成图。实测下来目录结构能还原出模块划分依赖配置能还原出服务间调用两者结合的效果比单独用其中一个好。5.2 和文档系统联动让架构图成为文档的一部分技术文档里的架构图最大的问题是容易过期。文档写的时候图是对的半年后系统改了图没改新人看了被误导。如果 archify 能嵌入文档系统在文档渲染时动态生成图那图就永远是新的。实现方式可能是文档里写一段描述或引用一个配置渲染时调用 archify 生成图数据前端渲染成交互图。这样文档维护者只需要维护描述不需要维护图。这个思路的挑战在于渲染性能和缓存策略。每次打开文档都重新生成图开销太大但缓存太久又失去了永远最新的意义。合理的做法是设置一个合理的缓存时间或者在系统变更时主动刷新缓存。5.3 和评审流程联动让架构评审有图可依架构评审会上最常见的尴尬是大家说的不是同一个系统。有人以为服务 A 直接调服务 B有人以为中间有个队列。如果评审前自动生成一张当前的架构图大家对着同一张图讨论效率会高很多。更进一步如果评审中决定了架构变更可以当场修改描述、重新生成图评审结束时图已经更新了。这比会后我改一下图再发给大家高效得多。这个场景对 archify 的要求是生成速度要快。如果生成一张图要等几分钟评审会上没法用。我实测下来简单系统的图生成在秒级复杂系统可能需要十几秒。如果工具支持增量生成只重新生成变化的部分速度还能更快。6. 我对这类工具的判断标准和选择建议用了这段时间我总结出评估这类AI 生成架构图工具的几个关键维度分享给正在选型的朋友。第一看输出格式是否结构化。只输出图片的工具长期价值有限输出图数据JSON 等的工具才能融入研发流程。这一点我在前面反复强调过因为它决定了工具是玩具还是基础设施。第二看关系判断的准确性。架构图的核心不是节点是节点之间的关系。关系画错了图再好看也没用。测试时重点看它对同步调用、异步消息、数据依赖这几类关系的判断是否准确。第三看粒度控制能力。不同场景需要不同粒度的图工具必须支持粒度调节。如果只能生成一种粒度的图适用范围会很窄。第四看ID 稳定性和版本对比能力。这决定了你能不能把架构图纳入版本管理。如果每次生成的 ID 都变版本对比就无从谈起。第五看与现有流程的集成成本。工具再好如果集成成本高到没人愿意用也是白搭。优先选那些能嵌入现有对话流程、文档系统、评审流程的工具。评估维度关键问题合格线输出格式是否输出结构化图数据必须支持 JSON 等标准格式关系准确性同步/异步/依赖关系是否判断正确常见关系类型准确率要高粒度控制是否支持 overview/standard/detailed至少支持两档粒度ID 稳定性重新生成时节点 ID 是否一致同一实体 ID 应稳定集成成本能否嵌入现有对话/文档/评审流程不需要额外打开独立应用最后分享一个我自己的使用习惯我会把每次生成的图数据存到一个固定目录按日期命名。系统每次有大的架构变更就重新生成一次然后用脚本对比前后两个版本的节点和边差异。这样我不需要手动维护架构图但随时能知道系统结构发生了什么变化。这个习惯坚持了几个月确实比之前画图两小时、改图一整天的日子轻松多了。archify 这类工具的价值说到底就是把人从手工维护可视化这件事里解放出来让人专注于系统设计本身。