agent-Specialization/scripts/qq_bot/DEPLOY.md

QQ Bot 部署指南

快速开始

1. 安装依赖

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

2. 测试连接

python scripts/qq_bot/test_connection.py

这会测试：

• NapCat API 连接
• Agents Web API 连接
• 创建对话功能

3. 启动机器人

python scripts/qq_bot/run.py

或者：

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 服务器正在运行

   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 服务器后生效

故障排查

测试失败

运行测试脚本查看详细错误：

python scripts/qq_bot/test_connection.py

查看日志

tail -f qq_bot.log

常见问题

1. NapCat 连接失败

   • 检查 NapCat 是否运行
   • 检查端口和 token 是否正确

2. Agents 登录失败

   • 检查 Web 服务器是否运行
   • 检查用户名密码是否正确
   • 确认用户已创建

3. 机器人无响应

   • 检查是否正确 @ 机器人
   • 查看日志了解详细错误

开发

添加新指令

编辑 message_handler.py：

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

修改轮询间隔

编辑 config.py：

POLL_INTERVAL = 2.0  # 秒

添加新的自定义工具

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