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-bot-v2

v0.1.0

Published

腾讯 QQ 机器人 API v2 适配器与新增开放接口

Readme

koishi-plugin-qq-bot-v2

腾讯 QQ 机器人 API v2 的 Koishi 适配器。入口是 QQBotV2,继承官方 @koishijs/plugin-adapter-qq 4.14.0 的网关、Webhook、消息编解码和平台事件处理,并补充 2026 年 8–9 月发布的开放接口。

接入

在 Koishi 插件市场搜索并安装 qq-bot-v2(npm 包名 koishi-plugin-qq-bot-v2),启用后填写 QQ 开放平台的 AppID 和 AppSecret。本地工作区目录名为 qq-bot。Config 沿用官方 QQ 适配器:可选择 WebSocket 或 Webhook、事件 Intents、沙箱和消息相关设置。请停用使用同一 AppID 的 adapter-qq 实例,避免重复连接和重复事件。

控制台管理菜单与面板

启用 Koishi 的 console 服务并登录权限等级至少为 4 的管理员账号。侧边栏中的「QQ 菜单与面板」页面可选择当前运行的 QQ Bot v2 实例:

  • 「自定义菜单」支持读取、添加、编辑和移除菜单项及子项。保存时通过 PUT /v2/menu 替换整个菜单;菜单只在 QQ 单聊展示,且对该机器人全部用户生效。移除全部菜单项并保存可清空菜单。
  • 「指令面板」按单聊、群聊、文字子频道、频道私信四种场景分页浏览;可创建、查看详情、修改面板内容、删除面板。单聊和群聊可创建指定对象面板,并在详情中增删关联的用户或群 OpenID。文字子频道和频道私信仅支持全局面板。

页面操作直接调用 QQ Bot API v2,不会在本地另存一份菜单或面板。菜单最多 10 项、每个子菜单最多 5 项;一个机器人最多 20 个指令面板,每个面板最多 20 个元素。页面和服务端均限制明显无效的配置;QQ 的接口频率限制、内容安全审核和机器人实际权限仍以开放平台响应为准。控制台服务未启用时,适配器和 bot.v2 仍可正常使用。

相关文档:自定义菜单与指令面板、查询指令面板列表。

WebSocket 的事件权限

QQ 网关在请求了未获授权的 Intents 时会关闭连接(常见为 4014,日志显示 disallowed intents)。本适配器默认 intentPolicy: auto:只订阅 QQ 文档列出的基础事件 GUILDS、GUILD_MEMBERS、PUBLIC_GUILD_MESSAGES,以及配置中已勾选的 USER_MESSAGE;其他已勾选事件不会参与 WebSocket Identify。当前仓库机器人已通过短时网关握手验证 USER_MESSAGE 可用,因此自动模式能继续接收 QQ 单聊及群聊 @ 消息。

如果机器人未获 USER_MESSAGE 权限,将 intentPolicy 设为 basic;该模式可以接收频道中 @ 机器人的消息,但不能接收 QQ 单聊或群聊消息。messages 只请求基础事件和 USER_MESSAGE。interactive 在此基础上增加 INTERACTIONS,用于游戏按钮;机器人须同时获准订阅 USER_MESSAGE 和 INTERACTIONS。configured 会原样提交「intents」中所有勾选项,仅在确知每一项都获授权时使用。当前工作区的只读根配置勾选了全部事件,其中 GUILD_MESSAGES、FORUM_EVENT 是私域专用;对 public 机器人直接选择 configured 会导致 disallowed intents。Webhook 的事件订阅在 QQ 开放平台管理端配置,不受此选项影响。

WebSocket 默认连接文档中的 wss://api.bot.qq.com/websocket/;如显式设置 gatewayUrl 或启用沙箱模式,将保留原有连接方式。当前仓库的 koishi.yml 位于禁止修改的目录,所以上述模式需通过 Koishi 控制台配置。

此插件会使用 https://api.bot.qq.com/app/getAppAccessToken 获取 Access Token,并按凭证有效期自动刷新;OpenAPI 请求使用 Authorization: QQBot ACCESS_TOKEN。不使用已废弃的固定 Token 鉴权。

收到的单聊、群聊、频道消息和事件,以及文本、Markdown、富媒体、按钮等消息发送能力由官方适配器提供。事件需在开放平台开通相应权限并配置 Intents。QQ 平台的频控、回复时效和审核规则仍适用。

本地富媒体上传

QQ 单聊和群聊中的 Buffer、data: 图片与本地文件使用 upload_prepare → 分片 PUT → upload_part_finish → /files 合并流程。预上传包含字符串大小和 md5_10m 校验值;兼容从 0 或 1 开始的分片序号(文档示例为 0,实际接口与腾讯 Node SDK 为 1),确认时透传服务器分片序号并使用实际分片大小。公网 URL 继续走 URL 上传。两种场景各自上传,不复用另一场景的 file_info。

上传失败会记录 HTTP 状态、QQ 错误码与 TraceID,供排查平台拒绝原因;不记录上传内容或鉴权头。协议参考:富媒体消息概述、单聊预上传。

实测 40011033 的平台响应为「请求处理失败,用户为末成年模式」,同一用户的分片和 Base64 上传都会被拒绝。遇到此码时记录明确原因并返回空发送结果,让异界连结回退本次结果的文字;同一入站事件的后续图片跳过上传,不重复输出异常堆栈。新的入站事件可重新尝试,以便用户调整 QQ 账号设置后恢复。此账号限制需要在 QQ 端处理,插件不能解除。独立画图命令发送失败时会提示用户查看平台错误日志。

游戏消息交互

本地编码器沿用上游发送流程,并支持 <button> 的 qqUserId 属性,将按钮限制为指定 OpenID 可操作;服务器仍须自行核对点击者身份。按钮组导出时移除上游产生的空行,避免空行占用 QQ 键盘行数。

对于 INTERACTION_CREATE 会话,消息回复使用事件最外层的 id 作为 event_id,与使用 d.id 的互动 ACK 区分;同一会话的分段、图片及后续回复连续分配 msg_seq,不携带 msg_id。缺少回复凭据、凭据过期或与消息 ID 混用时拒绝发送,避免意外发成主动消息。

异界连结提供的游戏按钮需要 INTERACTION_CREATE 事件。WebSocket 下,取得权限后在 Koishi 控制台选择 intentPolicy=interactive;该预设只请求 GUILDS、GUILD_MEMBERS、PUBLIC_GUILD_MESSAGES、USER_MESSAGE、INTERACTIONS,忽略当前「intents」中其余勾选项。若此预设仍报 disallowed intents,说明机器人尚无 INTERACTIONS 权限;先切回 auto 或 messages 恢复消息连接,再到 QQ 开放平台申请或确认权限。Webhook 在 QQ 开放平台管理端订阅。自动 ACK 与游戏的手动 ACK 路径互斥,不应为同一事件再额外注册重复应答。

协议参考:消息交互、互动事件、互动响应。

开发验证:在此插件目录运行 node scripts/test.cjs、node scripts/build.cjs --typecheck、node scripts/build.cjs。构建只输出本插件的 lib 和 TypeScript 增量文件;测试不连接真实 QQ,关闭 tsx 磁盘缓存。

新增接口

通过机器人实例上的 bot.v2 调用:

| 方法 | QQ API v2 能力 | | --- | --- | | getGroupMembers(groupId, cursor?) | 群成员分页列表 | | removeGroupMembers(groupId, memberIds, addToBlacklist?) | 批量移除群成员 | | getGroupBlacklist(groupId, cursor?, limit?) | 查询群黑名单 | | updateGroupBlacklist(groupId, op, memberIds) | 增删群黑名单 | | listJoinApprovalStrategies(cursor?, limit?) | 查询入群自动审批策略 | | createJoinApprovalStrategy(data) / updateJoinApprovalStrategy(id, data) | 创建和修改入群自动审批策略 | | deleteJoinApprovalStrategy(id) / executeJoinApprovalStrategy(id) | 删除策略或启动异步扫描 | | updateJoinApprovalWhitelist(id, op, userNumbers) | 增删策略白名单 QQ 号码 | | getMenu() / updateMenu(menu) | 查询和替换单聊自定义菜单 | | listPanels(scope, cursor?, limit?) | 分页查询指令面板 | | createPanel(data) / getPanel(id) | 创建和查询面板 | | updatePanel(id, panel) / deletePanel(id) | 修改和删除面板 | | updatePanelTargets(id, op, targets) | 增删面板关联用户或群 | | generateShareLink(callbackData?) | 生成邀请用户添加机器人的分享链接 | | sendPrivateStreamMessage(openId, fragment) | 按顺序发送 QQ 单聊流式片段,返回流式消息 ID 与剩余长度 |

getGuildMemberList() 和 kickGuildMember() 也映射到 QQ 群成员接口;kickGuildMember(..., true) 会同时尝试将成员加入黑名单。群成员列表、批量移除和群黑名单接口目前由 QQ 内邀开放,未获授权的机器人会收到平台的 11253 错误。

流式接口仅适用于 QQ 单聊。首片 index=0,后续片段使用首片返回的 id 作为 stream_msg_id,保留同一 msg_seq 并递增 index,结束片设置 input_state=10。群聊接口不支持流式参数,继续使用普通 Markdown 消息。

const bot = ctx.bots.find(bot => bot.platform === 'qq' && bot.selfId === appId) as QQBotV2
const { records } = await bot.v2.listPanels('group')
const { data } = await bot.v2.generateShareLink('campaign-1')
console.log(records, data.url)

文档