QQ 连接

QQ 连接工具实现了 AI 与 QQ 群的实时通信。通过 OneBot 协议，AI 可以发送消息到 QQ 群，也可以查询群信息。这让游戏外部的玩家可以通过 QQ 与 AI 互动。

工具列表

工具	功能	参数	返回值
`qq_send`	发送 QQ 消息	`type`, `target_id`, `content`(可选)	发送结果
`qq_info`	查询 QQ 信息	`type`, `target_id`	查询结果

工具详解

qq_send — 发送 QQ 消息

向 QQ 群或好友发送消息，支持文本消息、表情和贴图。

{
  "tool": "qq_send",
  "params": {
    "type": "group",
    "target_id": "123456789",
    "content": "矿洞挖完了，收获了 32 个铁矿石！"
  }
}

支持的消息类型：

文本消息 — 普通文字内容
表情（face）— 通过 faceId 指定 QQ 表情
贴图（sticker）— 通过 stickerId 发送贴图

qq_info — 查询信息

查询 QQ 群信息或群成员列表，帮助 AI 了解群聊环境和目标受众。

{
  "tool": "qq_info",
  "params": {
    "type": "group_info",
    "target_id": "123456789"
  }
}

架构说明

QQ 连接基于 NapCat + OneBot 协议实现：

QQ 用户 → QQ 群
    │
    ▼
NapCat (QQ 机器人框架)
    │ OneBot 协议
    ▼
Agent Core → QQ Agent (子 Agent)
    │ 工具注册表
    ▼
qq_send / qq_info 工具

QQ 消息的处理由独立的 QQ Sub-Agent 完成：

收到 QQ 消息 → QQ Sub-Agent 处理后回复
如需游戏内操作 → 通过 request_game_action 转发给主 Agent
主 Agent 的结果 → 通过 notify_qq 工具推送回 QQ 群

典型场景

远程查询游戏状态：

用户在 QQ 群: "@Alice 你的位置在哪里？"

QQ Agent 收到消息:
1. request_game_action(description: "用户想知道我在游戏中的位置")
   → 转发给主 Agent
2. 主 Agent 调用 query_location()
   → 获得坐标信息
3. notify_qq → 回复到 QQ 群
   "我现在在 (-100, 64, 200) 的矿洞里，正在挖铁矿石"

定时推送：

AI 自动:
→ qq_send("group", "群号", "全物品备货已完成！")

错误处理

场景	错误码	说明
目标群/好友不存在	`NOT_FOUND`	QQ 号或群号无效
消息发送失败	`SEND_FAILED`	网络错误或被风控
权限不足	`NO_PERMISSION`	机器人无发送权限

Perception Social