企业官网建设流程全解析

最近一直在关注 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 什么是 Agent

Agent（智能体）这几年是 AI 开发领域的高频词。简单说，Agent 是一个能够根据目标自主决策并执行任务的程序系统。与普通程序固定流程不同，Agent 的行为由大模型根据当前输入和上下文动态生成。

一个典型的 Agent 工作循环包括：

• 理解目标：把用户输入转化为可执行的任务。
• 拆解步骤：规划完成目标需要哪些步骤。
• 调用工具：调用外部 API、代码解释器、搜索引擎等工具。
• 观察结果：检查工具返回的结果是否符合预期。
• 修正行动：如果结果异常，调整策略重新执行。

架构图 Agent 就是 Agent 在“信息可视化”领域的具体应用。它把自然语言描述转化为结构化的图表描述，再渲染为图片。

2.2 架构图 Agent 与传统模板填充的区别

有人可能会问：用一段预设好的提示词让大模型输出 Mermaid，不也能生成架构图吗？为什么需要 Agent？

区别在于“稳定性和自省能力”。

简单提示词方案通常存在几个问题：

• 大模型输出的 Mermaid 代码经常有语法错误，节点 ID 包含非法字符时直接渲染失败。
• 用户表达能力不同，提示词稍一复杂，模型就会漏掉模块关系。
• 没有校验，也没有重试机制，生成的图表质量完全不可控。

而架构图 Agent 的核心改进在于：

• 让模型先输出结构化数据（JSON），而不是直接输出 Mermaid 语法。
• 对 JSON 做二次校验，确保节点和边的字段完整。
• 渲染前检查 Mermaid 语法的关键规则，出错时携带错误信息让模型重新生成。

这种“先生成数据，再转换渲染，再校验修正”的流程，比单纯依赖提示词要稳定得多。

2.3 一个完整的工作流程

我们可以把架构图 Agent 拆成四个模块：

用户输入“一个电商系统，包含前端、网关、订单服务、商品服务、用户服务和数据库”，Agent 会先抽取六个组件的类型和依赖关系，再转换为 Mermaid 代码，最后渲染成一张完整的系统架构图。

3. 环境准备与项目结构

在动手写代码之前，先确认一下环境。本文的示例以 Python 3.10+ 为主，同时需要准备一个可调用的 LLM API（兼容 OpenAI 接口格式即可，不需要限定具体服务商）。

3.1 环境要求

如果你所在环境无法访问某些服务，请自行确认网络可用性，这里只讨论代码实现本身。

3.2 依赖清单

依赖库不需要太多，核心只需要几个：

openai>=1.0.0 fastapi>=0.104.0 uvicorn>=0.24.0 python-dotenv>=1.0.0 pydantic>=2.0.0

3.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( model="gpt-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 渲染，这样在浏览器里看效果最直观，也可以一键下载截图。

5. 完整实战：实现一个可用的架构图 Agent

5.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\activate

5.2 准备环境变量文件

在项目目录下创建.env.example：

LLM_API_KEY=sk-你的密钥 LLM_BASE_URL=https://api.openai.com/v1 LLM_MODEL=gpt-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_key=config.LLM_API_KEY, base_url=config.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( model=self.model, messages=messages, temperature=0.2, response_format={"type": "json_object"}, ) content = response.choices[0].message.content return json.loads(content) except Exception as e: raise RuntimeError(f"LLM 调用失败: {e}")

这里的关键点是temperature=0.2，较低的采样温度可以让模型输出更稳定，减少结构遗漏。

5.4 编写 JSON 转 Mermaid 的生成器

创建generator.py：

def 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.py：

from 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_class=HTMLResponse) def index(): with open("index.html", encoding="utf-8") as f: return HTMLResponse(f.read())

这个接口做了两件事：调用大模型抽取架构信息，然后把 JSON 转成 Mermaid 代码。前端拿到 Mermaid 代码后，通过 mermaid.js 实时渲染成图。

5.6 编写前端页面

创建index.html：

<!DOCTYPE html> <html lang="zh-CN"> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>架构图 Agent</title> <script src="https://cdn.jsdelivr.net/npm/mermaid@10/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 id="desc" placeholder="例如：一个电商系统包含前端、网关、订单服务、商品服务、用户服务，订单服务依赖订单数据库，商品服务依赖商品数据库，用户服务依赖用户数据库。"></textarea> <br> <button id="run">生成架构图</button> <div id="graph"> <div class="mermaid"> 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 class="mermaid"></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. 常见问题与排查思路

遇到报错时，不要只盯着错误信息的最后一行。先确认数据格式是否正确，再确认渲染环节是否出错，最后检查前后端交互。逐层定位是排查问题最高效的方式。

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 帮你生成，你会发现画图这件事，其实可以很简单。