最近 GitHub Trending 上“架构图 Agent”这类项目连续多天排在热门榜前列和它相关的讨论也从“AI 能不能画图”变成了“Agent 能不能代替人完成架构梳理”。在大量热搜词里微服务架构图、技术架构图、Agent 框架、Agent 开发学习路线这些词几乎每天都出现说明大家关心的不只是某个仓库的 star 数而是“这类能力到底怎么实现”。这篇文章不讨论某个项目是否真的连续五天全球第一也不评价任何人是否进入开发者趋势榜。更值得做的是拆开看一个架构图 Agent 由哪些模块组成它和普通脚本或一次 ChatGPT 问答有什么区别以及如果让你从零实现一个最小可运行版本应该先写哪些代码。读完并跟着做完你会得到一个能根据自然语言描述生成 Graphviz 架构图的小工具同时知道它为什么需要“Agent 循环”而不是一个简单的提示词模板。1. 架构图 Agent 到底在做什么1.1 从画图工具到生成式 Agent传统架构图工具的使用路径是打开绘图软件手动拖入节点手动连线手动调整分组。这个过程的可复用性很低因为“图”的本质不是画布上的几个框而是对系统结构的理解。架构图 Agent 的思路不一样。它把“画图”这个行为拆成两个阶段先理解系统再生成描述。理解系统包括识别模块、依赖关系、部署层次和技术栈生成描述则落到一种机器可解析的图描述语言上例如 Graphviz 的 DOT 格式。Agent 拿到用户输入后不是直接输出一张静态图片而是通过多轮调度把“自然语言需求”转换成“结构化图数据”再调用渲染工具输出 SVG 或 PNG。这里的关键是 Agent 这个概念。普通程序遇到输入后执行固定逻辑遇到异常可能直接退出Agent 则在循环里自主判断下一步该做什么信息不够就提问生成失败就读取错误信息并重新生成渲染成功后返回结果。这种“感知、决策、行动、再感知”的循环才是它和普通脚本的本质区别。1.2 为什么架构图生成很适合 Agent 化架构图生成是最适合 Agent 化的任务之一原因是它的验证成本低、反馈信号强、输出格式明确。低验证成本体现在两方面。DOT 代码是否合法交给dot命令渲染一次就能得到明确结果结构是否合理人眼一看就能判断。相比代码生成需要编译、测试、人工 review 多道关卡架构图生成的闭环更短。强反馈信号来自 Graphviz 编译器语法错误会精确告诉你是第几行、哪个节点或边出了问题。这种错误信息可以直接塞回对话上下文让大语言模型自己修正。输出格式明确也是重要原因。架构图最终要落到一种描述语言里无论是 DOT、PlantUML 还是 JSON 关系数据都是结构化文本。大语言模型最擅长的恰恰是把非结构化描述整理成结构化文本。三个条件叠加就形成了一个非常适合 Agent 迭代式工作的场景。另外架构图本身带有很强的“规划”属性。一个系统包含哪些服务、服务之间如何调用、数据如何流动这些信息天然是分层、分模块的。让模型直接一次生成完整架构图经常会出现节点过多、布局混乱、边界不清的问题但让模型先列组件再补关系最后成图效果会稳定很多。这种分解动作正好是 Agent 多轮机制擅长的事。1.3 热榜现象背后的三个信号架构图 Agent 类项目在 GitHub 热榜频繁出现背后有三个信号值得记录。第一AI Agent 的应用正在从通用对话转向垂直场景。可以问答的聊天机器人已经很多但能完成一个“具体交付物”的 Agent 更稀缺。架构图就是一种具体交付物它不是一个答案而是一份可用于评审、归档、汇报的产物。第二开发者对“可视化理解代码库”有真实需求。很多项目面临的不是没有代码而是代码太多新人难以看懂老人难以讲清。架构图 Agent 如果能把仓库结构、服务依赖、配置文件整理成一张清晰的图等于把“读代码”这件事部分自动化了。第三个人开发者在开源社区的可见度在提高。GitHub 趋势榜不仅看 star 增长也综合了活跃度、fork、issue 响应等因素。一个个人项目如果能连续上榜通常意味着它选对了场景、给出了最小可用产物并且 README 和示例足够直观。这类经验本身也值得学习。2. 拆解一个架构图 Agent 的四个核心模块一个完整的架构图 Agent 不是“调一次大模型接口”就结束了。它至少需要四个模块才能形成闭环输入理解、工具调用、多轮修正、结果输出。这几个模块可以写在一个文件里也可以按工程方式拆成独立服务但职责必须清晰。2.1 输入理解把自然语言变成结构化需求输入理解模块负责把用户的原始描述转换成 Agent 能处理的任务上下文。用户可能说“帮我画一个微服务架构图”也可能说“根据这个仓库画出模块依赖”还可能说“把订单系统从单体拆成微服务画一张目标架构图”。这些输入的复杂度差异很大因此输入理解不是简单拼接 prompt。它要做的事情包括识别系统边界用户要画的是整体架构、服务调用、部署拓扑还是数据流。提取关键实体网关、注册中心、数据库、消息队列、业务服务等名词。识别约束条件例如必须包含缓存层、不需要画出中间件、使用某类数据库。判断信息是否充分如果用户没说清模块数量或调用关系Agent 应该主动提问。在最小实现中这一步可以由大语言模型在 system prompt 的引导下完成。模型不需要单独输出一份“理解报告”而是把理解结果直接体现在后续生成的 DOT 代码里。更复杂的实现可以增加一层“需求结构化”调用先让模型输出 JSON 格式的需求清单再进入画图阶段。2.2 工具调用让 Agent 真正碰一下渲染器很多把大模型包装成 Agent 的项目实际并没有调用任何工具只是“看起来像 Agent”。真正的 Agent 必须能用外部工具验证自己的输出。对于架构图生成来说工具层至少要做两件事。第一是语法校验。模型输出的 DOT 代码可能是错的比如节点 id 用了中文、引号没转义、边定义缺少分号。把这些代码直接交给dot渲染大概率会失败。这时 Agent 需要调用本地的 Graphviz 工具完成一次真实渲染并捕获错误信息。第二是文件输出。校验通过后需要把 DOT 代码渲染成 SVG 或 PNG并保存到指定目录。这个过程看起来简单但它决定了 Agent 的“交付物”能否被用户直接使用。工具调用的价值在于引入外部世界的反馈。模型可以自信地认为自己写得对但dot命令不会说谎。如果工具层说“渲染失败第 12 行有语法错误”模型就必须在下一次输出中修复这个问题。2.3 多轮修正失败后还能继续完善多轮修正是 Agent 和普通程序最明显的差异。普通脚本的流程是读取输入、执行逻辑、输出结果如果结果不对只能人工修改代码重新运行。Agent 的流程则是读取输入、生成方案、调用工具、获取反馈如果反馈是错误就把错误信息追加到对话上下文让模型重新生成。这个机制在工程上通常用一个for循环实现循环次数就是 Agent 的最大尝试轮数。每一轮包含一次对话调用和一次工具校验具体流程可以概括为把用户需求与历史对话组装成 messages 列表。调用大模型返回一个 JSON 格式的动作指令。解析动作如果是“ask”说明信息不足需要追问用户如果是“generate”取出 DOT 代码。调用工具层校验渲染 DOT 代码。校验失败则把错误信息追加到 messages回到第 2 步重新生成。校验成功则渲染输出并结束循环。这个循环把大模型的自我纠错能力限制在一个可控范围内。它允许模型犯错但不会让模型无限犯错。最大轮数一旦耗尽Agent 就返回失败不会产生不可控行为。2.4 结果输出架构图的格式选型架构图 Agent 的输出格式选择直接影响实现复杂度。常见选择有 Graphviz DOT、PlantUML、JSON 关系数据和图片文件。DOT 的优点是语法简单、生态成熟、渲染结果稳定。Graphviz 的dot命令几乎可以在所有系统上运行支持输出 SVG、PNG 甚至 PDF。SVG 文件体积小、可直接嵌入网页和文档后续还可以二次编辑是个人工具和内部工具的首选。PlantUML 的优势是类 Java 的语法更容易阅读但需要额外的 Java 运行时安装链比 Graphviz 长。纯 JSON 关系数据适合作为中间格式方便后续转成其他图表或导入其他工具但用户拿到 JSON 后仍然需要自己完成渲染。表格对比可以这样看输出格式优点缺点适用场景Graphviz DOT / SVG语法简单、渲染稳定、安装轻量复杂布局需要手动调整最小实现、内部工具、文档插图PlantUML语法更接近程序语言、序列图支持好依赖 Java渲染链路较重已有 Java 环境、需要时序图JSON 关系数据结构清晰、可编程处理需要二次渲染不直观作为中间层、数据交换PNG 图片查看方便、兼容所有编辑器不易修改、放大模糊汇报、演示、对外交付对于本文的最小实现选择 Graphviz DOT 加 SVG 输出。原因是它在部署成本和结果可用性之间最平衡。3. 环境准备与项目结构3.1 技术选型实现一个最小架构图 Agent技术栈不需要复杂。核心工具是三样Python 用于编排OpenAI 兼容接口用于大模型对话Graphviz 用于渲染。不需要引入 LangChain 或 LlamaIndex 这类重量级框架因为基础 Agent 循环本身只有几十行代码。先亲手实现一次循环再考虑框架理解会深很多。Python 版本建议 3.10 及以上。大模型接口使用requests直接调用 HTTP API不额外封装方便理解对话协议。3.2 环境依赖需要安装两部分环境。第一部分是 Python 依赖。创建一个requirements.txt内容如下requests2.31.0第二部分是 Graphviz。不同系统的安装方式不同# Ubuntu / Debian sudo apt install graphviz # macOS brew install graphviz # Windows choco install graphviz安装完成后在终端执行dot -V能输出版本信息即代表成功dot -V如果运行 Agent 时报 “dot: command not found”说明 Graphviz 没有安装或者安装后没有把dot命令加入 PATH。大模型接口方面需要准备一个可用环境变量OPENAI_API_KEY。如果你的模型服务兼容 OpenAI 的/v1/chat/completions协议可以把服务的 base_url 传进来。最小实现里使用环境变量读取 API Key避免把密钥写进代码export OPENAI_API_KEY你的密钥3.3 目录结构项目目录可以这样组织archi-agent/ ├── agent/ │ ├── __init__.py │ ├── agent.py │ ├── llm.py │ ├── protocol.py │ └── tools.py ├── output/ ├── cli.py └── requirements.txtllm.py负责大模型对话调用tools.py负责 DOT 校验和渲染protocol.py负责解析模型返回的动作指令agent.py是主循环cli.py是命令行入口。这种拆分对于最小项目已经足够后续扩展时可以再把配置、日志、缓存独立成模块。4. 实现最小可运行的架构图 Agent4.1 定义消息协议Agent 和大模型之间需要一套固定协议。协议的作用是让模型的输出能被程序解析而不是一段随意发挥的文本。协议定义如下模型每次返回一个 JSON 对象包含action、dot_code、message三个字段。action为generate时dot_code保存 Graphviz DOT 代码。action为ask时message保存需要向用户补充的问题。action为其他值时程序按异常处理并提示模型修正。在 system prompt 中把协议写清楚能显著降低输出解析失败的概率def build_system_prompt() - str: return 你是一个软件架构图生成助手。你的任务是根据用户需求生成 Graphviz DOT 代码。 输出要求 - 只输出一个 JSON 对象不要输出 Markdown 代码块。 - 格式{action: generate, dot_code: digraph G {...}, message: 简要说明} - 如果用户需求中的模块、关系、边界不明确输出 {action: ask, message: 需要补充的问题} DOT 代码要求 - 使用 digraph 结构。 - 节点 id 使用英文和下划线。 - 节点 label 可以使用中文但特殊字符必须转义。 - 必须能通过 graphviz 的 dot 命令渲染。 这个 prompt 里的关键点有两个一是要求“只输出 JSON 对象”避免模型在 JSON 外层套 Markdown 代码块二是明确“可以提问”让 Agent 在信息不足时不至于硬编一个错误架构。解析函数放在protocol.py里import json def parse_llm_content(content: str) - dict: text content.strip() if text.startswith(): text text.strip() if text.startswith(json): text text[4:].strip() return json.loads(text)这里兼容了模型偶尔输出代码块的场景。如果仍然解析失败异常会抛出到主循环中主循环会把异常信息反馈给模型让模型重新输出。4.2 实现 LLM 调用层llm.py负责调用大模型接口。代码如下import os import requests def chat_completion( messages, modelgpt-4o-mini, temperature0.2, base_urlhttps://api.openai.com/v1, ): api_key os.environ.get(OPENAI_API_KEY) if not api_key: raise RuntimeError(缺少 OPENAI_API_KEY 环境变量) url base_url.rstrip(/) /chat/completions headers { Authorization: fBearer {api_key}, Content-Type: application/json, } payload { model: model, messages: messages, temperature: temperature, } response requests.post(url, headersheaders, jsonpayload, timeout60) response.raise_for_status() data response.json() return data[choices][0][message][content]温度设置为 0.2目的是让模型输出更稳定、更接近结构化结果。架构图生成属于“格式确定性优先”的任务不追求创意因此温度不要太高。如果使用的模型服务不在官方地址比如企业内部部署的兼容服务只需要在调用时传入base_url即可不需要改其他代码。4.3 实现 DOT 渲染工具tools.py中实现两个函数validate_dot和render_dot_svg。validate_dot负责把 DOT 代码写入临时文件调用dot命令渲染到空输出同时捕获标准错误。渲染成功则返回(True, )失败则返回(False, 错误信息)。import os import shutil import subprocess import tempfile def validate_dot(dot_text: str) - tuple[bool, str]: if not shutil.which(dot): return False, 未找到 graphviz 的 dot 命令请先安装 graphviz with tempfile.TemporaryDirectory() as tmpdir: dot_path os.path.join(tmpdir, input.dot) with open(dot_path, w, encodingutf-8) as f: f.write(dot_text) proc subprocess.run( [dot, -Tsvg, dot_path], capture_outputTrue, textTrue, timeout30, ) if proc.returncode ! 0: return False, proc.stderr[-500:] return True, 注意这里没有把 SVG 写到磁盘只是让dot执行一次真实解析。这样做的目的是把校验和渲染分离校验失败时不产生残留在磁盘上的多余文件。render_dot_svg则在校验通过后输出最终图片def render_dot_svg(dot_text: str, output_path: str output/architecture.svg) - str: output_dir os.path.dirname(os.path.abspath(output_path)) os.makedirs(output_dir, exist_okTrue) with tempfile.TemporaryDirectory() as tmpdir: dot_path os.path.join(tmpdir, input.dot) with open(dot_path, w, encodingutf-8) as f: f.write(dot_text) proc subprocess.run( [dot, -Tsvg, dot_path, -o, output_path], capture_outputTrue, textTrue, timeout30, ) if proc.returncode ! 0: raise RuntimeError(proc.stderr[-500:]) return output_path4.4 组装 Agent 主循环agent.py是整个项目的核心。它维护一个 messages 列表作为 Agent 的“记忆”在每一步对话中加入新的结果与反馈。import json from .llm import chat_completion from .protocol import parse_llm_content from .tools import validate_dot, render_dot_svg from .agent_prompt import build_system_prompt def run_agent(user_input: str, max_rounds: int 4, output_path: str output/architecture.svg): messages [{role: system, content: build_system_prompt()}] messages.append({role: user, content: user_input}) for _ in range(max_rounds): response chat_completion(messages) messages.append({role: assistant, content: response}) try: parsed parse_llm_content(response) except json.JSONDecodeError as exc: messages.append({ role: user, content: f上一轮输出不是合法 JSON请重新输出完整 JSON。错误信息{exc}, }) continue action parsed.get(action) if action ask: return { status: need_more_info, message: parsed.get(message, ), } if action generate: dot_code parsed.get(dot_code, ) ok, err validate_dot(dot_code) if not ok: messages.append({ role: user, content: fDOT 渲染失败{err}。请修正 DOT 代码后重新输出完整 JSON。, }) continue final_path render_dot_svg(dot_code, output_path) return { status: success, dot_code: dot_code, output_path: final_path, message: parsed.get(message, ), } messages.append({ role: user, content: f未知 action{action}。请只使用 generate 或 ask。, }) return { status: timeout, message: 达到最大迭代次数仍未生成有效架构图。, }主循环的核心逻辑是“把每一条失败信息都变成下一次对话的上下文”。这是 Agent 能够自我修正的关键。模型第一次生成的 DOT 代码可能有语法错误但dot命令返回的错误信息会进入下一轮输入模型看到错误后重新生成成功率会明显提高。写完后把 system prompt 独立到agent_prompt.py中避免和主逻辑混在一起。4.5 增加 CLI 入口cli.py让项目可以从命令行动起来import sys from agent.agent import run_agent if __name__ __main__: user_input sys.argv[1] if len(sys.argv) 1 else input(描述你的系统) result run_agent(user_input) print(result)使用时直接运行python cli.py 帮我画一个用户登录系统的架构图包含前端、网关、认证服务、用户服务和数据库运行完成后可以在output/architecture.svg找到生成的 SVG 文件。5. 运行验证与输出分析5.1 一个完整的输入输出示例假设输入是帮我画一个微服务架构图包含 API 网关、订单服务、用户服务、商品服务、消息队列和 MySQL 数据库订单服务通过消息队列异步通知用户服务。Agent 可能经过两轮生成得到类似下面的 DOT 代码digraph architecture { rankdirLR; node [shapebox, stylerounded, fontnameHeiti SC]; gateway [labelAPI 网关]; order [label订单服务]; user [label用户服务]; product [label商品服务]; mq [label消息队列]; db [labelMySQL 数据库]; gateway - order; gateway - user; gateway - product; order - mq; mq - user; order - db; user - db; product - db; }如果第一轮生成的 DOT 有语法错误程序会返回类似下面的反馈信息并进入下一轮DOT 渲染失败Error: syntax error in line 8 near labelAgent 会把这条错误信息拼接到下一轮对话中让模型自己修正。5.2 验证步骤运行后建议按下面顺序检查观察命令行返回的status字段是否为success。检查output_path指向的文件是否存在。用浏览器或图片查看器打开 SVG 文件。打开同一个 SVG 的源码确认图中节点数量与需求是否匹配。对照需求检查服务之间调用关系是否有遗漏或错误。如果状态为need_more_info说明 Agent 认为信息不足需要补充模块或关系后再运行。如果状态为timeout说明模型连续多轮都没有生成可渲染的 DOT需要检查系统 prompt、模型选择和 API 返回内容。5.3 从输出反推质量生成架构图后质量评估可以从三个维度进行。维度一是结构清晰度。图中是否只有必要的节点和边是否可以通过子图合理分组部署层次是否看得清楚。Graphviz 的自动布局有时会把边画得很乱这时可以在 DOT 代码中使用rankdir、ranksame、subgraph cluster_xxx来控制布局节奏。维度二是关系准确性。服务之间的箭头方向是否正确数据流方向是否一致是否把“同步调用”和“异步消息”混在一条边上。当前最小实现没有区分边类型实际使用中可以要求模型为边添加不同颜色或样式。维度三是信息完整性。用户提到的关键组件是否都出现在图中没有提到的多余组件是否越界。要避免模型为了“好看”而凭空添加缓存、日志、监控等组件除非用户明确要求。6. 常见问题与排查路径6.1 LLM 返回了非法 JSON现象程序抛出JSONDecodeError或者主循环不断进入parse_llm_content的异常分支。可能原因模型在 JSON 外层加了 Markdown 代码块JSON 内部出现了单引号、尾逗号或者dot_code中的双引号没有转义。检查方式打印原始response文本前后截取 200 字观察格式。处理建议在 system prompt 中再次强调“只输出 JSON 对象不要 Markdown 代码块”在解析函数中兼容代码块前缀同时要求模型在 JSON 字符串中统一用\转义 DOT 里的引号。6.2 DOT 语法校验失败现象程序返回DOT 渲染失败并带有一段dot命令的标准错误输出。可能原因节点 id 使用了中文或空格label 中的引号没有转义边定义写成了-但缺少分号或使用了 Graphviz 不支持的字符。检查方式把dot_code单独保存成.dot文件在终端手动执行dot -Tsvg input.dot -o out.svg处理建议根据错误行号定位问题要求模型用英文下划线格式命名节点 id在 DOT 代码段后追加“必须能通过 dot 命令直接渲染”的约束保留错误信息的最近 500 个字符反馈给模型避免上下文过长。6.3 多轮对话上下文膨胀现象随着轮数增加请求耗时变长费用变高模型开始遗漏早期需求。可能原因每一轮都把完整 DOT 代码和错误信息追加到 messages 中三轮以后上下文里可能积累了两三千 token 的无效内容。检查方式打印每轮 messages 的总 token 或字符数观察增长趋势。处理建议给max_rounds设置较小值比如 3 到 4当校验失败时只把错误摘要加入上下文而不是完整 DOT 代码如果项目进一步发展可以在每一轮都重新固定 system prompt只保留最初的用户需求不保留除最近一轮以外的历史输出。6.4 生成的架构图信息过载现象图能正常渲染但节点数量超过 30 个边交叉严重整体无法阅读。可能原因用户输入描述过于宽泛比如“画出整个系统的架构图”而系统本身包含几十个微服务和大量中间件。检查方式统计 dot_code 中的节点数量。处理建议在 system prompt 中增加“优先展示主要模块次要模块归入分组或省略”的约束当模型需要处理过大系统时主动要求用户拆分成子系统实现子图分组例如在集群外展示服务入口和数据库集群内展示核心服务。7. 从玩具到生产架构图 Agent 的工程化建议7.1 功能上的扩展方向最小实现跑通后可以沿着几个方向扩展。支持本地代码仓库分析。把用户输入的仓库路径交给 Agent模型先扫描模块目录和依赖文件再生成模块依赖图。这样可以减少用户手动描述的工作量。支持多轮交互式构建。允许用户对生成的图提出修改意见例如“把用户服务拆分出来”“增加 Redis 缓存层”“把数据库单独放到一个 cluster 中”每次修改都重新生成 DOT 并渲染。支持多种输出格式。除 SVG 外可以增加 PNG、JSON 关系数据以及面向不同工具的 DSL 转换。把中间结果统一成 JSON再派生出其他格式是最稳妥的做法。7.2 安全与权限边界架构图 Agent 涉及大模型调用和文件系统操作生产化时需要明确权限边界。不要把 API Key 写死在代码或前端使用环境变量或密钥管理服务。不要把用户输入直接拼进 system prompt 而不做任何过滤。如果 Agent 未来要读取本地文件或调用 Git 命令建议在独立 sandbox 中运行限制可访问目录禁止危险命令例如删除、格式化、网络穿越等。所有外部命令执行都应设置超时例如本文代码中的timeout30避免渲染过程卡死。7.3 成本与性能控制每次调用大模型都会产生费用和延迟。生产环境中可以采取以下手段。限制每一轮对话的最大 token 数防止模型输出无节制的长 DOT 代码。将渲染失败的错误信息截断后再回传降低上下文成本。对相同输入做缓存例如按输入文本的哈希值缓存上一次成功生成的 DOT 和 SVG。低频内部工具可以直接使用较小的模型只有生成质量不稳定时再切换更大模型。7.4 从热榜项目到自身能力的学习路径当你在 GitHub Trending 看到一个架构图 Agent 类项目时不要只盯着 star 数。按照下面这个顺序学习往往比收藏仓库更有价值。先看 README 的示例图明确它解决什么场景。再看它的 Agent 循环代码找到run或execute主函数理解循环结构。然后看它如何组织 prompt重点关注输出协议和错误反馈。接着看它的工具层确认它真的调用了渲染器还是只输出文本。最后看它的防错设计包括超时、重试、上下文控制和质量校验。这套流程同样适用于学习其他 Agent 类开源项目。热榜只是入口持续拆解能力才是真正能积累的东西。8. 值得持续关注的三个问题8.1 让 Agent 理解系统而不是只会画框很多架构图 Agent 只是把自然语言描述翻成图形本质上是提示词模板加渲染器。这种做法对简单系统足够对复杂系统远远不够。真正有价值的 Agent应该在生成图之前先理解系统的边界、层次、依赖方向和变化原因。这意味着后续可以引入代码扫描、配置文件解析、运行时调用链分析而不是只依赖用户描述。这也是为什么学习 Agent 循环比学习某个框架更重要。框架会更新协议会变化但“理解输入、调用工具、获取反馈、修正输出”这个循环不会过时。8.2 最小闭环检查清单在把本文代码用于更复杂的场景之前建议按照下面的清单检查一遍能否通过环境变量读取 API Key而不是写死在代码中。模型返回 JSON 后程序是否能稳定解析并处理异常。校验失败的 DOT 是否能自动回传错误信息并触发重试。最大循环次数是否有限制避免无限调用造成费用失控。SVG 输出路径是否可配置目录是否存在且可写。所有外部命令是否设置了超时。生成的 SVG 是否经过人工检查而不是只检查程序退出码。这份清单同样适用于你之后读到、自己扩展的任何 Agent 项目。8.3 下一个练习方向如果本文的最小实现已经跑通下一步可以尝试三个练习。第一增加子图分组功能让 Agent 在生成 DOT 时自动使用subgraph cluster_xxx组织模块。第二增加“边类型”概念区分同步调用、异步消息、数据库访问用不同颜色和线型表现。第三接入一个真实的代码仓库先让脚本扫描出服务依赖文件再把扫描结果交给 Agent 生成系统架构图。三个练习完成之后你对 Agent 的理解会从“会调接口”变成“会构建交付链路”这才是架构图 Agent 类项目真正想解决的事情。GitHub 热榜上的名字会变但底层能力的复用在每个项目里都会重复出现。
从零实现架构图生成 Agent：循环机制与工程实践
最近 GitHub Trending 上“架构图 Agent”这类项目连续多天排在热门榜前列和它相关的讨论也从“AI 能不能画图”变成了“Agent 能不能代替人完成架构梳理”。在大量热搜词里微服务架构图、技术架构图、Agent 框架、Agent 开发学习路线这些词几乎每天都出现说明大家关心的不只是某个仓库的 star 数而是“这类能力到底怎么实现”。这篇文章不讨论某个项目是否真的连续五天全球第一也不评价任何人是否进入开发者趋势榜。更值得做的是拆开看一个架构图 Agent 由哪些模块组成它和普通脚本或一次 ChatGPT 问答有什么区别以及如果让你从零实现一个最小可运行版本应该先写哪些代码。读完并跟着做完你会得到一个能根据自然语言描述生成 Graphviz 架构图的小工具同时知道它为什么需要“Agent 循环”而不是一个简单的提示词模板。1. 架构图 Agent 到底在做什么1.1 从画图工具到生成式 Agent传统架构图工具的使用路径是打开绘图软件手动拖入节点手动连线手动调整分组。这个过程的可复用性很低因为“图”的本质不是画布上的几个框而是对系统结构的理解。架构图 Agent 的思路不一样。它把“画图”这个行为拆成两个阶段先理解系统再生成描述。理解系统包括识别模块、依赖关系、部署层次和技术栈生成描述则落到一种机器可解析的图描述语言上例如 Graphviz 的 DOT 格式。Agent 拿到用户输入后不是直接输出一张静态图片而是通过多轮调度把“自然语言需求”转换成“结构化图数据”再调用渲染工具输出 SVG 或 PNG。这里的关键是 Agent 这个概念。普通程序遇到输入后执行固定逻辑遇到异常可能直接退出Agent 则在循环里自主判断下一步该做什么信息不够就提问生成失败就读取错误信息并重新生成渲染成功后返回结果。这种“感知、决策、行动、再感知”的循环才是它和普通脚本的本质区别。1.2 为什么架构图生成很适合 Agent 化架构图生成是最适合 Agent 化的任务之一原因是它的验证成本低、反馈信号强、输出格式明确。低验证成本体现在两方面。DOT 代码是否合法交给dot命令渲染一次就能得到明确结果结构是否合理人眼一看就能判断。相比代码生成需要编译、测试、人工 review 多道关卡架构图生成的闭环更短。强反馈信号来自 Graphviz 编译器语法错误会精确告诉你是第几行、哪个节点或边出了问题。这种错误信息可以直接塞回对话上下文让大语言模型自己修正。输出格式明确也是重要原因。架构图最终要落到一种描述语言里无论是 DOT、PlantUML 还是 JSON 关系数据都是结构化文本。大语言模型最擅长的恰恰是把非结构化描述整理成结构化文本。三个条件叠加就形成了一个非常适合 Agent 迭代式工作的场景。另外架构图本身带有很强的“规划”属性。一个系统包含哪些服务、服务之间如何调用、数据如何流动这些信息天然是分层、分模块的。让模型直接一次生成完整架构图经常会出现节点过多、布局混乱、边界不清的问题但让模型先列组件再补关系最后成图效果会稳定很多。这种分解动作正好是 Agent 多轮机制擅长的事。1.3 热榜现象背后的三个信号架构图 Agent 类项目在 GitHub 热榜频繁出现背后有三个信号值得记录。第一AI Agent 的应用正在从通用对话转向垂直场景。可以问答的聊天机器人已经很多但能完成一个“具体交付物”的 Agent 更稀缺。架构图就是一种具体交付物它不是一个答案而是一份可用于评审、归档、汇报的产物。第二开发者对“可视化理解代码库”有真实需求。很多项目面临的不是没有代码而是代码太多新人难以看懂老人难以讲清。架构图 Agent 如果能把仓库结构、服务依赖、配置文件整理成一张清晰的图等于把“读代码”这件事部分自动化了。第三个人开发者在开源社区的可见度在提高。GitHub 趋势榜不仅看 star 增长也综合了活跃度、fork、issue 响应等因素。一个个人项目如果能连续上榜通常意味着它选对了场景、给出了最小可用产物并且 README 和示例足够直观。这类经验本身也值得学习。2. 拆解一个架构图 Agent 的四个核心模块一个完整的架构图 Agent 不是“调一次大模型接口”就结束了。它至少需要四个模块才能形成闭环输入理解、工具调用、多轮修正、结果输出。这几个模块可以写在一个文件里也可以按工程方式拆成独立服务但职责必须清晰。2.1 输入理解把自然语言变成结构化需求输入理解模块负责把用户的原始描述转换成 Agent 能处理的任务上下文。用户可能说“帮我画一个微服务架构图”也可能说“根据这个仓库画出模块依赖”还可能说“把订单系统从单体拆成微服务画一张目标架构图”。这些输入的复杂度差异很大因此输入理解不是简单拼接 prompt。它要做的事情包括识别系统边界用户要画的是整体架构、服务调用、部署拓扑还是数据流。提取关键实体网关、注册中心、数据库、消息队列、业务服务等名词。识别约束条件例如必须包含缓存层、不需要画出中间件、使用某类数据库。判断信息是否充分如果用户没说清模块数量或调用关系Agent 应该主动提问。在最小实现中这一步可以由大语言模型在 system prompt 的引导下完成。模型不需要单独输出一份“理解报告”而是把理解结果直接体现在后续生成的 DOT 代码里。更复杂的实现可以增加一层“需求结构化”调用先让模型输出 JSON 格式的需求清单再进入画图阶段。2.2 工具调用让 Agent 真正碰一下渲染器很多把大模型包装成 Agent 的项目实际并没有调用任何工具只是“看起来像 Agent”。真正的 Agent 必须能用外部工具验证自己的输出。对于架构图生成来说工具层至少要做两件事。第一是语法校验。模型输出的 DOT 代码可能是错的比如节点 id 用了中文、引号没转义、边定义缺少分号。把这些代码直接交给dot渲染大概率会失败。这时 Agent 需要调用本地的 Graphviz 工具完成一次真实渲染并捕获错误信息。第二是文件输出。校验通过后需要把 DOT 代码渲染成 SVG 或 PNG并保存到指定目录。这个过程看起来简单但它决定了 Agent 的“交付物”能否被用户直接使用。工具调用的价值在于引入外部世界的反馈。模型可以自信地认为自己写得对但dot命令不会说谎。如果工具层说“渲染失败第 12 行有语法错误”模型就必须在下一次输出中修复这个问题。2.3 多轮修正失败后还能继续完善多轮修正是 Agent 和普通程序最明显的差异。普通脚本的流程是读取输入、执行逻辑、输出结果如果结果不对只能人工修改代码重新运行。Agent 的流程则是读取输入、生成方案、调用工具、获取反馈如果反馈是错误就把错误信息追加到对话上下文让模型重新生成。这个机制在工程上通常用一个for循环实现循环次数就是 Agent 的最大尝试轮数。每一轮包含一次对话调用和一次工具校验具体流程可以概括为把用户需求与历史对话组装成 messages 列表。调用大模型返回一个 JSON 格式的动作指令。解析动作如果是“ask”说明信息不足需要追问用户如果是“generate”取出 DOT 代码。调用工具层校验渲染 DOT 代码。校验失败则把错误信息追加到 messages回到第 2 步重新生成。校验成功则渲染输出并结束循环。这个循环把大模型的自我纠错能力限制在一个可控范围内。它允许模型犯错但不会让模型无限犯错。最大轮数一旦耗尽Agent 就返回失败不会产生不可控行为。2.4 结果输出架构图的格式选型架构图 Agent 的输出格式选择直接影响实现复杂度。常见选择有 Graphviz DOT、PlantUML、JSON 关系数据和图片文件。DOT 的优点是语法简单、生态成熟、渲染结果稳定。Graphviz 的dot命令几乎可以在所有系统上运行支持输出 SVG、PNG 甚至 PDF。SVG 文件体积小、可直接嵌入网页和文档后续还可以二次编辑是个人工具和内部工具的首选。PlantUML 的优势是类 Java 的语法更容易阅读但需要额外的 Java 运行时安装链比 Graphviz 长。纯 JSON 关系数据适合作为中间格式方便后续转成其他图表或导入其他工具但用户拿到 JSON 后仍然需要自己完成渲染。表格对比可以这样看输出格式优点缺点适用场景Graphviz DOT / SVG语法简单、渲染稳定、安装轻量复杂布局需要手动调整最小实现、内部工具、文档插图PlantUML语法更接近程序语言、序列图支持好依赖 Java渲染链路较重已有 Java 环境、需要时序图JSON 关系数据结构清晰、可编程处理需要二次渲染不直观作为中间层、数据交换PNG 图片查看方便、兼容所有编辑器不易修改、放大模糊汇报、演示、对外交付对于本文的最小实现选择 Graphviz DOT 加 SVG 输出。原因是它在部署成本和结果可用性之间最平衡。3. 环境准备与项目结构3.1 技术选型实现一个最小架构图 Agent技术栈不需要复杂。核心工具是三样Python 用于编排OpenAI 兼容接口用于大模型对话Graphviz 用于渲染。不需要引入 LangChain 或 LlamaIndex 这类重量级框架因为基础 Agent 循环本身只有几十行代码。先亲手实现一次循环再考虑框架理解会深很多。Python 版本建议 3.10 及以上。大模型接口使用requests直接调用 HTTP API不额外封装方便理解对话协议。3.2 环境依赖需要安装两部分环境。第一部分是 Python 依赖。创建一个requirements.txt内容如下requests2.31.0第二部分是 Graphviz。不同系统的安装方式不同# Ubuntu / Debian sudo apt install graphviz # macOS brew install graphviz # Windows choco install graphviz安装完成后在终端执行dot -V能输出版本信息即代表成功dot -V如果运行 Agent 时报 “dot: command not found”说明 Graphviz 没有安装或者安装后没有把dot命令加入 PATH。大模型接口方面需要准备一个可用环境变量OPENAI_API_KEY。如果你的模型服务兼容 OpenAI 的/v1/chat/completions协议可以把服务的 base_url 传进来。最小实现里使用环境变量读取 API Key避免把密钥写进代码export OPENAI_API_KEY你的密钥3.3 目录结构项目目录可以这样组织archi-agent/ ├── agent/ │ ├── __init__.py │ ├── agent.py │ ├── llm.py │ ├── protocol.py │ └── tools.py ├── output/ ├── cli.py └── requirements.txtllm.py负责大模型对话调用tools.py负责 DOT 校验和渲染protocol.py负责解析模型返回的动作指令agent.py是主循环cli.py是命令行入口。这种拆分对于最小项目已经足够后续扩展时可以再把配置、日志、缓存独立成模块。4. 实现最小可运行的架构图 Agent4.1 定义消息协议Agent 和大模型之间需要一套固定协议。协议的作用是让模型的输出能被程序解析而不是一段随意发挥的文本。协议定义如下模型每次返回一个 JSON 对象包含action、dot_code、message三个字段。action为generate时dot_code保存 Graphviz DOT 代码。action为ask时message保存需要向用户补充的问题。action为其他值时程序按异常处理并提示模型修正。在 system prompt 中把协议写清楚能显著降低输出解析失败的概率def build_system_prompt() - str: return 你是一个软件架构图生成助手。你的任务是根据用户需求生成 Graphviz DOT 代码。 输出要求 - 只输出一个 JSON 对象不要输出 Markdown 代码块。 - 格式{action: generate, dot_code: digraph G {...}, message: 简要说明} - 如果用户需求中的模块、关系、边界不明确输出 {action: ask, message: 需要补充的问题} DOT 代码要求 - 使用 digraph 结构。 - 节点 id 使用英文和下划线。 - 节点 label 可以使用中文但特殊字符必须转义。 - 必须能通过 graphviz 的 dot 命令渲染。 这个 prompt 里的关键点有两个一是要求“只输出 JSON 对象”避免模型在 JSON 外层套 Markdown 代码块二是明确“可以提问”让 Agent 在信息不足时不至于硬编一个错误架构。解析函数放在protocol.py里import json def parse_llm_content(content: str) - dict: text content.strip() if text.startswith(): text text.strip() if text.startswith(json): text text[4:].strip() return json.loads(text)这里兼容了模型偶尔输出代码块的场景。如果仍然解析失败异常会抛出到主循环中主循环会把异常信息反馈给模型让模型重新输出。4.2 实现 LLM 调用层llm.py负责调用大模型接口。代码如下import os import requests def chat_completion( messages, modelgpt-4o-mini, temperature0.2, base_urlhttps://api.openai.com/v1, ): api_key os.environ.get(OPENAI_API_KEY) if not api_key: raise RuntimeError(缺少 OPENAI_API_KEY 环境变量) url base_url.rstrip(/) /chat/completions headers { Authorization: fBearer {api_key}, Content-Type: application/json, } payload { model: model, messages: messages, temperature: temperature, } response requests.post(url, headersheaders, jsonpayload, timeout60) response.raise_for_status() data response.json() return data[choices][0][message][content]温度设置为 0.2目的是让模型输出更稳定、更接近结构化结果。架构图生成属于“格式确定性优先”的任务不追求创意因此温度不要太高。如果使用的模型服务不在官方地址比如企业内部部署的兼容服务只需要在调用时传入base_url即可不需要改其他代码。4.3 实现 DOT 渲染工具tools.py中实现两个函数validate_dot和render_dot_svg。validate_dot负责把 DOT 代码写入临时文件调用dot命令渲染到空输出同时捕获标准错误。渲染成功则返回(True, )失败则返回(False, 错误信息)。import os import shutil import subprocess import tempfile def validate_dot(dot_text: str) - tuple[bool, str]: if not shutil.which(dot): return False, 未找到 graphviz 的 dot 命令请先安装 graphviz with tempfile.TemporaryDirectory() as tmpdir: dot_path os.path.join(tmpdir, input.dot) with open(dot_path, w, encodingutf-8) as f: f.write(dot_text) proc subprocess.run( [dot, -Tsvg, dot_path], capture_outputTrue, textTrue, timeout30, ) if proc.returncode ! 0: return False, proc.stderr[-500:] return True, 注意这里没有把 SVG 写到磁盘只是让dot执行一次真实解析。这样做的目的是把校验和渲染分离校验失败时不产生残留在磁盘上的多余文件。render_dot_svg则在校验通过后输出最终图片def render_dot_svg(dot_text: str, output_path: str output/architecture.svg) - str: output_dir os.path.dirname(os.path.abspath(output_path)) os.makedirs(output_dir, exist_okTrue) with tempfile.TemporaryDirectory() as tmpdir: dot_path os.path.join(tmpdir, input.dot) with open(dot_path, w, encodingutf-8) as f: f.write(dot_text) proc subprocess.run( [dot, -Tsvg, dot_path, -o, output_path], capture_outputTrue, textTrue, timeout30, ) if proc.returncode ! 0: raise RuntimeError(proc.stderr[-500:]) return output_path4.4 组装 Agent 主循环agent.py是整个项目的核心。它维护一个 messages 列表作为 Agent 的“记忆”在每一步对话中加入新的结果与反馈。import json from .llm import chat_completion from .protocol import parse_llm_content from .tools import validate_dot, render_dot_svg from .agent_prompt import build_system_prompt def run_agent(user_input: str, max_rounds: int 4, output_path: str output/architecture.svg): messages [{role: system, content: build_system_prompt()}] messages.append({role: user, content: user_input}) for _ in range(max_rounds): response chat_completion(messages) messages.append({role: assistant, content: response}) try: parsed parse_llm_content(response) except json.JSONDecodeError as exc: messages.append({ role: user, content: f上一轮输出不是合法 JSON请重新输出完整 JSON。错误信息{exc}, }) continue action parsed.get(action) if action ask: return { status: need_more_info, message: parsed.get(message, ), } if action generate: dot_code parsed.get(dot_code, ) ok, err validate_dot(dot_code) if not ok: messages.append({ role: user, content: fDOT 渲染失败{err}。请修正 DOT 代码后重新输出完整 JSON。, }) continue final_path render_dot_svg(dot_code, output_path) return { status: success, dot_code: dot_code, output_path: final_path, message: parsed.get(message, ), } messages.append({ role: user, content: f未知 action{action}。请只使用 generate 或 ask。, }) return { status: timeout, message: 达到最大迭代次数仍未生成有效架构图。, }主循环的核心逻辑是“把每一条失败信息都变成下一次对话的上下文”。这是 Agent 能够自我修正的关键。模型第一次生成的 DOT 代码可能有语法错误但dot命令返回的错误信息会进入下一轮输入模型看到错误后重新生成成功率会明显提高。写完后把 system prompt 独立到agent_prompt.py中避免和主逻辑混在一起。4.5 增加 CLI 入口cli.py让项目可以从命令行动起来import sys from agent.agent import run_agent if __name__ __main__: user_input sys.argv[1] if len(sys.argv) 1 else input(描述你的系统) result run_agent(user_input) print(result)使用时直接运行python cli.py 帮我画一个用户登录系统的架构图包含前端、网关、认证服务、用户服务和数据库运行完成后可以在output/architecture.svg找到生成的 SVG 文件。5. 运行验证与输出分析5.1 一个完整的输入输出示例假设输入是帮我画一个微服务架构图包含 API 网关、订单服务、用户服务、商品服务、消息队列和 MySQL 数据库订单服务通过消息队列异步通知用户服务。Agent 可能经过两轮生成得到类似下面的 DOT 代码digraph architecture { rankdirLR; node [shapebox, stylerounded, fontnameHeiti SC]; gateway [labelAPI 网关]; order [label订单服务]; user [label用户服务]; product [label商品服务]; mq [label消息队列]; db [labelMySQL 数据库]; gateway - order; gateway - user; gateway - product; order - mq; mq - user; order - db; user - db; product - db; }如果第一轮生成的 DOT 有语法错误程序会返回类似下面的反馈信息并进入下一轮DOT 渲染失败Error: syntax error in line 8 near labelAgent 会把这条错误信息拼接到下一轮对话中让模型自己修正。5.2 验证步骤运行后建议按下面顺序检查观察命令行返回的status字段是否为success。检查output_path指向的文件是否存在。用浏览器或图片查看器打开 SVG 文件。打开同一个 SVG 的源码确认图中节点数量与需求是否匹配。对照需求检查服务之间调用关系是否有遗漏或错误。如果状态为need_more_info说明 Agent 认为信息不足需要补充模块或关系后再运行。如果状态为timeout说明模型连续多轮都没有生成可渲染的 DOT需要检查系统 prompt、模型选择和 API 返回内容。5.3 从输出反推质量生成架构图后质量评估可以从三个维度进行。维度一是结构清晰度。图中是否只有必要的节点和边是否可以通过子图合理分组部署层次是否看得清楚。Graphviz 的自动布局有时会把边画得很乱这时可以在 DOT 代码中使用rankdir、ranksame、subgraph cluster_xxx来控制布局节奏。维度二是关系准确性。服务之间的箭头方向是否正确数据流方向是否一致是否把“同步调用”和“异步消息”混在一条边上。当前最小实现没有区分边类型实际使用中可以要求模型为边添加不同颜色或样式。维度三是信息完整性。用户提到的关键组件是否都出现在图中没有提到的多余组件是否越界。要避免模型为了“好看”而凭空添加缓存、日志、监控等组件除非用户明确要求。6. 常见问题与排查路径6.1 LLM 返回了非法 JSON现象程序抛出JSONDecodeError或者主循环不断进入parse_llm_content的异常分支。可能原因模型在 JSON 外层加了 Markdown 代码块JSON 内部出现了单引号、尾逗号或者dot_code中的双引号没有转义。检查方式打印原始response文本前后截取 200 字观察格式。处理建议在 system prompt 中再次强调“只输出 JSON 对象不要 Markdown 代码块”在解析函数中兼容代码块前缀同时要求模型在 JSON 字符串中统一用\转义 DOT 里的引号。6.2 DOT 语法校验失败现象程序返回DOT 渲染失败并带有一段dot命令的标准错误输出。可能原因节点 id 使用了中文或空格label 中的引号没有转义边定义写成了-但缺少分号或使用了 Graphviz 不支持的字符。检查方式把dot_code单独保存成.dot文件在终端手动执行dot -Tsvg input.dot -o out.svg处理建议根据错误行号定位问题要求模型用英文下划线格式命名节点 id在 DOT 代码段后追加“必须能通过 dot 命令直接渲染”的约束保留错误信息的最近 500 个字符反馈给模型避免上下文过长。6.3 多轮对话上下文膨胀现象随着轮数增加请求耗时变长费用变高模型开始遗漏早期需求。可能原因每一轮都把完整 DOT 代码和错误信息追加到 messages 中三轮以后上下文里可能积累了两三千 token 的无效内容。检查方式打印每轮 messages 的总 token 或字符数观察增长趋势。处理建议给max_rounds设置较小值比如 3 到 4当校验失败时只把错误摘要加入上下文而不是完整 DOT 代码如果项目进一步发展可以在每一轮都重新固定 system prompt只保留最初的用户需求不保留除最近一轮以外的历史输出。6.4 生成的架构图信息过载现象图能正常渲染但节点数量超过 30 个边交叉严重整体无法阅读。可能原因用户输入描述过于宽泛比如“画出整个系统的架构图”而系统本身包含几十个微服务和大量中间件。检查方式统计 dot_code 中的节点数量。处理建议在 system prompt 中增加“优先展示主要模块次要模块归入分组或省略”的约束当模型需要处理过大系统时主动要求用户拆分成子系统实现子图分组例如在集群外展示服务入口和数据库集群内展示核心服务。7. 从玩具到生产架构图 Agent 的工程化建议7.1 功能上的扩展方向最小实现跑通后可以沿着几个方向扩展。支持本地代码仓库分析。把用户输入的仓库路径交给 Agent模型先扫描模块目录和依赖文件再生成模块依赖图。这样可以减少用户手动描述的工作量。支持多轮交互式构建。允许用户对生成的图提出修改意见例如“把用户服务拆分出来”“增加 Redis 缓存层”“把数据库单独放到一个 cluster 中”每次修改都重新生成 DOT 并渲染。支持多种输出格式。除 SVG 外可以增加 PNG、JSON 关系数据以及面向不同工具的 DSL 转换。把中间结果统一成 JSON再派生出其他格式是最稳妥的做法。7.2 安全与权限边界架构图 Agent 涉及大模型调用和文件系统操作生产化时需要明确权限边界。不要把 API Key 写死在代码或前端使用环境变量或密钥管理服务。不要把用户输入直接拼进 system prompt 而不做任何过滤。如果 Agent 未来要读取本地文件或调用 Git 命令建议在独立 sandbox 中运行限制可访问目录禁止危险命令例如删除、格式化、网络穿越等。所有外部命令执行都应设置超时例如本文代码中的timeout30避免渲染过程卡死。7.3 成本与性能控制每次调用大模型都会产生费用和延迟。生产环境中可以采取以下手段。限制每一轮对话的最大 token 数防止模型输出无节制的长 DOT 代码。将渲染失败的错误信息截断后再回传降低上下文成本。对相同输入做缓存例如按输入文本的哈希值缓存上一次成功生成的 DOT 和 SVG。低频内部工具可以直接使用较小的模型只有生成质量不稳定时再切换更大模型。7.4 从热榜项目到自身能力的学习路径当你在 GitHub Trending 看到一个架构图 Agent 类项目时不要只盯着 star 数。按照下面这个顺序学习往往比收藏仓库更有价值。先看 README 的示例图明确它解决什么场景。再看它的 Agent 循环代码找到run或execute主函数理解循环结构。然后看它如何组织 prompt重点关注输出协议和错误反馈。接着看它的工具层确认它真的调用了渲染器还是只输出文本。最后看它的防错设计包括超时、重试、上下文控制和质量校验。这套流程同样适用于学习其他 Agent 类开源项目。热榜只是入口持续拆解能力才是真正能积累的东西。8. 值得持续关注的三个问题8.1 让 Agent 理解系统而不是只会画框很多架构图 Agent 只是把自然语言描述翻成图形本质上是提示词模板加渲染器。这种做法对简单系统足够对复杂系统远远不够。真正有价值的 Agent应该在生成图之前先理解系统的边界、层次、依赖方向和变化原因。这意味着后续可以引入代码扫描、配置文件解析、运行时调用链分析而不是只依赖用户描述。这也是为什么学习 Agent 循环比学习某个框架更重要。框架会更新协议会变化但“理解输入、调用工具、获取反馈、修正输出”这个循环不会过时。8.2 最小闭环检查清单在把本文代码用于更复杂的场景之前建议按照下面的清单检查一遍能否通过环境变量读取 API Key而不是写死在代码中。模型返回 JSON 后程序是否能稳定解析并处理异常。校验失败的 DOT 是否能自动回传错误信息并触发重试。最大循环次数是否有限制避免无限调用造成费用失控。SVG 输出路径是否可配置目录是否存在且可写。所有外部命令是否设置了超时。生成的 SVG 是否经过人工检查而不是只检查程序退出码。这份清单同样适用于你之后读到、自己扩展的任何 Agent 项目。8.3 下一个练习方向如果本文的最小实现已经跑通下一步可以尝试三个练习。第一增加子图分组功能让 Agent 在生成 DOT 时自动使用subgraph cluster_xxx组织模块。第二增加“边类型”概念区分同步调用、异步消息、数据库访问用不同颜色和线型表现。第三接入一个真实的代码仓库先让脚本扫描出服务依赖文件再把扫描结果交给 Agent 生成系统架构图。三个练习完成之后你对 Agent 的理解会从“会调接口”变成“会构建交付链路”这才是架构图 Agent 类项目真正想解决的事情。GitHub 热榜上的名字会变但底层能力的复用在每个项目里都会重复出现。
