1. 为什么要让AI代理去画架构图一个真实得不能再真实的场景先说个我上周遇到的场景。领导临时让我梳理一个老系统的模块关系说第二天汇报要用。我打开代码仓库翻了几十个service文件脑子里一团乱麻——模块之间的依赖关系散落在接口定义、配置文件、SQL脚本里谁调了谁谁依赖谁边界在哪光靠人肉梳理至少得一下午。这种时候我就特别能体会可交互架构图的价值。不是那种画完就死的静态框图而是能缩放、能点击、能按层级展开、能追溯依赖关系的活图。传统画图工具的问题在于你得先在大脑里把系统结构想清楚然后用手去画画的过程本质上是在翻译已经成形的认知。而AI代理如果能直接从代码仓库、配置文件、运行日志里抽取关系再把关系渲染成可交互的架构图等于把读代码—建模型—画图这条链路自动化了我只需要在最后做校验和纠偏。这就是archify这个项目打动我的地方。它在GitHub上的定位很明确不是又一个画图工具而是AI代理的一个技能模块skill module。什么意思简单说它给AI代理装上了一双会画架构图的手代理在分析完代码或架构信息之后可以直接生成可交互的架构图而不是只输出一坨文字描述。对于经常和微服务架构、系统梳理打交道的人来说这类技能模块的价值不在于它本身有多炫而在于它能被塞进现有工作流里成为一个可复用的能力单元。这篇文章就围绕这个东西展开archify到底做了什么、它的技能模块怎么设计、我实际接入的完整过程、以及生成架构图过程中那些画出来能用和画出来能看之间隔着的坑。如果你也是被架构图画到崩溃的开发者、架构师或者运维这篇应该能给你一些实在的参考。2. archify的技能模块设计一次配置、全代理复用的能力封装2.1 什么是技能模块把能力从具体对话里抽出来先说概念。普通的AI对话模式是你给一句指令模型回一段文字。这个模式做一次性问答没问题但放到每周都要画架构图这种高频重复的场景里就显得很笨——每次都要重新把需求讲一遍、把约束条件重申一遍、把输出格式再描述一遍。技能模块要解决的问题就是把这些重复的上下文、输出格式和处理逻辑固化下来变成代理可以随时调用的能力单元。archify干的正是这件事。它不是一个独立的架构图生成服务而是可以被注入到AI代理工作流里的一个技能包。你用Claude、用本地模型跑代理框架需要画架构图的时候代理会加载archify的规则和模板按一套标准流程去产出结果。这就像给一个会写代码的程序员配了一套工程规范他写出来的代码风格、结构、质量都有基本保障而不是每次随性发挥。这种设计的好处非常直观。第一上下文开销大幅降低——你不再需要在prompt里写请用Mermaid格式画一张微服务架构图每个服务画成节点依赖画成箭头分组用子图这种话技能模块里已经内置了这些约定。第二输出稳定可预期——它内置的处理流程和输出模板决定了下限哪怕模型状态波动画出来的图结构也不会跑偏太多。第三可组合——一个代理可以同时挂多个技能模块画架构图和写技术方案是两个独立模块互不干扰按需加载。2.2 archify的处理链路从架构信息到可交互图的四步走那archify具体是怎么干活的根据这个项目的设计逻辑我梳理出它大致的处理链路这部分也是我实际用下来觉得最值得学习的地方。第一步是信息抽取。AI代理接收到的输入可能是代码仓库路径、接口文档、甚至是对话描述。archify要做的是从这些异构输入里抽取出架构要素系统/服务/模块作为节点调用关系、数据流、依赖关系作为边分层和分组信息作为子图边界。这一步的关键在于知道什么该抽、什么不该抽——不是所有的import关系都算架构依赖只有那些能体现系统边界和调用链路的才算。第二步是关系建图。抽取出来的要素会被组织成结构化的数据——图模型。每个节点有类型服务/数据库/网关/消息队列、名称、职责描述每条边有方向、类型同步调用/异步事件/数据依赖。这一步做得好不好直接决定后面图的语义是否准确。实际实现里这个图模型往往对应着一种中间表示IR和具体渲染格式解耦。第三步是渲染表达。archify把图模型映射成可交互的架构图。这里有两个层次的理解一是底层用什么图引擎渲染——这个项目选择的方向是Mermaid这类文本即图的方案好处是文本可版本化、可diff、AI模型天生擅长生成文本二是交互能力怎么来——通过节点点击展开子架构、按分组折叠、悬停显示依赖详情这类机制实现。第四步是结果校验。生成完之后代理应该有能力自查节点是否重复边方向是否正确有没有孤立的节点这一步看起来简单但我实测下来发现很多AI生成架构图翻车就翻在这里——它能画但画得对不对需要一套校验逻辑兜底。这四步链路里最值得借鉴的是中间表示这个思路。它不是直接把你说的话翻译成图而是先抽成结构化数据再从数据渲染成图。这样带来的好处是换渲染引擎不影响数据模型人可以在渲染前审查和修改中间结果不同的输出格式Mermaid、PlantUML、SVG只是同一份数据的不同投影。这个设计在线下画图时体会不深一旦你接入AI代理并且想要人机协同——AI构图、人修正——中间表示就是那个协同的接口。3. 实操把archify接入AI代理并在真实项目里跑通3.1 环境准备代理框架、模型选择、技能注册我实际实验的时候用的是本地的代理框架配合一个支持函数调用的模型。之所以强调支持函数调用是因为技能模块的加载机制本质上就是让模型在合适的时机决定调用archify这个技能而不是在每一轮对话里都强制加载。具体配置上按常见实践补全一下我的步骤给想复现的人一个参照代理框架选型支持插件/技能机制的都可以关键是能把archify的定义文件挂到技能目录里并且能在系统提示词里声明这个技能的存在和触发条件。模型选择支持工具调用或函数调用的模型体验好很多。纯对话模型也能用但需要在prompt里反复强调输出格式效率低不少。技能文件准备archify以技能模块形式提供本质上是把指令模板、输出规范、示例、边界说明打包在一起。把技能目录挂载到代理框架的配置里让代理在需要时能读到archify的处理逻辑。这里有一个容易被忽视的细节# 让代理知道什么时候该用技能模块光挂载还不够还得让代理理解触发边界。我在系统提示词里补充了类似这样的声明当用户要求梳理系统结构、生成架构图、分析模块依赖关系时加载archify技能并按标准流程处理。没有这一步代理很容易把所有问题都当成聊聊天就行哪怕你挂了技能它也想不起来用。3.2 让代理画一张微服务架构图输入与产出的边界配置好之后我拿手头一个模拟的微服务项目做了测试。项目里有网关、订单服务、用户服务、支付服务、库存服务、消息队列、数据库等组件组件之间的依赖关系基本符合真实微服务项目的模式。我给的提示词很简单梳理这个项目的微服务架构画出架构图。然后观察代理的行为。有意思的地方来了。代理没有直接画图而是先做了一轮信息确认——它问我是否包含外部依赖如第三方支付网关是否要把数据库按服务拆开画。我当时觉得有点啰嗦但后来发现这个确认动作极其关键。架构图不同于一般的示意图它是有信息密度的如果边界条件不清楚生成的图要么缺东西要么多东西回头改的成本反而更高。确认完之后代理生成的输出大致包含三部分架构说明文本、Mermaid格式的架构图代码、以及交互说明哪些节点可点击展开、哪些分组可折叠。Mermaid代码的层级结构很清楚外层用flowchart主节点是服务服务内部用subgraph聚合依赖关系用带方向的箭头标注消息队列作为独立节点放在中间承接异步通信。这一步跑通之后我最大的感受是代理画架构图这件事的难点不在画而在理解系统。画图本身是纯粹的执行哪怕一个不太好的模型只要给定了准确的图模型数据也能渲染出像模像样的图。难的是模型从代码仓库或者描述文本里准确抽取结构信息、判断边界、识别真伪依赖。archify这类技能模块的意义就是把理解系统这部分的动作规范化用一系列约束和模板减小模型自由发挥的空间。3.3 交互式架构图的落地姿势静态生成动态展开说完基础跑通聊点更进阶的可交互架构图和静态图最大的区别在哪我用下来觉得核心在于分层展示和按需展开。一张图如果试图展示系统的所有细节结果就是一张什么都看不清的蜘蛛网。可交互架构图的处理方式是默认展示顶层视图——系统分为几大块、关键链路是什么用户点击某一层节点时才展开该模块的内部结构——子模块、关键类、依赖关系、数据流向。archify在这个方向上的实现是通过将架构信息组织成多级结构顶层是系统上下文中间层是服务/模块视图底层是组件/接口视图。每次渲染只画当前层级交互动作触发下一层数据的加载和渲染。底层数据的传递格式跟前面说的中间表示是一致的所以展开操作本质上就是拿同一个图数据模型换了渲染视角。我把这个机制用在了给新同事做项目导览的场景。先整体跑系统架构图新同事点击订单服务节点能立刻看到订单服务内部的领域模块、对外依赖、消息Topic。比发一份几十页的架构文档好使太多——文档是死的架构图是活的。4. 让AI画出来的架构图能看的细节布局、层级、交互的坑我和archify磨合的过程中发现画得出来和画得好看、画得能用之间还有相当长一段路。这段路不是靠模型能力就能cover的需要一些工程手段来兜底。4.1 布局算法为什么AI画图经常挤成一团先说我遇到的最常见的问题AI生成的Mermaid架构图节点一多就挤成一团。十几个服务、十几条箭头渲染出来线段交叉严重、节点重叠看不清楚。这不是模型笨而是Mermaid这类文本工具的布局算法本来就不是万能的尤其面对大量带子图的复杂结构时自动布局往往不如手动拖拽来的合理。我尝试的解决方案是分层次渲染——不要试图在一张图里展示所有东西。顶层只画服务和主要依赖每个服务的内部细节单独生成子图通过交互展开。这样每张图的节点控制在10个以内布局清晰度提升非常明显。实测下来10个节点以上的图无论谁画的可读性都急剧下降控制在6-8个节点再加1-2层子图是信息量和可读性的最佳平衡点。4.2 命名和分组架构图的语义质量取决于这两件事第二个坑是命名不规范导致语义混乱。模型有时候会根据代码文件名硬推节点名比如把UserController画成UserController把UserService画成UserService但架构图要呈现的应该是用户接口层用户业务逻辑这种有架构含义的分组。停留在类名层面的架构图本质上是类图的变体不是架构图。解决思路是在技能的指令模板里显式要求节点按架构角色分类命名而不是照搬代码文件。我给代理添加了一条处理规则——先识别每个组件在架构中的角色入口/业务/存储/基础设施再按照角色_领域的格式统一命名。这样图上的每个节点都自带语义读者不需要靠猜。分组也同理。微服务架构图如果没有跨服务的业务边界如订单域、用户域、支付域各服务就是一堆孤立的方块和箭头。archify的处理方式是支持按域的维度用子图分组把属于同一业务域的服务聚合在一起跨域依赖用清晰的长箭头体现。我在实际项目中把订单域包含订单服务、订单状态机、订单事件处理器划到一个子图里整体的信息骨架感一下就出来了。4.3 交互细节点击、悬停、折叠的信息承载交互方面有几个细节我觉得值得特别提一下。一是悬停展示依赖详情。架构图上两个服务之间的箭头如果只标调用信息量太稀薄。合理的交互是鼠标悬停时展示调用协议、接口路径、同步还是异步、大致调用频率。这些信息应该在你生成中间表示的时候就算好存好渲染只是把隐藏信息调出来。二是折叠分组。顶层视图里一个业务域可能只需要一个节点展开后才显示内部服务。这个机制静态渲染也能模拟但做成交互式后体验完全不同。我在给团队做评审演示的时候先展示系统全貌再逐步展开关键域过程和讲故事一样比对着干巴巴的PPT强太多。三是状态保留。当用户展开某个节点、缩放了视图之后刷新页面能不能记住当前状态这个需求看起来小但做交互式架构图的时候极其影响体验。我在实际试用的过程中发现至少应该把哪些节点处于展开状态存到URL参数或者本地存储里不然每次刷新都要重新点开很消耗耐心。4.4 一个绕不开的话题AI画图的准确性问题最后必须说实话AI生成的架构图准确性是需要人工兜底的。尤其从代码仓库抽取信息的时候模型可能把测试代码当成生产代码、把间接依赖当成直接依赖、把接口定义和实际实现搞混。我的应对策略是让AI生成的架构图和实际代码之间保留可溯源的关系——每个节点都带上证据来源哪个文件、哪段配置、哪条扫描日志人做校验的时候可以直接追溯到源头而不是对着图猜它画得对不对。这句话放出来可能有人觉得AI画图不靠谱但我的观点是靠谱是流程设计出来的不是模型天生的。人工画图准确率高是因为人脑在画的过程中天然做了信息校验。AI画图如果跳过校验环节准确率当然不行。但如果你在技能模块里加入每个节点附证据来源这个约束人为校验的成本就会低很多整体效率一定比纯人工更高。5. 从archify延伸出去的三个通用经验5.1 技能模块AI代理时代的能力分发单元archify让我第一次切身体会到技能模块这个概念的威力。倒不是说它本身多复杂而是它示范了一种AI能力组织方式的转变——从对话式的一次性能力到可复用的模块化能力。类比一下没有技能模块的AI代理像一个什么都会一点但什么都不精的实习生你说一句他动一下你不说他就不做说清楚了他也未必按规范来。挂了archify这类技能模块之后相当于给这个实习生发了一本操作手册和一套模板同样的活他干得又快又稳。这个经验可以迁移到任何领域。我自己就把一些技术方案写作的规范章节结构、篇幅控制、代码风格封装成了另一个技能模块挂到代理的工作流里。效果比在系统提示词里长篇大论写要求好得多——模块是聚焦的、按需触发的不会污染其他任务的上下文。5.2 文本即图理念为什么架构图应该被版本管理archify选择用Mermaid这类文本格式作为架构图的表达底层这部分是基于该项目设计倾向的实际推断这个决策我认为非常有远见。架构图本质上是系统设计的一种文档形式那它就理应跟代码一样被版本管理。传统画图工具存的是二进制文件或专有格式没法diff、没法code review、没法在合并请求里看到这次重构把订单和支付之间的依赖从双向改成了单向。文本化的架构图天然具备这些优势——任何改动都是一段可审查的diff任何节点新增依赖都是可追溯到具体提交的。我在自己的项目里已经开始实践架构图即代码。CI里跑一步检查每次有涉及服务间依赖的代码变更时自动触发架构图重生成然后把diff贴到合并请求的评论里。谁动了依赖关系一目了然。这个流程搭配archify这类文本生成工具落地成本比想象中低很多。5.3 人机协同的舒服姿势AI构图、人校验、工具渲染最后一层经验是关于人和AI的分工的。我自己最初的期待可能是全自动生成完美的架构图抱着这个期待去用落差感必然很大。但换个角度想最舒服的形态其实是AI负责脏活累活人负责判断和决策。具体到架构图这个场景我可以允许AI抽取信息、建图、出初稿这个过程能替我省掉70%的机械劳动但我保留最终的修改权——哪里有错改哪里哪个模块的边界该调整就调整哪条依赖其实不存在就删掉。人机不是竞争关系而是流水线上的两道工序。这也是我强烈建议把archify这类技能模块定位成助手而不是取代者的原因。真正天天和复杂系统打交道的人都知道架构认知不是画一次图就能完成的它是在持续的梳理、修正、反思中迭代出来的。工具能加快这个循环但替代不了这个循环本身。我现在的日常已经离不开这套工作流了——从代码库抽取信息交给代理初稿架构图几分钟出来我花十几分钟做校验和修正产出放进文档或Wiki供团队协作。效率比之前高了一个量级而且每次改完图我对系统的理解也比上一次更深一层。如果你也困在梳理老系统、给新项目画设计图、给领导做汇报这些事情上花半天时间啃一下archify这类项目找个代理框架把它接进去大概率会打开一扇新窗户。