架构图这东西做过系统设计的人基本都绕不过去。但说实话传统画架构图的方式早就跟不上一线开发的节奏了——架构调整一次图就得跟着改一次而改图这件事往往比改代码还让人头大。最近我在GitHub上挖到一个叫archify的项目思路很对我的胃口它不是又一个画图工具而是给AI代理装的一个“技能模块”你只要用自然语言描述要什么架构它就能自动生成一张可交互的架构图。这个方向我觉得值得展开聊聊既能帮团队省掉“画图五分钟改图两小时”的尴尬也能让架构信息的沉淀方式往前迈一步。这篇文章我会从项目思路、技术原理、实操部署到避坑经验完整拆一遍不管你是架构师、后端开发还是正在梳理存量系统的技术负责人都能找到可以直接用的部分。1. 项目核心思路为什么架构图需要AI代理来生成1.1 架构图绘制的传统痛点先说说我们平时画架构图都在痛什么。最典型的是信息不同步代码已经演进到第三版了PPT里的架构图还停留在第一版。尤其微服务架构下服务拆分、依赖调整、中间件替换几乎是常态图如果不跟着变很快就成了“仅供参考”的摆设。另外手工画图本身有很高的隐性成本。用Visio、draw.io这类工具每个节点、每条连线都要手动拖拽标注格式、对齐、配色这些东西极其消耗注意力。你画一张覆盖三四十个模块的架构图半天时间基本上就交代在里面了。更麻烦的是架构图表达的其实是一种“关系”服务之间怎么调用、数据往哪流转、外部依赖跟内部模块怎么交互。这些关系在代码里是明确存在的但靠人眼去梳理再转译成图形化表达中间产生的信息损耗非常大。还有一类痛点经常被忽略——架构图的“读者”不只一种。老板看的是分层和边界开发看的是接口和依赖运维看的是部署和流量路径。传统的静态架构图没法按需切换视图一张图画到极致也就只能覆盖一种视角。1.2 “技能模块”设计理念的巧妙之处archify这个项目有意思的点在于它把架构图生成这件事做成了AI代理的“技能”而不是一个独立的工具链。这里的逻辑值得琢磨一下如果只是做一个“输入代码、输出图片”的软件那本质上还是传统工具的自动化版本使用场景非常受限。但作为技能模块它被嵌入到了AI代理的工作流中等于给了AI一双“画架构图的手”。举个我实际遇到的场景。团队让我梳理一套老系统的调用关系传统做法是去看代码、画时序图、整理依赖清单来回折腾少说一两天。但如果代理已经加载了archify技能我只需要告诉它“把order-service及其依赖的完整调用链梳理出来生成可交互的架构图”它能自己去做代码分析、关系提取、图结构生成这一整套事情我拿到的是结果而不是过程。这个思路在工程上还有个很实际的好处——技能模块是可插拔的。今天需要架构图就加载archify明天需要写测试用例就换另一个技能AI代理的能力边界可以灵活伸缩。这种架构方式跟传统的“全家桶”方案完全不同每个技能都能独立迭代反而让整个工具的生态活得更好。2. 可交互架构图的技术拆解2.1 从模型到图表自动生成的完整链路要理解archify的生成链路先得搞清楚它内部大致是怎么跑的。整个流程可以拆成四段输入理解、结构抽取、图模型构建、交互渲染。输入理解这块代理需要解析用户的自然语言描述同时结合输入的代码仓库路径或源码内容。比如你说“帮我画一张用户认证模块的架构图”代理会先明确边界在哪再通过代码分析识别出认证相关类、接口和调用关系。结构抽取是技术含量最高的环节。这里依赖的大模型需要把非结构化的代码和文本转化为结构化的图谱数据——具体来说就是提取出实体服务、模块、数据库、外部系统和关系调用、依赖、数据流转。我用的时候发现archify对关系类型的定义还是比较丰富的不只是简单的“调用”还包括“异步消息”“数据读写”“部署依赖”这些细粒度语义。图模型构建接到结构化数据后会生成一张中间态的“图描述文件”。这一步很关键它相当于把架构信息跟具体渲染方式解耦了。哪怕后面要换渲染引擎只要图描述文件的格式不变整个链路就不会断。2.2 “可交互”是如何实现的很多工具也能自动生成架构图但生成的是静态PNG点不了、查不了、放大全靠拖动。archify比这往前走了一步它的输出是带交互能力的HTML/SVG页面。我实际体验下来的交互能力包括点击节点跳转到对应的代码位置、悬停节点高亮出它的上下游依赖、通过侧边栏筛选只看某个服务的相关链路、鼠标拖拽调整节点布局并自动保存。这块是怎么实现的简单说渲染层用的是一套基于Web的图形引擎把图描述文件转换成可交互的Dom元素节点和边的事件绑定、缩放手势、布局算法这些都在这个引擎里处理。用户的图里如果包含几十个微服务节点展开后信息量很大这时候布局算法的质量就非常影响使用体验——好在它支持力导向布局和分层布局的切换能适配不同复杂度的图。这里我多说一句。很多AI生成的图表工具输出完就撒手不管了但archify做到了一点很实用它生成的HTML文件里保留了完整的“溯源信息”。我点任意一个节点它能告诉我这个节点的数据是从哪段代码、哪个文件分析得来的。对于梳理存量系统这种场景这个能力等于给架构图加了一层“证据链”拿到图的人不用盲信可以自己回溯验证。2.3 技术栈与实现亮点从项目结构来看archify的核心逻辑主要围绕模型调用来组织跟常见的Claude Skills机制和类似的路由框架做了对接。依赖方向很明确处理代码分析的部分用到了树状视图工具来辅助做目录结构感知架构描述文件的生成靠的是大模型的结构化输出能力渲染层则走Web技术栈。这里值得夸一下它把“树状视图工具”整合进来的设计。AI代理分析代码的时候最大的问题是对仓库结构没有全局感经常捡了芝麻丢了西瓜。通过在代理工具链里加入树状目录读取能力archify在抽取结构前就能对整个仓库的模块边界有个预判这比直接拿文件路径列表去消耗大模型上下文要高效得多。3. 实操部署5分钟跑通Archify3.1 环境准备与安装先泼盆冷水archify本身不是一个点开即用的在线服务它是一个需要跟AI代理配合的技能模块所以你本地得先有一套能跑的AI代理环境。我自己用的是基于Claude生态的代理框架你也可以用其他兼容Skills机制的代理接口大同小异。安装这块我推荐直接clone仓库因为技能模块通常需要跟代理框架放在一起才能被识别。步骤很简单git clone https://github.com/shihabal3amri/archify.git cd archify然后根据项目的README把依赖装好。这里不同版本依赖差异比较大我的建议是严格按你clone那个版本的README来别直接照搬网上的教程因为项目还在快速迭代依赖版本变化很频繁。安装完重点检查一个东西技能配置文件的路径。代理框架加载技能模块时会去找注册文件里配置的skills目录如果你的目录层级不对代理根本感知不到archify的存在。我当时就卡在这步半天后来发现是技能目录没放在代理默认扫描的路径下。3.2 配置AI代理与本地模型archify生成架构图依赖大模型的结构化抽取能力所以模型的选择直接影响最终效果。我的实际体验是用云端模型效果最稳定尤其处理复杂代码结构时长上下文能力很重要但如果你比较在意数据隐私也可以接本地模型比如Ollama部署的Qwen系列或Llama系列。配置本地模型时要注意上下文窗口的大小。分析大型代码仓库时上下文很容易被文件内容撑爆所以要做好内容裁剪。我做了个小优化不让模型一次性读取全部代码而是先通过树状视图工具拿到目录结构再指定重点目录下的关键文件做全文分析其余文件只提取对外接口。这样既节省token也有效避免模型被无关代码带偏。代理端的配置则主要是一段连接信息把模型地址、API key、模型名称填好就行。验证是否生效的方式很简单让代理“介绍一下你有哪些技能”如果响应列表里出现了archify相关条目说明加载成功了。3.3 生成第一张架构图走通安装之后第一次生成架构图建议选一个规模可控的项目别上来就拿几百个服务的仓库练手。我拿公司一个中等规模的用户中心服务试过一次仓库大概有二十几个内部模块外加若干外部依赖。我的请求是这样描述的“分析当前仓库的架构生成一张可交互的架构图重点展示模块间调用关系、数据存储依赖以及对外部服务的依赖边界。”这一步代理会分阶段处理先扫目录结构再深挖关键文件间的关系最后调用archify技能生成图描述文件并渲染。整个过程跑了大概三分钟左右当时我感觉跟手动画图的效率差距就非常明显了——手动做这些光理清依赖就得几个小时。生成完之后打开输出的HTML文件第一感觉是图的信息量比我预想的完整。服务节点、数据库、外部依赖这些都是分组建模的节点间的连线标注了关系类型。最重要的是鼠标点上去真的能溯源到对应的代码文件这种“图即文档”的体验传统工具很难做到。4. 典型应用场景实战4.1 存量代码库架构梳理存量系统的架构梳理可以说是archify最适合的场景没有之一。老项目往往文档缺失、人员流动大新接手的人面对几十万行代码最头疼的就是“这系统到底是怎么转起来的”。传统做法是走读代码加访谈老员工成本极高。我第二周的实践中对一个维护了三年的订单中台做了完整梳理。这个系统里服务调用链很长订单创建会触发库存、支付、优惠券、物流等一串下游接口靠人眼跟根本理不过来。archify的处理方式是把代码里实际的调用关系直接抽出来生成一张带完整调用链的交互图我甚至能通过筛选功能只查看“订单创建”这条链路涉及的所有节点和依赖。这里有一个很打动我的细节。生成的架构图里有个服务之间的调用方向是反的——我一直以为是订单服务调用支付服务图里显示的是支付回调反过来调用了订单的接口。对照代码确认后我发现其实是之前重构时改了调用方式文档完全没更新。这就是为什么“从代码出发的架构图”比“从文档出发的架构图”可靠得多。4.2 微服务架构设计与评审在新项目设计阶段archify也能派上用场。虽然它本身不做设计决策但可以用场景推演来验证设计稿的合理性。比如我设计一套新的积分系统先把模块划分和服务边界写出来让代理结合archify生成架构图然后对着图检查是否有循环依赖、是否有服务间的调用链路过长、数据流是否有不合理的回环。实际推演中我发现了一个隐患两个服务之间既有同步调用又有异步消息在图上形成了闭环。单看代码设计发现不了这个问题但图把路径画出来之后一眼就能看出这里有潜在的死锁或数据一致性的坑。这种“图驱动设计评审”的思路现在我会推荐给每个做微服务方案的同学。另外架构评审会上可交互的架构图比静态图的演示效果好得多。评审的人不用靠想象去理解调用的上下游直接点节点就能看到路径和依赖范围提出的意见也更聚焦在真正的设计问题上而不是纠结于图画的清不清楚。4.3 与现有架构图方案的对比我用过不少架构图工具跟它们放在一起比archify的定位其实很清晰。传统的Visio/draw.io是“人画图”效率瓶颈在人的操作PlantUML和Mermaid是“代码生成图”虽然自动化程度高了但输出的还是静态图而且布局效果一般云厂商的架构图工具则往往绑定了自家产品灵活性不够。相比之下archify有几个明显的差异化优势。第一它的输入可以是自然语言加代码库不需要人手动维护绘图代码第二输出是可交互的HTML信息承载量比静态图高一个量级第三图里自带代码溯源能力这基本是独一份。局限性也有的复杂图的布局优化还有提升空间大型项目分析时的token消耗也需要关注。5. 常见问题与避坑指南5.1 依赖与兼容性问题这个项目迭代快我前后试过两个版本配置文件格式就变了。如果你clone了最新代码但代理框架版本比较老很可能出现技能模块加载不上的问题。排查思路是这样的先看代理的启动日志确认skills路径是否被正确扫描再看技能模块的注册入口跟代理期望的加载格式是否匹配。还有一个很容易踩的坑是Python环境冲突。archify的依赖里有好几个跟常见的AI库有版本重叠如果你机器上已经装了其他AI框架用虚拟环境隔离是必须的。我因为图省事装到全局环境结果把原来的代理环境搞崩过一次花了不少时间重建从那以后一律先建虚拟环境再装依赖。5.2 输出质量不佳怎么办AI生成架构图最怕的就是图出来结构混乱、关系对不上。我总结下来有这么几个典型问题和对应的调整策略。第一模型对代码库的理解不够深。表现是抽取出来的关系明显有遗漏或者把不相关的调用当成了依赖。这种情况通常可以通过“引导式提示”来改善就是告诉代理重点关注哪个目录、哪些类型的调用关系而不是让它自己漫无目的地扫。第二输出结构不稳定。同一段描述跑两次图结构可能不完全一样。如果你的场景对稳定性要求高可以把生成的图描述文件存下来做版本管理后续手动微调而非重新生成。第三布局不够美观。AI能保证结构正确但审美上有时会给你难堪。我的做法是在生成后手动调整一次布局或者通过指定布局算法来改善。毕竟图是给人看的节点分布交叉太乱会影响阅读效率。5.3 交互效果失效排查这种情况我遇到过一次生成的HTML文件节点和连线都在但点击节点没有反应。排查后发现是渲染层依赖的交互库没有正确加载当时是因为输出路径里带了中文目录导致资源引用异常。解决办法很简单把输出路径改成纯英文目录就恢复了。另外一个跟交互相关的经验生成的HTML是单文件还好但如果项目配置了将资源拆分开的选项那迁移到别处时一定要把静态资源一起带上只拷一个HTML文件过去交互会丢。这个坑我踩过一次之后现在都养成了输出后先本地验证再分享的习惯。6. 一些值得留意的细节与心得用archify这段时间我最深的感受是这类“AI代理技能模块”的组合正在改变我们跟软件系统的交互方式。以前是我们主动去理解系统现在是让AI先去理解再把理解结果用一种更直观的方式呈现给我们。架构图只是一个起点同样的技能思路完全可以扩展到数据流图、网络拓扑图、甚至是业务流程图的生成上。我目前的用法是把archify纳入到团队的文档维护流程里每次大版本重构后让代理重新生成一次架构图再跟前一版对比差异。这样架构演进的历史轨迹一目了然比维护一堆版本混乱的架构文档要靠谱得多。最后分享一个使用心得使用archify时描述需求越具体产出越可用。别只说“生成架构图”而是要说清楚你要“哪部分”的架构、关心“什么类型”的关系、面向“什么角色”的读者。比如“面向后端开发者展示订单模块的完整调用链和依赖方向”和“面向架构评审委员会展示系统分层边界与外部依赖”虽然都是画架构图但生成的图会完全不同。摸清楚这个“输入粒度”和“输出质量”的关系才能把这工具真正用好。