如果你平时维护的不只是一个服务而是一整组互相调用的 AI 代理你大概率经历过这种场面文档里的架构图画的是三个月前的版本代码里已经冒出七个新模块线上拓扑更是早就对不上号。手画架构图永远跟不上迭代速度这是团队里最容易被忽视的隐性成本。今天想聊的 GitHub 项目 archify就把“画架构图”这件事直接变成了 AI 代理的一项技能——你只需要在对话里描述需求代理就能产出可交互架构图而不是丢给你一张静态图片。这个项目真正吸引我的地方不是“用 AI 画图”这个噱头而是它的技能模块化设计。它不是一次性脚本而是可以被挂进 MCP、Claude Skill、本地 Agent 框架里的标准工具包。对有 AI 代理编排、系统设计、技术文档需求的开发团队来说能省掉大量重复劳动。下面我会从原理、接线、实测、心得四个角度聊透尽量还原我自己从接触这个项目到实际用起来的完整过程。1. AI 代理跑得越快架构图越画不出来1.1 架构图不再是“文档任务”而是调试工具Agent 系统跟传统后端系统最大的不同是调用链不是固定的。你写一个后端支付服务调用顺序基本是死的但一个 AI 代理今天可能先调工具 A明天换工具 B后天又从缓存里直接拿结果。这种动态行为靠人脑追踪基本上两三个模块之后就乱了。所以要有一张能实时反映当前结构的图这张图不是给人当汇报材料用的而是给调试、给设计评审、给新人上手用的。archify 的切入点就在这里它让代理在执行任务的过程中自动沉淀一张架构视图。代理每跑完一轮图就更新一次节点、边、状态都跟着最新代码和运行时信息走。这比“隔两周手工画一次”实用得多而且代理自己画的图反映的是它实际理解的系统而不是文档里理想化的系统。1.2 静态图和可交互图的本质差异大多数团队现在画架构图用的还是 Mermaid、PlantUML 或者 Draw.io。这几种工具本身没什么不好但都有一个共同问题产出的是“一锤子买卖”的静态描述。一旦系统变大节点上百个静态图基本就废了——你想看某个模块的详细依赖整张图糊在一起你想知道某个节点最近的状态变化图上根本体现不出来。可交互图解决的就是这个阅读问题。点击节点展开子模块、拖拽调整布局、缩放看全貌、悬停看节点元信息这些能力看起来是 UI 层面的事但背后要求架构图有一个稳定的结构化数据模型。archify 的输出本质上是一份对象模型再加一层渲染壳。对象模型描述“系统里有什么、谁跟谁相连”渲染壳负责让你能跟这张图互动。1.3 archify 和通用图表生成器的区别在哪市面上能生成架构图的 AI 工具不少有的直接让视觉模型改代码有的套一层前端画布就敢叫可视化平台。archify 不太一样的地方在于它把整个能力封装成了 agent skill而不是一个独立网页或命令行工具。这种定位带来的好处很直接它可以被任意智能体框架识别和调用。比如我自己的管线里路由层收到用户需求后会先做意图识别如果发现用户想要“看看当前系统的模块关系”就直接调用 archify 技能模块让它在后台跑一遍静态分析加交互图生成最后把图嵌进对话流返回。整个过程不需要人切换到另一个工具体验上是连续的。另外因为它是技能模块它可以被组合。出图之后把结构数据再交给另一个技能做依赖检查或者交给知识库技能做文档归档都是顺手的事。这种“模块化、可编排”的属性才是它值得被放进代理工作流里的核心原因。2. archify 技能模块的核心工作链路2.1 三步流水线收集、抽象、渲染我从项目文档和实际跑下来的情况里总结archify 的出图链路大致分为三步。第一步是收集原始信息来源可以是代码仓库、接口定义、运行日志甚至只是一段自然语言描述。第二步是抽象建模把收集来的信息转换成一个统一的结构模型通常包含节点、边、分组、状态这几类要素。第三步是渲染把结构模型交给渲染内核生成带交互能力的 HTML 画布。关键点在于第二步。很多自动生成架构图的方案死就死在“从信息到模型”这一步——要么只认代码要么只认文本稍微换个输入形态就不会了。archify 的做法是标准化中间表示无论输入是什么最后都转成一份可校验的 JSON 结构。这个设计带来的好处是在真正生成图形之前就能做一次结构校验少了节点、多了孤儿边立刻能发现不必等到图出来后才肉眼排错。输入类型信息来源能抽取出什么代码仓库目录结构、依赖声明、函数调用模块划分、服务边界、调用关系接口文档OpenAPI、gRPC proto、消息契约端点归属、数据模型、上下游依赖对话描述自然语言需求实体、关系、业务分组三种输入最后会汇总到同一个抽象层。这里有个我觉得很聪明的设计它允许不同输入源互相补全。比如代码扫描出来一条调用关系但不确定这个调用属于哪个业务域你可以在对话里补充一句“支付模块就是 PaymentService”它会把这个语义合并到已有模型里而不是重新生成一遍。这在调试大型系统时特别有用。2.2 输入解析层到底怎么工作实际使用中最常见的输入有三种。第一种是代码仓库archify 会扫描模块目录、识别 import/require 关系提取函数和接口调用。第二种是 API 清单比如一份 OpenAPI 文档它能解析出每个端点归属哪个服务、依赖什么模型。第三种是对话描述比如你直接说“帮我画一个订单中心包含支付、库存、物流三个下游”它能从自然语言里提取实体和关系。三种输入最后会汇总到同一个抽象层。这里有个我觉得很聪明的点它允许不同的输入源互相补全。比如代码扫描出来一条调用关系但不知道这个调用属于哪个业务域你可以在对话里补充一句“支付模块就是 PaymentService”它会把这个语义合并到已有模型里而不是重新生成一遍。这在调试大型系统时特别有用。2.3 交互层用了什么渲染策略架构图要做到可交互底层方案目前主流有两种一种是 SVG 加手动管理事件另一种是基于图形引擎维护状态。archify 走的路线接近第二类它维护一张图对象模型渲染层只负责把模型画到画布上用户交互产生的事件再反向改模型。这种数据驱动渲染的方式优势很明显做拖拽移动、折叠展开、节点状态更新时逻辑非常清晰不容易出现“UI 改了但模型没改”的错位。而且还支持“按图反查”——你在图上点中一个节点能直接看到它对应的原始代码位置或者配置项来源。对排查“这个模块是谁引入的”这类问题体验是质的提升。2.4 输出产物能干什么用产物本身是一份自包含的 HTML 文件里面嵌入了图形渲染脚本和透出的 JSON 数据。你可以直接在浏览器打开也可以内嵌到团队 Wiki、语雀、Notion 里因为本质上它就是一个前端组件。更好的一点是这份 JSON 数据不是一次性生成的死数据它可以和运行时的状态对拍代理每执行一轮就更新一次这份 JSON。我自己的做法是把 JSON 放进一个独立仓库由 CI 定时拉取最新代码跑一遍分析有任何架构变化自动提交一次更新。架构图成了仓库的一部分自然就有了版本历史。这不只是图而是一份持续维护的系统索引。3. 把 archify 接进代理管线的完整姿势3.1 安装和注册技能模块按照 GitHub 仓库的推荐路径实操过程大致是这样把项目 clone 到本地安装依赖然后把 skill 目录注册到你的代理框架配置里。如果你用的是 Claude Code 或者兼容 Skill 目录的框架直接把文件夹放到技能目录下重启就生效。如果用自己的 Agent 框架那就把入口写成一个可执行命令让代理在需要时调用。关键一步是给代理加一条“何时使用”的说明。技能模块能不能被正确触发瓶颈往往不在代码而在描述。建议在技能描述里写清楚“当用户询问系统的模块关系、架构、依赖、调用链或者需要生成架构图时使用本工具。”描述越贴近真实用户问法命中率越高。这个细节很多人忽略但它直接影响代理是否会在正确的时机调出这个技能。3.2 一条 prompt 驱动出图的实例我实际测过的一个场景站在一个微服务项目根目录下输入“分析当前项目结构生成一张可交互的架构图要标出每个服务之间的调用关系并且把外部依赖单独分组。”代理先扫了一遍目录结构然后识别出每个服务的入口和端口配置再通过代码里的 API 调用关系把服务间边补全最后输出一个 HTML 交互图。整个过程大概 40 秒生成的图可以直接放进评审文档里。相比手动梳理这个效率差距不是一点半点。后来我试了更复杂的输入让它根据线上日志里的调用链画一张运行时拓扑。它会把日志里的 traceId 聚合提取服务间实际调用次数然后按权重决定边的粗细。这个功能对排查链路瓶颈非常有用超出了我最初对“画架构图”的预期。3.3 和本地模型的组合玩法很多人问技能模块是不是非得用云端的大模型才能跑。实际不是。如果你把输入标准化做好本地模型也能完成大部分抽象建模工作。我的建议是拆成两步先用一个轻量级本地模型做信息抽取把代码和文本转成结构化描述再把结构化描述交给渲染内核生成交互图。这样既保住了数据隐私又绕开了大模型上下文窗口的限制。这也是 archify 这类技能模块比在线白板工具灵活的地方——它的渲染内核是纯本地的数据不需要离开服务器适合企业内部架构比较敏感的场景。我见过有团队直接把分析过程放在内网容器里只有最终生成的 HTML 在评审时外发安全性好得多。3.4 和 ROS、OpenClaw 这类代理框架的联动最近社区里关于 OpenClaw 和 ROS 组合做代理集群的讨论很热这类场景有个共同需求你要在一张图上看到每个代理节点的状态、通信关系、挂载的技能集。archify 在这里可以充当一个可视化视图层把代理集群的运行时信息拉进来画成拓扑图节点可以展开看每个代理当前加载的技能和模型。我这里提供的是思路不一定非要等官方支持。只要你的代理框架能输出一份“节点、关系、状态”的结构化清单archify 就能把它渲染成可交互图。所以重点是让代理框架往外吐数据剩下的交给渲染层。如果你正在做多代理编排这个组合值得一试。4. 实测中容易翻车的几个场景4.1 上下文越长识别越走样我用一个真实项目的代码扫描时遇到一个情况项目有 30 多个模块目录深进出口很多。代理第一次生成的图里把多个内部调用错误归到了外部依赖组里。原因很好理解一次性输入太长模型在抽象建模时的注意力被稀释了后半段的信息理解做得潦草。解决办法是分批喂先让它扫一层目录确认一级节点再逐个子目录深入。这种“先粗后细、逐步补图”的方式出图准确率明显提升。另外一定要让它在建模阶段输出中间 JSON 而不是直接跳到画图。看到 JSON 错了还能改图错了重画代价大得多。4.2 大图上节点重叠根本没法看生成的图一旦超过 80 个节点布局算法就开始吃力节点重叠、边交叉都非常严重。这不是渲染层的 bug而是图布局的经典难题。要解决最有效的做法是分层绘制把架构拆成“系统概览、服务层、模块层”三级视图默认只展示最上层用户点击再展开下一层。所以我在用的时候会尽量控制颗粒度。单张图最好只表达一个主题要么是全链路调用关系要么是单个服务的内部模块。不要指望一张图画完整个公司架构任何交互图工具都扛不住这种需求。graph 布局这件事越克制越好看。4.3 中文标签和字体容易变成豆腐块这个问题很隐蔽但非常常见。HTML 导出后在别人的机器上打开中文节点名可能全部变成方框。原因通常是渲染时用了自定义字体但那台机器没有装。我自己的规避方式是在导出配置里显式指定系统字体栈比如 PingFang SC、Microsoft YaHei、sans-serif 这组然后在生成后检查一遍。另外要注意部分接口字段里如果混入了特殊字符比如引号或尖括号会导致 JSON 解析失败。建议所有从代码里提取的字段名都要做转义处理。这种事不大但踩一次能浪费半天。4.4 动态更新与静态产物的冲突前面提到可以把 JSON 放进 CI 自动更新但真正跑起来会发现一个问题更新是覆盖式的之前手动调整过的布局会被冲掉。如果你在交互图里拖拽过节点调整过分组下一次自动化更新全给你打回原形。这个我目前用的折中方案是把布局信息和结构信息分开存储。布局单独存一份可选配置CI 更新时只更新结构数据布局尽量保留。如果官方后续支持这种分离体验会好得多。这也提醒我凡是自动化生成的产物都要想清楚哪些该自动化哪些该留给人工。5. 用顺手之后的一些进阶玩法5.1 让代理把架构评审变成例行任务我现在每周会让代理自动跑一次全项目的架构扫描输出变更对比图。代码里新增了一个调用、抽出了一个模块、多了一个外部依赖都能在图上直接标出来。评审会上不用再打开十几个文件找差异一张图就能讲清楚“这周架构发生了什么变化”。实现上就是在 CI 里把 archify 的生成逻辑和上周 JSON 做 diff差异部分用高亮标签渲染。这个能力本质还是数据驱动只要 JSON 里带了变更时间戳做增量标识就很简单。更重要的是这种方式让架构评审从“靠记忆”变成了“靠数据”客观很多。5.2 把架构图变成 agent 的共享记忆还有一点我觉得很有潜力就是让架构图反过来成为代理自己的记忆锚点。代理在规划任务时如果先调用一次 archify得到系统当前结构作为上下文再做任务规划回答质量和工具调用准确性都会好很多至少不会出现“调用一个根本不存在的模块”这种低级错误。我最近在代理系统提示里加了一行“复杂任务开始前如果涉及多模块协作先调用 archify 获取当前架构视图。”带来的提升很明显规划阶段的幻觉大幅减少。所谓“让代理看清地图再上路”这相当于给每个代理配了一张实时更新的地图。5.3 从“画架构图”到“画目标状态图”最后说说我觉得 archify 这类技能更大的想象空间。它不只是能画“当前是什么样子”同样能画“目标应该是什么样子”。你给它一段未来的架构设想它能生成一张目标架构图再和当前图并排对比重构路径就一目了然。这个玩法适合做技术规划。季度规划会上把当前架构和目标架构两张可交互图摆在一起业务方和研发看到的是同一份图沟通成本会低很多。谁对理解不一致直接指到图上比任何文字说明都快。我自己最深的感受是架构图这项工作的价值长期被低估了但传统做法也确实低效。archify 最大的贡献是把出图从人工梳理变成了代理能力而且这种能力是可组合、可自动更新的。如果你手头正好有代理编排或系统架构频繁变动的场景不妨把它接进管线试一轮重点观察它生成的中间 JSON 够不够干净——数据模型稳定了后面一切玩法都成立。