1. 从画图两小时改图一整天说起archify 到底想解决什么如果你做过系统设计或者写过技术方案一定经历过这种场景脑子里架构已经跑通了但要把那张图画出来得打开绘图工具拖方块、连箭头、调对齐、改配色一套操作下来半小时没了。更崩溃的是评审会上有人提了一句这个模块是不是应该拆成两个服务你回去又得重新拖一遍。画图这件事本身不产生任何架构价值但它消耗的时间却实实在在。archify 这个项目瞄准的就是这个痛点。从标题来看它是一个AI 代理自动生成可交互架构图的技能模块。拆开来看有几个关键词AI 代理、自动生成、可交互、架构图、技能模块。这几个词组合在一起指向的是一件事——你不再需要手动拖拽画图而是用自然语言描述你的系统架构AI 代理帮你把图生成出来而且生成的图不是一张死图片是可以点击、可以展开、可以交互的。这跟传统的AI 画图有本质区别。市面上很多工具也能根据文字生成图片但那些生成的是位图你没法改没法交互放大还糊。archify 走的是另一条路——它生成的是结构化的、可渲染的架构图底层大概率是基于某种图形描述语言或者前端渲染框架这样才能做到可交互。那技能模块又是什么意思这个词暗示 archify 不是一个独立的大型应用而是一个可以挂载到现有 AI 代理框架上的能力单元。换句话说它可能是一个 plugin、一个 skill、一个 tool你把它接入自己的 AI 工作流之后代理就多了一项画架构图的本事。这种设计思路在当下的 AI 工具生态里很常见——不重复造代理而是给代理加技能。适合谁来关注这个项目我梳理了一下大概三类人最需要第一类是系统架构师和技术负责人日常要输出大量架构设计文档画图是刚需第二类是技术博主和文档写作者文章里配一张清晰的架构图可读性直接上一个台阶第三类是AI 工具链的搭建者想把架构图生成能力集成到自己的代理系统里archify 的技能模块形态正好合适。下面我会从它的核心机制、交互能力怎么实现、实际怎么用起来、以及我在类似方案上踩过的坑这几个角度把这个项目拆透。2. 拆解 archify 的核心机制从自然语言到可交互架构图2.1 为什么可交互是分水岭而不是锦上添花先说说为什么我特别在意可交互这三个字。很多人觉得架构图嘛能看就行交互不交互无所谓。但实际工作中一张静态图和一张可交互图的价值差距是数量级的。静态图的问题在于信息密度被锁死了。一张图只能表达一个层级的信息你要么画高层概览要么画底层细节没法兼顾。想看某个服务的内部结构对不起另画一张。而可交互的架构图可以做到分层展开——顶层看到的是服务边界和数据流向点击某个服务节点展开它的内部模块再点击某个模块看到它依赖的中间件和存储。这种渐进式披露的能力让一张图承载了原本需要五六张图才能说清的信息。从技术实现角度看要做到可交互架构图的底层表示必须是结构化的数据而不是像素。常见的技术路线有这么几种用JSON 描述节点和边前端用图形库渲染用Mermaid 或 Graphviz 的 DSL描述关系再转成可交互的 SVG或者直接用React Flow、D3.js这类前端图形框架把每个节点做成组件。archify 作为 AI 代理的技能模块我推测它大概率走的是AI 生成结构化描述 → 前端渲染成交互图这条路因为纯靠 AI 直接生成可交互的前端代码稳定性和可控性都太难保证。这里有个经验判断一个 AI 画图工具是否真的可交互最简单的办法是看它输出的中间产物。如果输出的是 PNG/JPG那基本就是死图如果输出的是 JSON、SVG 或者某种 DSL那才有交互的底子。2.2 AI 代理在架构图生成里扮演的角色理解了可交互的底层逻辑再来看 AI 代理在这里面干了什么。很多人以为 AI 生成架构图就是文字转图片其实远不止。一个靠谱的架构图生成流程AI 代理至少要完成三件事第一件是意图理解与结构抽取。你用自然语言描述我有一个网关后面挂三个微服务每个服务连自己的数据库服务之间通过消息队列异步通信AI 要能从这段话里抽取出节点网关、三个微服务、三个数据库、消息队列、边网关到服务、服务到数据库、服务到队列以及边的类型同步调用、异步消息。这一步考验的是模型对架构语义的理解能力而不是单纯的文本生成。第二件是布局决策。节点和边抽出来了怎么摆放是个大问题。架构图的可读性很大程度上取决于布局——分层是否清晰、连线是否交叉、分组是否合理。AI 代理需要决定是用分层布局网关在上、服务在中、存储在下还是用分组布局按业务域聚类。这一步如果做不好生成的图就是一团乱麻。第三件是交互元数据的注入。这是 archify 区别于普通画图工具的关键。AI 在生成图的同时还要给每个节点打上元数据——这个节点属于哪个层级、点击后展开什么内容、鼠标悬停显示什么说明。这些元数据决定了最终图的交互行为。我实测过一些类似的方案发现一个规律AI 在结构抽取上表现普遍不错但在布局决策上容易翻车。尤其是节点数量超过十五个之后布局会明显变乱。所以 archify 如果在这方面做了优化比如内置了几套布局模板让 AI 选择或者引入了自动布局算法做兜底那它的实用性会高很多。2.3 技能模块这个形态意味着什么再聊聊技能模块这个定位。为什么 archify 不做成一个独立的网站或者桌面应用而要做成技能模块这背后其实是对使用场景的精准判断。独立应用的问题是你得专门打开它、专门用它、用完再切回来。而架构图生成这个动作往往不是独立发生的——它嵌入在你的工作流里。你可能正在写设计文档顺手想把架构图生成了你可能正在跟 AI 对话讨论方案聊到某个架构时想让它直接画出来。这种场景下如果画图能力是长在你正在用的 AI 代理身上的体验就顺滑得多。技能模块的形态还带来一个好处可组合。你可以把 archify 和文档生成技能组合让代理先画架构图再写设计文档也可以和代码分析技能组合让代理读你的代码仓库自动生成架构图。这种组合能力是独立应用给不了的。从工程角度看技能模块通常需要定义清晰的输入输出接口。输入可能是自然语言描述或者结构化的架构数据输出应该是可渲染的图描述。接口设计得好不好直接决定了这个技能能不能被灵活调用。如果 archify 的接口设计得足够通用那它的价值就不止于画架构图而是成了 AI 工作流里的一个基础能力单元。3. 可交互架构图的技术底座渲染、布局与交互的三层设计3.1 渲染层为什么结构化描述比直接生成图片更靠谱要理解 archify 这类工具的技术底座得从渲染层说起。前面提到可交互的前提是结构化描述。那结构化描述具体长什么样我拿一个简化版的例子来说明。假设你要描述一个经典的三层架构结构化描述大概是这样{ nodes: [ {id: gateway, label: API 网关, layer: access, type: gateway}, {id: user-svc, label: 用户服务, layer: service, type: microservice}, {id: order-svc, label: 订单服务, layer: service, type: microservice}, {id: user-db, label: 用户库, layer: storage, type: database}, {id: order-db, label: 订单库, layer: storage, type: database} ], edges: [ {from: gateway, to: user-svc, type: sync}, {from: gateway, to: order-svc, type: sync}, {from: user-svc, to: user-db, type: read-write}, {from: order-svc, to: order-db, type: read-write} ] }有了这份描述前端渲染层就可以把它变成一张图。节点按 layer 分层摆放边按 type 用不同的线型实线表示同步、虚线表示异步。点击某个节点可以读取它的 type 和 layer 决定展开什么内容。这种方式的优势很明显同一份描述可以渲染成不同风格的图。你想要横向布局还是纵向布局想要深色主题还是浅色主题改渲染参数就行不用重新生成。而且描述本身是可版本管理的架构变了改描述图自动更新比手动改图靠谱得多。实操提示如果你自己在做类似工具强烈建议把生成描述和渲染图这两步解耦。AI 只负责生成描述渲染交给确定性的代码。这样 AI 出错时你还能手动修描述而不是面对一张没法改的图干瞪眼。3.2 布局层自动布局算法在架构图里的取舍渲染层解决了怎么画的问题布局层解决的是画在哪的问题。架构图的布局比一般流程图更讲究因为它有语义约束——网关就该在上面存储就该在下面同一层的服务应该横向排列。常见的自动布局算法有几种。分层布局Layered Layout适合有明确层级关系的架构它会把节点按依赖关系分成若干层每层内部再横向排列。力导向布局Force-directed Layout适合展示节点之间的关联强度但它不保证层级清晰用在架构图上容易乱。正交布局Orthogonal Layout让所有连线都是横平竖直的视觉上最规整但计算复杂度高。archify 作为 AI 技能模块布局这块我推测它可能采用了AI 决策 算法兜底的混合策略。AI 根据架构描述判断应该用哪种布局然后调用对应的布局算法来实际计算坐标。这样做的好处是兼顾了灵活性和稳定性——AI 负责语义层面的判断算法负责几何层面的计算。我在实际项目里试过纯 AI 布局和纯算法布局两种方案。纯 AI 布局的问题是坐标不稳定同样的描述生成两次节点位置可能差很多看起来不专业。纯算法布局的问题是缺乏语义理解它不知道网关和数据库应该分开放可能把它们排在一起。混合策略是目前看来最靠谱的。3.3 交互层点击展开、悬停提示与层级钻取交互层是 archify 最值得说的部分。一张可交互的架构图至少应该支持这几种交互点击展开/收起。点击一个服务节点展开它的内部模块再点一次收起来。这个交互让一张图能表达多个层级的信息。实现上每个节点需要维护一个展开状态展开时动态渲染子节点。悬停提示。鼠标悬停在节点或连线上显示详细信息——这个服务的负责人是谁、这个接口的 QPS 是多少、这条连线走的是什么协议。这些信息平时不显示避免图太乱需要时再出现。层级钻取。从系统全景图钻取到某个子系统再钻取到某个模块。这需要图支持视图切换不同视图展示不同粒度的节点。搜索与高亮。输入关键词高亮相关节点和路径。这在排查问题时特别有用——你想看某个请求经过了哪些服务搜一下就能把链路高亮出来。这些交互的实现依赖的是渲染层输出的 DOM 结构或者 SVG 元素。每个节点是一个可交互的元素绑定了事件处理器。AI 代理在生成图描述时需要把交互相关的元数据也一并生成比如这个节点可以展开展开后包含哪些子节点。这里有个容易踩的坑交互元数据不要生成得太细。我见过一些方案AI 把每个节点的每个属性都生成成交互内容结果图变得极其复杂用户根本不知道点哪里。好的做法是分层——默认只显示核心信息交互后才显示细节。4. 把 archify 用起来从接入代理到产出第一张图的完整路径4.1 接入前的环境判断你的代理框架支持技能扩展吗在动手接入 archify 之前先确认你的 AI 代理框架是否支持技能扩展。不是所有代理框架都开放了技能接口有些是封闭的你只能用它内置的能力。判断方法很简单看你的代理框架有没有提供注册工具或注册技能的机制。常见的形态有几种一种是函数调用Function Calling你定义一个函数签名代理在需要时调用它一种是插件系统你把技能打包成插件安装还有一种是工作流编排你把技能作为一个节点拖进流程里。如果你的框架支持函数调用那接入 archify 最直接的方式就是把生成架构图定义成一个函数。函数接收自然语言描述返回图描述。代理判断用户想要画图时自动调用这个函数。如果你的框架只支持工作流编排那就把 archify 作为一个独立节点前面接理解需求节点后面接渲染展示节点。注意接入之前先确认你的代理框架能不能处理图描述这种结构化返回。有些框架只支持文本返回那你就需要额外加一个渲染步骤把图描述转成图片或者可嵌入的 HTML。4.2 描述架构的正确姿势给 AI 的输入该怎么写接入之后怎么给 AI 描述架构直接决定了生成质量。我总结了几条经验。先说边界再说内部。描述一个系统时先告诉 AI 这个系统的边界在哪——它包含哪些部分不包含哪些部分。比如这是一个电商下单系统包含网关、订单服务、库存服务、支付服务不包含用户管理和商品管理。边界清晰了AI 才不会乱加节点。说清楚关系类型。不要只说A 连 B要说清楚是什么关系。订单服务同步调用库存服务扣减库存和订单服务通过消息队列异步通知库存服务生成出来的图完全不一样。前者是实线箭头后者是虚线或者带队列图标的连线。给出层级提示。如果你希望图按特定方式分层直接在描述里说。网关放在最上层业务服务放中间层数据库和缓存放最下层。AI 有了这个提示布局会规整很多。控制节点数量。一张图超过二十个节点可读性就会急剧下降。如果系统很复杂建议拆成多张图或者用交互展开的方式分层展示。描述的时候可以主动说这张图只画到服务层每个服务的内部模块先不展开。我试过一个反例把整个微服务集群的所有服务、中间件、数据库、外部依赖一股脑描述给 AI结果生成了一张密密麻麻的图连线交叉得像蜘蛛网完全没法看。后来拆成三张图——接入层、业务层、数据层——每张都清清楚楚。4.3 生成结果的校验与微调哪些地方最容易出问题AI 生成完图别急着用先校验几个地方。节点是否齐全。AI 有时候会漏掉你提到的节点尤其是那些描述得比较靠后的。对照你的描述数一遍节点数量。关系方向是否正确。调用关系的方向特别容易搞反。A 调用 B和B 调用 A是完全不同的架构含义。检查每条边的方向。层级是否合理。看看有没有把数据库画到了服务上面或者把网关画到了最底层。层级错了图的可读性就毁了。连线是否交叉严重。如果连线交叉太多说明布局需要调整。可以尝试在描述里补充布局提示或者手动调整节点顺序。微调的时候如果 archify 支持增量修改就最好了——你说把订单服务和库存服务的位置换一下它只调整这两个节点其他不动。如果不支持增量修改那就得重新生成这时候记得把之前的描述保存好在基础上改。5. 我在类似方案上踩过的坑与实战心得5.1 AI 生成架构图的三个典型翻车场景做这类工具的过程中我踩过不少坑挑三个最典型的说说。第一个坑AI 自作主张加节点。你描述了一个简单的三层架构AI 觉得一个完整的系统应该有缓存和消息队列于是自作主张给你加上了 Redis 和 Kafka。图是好看了但跟你的实际架构不符。这个问题的根源是 AI 的过度补全倾向。解决办法是在描述里明确说只画我提到的组件不要添加任何我没说的东西。第二个坑布局在节点多的时候崩溃。节点少的时候布局很漂亮节点一多就乱套。这是因为很多布局算法的时间复杂度随节点数增长很快节点多了之后要么算得慢要么算出来的结果质量下降。应对办法是控制单张图的节点数量超过阈值就拆分。第三个坑交互元数据丢失。生成图的时候交互是好的但导出或者分享之后交互就没了。这通常是因为导出格式不支持交互比如导出成了 PNG。如果 archify 支持导出记得选支持交互的格式比如 HTML 或者 SVG。5.2 让生成质量稳定的几个实操技巧踩完坑之后我总结了几条让生成质量稳定的技巧。建立描述模板。不要每次都用自由文本描述建立一个模板固定包含系统边界、组件列表、关系列表、层级要求这几个部分。模板化的输入能让 AI 的输出更稳定。分步生成。不要指望一次生成完美的图。先让 AI 生成组件列表确认无误后再让它生成关系最后再生成布局。分步走每步都能校验。保留中间产物。图描述、布局参数这些中间产物都保存下来。下次架构变了在原来的基础上改比重新生成靠谱。准备几套布局预设。常用的架构模式——分层架构、微服务架构、事件驱动架构——各准备一套布局预设。生成时直接套用比让 AI 自由发挥稳定得多。5.3 可交互架构图在团队协作里的真实价值最后说说可交互架构图在团队里的实际价值。我所在的团队用类似方案之后有几个明显的变化。评审效率提升了。以前评审架构大家对着静态图讨论经常出现这个服务内部是什么的追问然后就得另找图。现在一张可交互的图谁有疑问谁自己点开看评审节奏顺畅多了。文档和图的同步问题缓解了。以前架构改了图经常忘了更新文档和图对不上。现在图是从描述生成的描述改了图自动更新一致性有保障。新人上手更快了。新同事了解系统架构以前要翻一堆文档和静态图现在一张可交互的全景图从顶层往下钻取半天就能把系统摸清楚。当然可交互架构图也不是银弹。它解决的是信息展示的问题解决不了架构设计的问题。图再好看架构本身不合理也没用。工具的价值在于让你把精力从画图转移到设计上这才是 archify 这类项目的真正意义。如果你也在做类似的事情我的建议是先把生成描述和渲染图这两步跑通别一上来就追求交互效果。描述生成得准图就成功了一半。交互是锦上添花结构清晰才是根本。