# AI Chat bot

**Repository Path**: orange_cat_studio/ai-chat-bot

## Basic Information

- **Project Name**: AI Chat bot
- **Description**: 这是一个由python+AI大模型调用实现的聊天机器人，支持本地和qq bot两种工作模式，如需要qq bot需要正确安装并配置协议端Napcat
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-05
- **Last Updated**: 2026-05-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AI Caller

一个基于火山引擎 Ark API 的 AI 对话工具，支持**本地终端模式**和 **QQ 机器人模式**，具备图片搜索、音乐搜索、视频搜索、天气查询、对话历史管理等功能。
当前版本 v0.2.0

## 功能特性

- **AI 对话** — 基于火山引擎 Ark API（豆包模型）的流式对话
- **双模式运行** — 本地终端交互 + QQ 机器人（基于 NoneBot2 + OneBot V11）
- **图片搜索** — 通过 Bing 搜索图片，支持命令模式和 AI 自动调用
- **音乐搜索** — 搜索网易云音乐，支持命令模式和 AI 自动调用
- **视频搜索** — 搜索 Bilibili 视频，支持命令模式和 AI 自动调用
- **天气查询** — 查询全国主要城市的实时天气和未来预报，支持命令模式和 AI 自动调用
- **推理模式** — 支持查看模型的推理过程（reasoning_content）
- **对话管理** — 历史记录保存/加载、自动截断、手动压缩、话题存档
- **Token 管理** — 本地估算 + 远程精确查询 token 消耗
- **长消息处理** — 自动分段或合并转发发送长消息
- **Function Calling** — AI 可自动调用图片搜索、音乐搜索、视频搜索和天气查询工具

## 项目结构

```
├── main.py                 # 本地终端模式入口
├── bot.py                  # QQ 机器人模式入口
├── config.py               # 配置文件（API Key、模型、参数等）
├── config.py.template      # 配置模板文件
├── request_ai.py           # AI API 请求封装（普通/流式/Function Calling）
├── history.py              # 对话历史管理（保存/加载/清除/存档）
├── tools/
│   ├── __init__.py
│   ├── image_search.py     # 图片搜索模块（Bing 爬取）
│   ├── music_search.py     # 音乐搜索模块（网易云音乐 API）
│   ├── video_search.py     # 视频搜索模块（Bilibili API）
│   ├── weather.py          # 天气查询模块（sojson API）
│   └── tool_list.py        # 工具列表（用于 Function Calling）
├── plugins/
│   ├── __init__.py
│   └── ai_chat.py          # QQ 机器人消息处理插件（含统一命令框架）
├── sessions/               # QQ 会话存储目录
├── archives/               # 对话存档目录
├── .env                    # NoneBot 运行配置
├── .env.example            # NoneBot 配置模板
└── .gitignore
```

## 快速开始

### 环境要求

- Python 3.10+
- 火山引擎 Ark API Key
- 操作系统：本人使用的是Windows11，其他操作系统未测试
- qq协议端：NapCat(需要在浏览器中配置websocket代理地址，见下方配置)、Lagrange等

### 安装依赖

```bash
pip install requests nonebot2 nonebot-adapter-onebot
``` 

### 配置 AI Caller

1. 复制配置模板并填写 API Key：

```bash
cp config.py.template config.py
```

2. 编辑 `config.py`，填入你的 API Key：

```python
KEY = "ark-你的API Key"
```

3. （可选）配置 QQ 机器人，创建 `.env` 文件：

```
DRIVER=~fastapi
HOST=0.0.0.0
PORT=8080
```
使用websocket反向代理，将 QQ 机器人端口映射到本地终端端口。
协议端使用NapCat,需要在浏览器中配置websocket代理地址为 ws://localhost:8080/onebot/v11/ws
使用浏览器访问http://127.0.0.1:6099/webui?token=<运行NapCat时shell显示的token>，即可进行NapCat的WebUI访问。

### 配置 NapCat 代理

NapCat 终端界面截图
![alt text](image-2.png)，图中红框为NapCat的token，需要在浏览器登录时输入才能进入NapCat的WebUI
NapCat WebUI-网络配置页面
![alt text](image.png)
NapCat WebUI-网络配置页面-代理配置
创建一个WebSocket代理，配置如下：
- 使用WebSocket客户端连接（注意是不是服务端）
- 代理地址： ws://localhost:8080/onebot/v11/ws
- 代理端口： 8080
![alt text](image-1.png)

### 运行

#### 本地终端模式

```bash
python main.py
```

输入 `/help` 查看所有可用命令。

#### QQ 机器人模式

有两种启动方式：

**方式一：在本地终端中启动**

```bash
# 先启动协议端（如 NapCat、Lagrange），再运行：
python bot.py
```

**方式二：通过本地模式的 /bot 命令启动**

```bash
python main.py
# 然后在交互界面输入：
/bot
```

## 使用指南

### 本地模式命令

| 命令 | 说明 |
|------|------|
| `/help` | 显示帮助信息 |
| `/clear` | 清除对话历史 |
| `/think` | 切换推理模式（显示 AI 思考过程） |
| `/prompt <内容>` | 设置系统提示词 |
| `/history` | 显示对话历史条数 |
| `/token` | 本地估算 token 消耗 |
| `/remote_token` | 获取远程 API 精确 token 消耗 |
| `/models` | 查看当前模型信息 |
| `/trim <数量>` | 保留最近 N 轮对话 |
| `/compress` | 将早期对话压缩为摘要 |
| `/new` | 存档当前对话并开启新话题 |
| `/max_history [数量]` | 查看或设置最大历史记录数 |
| `/save` | 切换自动保存 |
| `/image <关键词>` | 搜索图片 |
| `/music <关键词> [数量]` | 搜索音乐（默认10条，最多20条） |
| `/video <关键词> [数量]` | 搜索视频（默认10条，最多20条） |
| `/weather <城市名>` | 查询天气 |
| `/bot` | 启动 QQ 机器人 |
| `/bot stop` | 停止 QQ 机器人 |

### QQ 机器人命令

在 QQ 中 @机器人 后发送以下命令：

| 命令 | 说明 |
|------|------|
| `/help` | 显示帮助信息 |
| `/clear` | 清除当前群/用户的对话历史 |
| `/think` | 切换推理模式 |
| `/prompt <内容>` | 设置系统提示词 |
| `/history` | 显示对话历史条数 |
| `/token` | 本地估算 token 消耗 |
| `/remote_token` | 获取远程 API 精确 token 消耗 |
| `/models` | 查看当前模型信息 |
| `/trim <数量>` | 保留最近 N 轮对话 |
| `/compress` | 将早期对话压缩为摘要 |
| `/new` | 存档当前对话并开启新话题 |
| `/max_history [数量]` | 查看或设置最大历史记录数 |
| `/save` | 切换自动保存 |
| `/image <关键词>` | 搜索图片并发送 |
| `/music <关键词> [数量]` | 搜索音乐（默认10条，最多20条） |
| `/video <关键词> [数量]` | 搜索视频（默认10条，最多20条） |
| `/weather <城市名>` | 查询天气 |

### AI 自动调用

当用户发送自然语言时，AI 会自动判断是否需要调用以下工具：

- **图片搜索** — 如"帮我找几张风景图"
- **音乐搜索** — 如"帮我找周杰伦的歌"
- **视频搜索** — 如"帮我找Python教程视频"
- **天气查询** — 如"今天北京天气怎么样"

## 配置说明

### config.py

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `KEY` | 火山引擎 Ark API Key | 需自行填写 |
| `URL` | API 请求地址 | 火山引擎 Ark 地址 |
| `MODEL` | 模型 ID | doubao-seed-2-0-lite-260215 |
| `SYSTEM_PROMPT` | 默认系统提示词 | 空 |
| `MAX_COMPRESS_NUM` | 压缩触发的最小对话轮数 | 25 |
| `MAX_HISTORY_NUM` | 历史记录最大条数 | 50 |
| `MAX_MESSAGE_LENGTH` | 单条消息最大字符数 | 600 |
| `MAX_SPLIT_PARTS` | 长消息最多分多少段 | 10 |

### 支持的模型

本项目使用火山引擎 Ark API，支持豆包系列模型。可在 [火山引擎官方文档](https://www.volcengine.com/docs/82379/1330310) 查看完整模型列表，在 `config.py` 中修改 `MODEL` 即可切换。

## QQ 机器人架构

```
用户 → QQ → NapCat/Lagrange(协议端) → OneBot V11(WebSocket) → NoneBot2(框架) → AI(火山引擎API)
```

- **协议端**：NapCat 或 Lagrange，负责与 QQ 服务器通信
- **框架层**：NoneBot2，处理消息路由和事件分发
- **业务层**：自定义插件，处理 AI 对话、图片搜索、音乐搜索、视频搜索、天气查询等

每个群/用户拥有独立的对话历史和系统提示词，互不干扰。

## 数据存储

- **历史记录**：默认保存在 `history.json`，QQ 模式下按用户/群隔离存储于 `sessions/` 目录
- **自动保存**：默认关闭，可通过 `/save` 命令开启
- **话题存档**：使用 `/new` 命令可将当前对话存档至 `archives/` 目录
- **历史截断**：超过 `MAX_HISTORY_NUM` 条消息时自动截断最早的消息
- **对话压缩**：使用 `/compress` 命令可将早期对话用 AI 总结为摘要
- **长消息处理**：超过 `MAX_MESSAGE_LENGTH` 的消息自动分段或合并转发

## 长消息处理机制

当 AI 返回长消息时，系统会自动处理：

1. **判断长度**：如果消息超过 `MAX_MESSAGE_LENGTH`（默认600字符），进行分段
2. **尝试合并转发**：尝试使用 QQ 合并转发功能发送
3. **降级处理**：如果合并转发失败（协议端不支持），自动降级为分段发送
4. **分段格式**：每段带有序号标识，如【1/3】、【2/3】、【3/3】

## 命令框架

项目使用统一的命令注册框架，新增命令只需：

```python
@register_command("news", description="新闻", default_count=5)
async def handle_news(query, count, event):
    # 实现新闻搜索逻辑
    results = search_news(query, count=count)
    if results:
        return {"type": "text", "content": formatted_results}
    return None
```

## 注意事项

- API Key 请妥善保管，不要提交到版本控制
- 图片搜索通过爬取 Bing 实现，请合理使用
- 音乐搜索使用网易云音乐 API，请合理使用
- 视频搜索使用 Bilibili API，请合理使用
- 天气查询使用 sojson 免费 API，无需 Key
- QQ 机器人需要配合协议端（NapCat/Lagrange）使用
- 合并转发功能依赖协议端支持，部分协议端可能不支持

# 联系方式

qq: 1048924953
e-mail: 1048924953@qq.com

如有任何问题或建议，欢迎联系我，也可以在项目仓库issue中提交。