# aichat

一个基于 Go + Gin 的 AI 聊天 Web 应用，默认使用火山引擎 Ark/OpenAI 兼容接口，支持多模型配置、流式输出、工具调用、图片输入、上下文窗口管理和本地对话历史。

## 功能特性

- **多模型配置**：在配置文件中维护多个 OpenAI 兼容模型，并可在页面中切换当前模型。
- **流式对话**：通过 SSE 实时返回模型响应，支持 Token 统计与速度展示。
- **工具调用**：内置搜索、计算器、时间、SQL 查询等工具，并通过工具路由按需调用。
- **上下文窗口管理**：根据模型上下文长度自动保留、截断历史消息。
- **对话持久化**：会话保存在本地 `conversations/` 目录，支持创建、查看和删除。
- **多模态输入**：支持图片消息输入，由兼容多模态的模型处理。
- **思考标签解析**：可解析模型输出中的 `<think>` 内容并单独展示。

## 技术栈

- Go 1.25+
- Gin Web Framework
- 火山引擎 Ark SDK / OpenAI 兼容接口
- YAML 配置
- SQLite / MySQL 驱动
- 原生 HTML/CSS/JavaScript

## 快速开始

### 1. 克隆项目

```bash
git clone <your-repo-url>
cd aichat
```

### 2. 安装依赖

```bash
go mod download
```

### 3. 准备配置

首次运行时，程序会自动生成 `config.yaml`。你也可以手动创建：

```yaml
server:
  mode: tcp
  address: 0.0.0.0:8080

openai:
  - name: doubao
    active: true
    api_key: ${ARK_API_KEY}
    base_url: https://ark.cn-beijing.volces.com/api/v3
    model: doubao-seed-2-0-pro-260215
    timeout: 120
    context_window_tokens: 262144

tool_router:
  enabled: true
  openai_name: doubao
  timeout: 30
  max_tokens: 512
  system_prompt: |-
    你可以按需直接调用可用工具来回答用户问题。
    每个工具的 description 描述了它的适用场景和调用条件。
    工具结果优先于模型内置知识；工具失败时必须如实说明，不要编造结果。
    只调用确实必要的工具。
```

建议使用环境变量提供密钥，避免把 API Key 写入仓库：

```bash
export ARK_API_KEY="your-ark-api-key"
```

> `config.yaml` 已在 `.gitignore` 中忽略，适合作为本地私有配置文件。

### 4. 启动服务

```bash
go run main.go
```

启动后访问：

```text
http://localhost:8080
```

## 构建与测试

```bash
# 构建二进制
go build -o aichat main.go

# 运行全部测试
go test ./...

# 查看详细测试输出
go test -v ./...
```

## 配置说明

### `server`

| 字段 | 说明 | 示例 |
| --- | --- | --- |
| `mode` | 服务监听模式，支持 `tcp` 或 Unix socket | `tcp` |
| `address` | 监听地址 | `0.0.0.0:8080` |

### `openai`

`openai` 是模型配置列表，也兼容单对象配置。常用字段：

| 字段 | 说明 |
| --- | --- |
| `name` | 配置名称，用于页面展示和切换 |
| `active` | 是否为默认激活模型；多个配置只能有一个激活 |
| `api_key` | API Key；也可用 `ARK_API_KEY` 环境变量覆盖 |
| `base_url` | OpenAI 兼容接口地址 |
| `model` | 模型名称 |
| `timeout` | 请求超时时间，单位秒 |
| `context_window_tokens` | 上下文窗口 Token 上限 |
| `parse_think_tags` | 是否解析 `<think>` 标签，可选 |

### `tool_router`

工具路由用于判断用户问题是否需要调用工具。

| 字段 | 说明 |
| --- | --- |
| `enabled` | 是否启用工具路由 |
| `openai_name` | 用于工具路由决策的模型配置名称，留空时使用当前激活模型 |
| `timeout` | 工具路由请求超时时间，单位秒 |
| `max_tokens` | 工具路由最大输出 Token 数 |
| `system_prompt` | 工具路由系统提示词 |
| `tools` | 可选的工具覆盖配置 |

## 内置工具

工具配置位于 `agents/*/config.yaml`。

| 工具 | 默认状态 | 说明 |
| --- | --- | --- |
| `search` | 启用 | 联网搜索，默认 DuckDuckGo，可用于实时信息、新闻、版本、网页核验等场景 |
| `calculator` | 启用 | 四则运算和简单数学表达式计算 |
| `time` | 启用 | 将“今天、明天、本周”等相对时间转换为绝对日期范围 |
| `sql` | 禁用 | 查询本地业务数据库，默认 SQLite 只读连接 |

### 搜索工具

默认配置：

```yaml
enabled: true
profiles:
  - name: duckduckgo
    active: true
    enabled: true
    provider: duckduckgo
    base_url: https://api.duckduckgo.com/
    count: 5
    timeout: 10
```

如果使用 Brave Search，可设置：

```bash
export BRAVE_SEARCH_API_KEY="your-brave-search-api-key"
```

### SQL 工具

SQL 工具默认关闭。开启前请确认数据库连接、权限和表白名单配置：

```yaml
enabled: true
default_database: default
databases:
  - name: default
    active: true
    driver: sqlite
    dsn: file:data/app.db?mode=ro
    timeout: 10
    max_rows: 50
    max_cell_bytes: 4096
    schema:
      include_tables: []
      exclude_tables: []
```

## HTTP API

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| `GET` | `/` | Web 聊天页面 |
| `POST` | `/api/chat` | 流式聊天接口 |
| `GET` | `/api/openai` | 获取模型配置列表 |
| `POST` | `/api/openai/active` | 切换当前激活模型 |
| `GET` | `/api/search` | 获取搜索配置列表 |
| `POST` | `/api/search/active` | 切换当前激活搜索源 |
| `GET` | `/api/conversations` | 获取对话列表 |
| `POST` | `/api/conversations` | 创建新对话 |
| `GET` | `/api/conversations/:id` | 获取指定对话 |
| `DELETE` | `/api/conversations/:id` | 删除指定对话 |

## 项目结构

```text
.
├── main.go              # 应用入口
├── config.yaml          # 本地配置文件（已忽略）
├── config/              # 配置加载、默认值和规范化
├── server/              # HTTP 服务、路由和处理器
├── llm/                 # LLM 客户端与模型状态管理
├── message/             # 消息结构和格式转换
├── stream/              # SSE、流式响应、Token 统计
├── contextwindow/       # 上下文窗口管理
├── conversation/        # 对话历史存储
├── agenttool/           # 工具注册与加载框架
├── toolmanager/         # 工具管理器
├── toolrouter/          # 工具路由和调用循环
├── agents/              # 内置工具实现与配置
│   ├── search/
│   ├── calculator/
│   ├── time/
│   └── sql/
└── templates/           # 前端页面模板
```

## 添加新工具

1. 在 `agents/<tool-name>/` 下新增工具实现和 `config.yaml`。
2. 在工具配置中提供 `enabled` 和 `activation_prompt`，说明工具适用场景。
3. 使用 `agenttool` 注册工具，确保工具管理器能加载到该工具。
4. 根据需要补充测试用例。
5. 运行：

```bash
go test ./...
```

## 常见问题

### 配置文件不存在怎么办？

程序启动时会自动创建默认 `config.yaml`。你只需要补充模型名称和 API Key。

### 如何避免提交密钥？

`config.yaml` 已被 `.gitignore` 忽略。推荐使用环境变量：

```bash
export ARK_API_KEY="your-ark-api-key"
```

### 为什么工具没有被调用？

请检查：

1. `tool_router.enabled` 是否为 `true`。
2. 对应 `agents/<tool>/config.yaml` 中 `enabled` 是否为 `true`。
3. 用户问题是否符合该工具的 `activation_prompt`。
4. 工具路由模型配置 `tool_router.openai_name` 是否存在且可用。

### 对话记录保存在哪里？

默认保存在本地 `conversations/` 目录。该目录已被 `.gitignore` 忽略。

## License

请根据项目实际情况补充许可证信息。