1. 从一条 GitHub 热榜说起archify 到底解决了什么痛点第一次在 GitHub 趋势榜上刷到 archify 这个项目时我的反应是这不就是我团队里那个天天被吐槽的活儿吗。做过后端或者系统设计的朋友都懂每次架构评审之前最耗时间的往往不是写代码而是画那张架构图。产品经理要一张给客户看的技术负责人要一张给新人看的运维还要一张标注部署拓扑的。同一套系统画三遍改五遍最后还没人愿意维护因为代码一改图就过期了。archify 这个项目的定位很直接它是一个技能模块挂载在 AI 代理之上让代理能够根据你的描述或者现有代码自动生成可交互的架构图。注意这里有两个关键词一个是自动生成一个是可交互。前者省掉的是手工拖拽的时间后者解决的是静态图片无法下钻、无法联动、无法实时更新的问题。传统的架构图工具比如 draw.io、Excalidraw、PlantUML本质上还是你告诉它画什么它画什么而 archify 走的是你告诉它系统长什么样它自己理解并画出来的路子。那它适合谁用我梳理了一下大致是三类人。第一类是独立开发者和小团队没有专职的架构师画图全靠自己时间成本极高第二类是技术负责人和架构师需要频繁输出架构文档且文档要跟着代码演进第三类是技术博主和讲师做教程、写文章、录视频时需要大量示意图手工画图效率太低。如果你属于这三类中的任何一类archify 值得花半小时研究一下。需要先说明的是archify 本身不是一个独立的绘图软件它更像是一个能力插件。你得先有一个能跑起来的 AI 代理环境然后把 archify 作为技能加载进去代理才具备生成架构图的能力。这个设计思路其实很聪明因为绘图这件事本身依赖大模型对系统结构的理解能力把理解交给代理把渲染交给前端各司其职。2. 核心设计思路拆解为什么是技能模块而不是独立工具2.1 技能模块化的底层逻辑我研究过不少 AI 代理相关的项目发现一个规律凡是把功能做成技能或者工具挂载到代理上的扩展性都不会差。archify 选择这条路背后的考量其实很实在。架构图的生成涉及三个环节——语义理解、结构建模、可视化渲染。语义理解必须依赖大模型这是代理的强项结构建模需要一个中间格式来承载节点和连线的关系可视化渲染则需要前端库来画图。如果 archify 做成一个独立工具那它就得自己集成大模型调用、自己做提示词工程、自己维护模型版本维护成本极高。而做成技能模块之后它只需要定义清楚输入什么、输出什么中间的大模型调用完全交给宿主代理。这就好比你不必自己造一台发动机只需要把发动机装到车上就行。代理升级了模型archify 自动受益代理换了供应商archify 只要接口不变就还能用。这种解耦带来的另一个好处是可组合性。你可以让代理先用一个技能读代码仓库再用 archify 生成架构图最后用另一个技能把图导出成文档。整个流程串起来就是一个自动化的架构文档生成流水线。单独一个 archify 做不到这些但作为技能模块它能被编排进更大的工作流里。2.2 可交互架构图的技术选型考量可交互这三个字是 archify 区别于普通 AI 绘图工具的分水岭。我见过太多 AI 生成的架构图本质上就是一张 PNG节点位置固定文字写死想改一个模块名都得重新生成。archify 走的是另一条路它生成的图是基于数据驱动的节点和连线都是结构化数据前端根据数据渲染出图形。这意味着什么意味着你可以点击某个节点展开它的子模块可以悬停查看某个服务的详细说明可以拖拽调整布局甚至可以点击节点跳转到对应的代码文件。这些交互能力静态图片给不了。实现上这类可交互图通常基于 SVG 或者 Canvas 渲染配合一套图数据结构比如节点列表加边列表前端用类似 D3.js、Cytoscape.js 或者 React Flow 这样的库来画。为什么 archify 要强调可交互因为架构图的使用场景本身就是动态的。评审的时候有人问这个服务依赖哪些下游你得能当场展开新人入职问这个模块负责什么你得能点进去看注释。静态图在这些场景下就是死物而可交互图是活的。从投入产出比来看前期多花一点功夫做数据结构化后期省下的是无数次重画的时间。2.3 与主流方案的横向对比为了让大家更清楚 archify 的定位我把它和几种常见方案做了个对比。方案生成方式可交互性维护成本适合场景手工绘图draw.io 等人工拖拽弱部分支持高改一次画一次一次性汇报代码即图PlantUML/Mermaid写 DSL 代码无中需维护代码文档内嵌AI 生图通用绘图模型提示词生成无输出图片低但不可控概念示意archify 技能模块代理理解后生成强数据驱动低随代码更新持续演进的系统从表里能看出来archify 的差异化在于低维护成本 强交互。PlantUML 虽然也是代码驱动但你得自己写 DSL系统一复杂DSL 就长得没法看。archify 把写 DSL 这一步也省了你直接用自然语言描述或者让它读代码它来生成结构。这个体验上的差距用过的人都懂。3. 核心细节解析archify 生成一张图要经过哪些环节3.1 输入层代理如何理解你的系统archify 的输入可以有很多种形式这也是它灵活的地方。最常见的是自然语言描述比如你跟代理说我有一个电商系统包含用户服务、订单服务、支付服务订单服务依赖用户服务和支付服务底层用 MySQL 和 Redis。代理解析这段话提取出节点和依赖关系这是最基础的用法。进阶一点的是读取代码仓库。代理可以扫描你的项目目录识别出各个模块、服务、依赖关系然后自动生成架构图。这个能力依赖代理对代码结构的理解比如它能识别出 Spring Boot 的 Controller、Service、Repository 分层或者识别出微服务之间的调用关系。我实测下来对于结构清晰的项目这种方式生成的图准确率相当高。还有一种输入是配置文件比如 docker-compose.yml、Kubernetes 的 deployment 配置。这些文件本身就描述了服务之间的依赖和部署关系代理读完之后生成的图基本就是一张部署架构图。这种用法在运维场景下特别实用因为部署拓扑经常变手工画图根本跟不上。提示输入描述越结构化生成的图越准确。如果你用自然语言建议按模块-职责-依赖的格式组织比一大段散文效果好得多。3.2 中间层结构化数据的组织方式代理理解完输入之后不会直接去画图而是先生成一份结构化的中间数据。这份数据通常包含节点列表和边列表。节点里会有 id、名称、类型服务、数据库、缓存、网关等、描述等字段边里会有源节点、目标节点、关系类型调用、依赖、数据流等。为什么要有这一层因为这是可交互的基础。前端拿到这份数据才能知道哪个节点可以点击、点击之后展示什么、节点之间怎么连线。如果代理直接输出一张图片那交互就无从谈起。这份中间数据一般用 JSON 格式承载结构大致长这样{ nodes: [ {id: user-service, name: 用户服务, type: service, desc: 负责用户注册登录}, {id: order-service, name: 订单服务, type: service, desc: 负责订单创建与管理}, {id: mysql, name: MySQL, type: database, desc: 主数据存储} ], edges: [ {from: order-service, to: user-service, type: call}, {from: order-service, to: mysql, type: read-write} ] }这份数据的好处是可校验、可修改。如果代理生成的图有误你不用重新生成直接改 JSON 就行。而且这份数据可以存进版本库跟着代码一起演进下次生成时对比一下就知道哪里变了。3.3 渲染层从数据到可交互图形渲染层是 archify 的前端部分负责把中间数据变成看得见、点得动的图。这一步的技术选型很关键因为要兼顾美观和性能。节点少的时候几十个以内用 SVG 渲染完全够用清晰度还高节点多了上百个可能就得考虑 Canvas 或者 WebGL 了。布局算法也是个大问题。节点怎么摆才好看、连线怎么走才不交叉这些都有专门的算法比如力导向布局、层次布局、正交布局。archify 一般会根据图的类型自动选择布局比如分层架构用层次布局微服务调用关系用力导向布局。我个人的经验是布局算法再智能也架不住节点太多所以生成大图的时候建议先按模块分组分组内部再展开。交互方面常见的操作包括缩放、拖拽、点击展开、悬停提示。这些交互的实现依赖前端框架的事件处理能力。如果你是自己集成 archify建议选一个成熟的图可视化库别自己从零写坑太多。4. 实操过程从零跑通 archify 的完整流程4.1 环境准备与依赖安装要跑通 archify你得先有一个能加载技能的 AI 代理环境。这里我不指定具体是哪个代理平台因为不同平台的加载方式不一样但核心步骤是相通的。你需要确认代理支持自定义技能或者工具调用这是前提。环境准备好之后把 archify 的技能定义文件放到代理的技能目录下。技能定义文件一般包含两部分一是技能的描述告诉代理这个技能是干什么的、什么时候该用二是技能的参数定义告诉代理调用这个技能需要传什么参数。这两部分写清楚了代理才知道在什么场景下调用 archify。依赖方面archify 的渲染部分通常依赖 Node.js 环境因为前端构建需要。如果你只是用代理生成数据、自己用现成工具渲染那依赖会少很多。我建议新手先用最简配置跑通别一上来就搞全套。# 以常见的技能加载方式为例具体命令以你所用代理的文档为准 git clone archify 仓库地址 cd archify npm install npm run build注意不同代理平台的技能目录结构差异很大安装前务必先看代理的官方文档别照着别的平台教程硬套容易踩坑。4.2 编写第一个技能调用示例环境就绪之后先写一个最简单的调用示例验证链路是否通。最简单的场景就是让代理根据一段描述生成架构图。你可以这样跟代理说帮我生成一张架构图包含三个服务网关服务、用户服务、订单服务。网关服务调用用户服务和订单服务用户服务和订单服务都依赖 MySQL 数据库。代理收到这个请求后会判断这需要调用 archify 技能然后把描述传给技能。技能内部会调用大模型解析描述生成中间数据再渲染成图。整个过程如果顺利你就能看到一张可交互的架构图。第一次跑的时候建议把中间数据打印出来看看确认节点和边都提取正确了。如果发现漏了节点或者连错了线说明提示词需要调整。这一步是调优的关键别跳过。4.3 参数配置与效果调优archify 一般会提供一些参数让你控制生成效果常见的包括图的类型分层图、调用图、部署图、布局方式、节点样式等。这些参数怎么配直接影响最终效果。我整理了一份常用参数的配置建议参数作用推荐值说明diagram_type图类型layered分层架构用 layered调用关系用 graphlayout布局算法dagre层次清晰适合大多数场景direction布局方向TB从上到下符合阅读习惯node_style节点样式rounded圆角矩形视觉柔和show_legend是否显示图例true节点类型多时建议开启调优的核心思路是先保证结构正确再追求美观。结构错了图再好看也没用。结构对了之后再调布局和样式让图更易读。我见过有人一上来就纠结颜色搭配结果节点关系都是错的本末倒置。4.4 集成到日常工作流跑通单次生成之后下一步是把它集成到日常工作流里。我的做法是在项目的 CI 流程里加一个步骤每次代码合并到主分支就自动触发一次架构图生成把生成的图和数据存到文档目录。这样架构图永远是新的不用人工维护。具体实现上可以写一个脚本调用代理的 API传入代码仓库路径让代理读取代码后生成架构图。脚本跑完之后把生成的 HTML 或者数据文件推到文档站点。这套流程搭起来之后架构文档的维护成本几乎降为零。# 伪代码示例展示集成思路 #!/bin/bash # 触发代理生成架构图 curl -X POST 代理API地址/generate \ -d {skill: archify, input: ./src, type: layered} \ -o ./docs/architecture.json # 渲染成可交互页面 node ./archify/render.js ./docs/architecture.json ./docs/architecture.html5. 常见问题与排查技巧实录5.1 生成的图节点缺失或关系错误这是最常见的问题根源通常在输入描述不够清晰或者代理对代码的理解有偏差。排查思路是先把中间数据打印出来看看节点和边提取成了什么样。如果节点缺失检查输入描述里有没有明确提到那个模块如果关系错误检查描述里的依赖方向有没有说反。我踩过的一个坑是描述里用了订单服务连接用户服务这种模糊说法代理理解成了双向依赖。后来改成订单服务调用用户服务方向就对了。所以描述依赖关系时动词要精确调用、依赖、读写、订阅这些词的含义不一样代理会区别对待。5.2 图太大导致渲染卡顿节点超过一百个之后渲染性能会明显下降尤其是用 SVG 渲染的时候。解决办法有两个一是分组折叠把相关节点归到一个组里默认折叠点击才展开二是分层展示先展示顶层架构点击某个模块再下钻到内部细节。我在一个微服务项目里试过两百多个服务全画在一张图上浏览器直接卡死。后来改成按业务域分组每组默认折叠只显示组名和组间关系性能问题立刻解决。这个思路其实和看地图一样先看省市再看街道信息分层呈现才看得清。5.3 代理不调用 archify 技能有时候你跟代理说了半天它就是不用 archify自己用文字描述了一遍架构。这种情况通常是技能描述写得不够好代理没意识到该用这个技能。解决办法是优化技能描述把触发条件写清楚比如当用户要求生成架构图、系统图、部署图时调用此技能。另一个原因是代理的上下文里已经有类似的能力它优先用了内置功能。这时候你可以在提示词里明确指定使用 archify 技能生成强制它调用。实测下来明确指定之后调用成功率会高很多。5.4 常见问题速查表问题现象可能原因排查方法解决建议节点缺失输入描述不完整检查中间数据补充模块描述关系方向错误动词使用模糊检查边的方向用精确动词渲染卡顿节点过多查看节点数量分组折叠或分层技能不调用技能描述不清查看代理日志优化描述或强制指定布局混乱布局算法不匹配尝试不同布局按图类型选布局中文乱码字体未配置检查渲染配置指定中文字体提示遇到问题先看中间数据中间数据对了问题就在渲染层中间数据错了问题就在理解层。这个二分法能帮你快速定位。6. 我个人的使用体会与几个实用建议用了一段时间 archify 之后我最大的感受是它改变的不是画图这个动作而是架构文档的维护方式。以前架构图是一次性产物画完就扔在那代码改了也没人更新。现在架构图是代码的衍生品代码一变图就能重新生成永远和代码保持一致。这个转变的价值比省下画图时间大得多。几个实用建议分享给准备上手的朋友。第一从简单场景开始别一上来就让它读整个大仓库先拿一个小模块试试跑通了再扩大范围。第二中间数据要存起来别每次重新生成存下来之后可以对比、可以回滚、可以手工微调。第三别追求一次完美AI 生成的东西总有偏差把它当成初稿生成器人工再润色效率最高。第四注意图的粒度一张图别塞太多信息该拆就拆可交互的优势就在于可以分层展示。后续这个方向还能怎么扩展我想到的是和代码变更联动每次 PR 合并时自动对比架构图的变化如果新增了服务依赖就在 PR 里提示出来。这样架构评审就能前置到代码评审阶段而不是等到系统出问题才回头看架构。这个思路我觉得挺有价值等有空了打算自己搭一个试试。