先聊个现象。最近大模型写代码、写文档已经不算新鲜事了真正拉开差距的是那些把模型能力和具体生产工具“缝”在一起的模块。GitHub 上今天要聊的这个项目 archify就是一个典型例子——它把 AI 代理变成了一位“架构图绘图员”只需要一句自然语言描述就能自动生成可交互的架构图。说白了它不是一个画图软件而是给 AI 代理装上的一项技能模块。这类工具解决的是真实痛点以前我们画系统架构图要么手动拖拽框线要么写一堆 Mermaid 代码再反复渲染调试现在可以让 AI 代理直接理解你的系统描述输出结构清晰、可交互的架构图既省了重复劳动又把架构讨论的门槛拉低了一大截。适合谁看后端工程师、架构师、DevOps、技术文档维护者以及所有想折腾 AI Agent 技能扩展的开发者。我从标题和仓库公开信息出发把 archify 的设计思路、核心链路、实操步骤和踩坑经验完整拆一遍。1. 项目定位与核心思路拆解1.1 给 AI 代理装“第三只手”为什么需要架构图技能模块先说清楚 archify 在 AI 代理生态里的位置。现在主流的大模型调用方式有几层最底层是模型本身中间是函数调用Function Calling和工具调用Tool Use再往上就是技能模块Skill对应的是“模型 一系列预置工具 特定场景工作流”的组合包。archify 属于技能模块这一层。它做的事不是重新发明一个画图引擎而是把“理解架构描述”和“渲染可交互图表”这两件事串起来封装成 AI 代理可以直接调用的能力。传统方式是模型输出 Mermaid 代码你还得手动复制到渲染器里看效果archify 的方式是让模型直接调用画图工具输入系统描述输出一张能拖拽、能缩放、能点击跳转的交互图。为什么需要这样一层封装因为直接让模型输出 Mermaid 有几个老问题一是语法错误率高模型经常把节点定义和连线关系写错人工改起来很烦二是表达力受限Mermaid 能画流程图、时序图、状态图但做复杂系统分层和组件关系表达时代码会变得很长很绕三是交互能力几乎为零静态导出图片没法展开细节、没法悬停看注解。archify 这种技能模块把这些问题封装在内部模型只负责“说人话”画图的事交给模块去协调。从架构图这个场景往回看你会发现类似思路在很多领域已经跑通了代码生成、测试用例生成、SQL 生成本质都是“大模型负责语义理解工具负责确定性执行”。架构图生成的难点在于它既有结构性的部分系统有哪些组件、组件怎么连接又有表达性的部分层次怎么排、布局怎么好看、重点怎么突出。把这两部分完全交给模型自由发挥结果不稳定完全靠规则模板又失去了灵活性。archify 的方案是在中间加一层结构化中间表示让模型输出结构让渲染引擎处理表达两边各干各的擅长事。1.2 从文本描述到可交互图archify 的技术路线选择看 GitHub 上这类项目的通用做法再结合 archify 的功能描述它的技术路线大概率是自然语言解析 → 结构化中间表示 → 图数据模型 → 交互式渲染。第一步自然语言解析。用户输入“一个电商系统包含前端、网关、订单服务、支付服务、数据库前端通过网关调用订单服务订单服务依赖数据库支付服务通过异步消息与订单服务通信”这样一段描述。AI 代理要做的是从中抽取实体和关系。这一步通常交给大模型来完成因为实体抽取和关系识别正好是语言模型的长项。但光有实体和关系还不够还需要约定俗成的规范化输出比如统一用“service”“database”“queue”这类类型标签方便后续映射成图节点。第二步结构化中间表示。这一步很关键它是整个模块能稳定工作的“翻译层”。模型输出不能直接丢给渲染器得先转成统一的 JSON 或 YAML 结构包含节点列表id、名称、类型、属性和关系列表source、target、关系类型。有了这层中间表示后面换渲染引擎、加布局算法、做交互扩展都容易。这也是 archify 这类技能模块比“prompt 输出 Mermaid 代码”更可靠的根本原因——它把不确定性挡在中间表示之外。第三步图数据模型。拿到中间表示后模块内部会把它转换成图数据结构通常是节点Node和边Edge的集合。这一步要处理几个问题节点去重、关系校验比如引用了不存在的节点、类型归一化把“MySQL”“PostgreSQL”“redis”统一归为“database”类。这层数据模型是后续所有交互能力的基础因为可交互的本质就是“图数据 渲染器 事件绑定”没有干净的图数据后面全是空中楼阁。第四步交互式渲染。渲染层选择很多可以在网页里用 D3.js、AntV G6、Cytoscape.js 这类图可视化库也可以生成 Mermaid 再套一层交互脚本还可以生成 SVG 并绑定点击事件。archify 如果主打“可交互”大概率是基于某个成熟图可视化库做封装支持缩放、拖拽、节点点击展开详情、边高亮等功能。渲染层的核心工作是布局——图数据本身没有坐标布局算法负责把节点安排得好看且不重叠常用的有力导向布局Force-directed、层次布局Layered、圆形布局等架构图场景更适合层次布局或自定义分组布局因为能体现分层和边界。1.3 为什么选“技能模块”而不是“独立应用”archify 以技能模块的形式出现而不是做成一个独立 App这个定位本身就有讲究。独立应用的问题在于你画图时得切换上下文把架构描述从聊天窗口复制到画图工具里生成后又复制回来链路是断的。技能模块直接寄生在 AI 代理内部代理在对话中就能完成“理解 → 生成 → 渲染 → 反馈”的闭环。另外技能模块还意味着可组合性。AI 代理工作流里常常需要多个技能协同先用代码分析技能扫描项目结构再把扫描结果作为输入交给 archify 生成架构图最后用文档技能自动生成架构说明。这种组合能力是独立应用很难提供的。所以 archify 这种“被集成”的姿态反而让它更容易嵌入各种 Agent 工作流——无论是个人开发的自动化脚本还是企业级的运维分析平台。2. 核心细节解析与实操要点2.1 架构图生成链路里最容易被忽略的三个环节很多人以为架构图生成的难点是“让模型理解架构”实际上真正决定成败的是三个容易被忽略的环节。第一个环节是系统边界识别。用户描述一个系统时经常混着说既有业务组件又有基础设施还有外部依赖。如果模型不区分这些边界生成的图就是一大坨节点看不出系统的层次。好的实现在中间表示阶段就要给节点打上“层级”或“域”标记比如前端层、应用层、数据层、基础设施层、外部系统渲染时按域着色、按层分组图的可读性立刻不一样。第二个环节是关系类型标准化。用户可能说“A 调用 B”“A 依赖 B”“A 发消息给 B”“A 连接 B”这些在语义上是有区别的但模型如果只把它们都归为“关系”图就少了很多信息。实操中最好预设一套关系类型比如 HTTP 调用、异步消息、数据库读写、配置依赖、网络连接渲染时用不同线型或颜色区分。这样一眼扫过去就能看出系统的通信模式和耦合点。第三个环节是属性补全。光有节点和关系图能看但不够“可交互”。所谓可交互不只是能拖拽缩放更重要的是点开一个节点能看到详细信息。所以中间表示里要给节点预留属性位组件描述、负责人、技术栈、告警链接、日志入口、代码仓库地址。这些信息可能来自用户描述也可能来自模型知识补全也可能通过其他工具自动抓取。archify 这类模块如果做得好会在生成图的同时生成一份节点属性表交互时动态展示。2.2 可交互能力到底指什么从“能拖动”到“能作战”“可交互架构图”这个词不同项目含义差很多。最简单的交互是画布操作——拖拽、缩放、全屏中等程度的交互是节点行为——点击高亮关联边、双击展开子图、悬停显示信息卡片高阶交互则是图与外部系统联动——点击一个服务节点跳转到该服务的监控看板点击一条调用链展示链路追踪数据点击一个数据库节点打开慢查询报表。archify 如果要做成真正有用的技能模块不能停留在“能拖动”这一步。实战中架构图最大的价值是作为“系统作战地图”故障排查时从入口到依赖一路点过去快速定位可疑环节容量评估时通过边的粗细或颜色看出哪些链路的流量最高架构评审时把图导出来作为讨论底稿。要达到这些效果交互能力必须在图数据阶段就规划好而不是渲染时临时加效果。这也是我建议你在评估同类项目时重点看的维度它的交互是装饰性的还是数据驱动型的。从实现角度看数据驱动型交互一般是给每个节点绑定一个“元数据对象”渲染时预埋事件钩子点击事件触发时弹窗内容从元数据对象里读取。如果节点元数据里连的是外部 URL点击就能跳转如果挂着内部 API点击就能拉取最新状态。这些能力 Archify 如果开放了配置入口使用价值会大幅提升。2.3 模型选择与 Prompt 设计决定生成质量的隐藏因素技能模块的表现一半看封装设计一半看底层模型。实操中我有两个心得。第一模型能力至少要达到“能可靠输出结构化 JSON”的水平。因为 archify 要把自然语言转成中间表示如果模型连 JSON 格式都经常出错后面的渲染步骤就会频繁卡壳。实测下来当前主流的旗舰模型在架构描述解析上表现都不错但有个典型差异有的模型擅长抽取实体却经常把“依赖”和“调用”混为一谈有的模型擅长关系分类但会漏掉隐式依赖比如“支付服务通过异步消息与订单服务通信”如果描述里没有明确说消息队列模型容易把这条边画成直接调用。这一类问题靠 prompt 提示很难根治所以我建议在模块里内置一个“关系后处理”步骤用规则兜底。第二Prompt 里一定要内置角色和目标约束。“你是资深架构师请从以下描述中抽取系统组件和依赖关系并按 JSON 格式输出组件类型限定为……”这类约束式 prompt 比开放式“帮我画个架构图”稳定得多。还可以在 prompt 中附加输出示例让模型照葫芦画瓢。我踩过的坑是不限制输出格式时模型偶尔会夹带“解释性文字”导致 JSON 解析失败。在技能模块里预置一个格式解析容错层比如从模型输出中提取首个 JSON 代码块能显著提高成功率。3. 实操过程与核心环节实现3.1 环境准备与模块安装如果你想把 archify 跑起来第一步是搞清楚它运行在什么环境里。以目前 AI 技能模块的通用做法来看它大概率是一个 Python 包或 Node 模块需要配合大模型 API 使用。安装层面无非是克隆仓库、安装依赖、配置 API Key 这几件事。# 克隆仓库 git clone https://github.com/你的账号名/archify.git cd archify # 安装依赖以 Python 为例 pip install -r requirements.txt # 配置环境变量 export OPENAI_API_KEYsk-你的密钥 # 或者如果你用本地模型 export ARCHIFY_MODEL_ENDPOINThttp://localhost:11434配置完成后建议先跑一遍官方自带的示例脚本确认整条链路能通。这里提醒一点不要跳过示例直接上生产因为你首先要搞清楚模块默认调的是哪个模型、默认输出格式长什么样、渲染结果输出到哪里。这些信息在 README 里通常有说明但最好亲自跑一遍确认。3.2 最小示例让 AI 代理生成第一张架构图以我习惯的方式我会先设计一个最小测试用例一个包含三个组件和一个外部依赖的极简系统比如“用户通过 Nginx 访问后端 APIAPI 读写 PostgreSQLPostgreSQL 主从同步”。这个用例结构简单但覆盖了分层、调用、数据存储、内部关系足够验证核心链路。调用 archify 的方式通常有两种一是通过命令行工具直接传入描述文本二是把它作为函数工具注册到 AI 代理框架里。命令行方式适合测试函数调用方式适合集成。命令行方式大概长这样python -m archify generate \ --description 用户通过 Nginx 访问后端 APIAPI 读写 PostgreSQLPostgreSQL 主从同步 \ --format html \ --output ./output/architecture.html执行后模块内部会经历这样几个步骤把描述文本发给大模型要求返回结构化中间表示。解析模型输出校验 JSON 格式合法性提取节点和关系。做关系归一化和节点去重。调用渲染引擎生成可交互 HTML 页面输出到指定路径。打开生成的 HTML 文件你应该能看到一张包含四个节点的架构图Nginx 在最外层API 在中间PostgreSQL 作为数据层主从关系用特殊线型表示。鼠标悬停在 API 节点上应该能看到模块自动补全的描述信息拖动画布图能跟随缩放移动。3.3 让 AI 代理真正“调用”archify函数注册实战如果你用的是现在主流的 AI 代理框架比如 LangChain、LlamaIndex或者自己写的 Function Calling 调度层把 archify 接进去的思路大同小异把它包装成一个工具函数让模型在需要画图时主动调用。伪代码思路如下def generate_architecture_tool(description: str) - str: 生成可交互架构图返回 HTML 文件路径 result archify.generate( descriptiondescription, formathtml, output./agent_output/architecture.html ) return result.file_path # 注册到工具的加载配置里 tools [ { name: generate_architecture, description: 根据系统描述生成可交互架构图。当用户需要架构分析、系统设计可视化时调用。, parameters: { type: object, properties: { description: { type: string, description: 系统架构的自然语言描述应包含组件和相互关系。 } }, required: [description] }, function: generate_architecture_tool } ]这里有个细节值得展开工具描述description怎么写直接决定模型会不会主动调用。你写“生成架构图”太笼统模型拿不准什么时候该用它你写“当用户需要架构分析、系统设计可视化、组件关系梳理时调用”模型就更可能在合适时机触发。这就是工具调用的“触发条件设计”比想象中重要。模型判断要画图时会自动生成符合参数结构的 JSON你的调度层解析后调用generate_architecture_tool拿到返回路径后再以 Markdown 链接形式把结果回复给用户。整个链路跑通后用户在你自己的 Agent 对话框里输入一句“帮我画一下当前项目的架构图”模型会自动完成后续所有事。3.4 进阶接入本地模型与私有化部署不少团队对大模型 API 有数据安全顾虑更倾向用本地模型跑这类技能模块。只要你本地推理服务支持 OpenAI 兼容接口archify 这类模块通常都能切换 base_url 完成适配。常见做法是配一个兼容层export OPENAI_BASE_URLhttp://localhost:11434/v1 export OPENAI_MODEL_NAMEqwen2.5:14b接入本地模型后要调整预期。拿 7B 到 14B 量级的模型来测试我发现它们做简单系统描述四到八个节点的实体抽取基本够用但在关系类型分类和边界识别上错误率明显比旗舰模型高。解决思路是加重规则后处理实体抽取交给模型关系归一化交给规则两者结合能兼顾灵活性和稳定性。另一个私有化场景是渲染层离线部署。可交互架构图画出来后如果要嵌入内部 Wiki 或运维平台不能只输出本地 HTML 文件通常需要把渲染产物部署成静态资源或者封装成一个微服务提供 URL。实操时可以把生成的 HTML JS CSS 产物丢到 Nginx 或对象存储里再通过 iframe 嵌入内部系统。4. 常见问题与排查技巧实录4.1 高频问题速查表把我在类似项目里实际遇到的问题梳理一遍按出现频率从高到低排序现象可能原因解决思路调用后没有输出API Key 未配好或模型服务超时先跑官方示例确认链路再排查网络和 key 配置图生成成功但节点错乱模型抽取实体时产生了幻觉节点在中间表示校验层去掉不在合法类型清单里的节点交互点击没反应渲染层事件绑定失败或元数据缺失检查节点元数据对象是否完整确认事件是代理绑定而非内联布局重叠严重节点数过多单一布局算法失效启用按域分组布局把大图拆成多层视图中文乱码渲染层字体未覆盖 CJK 字符在 HTML 模板中显式引入中文字体或让节点标签走图片渲染模型不主动调用工具工具描述写得太窄或太宽重写触发条件补充“架构分析”“可视化”“系统设计”等触发词4.2 我实测下来的关键教训第一永远不要在生成链路里省掉中间表示校验层。一开始为了省事我只做了 JSON 合法性解析不校验节点类型和关系方向结果模型稍微飘一下就生成出“数据库调用 Nginx”这种离谱关系。补上类型白名单和关系方向校验后输出稳定性大幅提升。第二把“补全属性”的功能从模型完全自由生成改为“模型生成 模板互补”。比如服务节点默认补上“端口号”“健康检查路径”这些字段即使模型没提到模板也能填上默认值配合未知标记表示待确认。这样生成的图不会因为缺字段而显得空。第三可交互图不是一次生成就完事的后续修改同样重要。我强烈建议你在 archify 的使用流程里加一个“反馈修订”环节生成第一版图后用户可以用自然语言提出修改意见比如“把支付服务放到独立域”“给订单服务加一条到日志服务的虚线”模块再调一次模型输出修订版中间表示重新渲染。这一个来回的交互感远比一次性生成来得实用。4.3 排查思路的通用套路遇到 archify 表现异常先别急着怀疑项目 bug按这个顺序排查效率最高先看输入描述文本本身是否含糊。换个角度说任何画图工具面对“画出系统的架构”这种描述都不可能比“前端 Vue3 通过 HTTPS 调用后端 Spring Boot 的 8 个 REST 接口后端连接 MySQL 8.0 和 Redis 7Redis 用于会话缓存MySQL 做了主从复制”这种描述生成得更好。输入质量决定输出下限。再看模型输出把模块内部发往模型的 prompt 和模型返回的原始结果打出来逐字段核对。这一步能区分问题出在“模型理解错误”还是“模块解析错误”。最后看渲染端如果中间表示没问题但渲染效果不对问题一定在渲染层这时候要检查渲染库版本、布局参数、交互事件绑定代码。5. 扩展思路archify 不只能画系统架构图5.1 架构治理与文档联动一个很容易被忽略的场景是把 archify 接入架构治理流程让架构图“活”起来。传统架构文档的痛点是画完即过时代码变了文档没变。如果 archify 能配合代码扫描技能使用让 AI 代理先扫描项目代码结构再根据扫描结果自动更新架构图那架构图就从“一次性产物”变成了“持续更新的系统地图”。更实用的一种联动是架构评审自动化当开发提交了某个模块的改动可以让 AI 代理基于改动描述生成“前后对比架构图”评审者在图上直接看到受影响的服务和依赖路径。这个玩法对大型微服务系统特别有价值省掉的是一张一张翻调用关系的时间。5.2 从架构图到运维作战地图再把视野拉大一些。架构图如果只停留在“给人看”价值是有限的一旦和监控数据、链路追踪打通它就变成了运维作战地图。具体做法是在节点元数据里挂上监控系统的查询 URL点击节点时 iframe 嵌出该服务的实时曲线在边上挂上调用链路的聚合指标流量异常时边的颜色自动变红。这些联动做得越深架构图在日常排障中的使用频率就越高。我个人的体会是真正能落地的架构可视化工具不是画得好看而是“图里每一个点都能点出有价值的东西”。archify 这类技能模块给了我们一个很好的起点让 AI 代理先把图的结构画出来剩下的信息丰富度完全看你往里接多少数据。5.3 多模态输出的想象空间最后聊一个扩展方向。目前大多数架构图工具输出的是 SVG、HTML、PNG交互集中在浏览器内。但 archify 这类技能模块如果做得深完全可以在中间表示层之上做不同渲染出口导出 PPT 里的矢量图、生成 Notion 里可嵌入的看板块、输出 PlantUML 代码给遗留文档体系用、甚至生成 3D 分层视图应对超大规模系统可视化。这也回到这个项目的核心价值它在“模型理解”和“可视化表达”之间做了一层解耦。只要中间表示足够规范下游输出形态可以无限扩展。你在研究 archify 源码时重点看它的中间表示设计成什么样这决定了你对它后续扩展空间的判断。整个项目看下来我最大的体会是AI 代理时代真正稀缺的不是模型的想象力而是把想象力变成标准产物的工程能力。archify 的价值恰恰在于它给出了一条从自然语言到可交互架构图的确定性路径这条路足够窄但足够实用。如果你正在搭自己的 Agent 工作流不妨把它当作一个范本找一个高频、重复、需要视觉产出的场景用同样的思路封装一个技能模块你也会发现工具的威力比想象中更大。最后再分享一个小技巧动手改造之前先把官方的示例输入输出跑熟再打开源码看它中间表示的定义——你会少走很多弯路。