Archify：AI代理自动生成可交互微服务架构图的技能模块实战

1. 这个项目到底在解决什么问题画架构图这件事是时候换个思路了做后端开发、系统设计、或者带团队做技术评审的朋友应该都有过这种经历方案文档写好了核心模块列清楚了结果要画一张架构图的时候整个人就卡住了。不是不知道画什么是画的过程太折磨人——draw.io 里拖拖拽拽大半天框和线的对齐比写代码费劲PlantUML 写起来快但画完是张死图没有交互没有层级展开评审会上别人问“这个服务下游挂了会影响什么”你只能指着静态箭头干讲。我是在翻 GitHub 今日热门仓库的时候看到 archify 的项目标题写得很直白——AI 代理自动生成可交互架构图的技能模块。市面上 AI 画架构图的工具其实已经不少了大部分走的是“你描述、我出图”的路线本质是把提示词翻译成一张静态架构图。而 archify 的切入点不太一样它是把“生成架构图的能力”做成了一个可被 AI 代理调用的技能模块而且产出的不是 png是带交互能力的架构图。什么意思呢就是你不再需要自己在画布上排版布局也不需要专门学习某一种图表 DSL 语法你只需要向 AI 描述清楚系统长什么样它替你完成从“文本描述”到“结构化的架构数据”再到“可交互可视化视图”的整个过程。这个定位让它的适用面一下子变宽了你在设计微服务架构的时候可以用它快速出一版结构图做评审你在带新人的时候可以让它把现有项目的依赖关系生成一张可展开的交互图你甚至可以在技术汇报前让它把一套复杂系统浓缩成一张汇报级别的架构视图。这篇文章我就基于我实际跑的流程把它的工作逻辑、实操过程、以及我踩过的一些坑完整拆出来,给想玩一玩这个项目的朋友一份可参考的路线。2. 技能模块的内在逻辑拆解一条“自然语言到可交互架构图”的流水线先说一个很多人忽略的点——标题里的“技能模块”这三个字其实信息量很大。正常情况下你用大多数 AI 画图工具是从外部调用一个网站的接口把提示词发过去然后拿回一张图。但在 archify 这种设计范式下“生成架构图”变成了 AI 代理内置的一项能力相当于给代理装了一个工具插件。它不是一个独立的在线服务而是注入了技能定义、结构化输出规范和渲染器之后让 AI 在你自己的环境内完成从理解系统到产出图谱的全过程。这种设计的好处是你不受制于某一家的模型也不受制于固定 UI你甚至可以把它整合进现有工作流里比如在代码仓库里跑一个脚本让 AI 自动读代码结构然后生成架构图。2.1 它是怎么“听懂”架构描述的整个流水线里最难的一步其实是第一跳从自然语言里提取出架构要素。假设你告诉 AI“我们有个订单服务依赖库存服务和用户服务消息队列在中间做解耦数据存在 MySQL 里”模型需要做的事情是拆出这个句子里的实体和关系。我在实际使用中的感受是archify 的技能模块在提示词设计上下了不少功夫。它会把架构描述拆成几类核心要素——节点服务名、组件名、关系依赖方向、调用方式、层级分组边界、属性信息技术栈、协议类型然后要求模型按一个半结构化的格式输出。所谓半结构化就是让模型在自由文本和严格 Schema 之间取一个平衡点它不需要像 JSON Schema 那样总是懂得语法合法性但它要求输出的结构是稳定的、键名是一致的。比如同样是说“订单服务调用库存服务”不同的输出质量差别很大。普通模型可能把它写进一大段描述里archify 则会把模型往“源节点、目标节点、关系类型”这个三角结构上去引导。这一步做扎实了后续所有渲染逻辑才有数据基础。2.2 从“画框”到“生成”的关键一跳传统画图工具里你要自己决定一个服务放在哪个位置、箭头怎么拐弯、分组边界怎么圈。这种布局工作对 AI 来说其实不友好。archify 的做法是把布局逻辑从 AI 的任务里剥离掉——你不再让 AI 去“画”图而是让它去“生成图的数据结构”渲染的活儿交给前端渲染器来处理。这个设计的精妙之处在于AI 擅长的是理解语义和抽取关系而不是计算坐标。你要让模型输出一张完整画布它大概率会在排版上翻车但你让它输出“有哪些节点、节点之间什么关系、哪些节点属于同一个分组、关键路径是什么”它基本不会出错。坐标和布局是确定性逻辑交给渲染器去算既稳定又灵活。打个比方这就跟前端的 MVVM 思路差不多。传统做法是“你告诉 UI 控件往哪放”AI 画图工具的做法是“你直接用指令操作画布”而 archify 走的是声明式路线——你只描述“有什么、什么关系”图形怎么呈现是渲染层自动推导的。2.3 可交互性从哪里来这是 archify 和普通 AI 架构图工具拉开差距的核心点。传统的 AI 画图工具给你返回一张图片意味着信息是扁平的、不可展开的。而 archify 生成的是带交互能力的视图意味着架构数据是活的。它能做的交互包括但不限于缩放和平移看大图不费眼、节点聚焦点一个服务只看它连了谁、层级折叠收起某个分组下面的细节保留整体结构。这些交互能力本质上是因为渲染层读取了结构化数据而不是读一个渲染好的像素图。数据在交互就在。这一点对做微服务架构的人特别有用。微服务之间依赖关系几十条甚至上百条静态图看着像一团乱麻但如果你能把“公共服务”折叠起来只显示核心链路图一下就清爽了。技术评审的时候这种交互能力不是锦上添花而是刚需。3. 本地跑通 archify 的完整实操流程从拉代码到生成第一张交互架构图官网文档写得比较简洁我第一次跑的时候就卡在环境依赖上后面翻源码才搞明白。这里我把完整的踩坑过程整理出来按步骤走基本能一次跑通。3.1 环境准备几个容易忽略的依赖项先明确一下基础环境要求。项目基于 Python 3 开发前端渲染部分依赖 Node.js 相关的构建工具所以这两个运行时都需要提前装好。我用的是 Python 3.10 加 Node.js 18兼容性没问题。依赖项里有几个比较容易忽略的点我列一下AI API 的 Keyarchify 需要调用大模型接口来解析你的架构描述。它默认兼容 OpenAI 格式的 API也就是说如果你用本地跑的模型或者第三方兼容 OpenAI 协议的网关也可以通过改环境变量来对接。这是它比较开放的一点不绑定某一家。Graphviz这个不是必需的但如果你想让输出结果里有额外的布局计算能力或者想导出部分固定格式的图建议提前装好。apt install graphviz或者brew install graphviz都能搞定。前端渲染依赖渲染器和交互逻辑跑在 Web 环境里需要先构建前端资源。我之前就是漏了这一步结果后端 API 起来了浏览器打开空白页。我整理了一份准备清单方便对照项目版本/命令备注Python3.10建议用虚拟环境Node.js18构建前端资源需要API KeyOpenAI 兼容格式设成环境变量Graphviz可选部分布局功能需要Git最新稳定版拉取仓库代码3.2 安装与构建我踩的第一个坑安装过程本身不复杂clone 仓库之后装 Python 依赖就行。但这里有一个非常关键的细节前端资源必须单独构建。我自己第一次跑的时候只装了 Python 依赖就急着启动服务本地倒是启动了端口也监听了但浏览器访问的时候页面一片空白控制台报了一大堆静态资源 404。翻了一下项目结构才发现它把前端构建产物放在了后端服务的静态资源目录里而仓库里不包含预构建产物必须手动构建一次。操作流程是这样的# 1. 克隆仓库 git clone https://github.com/shihabal3amri/archify.git cd archify # 2. 创建虚拟环境并安装 Python 依赖 python -m venv .venv source .venv/bin/activate pip install -r requirements.txt # 3. 安装前端依赖并构建 cd frontend npm install npm run build cd .. # 4. 配置 API Key 环境变量 export OPENAI_API_KEY你的API Key # 5. 启动服务 python -m archify.server这个顺序很重要亲测有效。如果你构建完前端再启动服务本地访问http://localhost:8000就能看到界面了。3.3 用一句描述生成第一张架构图服务跑起来之后界面是一个输入框你直接描述系统架构就行。我实际测的时候给了一段比较典型的微服务场景描述我们有一个用户服务负责用户注册和登录。订单服务依赖用户服务来校验用户状态。商品服务和订单服务之间通过消息队列异步交互。所有的数据都存储在同一个 MySQL 实例里分库分表。有一个 API 网关统一接收外部请求转发到用户服务和订单服务。提交之后AI 会先解析这段描述然后返回一个结构化的架构数据模型。这一步如果 API 响应正常几秒种后画布上就会渲染出带交互的架构图用户服务、订单服务、商品服务、API 网关、MySQL 都变成了独立的节点消息队列作为中间节点连接了订单服务和商品服务箭头的方向清楚地标出了依赖调用的关系。我第一次生成完最大的感受是它没有把“消息队列”理解成两个服务之间的普通连线而是作为独立节点插进了链路里。这一点对系统设计来说非常重要因为消息中间件在架构里本身就是独立组件而不是连线的附属品。模型对架构语义的理解明显是做过针对性优化的。4. 生成结果的实际使用从个人画图工具到团队协作的转变跑通了基本流程之后我开始把注意力放在一个更实际的问题上这张图生成出来之后除了好看还能干什么我实际用了一段时间发现它的价值远不止“替代手动画图”这么简单。4.1 交互操作的实际体验折叠、聚焦与路径高亮前面提到 archify 生成的架构图是可交互的实际用起来确实有点东西。我最常用的两个操作是节点聚焦和子图折叠。节点聚焦的意思是点击某个节点之后视图会自动把与它相关的节点突出显示无关的节点置灰。这个功能在处理复杂系统时特别有用。比如我导入了一个包含 30 多个节点的微服务架构直接看全貌就是一团乱麻但点一下订单服务视图立刻变成“订单服务以及它依赖的上下游”整个调用链清晰得像是专门画的。子图折叠则用于管理层次结构。比如你把某个服务内部拆成子服务或者把一组公共组件归到一个分组里渲染出来的图会支持在“展开完整结构”和“折叠为单个节点”之间切换。这相当于你把架构图的阅读深度控制权握在了手里——汇报时折叠成粗粒度视图讲整体进入技术细节时逐层展开往下钻。另外还有一个很实用的交互是路径高亮。你可以指定一个起点和一个终点渲染器会标记出两点之间的所有调用路径。这个特性在做故障影响面分析的时候太关键了直接回答“这个链路里还有多少个依赖是真正绕不开的”这种问题。4.2 替代方案对比画一张交互架构图到底需要几种工具我把自己以前的工作流和 archify 对比了一下。以前要实现同样效果我的工具链大致是用 draw.io 画静态图用 PlantUML 维护版本化文档再用 VuePress 或者 Docusaurus 之类的静态站点做文档托管如果需要交互还得再引入 D3.js 之类的可视化库。一套下来成本非常高而且图越复杂维护成本越失控。简单做了个对比对比维度传统静态绘图PlantUML 代码绘图archify上手难度中等拖拽排版耗时间低但语法要学低自然语言描述即可修改成本高重新排版中改代码重新生成低改描述重新生成交互能力无无有支持缩放/聚焦/折叠语义理解无纯手工无结构化但是人工输入有AI 抽取关系团队协作图形文件难以 diff文本 diff 友好数据结构可版本化表格里最后一行其实是我觉得最值得关注的点archify 的中间产物是一份结构化的架构定义文件它当然能在界面里渲染成交互图更可以作为代码仓库里的一个版本化文档维护。架构哪里变了diff 里看得很清楚不用像图片时代那样“谁改了架构图也看不出来”。我在实际使用里会把这个文件提交到仓库里架构评审的时候直接关联 diff。4.3 在文档中心和评审汇报中的落地用法如果你做得稍微深入一点archify 完全可以嵌入到现有的文档工作流里。你可以在构建文档站点时把架构定义文件渲染成交互组件嵌入页面读者看到的不再是“第 2 章架构总览图.jpg”而是一张能自己探索的交互图。我具体是这么用的团队内部的技术文档站里架构信息是静态的 Markdown 加图片。后来我把 archify 生成的交互架构图嵌入到核心项目文档页里阅读者可以直接在文档里点击服务节点查看它依赖了哪些服务、被谁依赖。这个体验的提升是很直观的——新人在第一次阅读系统文档时普遍反馈能更快地建立大局观。汇报场景就更自然了。技术评审会议上你直接把交互架构图投出来讲到订单服务就说“点开依赖链路”讲到公共组件就“折叠子图”。整个过程不需要切换窗口不需要切换工具表述是完全顺着你的思维走的。5. 用了几轮之后我踩过的坑稳定输出的关键不在于提示词而在于结构约束任何和生成式 AI 打交道的工具都有一个绕不开的问题——输出质量不稳定。我在实际使用 archify 的过程中遇到了几种典型的翻车情况每次都有可复现的原因。5.1 模型漏节点架构描述越长信息丢失越严重第一次遇到的问题是我描述了一个十几行文字的系统结果模型只识别出四五个核心服务消息队列、缓存层这些组件被吞掉了但连接关系里又出现了引用这些组件的边导致渲染出来的图上有悬空的线。这个问题的本质是上下文长度和信息优先级。模型在解析长文本时会把注意力集中在语义突出的实体上频繁出现的名词、和动词直接关联的对象而容易被省略的是“插入语”性质的组件描述。我采用的解决方式是把描述拆成“节点清单 关系清单”两段式。第一段先说有哪些节点每个节点一句话说明职责第二段再说谁依赖谁。这样模型的任务从“一边找实体一边找关系”变成了“先确认清单再连边”信息完整度提升非常明显。如果是在 archify 界面上直接操作我会先在文本里单独写一个小节罗列组件再做关系描述。5.2 依赖方向反了箭头画反比漏画更危险另一种翻车情况是方向错误。我描述“订单服务通过消息队列给商品服务发消息”结果模型把箭头画成了商品服务调用订单服务。这个错误单看图不容易发现但一旦它进入设计评审后果就是对调用链路的误判。这个问题的根源在于模型对“发送方”和“接收方”的判别依赖于动词的语义解析而中文描述里“给……发消息”“把……返回给……”这些表达方式对模型来说并不总是能准确识别方向。我的对策是在描述关系时强制用“A 调用 B”或“A 依赖 B”的句式并在最后加一句强调“以上所有依赖方向均以箭头表示从调用方指向被调用方”。结构化提示确实能明显降低方向错误率但做不到完全消除所以生成的图我还是会快速扫一遍核心链路。5.3 图太大之后的性能问题交互要“够用”而不是“炫技”还有一个很实际的问题当节点数量超过一定阈值时交互式画布的实时缩放和平移会开始卡顿。如果架构图里塞了几百个节点重新布局和碰撞检测的计算量会显著上升浏览器端的渲染压力很大。在这个问题上我踩过的坑是试图生成一张“全家桶”级别的大全图。后来我调整了使用方式按边界拆分架构图。核心业务链路单独生成一张基础设施层单独生成一张中间件通信网络再单独一张。宁可多管理几个架构定义文件也不硬塞一张大图。说实话对团队协作来讲拆开反而更好用因为不同角色关心的边界不同——后端看业务链路运维看基础设施两张图硬拼在一起徒增干扰。5.4 承诺边界与适用场景它不是万能的最后说一句实在的。archify 这个技能模块在“从描述生成架构示意图”这个环节上做得不错但它不是架构设计工具更不是审计工具。不要指望它来验证你的架构是否合理它不具备推理依赖合理性、找出单点故障的能力。它适合的场景是你有一个脑内成型的架构方案需要快速产出可视化结构用于沟通和对齐。至于架构是否最优那仍然是你自己的事。另外如果项目代码已经存在期望它直接读代码生成真实架构这一步超出它当前的设计边界——除非你给它喂的提示词里明确包含代码分析信息比如让 AI 代理先扫描目录、抽取 import 关系再交给渲染器。理论上可以做但 archify 本身不内置代码分析器需要你在上游自行完成。我自己的体会是这类工具最大的价值不在于“让画图变快”而在于它让架构可视化的门槛降到了“会说话就能画”。以前带新人让对方画系统架构图对方先得学会工具操作现在直接把文档丢给 AI先把图生成出来再看着图问自己“这么设计合不合理”。这个顺序的颠倒其实比工具本身的技术含量更值得玩味。如果你平时也需要频繁输出架构图、依赖图、技术方案示意图archify 绝对值得放进你的工具清单里跑一跑这轮下来说不定又给你省出半天时间。