QQ 官方机器人协作
「官方机器人协作」是 UniQQ 综合插件上的一种双机器人协同模式:由 QQ 官方机器人负责前台收发与回复,综合插件负责业务判断,UniQQ 插件机器人负责后台执行强动作;本页介绍模式说明、身份映射与部署要点。
✨ 简介
QQ 官方机器人经由腾讯开放平台接入,形象规范、消息由官方通道收发,但存在能力边界(例如不便稳定执行禁言、踢人等强管理动作,且只能看到 openid 形式的标识)。「官方机器人协作」模式正是为结合双方优势而设计:
官方机器人 = 前台交互机器人
综合插件 = 业务大脑
插件机器人 = 后台执行机器人用户在群里看到的回复、菜单、验证提示与处理结果,优先由官方机器人发出;踢人、禁言、撤回、改名片等官方机器人不能稳定完成的强执行动作,由 UniQQ 插件机器人执行。
与原插件的关系
「官方机器人协作」是新增功能,不是对原综合插件的改动。协作模式由总开关控制:关闭时,综合插件按原有 UniQQ 插件方式独立运行,原有收发消息与业务逻辑完全不变;开启后才启用双机器人协同逻辑。
🔄 工作模式
开关规则
| 开关状态 | 行为 |
|---|---|
| 关闭官方机器人协作 | 综合插件按原 UniQQ 框架插件方式运行,不依赖官方机器人,不影响已有用户与已有群 |
| 开启官方机器人协作 | 官方机器人负责收消息、回复消息、发送提示;综合插件负责业务判断;插件机器人负责执行落地动作 |
职责分工
| 动作 / 功能 | 执行通道 | 说明 |
|---|---|---|
| 普通回复、菜单、问答、AI 回复 | 官方机器人 | 用户可见的回复优先由官方机器人发出 |
| 群通知、提示语 | 官方机器人优先,失败由插件机器人补发 | — |
| 入群验证提示 | 官方机器人 | 验证码提示、校验结果提示 |
| 禁言 / 解除禁言 | 插件机器人 | 需机器人具备群管理员权限 |
| 踢人 | 插件机器人 | 需机器人具备群管理员权限 |
| 撤回消息 | 插件机器人优先 | — |
| 修改群名片 | 插件机器人 | — |
| 黑名单 / 白名单 | 综合插件内部 | 写入插件自身的黑白名单体系 |
消息发送与容灾
- 消息发送采用官方优先、失败补发策略:开启协作后由官方机器人优先发送;官方发送失败、不在线或无权限时,若开启了补发开关,则由插件机器人自动补发。
- 官方机器人断线或异常时,收消息可由插件机器人临时接管,发消息由插件机器人补发;官方恢复后自动切回官方优先。
- 为避免双机器人重复回复,内置去重机制:同一群 + 同一用户 + 同一内容 + 2 秒窗口内的重复事件只处理一次。
🗺️ 身份映射
官方机器人与插件机器人看到的身份体系不同:
| 侧 | 群标识 | 用户标识 |
|---|---|---|
| 官方机器人 | group_openid | member_openid |
| 插件机器人(UniQQ 框架) | 真实 QQ 群号 | 真实用户 QQ 号 |
协作模式通过身份映射中心将两侧身份统一:
- 每个群与用户对应系统内部的统一 ID,权限、白名单、黑名单、验证状态、处罚记录均绑定到统一用户 ID。
- 自动绑定:插件机器人检测到真实群号与 QQ 号后先建立待定记录,官方机器人侧收到对应事件后按群、时间、昵称、事件顺序自动匹配绑定。
- 手动绑定:无法自动匹配时,控制台显示「待绑定用户」,管理员可手动完成绑定。
- 主动绑定:用户也可通过「绑定QQ」指令主动绑定身份。
📦 部署要点
前置条件
官方机器人侧(腾讯开放平台):
- 机器人凭证:AppID 与 AppSecret
- 环境选择:沙箱 / 正式
- WebSocket 事件订阅
- 权限:群消息、私聊消息、群成员事件
插件机器人侧(UniQQ 框架):
- UniQQ 框架运行环境与综合插件
- 机器人已在目标群内,并具备禁言、踢人、撤回等所需的管理员权限
控制台配置
在综合插件控制台的「官方机器人协作」设置区完成以下配置:
| 配置项 | 说明 |
|---|---|
| 启用官方机器人协作 | 总开关,关闭后完全走原插件逻辑 |
| 官方 AppID / AppSecret | 开放平台机器人凭证;AppSecret 需加密或本地安全保存 |
| 环境 | 沙箱 / 正式 |
| 官方机器人优先回复 | 开启后群回复优先由官方机器人发送 |
| 官方失败插件补发 | 官方机器人发送失败时由插件机器人自动补发 |
| 插件机器人执行动作 | 开启后禁言、踢人、撤回等动作交给插件机器人执行 |
| 身份映射策略 | 自动匹配 / 手动绑定 / 混合模式 |
| 群映射管理 | 绑定 group_openid 与真实 QQ 群号 |
| 用户映射管理 | 绑定 member_openid 与真实 QQ 号 |
安全注意
- 不要把 AppSecret 明文写入日志,也不要写入导出的公开配置。
- 协作运行产生的配置、身份映射、通道状态与动作记录均保存在本地数据文件中,请妥善保管,勿随程序分发包外泄。
部署自检
- 保存配置后,确认控制台中官方机器人连接状态与插件机器人状态均正常。
- 发送一条菜单指令,确认回复由官方机器人发出。
- 测试一次入群验证或违禁词场景,确认提示由官方机器人发送、强执行动作由插件机器人落地。
- 在协作日志中核对收消息、业务匹配、官方发送结果与插件执行结果是否完整记录。
❓ 常见问题
官方机器人拿不到真实 QQ 号或群号? 这是官方通道的固有特性(只提供 openid 标识)。依赖身份映射中心由插件机器人补全真实 QQ,群号可在控制台手动绑定 group_openid 与真实群号。
官方和插件机器人重复回复同一条消息? 确认使用的是支持去重的协作版本;去重窗口为「同一群 + 同一用户 + 同一内容 + 2 秒」。若仍出现,检查是否同时保留了旧版双开配置。
官方机器人发送失败怎么办? 开启「官方失败插件补发」后,发送失败、官方不在线或无权限时由插件机器人自动补发;发送结果会记录在发送日志中,可据此排查。
插件机器人不在线会影响什么? 官方机器人可继续回复;但禁言、踢人等强执行动作会进入等待或失败提示,建议保持插件机器人在线并具备管理员权限。
关闭协作模式后原有功能会受影响吗? 不会。关闭后综合插件回到原有独立运行方式,不依赖官方机器人,已有用户与已有群不受影响。
🆘 获取帮助
- 优先查看控制台的「官方机器人协作」设置页:其中展示协作开关、官方机器人连接状态、插件机器人状态、当前优先发送通道、失败补发开关与最近错误。
- 结合「协作日志」排查完整链路:收到消息 → 业务匹配 → 官方发送结果 → 插件执行动作结果 → 失败补发记录。
- 综合插件各功能(菜单、问答、入群验证、违禁词等)的详细配置与指令,参见对应插件分类的使用教程;框架相关问题参见 UniQQ 机器人框架文档。
