# goai-agent-scaffold

**Repository Path**: jerris-code-space/goai-agent-scaffold

## Basic Information

- **Project Name**: goai-agent-scaffold
- **Description**: 基于 github.com/zendev-sh/goai 库构建的智能体脚手架工程。
- **Primary Language**: Go
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-11
- **Last Updated**: 2026-06-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# GoAI Agent Scaffold

基于 Go 的 AI 智能体脚手架，提供 LLM 调用、多后端 RAG 检索增强（Milvus / PGVector / Memory）、LLM 驱动的工具调用（Function Calling）、HTTP API、Cobra CLI（统一入口）、异步任务和回调机制。

## 架构概览

```
                      +---------------------+
                      |   CLI (Cobra 统一)   |
                      | chat | server |embed|
                      +----------+----------+
                                 |
             +-------------------+-------------------+
             |                                       |
+------------v-----------+               +-----------v----------+
|   HTTP Server (Gin)    |               |   Task Manager       |
|   /api/v1/chat|stream  |               |   (Worker Pool)      |
|   /api/v1/task|tools   |               |   pending→done/fail   |
+------------+-----------+               +-----------+----------+
             |                                       |
             +-------------------+-------------------+
                                 |
                       +---------v---------+
                       |   Agent Engine    |
                       | (LLM+RAG+Tool)    |
                       +---------+---------+
                                 |
           +---------------------+---------------------+
           |                     |                     |
+----------v-------+  +----------v----------+  +-------v----------+
|   LLM Adapter    |  |   RAG 检索增强      |  |  Tool Registry   |
| Mock | GoAI(OpenAI)| | Memory|Milvus|PGVec|  |  time | http_get |
+------------------+  +---------------------+  +------------------+
```

## 快速开始

### 前置条件

- Go 1.25+
- （可选）OpenAI API Key 或其他兼容的 LLM 服务
- （可选）Milvus / PostgreSQL + pgvector（用于向量检索）

### 安装

```bash
go build -o goai ./cmd/cli
```

### CLI 命令一览

```bash
# 启动 HTTP 服务
./goai server
./goai server -c prod.yaml

# 交互式对话（默认流式输出）
./goai chat
./goai chat --no-stream

# 文档向量化入库
./goai embed -f docs/readme.md
./goai embed -d docs/ --chunk-size 500

# 查看帮助
./goai --help
./goai server --help
```

## 配置

所有配置通过 YAML 文件管理，支持环境变量覆盖（前缀 `GOAI_`，例如 `GOAI_LLM_API_KEY`）。

### 完整配置参考

```yaml
server:
  host: 0.0.0.0
  port: 8080

llm:
  provider: mock              # mock | openai | goai-openai
  api_key: ""                 # OpenAI API Key（mock 模式下无需填写）
  base_url: ""                # 自定义 API 地址（可选）
  model: mock-agent
  timeout: 30s
  max_retries: 2

rag:
  enabled: true
  vector_db: memory           # memory | milvus | pgvector
  top_k: 5
  documents:                  # 内嵌知识库文档（memory 模式）
    - id: intro
      content: "GoAI Agent Scaffold provides LLM calls, RAG..."

  # Embedding 配置（milvus / pgvector 模式需要）
  embedding:
    provider: mock            # mock | openai
    model: text-embedding-3-small
    api_key: ""
    base_url: ""

  # Milvus 连接配置
  milvus:
    address: localhost:19530
    collection: rag_documents
    dim: 1536

  # PGVector 连接配置
  pgvector:
    host: localhost
    port: 5432
    user: postgres
    password: ""
    dbname: rag
    table: documents
    dim: 1536

task:
  worker_pool_size: 5
  queue_size: 100

callback:
  timeout: 10s
```

### 接入真实 LLM

```yaml
llm:
  provider: openai
  api_key: sk-xxxxx
  base_url: https://api.openai.com/v1
  model: gpt-4o-mini
```

`api_key` 可通过环境变量 `GOAI_LLM_API_KEY` 或 `OPENAI_API_KEY` 注入。

### RAG 后端切换

| `vector_db` | 检索方式 | 适用场景 |
|---|---|---|
| `memory`（默认） | 关键词 TF 匹配，零依赖 | 开发调试、小规模文档 |
| `milvus` | 余弦相似度向量检索 | 生产环境、大规模向量库 |
| `pgvector` | PostgreSQL pgvector 余弦相似度 | 已有 PG 基础设施 |

切换方式：修改 `rag.vector_db` 配置项，并配置对应的 `embedding` 和连接参数。

## CLI 命令详解

### `goai chat` — 交互式对话

启动 REPL 对话，Agent 自动加载 RAG 知识库和工具（`time`、`http_get`），LLM 决定是否调用工具。

```
> 现在几点了？
AI: 当前时间是 2026-06-15T10:30:00+08:00

> /exit
```

- `--no-stream` — 禁用流式输出，等待完整回复后一次性显示

### `goai server` — HTTP API 服务

启动 Gin HTTP 服务器，提供完整的 REST API。

### `goai embed` — 文档向量化

将 `.txt`、`.md` 文件智能分块后嵌入向量库（支持 Milvus / PGVector）。

```bash
# 单文件
goai embed -f knowledge.md

# 整个目录
goai embed -d docs/

# 自定义分块
goai embed -f doc.txt --chunk-size 500 --chunk-overlap 100
```

**分块策略**：优先在段落边界（`\n\n`）切割 → 换行 → 句子结尾 → 单词边界，保证语义完整性。

## HTTP API

| 方法 | 路径 | 说明 |
|---|---|---|
| `POST` | `/api/v1/chat` | 同步对话 |
| `GET` | `/api/v1/chat/stream` | 流式对话（SSE） |
| `GET` | `/api/v1/tools` | 已注册工具列表 |
| `POST` | `/api/v1/task/submit` | 提交异步任务 |
| `GET` | `/api/v1/task/:task_id` | 查询任务状态 |
| `GET` | `/healthz` | 健康检查 |

### POST /api/v1/chat

```json
// Request
{ "session_id": "abc", "message": "现在几点了？" }

// Response
{
  "reply": "当前时间是 2026-06-15T10:30:00+08:00",
  "rag": {
    "question": "现在几点了？",
    "context": "...",
    "documents": [...]
  }
}
```

### GET /api/v1/chat/stream

```
GET /api/v1/chat/stream?message=hello&session_id=abc
```

SSE 流，每帧格式 `data: {"content":"...","done":false}\n\n`。

### POST /api/v1/task/submit

```json
// Request
{ "message": "帮我分析一下", "callback_url": "https://example.com/cb" }

// Response
{ "task_id": "task_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" }

// Callback POST body
{ "task_id": "task_xxx", "status": "done", "result": "..." }
```

## 模块说明

### Agent（`internal/agent`）

核心引擎，协调三者的协作流程：

```
用户消息 → RAG 检索上下文 → 构建 Prompt + 工具列表 →
LLM 调用（goai 自动处理工具调用循环）→ 最终回复
```

- LLM 决定是否调用工具，goai 库内部自动执行"调用 → 执行 → 回传结果"循环
- 暴露 `RAG()` 方法供 CLI `embed` 命令运行时索引文档

### LLM Adapter（`internal/llm`）

| 实现 | 说明 |
|---|---|
| `MockLLM` | 回显用户输入，零依赖，适合开发调试 |
| `GoAIAdapter` | 基于 `github.com/zendev-sh/goai`，支持 OpenAI 及兼容协议，内置 retry、token 统计、工具调用循环 |

通过 `llm.New(cfg)` 工厂函数切换。

### RAG（`internal/rag`）

多后端的检索增强生成系统：

| 组件 | 说明 |
|---|---|
| `VectorStore` 接口 | 定义 `Search` / `AddDocuments` / `Close` |
| `MemoryStore` | 内存关键词 TF 匹配 |
| `MilvusStore` | Milvus 向量数据库，自动建库建索引 |
| `PGVectorStore` | PostgreSQL + pgvector，自动建表建索引 |
| `Embedder` 接口 | 文本 → 向量转换 |
| `MockEmbedder` | 确定性伪向量（hash），开发用 |
| `OpenAIEmbedder` | 基于 goai 的 OpenAI Embedding API |
| `Service` | 封装 `VectorStore` + `Embedder`，Memory 走关键词，向量后端走 Embedding+Search |

### Tool Calling（`internal/tool`）

- **`Tool` 接口**：`Name()` + `Description()` + `Run()`
- **`Registry`**：注册、查询、执行
- **`ToGoAITool()`**：适配为 goai 原生 Tool，使 LLM 自动触发调用

内置工具：

| 工具 | 名称 | 说明 |
|---|---|---|
| `TimeTool` | `time` | 获取当前时间，支持时区 |
| `HTTPGetTool` | `http_get` | HTTP GET 请求，返回状态码和响应体 |

### 异步任务（`internal/task`）

- 内存 channel 任务队列 + Worker Pool
- 状态流转：`pending` → `running` → `done` / `failed`
- 支持 `callback_url` 回调通知

### Callback（`internal/callback`）

异步任务回调 HTTP 客户端，带超时控制。

## 项目结构

```
goai-agent-scaffold/
├── cmd/
│   ├── cli/
│   │   ├── main.go              # CLI 入口
│   │   └── cmd/
│   │       ├── root.go          # Cobra 根命令（配置加载）
│   │       ├── chat.go          # goai chat 交互式对话
│   │       ├── server.go        # goai server HTTP 服务
│   │       └── embed.go         # goai embed 文档向量化
│   └── server/main.go           # 独立 HTTP 入口（兼容保留）
├── configs/
│   └── config.yaml              # 默认配置
├── internal/
│   ├── agent/                   # Agent 核心引擎
│   │   ├── agent.go
│   │   └── agent_test.go
│   ├── app/                     # 应用组装（依赖注入）
│   │   └── app.go
│   ├── callback/                # 回调 HTTP 客户端
│   │   └── client.go
│   ├── config/                  # 配置加载（Viper）
│   │   └── config.go
│   ├── http/                    # Gin 路由和处理器
│   │   └── router.go
│   ├── llm/                     # LLM 适配器
│   │   ├── llm.go               # 接口定义
│   │   ├── mock.go              # Mock 实现
│   │   ├── goai.go              # GoAI OpenAI 实现
│   │   └── factory.go           # 工厂函数
│   ├── rag/                     # RAG 多后端检索
│   │   ├── rag.go               # RAG 接口 + Document 定义
│   │   ├── service.go           # 检索服务（工厂模式）
│   │   ├── vectorstore.go       # VectorStore 接口 + 工厂
│   │   ├── memory_store.go      # 内存关键词匹配
│   │   ├── milvus_store.go      # Milvus 向量检索
│   │   ├── pgvector_store.go    # PGVector 向量检索
│   │   └── embedder.go          # Embedder 接口 + Mock/OpenAI
│   ├── task/                    # 异步任务系统
│   │   ├── task.go
│   │   └── manager.go
│   └── tool/                    # 工具调用系统
│       ├── tool.go              # Tool 接口 + goai 适配
│       ├── registry.go          # 工具注册中心
│       ├── time.go              # 时间工具
│       └── http.go              # HTTP 请求工具
├── go.mod
├── go.sum
├── README.md
└── PRD.md
```

## 扩展指南

### 添加自定义工具

1. 实现 `tool.Tool` 接口：`Name()`、`Description()`、`Run()`
2. 在 `app.New()` 中 `registry.Register(YourTool{})`

Agent 会将工具暴露给 LLM，由 LLM 自主决策调用。

### 添加新的 RAG 后端

1. 实现 `rag.VectorStore` 接口：`Search()`、`AddDocuments()`、`Close()`
2. 在 `vectorstore.go` 的 `NewVectorStore()` 中添加 case 分支

### 添加新的 Embedding 服务

1. 实现 `rag.Embedder` 接口：`Embed(ctx, text) → ([]float64, error)`
2. 在 `embedder.go` 的 `NewEmbedder()` 中添加 case 分支

### 切换 LLM 提供商

修改 `config.yaml` 的 `llm.provider`：
- `mock` — 本地回显，无需联网
- `openai` / `goai-openai` — 通过 goai 调用 OpenAI 或兼容 API

如需接入其他模型，在 `llm/factory.go` 中添加适配器。