npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

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 请求超时后回复最终结果。当前群映射关闭,不会出现群关联提示。