Skip to content

QQ 官方机器人协作 ​

「官方机器人协作」是 UniQQ 综合插件上的一种双机器人协同模式:由 QQ 官方机器人负责前台收发与回复,综合插件负责业务判断,UniQQ 插件机器人负责后台执行强动作;本页介绍模式说明、身份映射与部署要点。

✨ 简介 ​

QQ 官方机器人经由腾讯开放平台接入,形象规范、消息由官方通道收发,但存在能力边界(例如不便稳定执行禁言、踢人等强管理动作,且只能看到 openid 形式的标识)。「官方机器人协作」模式正是为结合双方优势而设计:

text
官方机器人 = 前台交互机器人
综合插件   = 业务大脑
插件机器人 = 后台执行机器人

用户在群里看到的回复、菜单、验证提示与处理结果,优先由官方机器人发出;踢人、禁言、撤回、改名片等官方机器人不能稳定完成的强执行动作,由 UniQQ 插件机器人执行。

与原插件的关系

「官方机器人协作」是新增功能,不是对原综合插件的改动。协作模式由总开关控制:关闭时,综合插件按原有 UniQQ 插件方式独立运行,原有收发消息与业务逻辑完全不变;开启后才启用双机器人协同逻辑。

🔄 工作模式 ​

开关规则 ​

开关状态行为
关闭官方机器人协作综合插件按原 UniQQ 框架插件方式运行,不依赖官方机器人,不影响已有用户与已有群
开启官方机器人协作官方机器人负责收消息、回复消息、发送提示;综合插件负责业务判断;插件机器人负责执行落地动作

职责分工 ​

动作 / 功能执行通道说明
普通回复、菜单、问答、AI 回复官方机器人用户可见的回复优先由官方机器人发出
群通知、提示语官方机器人优先,失败由插件机器人补发—
入群验证提示官方机器人验证码提示、校验结果提示
禁言 / 解除禁言插件机器人需机器人具备群管理员权限
踢人插件机器人需机器人具备群管理员权限
撤回消息插件机器人优先—
修改群名片插件机器人—
黑名单 / 白名单综合插件内部写入插件自身的黑白名单体系

消息发送与容灾 ​

  • 消息发送采用官方优先、失败补发策略:开启协作后由官方机器人优先发送;官方发送失败、不在线或无权限时,若开启了补发开关,则由插件机器人自动补发。
  • 官方机器人断线或异常时,收消息可由插件机器人临时接管,发消息由插件机器人补发;官方恢复后自动切回官方优先。
  • 为避免双机器人重复回复,内置去重机制:同一群 + 同一用户 + 同一内容 + 2 秒窗口内的重复事件只处理一次。

🗺️ 身份映射 ​

官方机器人与插件机器人看到的身份体系不同:

侧群标识用户标识
官方机器人group_openidmember_openid
插件机器人(UniQQ 框架)真实 QQ 群号真实用户 QQ 号

协作模式通过身份映射中心将两侧身份统一:

  • 每个群与用户对应系统内部的统一 ID,权限、白名单、黑名单、验证状态、处罚记录均绑定到统一用户 ID。
  • 自动绑定:插件机器人检测到真实群号与 QQ 号后先建立待定记录,官方机器人侧收到对应事件后按群、时间、昵称、事件顺序自动匹配绑定。
  • 手动绑定:无法自动匹配时,控制台显示「待绑定用户」,管理员可手动完成绑定。
  • 主动绑定:用户也可通过「绑定QQ」指令主动绑定身份。

📦 部署要点 ​

前置条件 ​

官方机器人侧(腾讯开放平台):

  • 机器人凭证:AppID 与 AppSecret
  • 环境选择:沙箱 / 正式
  • WebSocket 事件订阅
  • 权限:群消息、私聊消息、群成员事件

插件机器人侧(UniQQ 框架):

  • UniQQ 框架运行环境与综合插件
  • 机器人已在目标群内,并具备禁言、踢人、撤回等所需的管理员权限

控制台配置 ​

在综合插件控制台的「官方机器人协作」设置区完成以下配置:

配置项说明
启用官方机器人协作总开关,关闭后完全走原插件逻辑
官方 AppID / AppSecret开放平台机器人凭证;AppSecret 需加密或本地安全保存
环境沙箱 / 正式
官方机器人优先回复开启后群回复优先由官方机器人发送
官方失败插件补发官方机器人发送失败时由插件机器人自动补发
插件机器人执行动作开启后禁言、踢人、撤回等动作交给插件机器人执行
身份映射策略自动匹配 / 手动绑定 / 混合模式
群映射管理绑定 group_openid 与真实 QQ 群号
用户映射管理绑定 member_openid 与真实 QQ 号

安全注意 ​

  • 不要把 AppSecret 明文写入日志,也不要写入导出的公开配置。
  • 协作运行产生的配置、身份映射、通道状态与动作记录均保存在本地数据文件中,请妥善保管,勿随程序分发包外泄。

部署自检 ​

  1. 保存配置后,确认控制台中官方机器人连接状态与插件机器人状态均正常。
  2. 发送一条菜单指令,确认回复由官方机器人发出。
  3. 测试一次入群验证或违禁词场景,确认提示由官方机器人发送、强执行动作由插件机器人落地。
  4. 在协作日志中核对收消息、业务匹配、官方发送结果与插件执行结果是否完整记录。

❓ 常见问题 ​

官方机器人拿不到真实 QQ 号或群号? 这是官方通道的固有特性(只提供 openid 标识)。依赖身份映射中心由插件机器人补全真实 QQ,群号可在控制台手动绑定 group_openid 与真实群号。

官方和插件机器人重复回复同一条消息? 确认使用的是支持去重的协作版本;去重窗口为「同一群 + 同一用户 + 同一内容 + 2 秒」。若仍出现,检查是否同时保留了旧版双开配置。

官方机器人发送失败怎么办? 开启「官方失败插件补发」后,发送失败、官方不在线或无权限时由插件机器人自动补发;发送结果会记录在发送日志中,可据此排查。

插件机器人不在线会影响什么? 官方机器人可继续回复;但禁言、踢人等强执行动作会进入等待或失败提示,建议保持插件机器人在线并具备管理员权限。

关闭协作模式后原有功能会受影响吗? 不会。关闭后综合插件回到原有独立运行方式,不依赖官方机器人,已有用户与已有群不受影响。

🆘 获取帮助 ​

  • 优先查看控制台的「官方机器人协作」设置页:其中展示协作开关、官方机器人连接状态、插件机器人状态、当前优先发送通道、失败补发开关与最近错误。
  • 结合「协作日志」排查完整链路:收到消息 → 业务匹配 → 官方发送结果 → 插件执行动作结果 → 失败补发记录。
  • 综合插件各功能(菜单、问答、入群验证、违禁词等)的详细配置与指令,参见对应插件分类的使用教程;框架相关问题参见 UniQQ 机器人框架文档。

薇薇官机平台 · ZL 系列插件