架构图Agent实战：让系统设计从手绘变为可维护文本

架构图 Agent 这个方向过去几天在 GitHub 上热度非常高。我自己的架构图 Agent 项目连续五天排在 GitHub 全球热门榜前列个人账号也登上了全球开发者趋势榜第一。这类项目不是简单生成一张模板图而是把一段需求描述转成结构化的架构图输出。关注它的人主要三类系统设计文档写到一半的开发、负责微服务改造的技术负责人、以及想用 Agent 替代重复绘图工作的效率型工程师。它最值得关注的不是“能画图”而是让架构表达从“手绘劳动”变成“可审查、可修改、可版本化的文本”。画图本身不产生技术价值真正的价值在于把系统的结构说清楚。传统做法是先画一个大概流程再不停手工调整节点、连线、分组一旦需求变化整个图要重排。架构图 Agent 的路线不一样它用大模型理解你的系统描述然后输出结构化内容再用渲染引擎自动生成图。你后续维护的是一段描述文本不是画布上的图形。这个改动对日常开发来说非常关键。如果你也想把这个项目拉下来本地跑一遍或者自己写一个类似的 Agent这篇内容按我实际踩完的顺序来拆环境、最小流程、参数调整、批量处理、常见坑、以及哪些场景不适合过度期待。1. 架构图 Agent 到底解决什么问题为什么连续五天冲上全球热门1.1 架构图 Agent 的实际使用场景一个成熟的架构图 Agent可以处理的不只是单机模块图。输入一段需求比如“一个支持多租户的订单系统包含前端、网关、订单服务、支付服务、消息队列、数据库数据库需要主从分离消息队列用于订单状态变更通知”它能把这些信息整理成包含边界、分组、依赖关系的架构描述再渲染成图。我实际使用中最常见的几个场景技术方案文档里需要快速画出目标架构但不想在画图工具里拖节点。微服务改造前先让 Agent 生成一版候选结构再人工修正。给老系统补架构文档基于现有代码和模块描述生成依赖关系图。做技术分享或评审 PPT 时需要统一视觉风格的架构图。这些场景的共性是图不是最终交付物理解才是。图越容易修改和复现沟通效率越高。1.2 相比传统架构图软件它的价值变化在哪里传统架构图软件比如 Visio、draw.io、ProcessOn解决的是“怎么画”的问题。你仍然需要先想清楚节点、连线和分组软件只是让绘制更快。架构图 Agent 解决的是“从哪来”的问题你只需要描述业务和系统结构Agent 负责把描述转成图形语言。这里有个容易被忽略的差异传统工具保存的文件很难在代码评审里展示差异而 Agent 的输出通常是 Mermaid 或者 PlantUML 这类文本格式。文本格式意味着可以放进 Git 做版本管理。哪个人改了什么评审时一目了然。这也是它能连续上榜的原因之一。最近的 Agent 开发热度本身就高再加上架构图又是大量开发者的刚需两个需求叠在一起项目很容易被点进来看。热度不代表功能完美但至少说明方向对了把 Agent 用在真实工程步骤上比做一个通用的聊天助手更容易被接受。2. 想本地跑通这类 Agent先准备哪些条件2.1 基础运行环境和依赖清单以我本地测试的 Python 版流程为例准备一个 Python 3.10 以上的环境再装一个支持 Mermaid 渲染的命令行工具。如果你拿到的仓库是基于 Node.js 的逻辑也类似依赖会变成 mermaid-cli 或 puppeteer。关键依赖通常包括三部分Agent 框架或编排逻辑负责拆解输入、调用模型、处理结果。大模型 SDK负责连接你选择的模型服务。渲染工具把模型输出的文本转成图片或 HTML。安装依赖之前先确认仓库的 requirements.txt 或 package.json不要自己凭感觉装。我在测试时遇到过几次问题都不是模型报错而是 mermaid-cli 版本和 Node 版本不匹配渲染阶段直接崩溃。建议先把项目自带的锁文件安装好再跑自带样例。2.2 模型服务的接入方式与 API 配置架构图 Agent 的核心是“把文字转成结构化架构描述”这一步通常需要一个支持 function calling 的大模型接口。你可以在环境变量里配置模型服务的 key 和 base_url再指定模型名称。常见环境变量示例export LLM_API_KEYyour-api-key export LLM_BASE_URLhttps://api.example.com export LLM_MODELyour-model-name这里有一个实用原则如果只想验证流程先用一个你手上已经有的模型服务不要为了项目去开一堆新服务。低 temperature、偏高 max_tokens 是比较稳的初始设置。因为生成架构图需要忠实于输入不需要太多随机发挥。2.3 目录和输入输出格式建议跑通之前先把输入输出目录想好。我自己习惯建三个目录input/放需求描述每个需求一个 Markdown 文件。output/放 Agent 生成的文本图和 Mermaid 代码。rendered/放渲染后的 PNG 或 SVG。这样做的好处是排查问题时有清晰的链路如果输出文件存在但没有渲染图问题在渲染环境如果输出文件不存在问题在模型调用或 Agent 流程。目录结构看似简单却是批量使用时最省时间的安排。注意第一次跑不要贪多先放一个需求文件跑通后再考虑多文件。3. 最小可运行流程从一段需求描述到一张架构图3.1 第一步先写清楚输入需求架构图 Agent 对输入的敏感程度远高于普通聊天。模糊的输入会得到节点随意、层次混乱的图。我推荐按以下结构写需求系统定位这个系统解决什么问题有哪些用户角色。核心模块列出主要服务或组件。数据依赖说明模块之间谁调用谁数据流向是什么。基础设施数据库、缓存、消息队列、网关等。边界约束是否多租户、是否需要高可用、是否需要异步。示例系统定位电商订单系统面向 C 端用户支持订单创建、支付、售后。 核心模块 - 用户服务 - 订单服务 - 支付服务 - 库存服务 - 消息通知服务 数据依赖 - 用户服务提供用户信息给订单服务 - 订单服务调用支付服务完成支付 - 支付成功后发送消息库存服务和消息通知服务消费 基础设施 - MySQL 主从用于订单和用户数据 - Redis 用于会话和热点库存 - Kafka 用于订单状态事件 边界约束需要支持多租户订单状态变化需要异步通知。输入写清楚Agent 输出的节点边界才会明确。3.2 第二步调用 Agent 生成结构描述直接用 API 调用或者跑项目里的 CLI 命令都可以。以最小伪代码为例from agent_core import generate_architecture result generate_architecture( input_fileinput/order_system.md, output_formatmermaid, temperature0.2, ) print(result.text) print(result.mermaid_code)这一步本质上包含三个动作把需求文件读入上下文、让模型输出 JSON 或 Mermaid 代码、把结果保存到输出目录。如果项目里没有现成 CLI你可以自己写一个十几行的脚本核心就是把输入文件内容拼进 Prompt再把模型返回结果落盘。3.3 第三步把输出渲染成架构图并检查拿到 Mermaid 代码后用渲染工具生成 PNG 或 SVG。命令行方式类似mmdc -i output/order_system.mmd -o rendered/order_system.png -w 1280 -b white渲染完成后不要只看“能出图”就结束。我一般会检查三点节点是否完整主要服务都在图里没有漏掉。分组是否正确基础设施、核心服务、外部系统是否分区清晰。连线方向是否符合数据流避免把“调用”和“依赖”画反。一个常见误区是生成成功不代表语义正确。你在评审阶段多花两分钟看图能避免把错误架构图贴进文档。4. 哪些参数真正影响生成效果先改哪个4.1 模型选择和 temperature 参数模型选择对结果影响最大。同一个输入不同模型对架构层次的理解差异很大。更稳的做法是先在同一个任务上对比两三个模型固定输入比较输出质量再决定长期用哪个。temperature 参数直接影响稳定性。画架构图不是写小说我一般会设置在 0.1 到 0.3 之间。太高会让节点命名出现同义表述比如一会儿叫“订单服务”一会儿叫“Order Service”影响后续文本解析。太低会让输出死板但架构图本身就要求稳定所以低一点更合适。4.2 Prompt 模板和示例约束Prompt 模板比很多参数都重要。好的模板要包含三部分角色说明、输出格式约束、示例。角色说明告诉模型你是在生成架构图输出格式约束告诉它必须输出指定结构的 Mermaid 代码示例则让模型模仿节点命名和层级风格。示例不是越多越好一个和当前场景接近的示例往往比五个无关示例更有效。我在项目里把 Prompt 模板设计成可配置项每次生成时动态插入需求内容。这样调优时不用改主流程代码只改模板文件。如果你也打算长期使用建议把模板独立出来维护。4.3 输出格式Mermaid 与 JSON 结构怎么选输出格式分两层中间结构和最终展示。中间结构适合用 JSON包含模块列表、分组、依赖关系方便程序做进一步分析。最终展示直接用 Mermaid因为渲染生态成熟GitHub、飞书、语雀、Typora 都支持预览。如果项目需要自定义图形也可以从 JSON 再生成 PlantUML 或 SVG。需要注意 Mermaid 版本的差异。不同渲染器对语法支持不完全一致比如flowchart LR、subgraph、classDef这些常用语法在旧版 mermaid-cli 上表现可能有差别。输出要在你实际使用的渲染器里测试不能只看模型返回语法正确。5. 批量生成架构图时输出命名、队列和失败重试怎么处理5.1 批量任务最容易忽略的不是速度而是输出一致性单条任务跑通之后很多人会急着把所有系统描述丢进去然后把并发拉满。我实测后的结论是批量任务最值得关注的不是吞吐而是输出一致性和失败恢复。架构图 Agent 是外部模型调用不是本地纯计算任务单次请求可能失败、可能超时、可能生成一半被截断。如果你只跑一次就写文件很容易得到一批残缺图。更稳的做法是先把每次结果保存为 JSON包含输入文件、模型返回原文、解析后的结构、渲染状态再进入渲染阶段。5.2 设计一个简单的队列和失败重试流程批量任务建议按“读取输入、调用模型、保存结果、渲染、检查状态”五个步骤拆开。每一步都独立记录日志。伪代码流程for input_file in input_files: content read(input_file) for attempt in range(3): try: result call_model(content) save_json(result) break except TimeoutError: wait(attempt * 2) continue else: log_error(input_file)这里的关键是失败时不要把上次的旧输出覆盖掉也不要静默跳过。记录下来之后根据日志重新跑失败文件。并发方面我建议一开始只跑一个请求确认模型端没有限流后再逐步增加。外部 API 的并发上限不是由你的 Agent 决定的贸然拉高并发只会得到一堆限流报错。5.3 结果检查清单批量任务结束后我会按这份清单检查所有输入文件是否都有对应输出。失败文件是否有明确错误日志。JSON 中的模块数量是否符合输入描述。Mermaid 代码能否全部通过渲染。渲染图片大小是否统一命名是否能对应到输入。如果只是重建一批系统的架构文档这个链路已经够用。如果要做成团队工具还需要加权限、审计、可视化界面复杂度会明显上升不建议一开始就铺开。6. 实际使用中常见的坑以及我的排查顺序6.1 生成成功但渲染失败先看 Mermaid 语法最典型的场景是模型返回了一段看似正常的 Mermaid 代码但 mermaid-cli 渲染时报错。不要先怀疑项目代码把代码单独贴到 Mermaid Live Editor 里验证通常能快速定位问题。常见问题包括中文标点被混进代码、节点 ID 和标签用了特殊字符、subgraph 闭合缺失、classDef 放置位置不对。这些不是模型听不懂而是输出格式没有严格规范化。可以在 Prompt 里增加一句“不要输出除 Mermaid 代码以外的内容”或者在后处理时剥离开头和结尾的代码块标记。6.2 生成结果和需求不一致优先调整输入措辞如果架构图节点齐全但关系错乱先不要急着改模型。把输入重写一遍明确描述“谁调用谁”“谁依赖谁”“数据流向是什么”再重新生成效果通常比换一个模型更明显。我在处理订单系统示例时发现原文里写“支付完成后通知库存和用户”模型经常把通知关系画成消息队列指向所有服务产生大量连线。改成“支付服务发送事件到 Kafka库存服务和通知服务订阅 Kafka 中的订单支付成功事件”之后图的层次就清楚了很多。输入里多一个动词输出里少一条线。6.3 资源占用和长文本超时问题架构图 Agent 看起来只是文本处理实际使用中也可能卡住。长文本输入会让单次请求时间变长尤其是包含大量模块和复杂依赖时。如果模型端设置了偏短的超时时间整个任务就会失败。排查顺序一般是先看任务卡在哪个阶段是模型调用阶段卡住还是渲染阶段卡住。模型调用阶段卡住时检查网络连接、API 超时配置、上下文长度是否超限渲染阶段卡住时检查 mermaid-cli 是否安装了 Chromium、内存是否足够、图片输出路径是否有写权限。我遇到过一个问题批量渲染 50 张图时前 30 张正常后面全部失败。查日志发现是临时目录磁盘满了。这种问题跟 Agent 本身没什么关系但如果你只看“生成架构图”这层现象很容易误判成模型不稳定。所以日志要按阶段记录别把错误都混在一起。7. 架构图 Agent 的边界什么能做什么不能期待7.1 它能辅助设计但不能替代架构评审架构图 Agent 擅长把信息整理成图但图不等于正确设计。它不会判断你是否真的需要消息队列也不会指出单点故障风险。它只能把你给的需求结构化让人更容易发现问题。所以更好的使用方式是把 Agent 生成的图当作评审初稿而不是最终答案。让有经验的工程师在图上标注问题和修正意见反复迭代几轮之后再作为正式文档进入版本库。7.2 对复杂系统、多角色、动态交互的支持仍然有限如果是几十个服务、大量动态交互、多层安全策略的系统当前 Agent 生成的图往往过于简化或者连线过密导致不可读。这种情况下不要指望一张图覆盖所有细节建议按视图拆分系统上下文图、容器图、组件图、部署图分别生成再统一管理。7.3 真正值得关注的不是热度而是可维护性和可复现性回到开头的问题这个项目连续几天登上 GitHub 全球热门榜确实说明大家对这个方向感兴趣。但项目能不能长期用关键在三点输入是否可复现同一份需求多次生成结果是否稳定。输出是否可维护架构图文本是否容易修改、版本化。流程是否可扩展能否接入自己的模型、渲染器和团队工作流。我自己的项目能冲上趋势榜很大程度是因为这几块做得比较简单直接没有过度包装功能。如果你也想做一个类似的 Agent 项目最值得投入的地方不是花哨的界面而是把输入结构、Prompt 模板、输出格式、失败恢复这几个基础环节做扎实。架构图 Agent 不是一个能把所有架构问题都解决的万能工具。它真正改变的是画图这件事的启动成本和维护成本。把文字需求转成可版本化的架构图然后让人的经验继续去修正它这个流程在绝大多数团队里都值得试一次。