198 lines
5.8 KiB
Markdown
198 lines
5.8 KiB
Markdown
# GoLoom
|
||
|
||
**AI Agent Scaffold** — 一个基于 Go 的多 Agent LLM 编排框架。
|
||
|
||
GoLoom 提供开箱即用的 HTTP 服务，支持多 Agent 编排、SSE 流式对话、工具调用（Function Calling）以及 YAML 配置驱动的 Agent 定义，帮助你快速构建和部署 AI Agent 应用。
|
||
|
||
## 核心特性
|
||
|
||
- **多 Agent 编排** — 支持 4 种编排模式：LLM（单轮）、Sequential（顺序）、Parallel（并发）、Loop（循环）
|
||
- **SSE 流式对话** — 基于 Server-Sent Events 的实时流式输出
|
||
- **工具调用** — OpenAI Function Calling 协议，支持自定义 Tool 扩展
|
||
- **YAML 配置驱动** — 通过 YAML 文件定义 Agent 拓扑，支持环境变量展开
|
||
- **OpenAI 兼容** — 适配 DeepSeek、通义千问等 OpenAI 兼容 API
|
||
- **Next.js 前端** — 配套的 React + TypeScript + Tailwind CSS 聊天界面
|
||
|
||
## 技术栈
|
||
|
||
| 层级 | 技术 |
|
||
|------|------|
|
||
| 后端语言 | Go 1.26 |
|
||
| Web 框架 | Gin |
|
||
| 日志 | Zap (structured logging) |
|
||
| 前端框架 | Next.js + React + TypeScript |
|
||
| 样式 | Tailwind CSS |
|
||
| LLM 协议 | OpenAI Chat Completions API |
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
GoLoom/
|
||
├── backend/ # Go 后端
|
||
│ ├── cmd/server/main.go # 入口：.env → config → bootstrap → Gin
|
||
│ ├── internal/
|
||
│ │ ├── config/ # YAML 配置加载 + ${VAR} 环境变量展开
|
||
│ │ ├── handler/ # Gin 路由、请求/响应处理、SSE
|
||
│ │ ├── service/ # ChatService、Agent 实现、Runner、Assembler
|
||
│ │ ├── model/ # 核心接口（Agent、ChatModel、Tool、Runner）
|
||
│ │ └── llm/ # OpenAI 兼容 HTTP 客户端
|
||
│ ├── pkg/types/ # 错误码与 AppError 类型
|
||
│ ├── configs/ # application.yaml + agent/*.yaml
|
||
│ └── .env.example # 环境变量模板
|
||
├── frontend/ # Next.js 前端
|
||
├── docs/ # 详细文档（中文）
|
||
└── CLAUDE.md # Claude Code 开发指南
|
||
```
|
||
|
||
**依赖方向：** handler → service → model/llm（`model` 不依赖任何内部包）
|
||
|
||
## 快速开始
|
||
|
||
### 1. 环境准备
|
||
|
||
- Go 1.26+
|
||
- Node.js 18+（前端）
|
||
- 一个 OpenAI 兼容的 LLM API Key
|
||
|
||
### 2. 后端
|
||
|
||
```bash
|
||
cd backend
|
||
|
||
# 配置环境变量
|
||
cp .env.example .env
|
||
# 编辑 .env，填入你的 API Key
|
||
|
||
# 安装依赖
|
||
go mod tidy
|
||
|
||
# 运行
|
||
go run ./cmd/server
|
||
```
|
||
|
||
服务默认监听 `http://localhost:8091`。
|
||
|
||
### 3. 前端
|
||
|
||
```bash
|
||
cd frontend
|
||
|
||
npm install
|
||
npm run dev
|
||
```
|
||
|
||
前端默认运行在 `http://localhost:3000`。
|
||
|
||
## API 接口
|
||
|
||
基础路径：`/api/v1`
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/healthz` | 健康检查 |
|
||
| GET | `/api/v1/query_ai_agent_config_list` | 查询已注册 Agent 列表 |
|
||
| POST | `/api/v1/create_session` | 创建会话 |
|
||
| POST | `/api/v1/chat` | 同步对话 |
|
||
| POST | `/api/v1/chat_stream` | SSE 流式对话 |
|
||
|
||
**典型流程：** 查询 Agent 列表 → 创建会话 → 使用 sessionId 进行对话。
|
||
|
||
### 示例
|
||
|
||
```bash
|
||
# 查询 Agent 列表
|
||
curl http://localhost:8091/api/v1/query_ai_agent_config_list
|
||
|
||
# 创建会话
|
||
curl -X POST http://localhost:8091/api/v1/create_session \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"agent_id": "your-agent-id"}'
|
||
|
||
# 同步对话
|
||
curl -X POST http://localhost:8091/api/v1/chat \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"session_id": "xxx", "content": "你好"}'
|
||
|
||
# 流式对话
|
||
curl -X POST http://localhost:8091/api/v1/chat_stream \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"session_id": "xxx", "content": "你好"}'
|
||
```
|
||
|
||
## Agent 配置
|
||
|
||
在 `backend/configs/agent/` 目录下创建 YAML 文件定义 Agent：
|
||
|
||
```yaml
|
||
id: my-agent
|
||
name: My Agent
|
||
description: 一个示例 Agent
|
||
type: llm
|
||
model_id: deepseek-chat
|
||
system_prompt: |
|
||
你是一个 helpful assistant.
|
||
tools:
|
||
- name: search
|
||
description: 搜索工具
|
||
parameters:
|
||
query:
|
||
type: string
|
||
required: true
|
||
description: 搜索关键词
|
||
```
|
||
|
||
支持 4 种 Agent 类型：
|
||
|
||
| 类型 | 说明 |
|
||
|------|------|
|
||
| `llm` | 单次 LLM 调用，支持工具调用循环（最多 4 轮） |
|
||
| `sequential` | 顺序执行子 Agent，前一个的输出注入下一个的 `{outputKey}` |
|
||
| `parallel` | 并发执行所有子 Agent，合并结果 |
|
||
| `loop` | 重复执行子 Agent，最多 `maxIterations` 次 |
|
||
|
||
配置支持环境变量展开：`${VAR}` 或 `${VAR:-default}`。
|
||
|
||
## 测试
|
||
|
||
```bash
|
||
cd backend
|
||
|
||
# 运行所有测试
|
||
go test ./...
|
||
|
||
# 带 race 检测和覆盖率
|
||
go test -race -coverprofile=coverage.out ./...
|
||
|
||
# 查看覆盖率
|
||
go tool cover -html=coverage.out
|
||
|
||
# 运行指定测试
|
||
go test -run TestFuncName ./internal/service/...
|
||
|
||
# Lint
|
||
golangci-lint run --timeout=5m
|
||
```
|
||
|
||
## 文档
|
||
|
||
| 文档 | 内容 |
|
||
|------|------|
|
||
| [架构设计](docs/architecture.md) | 整体架构与设计决策 |
|
||
| [API 参考](docs/api-reference.md) | HTTP API 详细规格与 curl 示例 |
|
||
| [后端构建指南](docs/build-from-scratch.md) | 完整的 Go 后端实现参考 |
|
||
| [前端构建指南](docs/frontend-build-from-scratch.md) | Next.js 前端实现参考 |
|
||
| [测试指南](docs/testing-guide.md) | 测试规范与最佳实践 |
|
||
| [日志指南](docs/logging-guide.md) | Zap 日志级别与结构化字段规范 |
|
||
| [构建计划](docs/plan.md) | 6 阶段开发计划与进度追踪 |
|
||
|
||
## 设计理念
|
||
|
||
- **接口驱动** — 核心抽象（Agent、ChatModel、Tool、Runner）定义在 `model` 包，零外部依赖
|
||
- **配置即代码** — YAML 定义 Agent 拓扑，无需修改代码即可编排复杂工作流
|
||
- **依赖注入** — ChatService 通过接口注入 AgentRegistry 和 SessionStore，便于测试和扩展
|
||
- **渐进式复杂度** — 从单 Agent 到多 Agent 编排，按需组合
|
||
|
||
## 协议
|
||
|
||
MIT License
|