企业官网建设流程全解析

这几天 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”，而不只是一个套了提示词的脚本。

再看它和传统方式的对比：

表格里的最后一列，就是架构图 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_URL="https://api.example.com/v1"

这里要特别提醒：不要把密钥写进代码仓库。示例代码里虽然会出现配置字样，但真实项目应该用环境变量、配置中心或密钥管理服务来保存。

5. 动手实现一个最小架构图 Agent

5.1 设计思路

整个 Agent 的核心就三步：

1. 系统提示词约束模型，把用户的自然语言架构描述转换为固定结构的 JSON。
2. 校验 JSON 中的节点和边是否合法。
3. 将 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_key=os.getenv("LLM_API_KEY"), base_url=os.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( model=os.getenv("LLM_MODEL", "gpt-4o-mini"), messages=[ {"role": "system", "content": SYSTEM_PROMPT}, {"role": "user", "content": description}, ], temperature=0.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_ok=True) with open(path, "w", encoding="utf-8") as f: json.dump(data, f, ensure_ascii=False, indent=2) if __name__ == "__main__": user_input = "一个电商系统，用户通过浏览器访问 Nginx，Nginx 转发到订单服务和商品服务，两个服务都读写同一个 MySQL，订单服务创建订单后向消息队列发送消息，消费者服务处理消息并更新库存。" result = generate_architecture(user_input) save_json(result) print(json.dumps(result, ensure_ascii=False, indent=2))

这段代码里的几个细节值得注意：

第一，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_ok=True) mmd_path = os.path.join(output_dir, f"{filename}.mmd") with open(mmd_path, "w", encoding="utf-8") as f: f.write(mmd_text) return mmd_path if __name__ == "__main__": with open("output/demo.json", "r", encoding="utf-8") as f: data = json.load(f) mmd = json_to_mermaid(data) path = render_mermaid(mmd) print(f"Mermaid 源码已保存到: {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(name=data["title"], format="png") for node in data["nodes"]: dot.node(node["id"], node["label"]) for edge in data["edges"]: dot.edge(edge["from"], edge["to"], label=edge.get("label", "")) dot.render(filename=f"output/{filename}", view=False)

两条渲染路径都可以，选你环境里装起来更顺手的那条。核心是：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. 常见问题与排查思路

排错的第一步永远是打印原始返回内容。不要让程序静默失败，建议在调用模型后先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 是很好的“思考放大器”，但它不能替代你对系统的理解。生成出来的图，永远要经过你自己的判断，再进入团队评审。把它当成一个把思想快速变成图纸的引擎，而不是替你思考的顾问，这才是正确的使用姿势。