ARTICLE · 1325549

一个基于 Go 语言的 AI 自动生成架构图工具

发布时间：2026-11-07 12:07:44 最近访问：2026-11-07 12:07:45

大家好，我是码农先森。

项目地址：https://github.com/peakxy/drawio-agent-go

📦 15 Parts + Conclusion

👉 滑动

PART 01

项目简介

PART 02

项目展示

PART 03

项目讲解文档

PART 04

核心能力

PART 05

工作原理

PART 06

快速开始

QUICK START · 快速上手

PART 07

使用指南

PART 08

技术栈

TECH STACK · 技术选型

PART 09

架构设计

PART 10

配置说明

CONFIG · 环境变量

PART 11

HTTP API

PART 12

常见问题

PART 13

开发与验证

PART 14

参与贡献

PART 15

联系作者

PART ///

写在最后

SUMMARY · 个人观点

PART

项目简介

Drawio-Agent-Go 是一个基于 Agent 应用开发的 Go 脚手架搭建的 Draw.io 智能体，可通过多轮对话来绘制理想中的架构图。

用户只需要用自然语言描述想法，系统就会通过“需求分析、图形生成、结果检查”三个 Agent 协作，把需求转换为可编辑的 Draw.io XML，并在网页画布中直接渲染。开启“携带画布上下文”后，还可以继续通过对话调整节点、补充链路或优化布局。

PART

项目展示

前端工作台由三部分组成：左侧管理绘图记录，中间嵌入 Draw.io 画布，右侧通过 AI 对话生成或修改图表。

绘图记录	Draw.io 画布	AI 对话区
创建、切换、重命名和删除会话	加载 Agent 生成的 XML，并支持手动编辑与自动保存	选择 Agent、输入绘图需求、携带当前画布上下文

可以从一段简单的自然语言开始：

...text

请绘制一个微服务电商系统架构图，包含 API Gateway、用户服务、

商品服务、订单服务、Redis、MySQL 和 Kafka，并标注主要调用关系。

生成初稿后，开启“携带画布上下文”，继续输入：

...text

在现有架构图中增加库存服务和支付服务，将异步事件统一接入 Kafka，

并调整布局，避免节点和连线重叠。

PART

项目讲解文档

•地址：项目文档

•内容：简历写法、项目亮点与难点解析等

PART

核心能力

能力	说明
自然语言绘图	将架构描述、业务流程或调用关系转换为合法的 Draw.io `mxfile` XML
三 Agent 协作	`agent_analyst` 分析需求，`agent_drawer` 生成图形，`agent_reviewer` 检查并优化结果
多轮迭代修改	前端可把当前画布 XML 随新指令一起提交，让 Agent 在已有图表基础上继续修改
Draw.io 深度集成	基于 `react-drawio` 嵌入真实画布，支持手动编辑、自动保存和 SVG 导出
多会话绘图记录	浏览器本地保存聊天消息和图表 XML，支持创建、切换、重命名和删除绘图记录
配置驱动装配	通过 YAML 声明模型、Agent、Workflow、Runner、MCP 工具和 Skill 资源
OpenAI-compatible	模型层直接调用兼容 Chat Completions 的服务，方便对接不同模型提供方
MCP 工具扩展	支持配置 SSE MCP 工具，在需求分析阶段按需检索和补充绘图信息
Go 工程化分层	使用端口与适配器组织领域、应用、基础设施和 HTTP 入站层，便于替换外部依赖

> [!NOTE]

> 当前“多轮修改”主要由前端保存绘图记录，并在用户开启“携带画布上下文”后提交当前 XML 实现；它不是服务端长期记忆系统。

PART

工作原理

...mermaid

flowchart LR

User["用户描述绘图需求"] --> Web["Next.js 对话工作台"]

Web --> API["Go HTTP API"]

API --> Analyst["agent_analyst 理解需求并补全关系"]

Analyst --> Drawer["agent_drawer 生成 Draw.io XML"]

Drawer --> Reviewer["agent_reviewer 校验语法并优化布局"]

Reviewer --> XML["最终 mxfile XML"]

XML --> Canvas["react-drawio 画布"]

Canvas --> Edit["人工编辑 / SVG 导出"]

Canvas -. "携带当前画布上下文" .-> Web

三 Agent 分工

Agent	输入	职责	输出
`agent_analyst`	用户最新指令	判断图表类型，整理节点、关系、调用顺序和布局要求，必要时调用 MCP 工具	`analysis_result`
`agent_drawer`	`analysis_result`	生成包含 `mxfile`、`diagram`、`mxGraphModel` 和 `mxCell` 的 Draw.io XML	`draft_diagram`
`agent_reviewer`	`draft_diagram`	检查标签、属性、节点引用和布局，修复错误并输出最终 XML	`final_result`

默认 Runner 使用串行工作流 sequential_draw_process：

...text

agent_analyst -> agent_drawer -> agent_reviewer

仓库同时保留了 loop 和 parallel Workflow 的配置示例，便于继续实验循环优化和多方案生成。

PART

快速开始

QUICK START · 快速上手

环境要求

•Go 1.25.6+

•Node.js 20+ 和 npm

•一个 OpenAI-compatible Chat Completions 服务

•可访问的 MCP SSE 服务；如果不使用 MCP，需要从启用的 Agent 配置中移除对应 tool-mcp-list

•Docker，可选，仅用于本地 MySQL/Redis 参考环境

1. 克隆项目

...bash

git clone https://github.com/peakxy/drawio-agent-go.git

cd drawio-agent-go

2. 安装后端依赖

...bash

go mod download

go build ./...

3. 准备环境变量

...bash

cp .env.example .env

至少需要替换以下配置：

...dotenv

OPENAI_BASE_URL=https://api.example.com/

OPENAI_API_KEY=replace-with-your-key

BAIDU_SEARCH_MCP_BASE_URI=https://example.com/mcp/

BAIDU_SEARCH_MCP_SSE_ENDPOINT=sse?api_key=replace-with-your-key

说明：

•OPENAI_BASE_URL 可以指向 OpenAI 官方服务或兼容 Chat Completions 的模型服务。

•默认启用的 Agent YAML 声明了百度搜索 SSE MCP，因此需要提供可用的 MCP 地址。

•如果暂时不需要 MCP，请从实际启用的 configs/agent/*.yaml 中移除 tool-mcp-list，不要保留空的 base-uri。

•.env 中的变量会在加载 Agent YAML 时展开，支持 ${VAR} 和 ${VAR:-default}。

4. 启动后端

...bash

go run ./cmd/server

也可以显式指定环境变量文件和应用配置：

...bash

go run ./cmd/server -env .env -config configs/application.yaml

默认监听 :8091，可以通过健康检查确认服务状态：

...bash

curl http://localhost:8091/healthz

...json

{"status":"ok"}

5. 启动前端

打开另一个终端：

...bash

cd frontend

npm ci

npm run dev

访问 http://localhost:3000，演示账号和密码均为：

...text

admin / admin

登录后选择 AI交互式绘图智能体，输入绘图需求即可开始。

> [!IMPORTANT]

> admin / admin 只是前端演示登录，数据保存在浏览器 Cookie 中，不包含生产环境所需的服务端鉴权能力。

PART

使用指南

创建一张新图

点击左侧新增按钮创建绘图记录。

在右侧选择“AI交互式绘图智能体”。

描述图表类型、关键节点、节点关系和期望布局。

等待三 Agent 工作流完成，最终 XML 会自动加载到中间画布。

在 Draw.io 中继续手动编辑，或点击 Export 导出 SVG。

基于当前画布继续修改

打开右侧输入框上方的“携带画布上下文”。

输入新的修改指令，例如“增加 Redis 缓存层，并将所有缓存访问改为虚线”。

前端会导出当前 Draw.io XML，并与新指令一起发送给 Agent。

Agent 返回新的 XML 后，前端更新当前画布和本地绘图记录。

管理绘图记录

•单击左侧记录切换会话和画布。

•双击记录名称进行重命名。

•点击删除按钮移除记录。

•聊天消息、后端会话 ID 和 Draw.io XML 会保存在浏览器 localStorage。

PART

技术栈

TECH STACK · 技术选型

领域	选型
后端语言	Go 1.25.6+
HTTP 框架	Gin 1.12
Agent 配置与装配	YAML、Google ADK Go 插件接口、自定义 Runner/Agent adapter
模型抽象	Eino 相关依赖 + 本地 OpenAI-compatible adapter
模型协议	OpenAI-compatible Chat Completions
工具协议	MCP SSE；同时保留 local/stdio 配置结构
持久化适配器	GORM + MySQL，可选，默认启动链路未启用
缓存适配器	go-redis，可选，默认启动链路未启用
日志	zap + Gin logger
前端	Next.js 16、React 19、Tailwind CSS 4、react-drawio 1.0.7

PART

架构设计

整体架构

...mermaid

flowchart TB

Browser["Browser"] --> Frontend["frontend Next.js + react-drawio"]

Frontend --> Handler["internal/trigger/http Gin handlers"]

Handler --> Chat["domain/agent/service/chat"]

Chat --> Registry["AgentRegistry in-memory"]

Chat --> Session["SessionStore in-memory"]

Registry --> Runner["Runner adapter"]

Runner --> Workflow["Sequential Agent Workflow"]

Workflow --> Model["OpenAI-compatible ChatModel"]

Workflow --> Tools["MCP Tool Router"]

Model --> LLM["Chat Completions Service"]

Tools --> MCP["MCP SSE Server"]

AppConfig["configs/application.yaml"] --> Bootstrap["internal/app/bootstrap"]

AgentConfig["configs/agent/*.yaml"] --> Bootstrap

Bootstrap --> Armory["domain/agent/service/armory"]

Armory --> Registry

后端按端口与适配器组织：

•internal/domain：定义 Agent 配置模型、领域端口、Armory 装配和聊天服务。

•internal/app：加载应用配置并连接领域服务与基础设施。

•internal/infrastructure：实现模型、MCP、ADK、日志、MySQL 和 Redis adapter。

•internal/trigger/http：处理 Gin 路由、HTTP 参数和响应。

•pkg/types：提供应用错误码与统一错误类型。

项目结构

...text

drawio-agent-go

├── cmd/server/main.go # 后端入口

├── configs

│ ├── application.yaml # 服务、LLM 超时和 Agent 配置路径

│ └── agent

│ ├── agent-draw-io.yaml # Draw.io 三 Agent 工作流

│ ├── only-one-agent.yaml # 单 Agent 示例

│ └── skills/ # SKILL.md 资源示例

├── deployments # MySQL/Redis 参考环境

├── frontend # Next.js + react-drawio 前端

├── internal

│ ├── api # HTTP DTO 与统一响应

│ ├── app # 配置加载与应用 Bootstrap

│ ├── domain # Agent 领域模型、端口和服务

│ ├── infrastructure # 模型、MCP、ADK、DB、缓存和日志 adapter

│ └── trigger/http # Gin 路由与 Handler

├── pkg/types # 错误码与 AppError

├── .env.example

├── go.mod

└── README.md

> 仓库展示名称已经是 Drawio-Agent-Go；当前 Go module 和部分运行时配置仍保留 ai-agent-scaffold-go，因此代码导入路径不应直接按展示名称替换。

PART

配置说明

CONFIG · 环境变量

应用配置

configs/application.yaml 控制服务地址、LLM 超时和需要装配的 Agent 文件：

...yaml

app:

env: local

server:

addr: ":8091"

llm:

request-timeout: 5m

agent:

config-paths:

- configs/agent/only-one-agent.yaml

- configs/agent/agent-draw-io.yaml

默认配置会同时注册单 Agent 示例和 Draw.io Agent。前端首次进入时不保证自动选中绘图 Agent，请手动选择 AI交互式绘图智能体。

MySQL 和 Redis adapter 已经存在，但默认 Bootstrap 使用内存态 AgentRegistry 和 SessionStore，启动本项目不强制依赖 MySQL 或 Redis。

Draw.io Agent 配置

核心配置位于 configs/agent/agent-draw-io.yaml：

...yaml

ai:

agent:

config:

tables:

drawIoAgent:

app-name: drawIoAgent

agent:

agent-id: "300000"

agent-name: "AI交互式绘图智能体"

agent-desc: "人 + AI + Draw.io，交互式对话完成 draw.io 绘图。"

module:

ai-api:

base-url: ${OPENAI_BASE_URL}

api-key: ${OPENAI_API_KEY}

completions-path: v1/chat/completions

chat-model:

model: "gpt-5.5"

tool-mcp-list:

- sse:

base-uri: ${BAIDU_SEARCH_MCP_BASE_URI}

sse-endpoint: ${BAIDU_SEARCH_MCP_SSE_ENDPOINT}

agents:

- name: agent_analyst

output-key: analysis_result

- name: agent_drawer

output-key: draft_diagram

- name: agent_reviewer

output-key: final_result

agent-workflows:

- type: sequential

sub-agents:

- agent_analyst

- agent_drawer

- agent_reviewer

runner:

agent-name: sequential_draw_process

完整的 Agent 指令、Workflow 示例和插件配置请直接查看 configs/agent/agent-draw-io.yaml。

PART

HTTP API

/api/v1 下的成功响应统一使用以下结构：

...json

{

"code": "0000",

"info": "success",

"data": {}

}

方法	路径	用途
`GET`	`/healthz`	服务健康检查
`GET`	`/api/v1/query_ai_agent_config_list`	查询已注册的 Agent
`POST / GET`	`/api/v1/create_session`	为 `userId + agentId` 创建或复用会话
`POST`	`/api/v1/chat`	同步执行 Agent
`POST`	`/api/v1/chat_stream`	以 SSE 形式返回 Runner 输出