koishi-plugin-qq-bot-v2
v0.1.0
Published
腾讯 QQ 机器人 API v2 适配器与新增开放接口
Maintainers
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)