docs: 在README中新增项目讲解文档
This commit is contained in:
peakxy
561
README.md
561
README.md
@@ -2,41 +2,45 @@
|
||||
|
||||
[](https://go.dev/)
|
||||
[](https://gin-gonic.com/)
|
||||
[](https://google.github.io/adk-docs/)
|
||||
[](https://github.com/cloudwego/eino)
|
||||
[](https://github.com/google/adk-go)
|
||||
[](https://gorm.io/)
|
||||
[](https://redis.io/)
|
||||
[](https://nextjs.org/)
|
||||
[](https://redis.io/)
|
||||
[](https://nextjs.org/)
|
||||
|
||||
AI Agent Scaffold Go 是一个面向 Agent 应用开发的 Go 脚手架，围绕 Gin、Eino、Google ADK Go、GORM、MySQL、Redis 构建，重点提供清晰的 DDD 分层、配置驱动的 Agent 装配、多 Agent 工作流编排和 HTTP 运行时接口。仓库同时附带一个基于 Next.js 的 `frontend/` 子项目，作为对接后端 API 的示例前端，这个场景是通过drawio组件搭建的，旨在通过多轮对话来画出理想中的流程图。
|
||||
|
||||
这个项目适合作为 Agent 平台、智能助手后端、工作流 Agent 服务的起点。它把模型、工具、技能、Agent、Workflow、Runner 的装配逻辑收敛在领域层，通过端口隔离基础设施实现，让核心业务代码不直接依赖具体 SDK 或框架。
|
||||
|
||||
## 目录
|
||||
|
||||
- [核心特性](#核心特性)
|
||||
- [核心能力](#核心能力)
|
||||
- [技术栈](#技术栈)
|
||||
- [项目结构](#项目结构)
|
||||
- [架构设计](#架构设计)
|
||||
- [后端架构](#后端架构)
|
||||
- [启动流程](#启动流程)
|
||||
- [Armory 装配流程](#armory-装配流程)
|
||||
- [运行时对话流程](#运行时对话流程)
|
||||
- [快速开始](#快速开始)
|
||||
- [配置说明](#配置说明)
|
||||
- [HTTP API](#http-api)
|
||||
- [开发命令](#开发命令)
|
||||
- [当前实现状态](#当前实现状态)
|
||||
- [路线图](#路线图)
|
||||
- [Star 趋势](#star-趋势)
|
||||
- [许可证](#许可证)
|
||||
- [前端启动](#前端启动)
|
||||
- [开发与验证](#开发与验证)
|
||||
- [联系作者](#联系作者)
|
||||
|
||||
## 核心特性
|
||||
## 项目讲解文档
|
||||
|
||||
- **配置驱动 Agent**：通过 YAML 定义模型 API、ChatModel、工具、技能、单 Agent、Workflow 和 Runner。
|
||||
- **多 Agent 工作流**：支持 `loop`、`parallel`、`sequential` 三类工作流 Agent 组装。
|
||||
- **Armory 规则树装配**：使用 `Root -> AiApi -> ChatModel -> Agent -> AgentWorkflow -> Runner` 的显式节点链路构建运行时 Agent。
|
||||
- **DDD 六层结构**：将 API 契约、应用启动、领域模型、触发器、基础设施和通用类型分离。
|
||||
- **端口隔离基础设施**：领域层依赖本地 ports，不直接耦合 Gin、GORM、Redis、Eino、ADK Go 等实现细节。
|
||||
- **HTTP 运行时接口**：提供查询 Agent、创建会话（POST/GET）、同步对话、流式对话四类接口。
|
||||
- **本地开发资产**：包含示例配置、MySQL/Redis Docker Compose、环境变量模板和可一键启动的 Next.js 示例前端。
|
||||
- 地址：[项目文档](https://my.feishu.cn/wiki/FbISwBnZPiGx0vkxyHFc8a1enig?fromScene=spaceOverview)
|
||||
- 内容：简历写法、项目亮点与难点解析等
|
||||
|
||||
## 核心能力
|
||||
|
||||
- **配置驱动 Agent**：通过 `configs/agent/*.yaml` 声明模型 API、ChatModel、MCP 工具、skills、LLM Agent、workflow Agent 和 Runner。
|
||||
- **Armory 装配链**：按 `Root -> AiAPI -> ChatModel -> Agent -> AgentWorkflow -> Runner` 的顺序装配运行时对象。
|
||||
- **多 Agent 工作流**：支持 `loop`、`parallel`、`sequential` 三类 workflow Agent，串行工作流可通过 `output-key` 把上一步结果注入下一步指令。
|
||||
- **HTTP 运行时接口**：提供 Agent 列表、创建会话、同步聊天、SSE 流式聊天接口。
|
||||
- **OpenAI-compatible 模型调用**：基础设施层直接构造 Chat Completions 请求，支持普通响应和 `stream: true`。
|
||||
- **MCP SSE 工具调用**：装配阶段注册 SSE MCP 工具，运行时在模型触发 tool call 后执行 JSON-RPC `tools/call`，再把工具结果回灌给模型。
|
||||
- **Skill 资源扫描**：支持扫描 `SKILL.md`，把 skill 元数据转换为模型可见工具。
|
||||
- **分层边界清晰**：领域层依赖本地 `ports`，避免直接耦合 Gin、GORM、Redis、模型 provider 和 ADK 实现。
|
||||
|
||||
## 技术栈
|
||||
|
||||
@@ -44,194 +48,262 @@ AI Agent Scaffold Go 是一个面向 Agent 应用开发的 Go 脚手架，围绕
|
||||
| --- | --- |
|
||||
| 后端语言 | Go 1.25.6+ |
|
||||
| HTTP 框架 | Gin |
|
||||
| Agent / 模型封装 | Eino |
|
||||
| Agent 编排 | Google ADK Go |
|
||||
| 持久化 | GORM + MySQL |
|
||||
| 缓存 / 会话 | Redis |
|
||||
| 配置 | YAML + 环境变量 |
|
||||
| 日志 | zap |
|
||||
| 前端 | Next.js + React + TailwindCSS |
|
||||
| Agent 运行与插件 | Google ADK Go |
|
||||
| 模型/工具抽象依赖 | Eino 相关依赖已纳入模块；当前模型调用由本地 OpenAI-compatible adapter 完成 |
|
||||
| 配置 | YAML + dotenv + 环境变量占位符 |
|
||||
| 模型协议 | OpenAI-compatible Chat Completions |
|
||||
| 工具协议 | MCP SSE；stdio/local 配置结构已存在 |
|
||||
| 持久化适配器 | GORM + MySQL，当前默认启动路径未强制启用 |
|
||||
| 缓存适配器 | go-redis，当前默认启动路径未强制启用 |
|
||||
| 日志 | zap + Gin logger |
|
||||
| 前端 | Next.js 16 + React 19 + Tailwind CSS + react-drawio |
|
||||
|
||||
## 项目结构
|
||||
|
||||
```text
|
||||
ai-agent-scaffold-go
|
||||
├── cmd/server # 服务入口，当前负责启动日志初始化
|
||||
├── cmd/server
|
||||
│ └── main.go # 后端入口：加载 .env、读取配置、构建应用、启动 HTTP 服务
|
||||
├── configs
|
||||
│ ├── application.yaml # 应用、服务端口、MySQL、Redis、Agent 配置入口
|
||||
│ ├── application.yaml # 应用、端口、LLM 超时、Agent 配置路径、可选 DB/Redis 设置
|
||||
│ └── agent
|
||||
│ ├── only-one-agent.yaml # 单 Agent 示例配置（含 MCP 与 skills）
|
||||
│ ├── agent-draw-io.yaml # draw.io Agent 示例配置
|
||||
│ └── skills/ # 内置 skill 资源（battle-plan、pdf 等）
|
||||
│ ├── only-one-agent.yaml # 单 Agent 示例
|
||||
│ ├── agent-draw-io.yaml # draw.io 多 Agent 工作流示例
|
||||
│ └── skills/ # skill 资源，按 SKILL.md 扫描
|
||||
├── deployments
|
||||
│ └── docker-compose.yml # 本地 MySQL / Redis
|
||||
├── frontend # Next.js 示例前端，调用后端 /api/v1
|
||||
│ ├── docker-compose.yml # 本地 MySQL/Redis 参考服务
|
||||
│ ├── mysql/my.cnf
|
||||
│ └── redis/redis.conf
|
||||
├── frontend # Next.js draw.io 示例前端
|
||||
├── internal
|
||||
│ ├── api # DTO 与统一响应封装
|
||||
│ ├── app # 应用装配与配置加载边界
|
||||
│ ├── api
|
||||
│ │ ├── dto # HTTP 请求/响应 DTO
|
||||
│ │ └── response # code/info/data 统一响应封装
|
||||
│ ├── app
|
||||
│ │ ├── bootstrap # 应用装配：配置表加载、Armory、ChatService、Gin 路由
|
||||
│ │ └── config # application.yaml 与 Agent YAML 加载/校验
|
||||
│ ├── domain
|
||||
│ │ ├── agent
|
||||
│ │ │ ├── model # Agent 配置、聊天命令、Runner 等领域模型
|
||||
│ │ │ ├── ports # 模型、工具、Agent、Runner、Registry 等领域端口
|
||||
│ │ │ ├── model # Agent 配置模型、聊天命令、Runner 接口
|
||||
│ │ │ ├── ports # 模型、工具、Agent、Runner、Registry、SessionStore 端口
|
||||
│ │ │ └── service
|
||||
│ │ │ ├── armory # Agent 装配领域服务与核心节点
|
||||
│ │ │ │ ├── factory # 默认装配工厂
|
||||
│ │ │ │ └── workflow # loop / parallel / sequential 工作流节点
|
||||
│ │ │ └── chat # 会话与聊天运行时服务
|
||||
│ │ │ ├── armory # Agent 装配领域服务与节点链
|
||||
│ │ │ └── chat # 会话解析与聊天运行时服务
|
||||
│ │ └── shared/tree # 泛型策略树路由框架
|
||||
│ ├── infrastructure # Eino、ADK、MySQL、Redis、日志等适配器
|
||||
│ └── trigger/http # Gin HTTP 入站适配器
|
||||
├── pkg/types # 响应码与应用错误
|
||||
├── .env.example # 环境变量示例
|
||||
│ ├── infrastructure
|
||||
│ │ ├── adk # Agent/Runner/插件适配
|
||||
│ │ ├── ai # OpenAI-compatible client、MCP SSE client、tool/skill 工厂
|
||||
│ │ ├── cache # Redis client adapter
|
||||
│ │ ├── logging # zap logger
|
||||
│ │ └── persistence # MySQL/GORM adapter
|
||||
│ └── trigger/http # Gin HTTP 入站路由
|
||||
├── pkg/types # 应用错误码与 AppError
|
||||
├── .env.example
|
||||
├── go.mod
|
||||
└── README.md
|
||||
```
|
||||
|
||||
## 架构设计
|
||||
## 后端架构
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
Client["客户端 / frontend"] --> Trigger["trigger/http<br/>Gin 路由"]
|
||||
Trigger --> ChatService["domain/service/chat<br/>聊天服务"]
|
||||
ChatService --> Registry["AgentRegistry"]
|
||||
Registry --> Runner["Runner"]
|
||||
Client["Client / frontend"] --> Gin["trigger/http<br/>Gin routes"]
|
||||
Gin --> ChatService["domain/agent/service/chat"]
|
||||
ChatService --> Registry["AgentRegistry<br/>in-memory by default"]
|
||||
ChatService --> SessionStore["SessionStore<br/>in-memory by default"]
|
||||
Registry --> Runner["model.Runner"]
|
||||
Runner --> Agent["ADK adapter Agent"]
|
||||
Agent --> Model["ports.ChatModel"]
|
||||
Model --> OpenAI["OpenAI-compatible<br/>chat/completions"]
|
||||
Agent --> ToolRouter["MCPToolRouter"]
|
||||
ToolRouter --> MCP["MCP SSE tools"]
|
||||
|
||||
Config["configs/*.yaml"] --> App["internal/app<br/>配置加载与应用装配"]
|
||||
App --> Armory["domain/service/armory<br/>Agent 装配"]
|
||||
Config["configs/application.yaml<br/>configs/agent/*.yaml"] --> Bootstrap["internal/app/bootstrap"]
|
||||
Bootstrap --> Armory["domain/agent/service/armory"]
|
||||
Armory --> Registry
|
||||
|
||||
Armory --> Ports["domain/agent/ports"]
|
||||
ChatService --> Ports
|
||||
Ports --> Infra["internal/infrastructure"]
|
||||
Infra --> Eino["Eino"]
|
||||
Infra --> ADK["Google ADK Go"]
|
||||
Infra --> MySQL["MySQL / GORM"]
|
||||
Infra --> Redis["Redis"]
|
||||
```
|
||||
|
||||
### 分层边界
|
||||
后端按端口与适配器组织：
|
||||
|
||||
- `internal/api`：请求/响应 DTO 与统一响应结构。
|
||||
- `internal/app`：应用启动、配置加载、服务装配边界。
|
||||
- `internal/domain`：领域模型、端口、Armory 装配、聊天运行时、策略树框架。
|
||||
- `internal/trigger`：HTTP 等入站触发器。
|
||||
- `internal/infrastructure`：数据库、缓存、AI SDK、日志等外部依赖适配。
|
||||
- `pkg/types`：跨层可复用的错误码和应用错误。
|
||||
- `internal/domain` 定义核心模型、端口、Armory 装配和聊天服务。
|
||||
- `internal/app/bootstrap` 负责把配置、领域服务、基础设施 adapter 和 Gin 路由连起来。
|
||||
- `internal/infrastructure` 实现外部依赖适配，包括模型 client、MCP client、ADK Runner、Redis、MySQL 和日志。
|
||||
- `internal/trigger/http` 只处理 HTTP 入参、出参和路由注册。
|
||||
- `pkg/types` 提供跨层使用的错误码：`0000` 成功、`0001` 未知错误、`0002` 参数错误、`0003` Agent 不存在。
|
||||
|
||||
领域层保持稳定，不直接导入 Gin、GORM、Redis、Eino、ADK Go 或 provider-specific 的基础设施包。
|
||||
## 启动流程
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Main as cmd/server
|
||||
participant Config as app/config
|
||||
participant Bootstrap as app/bootstrap
|
||||
participant Armory as domain/armory
|
||||
participant HTTP as Gin
|
||||
|
||||
Main->>Main: parse -env and -config flags
|
||||
Main->>Main: load dotenv file if present
|
||||
Main->>Config: LoadApplication(configs/application.yaml)
|
||||
Main->>Bootstrap: Build(context, appCfg, logger)
|
||||
Bootstrap->>Config: LoadAgentTablesFile(configured paths)
|
||||
Bootstrap->>Armory: AcceptArmoryAgents(tables)
|
||||
Armory->>Bootstrap: registered runnable Agents
|
||||
Bootstrap->>HTTP: create router and register /healthz + /api/v1
|
||||
Main->>HTTP: engine.Run()
|
||||
```
|
||||
|
||||
入口文件是 `cmd/server/main.go`。默认行为：
|
||||
|
||||
- `-env` 默认读取 `.env`，也可通过 `APP_ENV_FILE` 指定；传空字符串可跳过 dotenv。
|
||||
- `-config` 默认读取 `configs/application.yaml`，也可通过 `APP_CONFIG` 指定。
|
||||
- dotenv 中的变量会进入进程环境，Agent YAML 里的 `${VAR}` 和 `${VAR:-default}` 会在加载时展开。
|
||||
- `configs/application.yaml` 负责声明服务地址、LLM 请求超时、Agent 配置文件路径，以及当前可选的 MySQL/Redis 设置。
|
||||
- `bootstrap.Build` 会装配 Agent、创建 `ChatService`、注册 Gin 路由并返回可运行的 `Engine`。
|
||||
|
||||
## Armory 装配流程
|
||||
|
||||
Armory 是项目里的 Agent 装配链路。它接收 Agent 配置表，按节点顺序构建模型、工具、Agent、Workflow 和 Runner。
|
||||
Armory 是 Agent 配置到运行时对象的装配链。每个 Agent table 都会使用新的 `DynamicContext`，按节点顺序构建和传递装配状态。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Root["RootNode<br/>装配入口"] --> AiApi["AiAPINode<br/>创建模型 API"]
|
||||
AiApi --> ChatModel["ChatModelNode<br/>创建 ChatModel 并挂载工具"]
|
||||
ChatModel --> Agent["AgentNode<br/>创建单 Agent"]
|
||||
Agent --> Workflow["workflow.AgentWorkflowNode<br/>创建工作流 Agent"]
|
||||
Workflow --> Runner["RunnerNode<br/>创建并注册 Runner"]
|
||||
Root["RootNode"] --> Api["AiAPINode<br/>build ModelAPI"]
|
||||
Api --> ChatModel["ChatModelNode<br/>build MCP/skill tools<br/>build ChatModel"]
|
||||
ChatModel --> Agent["AgentNode<br/>build LLM Agents"]
|
||||
Agent --> Workflow["AgentWorkflowNode<br/>build loop/parallel/sequential Agents"]
|
||||
Workflow --> Runner["RunnerNode<br/>build Runner and register Agent"]
|
||||
```
|
||||
|
||||
最新代码已经按职责拆分：
|
||||
关键文件：
|
||||
|
||||
```text
|
||||
internal/domain/agent/service/armory
|
||||
├── root_node.go
|
||||
├── ai_api_node.go
|
||||
├── chat_model_node.go
|
||||
├── agent_node.go
|
||||
├── runner_node.go
|
||||
├── factory/factory.go
|
||||
└── workflow
|
||||
├── agent_workflow_node.go
|
||||
├── loop_node.go
|
||||
├── parallel_node.go
|
||||
└── sequential_node.go
|
||||
- `internal/domain/agent/service/armory/factory/factory.go`：组合完整节点链。
|
||||
- `internal/domain/agent/service/armory/context.go`：保存 ModelAPI、ChatModel、已构建 Agent、当前 workflow 进度和临时值。
|
||||
- `internal/domain/agent/service/armory/chat_model_node.go`：构建 MCP 工具、skill 工具和 ChatModel。
|
||||
- `internal/domain/agent/service/armory/workflow/*.go`：按 `loop`、`parallel`、`sequential` 构建 workflow Agent。
|
||||
- `internal/domain/agent/service/armory/runner_node.go`：根据 `runner.agent-name` 找到入口 Agent，创建 Runner 并注册到 `AgentRegistry`。
|
||||
|
||||
Workflow 行为：
|
||||
|
||||
- `sequential`：按配置顺序执行子 Agent，并用子 Agent 的 `output-key` 保存中间结果，后续 Agent 指令可用 `{output_key}` 引用。
|
||||
- `loop`：当前 adapter 中按 fan-out 方式执行配置的子 Agent；配置里保留 `max-iterations` 字段。
|
||||
- `parallel`：当前 adapter 中按 fan-out 方式聚合子 Agent 输出。
|
||||
|
||||
## 运行时对话流程
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Client
|
||||
participant Handler as trigger/http
|
||||
participant Chat as chat.Service
|
||||
participant Registry as AgentRegistry
|
||||
participant Runner
|
||||
participant Agent
|
||||
participant Model as OpenAI-compatible model
|
||||
participant Tool as MCPToolRouter
|
||||
|
||||
Client->>Handler: POST /api/v1/chat
|
||||
Handler->>Chat: HandleMessage(agentId,userId,sessionId,message)
|
||||
Chat->>Registry: Get(agentId)
|
||||
Chat->>Runner: Run(userId,sessionId,content)
|
||||
Runner->>Agent: run(content)
|
||||
Agent->>Model: chat/completions
|
||||
alt model requests tool calls
|
||||
Agent->>Tool: CallTool(name,args)
|
||||
Tool-->>Agent: tool result
|
||||
Agent->>Model: next chat/completions with tool result
|
||||
end
|
||||
Model-->>Agent: final content
|
||||
Agent-->>Runner: output
|
||||
Runner-->>Handler: []string
|
||||
Handler-->>Client: {code,info,data}
|
||||
```
|
||||
|
||||
Workflow 支持三种编排方式：
|
||||
|
||||
- `loop`：循环执行子 Agent，支持最大迭代次数配置。
|
||||
- `parallel`：并行组合多个子 Agent。
|
||||
- `sequential`：按顺序串联单 Agent 或已装配的 Workflow Agent。
|
||||
同步聊天走 `Runner.Run`，流式聊天走 `Runner.Stream`。LLM Agent 最多允许 4 轮 tool-call 循环，避免工具调用无限递归。
|
||||
|
||||
## 快速开始
|
||||
|
||||
### 环境要求
|
||||
|
||||
- Go 1.25.6+
|
||||
- Node.js 18+ 与 npm（仅在启动 `frontend/` 时需要）
|
||||
- Docker，可选，用于本地 MySQL / Redis
|
||||
- Node.js 18+ 和 npm，仅启动 `frontend/` 时需要
|
||||
- Docker，可选，仅在本地启动 MySQL/Redis 参考服务时需要
|
||||
- 一个 OpenAI-compatible Chat Completions 服务
|
||||
- 如果启用示例里的百度搜索 MCP，还需要可访问的 MCP SSE endpoint
|
||||
|
||||
### 获取代码并编译
|
||||
### 1. 安装依赖并编译
|
||||
|
||||
```bash
|
||||
git clone <repo-url>
|
||||
cd ai-agent-scaffold-go
|
||||
go mod tidy
|
||||
go build ./...
|
||||
```
|
||||
|
||||
### 启动后端服务入口
|
||||
### 2. 准备环境变量
|
||||
|
||||
复制示例文件：
|
||||
|
||||
```bash
|
||||
go run ./cmd/server
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
当前 `cmd/server` 会完成日志初始化并输出启动日志。完整运行时装配、Armory 初始化、Gin 路由挂载等能力已经按包结构准备好，后续可以继续在入口层串接。
|
||||
至少替换以下变量为自己的真实值：
|
||||
|
||||
### 启动本地基础设施
|
||||
```dotenv
|
||||
OPENAI_BASE_URL=https://api.example.com/
|
||||
OPENAI_API_KEY=replace-with-your-key
|
||||
BAIDU_SEARCH_MCP_BASE_URI=http://example.com/mcp/
|
||||
BAIDU_SEARCH_MCP_SSE_ENDPOINT=sse?api_key=replace-with-your-key
|
||||
```
|
||||
|
||||
`configs/agent/*.yaml` 会读取这些变量来构建模型和 MCP 工具。
|
||||
|
||||
### 3. 可选：启动本地 MySQL/Redis
|
||||
|
||||
当前默认后端启动路径使用内存态 Agent registry 和 session store；MySQL/Redis 适配器已经存在，但不是默认启动的硬依赖。需要本地服务时可以使用：
|
||||
|
||||
```bash
|
||||
docker compose -f deployments/docker-compose.yml up -d
|
||||
```
|
||||
|
||||
默认端口：
|
||||
参考端口：
|
||||
|
||||
- MySQL：`127.0.0.1:13306`
|
||||
- Redis：`127.0.0.1:16379`
|
||||
|
||||
### 启动前端
|
||||
|
||||
仓库内置一个 Next.js 示例前端，默认调用后端 `http://localhost:8091/api/v1`。最小启动方式：
|
||||
### 4. 启动后端
|
||||
|
||||
```bash
|
||||
cd frontend
|
||||
npm install
|
||||
npm run dev
|
||||
go run ./cmd/server
|
||||
```
|
||||
|
||||
访问：
|
||||
也可以显式指定文件：
|
||||
|
||||
```bash
|
||||
go run ./cmd/server -env .env -config configs/application.yaml
|
||||
```
|
||||
|
||||
默认监听地址来自 `configs/application.yaml`：
|
||||
|
||||
```text
|
||||
http://localhost:3000
|
||||
:8091
|
||||
```
|
||||
|
||||
更多前端使用细节见 `frontend/README.md`。
|
||||
健康检查：
|
||||
|
||||
```bash
|
||||
curl http://localhost:8091/healthz
|
||||
```
|
||||
|
||||
预期响应：
|
||||
|
||||
```json
|
||||
{"status":"ok"}
|
||||
```
|
||||
|
||||
## 配置说明
|
||||
|
||||
应用主配置：
|
||||
### 应用配置
|
||||
|
||||
```text
|
||||
configs/application.yaml
|
||||
```
|
||||
|
||||
Agent 示例配置：
|
||||
|
||||
```text
|
||||
configs/agent/only-one-agent.yaml
|
||||
configs/agent/agent-draw-io.yaml
|
||||
```
|
||||
|
||||
环境变量示例：
|
||||
|
||||
```text
|
||||
.env.example
|
||||
```
|
||||
|
||||
`configs/application.yaml` 会声明服务端口、本地数据库、Redis 和 Agent 配置路径：
|
||||
`configs/application.yaml` 控制应用启动参数：
|
||||
|
||||
```yaml
|
||||
app:
|
||||
@@ -241,16 +313,30 @@ server:
|
||||
addr: ":8091"
|
||||
database:
|
||||
required: false
|
||||
dsn: "root:123456@tcp(127.0.0.1:13306)/ai_agent_scaffold_go?charset=utf8mb4&parseTime=True&loc=Local"
|
||||
dsn: "root:<password>@tcp(127.0.0.1:13306)/ai-agent-scaffold-go?charset=utf8mb4&parseTime=True&loc=Local"
|
||||
redis:
|
||||
required: false
|
||||
addr: "127.0.0.1:16379"
|
||||
password: ""
|
||||
db: 0
|
||||
llm:
|
||||
request-timeout: 5m
|
||||
agent:
|
||||
config-paths:
|
||||
- configs/agent/only-one-agent.yaml
|
||||
- configs/agent/agent-draw-io.yaml
|
||||
```
|
||||
|
||||
Agent 配置示例（节选自 `configs/agent/only-one-agent.yaml`）：
|
||||
说明：
|
||||
|
||||
- `server.addr` 是 Gin 监听地址。
|
||||
- `llm.request-timeout` 使用 Go `time.ParseDuration` 格式，例如 `30s`、`5m`、`1h`。
|
||||
- `agent.config-paths` 可配置多个 Agent YAML，启动时会合并所有 tables。
|
||||
- `database` 和 `redis` 设置目前主要对应基础设施 adapter；默认 bootstrap 没有强制打开它们。
|
||||
|
||||
### Agent 配置
|
||||
|
||||
Agent 配置文件结构位于 `configs/agent/*.yaml`：
|
||||
|
||||
```yaml
|
||||
ai:
|
||||
@@ -265,17 +351,17 @@ ai:
|
||||
agent-desc: "single agent demo"
|
||||
module:
|
||||
ai-api:
|
||||
base-url: "https://apis.itedus.cn"
|
||||
api-key: "${OPENAI_API_KEY}"
|
||||
base-url: ${OPENAI_BASE_URL}
|
||||
api-key: ${OPENAI_API_KEY}
|
||||
completions-path: "v1/chat/completions"
|
||||
embeddings-path: "v1/embeddings"
|
||||
chat-model:
|
||||
model: "gpt-4.1"
|
||||
model: "gpt-5.5"
|
||||
tool-mcp-list:
|
||||
- sse:
|
||||
name: baidu-search
|
||||
base-uri: http://appbuilder.baidu.com
|
||||
sse-endpoint: /v2/ai_search/mcp/sse?api_key=${BAIDU_SEARCH_MCP_API_KEY}
|
||||
base-uri: ${BAIDU_SEARCH_MCP_BASE_URI}
|
||||
sse-endpoint: ${BAIDU_SEARCH_MCP_SSE_ENDPOINT}
|
||||
request-timeout: 500000
|
||||
tool-skills-list:
|
||||
- type: "resource"
|
||||
@@ -292,25 +378,77 @@ ai:
|
||||
- "myLogPlugin"
|
||||
```
|
||||
|
||||
连接真实模型服务前，需要复制 `.env.example` 并设置真实的模型 API Key。
|
||||
启动时会校验：
|
||||
|
||||
- `app-name`
|
||||
- `agent.agent-id`
|
||||
- `module.ai-api.base-url`
|
||||
- `module.ai-api.api-key`
|
||||
- `module.chat-model.model`
|
||||
- `module.agents[].name`
|
||||
- `module.agents[].instruction`
|
||||
- `module.runner.agent-name`
|
||||
- 每个 MCP tool 必须且只能声明 `local`、`sse`、`stdio` 之一
|
||||
- workflow type 必须是 `loop`、`parallel` 或 `sequential`
|
||||
|
||||
默认值：
|
||||
|
||||
- `ai-api.completions-path` 默认 `v1/chat/completions`
|
||||
- `ai-api.embeddings-path` 默认 `v1/embeddings`
|
||||
- `tool-skills-list[].type` 默认 `directory`
|
||||
- `agent-workflows[].max-iterations` 默认 `3`
|
||||
|
||||
## HTTP API
|
||||
|
||||
基础路径：
|
||||
非流式接口统一返回：
|
||||
|
||||
```text
|
||||
/api/v1
|
||||
```json
|
||||
{
|
||||
"code": "0000",
|
||||
"info": "success",
|
||||
"data": {}
|
||||
}
|
||||
```
|
||||
|
||||
这些路由由 `internal/trigger/http/agent_handler.go` 中的 `RegisterAgentRoutes` 注册。当前服务入口还没有把 Gin 路由完整挂到 `cmd/server`，接入时可复用 `RegisterAgentRoutes(router, chatService)`。
|
||||
### GET /healthz
|
||||
|
||||
### 查询 Agent 配置
|
||||
健康检查。
|
||||
|
||||
```bash
|
||||
curl http://localhost:8091/healthz
|
||||
```
|
||||
|
||||
```json
|
||||
{"status":"ok"}
|
||||
```
|
||||
|
||||
### GET /api/v1/query_ai_agent_config_list
|
||||
|
||||
查询已经注册的 Agent。
|
||||
|
||||
```bash
|
||||
curl http://localhost:8091/api/v1/query_ai_agent_config_list
|
||||
```
|
||||
|
||||
### 创建会话
|
||||
响应示例：
|
||||
|
||||
```json
|
||||
{
|
||||
"code": "0000",
|
||||
"info": "success",
|
||||
"data": [
|
||||
{
|
||||
"agentId": "100003",
|
||||
"agentName": "single agent",
|
||||
"agentDesc": "single agent demo"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### POST /api/v1/create_session
|
||||
|
||||
创建或复用某个 `userId + agentId` 的会话。
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:8091/api/v1/create_session \
|
||||
@@ -318,31 +456,107 @@ curl -X POST http://localhost:8091/api/v1/create_session \
|
||||
-d '{"agentId":"100003","userId":"u1001"}'
|
||||
```
|
||||
|
||||
也支持 GET：
|
||||
响应示例：
|
||||
|
||||
```json
|
||||
{
|
||||
"code": "0000",
|
||||
"info": "success",
|
||||
"data": {
|
||||
"sessionId": "testAgent03:u1001:1"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
同等 GET 形式：
|
||||
|
||||
```bash
|
||||
curl 'http://localhost:8091/api/v1/create_session?agentId=100003&userId=u1001'
|
||||
```
|
||||
|
||||
### 同步对话
|
||||
### POST /api/v1/chat
|
||||
|
||||
同步聊天。`sessionId` 可为空；为空时服务会自动创建或复用会话。
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:8091/api/v1/chat \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d '{"agentId":"100003","userId":"u1001","message":"帮我制定一个学习计划"}'
|
||||
-d '{
|
||||
"agentId": "100003",
|
||||
"userId": "u1001",
|
||||
"sessionId": "",
|
||||
"message": "帮我制定一个 Go Agent 学习计划"
|
||||
}'
|
||||
```
|
||||
|
||||
### 流式对话
|
||||
响应示例：
|
||||
|
||||
`/chat_stream` 通过 SSE（`text/event-stream`）推送结果，每个分片以 `event: message` 形式发送，错误以 `event: error` 结束。
|
||||
```json
|
||||
{
|
||||
"code": "0000",
|
||||
"info": "success",
|
||||
"data": {
|
||||
"content": "..."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### POST /api/v1/chat_stream
|
||||
|
||||
流式聊天，响应类型为 `text/event-stream`。
|
||||
|
||||
```bash
|
||||
curl -N -X POST http://localhost:8091/api/v1/chat_stream \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d '{"agentId":"100003","userId":"u1001","sessionId":"session-u1001","message":"继续"}'
|
||||
-d '{
|
||||
"agentId": "100003",
|
||||
"userId": "u1001",
|
||||
"sessionId": "",
|
||||
"message": "继续细化第一周计划"
|
||||
}'
|
||||
```
|
||||
|
||||
## 开发命令
|
||||
流式片段示例：
|
||||
|
||||
```text
|
||||
event: message
|
||||
data: 第一周可以从...
|
||||
|
||||
event: message
|
||||
data: 接下来...
|
||||
```
|
||||
|
||||
如果执行出错，服务会发送：
|
||||
|
||||
```text
|
||||
event: error
|
||||
data: <error message>
|
||||
```
|
||||
|
||||
## 前端启动
|
||||
|
||||
`frontend/` 是一个 Next.js draw.io 示例前端，默认调用 `http://localhost:8091/api/v1`；启动方式是 `cd frontend && npm install && npm run dev`，然后访问 `http://localhost:3000`。
|
||||
|
||||
如需改后端地址，设置：
|
||||
|
||||
```bash
|
||||
NEXT_PUBLIC_API_BASE_URL=http://localhost:8091/api/v1
|
||||
```
|
||||
|
||||
## 开发与验证
|
||||
|
||||
后端常用命令：
|
||||
|
||||
```bash
|
||||
go test ./...
|
||||
go build ./...
|
||||
```
|
||||
|
||||
检查 Go 文件是否需要格式化：
|
||||
|
||||
```bash
|
||||
test -z "$(gofmt -l .)"
|
||||
```
|
||||
|
||||
格式化：
|
||||
|
||||
@@ -350,45 +564,14 @@ curl -N -X POST http://localhost:8091/api/v1/chat_stream \
|
||||
gofmt -w .
|
||||
```
|
||||
|
||||
编译：
|
||||
前端常用命令：
|
||||
|
||||
```bash
|
||||
go build ./...
|
||||
cd frontend
|
||||
npm run lint
|
||||
npm run build
|
||||
```
|
||||
|
||||
启动前端开发服务器：
|
||||
## 联系作者
|
||||
|
||||
```bash
|
||||
cd frontend && npm run dev
|
||||
```
|
||||
|
||||
## 当前实现状态
|
||||
|
||||
- DDD 包结构、领域模型、端口、策略树和 Armory 装配链路已经建立。
|
||||
- Armory 核心节点、工厂、Workflow 节点已按职责拆分。
|
||||
- ChatService、AgentRegistry、SessionStore 和 HTTP 路由边界已在代码结构中分离。
|
||||
- Eino、ADK Go、GORM、Redis、zap 等依赖已经纳入模块，并通过本地端口和基础设施包隔离。
|
||||
- `cmd/server` 已串接配置加载、Armory 装配、Gin 路由和插件链路，启动后即对外提供 `/api/v1` 接口。
|
||||
- Runner 已接入真实 OpenAI 兼容 ChatModel：`/api/v1/chat` 调 `chat/completions` 同步接口，`/api/v1/chat_stream` 走 `stream: true` SSE 推送 delta。
|
||||
- SSE MCP 客户端可用：装配阶段连接 `tool-mcp-list[].sse`，运行时模型选中工具后真正发起 JSON-RPC `tools/call` 并把结果回灌给下一轮模型请求，工具调用循环上限为 4 轮。
|
||||
- Local MCP、stdio MCP 仍返回 unsupported 错误；Skill 工具当前只向模型暴露名字，不参与执行。
|
||||
- `frontend/` 提供基于 Next.js 的 draw.io 示例前端，默认对接后端 `/api/v1`。
|
||||
|
||||
## 路线图
|
||||
|
||||
- 接入更稳定的模型 backoff / 重试与请求级超时控制。
|
||||
- 补齐 stdio MCP 客户端实现，扩展 local MCP 真实执行入口。
|
||||
- 让 Skill 工具具备运行时调用能力，并把 skill 元数据注入模型 tool schema。
|
||||
- 增加基于 MySQL 的 Agent 配置仓储。
|
||||
- 增加基于 Redis 的分布式会话存储。
|
||||
- 增加请求追踪、Token 用量、Agent Workflow 事件等可观测能力。
|
||||
|
||||
## Star 趋势
|
||||
|
||||
[](https://star-history.com/#peakxy/ai-agent-scaffold-go&Date)
|
||||
|
||||
## 许可证
|
||||
|
||||
## 联系方式
|
||||
|
||||
- 邮箱: 2465549609@qq.com
|
||||
- 邮箱：2465549609@qq.com
|
||||
|
||||
Reference in New Issue
Block a user