# QQ Bot 部署指南

## 快速开始

### 1. 安装依赖

```bash
cd /Users/jojo/Desktop/agents/正在修复中/agents
pip install aiohttp
```

### 2. 测试连接

```bash
python scripts/qq_bot/test_connection.py
```

这会测试：
- NapCat API 连接
- Agents Web API 连接
- 创建对话功能

### 3. 启动机器人

```bash
python scripts/qq_bot/run.py
```

或者：

```bash
python -m scripts.qq_bot.main
```

## 使用说明

### 在 QQ 群中使用

1. **创建新对话**
   ```
   @机器人 /new
   ```

2. **查看对话列表**
   ```
   @机器人 /resume 10
   ```

3. **切换对话**
   ```
   @机器人 /switch conv_xxx
   ```

4. **停止任务**
   ```
   @机器人 /stop
   ```

5. **发送消息**
   ```
   @机器人 帮我查一下今天的天气
   ```

### 发送文件

模型可以使用 `send_qq_file` 工具发送文件：

```
@机器人 生成一个柱状图并发送给我
```

模型会：
1. 生成图表文件
2. 调用 `send_qq_file` 工具
3. 文件自动发送到 QQ 群

## 文件结构

```
scripts/qq_bot/
├── __init__.py              # 包初始化
├── main.py                  # 主程序
├── run.py                   # 启动脚本
├── test_connection.py       # 连接测试
├── config.py                # 配置
├── napcat_client.py         # NapCat 客户端
├── web_api_client.py        # Web API 客户端
├── message_handler.py       # 消息处理
├── state_manager.py         # 状态管理
├── poller.py                # 消息轮询
├── requirements.txt         # 依赖
└── README.md                # 详细文档

data/custom_tools/send_qq_file/
├── definition.json          # 工具定义
├── execution.py             # 执行代码
└── return.json              # 返回配置
```

## 配置说明

默认配置（可通过环境变量覆盖）：

- `NAPCAT_HOST`: http://localhost:3000
- `NAPCAT_TOKEN`: 283222464f13
- `AGENTS_HOST`: http://localhost:8091
- `AGENTS_EMAIL`: qqbot@qq.com
- `AGENTS_PASSWORD`: 12345678
- `TARGET_GROUP_ID`: 1092770403

## 注意事项

1. **确保 NapCat 正在运行**
   - HTTP Server 端口：3000
   - Token 已配置

2. **确保 Agents Web 服务器正在运行**
   ```bash
   python web_server.py --port 8091
   ```

3. **确保 qqbot 用户已创建**
   - 用户名：qqbot
   - 邮箱：qqbot@qq.com
   - 密码：12345678
   - 必须使用 Docker 模式

4. **自定义工具**
   - `send_qq_file` 工具已创建在 `data/custom_tools/send_qq_file/`
   - 重启 Agents 服务器后生效

## 故障排查

### 测试失败

运行测试脚本查看详细错误：
```bash
python scripts/qq_bot/test_connection.py
```

### 查看日志

```bash
tail -f qq_bot.log
```

### 常见问题

1. **NapCat 连接失败**
   - 检查 NapCat 是否运行
   - 检查端口和 token 是否正确

2. **Agents 登录失败**
   - 检查 Web 服务器是否运行
   - 检查用户名密码是否正确
   - 确认用户已创建

3. **机器人无响应**
   - 检查是否正确 @ 机器人
   - 查看日志了解详细错误

## 开发

### 添加新指令

编辑 `message_handler.py`：

```python
async def _handle_command(self, command: str):
    # ...
    elif cmd == "/your_command":
        await self._cmd_your_command(args)
```

### 修改轮询间隔

编辑 `config.py`：

```python
POLL_INTERVAL = 2.0  # 秒
```

### 添加新的自定义工具

在 `data/custom_tools/` 下创建新文件夹，参考 `send_qq_file` 的结构。