文档同步

本页由 plugins/adapters/qq/README.md 自动生成。请修改包内 README 后运行 pnpm sync:adapter-docs。

@zhin.js/adapter-qq

Zhin.js QQ 官方机器人适配器（Plugin Runtime），默认通过 WebSocket Gateway（qq-official-bot）收发消息（无需 host-router / host-http）。

功能

WebSocket Gateway 入站（默认；无需公网 HTTPS / host）
解析私聊 / 群 / 频道消息
出站 send({ target, payload }) → QQ API（private: / group: / channel: / direct:）
约定式 defineAdapter / definePlugin（无需 usePlugin）
Webhook / middleware 模式已实现（经 httpHostToken 注册 POST 路由）
AI @ 触发标注：群消息（GROUP_AT_MESSAGE_CREATE 仅 @ 时下发）与频道 mentions[].bot 会在入站 metadata 标 mentioned: true（新 Plugin Runtime 纯文本 content 经 metadata 传递 @）

安装

bash

pnpm add @zhin.js/adapter-qq

Plugin Runtime

@zhin.js/adapter — 约定式 adapters/qq.ts（defineAdapter）
@zhin.js/core — messageGatewayToken 入站/出站
@zhin.js/plugin-runtime — plugin.ts（definePlugin）
配置经插件 schema.json 落到 plugins.<instanceKey>
无需 @zhin.js/host-http / @zhin.js/host-router（WebSocket 路径）

入站：gateway.receive({ adapter, target: 'group:…'|…, content, sender, metadata })
出站：send({ target, payload }) → sendPrivateMessage / sendGroupMessage / sendGuildMessage

前置条件

要求	说明
AppID / Secret	QQ 开放平台创建机器人应用并获取
WebSocket（默认）	`qq-official-bot` 正向连接；无需公网回调
host-http	WebSocket 不需要；Webhook / middleware 模式需要（经 `httpHostToken`）

必填字段（endpoints[i]）：name、appid、secret。

最小配置

yaml

# zhin.config.yml（Plugin Runtime）
plugins:
  qq:
    # mode: websocket   # 默认
    endpoints:
      - name: my-qq-bot
        appid: ${QQ_APPID}
        secret: ${QQ_SECRET}

多账号：一个插件实例挂多个 endpoint（endpoints 数组逐项覆盖顶层字段，name 必填）：

yaml

plugins:
  qq:
    mode: websocket
    intents: [GUILDS, GROUP_AND_C2C_EVENT]
    endpoints:
      - name: main-bot
        appid: ${QQ_APPID}
        secret: ${QQ_SECRET}
      - name: second-bot
        appid: ${QQ_APPID_2}
        secret: ${QQ_SECRET_2}

根插件 zhin.plugins（或项目图）需引用 @zhin.js/adapter-qq（instanceKey: qq）。

Endpoint 管理命令

适配器自带 qq endpoint 命令组（聊天内直接使用，默认无前缀；受 commandPrefix 影响）：

命令	说明
`qq endpoint add [name]`	手机 QQ 扫码绑定：下发二维码链接 → 确认后凭据写入 `.env`（`QQ_<NAME>_APPID/SECRET`），并追加 `plugins.qq.endpoints`（重启生效）
`qq endpoint cancel`	取消进行中的扫码绑定（同时只允许一个流程）
`qq endpoint list`	列出运行中与配置中的 endpoints
`qq endpoint remove <name>`	从配置移除 endpoint（`.env` 键保留，可手动清理）

add/cancel/remove 受 master 限制：实例配置声明了 master（顶层或 endpoints[i]）时仅 master 可执行；未配置则放行（首个扫码绑定者即 owner）。二维码当前以链接文本下发（出站富媒体待迁移），用手机 QQ 打开链接即可扫码。

环境变量

变量	说明
`QQ_APPID` / `QQ_BOT_APPID`	应用 AppID
`QQ_SECRET` / `QQ_BOT_SECRET`	应用 Secret
`QQ_BOT_NAME`	可选，默认 endpoint 名

Webhook / middleware

mode: webhook 或 mode: middleware 经 httpHostToken 注册 POST 路由（默认 /qq/webhook），使用 qq-official-bot Middleware 接收器验签并入站；出站仍走 QQ HTTP API。Host 需注入 httpHostToken。

AI 工具（Skill）

类别	路径
Permit 词汇	`agent/PERMITS.md`
平台工具	`agent/tools/`（频道、角色等）
技能说明	`agent/skills/qq.md`

平台权限（platform permit）

platform permit checker 由 plugin.ts 的 generation 生命周期注册；@zhin.js/tool descriptor 保留 platforms / scopes / permissions，CapabilityIngress 与 ToolSystem 统一经 Core canAccessTool() 执行门禁。

迁移后出站能力变化

迁移到 Plugin Runtime 后，出站统一经 messageGatewayToken 渲染为文本后发送（sendPrivateMessage / sendGroupMessage / sendGuildMessage）。旧 Adapter 的富媒体出站能力（图片 / 语音 / 视频、keyboard 按钮、markdown 模板等）暂未迁移，当前出站等价于纯文本。如需富媒体，可通过 endpoint 的 QQ API 封装或直接调用 QQ HTTP API 作为逃生舱。

许可证

MIT License

@zhin.js/adapter-qq ​

功能 ​

安装 ​

Plugin Runtime ​

前置条件 ​

最小配置 ​

Endpoint 管理命令 ​

环境变量 ​

Webhook / middleware ​

AI 工具（Skill） ​

平台权限（platform permit） ​

迁移后出站能力变化 ​

许可证 ​