aichat/README.md

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. 克隆项目

git clone <your-repo-url>
cd aichat

2. 安装依赖

go mod download

3. 准备配置

首次运行时，程序会自动生成 config.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 写入仓库：

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

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

4. 启动服务

go run main.go

启动后访问：

http://localhost:8080

构建与测试

# 构建二进制
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 只读连接

搜索工具

默认配置：

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

如果使用 Brave Search，可设置：

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

SQL 工具

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

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	删除指定对话

项目结构

.
├── 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. 运行：

go test ./...

常见问题

配置文件不存在怎么办？

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

如何避免提交密钥？

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

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

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