186 lines
3.5 KiB
Markdown
186 lines
3.5 KiB
Markdown
# 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` 的结构。
|