最近一直在关注 GitHub 上的 Agent 类开源项目发现一个很有意思的赛道连续多天霸榜架构图生成 Agent。这类项目用自然语言描述系统需求就能自动生成微服务架构图、系统架构图、技术架构图演示效果非常直观很多开发者看完的第一反应都是“这不正是我画架构文档时最需要的东西吗”。传统画架构图的方式确实存在明显痛点用 Draw.io、Visio 这类工具手动拖拽节点耗费大量时间手写 Mermaid 代码节点一多就很容易出现缩进混乱、关系丢失、渲染报错。架构图 Agent 要解决的核心问题就是把“画图的时间”还给“设计本身”。这篇文章会从架构图 Agent 的核心概念入手带大家理解它的运行原理然后完整实现一个可运行的“自然语言生成架构图”工具最后分享一些 GitHub 开源项目上榜与长期维护的实践经验。如果你有一定 Python 基础想学习 Agent 开发或者想给自己项目做一个自动画架构图的小工具这篇文章可以直接作为入门参考。1. 架构图 Agent 为什么在 GitHub 上这么火1.1 架构图是刚需但绘制过程很“痛苦”在软件研发流程中架构图是沟通设计和梳理依赖的重要载体。无论是微服务架构图、系统架构图还是技术架构图都能帮助团队成员快速理解系统全貌。但真正画过架构图的人都知道手动绘图工具学习成本不低样式的调整非常繁琐。在项目迭代过程中架构图容易和真实代码脱节最后变成没人维护的“过期文档”。写 Mermaid、PlantUML 这类代码型图表虽然有版本管理优势但语法细节较多容易踩坑。架构图生成 Agent 的切入点非常精准把“让用户画图”变成“让模型画图”。用户只需要描述系统包含哪些模块、模块之间如何调用Agent 就能输出一张结构合理的架构图。1.2 “大模型 图表”是天然适合 Agent 的场景为什么这类项目能在 GitHub Trending 上保持热度从开发者的角度看有几个原因第一结果可视化程度极高。输入一段文字立刻输出一张结构清晰的架构图这种反馈远比其他文本生成类工具更有冲击力。演示截图和动图很容易在社交平台传播。第二技术门槛适中。大模型负责“理解需求”和“抽取关系”开发者只需要做好结构化输出解析和图表渲染不需要训练模型也不需要复杂的算法背景。第三可以解决真实问题。架构图是几乎每个开发团队都会遇到的痛点有真实需求就意味着有用户持续使用和反馈项目自然容易积累口碑和 Star。这类项目火爆的背后本质上反映了一个趋势Agent 的价值不在于“能做多少事情”而在于“能帮助开发者减少多少重复劳动”。2. 架构图 Agent 的核心概念2.1 什么是 AgentAgent智能体这几年是 AI 开发领域的高频词。简单说Agent 是一个能够根据目标自主决策并执行任务的程序系统。与普通程序固定流程不同Agent 的行为由大模型根据当前输入和上下文动态生成。一个典型的 Agent 工作循环包括理解目标把用户输入转化为可执行的任务。拆解步骤规划完成目标需要哪些步骤。调用工具调用外部 API、代码解释器、搜索引擎等工具。观察结果检查工具返回的结果是否符合预期。修正行动如果结果异常调整策略重新执行。架构图 Agent 就是 Agent 在“信息可视化”领域的具体应用。它把自然语言描述转化为结构化的图表描述再渲染为图片。2.2 架构图 Agent 与传统模板填充的区别有人可能会问用一段预设好的提示词让大模型输出 Mermaid不也能生成架构图吗为什么需要 Agent区别在于“稳定性和自省能力”。简单提示词方案通常存在几个问题大模型输出的 Mermaid 代码经常有语法错误节点 ID 包含非法字符时直接渲染失败。用户表达能力不同提示词稍一复杂模型就会漏掉模块关系。没有校验也没有重试机制生成的图表质量完全不可控。而架构图 Agent 的核心改进在于让模型先输出结构化数据JSON而不是直接输出 Mermaid 语法。对 JSON 做二次校验确保节点和边的字段完整。渲染前检查 Mermaid 语法的关键规则出错时携带错误信息让模型重新生成。这种“先生成数据再转换渲染再校验修正”的流程比单纯依赖提示词要稳定得多。2.3 一个完整的工作流程我们可以把架构图 Agent 拆成四个模块模块职责关键技术点输入理解模块接收自然语言描述大模型 Prompt信息抽取模块输出结构化节点和关系强制 JSON 输出图生成模块把 JSON 转为 Mermaid语法映射规则渲染与校验模块渲染为图片并检查错误mermaid-cli、前端渲染用户输入“一个电商系统包含前端、网关、订单服务、商品服务、用户服务和数据库”Agent 会先抽取六个组件的类型和依赖关系再转换为 Mermaid 代码最后渲染成一张完整的系统架构图。3. 环境准备与项目结构在动手写代码之前先确认一下环境。本文的示例以 Python 3.10 为主同时需要准备一个可调用的 LLM API兼容 OpenAI 接口格式即可不需要限定具体服务商。3.1 环境要求环境项推荐配置说明操作系统Windows / macOS / Linux本文命令以 Linux/macOS 风格为例Python3.10 及以上需要支持新版类型语法包管理工具pip用于安装依赖LLM APIOpenAI 兼容接口需要配置 API Key 和 Base URLNode.js18可选仅当需要本地渲染 PNG/SVG 时使用如果你所在环境无法访问某些服务请自行确认网络可用性这里只讨论代码实现本身。3.2 依赖清单依赖库不需要太多核心只需要几个openai1.0.0 fastapi0.104.0 uvicorn0.24.0 python-dotenv1.0.0 pydantic2.0.03.3 项目目录我们实现一个叫arch-agent的项目目录结构如下arch-agent/ ├── requirements.txt # 依赖清单 ├── .env.example # 环境变量模板 ├── config.py # 读取环境变量配置 ├── llm_client.py # 调用 LLM API 获取结构化 JSON ├── generator.py # 将 JSON 转为 Mermaid 代码 ├── main.py # FastAPI 服务入口 ├── index.html # 前端页面 └── README.md # 项目说明文档后面的代码都会按这个结构展开方便你直接参照创建文件。4. 核心原理拆解这一节先把架构图 Agent 的几个关键实现点讲清楚方便后续实战部分快速理解。4.1 让大模型输出结构化 JSON大模型默认输出是自然语言。为了让它可以被程序稳定处理我们需要约束输出格式。OpenAI 兼容接口中常用的做法是使用response_format参数from openai import OpenAI client OpenAI( api_key你的API_KEY, base_url你的BASE_URL, ) response client.chat.completions.create( modelgpt-4o-mini, response_format{type: json_object}, messages[ {role: system, content: 你是一个架构师只输出 JSON。}, {role: user, content: 请抽取系统组件和依赖关系。}, ], )需要注意的是response_format并不是所有兼容服务都支持。如果你的服务商不支持可以去掉这个参数然后在提示词里明确要求“只输出 JSON不要输出任何解释”再用字符串解析兜底。4.2 设计节点和边的 JSON Schema为了让生成结果可预测我们需要定义一个简单的 JSON 结构。它由两个字段组成nodes架构图中的所有组件节点。edges节点之间的关系。每个节点包含id、label和type三个字段type用来描述节点类型比如网关、服务、数据库、缓存。每个边包含from、to和label三个字段分别表示起点、终点和关系描述。示例{ nodes: [ {id: gateway, label: API网关, type: gateway}, {id: order, label: 订单服务, type: service}, {id: db, label: 订单数据库, type: db} ], edges: [ {from: gateway, to: order, label: 调用}, {from: order, to: db, label: 读写} ] }实际开发中你还可以扩展更多字段比如节点样式、子图分组、颜色标识等。但前期保持简单更容易把流程跑通。4.3 从 JSON 到 Mermaid 的映射规则Mermaid 是当前 GitHub 原生支持的图表语法也是这类项目最常使用的输出格式。一个简单架构图的 Mermaid 代码如下graph LR gateway[API网关] order[订单服务] db[(订单数据库)] gateway --|调用| order order --|读写| db从 JSON 到 Mermaid 的转换规则如下每个node对应一行节点定义。db类型的节点使用[(名称)]语法表示圆柱体。cache类型的节点使用{名称}语法表示。每个edge对应一行箭头连接。4.4 图片渲染的几种方式拿到 Mermaid 代码后有三种常见渲染方式方式优点缺点前端 mermaid.js用户体验好实时预览需要浏览器环境mermaid-cli 命令行渲染可生成 PNG/SVG 文件需要安装 Node.js 环境mermaid.ink 在线 API请求简单适合快速测试依赖外部在线服务在本文的实战项目中我们会优先使用前端 mermaid.js 渲染这样在浏览器里看效果最直观也可以一键下载截图。5. 完整实战实现一个可用的架构图 Agent5.1 创建项目并安装依赖打开终端创建项目目录并初始化虚拟环境mkdir arch-agent cd arch-agent python -m venv venv source venv/bin/activate pip install openai fastapi uvicorn python-dotenv pydantic如果使用的是 Windows激活命令是venv\Scripts\activate5.2 准备环境变量文件在项目目录下创建.env.exampleLLM_API_KEYsk-你的密钥 LLM_BASE_URLhttps://api.openai.com/v1 LLM_MODELgpt-4o-mini创建.env文件并填入你自己的配置。需要特别提醒的是.env文件包含敏感信息不要把真实密钥提交到 Git 仓库。创建一个config.py用于统一读取配置import os from dotenv import load_dotenv load_dotenv() LLM_API_KEY os.getenv(LLM_API_KEY, ) LLM_BASE_URL os.getenv(LLM_BASE_URL, https://api.openai.com/v1) LLM_MODEL os.getenv(LLM_MODEL, gpt-4o-mini)5.3 编写 LLM 客户端创建llm_client.py封装大模型调用逻辑import json from openai import OpenAI import config class LLMClient: def __init__(self) - None: self.client OpenAI( api_keyconfig.LLM_API_KEY, base_urlconfig.LLM_BASE_URL, ) self.model config.LLM_MODEL def extract_architecture(self, description: str) - dict: system_prompt 你是一名系统架构设计师。用户会提供一段关于系统的描述。 你需要从中提取架构组件和组件之间的依赖关系并输出 JSON 格式的结果。 JSON 结构必须严格遵循以下格式 { nodes: [ {id: string, label: string, type: gateway|service|db|cache|client} ], edges: [ {from: string, to: string, label: string} ] } 节点类型说明 - gateway网关或入口 - service服务模块 - db数据库 - cache缓存 - client客户端 请只输出 JSON不要输出任何解释或多余内容。 messages [ {role: system, content: system_prompt}, {role: user, content: description}, ] try: response self.client.chat.completions.create( modelself.model, messagesmessages, temperature0.2, response_format{type: json_object}, ) content response.choices[0].message.content return json.loads(content) except Exception as e: raise RuntimeError(fLLM 调用失败: {e})这里的关键点是temperature0.2较低的采样温度可以让模型输出更稳定减少结构遗漏。5.4 编写 JSON 转 Mermaid 的生成器创建generator.pydef dict_to_mermaid(arch: dict) - str: 将架构 JSON 转换为 Mermaid 代码 lines [graph LR] for node in arch.get(nodes, []): node_id node[id] label node[label] node_type node.get(type, service) if node_type db: lines.append(f {node_id}[({label})]) elif node_type cache: lines.append(f {node_id}{{{label}}}) elif node_type gateway: lines.append(f {node_id}{{{label}}}) elif node_type client: lines.append(f {node_id}[{label}]) else: lines.append(f {node_id}[{label}]) for edge in arch.get(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)这个函数把模型输出的结构化 JSON 映射为 Mermaid 节点和边。实际使用中需要注意节点id中不要包含空格、括号等特殊字符否则 Mermaid 渲染很可能报错。可以在解析层增加清洗逻辑import re def clean_node_id(node_id: str) - str: 清洗节点 ID只保留字母、数字和下划线 return re.sub(r[^a-zA-Z0-9_], _, node_id)5.5 编写 FastAPI 服务创建main.pyfrom fastapi import FastAPI from fastapi.responses import HTMLResponse from pydantic import BaseModel from llm_client import LLMClient from generator import dict_to_mermaid app FastAPI() llm_client LLMClient() class GenerateRequest(BaseModel): description: str app.post(/api/generate) def generate_architecture(req: GenerateRequest): 接收自然语言描述返回 Mermaid 代码和结构化数据 arch llm_client.extract_architecture(req.description) mermaid_code dict_to_mermaid(arch) return { mermaid: mermaid_code, arch: arch, } app.get(/, response_classHTMLResponse) def index(): with open(index.html, encodingutf-8) as f: return HTMLResponse(f.read())这个接口做了两件事调用大模型抽取架构信息然后把 JSON 转成 Mermaid 代码。前端拿到 Mermaid 代码后通过 mermaid.js 实时渲染成图。5.6 编写前端页面创建index.html!DOCTYPE html html langzh-CN head meta charsetUTF-8 meta nameviewport contentwidthdevice-width, initial-scale1.0 title架构图 Agent/title script srchttps://cdn.jsdelivr.net/npm/mermaid10/dist/mermaid.min.js/script style body { font-family: -apple-system, PingFang SC, sans-serif; max-width: 960px; margin: 40px auto; padding: 0 20px; background: #f6f8fa; color: #24292f; } textarea { width: 100%; height: 80px; padding: 12px; font-size: 14px; border: 1px solid #d0d7de; border-radius: 6px; box-sizing: border-box; } button { margin-top: 12px; padding: 10px 24px; background: #2da44e; color: #fff; border: none; border-radius: 6px; font-size: 14px; cursor: pointer; } button:disabled { background: #94d3a2; cursor: not-allowed; } #graph { background: #fff; border: 1px solid #d0d7de; border-radius: 6px; padding: 24px; margin-top: 20px; text-align: center; } /style /head body h1架构图生成 Agent/h1 p输入一段系统描述自动生成架构图。/p textarea iddesc placeholder例如一个电商系统包含前端、网关、订单服务、商品服务、用户服务订单服务依赖订单数据库商品服务依赖商品数据库用户服务依赖用户数据库。/textarea br button idrun生成架构图/button div idgraph div classmermaid graph LR placeholder[等待生成] /div /div script document.getElementById(run).addEventListener(click, async function () { const desc document.getElementById(desc).value; if (!desc) { alert(请输入系统描述); return; } const btn document.getElementById(run); btn.disabled true; btn.textContent 生成中...; try { const resp await fetch(/api/generate, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify({ description: desc }) }); const data await resp.json(); renderMermaid(data.mermaid); } catch (err) { alert(生成失败 err.message); } finally { btn.disabled false; btn.textContent 生成架构图; } }); function renderMermaid(code) { const container document.getElementById(graph); container.innerHTML div classmermaid/div; const el container.querySelector(.mermaid); el.textContent code; mermaid.run({ nodes: [el] }); } /script /body /html前端页面使用了 Mermaid 的浏览器运行时不需要额外安装 Node.js 环境打开页面就能渲染架构图。5.7 运行与验证启动 FastAPI 服务uvicorn main:app --reload --host 0.0.0.0 --port 8000浏览器访问http://127.0.0.1:8000在输入框中填写系统描述点击“生成架构图”。也可以先用 curl 验证接口curl -X POST http://127.0.0.1:8000/api/generate \ -H Content-Type: application/json \ -d {description: 一个订单系统包含前端、网关、订单服务、用户服务订单服务依赖订单数据库用户服务调用订单服务}预期返回结果类似{ mermaid: graph LR\n gateway{{API网关}}\n order[订单服务]\n user[用户服务]\n db[(\订单数据库\)]\n gateway --|转发| order\n order --|读写| db\n user --|调用| order, arch: { nodes: [], edges: [] } }arch中的具体内容会因模型输出而略有不同但mermaid字段应该可以直接被 Mermaid 渲染。5.8 进阶加上校验重试的 Agent 循环一个真正有“Agent 味”的版本应该包含错误反馈和自我修正。当生成的 Mermaid 无法渲染时可以把渲染错误信息回传给模型让它重新生成。在llm_client.py中增加一个带重试的方法def extract_with_retry(self, description: str, error_msg: str ) - dict: user_content description if error_msg: user_content f{description}\n\n上次生成的架构 JSON 存在问题{error_msg}\n请修正后重新输出 JSON。 # 继续调用 extract_architecture然后在主程序中捕获渲染异常进入重试循环。这个设计虽然简单但它体现了 Agent 的核心思想观察结果、发现问题、携带上下文重新执行。6. GitHub 开源项目上榜的实践经验6.1 GitHub Trending 究竟在推荐什么参加过大热项目的开发者都知道GitHub Trending 的排序并不只看总 Star 数而是看 Star 的“增长速度”。一个新建仓库如果短时间内获得大量 Star会比一个老牌项目更容易上榜。从我的观察来看能被 Trending 推荐的项目通常满足几个条件主题踩中当前热点。AI Agent、大模型应用、自动化工具这些关键词本身就自带流量。项目有清晰可见的演示效果。架构图 Agent 用一张动态生成的架构图截图就能让用户秒懂项目价值。README 质量高安装和使用步骤足够简单。作者在项目发布的第一周保持更新频率及时修复用户反馈的 issue。6.2 让 README 成为项目最好的“门面”很多开发者低估了 README 的重要性。GitHub 用户决定是否点 Star往往只花几十秒浏览 README。一个专业的 README 应该包含以下结构项目名称和一句精准的简介。一张核心功能演示截图或 GIF这一步最重要。功能特性列表让用户快速了解它能做什么。安装和快速开始用尽量少的命令让用户跑起来。真实的使用示例包含输入和输出。常见问题 FAQ减少不必要的 issue。License、贡献指南、联系方式等补充信息。在写 README 时还有一个容易被忽略的细节项目描述Description要包含关键词。比如“架构图 Agent”“自然语言生成架构图”“Mermaid 自动生成”这类描述能提高项目在 GitHub 搜索中被发现的概率。6.3 从 Trending 到长期维护登上 Trending 只是第一步。很多项目火了一周后因为作者不维护Star 数就停滞不前。长期维护比短期上榜更重要。建议保持以下节奏每周至少发布一次新版本哪怕是修复小 bug。及时回复 issue 和 PR让贡献者感受到项目是“活的”。定期整理 Release Notes记录每个版本的变化。把用户提得最多的问题沉淀到 FAQ 文档中。围绕项目写一些技术解析文章吸引更多开发者进入社区。开源项目的本质不是“代码仓库”而是一个“开发者社区”。代码只是载体真正让项目持续增长的是作者与使用者之间持续互动的过程。7. 常见问题与排查思路问题现象常见原因解决思路LLM 返回的内容无法解析为 JSON服务商不支持response_format参数或模型输出包含额外文字去掉response_format在提示词中强制要求只输出 JSON解析前进行字符串截取Mermaid 渲染报错节点 ID 包含非法字符或 JSON 中缺少关键字段增加节点 ID 清洗函数先用json.loads校验结构再进行转换页面能打开但生成按钮无反应FastAPI 接口跨域问题或前端页面调用地址错误检查浏览器 Console 报错确认请求地址是否为http://127.0.0.1:8000/api/generate生成速度慢模型参数量大或网络请求延迟较高换用更轻量的模型设置合理的超时时间减少重复轮次架构图节点过多无法阅读用户描述太复杂模型一次抽取的节点过多增加节点数量限制超出后提示用户拆分描述GitHub 仓库克隆速度慢且不稳定网络环境差异导致的仓库拉取缓慢使用git clone配合代理配置或者将仓库先导入国内平台后再本地拉取部署到服务器后无法访问云服务安全组未开放端口检查服务监听地址是否为0.0.0.0并确认安全组放行对应端口遇到报错时不要只盯着错误信息的最后一行。先确认数据格式是否正确再确认渲染环节是否出错最后检查前后端交互。逐层定位是排查问题最高效的方式。8. 最佳实践与工程化建议8.1 Prompt 和结构化输出把 System Prompt 单独抽成一个配置文件或模板文件方便反复调优。不要在 Python 代码里写过长字符串。在提示词中明确“只输出 JSON”并给出一个示例 JSON 结构模型输出质量会有明显提升。如果模型偶尔输出脏数据可以在解析层做“修复”比如缺少label时用id兜底type不合法时默认按service处理。8.2 安全与密钥管理大模型 API Key 是敏感信息绝不能写死在代码里也不能提交到 Git 仓库。推荐使用.env文件加python-dotenv管理。如果项目要公开一定要在.gitignore中加入.env。生产中还需要注意给 API 调用设置超时时间避免长时间阻塞。对用户输入长度做限制防止恶意超长文本消耗 token。日志中不要打印完整的请求和响应内容尤其是密钥和用户隐私数据。如果服务面向公网建议增加登录鉴权或简单的访问控制。8.3 成本与性能优化架构图生成属于轻量级任务对延迟不是特别敏感但成本控制仍然值得注意。建议从这几个方面入手使用性价比更高的模型比如gpt-4o-mini这类轻量模型而不是每个请求都调用最大参数模型。对描述内容做长度截断超长文本先让模型做摘要。引入缓存相同或高度相似的描述直接返回缓存结果减少重复调用。前端渲染交给 Mermaid.js 完成后端只返回结构化数据减少服务端渲染压力。8.4 可扩展方向架构图 Agent 只是 Agent 应用的一个方向。完成这个项目后你还可以继续扩展支持输出 PlantUML、D2、Graphviz 等多种格式。支持按微服务架构图模板进行领域划分自动生成子图分组。加入“对话式修正”用户可以说“订单服务和用户服务之间不用直连”Agent 根据反馈调整架构。与代码仓库打通读取 Dockerfile、服务编排文件逆向生成部署架构图。这些方向的核心逻辑和本文实现的项目是一致的利用大模型理解需求用结构化数据保证输出稳定再通过渲染层把数据变成用户能直接使用的结果。9. 总结与后续学习路线这篇文章从 GitHub 上架构图 Agent 项目火热的现状出发梳理了 Agent 的基本概念和工作循环然后完整实现了“自然语言描述 → 结构化 JSON → Mermaid 代码 → 前端渲染”的架构图生成工具。核心代码包含 LLM 客户端封装、JSON 转 Mermaid 映射、FastAPI 服务接口和浏览器渲染页面整体结构比较简单但已经具备一个真实 Agent 应用的主要模块。如果你是第一次接触 Agent 开发建议先用本文的代码跑通整个链路再逐步加入校验重试、多轮修正、更多图表格式支持。最终你会发现Agent 应用没有想象中那么神秘关键是把“模型输出”和“程序逻辑”之间的接口设计好。如果你希望项目也能进入 GitHub Trending不妨先把自己的工具打磨到“自己每天都在用”的程度再用规范的 README 展示出去。持续维护一个开源项目远比一次上榜更有价值。如果本文对你有帮助可以收藏备用。下次需要画微服务架构图时试试让 Agent 帮你生成你会发现画图这件事其实可以很简单。 自然语言生成架构图：基于大模型Agent的实战解析
最近一直在关注 GitHub 上的 Agent 类开源项目发现一个很有意思的赛道连续多天霸榜架构图生成 Agent。这类项目用自然语言描述系统需求就能自动生成微服务架构图、系统架构图、技术架构图演示效果非常直观很多开发者看完的第一反应都是“这不正是我画架构文档时最需要的东西吗”。传统画架构图的方式确实存在明显痛点用 Draw.io、Visio 这类工具手动拖拽节点耗费大量时间手写 Mermaid 代码节点一多就很容易出现缩进混乱、关系丢失、渲染报错。架构图 Agent 要解决的核心问题就是把“画图的时间”还给“设计本身”。这篇文章会从架构图 Agent 的核心概念入手带大家理解它的运行原理然后完整实现一个可运行的“自然语言生成架构图”工具最后分享一些 GitHub 开源项目上榜与长期维护的实践经验。如果你有一定 Python 基础想学习 Agent 开发或者想给自己项目做一个自动画架构图的小工具这篇文章可以直接作为入门参考。1. 架构图 Agent 为什么在 GitHub 上这么火1.1 架构图是刚需但绘制过程很“痛苦”在软件研发流程中架构图是沟通设计和梳理依赖的重要载体。无论是微服务架构图、系统架构图还是技术架构图都能帮助团队成员快速理解系统全貌。但真正画过架构图的人都知道手动绘图工具学习成本不低样式的调整非常繁琐。在项目迭代过程中架构图容易和真实代码脱节最后变成没人维护的“过期文档”。写 Mermaid、PlantUML 这类代码型图表虽然有版本管理优势但语法细节较多容易踩坑。架构图生成 Agent 的切入点非常精准把“让用户画图”变成“让模型画图”。用户只需要描述系统包含哪些模块、模块之间如何调用Agent 就能输出一张结构合理的架构图。1.2 “大模型 图表”是天然适合 Agent 的场景为什么这类项目能在 GitHub Trending 上保持热度从开发者的角度看有几个原因第一结果可视化程度极高。输入一段文字立刻输出一张结构清晰的架构图这种反馈远比其他文本生成类工具更有冲击力。演示截图和动图很容易在社交平台传播。第二技术门槛适中。大模型负责“理解需求”和“抽取关系”开发者只需要做好结构化输出解析和图表渲染不需要训练模型也不需要复杂的算法背景。第三可以解决真实问题。架构图是几乎每个开发团队都会遇到的痛点有真实需求就意味着有用户持续使用和反馈项目自然容易积累口碑和 Star。这类项目火爆的背后本质上反映了一个趋势Agent 的价值不在于“能做多少事情”而在于“能帮助开发者减少多少重复劳动”。2. 架构图 Agent 的核心概念2.1 什么是 AgentAgent智能体这几年是 AI 开发领域的高频词。简单说Agent 是一个能够根据目标自主决策并执行任务的程序系统。与普通程序固定流程不同Agent 的行为由大模型根据当前输入和上下文动态生成。一个典型的 Agent 工作循环包括理解目标把用户输入转化为可执行的任务。拆解步骤规划完成目标需要哪些步骤。调用工具调用外部 API、代码解释器、搜索引擎等工具。观察结果检查工具返回的结果是否符合预期。修正行动如果结果异常调整策略重新执行。架构图 Agent 就是 Agent 在“信息可视化”领域的具体应用。它把自然语言描述转化为结构化的图表描述再渲染为图片。2.2 架构图 Agent 与传统模板填充的区别有人可能会问用一段预设好的提示词让大模型输出 Mermaid不也能生成架构图吗为什么需要 Agent区别在于“稳定性和自省能力”。简单提示词方案通常存在几个问题大模型输出的 Mermaid 代码经常有语法错误节点 ID 包含非法字符时直接渲染失败。用户表达能力不同提示词稍一复杂模型就会漏掉模块关系。没有校验也没有重试机制生成的图表质量完全不可控。而架构图 Agent 的核心改进在于让模型先输出结构化数据JSON而不是直接输出 Mermaid 语法。对 JSON 做二次校验确保节点和边的字段完整。渲染前检查 Mermaid 语法的关键规则出错时携带错误信息让模型重新生成。这种“先生成数据再转换渲染再校验修正”的流程比单纯依赖提示词要稳定得多。2.3 一个完整的工作流程我们可以把架构图 Agent 拆成四个模块模块职责关键技术点输入理解模块接收自然语言描述大模型 Prompt信息抽取模块输出结构化节点和关系强制 JSON 输出图生成模块把 JSON 转为 Mermaid语法映射规则渲染与校验模块渲染为图片并检查错误mermaid-cli、前端渲染用户输入“一个电商系统包含前端、网关、订单服务、商品服务、用户服务和数据库”Agent 会先抽取六个组件的类型和依赖关系再转换为 Mermaid 代码最后渲染成一张完整的系统架构图。3. 环境准备与项目结构在动手写代码之前先确认一下环境。本文的示例以 Python 3.10 为主同时需要准备一个可调用的 LLM API兼容 OpenAI 接口格式即可不需要限定具体服务商。3.1 环境要求环境项推荐配置说明操作系统Windows / macOS / Linux本文命令以 Linux/macOS 风格为例Python3.10 及以上需要支持新版类型语法包管理工具pip用于安装依赖LLM APIOpenAI 兼容接口需要配置 API Key 和 Base URLNode.js18可选仅当需要本地渲染 PNG/SVG 时使用如果你所在环境无法访问某些服务请自行确认网络可用性这里只讨论代码实现本身。3.2 依赖清单依赖库不需要太多核心只需要几个openai1.0.0 fastapi0.104.0 uvicorn0.24.0 python-dotenv1.0.0 pydantic2.0.03.3 项目目录我们实现一个叫arch-agent的项目目录结构如下arch-agent/ ├── requirements.txt # 依赖清单 ├── .env.example # 环境变量模板 ├── config.py # 读取环境变量配置 ├── llm_client.py # 调用 LLM API 获取结构化 JSON ├── generator.py # 将 JSON 转为 Mermaid 代码 ├── main.py # FastAPI 服务入口 ├── index.html # 前端页面 └── README.md # 项目说明文档后面的代码都会按这个结构展开方便你直接参照创建文件。4. 核心原理拆解这一节先把架构图 Agent 的几个关键实现点讲清楚方便后续实战部分快速理解。4.1 让大模型输出结构化 JSON大模型默认输出是自然语言。为了让它可以被程序稳定处理我们需要约束输出格式。OpenAI 兼容接口中常用的做法是使用response_format参数from openai import OpenAI client OpenAI( api_key你的API_KEY, base_url你的BASE_URL, ) response client.chat.completions.create( modelgpt-4o-mini, response_format{type: json_object}, messages[ {role: system, content: 你是一个架构师只输出 JSON。}, {role: user, content: 请抽取系统组件和依赖关系。}, ], )需要注意的是response_format并不是所有兼容服务都支持。如果你的服务商不支持可以去掉这个参数然后在提示词里明确要求“只输出 JSON不要输出任何解释”再用字符串解析兜底。4.2 设计节点和边的 JSON Schema为了让生成结果可预测我们需要定义一个简单的 JSON 结构。它由两个字段组成nodes架构图中的所有组件节点。edges节点之间的关系。每个节点包含id、label和type三个字段type用来描述节点类型比如网关、服务、数据库、缓存。每个边包含from、to和label三个字段分别表示起点、终点和关系描述。示例{ nodes: [ {id: gateway, label: API网关, type: gateway}, {id: order, label: 订单服务, type: service}, {id: db, label: 订单数据库, type: db} ], edges: [ {from: gateway, to: order, label: 调用}, {from: order, to: db, label: 读写} ] }实际开发中你还可以扩展更多字段比如节点样式、子图分组、颜色标识等。但前期保持简单更容易把流程跑通。4.3 从 JSON 到 Mermaid 的映射规则Mermaid 是当前 GitHub 原生支持的图表语法也是这类项目最常使用的输出格式。一个简单架构图的 Mermaid 代码如下graph LR gateway[API网关] order[订单服务] db[(订单数据库)] gateway --|调用| order order --|读写| db从 JSON 到 Mermaid 的转换规则如下每个node对应一行节点定义。db类型的节点使用[(名称)]语法表示圆柱体。cache类型的节点使用{名称}语法表示。每个edge对应一行箭头连接。4.4 图片渲染的几种方式拿到 Mermaid 代码后有三种常见渲染方式方式优点缺点前端 mermaid.js用户体验好实时预览需要浏览器环境mermaid-cli 命令行渲染可生成 PNG/SVG 文件需要安装 Node.js 环境mermaid.ink 在线 API请求简单适合快速测试依赖外部在线服务在本文的实战项目中我们会优先使用前端 mermaid.js 渲染这样在浏览器里看效果最直观也可以一键下载截图。5. 完整实战实现一个可用的架构图 Agent5.1 创建项目并安装依赖打开终端创建项目目录并初始化虚拟环境mkdir arch-agent cd arch-agent python -m venv venv source venv/bin/activate pip install openai fastapi uvicorn python-dotenv pydantic如果使用的是 Windows激活命令是venv\Scripts\activate5.2 准备环境变量文件在项目目录下创建.env.exampleLLM_API_KEYsk-你的密钥 LLM_BASE_URLhttps://api.openai.com/v1 LLM_MODELgpt-4o-mini创建.env文件并填入你自己的配置。需要特别提醒的是.env文件包含敏感信息不要把真实密钥提交到 Git 仓库。创建一个config.py用于统一读取配置import os from dotenv import load_dotenv load_dotenv() LLM_API_KEY os.getenv(LLM_API_KEY, ) LLM_BASE_URL os.getenv(LLM_BASE_URL, https://api.openai.com/v1) LLM_MODEL os.getenv(LLM_MODEL, gpt-4o-mini)5.3 编写 LLM 客户端创建llm_client.py封装大模型调用逻辑import json from openai import OpenAI import config class LLMClient: def __init__(self) - None: self.client OpenAI( api_keyconfig.LLM_API_KEY, base_urlconfig.LLM_BASE_URL, ) self.model config.LLM_MODEL def extract_architecture(self, description: str) - dict: system_prompt 你是一名系统架构设计师。用户会提供一段关于系统的描述。 你需要从中提取架构组件和组件之间的依赖关系并输出 JSON 格式的结果。 JSON 结构必须严格遵循以下格式 { nodes: [ {id: string, label: string, type: gateway|service|db|cache|client} ], edges: [ {from: string, to: string, label: string} ] } 节点类型说明 - gateway网关或入口 - service服务模块 - db数据库 - cache缓存 - client客户端 请只输出 JSON不要输出任何解释或多余内容。 messages [ {role: system, content: system_prompt}, {role: user, content: description}, ] try: response self.client.chat.completions.create( modelself.model, messagesmessages, temperature0.2, response_format{type: json_object}, ) content response.choices[0].message.content return json.loads(content) except Exception as e: raise RuntimeError(fLLM 调用失败: {e})这里的关键点是temperature0.2较低的采样温度可以让模型输出更稳定减少结构遗漏。5.4 编写 JSON 转 Mermaid 的生成器创建generator.pydef dict_to_mermaid(arch: dict) - str: 将架构 JSON 转换为 Mermaid 代码 lines [graph LR] for node in arch.get(nodes, []): node_id node[id] label node[label] node_type node.get(type, service) if node_type db: lines.append(f {node_id}[({label})]) elif node_type cache: lines.append(f {node_id}{{{label}}}) elif node_type gateway: lines.append(f {node_id}{{{label}}}) elif node_type client: lines.append(f {node_id}[{label}]) else: lines.append(f {node_id}[{label}]) for edge in arch.get(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)这个函数把模型输出的结构化 JSON 映射为 Mermaid 节点和边。实际使用中需要注意节点id中不要包含空格、括号等特殊字符否则 Mermaid 渲染很可能报错。可以在解析层增加清洗逻辑import re def clean_node_id(node_id: str) - str: 清洗节点 ID只保留字母、数字和下划线 return re.sub(r[^a-zA-Z0-9_], _, node_id)5.5 编写 FastAPI 服务创建main.pyfrom fastapi import FastAPI from fastapi.responses import HTMLResponse from pydantic import BaseModel from llm_client import LLMClient from generator import dict_to_mermaid app FastAPI() llm_client LLMClient() class GenerateRequest(BaseModel): description: str app.post(/api/generate) def generate_architecture(req: GenerateRequest): 接收自然语言描述返回 Mermaid 代码和结构化数据 arch llm_client.extract_architecture(req.description) mermaid_code dict_to_mermaid(arch) return { mermaid: mermaid_code, arch: arch, } app.get(/, response_classHTMLResponse) def index(): with open(index.html, encodingutf-8) as f: return HTMLResponse(f.read())这个接口做了两件事调用大模型抽取架构信息然后把 JSON 转成 Mermaid 代码。前端拿到 Mermaid 代码后通过 mermaid.js 实时渲染成图。5.6 编写前端页面创建index.html!DOCTYPE html html langzh-CN head meta charsetUTF-8 meta nameviewport contentwidthdevice-width, initial-scale1.0 title架构图 Agent/title script srchttps://cdn.jsdelivr.net/npm/mermaid10/dist/mermaid.min.js/script style body { font-family: -apple-system, PingFang SC, sans-serif; max-width: 960px; margin: 40px auto; padding: 0 20px; background: #f6f8fa; color: #24292f; } textarea { width: 100%; height: 80px; padding: 12px; font-size: 14px; border: 1px solid #d0d7de; border-radius: 6px; box-sizing: border-box; } button { margin-top: 12px; padding: 10px 24px; background: #2da44e; color: #fff; border: none; border-radius: 6px; font-size: 14px; cursor: pointer; } button:disabled { background: #94d3a2; cursor: not-allowed; } #graph { background: #fff; border: 1px solid #d0d7de; border-radius: 6px; padding: 24px; margin-top: 20px; text-align: center; } /style /head body h1架构图生成 Agent/h1 p输入一段系统描述自动生成架构图。/p textarea iddesc placeholder例如一个电商系统包含前端、网关、订单服务、商品服务、用户服务订单服务依赖订单数据库商品服务依赖商品数据库用户服务依赖用户数据库。/textarea br button idrun生成架构图/button div idgraph div classmermaid graph LR placeholder[等待生成] /div /div script document.getElementById(run).addEventListener(click, async function () { const desc document.getElementById(desc).value; if (!desc) { alert(请输入系统描述); return; } const btn document.getElementById(run); btn.disabled true; btn.textContent 生成中...; try { const resp await fetch(/api/generate, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify({ description: desc }) }); const data await resp.json(); renderMermaid(data.mermaid); } catch (err) { alert(生成失败 err.message); } finally { btn.disabled false; btn.textContent 生成架构图; } }); function renderMermaid(code) { const container document.getElementById(graph); container.innerHTML div classmermaid/div; const el container.querySelector(.mermaid); el.textContent code; mermaid.run({ nodes: [el] }); } /script /body /html前端页面使用了 Mermaid 的浏览器运行时不需要额外安装 Node.js 环境打开页面就能渲染架构图。5.7 运行与验证启动 FastAPI 服务uvicorn main:app --reload --host 0.0.0.0 --port 8000浏览器访问http://127.0.0.1:8000在输入框中填写系统描述点击“生成架构图”。也可以先用 curl 验证接口curl -X POST http://127.0.0.1:8000/api/generate \ -H Content-Type: application/json \ -d {description: 一个订单系统包含前端、网关、订单服务、用户服务订单服务依赖订单数据库用户服务调用订单服务}预期返回结果类似{ mermaid: graph LR\n gateway{{API网关}}\n order[订单服务]\n user[用户服务]\n db[(\订单数据库\)]\n gateway --|转发| order\n order --|读写| db\n user --|调用| order, arch: { nodes: [], edges: [] } }arch中的具体内容会因模型输出而略有不同但mermaid字段应该可以直接被 Mermaid 渲染。5.8 进阶加上校验重试的 Agent 循环一个真正有“Agent 味”的版本应该包含错误反馈和自我修正。当生成的 Mermaid 无法渲染时可以把渲染错误信息回传给模型让它重新生成。在llm_client.py中增加一个带重试的方法def extract_with_retry(self, description: str, error_msg: str ) - dict: user_content description if error_msg: user_content f{description}\n\n上次生成的架构 JSON 存在问题{error_msg}\n请修正后重新输出 JSON。 # 继续调用 extract_architecture然后在主程序中捕获渲染异常进入重试循环。这个设计虽然简单但它体现了 Agent 的核心思想观察结果、发现问题、携带上下文重新执行。6. GitHub 开源项目上榜的实践经验6.1 GitHub Trending 究竟在推荐什么参加过大热项目的开发者都知道GitHub Trending 的排序并不只看总 Star 数而是看 Star 的“增长速度”。一个新建仓库如果短时间内获得大量 Star会比一个老牌项目更容易上榜。从我的观察来看能被 Trending 推荐的项目通常满足几个条件主题踩中当前热点。AI Agent、大模型应用、自动化工具这些关键词本身就自带流量。项目有清晰可见的演示效果。架构图 Agent 用一张动态生成的架构图截图就能让用户秒懂项目价值。README 质量高安装和使用步骤足够简单。作者在项目发布的第一周保持更新频率及时修复用户反馈的 issue。6.2 让 README 成为项目最好的“门面”很多开发者低估了 README 的重要性。GitHub 用户决定是否点 Star往往只花几十秒浏览 README。一个专业的 README 应该包含以下结构项目名称和一句精准的简介。一张核心功能演示截图或 GIF这一步最重要。功能特性列表让用户快速了解它能做什么。安装和快速开始用尽量少的命令让用户跑起来。真实的使用示例包含输入和输出。常见问题 FAQ减少不必要的 issue。License、贡献指南、联系方式等补充信息。在写 README 时还有一个容易被忽略的细节项目描述Description要包含关键词。比如“架构图 Agent”“自然语言生成架构图”“Mermaid 自动生成”这类描述能提高项目在 GitHub 搜索中被发现的概率。6.3 从 Trending 到长期维护登上 Trending 只是第一步。很多项目火了一周后因为作者不维护Star 数就停滞不前。长期维护比短期上榜更重要。建议保持以下节奏每周至少发布一次新版本哪怕是修复小 bug。及时回复 issue 和 PR让贡献者感受到项目是“活的”。定期整理 Release Notes记录每个版本的变化。把用户提得最多的问题沉淀到 FAQ 文档中。围绕项目写一些技术解析文章吸引更多开发者进入社区。开源项目的本质不是“代码仓库”而是一个“开发者社区”。代码只是载体真正让项目持续增长的是作者与使用者之间持续互动的过程。7. 常见问题与排查思路问题现象常见原因解决思路LLM 返回的内容无法解析为 JSON服务商不支持response_format参数或模型输出包含额外文字去掉response_format在提示词中强制要求只输出 JSON解析前进行字符串截取Mermaid 渲染报错节点 ID 包含非法字符或 JSON 中缺少关键字段增加节点 ID 清洗函数先用json.loads校验结构再进行转换页面能打开但生成按钮无反应FastAPI 接口跨域问题或前端页面调用地址错误检查浏览器 Console 报错确认请求地址是否为http://127.0.0.1:8000/api/generate生成速度慢模型参数量大或网络请求延迟较高换用更轻量的模型设置合理的超时时间减少重复轮次架构图节点过多无法阅读用户描述太复杂模型一次抽取的节点过多增加节点数量限制超出后提示用户拆分描述GitHub 仓库克隆速度慢且不稳定网络环境差异导致的仓库拉取缓慢使用git clone配合代理配置或者将仓库先导入国内平台后再本地拉取部署到服务器后无法访问云服务安全组未开放端口检查服务监听地址是否为0.0.0.0并确认安全组放行对应端口遇到报错时不要只盯着错误信息的最后一行。先确认数据格式是否正确再确认渲染环节是否出错最后检查前后端交互。逐层定位是排查问题最高效的方式。8. 最佳实践与工程化建议8.1 Prompt 和结构化输出把 System Prompt 单独抽成一个配置文件或模板文件方便反复调优。不要在 Python 代码里写过长字符串。在提示词中明确“只输出 JSON”并给出一个示例 JSON 结构模型输出质量会有明显提升。如果模型偶尔输出脏数据可以在解析层做“修复”比如缺少label时用id兜底type不合法时默认按service处理。8.2 安全与密钥管理大模型 API Key 是敏感信息绝不能写死在代码里也不能提交到 Git 仓库。推荐使用.env文件加python-dotenv管理。如果项目要公开一定要在.gitignore中加入.env。生产中还需要注意给 API 调用设置超时时间避免长时间阻塞。对用户输入长度做限制防止恶意超长文本消耗 token。日志中不要打印完整的请求和响应内容尤其是密钥和用户隐私数据。如果服务面向公网建议增加登录鉴权或简单的访问控制。8.3 成本与性能优化架构图生成属于轻量级任务对延迟不是特别敏感但成本控制仍然值得注意。建议从这几个方面入手使用性价比更高的模型比如gpt-4o-mini这类轻量模型而不是每个请求都调用最大参数模型。对描述内容做长度截断超长文本先让模型做摘要。引入缓存相同或高度相似的描述直接返回缓存结果减少重复调用。前端渲染交给 Mermaid.js 完成后端只返回结构化数据减少服务端渲染压力。8.4 可扩展方向架构图 Agent 只是 Agent 应用的一个方向。完成这个项目后你还可以继续扩展支持输出 PlantUML、D2、Graphviz 等多种格式。支持按微服务架构图模板进行领域划分自动生成子图分组。加入“对话式修正”用户可以说“订单服务和用户服务之间不用直连”Agent 根据反馈调整架构。与代码仓库打通读取 Dockerfile、服务编排文件逆向生成部署架构图。这些方向的核心逻辑和本文实现的项目是一致的利用大模型理解需求用结构化数据保证输出稳定再通过渲染层把数据变成用户能直接使用的结果。9. 总结与后续学习路线这篇文章从 GitHub 上架构图 Agent 项目火热的现状出发梳理了 Agent 的基本概念和工作循环然后完整实现了“自然语言描述 → 结构化 JSON → Mermaid 代码 → 前端渲染”的架构图生成工具。核心代码包含 LLM 客户端封装、JSON 转 Mermaid 映射、FastAPI 服务接口和浏览器渲染页面整体结构比较简单但已经具备一个真实 Agent 应用的主要模块。如果你是第一次接触 Agent 开发建议先用本文的代码跑通整个链路再逐步加入校验重试、多轮修正、更多图表格式支持。最终你会发现Agent 应用没有想象中那么神秘关键是把“模型输出”和“程序逻辑”之间的接口设计好。如果你希望项目也能进入 GitHub Trending不妨先把自己的工具打磨到“自己每天都在用”的程度再用规范的 README 展示出去。持续维护一个开源项目远比一次上榜更有价值。如果本文对你有帮助可以收藏备用。下次需要画微服务架构图时试试让 Agent 帮你生成你会发现画图这件事其实可以很简单。