# 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 项目保持一致。