架构图Agent爆火，如何用LLM将自然语言变成可维护的架构图？

这几天 GitHub 热榜上很有意思的现象一个专注“架构图生成”的 Agent 项目连续多天排在热度第一很多开发者都在讨论它相关的架构图、Agent、大模型工具链话题也跟着上了热榜。如果你平时画过架构图应该能理解它为什么这么受关注画图本身不难难的是把脑子里模糊的想法梳理成一张清晰、分层、能给人讲明白的图。这篇文章不打算只复述“有个项目火了”而是想认真拆解三件事架构图生成为什么适合做成 Agent它和传统画图工具、AI 生图工具的本质区别在哪里以及如果你想在自己的项目里接入这类能力应该从哪一步开始落地。文章会包含完整的最小代码实现、运行验证方式和一整套排错思路适合想追这个技术热点、又不想只停留在收藏夹里的开发者。我的判断是架构图 Agent 的价值不在“自动画图”这个表面功能而在于它把“画图”这个动作变成了“可对话、可迭代、可评审、可版本化”的工程流程。这才是它真正值得关注的地方。1. 架构图 Agent 为什么突然火了先聊一个很现实的问题为什么很多开发者宁愿写一千行代码也不想画一张架构图因为画架构图的过程中真正的成本不是拖动框线而是思考。你要想清楚系统有哪些模块、模块之间是什么关系、数据流怎么走、哪些是同步调用哪些是异步消息、部署上又分成几层。这些信息通常分散在代码、配置、文档和人脑子里画图本质上是在做一次“架构决策可视化”。传统画图工具比如 Visio、draw.io、ProcessOn解决的是“怎么画出来”它们不帮你解决“画什么”和“为什么这么画”。于是常见的场景就变成了架构师先要在文档里写一大段文字描述再对着文字去拖图框画完发现某个模块划分不对又得重画。整个过程既低效又很难让团队其他人参与修改。架构图 Agent 火起来是因为它把这条链路改掉了。交互方式从“拖拽图形”变成“用自然语言描述系统”工具从“图形编辑器”变成“Agent 程序”输出物从“图片文件”变成“一份可追溯、可修改的图表脚本”。这不是简单的 AI 自动生成图片而是把画架构图这件事从手工劳动变成了一种“人机对话式的设计过程”。所以它在 GitHub 热榜上连续多天排第一背后反映的是一个真实需求大量开发者在日常工作中都需要画架构图而现有的工具链已经明显跟不上“快速迭代、频繁评审、多版本维护”的节奏了。这个现象对普通开发者的启发是与其等别人把产品做得更完善不如先理解它是怎么运作的然后把它接进自己的技术方案输出流程里。2. 什么是架构图 Agent核心概念与原理很多人第一次听说“架构图 Agent”时会误以为它是类似 Midjourney、Stable Diffusion 那样的 AI 生图工具。这是最常见的一个误区。AI 生图走的是“像素生成”路线模型输出的是图片的像素分布你很难控制某条线连到哪个节点也很难在生成后单独修改一句话。而架构图生成走的是“结构生成”路线模型输出的是一段结构化的文本描述再由渲染引擎把它变成图片。这个结构化文本就是架构图 DSL常见的格式有 Mermaid、PlantUML、Graphviz DOT 等。所以正确的理解方式是这样一条管线自然语言描述 - LLM 生成结构化 DSL - 渲染引擎 - 架构图图片/SVG这条管线里最关键的不是“画图”这一步而是中间那一层 DSL。它的存在意味着你生成的架构图不再是不可编辑的图片而是一份可以被 diff、被 review、被版本管理的源码。这才是架构图 Agent 和传统工具拉开差距的根本原因。那它为什么叫“Agent”而不是简单叫“AI 画图工具”因为 Agent 具有几个传统工具不具备的能力理解上下文。你可以告诉它“前端服务通过 Nginx 接入后端分为订单和用户两个服务共用一套 MySQL”它能理解这些实体之间的关系。调用工具。Agent 不只生成文本它可以通过函数调用拿到代码仓库里的目录结构、读取接口定义甚至把生成的 DSL 直接渲染成图片。多轮迭代。画完初稿后你可以说“把网关层单独拆出来”“数据层加上 Redis”它会基于上一次的结果修改而不是从头再生成一遍。保持一定程度的记忆。比如你告诉过它“用蓝绿配色数据库放在底部”它可以在后续修改时沿用这些偏好。把这些能力组合起来架构图 Agent 才真正称得上“Agent”而不只是一个套了提示词的脚本。再看它和传统方式的对比对比维度传统画图工具AI 生图工具架构图 Agent交互方式手动拖拽图形输入提示词生成图片自然语言对话 多轮修改输出形式图片 / 源文件像素图结构化 DSL 渲染图可编辑性依赖工具格式基本不可编辑DSL 可直接修改可追溯性较差较差可版本管理、可 diff是否理解架构语义不理解不理解理解实体与关系是否适合团队协作一般差适合评审和协作表格里的最后一列就是架构图 Agent 真正的护城河它让架构图从“一次性产物”变成了“可持续维护的资产”。3. 适用场景与边界判断聊完原理必须聊边界。因为任何技术都有适合它的场景架构图 Agent 不是万能的。从目前的实践来看它适合处理这样几类需求第一类是系统设计阶段的草图。项目启动时你脑子里有一个大致的模块划分但还没有细化到每个接口。这时用自然语言把模块、依赖、数据流描述出来Agent 能快速生成一版初稿。这个初稿的意义是“把想法从脑子里拽出来”先让团队看到全貌再慢慢修改。第二类是技术方案评审辅助。很多团队做设计评审时都是贴一张图然后开始讲。架构图 Agent 可以做到“图随文走”需求文档里改了描述重新生成一版架构图评审会上直接对比新旧版本讨论“为什么这里多了一层”“为什么这个服务要拆开”这类问题。第三类是代码库逆向梳理。现在不少 Agent 框架支持读取代码仓库结构根据实际代码目录和依赖关系生成架构图。这个场景下图的准确性更容易验证因为它是基于真实代码生成的而不是基于模型记忆生成的。第四类是文档配图和面试讲项目。写技术博客、做项目复盘、准备架构师面试时需要快速画一张能讲清楚项目全貌的图。这类图对精确度要求不高但对结构清晰度要求很高正好是 Agent 的强项。但它不适合的场景也很明确精确的运维网络拓扑。涉及具体 IP、端口、防火墙策略、流量路径的图不能用生成式 Agent 来做容易产生幻觉必须依赖真实的运维配置数据。安全合规要求高的架构文档。如果架构图会暴露内网结构、敏感服务清单不建议把完整信息喂给外部大模型服务应该使用私有化部署模型或者在输入前做脱敏。超大规模系统全局图。几千个节点、上万条依赖的全局架构图任何工具生成出来都是灾难。这个场景的正确做法是分层画、按领域拆分。这里可以给一个简单判断标准如果你需要的是“辅助思考、梳理结构、可视化讨论”的架构图Agent 很合适如果你需要的是“精确反映线上真实状态”的架构图应该走 CMDB、链路追踪、配置管理这些真实数据源而不是靠生成式模型。4. 环境准备与基础配置下面进入实操部分。我们写一个最小可用的架构图 Agent不依赖任何重框架核心思路是用大模型把自然语言转换为结构化 JSON再把 JSON 渲染成 Mermaid DSL最后通过命令行工具导出图片。这个方案足够轻量逻辑清楚后续也方便替换成你自己的 Agent 框架。整篇文章不会绑定某个特定版本的 SDK不同阶段请以你实际项目使用的版本为准但设计思路是通用的。环境准备如下Python 3.9 或更高版本。一个可调用的大模型 API或本地部署的模型服务。示例代码按 OpenAI 兼容接口来写国内主流模型服务和许多本地推理服务都提供了兼容接口替换配置即可。pip 安装必要的依赖openai 用于调用模型接口graphviz 或 mermaid-cli 用于渲染。目录结构建议这样组织architecture-agent-demo/ ├── agent.py # Agent 主逻辑负责调用模型和解析输出 ├── render.py # 渲染模块负责 JSON 转 Mermaid DSL ├── tools.json # 工具定义展示 Agent 工具注册方式 └── output/ ├── demo.json # 模型生成的结构化架构数据 └── demo.mmd # 渲染后的 Mermaid 源码安装依赖时只需要安装 Python 侧的依赖pip install openai graphviz如果你希望最终生成 PNG还需要安装系统级的 graphviz 组件或者使用 npm 安装 mermaid-cli。二选一即可本文示例使用 graphviz 渲染因为它在 Python 环境里接入更直接。如果本地没有可用的模型 API建议先准备一个 API Key并确认接口地址。可以在代码里通过环境变量注入避免把密钥硬编码进去。export LLM_API_KEY你的API Key export LLM_BASE_URLhttps://api.example.com/v1这里要特别提醒不要把密钥写进代码仓库。示例代码里虽然会出现配置字样但真实项目应该用环境变量、配置中心或密钥管理服务来保存。5. 动手实现一个最小架构图 Agent5.1 设计思路整个 Agent 的核心就三步系统提示词约束模型把用户的自然语言架构描述转换为固定结构的 JSON。校验 JSON 中的节点和边是否合法。将 JSON 渲染成 Mermaid 源码。固定结构是保证可靠性的关键。如果不做结构化约束模型可能输出一段散文也可能输出一份 Markdown 表格后续处理会很痛苦。所以我们在系统提示词里把 JSON Schema 写死然后要求模型只输出 JSON。5.2 完整代码调用大模型生成结构化 JSON先写 Agent 主逻辑文件路径agent.py。# 文件路径architecture-agent-demo/agent.py import json import os from openai import OpenAI client OpenAI( api_keyos.getenv(LLM_API_KEY), base_urlos.getenv(LLM_BASE_URL), ) SYSTEM_PROMPT 你是一名资深系统架构师。用户会用自然语言描述一个软件系统的组成和关系。 你的任务是把用户的描述转换成一个 JSON 对象只输出 JSON不要输出任何解释性文字。 JSON 结构必须严格遵守 { title: 系统名称, nodes: [ {id: web, label: Web前端, layer: 接入层}, {id: api, label: API服务, layer: 应用层}, {id: db, label: MySQL, layer: 数据层} ], edges: [ {from: web, to: api, label: HTTP调用}, {from: api, to: db, label: 读写} ] } 要求 1. id 使用英文小写字母多个单词用下划线连接。 2. layer 只能是接入层、应用层、数据层、中间件层、基础设施层之一。 3. 根据用户的描述合理补充拓扑中缺失的关键节点但不要虚构没有依据的组件。 4. 节点数量控制在 5 到 15 个之间。 5. 如果用户描述中有明确的调用关系必须体现在 edges 中。 def generate_architecture(description: str) - dict: response client.chat.completions.create( modelos.getenv(LLM_MODEL, gpt-4o-mini), messages[ {role: system, content: SYSTEM_PROMPT}, {role: user, content: description}, ], temperature0.3, response_format{type: json_object}, ) content response.choices[0].message.content return json.loads(content) def save_json(data: dict, path: str output/demo.json) - None: os.makedirs(os.path.dirname(path), exist_okTrue) with open(path, w, encodingutf-8) as f: json.dump(data, f, ensure_asciiFalse, indent2) if __name__ __main__: user_input 一个电商系统用户通过浏览器访问 NginxNginx 转发到订单服务和商品服务两个服务都读写同一个 MySQL订单服务创建订单后向消息队列发送消息消费者服务处理消息并更新库存。 result generate_architecture(user_input) save_json(result) print(json.dumps(result, ensure_asciiFalse, indent2))这段代码里的几个细节值得注意第一response_format{type: json_object}是让模型输出合法 JSON 的关键开关。不同模型服务对这个参数的兼容程度不同如果你的服务不支持可以去掉这个参数但在提示词里必须更严格地强调“只输出 JSON”。第二temperature设置为 0.3。生成架构图不是创意写作而是结构化产出。温度太低容易呆板但温度太高会导致节点命名和层级关系不稳定0.3 是一个相对稳妥的起点。第三提示词里写清楚了节点数量的范围这是为了避免模型一次生成几百个节点导致图完全没法看。实际使用中这个数量应该根据你的系统复杂度调整。5.3 渲染模块JSON 转 Mermaid DSL拿到结构化 JSON 之后还要把它变成人能看的架构图。这里用 Mermaid DSL 作为中间格式。# 文件路径architecture-agent-demo/render.py import json import subprocess import os def json_to_mermaid(data: dict) - str: lines [] lines.append(graph TB) lines.append(f title[\{data[title]}\]) layer_styles { 接入层: #style 接入层 fill:#E3F2FD,stroke:#1565C0, 应用层: #style 应用层 fill:#E8F5E9,stroke:#2E7D32, 数据层: #style 数据层 fill:#FFF3E0,stroke:#E65100, 中间件层: #style 中间件层 fill:#F3E5F5,stroke:#6A1B9A, 基础设施层: #style 基础设施层 fill:#ECEFF1,stroke:#455A64, } for node in data[nodes]: node_id node[id] label node[label] layer node.get(layer, 应用层) lines.append(f subgraph {layer}[\{layer}\]) lines.append(f {node_id}[\{label}\]) lines.append( end) for edge in data[edges]: from_id edge[from] to_id edge[to] label edge.get(label, ) if label: lines.append(f {from_id} --|{label}| {to_id}) else: lines.append(f {from_id} -- {to_id}) return \n.join(lines) def render_mermaid(mmd_text: str, output_dir: str output, filename: str demo) - str: os.makedirs(output_dir, exist_okTrue) mmd_path os.path.join(output_dir, f{filename}.mmd) with open(mmd_path, w, encodingutf-8) as f: f.write(mmd_text) return mmd_path if __name__ __main__: with open(output/demo.json, r, encodingutf-8) as f: data json.load(f) mmd json_to_mermaid(data) path render_mermaid(mmd) print(fMermaid 源码已保存到: {path}) print(mmd)这一步生成的.mmd文件就是你的架构图源码。后续无论怎么修改都可以基于这份源码做 diff团队评审时也能清楚看到每次改动到底动了哪些节点和连线。如果你希望直接看到图片效果可以安装 mermaid-cli然后执行npx mmdc -i output/demo.mmd -o output/demo.svg该命令会渲染出一张 SVG 格式的架构图可以用浏览器打开查看。5.4 工具注册与 Agent 编排思路很多 Agent 项目不只是“文字生成 DSL”而是通过“工具调用”来组织能力。以tools.json为例展示如果你的架构图 Agent 要接进一个更大的 Agent 框架工具定义应该怎么设计。{ tools: [ { name: generate_architecture_json, description: 将自然语言架构描述转换为结构化的节点和边 JSON, parameters: { type: object, properties: { description: { type: string, description: 用户描述的系统架构 } }, required: [description] } }, { name: render_architecture_diagram, description: 将架构 JSON 渲染为 Mermaid 源码并保存到文件, parameters: { type: object, properties: { architecture_json: { type: object, description: 包含 nodes 和 edges 的架构描述 }, output_filename: { type: string, description: 输出文件名默认 demo } }, required: [architecture_json] } }, { name: read_project_structure, description: 读取代码仓库的目录结构用于从真实代码生成架构图, parameters: { type: object, properties: { root_path: { type: string, description: 项目根目录路径 } }, required: [root_path] } } ] }工具注册的意义在于Agent 框架会从你的自然语言中选择合适的工具而不是每次都走同一条固定链路。比如用户说“根据我这个项目的代码生成架构图”Agent 就会先调用read_project_structure读取目录再调用generate_architecture_json生成结构化数据。这套思路是可以平滑升级的也就是从今天这个最小 Demo演进到完整 Agent 应用时核心逻辑不变只是多了一层调度。5.5 完整工作流跑一次把上面的文件都保存好后按顺序执行python agent.py python render.py npx mmdc -i output/demo.mmd -o output/demo.svg第一步会生成output/demo.json里面是模型输出的结构化架构数据第二步会把它变成 Mermaid 源码第三步导出可视化图片。如果你的环境没有安装 Node.js 和 mermaid-cli也可以直接用下面的代码调用 graphviz 渲染# 文件路径architecture-agent-demo/render_graphviz.py from graphviz import Digraph def render_with_graphviz(data: dict, filename: str architecture) - None: dot Digraph(namedata[title], formatpng) for node in data[nodes]: dot.node(node[id], node[label]) for edge in data[edges]: dot.edge(edge[from], edge[to], labeledge.get(label, )) dot.render(filenamefoutput/{filename}, viewFalse)两条渲染路径都可以选你环境里装起来更顺手的那条。核心是Agent 负责生成结构渲染引擎负责出图两者解耦。6. 运行结果与效果验证我们用上一节的电商系统示例跑一遍预期的 JSON 输出大致是这样的结构{ title: 电商系统, nodes: [ {id: user, label: 用户浏览器, layer: 接入层}, {id: nginx, label: Nginx, layer: 接入层}, {id: order, label: 订单服务, layer: 应用层}, {id: product, label: 商品服务, layer: 应用层}, {id: mysql, label: MySQL, layer: 数据层}, {id: mq, label: 消息队列, layer: 中间件层}, {id: consumer, label: 库存消费者, layer: 应用层} ], edges: [ {from: user, to: nginx, label: HTTPS}, {from: nginx, to: order, label: 反向代理}, {from: nginx, to: product, label: 反向代理}, {from: order, to: mysql, label: 读写}, {from: product, to: mysql, label: 读写}, {from: order, to: mq, label: 发送消息}, {from: mq, to: consumer, label: 消费消息} ] }这里需要注意两点第一模型生成的节点 ID 可能和你预想的不一样但只要 JSON 结构合法渲染就不会出问题。这也是为什么我们要强调“结构约束优先”而不是“名称约束优先”。第二判断架构图是否生成成功不能只看“有没有图”还要看三点节点是否完整覆盖了用户描述中的关键组件。边的方向是否符合真实调用关系。这里特别容易出错的是反了方向比如把“Nginx 转发到服务”写成“服务转发到 Nginx”。分层是否合理。数据库不应该出现在接入层消息队列不应该出现在数据层。如果生成的图出现了明显的语义错误不需要重写整个提示词直接多轮对话要求修正即可“把商品服务和订单服务之间的依赖关系表达清楚两个服务不直接互调。”7. 常见问题与排查思路问题现象可能原因排查方式解决方案模型返回的不是合法 JSONresponse_format 参数不被模型服务支持查看返回的原始字符串去掉 response_format并在提示词中强调“只输出 JSON”生成的节点过多图非常混乱提示词未限制节点数量检查 JSON 中 nodes 数组长度在系统提示词中增加“节点数量控制在 5 到 15 个之间”的约束边的方向经常反模型没有理解调用方向查看 edges 数组的方向在提示词中明确“from 是调用方to 是被调用方”Mermaid 渲染中文乱码渲染引擎字体不支持中文查看 SVG 中的中文字符更换系统字体或在渲染命令中指定中文字体反复修改不收敛没有把历史偏好写入上下文检查每次请求是否携带了历史记录用一个变量保存用户偏好在每轮请求中拼接进 messages生成的架构图与真实代码不符模型根据猜测生成没有基于真实代码查看是否调用过代码读取工具增加读取项目目录结构的工具并显式要求模型基于真实目录生成Mermaid 渲染报错节点 ID 包含特殊字符查看报错信息中的 ID 字段生成 ID 时过滤非字母数字和下划线排错的第一步永远是打印原始返回内容。不要让程序静默失败建议在调用模型后先print(response.choices[0].message.content)确认模型输出是否符合预期再决定是修改提示词还是修改代码。8. 最佳实践与工程建议如果你不满足于跑通一个 Demo而是想把架构图 Agent 用进日常工作甚至团队流程中下面这些工程建议可以直接参考。第一提示词里要写清楚“分层规范”。这是架构图 Agent 最容易出彩也最容易翻车的地方。没有分层约束时模型生成的图基本是平铺的看不出系统边界。有了明确的 layer 枚举图的结构感会立刻提升。建议在你的提示词里维护一份固定的分层枚举比如接入层、应用层、数据层、中间件层、基础设施层这是成本最低但收益最大的优化。第二把生成的 DSL 当代码管理。Mermaid 源码和普通代码一样要进 Git要打标签要做 Code Review。团队里任何人对架构有调整直接改 DSL 或让 Agent 改 DSL然后提交一个 PR。评审者看 diff 就能理解这次架构调整到底动了什么。这才是架构图 Agent 相对传统画图工具最大的优势可追溯。第三重要架构图要保留人工审核环节。Agent 生成的图只能是“初稿”不能是“终稿”。特别是涉及线上系统的架构图必须由熟悉系统的人核对节点、依赖方向和部署边界。建议在流程中加一个“架构评审”阶段把 Agent 生成的图作为评审材料而不是结论。第四输入要脱敏敏感架构不要裸奔到外部模型。如果你画的图涉及内部服务名、数据库地址、机房信息或者客户敏感数据不要直接把完整描述发送给外部模型服务。可以选择私有化部署模型或者在输入前用代号替换敏感信息。安全边界应该从一开始就设好而不是出事后再补。第五善用记忆机制。Agent 的“记忆”其实就是请求里的 messages 列表。把用户在历史对话中提到的偏好整理成一段“用户偏好摘要”每次请求都携带这段摘要效果比每次都从零开始要好得多。比如用户说过“数据库放在最底层”“不需要画出网络设备”这些约束都应该被记住。第六不要只把图当图。架构图应该跟架构决策记录配合使用。图回答“系统长什么样”ADR 回答“为什么长这样”。有图无决策图很快就腐烂了。建议在架构图文件旁边放一份简短的 ADR 文档记录关键架构决策的背景和取舍。第七衡量标准是“修改成本”而不是“生成速度”。不要过分追求一次生成完美的图而要看“初稿生成后改到可用状态需要多少轮对话”。如果第三轮修改还不能收敛说明你的提示词约束不够或者输入描述太模糊。这时候优先补输入信息而不是继续碰运气。9. 总结与后续学习方向回到开头的问题架构图 Agent 为什么会连续多天排在 GitHub 热榜第一我认为答案不是“AI 画图很酷”而是它把画架构图这件事从一次性手工劳动变成了可对话、可迭代、可版本化、可评审的工程流程。它真正改变的不是出图那一秒而是出图之后的整条协作链路。这篇文章里我们拆解了架构图 Agent 的工作原理对比了它和传统画图工具、AI 生图工具的本质区别也用一个最小 Demo 演示了“自然语言 - 结构化 JSON - Mermaid DSL - 图片”的完整流程。你可以直接把这个 Demo 跑起来替换成自己的系统描述感受一下从一段话到一张图的过程。下一步如果你想继续深入有几个方向值得探索一是追踪 GitHub 上热门的 Agent 框架看看它们是如何做工具调度和记忆管理的业务 Agent 和通用 Agent 在编排方式上有什么差异。二是把这个架构图生成能力接到你实际的项目里做成一个内部工具让团队成员通过命令行或 Web 界面就能把方案文档转成架构图。三是研究“代码仓库逆向生成架构图”这个方向。它比纯文本输入更可靠因为信息源来自真实代码而不是模型的猜测。围绕这个方向可以关注代码解析、调用关系分析、依赖可视化等相关技术。最后提醒一句架构图 Agent 是很好的“思考放大器”但它不能替代你对系统的理解。生成出来的图永远要经过你自己的判断再进入团队评审。把它当成一个把思想快速变成图纸的引擎而不是替你思考的顾问这才是正确的使用姿势。