1. 架构图这件事为什么一直让人又爱又恨做后端或者搞系统设计的朋友都有体会架构图这东西画的时候嫌烦不画的时候又不行。新同事入职要一张全局图技术评审要一张部署图给老板汇报还得来一张业务架构图。问题是每次系统一改图就过期改图的时间比写代码还长。我见过太多团队架构图停留在某个远古版本的 Visio 文件里谁也不敢动谁也不想动。archify 这个项目就是冲着这个痛点来的。它是一个给 AI 代理用的技能模块核心能力是让 AI 代理根据你的代码仓库或者文字描述自动生成可交互的架构图。注意这里有两个关键词一个是“AI 代理”一个是“可交互”。前者意味着它不是那种你填表单然后点生成的死板工具而是能理解上下文、能追问、能迭代的智能助手后者意味着产出的不是一张静态 PNG而是能点击、能展开、能钻取的动态视图。这个技能模块适合谁用我梳理了一下大概三类人收益最大。第一类是中小团队的技术负责人没预算买昂贵的架构管理平台但又需要维护一份能看的架构文档第二类是独立开发者或者接私活的朋友交付项目时附一张清晰的架构图专业度直接拉满第三类是正在学习系统设计的新人拿它来分析开源项目的结构比干啃代码快得多。我花了几天时间把这个技能模块的玩法摸了一遍下面把整个思路、实现细节、踩过的坑都摊开讲。文章会比较长但每一段都是实操里攒出来的不是那种翻译 README 的水文。2. 整体设计思路为什么是“技能模块”而不是“独立工具”2.1 技能模块的定位逻辑先说说为什么 archify 选择做成技能模块而不是一个独立的 SaaS 或者桌面应用。这个选择背后有很实际的考量。独立工具的问题是你得单独打开它单独输入信息单独导出结果然后再切回你的工作流。这个切换成本看着小实际上很致命。而技能模块是挂载在 AI 代理身上的你在跟代理讨论代码的时候随口一句“帮我把这个服务的架构画出来”它就调用了 archify 的能力直接在当前对话里产出图。这种“无感调用”才是它真正的价值。从技术架构上看技能模块本质上是一组封装好的提示词模板、工具调用定义和输出渲染逻辑。AI 代理负责理解意图和提取信息archify 负责把信息转成结构化的图描述最后前端负责渲染成可交互的图形。三层各司其职耦合度低这也是为什么它能适配不同的代理平台。2.2 可交互架构图的技术选型“可交互”这三个字说起来轻巧实现起来有好几条路。我研究了一下 archify 的思路它没有走传统的图片生成路线而是输出结构化的图数据再由前端渲染。这个决策很关键。如果生成静态图片那交互性就无从谈起而且图片体积大、不可搜索、不可访问。如果生成 SVG虽然能交互但复杂架构下节点一多性能会崩。archify 选择的是输出类似节点-边关系的结构化数据前端用图形库渲染。这样做的好处是缩放、拖拽、点击展开、搜索节点这些操作都是原生支持的而且数据可以增量更新改一个节点不用重画整张图。提示如果你打算自己复现类似方案图形渲染库的选择很关键。节点数在 100 以内的大部分库都能扛超过 500 个节点的一定要选支持虚拟化或者 Canvas 渲染的方案否则浏览器会卡到怀疑人生。2.3 与本地模型配合的考量热词里提到了“AI 代理助手加本地模型”这个组合在 archify 的场景下特别有意义。架构信息往往涉及公司内部系统很多人不愿意把代码结构发给云端模型。这时候本地模型就派上用场了。archify 的技能定义是平台无关的也就是说你把它挂到云端代理上能用挂到本地跑的模型上也能用。本地模型的优势是数据不出内网劣势是理解能力可能弱一些。我的经验是对于结构清晰、命名规范的代码库本地模型完全够用对于那种命名混乱、历史包袱重的老项目云端大模型的理解准确率会高不少。这个取舍要根据你的数据敏感度来定。3. 核心细节拆解从代码到架构图中间发生了什么3.1 信息提取阶段的关键动作AI 代理拿到“生成架构图”这个指令后第一步是搞清楚要画什么。这里有个容易被忽略的细节架构图分很多种是画部署架构、业务架构、还是数据流架构archify 的技能定义里应该包含了意图澄清的逻辑。如果用户只说“画个架构图”代理会先扫描项目结构识别出这是单体应用还是微服务用了哪些中间件然后给出一个默认的架构视角。如果用户明确说了“我要看服务之间的调用关系”那代理就会聚焦在服务依赖上。这个澄清过程看似简单实际上决定了后面所有工作的方向。信息提取的具体手段包括读取项目根目录的配置文件比如 pom.xml、package.json、docker-compose.yml分析目录结构推断模块划分扫描关键注解或装饰器识别服务边界。对于微服务架构还会去读服务注册配置和网关路由规则。3.2 图结构生成的参数与规则从提取到的信息到最终的图结构中间要经过一层转换。这层转换的规则直接决定了图的质量。我实测下来有几个参数特别影响效果。参数项作用推荐值说明节点粒度控制每个节点代表多大范围服务级或模块级太细会爆炸太粗没信息量分层策略决定图的分层方式按调用层级也可按业务域或部署单元边的关系类型标注连接的含义调用/依赖/数据流不同类型用不同线型区分布局算法决定节点排布分层布局复杂图用力导向布局折叠阈值超过多少子节点自动折叠5-8 个避免单节点展开后占满屏幕这些参数不是拍脑袋定的。节点粒度选服务级是因为大部分场景下大家关心的是服务之间的边界而不是某个服务内部的类关系。分层策略按调用层级是因为这样最符合阅读习惯从上到下就是请求的流向。折叠阈值定在 5 到 8是实测下来屏幕空间和可读性的平衡点。3.3 可交互能力的实现要点可交互不是加个缩放就完事了。真正好用的交互设计要解决几个具体问题。第一个是渐进式披露。一张完整的微服务架构图可能有几十个服务全展开根本看不清。好的做法是默认只显示核心服务点击某个服务才展开它的内部模块。archify 的输出结构里应该包含了层级信息前端据此实现展开折叠。第二个是上下文关联。点击一个节点应该能高亮所有跟它直接相关的节点和边其他的淡出。这个功能在排查依赖问题时特别好用一眼就能看出某个服务挂了会影响谁。第三个是信息浮层。鼠标悬停或者点击节点时弹出该节点的详细信息比如技术栈、负责人、部署环境。这些信息如果全画在图上会乱成一锅粥放在浮层里按需查看才合理。注意交互设计有个反直觉的点功能不是越多越好。我见过一些架构图工具右键菜单里塞了二十个选项结果没人用。核心交互控制在三到四个就够了展开折叠、高亮关联、查看详情、搜索定位。4. 实操过程手把手把 archify 跑起来4.1 环境准备与技能挂载假设你已经有一个能用的 AI 代理环境接下来要做的是把 archify 技能挂上去。不同平台的挂载方式不一样但核心步骤大同小异。首先得拿到 archify 的技能定义文件。这类技能模块通常包含一个描述文件说明技能名称、触发条件、输入输出格式和若干提示词模板。拿到之后按照你所用代理平台的文档把技能注册进去。注册的时候要注意触发词的设置太宽泛会误触发太窄了又叫不出来。我的建议是设置成“画架构图”“生成架构图”“架构可视化”这几个明确的短语。挂载完成后做个简单的验证。随便找个项目目录对代理说“帮我分析这个项目的架构并画出来”。如果代理开始读取文件、分析结构说明技能已经生效。如果它反问你“什么是架构图”那就是没挂上回去检查注册步骤。4.2 从代码仓库生成第一张图验证通过后来走一遍完整流程。我拿一个典型的 Spring Cloud 微服务项目做测试目录结构大概是这样的一个网关服务、一个注册中心、三个业务服务、一个公共模块。第一步让代理扫描项目。它会读取各个服务的配置文件识别出服务名、端口、依赖关系。这个过程大概需要十几秒取决于项目大小。第二步代理会输出一份中间结果通常是一段结构化的描述列出它识别到的所有服务和它们之间的关系。这一步很关键你要仔细核对看看有没有漏掉的服务或者识别错的依赖。我测试的时候就发现代理把某个通过消息队列异步通信的服务误判成了直接调用关系。这种错误在自动生成里很常见手动修正一下就好。第三步确认无误后让代理生成图。它会输出一份图数据前端渲染出来就是可交互的架构图。第一次生成可能需要调整布局参数比如节点间距、连线样式这些都可以通过追加指令来微调。4.3 手动修正与迭代优化自动生成的东西一次就完美的概率很低。我总结了几类常见问题和对策。服务漏识别的情况通常是因为配置文件格式不标准或者服务注册信息藏在代码里而不是配置里。解决办法是手动补充信息告诉代理“还有一个叫 xxx 的服务它依赖 a 和 b”。依赖关系画错的情况多半是代理把间接依赖当成了直接依赖。这时候需要明确告诉它“只画直接调用关系不要展开传递依赖”。布局混乱的情况一般是节点太多导致的。可以调整折叠阈值让部分节点默认收起。或者换一种布局算法分层布局搞不定的试试力导向布局。提示迭代的时候不要每次都从头生成。让代理记住上一版的结果只修改需要调整的部分。这样既快又不会把之前调好的部分搞乱。5. 常见问题与排查技巧实录5.1 代理不触发技能怎么办这是最常见的问题。你说了“画架构图”代理却跟你聊别的。原因通常有三个技能没注册成功、触发词不匹配、或者代理的意图识别把架构图理解成了别的意思。排查顺序是这样的先确认技能列表里能看到 archify看不到就是注册失败再看触发词设置试着用技能定义里写的原话去触发如果都正常但还是不触发那就是意图识别的问题可以换一种说法比如“把这个项目的结构可视化一下”。5.2 生成的图节点太多看不了节点爆炸是自动生成架构图的通病。一个中等规模的微服务项目自动展开后可能有上百个节点。这时候不要硬看先调折叠阈值把非核心服务收起来。然后按业务域分组把相关的服务聚在一起。最后用搜索功能定位你关心的部分。如果调整参数后还是太乱那说明这个项目的架构本身就需要梳理。自动生成只是把现状画出来现状乱说明架构该重构了。这时候图反而成了一个诊断工具。5.3 本地模型生成质量差怎么提升本地模型在理解复杂代码结构时确实会力不从心。提升质量有几个实操技巧。一是给模型提供更明确的上下文比如先让它读一遍项目的 README 和主要配置文件再让它画图。二是分步走先让它列出所有服务确认后再让它分析依赖关系最后再生成图。三是降低期望本地模型适合结构清晰的新项目老项目还是老老实实用云端模型或者手动画。5.4 图数据能导出和版本管理吗可以。archify 输出的图数据是结构化的通常是 JSON 格式。你可以把它存到代码仓库里跟代码一起做版本管理。每次架构变更重新生成一次对比 diff 就能看出改了什么。这个用法在技术评审时特别有用评审材料直接附上架构图的 diff谁改了什么一目了然。问题现象可能原因排查动作解决方式代理不响应画图指令技能未注册或触发词不对检查技能列表和触发词配置重新注册或更换触发短语生成图节点过多折叠阈值设置过大查看当前阈值参数调小阈值启用分组折叠依赖关系错误代理混淆了直接和间接依赖核对中间结果描述明确指令只保留直接关系本地模型输出混乱上下文不足或模型能力限制检查是否提供了项目说明分步引导补充上下文图数据无法保存输出格式未指定确认代理是否输出了结构化数据明确要求以 JSON 格式输出6. 这套玩法还能怎么扩展archify 这个技能模块本身是个起点围绕它还能做不少延伸。我想到几个方向有的已经试过有的还在琢磨。第一个方向是跟 CI 流水线集成。每次代码合并到主分支自动触发一次架构图生成把结果推到文档站点。这样架构图永远是新的再也不会出现过期问题。实现上就是在流水线里加一个步骤调用代理的 API 生成图数据然后部署到静态站点。第二个方向是做架构变更影响分析。把历史版本的图数据存下来对比两个版本自动识别出新增的服务、删除的依赖、变更的调用关系。这个在微服务治理里价值很大能提前发现不合理的依赖引入。第三个方向是结合芋道这类开源系统的架构图做学习辅助。拿一个成熟的开源项目让代理生成架构图然后对照着图去读代码理解效率会高很多。特别是对于刚接触某个技术栈的人来说先看图再看代码比直接扎进代码里要快得多。第四个方向是多视图切换。同一套系统可以生成业务架构视图、部署架构视图、数据流视图用户按需切换。这个对代理的信息提取能力要求更高需要它从不同维度去理解同一份代码。注意扩展功能的时候要控制复杂度。我见过一些团队给架构图工具加了太多花哨功能结果核心的画图能力反而退化了。先把基础的生成和交互做扎实再考虑锦上添花。7. 我踩过的几个坑你大概率也会遇到第一个坑是过度依赖自动生成。刚开始用的时候觉得太爽了什么图都让代理画。后来发现代理画出来的图适合做初稿和沟通但真正要归档的架构文档还是得人工审核和润色。自动生成解决的是从零到一的问题从一到十还得靠人。第二个坑是忽略了图数据的维护。图生成出来就不管了过两个月再看跟代码完全对不上。后来我养成了习惯每次大的架构调整后顺手重新生成一次花不了几分钟但能省掉后面很多扯皮。第三个坑是参数调得太激进。为了让图好看把节点粒度调得很细结果生成出来的图密密麻麻自己都看不懂。后来学乖了默认用服务级粒度需要看细节的时候再单独展开某个服务。第四个坑是没做版本对比。有一次排查一个线上问题怀疑是某个依赖关系变更导致的但谁也说不清什么时候改的。要是有架构图的版本记录翻一下 diff 就清楚了。从那以后我把图数据纳入了版本管理。这几个坑说到底都是一个原因把自动生成当成了终点而不是起点。工具再好用也得配上合理的流程和习惯才能真正发挥价值。archify 这类技能模块的意义是把你从重复劳动里解放出来让你有精力去关注架构本身是否合理而不是纠结于怎么把线画直。
)
