JOJO/agent-Specialization

Fork 0

JOJO 5f6622a212 chore: add docs and remove sub_agent

2026-03-17 22:46:43 +08:00

5.2 KiB

Raw Permalink Blame History

QQ Bot for Agents

通过 QQ 群调用 Agents 系统的桥接程序。

功能特性

✅ 支持通过 @ 机器人触发对话
✅ 支持创建/切换/查看对话
✅ 支持停止运行中的任务
✅ 实时推送工具调用信息和模型输出
✅ 支持发送工作区文件到 QQ 群（图片/普通文件）

系统要求

Python 3.9+
NapCat（已配置 HTTP Server）
Agents 系统（Web 模式运行）
aiohttp 库

安装依赖

pip install aiohttp

配置

1. NapCat 配置

确保 NapCat 已启用 HTTP Server，配置文件示例：

{
  "network": {
    "httpServers": [
      {
        "name": "HttpServer",
        "enable": true,
        "host": "0.0.0.0",
        "port": 3000,
        "token": "your-token-here",
        "messagePostFormat": "array"
      }
    ]
  }
}

2. Agents 系统配置

确保 Agents Web 服务器正在运行：

cd /Users/jojo/Desktop/agents/正在修复中/agents
python web_server.py --port 8091

确保已创建 qqbot 用户：

用户名: qqbot
邮箱: qqbot@qq.com
密码: 12345678

3. 环境变量（可选）

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

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"

运行

cd /Users/jojo/Desktop/agents/正在修复中/agents
python -m scripts.qq_bot.main

或者：

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            # 本文档

工作流程

消息接收: HTTP 轮询器定期获取群消息
消息解析: 检测 @ 机器人的消息，解析指令或普通消息
任务创建: 通过 Web API 发送消息到 Agents 系统
事件轮询: 轮询任务状态，获取工具调用和模型输出
消息推送: 将工具调用和模型输出发送到 QQ 群

自定义工具

send_qq_file

位置：data/custom_tools/send_qq_file/

功能：发送工作区内的文件到 QQ 群

参数：

file_path: 文件相对路径（必填）
description: 文件描述（可选）

示例：

# 模型会这样调用
send_qq_file(file_path="output/chart.png", description="这是生成的图表")

注意事项

单群模式: 当前只支持一个群（TARGET_GROUP_ID）
任务互斥: 同一时间只能运行一个任务
Docker 隔离: qqbot 用户必须使用 Docker 模式，不能使用 host 模式
文件路径: send_qq_file 工具只能访问工作区内的文件
消息轮询: 使用 HTTP 轮询方式获取消息，可能有 1-2 秒延迟

故障排查

机器人无响应

检查 NapCat 是否正常运行
检查 Agents Web 服务器是否运行
检查日志文件 qq_bot.log
确认机器人 QQ 号是否正确

登录失败

确认 qqbot 用户已创建
检查邮箱和密码是否正确
查看 Agents 日志确认登录请求

文件发送失败

确认文件路径正确（相对于工作区）
检查文件是否存在
确认 NapCat 支持该文件类型
查看日志了解详细错误信息

开发

添加新指令

在 message_handler.py 的 _handle_command 方法中添加新的指令处理：

elif cmd == "/your_command":
    await self._cmd_your_command(args)

修改消息格式

在 message_handler.py 的 _handle_tool_start 和 _handle_text_end 方法中修改。

调整轮询间隔

修改 config.py 中的 POLL_INTERVAL 变量。

许可证

与 Agents 项目保持一致。

5.2 KiB Raw Permalink Blame History Unescape Escape