250 lines
5.2 KiB
Markdown
250 lines
5.2 KiB
Markdown
# QQ Bot for Agents
|
||
|
||
通过 QQ 群调用 Agents 系统的桥接程序。
|
||
|
||
## 功能特性
|
||
|
||
- ✅ 支持通过 @ 机器人触发对话
|
||
- ✅ 支持创建/切换/查看对话
|
||
- ✅ 支持停止运行中的任务
|
||
- ✅ 实时推送工具调用信息和模型输出
|
||
- ✅ 支持发送工作区文件到 QQ 群（图片/普通文件）
|
||
|
||
## 系统要求
|
||
|
||
- Python 3.9+
|
||
- NapCat（已配置 HTTP Server）
|
||
- Agents 系统（Web 模式运行）
|
||
- aiohttp 库
|
||
|
||
## 安装依赖
|
||
|
||
```bash
|
||
pip install aiohttp
|
||
```
|
||
|
||
## 配置
|
||
|
||
### 1. NapCat 配置
|
||
|
||
确保 NapCat 已启用 HTTP Server，配置文件示例：
|
||
|
||
```json
|
||
{
|
||
"network": {
|
||
"httpServers": [
|
||
{
|
||
"name": "HttpServer",
|
||
"enable": true,
|
||
"host": "0.0.0.0",
|
||
"port": 3000,
|
||
"token": "your-token-here",
|
||
"messagePostFormat": "array"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2. Agents 系统配置
|
||
|
||
确保 Agents Web 服务器正在运行：
|
||
|
||
```bash
|
||
cd /Users/jojo/Desktop/agents/正在修复中/agents
|
||
python web_server.py --port 8091
|
||
```
|
||
|
||
确保已创建 qqbot 用户：
|
||
- 用户名: qqbot
|
||
- 邮箱: qqbot@qq.com
|
||
- 密码: 12345678
|
||
|
||
### 3. 环境变量（可选）
|
||
|
||
可以通过环境变量覆盖默认配置：
|
||
|
||
```bash
|
||
export NAPCAT_HOST="http://localhost:3000"
|
||
export NAPCAT_TOKEN="your-token"
|
||
export AGENTS_HOST="http://localhost:8091"
|
||
export AGENTS_EMAIL="qqbot@qq.com"
|
||
export AGENTS_PASSWORD="12345678"
|
||
export TARGET_GROUP_ID="1092770403"
|
||
export LOG_LEVEL="INFO"
|
||
```
|
||
|
||
## 运行
|
||
|
||
```bash
|
||
cd /Users/jojo/Desktop/agents/正在修复中/agents
|
||
python -m scripts.qq_bot.main
|
||
```
|
||
|
||
或者：
|
||
|
||
```bash
|
||
cd /Users/jojo/Desktop/agents/正在修复中/agents/scripts/qq_bot
|
||
python main.py
|
||
```
|
||
|
||
## 使用方法
|
||
|
||
### 基本指令
|
||
|
||
在 QQ 群中 @ 机器人并发送以下指令：
|
||
|
||
#### 创建新对话
|
||
```
|
||
@机器人 /new
|
||
```
|
||
|
||
#### 查看最近对话
|
||
```
|
||
@机器人 /resume 10
|
||
```
|
||
获取最近 10 条对话的标题和 ID。
|
||
|
||
#### 切换对话
|
||
```
|
||
@机器人 /switch conv_20260315_162256_599
|
||
```
|
||
|
||
#### 停止当前任务
|
||
```
|
||
@机器人 /stop
|
||
```
|
||
只能在任务运行期间使用。
|
||
|
||
### 发送消息
|
||
|
||
直接 @ 机器人并发送消息：
|
||
|
||
```
|
||
@机器人 英伟达今天的股票价格是多少？
|
||
```
|
||
|
||
如果没有当前对话，会自动创建一个新对话。
|
||
|
||
### 发送文件
|
||
|
||
模型可以使用 `send_qq_file` 工具发送工作区内的文件：
|
||
|
||
```
|
||
@机器人 生成一张图表并发送给我
|
||
```
|
||
|
||
模型会调用工具生成图表，然后使用 `send_qq_file` 工具将图片发送到群里。
|
||
|
||
## 消息格式
|
||
|
||
### 工具调用
|
||
|
||
当模型调用工具时，会发送格式化的工具信息：
|
||
|
||
```
|
||
[工具] run_command
|
||
参数: ls -la
|
||
|
||
[工具] web_search
|
||
参数: 英伟达2026年3月15日股价
|
||
```
|
||
|
||
### 模型输出
|
||
|
||
模型的文本输出会直接发送到群里，不包含思考过程和工具结果。
|
||
|
||
## 架构说明
|
||
|
||
```
|
||
scripts/qq_bot/
|
||
├── __init__.py # 包初始化
|
||
├── main.py # 主程序入口
|
||
├── config.py # 配置管理
|
||
├── napcat_client.py # NapCat API 客户端
|
||
├── web_api_client.py # Agents Web API 客户端
|
||
├── message_handler.py # 消息处理器
|
||
├── state_manager.py # 状态管理
|
||
├── poller.py # HTTP 轮询器
|
||
└── README.md # 本文档
|
||
```
|
||
|
||
### 工作流程
|
||
|
||
1. **消息接收**: HTTP 轮询器定期获取群消息
|
||
2. **消息解析**: 检测 @ 机器人的消息，解析指令或普通消息
|
||
3. **任务创建**: 通过 Web API 发送消息到 Agents 系统
|
||
4. **事件轮询**: 轮询任务状态，获取工具调用和模型输出
|
||
5. **消息推送**: 将工具调用和模型输出发送到 QQ 群
|
||
|
||
## 自定义工具
|
||
|
||
### send_qq_file
|
||
|
||
位置：`data/custom_tools/send_qq_file/`
|
||
|
||
功能：发送工作区内的文件到 QQ 群
|
||
|
||
参数：
|
||
- `file_path`: 文件相对路径（必填）
|
||
- `description`: 文件描述（可选）
|
||
|
||
示例：
|
||
```python
|
||
# 模型会这样调用
|
||
send_qq_file(file_path="output/chart.png", description="这是生成的图表")
|
||
```
|
||
|
||
## 注意事项
|
||
|
||
1. **单群模式**: 当前只支持一个群（TARGET_GROUP_ID）
|
||
2. **任务互斥**: 同一时间只能运行一个任务
|
||
3. **Docker 隔离**: qqbot 用户必须使用 Docker 模式，不能使用 host 模式
|
||
4. **文件路径**: send_qq_file 工具只能访问工作区内的文件
|
||
5. **消息轮询**: 使用 HTTP 轮询方式获取消息，可能有 1-2 秒延迟
|
||
|
||
## 故障排查
|
||
|
||
### 机器人无响应
|
||
|
||
1. 检查 NapCat 是否正常运行
|
||
2. 检查 Agents Web 服务器是否运行
|
||
3. 检查日志文件 `qq_bot.log`
|
||
4. 确认机器人 QQ 号是否正确
|
||
|
||
### 登录失败
|
||
|
||
1. 确认 qqbot 用户已创建
|
||
2. 检查邮箱和密码是否正确
|
||
3. 查看 Agents 日志确认登录请求
|
||
|
||
### 文件发送失败
|
||
|
||
1. 确认文件路径正确（相对于工作区）
|
||
2. 检查文件是否存在
|
||
3. 确认 NapCat 支持该文件类型
|
||
4. 查看日志了解详细错误信息
|
||
|
||
## 开发
|
||
|
||
### 添加新指令
|
||
|
||
在 `message_handler.py` 的 `_handle_command` 方法中添加新的指令处理：
|
||
|
||
```python
|
||
elif cmd == "/your_command":
|
||
await self._cmd_your_command(args)
|
||
```
|
||
|
||
### 修改消息格式
|
||
|
||
在 `message_handler.py` 的 `_handle_tool_start` 和 `_handle_text_end` 方法中修改。
|
||
|
||
### 调整轮询间隔
|
||
|
||
修改 `config.py` 中的 `POLL_INTERVAL` 变量。
|
||
|
||
## 许可证
|
||
|
||
与 Agents 项目保持一致。
|