GoLoom/README.md

# 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