koishi-plugin-qq-onebot-user
v0.2.0
Published
通过同群消息静默绑定 QQ 与 OneBot 用户,复用原有用户数据。
Readme
QQ 与 OneBot 用户绑定
Koishi 插件,包名为 koishi-plugin-qq-onebot-user,配置名为 qq-onebot-user,依赖 database 服务。
默认启用静默绑定:在已确认两端群对应关系的群内,QQ 官方机器人与任意 OneBot 收到同一用户的消息后,分别缓存并等待默认五秒的核验窗口结束。不存在多个可能发送者的消息才计入证据,十分钟内累计两条独立消息后自动复用 OneBot 的用户数据。重复正文和“1”“好”“菜单”等短消息都可以计数;同一条消息重复投递、多个 OneBot 收到同一条消息只算一次。自动成功、失败、过期和冲突均不发送提示。
兼容只能接收 @ 消息及能够接收全部群消息的 QQ 机器人,无需手动切换模式。只在匹配副本中统一对当前官方机器人的 @,保留对其他人的 @;不改变实际消息、前置身份替换或后续插件输入。当前自动核验处理文本和 @,图片、语音等消息暂不计入证据。自动绑定完成后,从下一条消息起使用关联身份。
QQ 的群 OpenID 与 OneBot 数字群号不同,同群核验关系单独保存在 qq_onebot_scope,不改写 session.gid 或 qq_onebot_group,也不改变问答群范围。新群可由已有绑定用户的两条双端消息自动确认;成功的手动绑定也会确认群关系。群来源尚未确认、群对应冲突或同一窗口存在多个可能发送者时,不跨群猜测绑定。如果一个新群内尚无任何已绑定用户,需要先由一位成员手动绑定一次。
消息进入队列时只保存核验副本,不进行全队列匹配;到窗口期限后,按正文和核验群索引查找候选。相关窗口仍未结束时,合并下一次核验时间,避免反复扫描。已绑定用户跳过重复累计和绑定写入,但消息仍作为歧义判断依据;确认群关系后,不需要核验群或机器人 @ 的这类消息只保留轻量记录。十分钟证据缓存只保存消息键、账号标识和时间,不保留完整会话。待核验消息上限为 2000 条,达到上限时丢弃待核验记录及索引,不提前做出绑定判断。
手动方式仍可用:在 QQ 官方机器人和任意 OneBot 都能收到消息的群中,发送一次 @QQ机器人 绑定qq 你的QQ号。所有 OneBot 账号都可提供核验消息,消息实际发送者仍须与填写的 QQ 号一致。两端消息在默认五秒内唯一匹配后,QQ 用户会关联 OneBot 原有的用户数据。手动结果只由 QQ 官方机器人回复。
QQ 侧使用 Koishi 原生指令发起绑定,直接兼容现有 command-trie 插件的省略空格功能。启用该插件时支持 绑定qq123456789;未启用时使用 绑定qq 123456789。OneBot 侧只被动核验消息,不执行指令或回复,无需运行补空格插件。已有身份替换中间件仍在普通业务及 dialogue 识别之前执行。
绑定qq <QQ号>:绑定用户。绑定状态:查看当前绑定。解绑qq:恢复 QQ 原有的用户关联,并清空旧的自动核验证据及待提交请求;随后新消息仍可重新积累证据。
配置项:
autoBind:是否启用静默绑定,默认true。timeout:单条消息匹配窗口,单位毫秒,默认5000;自动核验等待相关窗口全部结束,手动绑定仍在唯一匹配时立即完成。evidenceCount:自动确认用户或核验群关系需要的消息数,默认2,最少2。evidenceWindow:证据累计有效期,单位毫秒,默认600000(十分钟)。mapGroups:是否关联群问答范围,默认false。
在 Koishi 控制台启用 qq-onebot-user。问答群范围映射默认关闭;已核验的同群关系仍可供统一受理和订阅推送使用。
前置中间件只按当前机器人和原始 OpenID 精确查询绑定;没有匹配时保留原平台身份,已映射会话不重复包装。不反查数字发送者,也不特殊处理 bot.session()。dialogue 创建子会话时通用地保留原执行上下文,无需读取绑定字段或重新执行身份转换;未安装本插件时,自定义 uid 和其他插件状态也能保留。
入口和手动队列为 index.cjs、queue.cjs,自动证据队列为 silent.cjs,内容比较为 content.cjs,身份替换为 session.cjs,无需编译。普通消息关联属于推断,歧义排除不能识别所有两端漏报造成的错误唯一候选。
维护项目的隔离测试位于根目录 tests:qq-onebot-silent.cjs 验证自动证据、重复消息、歧义、核验群、两种权限模式和解绑后重绑;qq-onebot-user.cjs 验证手动绑定;qq-onebot-package.cjs 验证插件包与控制台识别。测试文件不随 npm 包分发。
原生频道群关系
已确认的同群关系会同步到 QQ 原生 channel.onebotChannelId 列,供 assignee-switch 和 subscription 读取。旧核验关系启动时补写;QQ 退群后清除此关联。此字段与 mapGroups 控制的问答群范围映射相互独立。
手动绑定返回消息
以下为当前关闭群映射时的绑定返回,{QQ号} 替换成实际号码,超时默认五秒。所有提示由 QQ 侧发送。
| 条件 | 返回文本 | | --- | --- | | 成功,或重新核验同一个已绑定账号 | 已绑定 QQ {QQ号},开始复用原有用户数据。 | | 五秒内未匹配到 OneBot;填写的号码不是本人时也会走此结果 | 绑定失败:5 秒内未收到对应的 OneBot 消息,请确认两端在线后重试。 | | 当前队列出现不同用户/群的歧义候选 | 绑定失败:存在多条无法唯一匹配的消息,请稍后重新发送。 | | QQ 消息到达时已经超过匹配有效时间 | 绑定失败:这条消息已过期,请重新发送。 | | QQ 账号已经绑定其他号码 | 绑定失败:此账号已绑定其他 QQ 号,请先发送“解绑qq”。 | | 已有其他原生数据绑定 | 绑定失败:此账号已有其他数据绑定,请先解除原有绑定。 | | 绑定被其他插件改动 | 绑定失败:原有绑定已被其他插件修改,请先解除原有绑定。 | | 数字 QQ 兼容别名冲突 | 绑定失败:该 QQ 号的兼容身份已关联其他用户,请联系管理员检查。 | | OneBot 的绑定指向缺失用户行 | 绑定失败:OneBot 用户数据不存在,请检查原有绑定。 | | 解绑恰好取消了正在排队提交的请求 | 绑定失败:绑定请求已取消,请重新发送。 | | 数据库等内部错误 | 绑定失败:发生内部错误,请稍后重试或联系管理员。 |
辅助命令返回:
| 条件 | 返回文本 | | --- | --- | | 私聊发起绑定 | 请在 QQ 和 OneBot 都能收到消息的群里绑定。 | | 缺少号码或号码格式不正确 | 请发送“绑定qq 你的QQ号”,例如:绑定qq 123456789。 | | 查询已绑定状态 | 当前已绑定 QQ {QQ号}。 | | 查询未绑定状态 | 当前尚未绑定,请发送“绑定qq 你的QQ号”。 | | 解绑成功 | 已解除账号绑定,恢复 QQ 原有用户数据。 | | 取消尚未匹配的请求 | 已取消待处理的绑定请求。 | | 未绑定时解绑 | 当前尚未绑定。 | | 解绑时发现原有绑定被其他插件修改 | 原有绑定已被其他插件修改,请检查后再解绑。 |
OneBot 单侧消息、重复投递和 OneBot 发送者不符的消息不会由 OneBot 回复。匹配过程中没有额外的“等待中”提示,匹配完成或 QQ 请求超时后回复最终结果。当前群映射关闭,不会出现群关联提示。
