前阵子在GitHub上刷到一个叫 archify 的项目标题写得很直白AI 代理自动生成可交互架构图的技能模块。乍一看我以为又是那种套层壳的 Mermaid 玩具仔细翻了项目说明和示例输出之后发现它确实把让 AI 代理画架构图这件事做成了一套可复用的能力包而不是一句简单的帮我画个架构图提示词。这篇文章就聊聊 archify 到底在做什么、它的工作链路怎么拆、我在本地把它接入 AI 代理时踩过的坑以及这东西适合什么人用。如果你属于下面几类人这篇应该对你有用日常要给微服务系统画架构图、画完又懒得维护的人在折腾 AI 代理、想让代理自动产出交付物的人以及单纯对技能模块Skill这种新分发形态好奇的人。我会从工具形态、核心链路、实际接入三个角度展开最后给一些我自己的判断。1. 它解决的其实是个老问题架构图为什么这么难画1.1 画图的痛从来不在画这个动作上我自己画系统架构图画了快十年最深的感受是打开画图工具、拖几个方框、连几条线这些操作本身五分钟就能学会。真正让人头疼的是画之前的信息收集和结构整理。你要画一张微服务架构图得先搞清楚系统里有哪些服务、服务之间谁调谁、数据走 MySQL 还是 Kafka、网关在哪一层、哪些模块属于基础设施。这些信息分散在代码仓库、文档、配置中心、甚至老同事的脑子里。传统流程里画图的人要先做一遍架构梳理再把梳理结果手工落成图形。图一多维护成本就上来了——某次重构加了一个服务忘了更新图几天后这张图就成了误导人的废纸。archify 想切的就是这个环节。它不是一个绘图软件而是一个让 AI 代理代替你完成架构梳理到图形产出全流程的模块。你只需要给代理一个入口一段系统描述、一份代码仓库、或者一句把订单系统架构画出来它负责理解、建模最后吐出一张能用的架构图。1.2 技能模块这个形态比普通提示词重但也比普通提示词可靠和很多人的第一反应不同archify 并不是简单地把一段画架构图提示词丢给 ChatGPT 就行。它采用的是最近 Agent 生态里越来越流行的 Skills技能形态把一项能力的完整定义打包成一个目录里面包含提示词协议、处理脚本、模板文件、示例数据AI 代理在遇到相关任务时可以自动加载这个技能包。你可以把技能模块理解成给 AI 代理的一份岗位说明书 工具箱。普通提示词只告诉模型你要做什么技能模块还包含了你要按什么流程做中间产物长什么样最终输出用什么模板渲染。这种形态的优点是协议固定每次生成架构图的流程是统一的不会这次先画图后分析、下次先分析后画图工具可复用渲染、转换脚本写在技能包里模型直接调用不用每次临场发挥结果可预期因为输入输出中间态都被定义了最终产出质量比自由发挥稳定得多。这正是 archify 能被叫作模块而不是一段提示词的原因。它把画架构图这项能力工程化了。1.3 它生成的不是静态截图而是一张能用起来的图archify 的输出有一个很关键的特点可交互。不是一张 PNG 图片而是一个自包含的 HTML/SVG 页面支持缩放、拖拽、点击节点查看详情、按层级展开折叠。这个差异很重要。一张静态架构图信息量一大就变成一碗面条——几十个节点互相连线根本看不清。可交互图把这个问题拆成了两层全局视图只显示核心模块和主要依赖想看某个服务的细节点一下就能下钻图里节点太多可以先折叠次要模块等需要时再展开。从画图给人看变成了做图给人用。2. 核心链路拆解从一句帮我画系统架构到可交互页面我用下来觉得 archify 的工作链路可以拆成三个环节下面逐个说。2.1 第一步把系统理解成节点和边所有架构图的底层本质上都是图论里的节点和边。archify 给代理的第一项任务是做信息抽取面对一段描述或一个代码仓库代理需要识别出架构要素并归类为节点、关系、分组三种基本元素。节点服务、数据库、网关、消息队列、前端应用等具体组件关系调用、依赖、数据流、消息订阅等连接关系分组把节点按业务域、部署环境、团队归属等维度聚合成逻辑分组。这一步是决定整张图质量的关键。模型如果连这是个服务还是个数据库都分不清后面渲染得再漂亮也没用。我在实际测试中发现archify 的提示词协议里会强制代理先输出组件清单再进入下一步这就避免了模型跳过分析直接画图导致的胡编乱造。2.2 第二步用结构化数据模型作为中间桥梁信息抽取完成之后代理不是直接去画图而是把这些要素组织成一份结构化数据。你可以把它理解成一份图的源代码——用 JSON 描述每个节点的 ID、名称、类型、所属分组以及每条边的起点、终点、关系类型。{ nodes: [ { id: gateway, label: API Gateway, group: infra, meta: { tech: Kong } }, { id: order-service, label: Order Service, group: business, meta: { tech: Spring Boot } }, { id: order-db, label: Order DB, group: data, meta: { tech: PostgreSQL } } ], edges: [ { source: gateway, target: order-service, relation: http }, { source: order-service, target: order-db, relation: jdbc } ], groups: [ { id: infra, label: Infrastructure }, { id: business, label: Business Services }, { id: data, label: Data Stores } ] }这个中间层的作用是把模型的理解和页面的渲染解耦。模型不需要知道 SVG 怎么画曲线、力导向布局怎么计算它只需要把架构事实表达准确渲染部分由技能包里的脚本和模板负责。这种分层设计和软件工程里的数据与展示分离是一个道理好处是任何一环出了问题都可以单独修复不会因为模型输出格式不规范就整体崩掉。2.3 第三步布局与渲染把数据变成一张人能看懂的图拿到结构化数据之后要解决的是布局问题。这里有几个常见方案力导向布局节点之间有类似物理弹簧的力互相拉扯后自然稳定适合展示复杂的服务依赖网络但节点多了容易乱成一团分层布局按调用层级从上到下排列网关在最上面数据库在最下面适合展示清晰的调用链径向布局以一个核心节点为圆心其他节点环绕排布适合展示中心辐射型的架构。archify 在这块的做法通常是让代理根据图的规模自动选择布局策略再交给模板里的渲染脚本执行。技术实现上我推测不复杂生成自包含的 HTML 文件内嵌 SVG 和少量 JavaScript不需要后端服务双击就能在浏览器里打开。这也是它作为技能模块的价值——渲染脚本是写死在技能包里的固定工具模型不需要会写前端也能交付一个像样的前端产物。2.4 交互能力从哪来交互其实就是在前端脚本里做三件事监听鼠标事件、修改 SVG 元素的属性、动态更新详情面板。点一下节点展开详情滚轮缩放改变 viewBox 的尺寸拖拽节点更新坐标。技术门槛不高难的是把这些交互和架构图的信息结构结合起来——也就是要让交互本身有意义而不是为了动而动。archify 做得比较聪明的一点是它的交互围绕架构理解来设计默认只展示分组级别的视图点开分组才展开内部节点。这相当于给读者做了一次信息降噪让一张原本几十个节点的复杂图在初始状态下只显示七八个分组需要细节时再逐步下钻。这个思路非常贴近真实架构评审的场景先讲全局再讲局部。3. 实操把一个技能包接入你的 AI 代理3.1 典型的技能包目录结构如果你打算在本地复现 archify 的用法首先要有技能包的组织概念。一个标准技能模块通常长这样archify/ ├── SKILL.md # 技能说明何时使用、主协议、处理流程 ├── scripts/ │ ├── extract.py # 信息抽取辅助脚本 │ └── render.py # 从JSON渲染出HTML/SVG ├── templates/ │ ├── default.html # 交互页面模板 │ └── styles.css # 样式 └── examples/ └── sample.json # 一个标准的架构数据示例SKILL.md 是整个技能包的核心它负责告诉模型三件事第一什么情况下应该激活这个技能用户提到架构图、系统设计、服务依赖的时候第二处理任务的标准流程先收集信息、再抽取组件、再建模、最后渲染第三每个环节的输出格式要求。3.2 核心协议要约束住模型的自由发挥我接入的时候踩过最大的坑是第一次没有给模型足够的流程约束结果它跳过组件清单直接出图画出来的架构图缺了三分之一的服务。后来我把技能包里的流程定义改成明确的分步协议Step 1: 如果用户没有提供系统描述先用问答或代码检索收集信息; Step 2: 输出组件清单结构化列表, 不通过则不要进入下一步; Step 3: 将组件清单转换为架构数据模型JSON; Step 4: 调用渲染脚本生成可交互 HTML 并返回文件路径; Step 5: 用自然语言总结图里的关键依赖关系。加了这套协议之后生成的图质量稳定了很多。核心原因在于大模型是概率输出你不在流程层面给它设卡它就倾向于怎么简单怎么来。技能模块的作用之一就是用协议把模型发挥控制在一个可靠的轨道上。3.3 线上模型与本地模型两种接入路径接入方式取决于你用的是线上大模型还是本地部署的模型加代理框架。线上模型这条路最简单现在不少 Agent 平台支持自定义技能功能你只要把 archify 的技能目录传上去然后在对话里说帮我把系统架构图生出来代理会自动调用技能包完成全流程。这个过程你不需要写任何代码属于配置即用。本地模型这条路稍微麻烦一点但可控性更强。核心思路是把 archify 作为 Agent 框架里的一个工具Tool来注册代理框架负责接收用户意图、调用大模型做决策当模型判断用户想生成架构图时就触发 archify 技能对应的脚本脚本执行完把生成的 HTML 路径返回给模型再由模型用自然语言向用户交付。这种情况下技能模块的本质就是一组让模型可以调用的外部工具加提示词约束。不管走哪条路我的建议都是先跑通一个最小样例再上真实系统。最小样例我用的是一个只有三个服务的小型 demo网关、订单服务、数据库。确认整条链路跑通之后再去处理几十个服务的真实系统否则一旦出问题你很难判断是模型理解错了还是渲染脚本的 bug。3.4 一个完整的输入输出效果示例我实际跑过的一个例子是让代理画一下客户端的订单创建链路图。输入就这么一句话代理自己补了问题来收集信息订单从哪个入口进来、经过哪些服务、数据落到哪里然后给我返回了一个 HTML 文件。打开页面之后第一屏显示的是三个分组入口层、业务层、数据层。点击业务层里面展开订单服务、库存服务、支付服务三个节点节点之间的线条标注了调用关系。点一下订单服务右侧面板弹出它的详细信息技术栈 Spring Boot、负责的接口列表、下游依赖了哪些服务。整个过程不需要任何绘图操作全部由对话驱动。这个体验确实是传统画图流程没法比的。传统方式你做一张同等信息量的图至少要半天代理来做从对话到拿到文件几分钟。4. 我实际用下来最有价值的场景和最容易翻车的地方4.1 微服务与存量系统架构最能出效果的地方archify 最亮眼的场景是帮团队梳理存量微服务架构。很多团队的系统跑了三五年文档早就跟代码脱节了真正知道架构全貌的可能只有一两个老员工。这种时候让代理扫描代码仓库、抽取服务间的调用关系快速产出一张当前真实架构图价值非常大。你可能会有疑虑代码仓库那么大代理自己能搞定吗实测下来关键在于给代理设定合适的扫描范围。一次性丢一整个几十万行代码的 monorepo 进去模型很容易遗漏重要模块。我的做法是分层喂先让它顺着服务入口和配置文件识别服务清单再逐层分析服务内部依赖最后汇总成架构数据模型。这个过程可以在技能包里定义成固定流程让每次处理都按同一套节奏来。4.2 逆向一个代码仓库效果取决于仓库质量和直接给描述相比让代理从代码仓库逆向出图的成功率要低一些而且高度依赖仓库本身的质量。如果项目依赖关系清晰、目录结构规范、服务边界明显生成出来的图可用性很高但如果是个历史遗留的大泥球项目服务之间互相引用依赖关系绕成一团代理产出的图基本没法看。这里我试过的一个有效缓解办法在提示词里要求代理出图之前先标记不确定的依赖关系并把它们单独列在图的备注区而不是直接画成线。这样图的主干信息是可信的不确定的部分留给人工确认。这也算是人机协作里一个很有用的原则——让 AI 把它不确定的地方显式暴露给你而不是假装它什么都知道。4.3 四类典型翻车场景用了一段时间我整理了几类比较典型的翻车情况供你参考翻车表现根本原因处理方式服务缺失图里少了一半节点信息收集不完整模型跳过了分析和确认阶段强化流程协议组件清单未确认前禁止出图节点关系完全错乱模型把无直接调用的服务连了线要求标记确定性等级不确定的边不画输出格式不稳定模型偶尔输出不符合数据模型的 JSON添加校验脚本格式错误时自动让模型重试大图渲染卡顿一次性渲染了上百个节点默认折叠到分组层级按需展开限制单屏节点数第一条是最常见的也是我在 3.2 里专门把流程协议拎出来的原因。技能模块的价值不在于让模型一次就做对而在于让模型在流程的约束下有纠错重来的机会。4.4 和 Mermaid 这类静态方案怎么取舍很多人看到架构图自动生成第一反应是 Mermaid 就够了。这里我需要帮大家理清楚 archify 这类交互式方案和 Mermaid 的边界对比维度Mermaidarchify 这类交互式方案产物形态静态图PNG/SVG代码定义自包含 HTML可交互上手门槛语法简单随处可用需要配置技能包依赖 AI 代理表达能力适合中小规模、结构清晰的图适合大规模、需要分层的复杂图信息承载节点多了就乱分组折叠 下钻承载量更大使用前提人先想清楚再画AI 代理帮你做信息抽取与建模我的判断是这两者不是替代关系。快速画一张简单的流程图、时序图Mermaid 仍然是最省事的方案但当你要表达的是一个几十个服务的系统架构需要分层、下钻、动态展示时交互式架构图的优势就很明显了。archify 不是要取代你画图而是要接管从架构信息到图形表达这一整条链路。5. 我对 archify 这类技能模块的判断5.1 它真正改变的是画图这件事的工作流起点过去画架构图起点是你的脑子里先有一个对系统的理解然后把它外化成图。archify 这类工具把起点往前推了理解系统的任务也交给模型人只需要提供入口一句话、一个仓库、一份文档剩下的抽取、建模、渲染全部自动完成。这让架构图的成本结构发生了根本变化。以前改一张图你得重新梳理变更点、手动拖节点、调布局半小时没了现在只需要让代理重新扫一遍相关代码或描述新图几秒就出来。当生成成本趋近于零你就会有动力频繁地更新架构图让它始终跟随代码的现实。这才是它最大的价值——让架构图从一次性交付物变成活文档。5.2 顺着这个思路可以继续扩展哪些玩法我自己在用的基础上琢磨出了几个可以延伸的方向一是结合 C4 模型做分层输出。C4 模型把架构分成 Context、Container、Component、Code 四个层级正好匹配 archify 的分组折叠能力——一套数据模型切换四个层级视图从系统大盘一路下钻到代码级别。二是把架构图和架构决策记录ADR绑定。代理生成图的同时把图里的关键依赖关系反查对应的 ADR 文档节点点击详情里直接显示为什么会有这条调用的背景资料。三是和文档生成技能联动。代理先输出架构图再基于同一份数据模型生成架构说明文档图和文天然保持一致不会出现图改了文档没改的割裂问题。四是结合定时任务做架构巡检。定期让代理扫描代码仓库对比上一版架构数据模型如果有新增的服务或依赖自动生成一张架构变更图相当于给系统做体检。5.3 适合谁用不适合谁用最后说点直接的。如果你只是偶尔画一张简单的架构示意图那 archify 对你是杀鸡用牛刀Mermaid 或者 draw.io 就够了。如果你已经是在做 AI 代理相关项目或者你需要频繁维护一套复杂系统的架构图那 archify 这种技能模块的思路值得你投入时间研究。我自己实际用下来的体会是这类工具最大的门槛不在技术而在你对AI 代理可以做架构梳理这件事的接受度。一开始我总怀疑模型会不会漏掉关键服务后来用流程协议约束了几次、对产出做了几轮校验逐步建立起了信任。现在我的习惯是复杂系统先让代理出第一版图我对照代码做补充修正而不是从零开始画。人负责判断和把关机器负责繁琐的信息整理和渲染这个分工对我来说是当前最舒服的协作状态。