From a31505cd9500a412e488efae16e94755df49f5f8 Mon Sep 17 00:00:00 2001 From: hhs <386998068@qq.com> Date: Wed, 10 Jun 2026 16:15:38 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0=20README.md=20?= =?UTF-8?q?=E9=A1=B9=E7=9B=AE=E4=BB=8B=E7=BB=8D=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 197 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 197 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..a50af8b --- /dev/null +++ b/README.md @@ -0,0 +1,197 @@ +# 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