QQBot Connector

QQ 机器人扫码连接 SDK，在控制台展示二维码，用户使用手机 QQ 扫码后自动获取机器人的 AppID 与 AppSecret。

默认情况下扫码页面会将接入方统一显示为"第三方机器人"。如需在扫码页面展示你的平台名称，或有其他商务合作需求，请通过邮件与我们联系：[email protected]。

系统要求

• Node.js >= 18.0.0

安装

npm install @tencent-connect/qqbot-connector

快速开始

Promise 风格

始终在控制台打印二维码，扫码后返回凭据：

import { qrConnect } from '@tencent-connect/qqbot-connector';

try {
  const [{ appId, appSecret }] = await qrConnect();
  console.log('绑定成功！');
  console.log('AppID:', appId);
  console.log('AppSecret:', appSecret);
} catch (err) {
  console.error('绑定失败:', err.message);
}

回调风格

通过 displayQrCodeToConsole 控制是否在控制台打印二维码，onQrDisplayed 始终会在轮询开始前回调二维码 URL：

import { startQrConnect } from '@tencent-connect/qqbot-connector';

// 不打印二维码到控制台，通过 onQrDisplayed 自行处理 URL
const stop = startQrConnect({
  onSuccess([{ appId, appSecret }]) {
    console.log('绑定成功！');
    console.log('AppID:', appId);
    console.log('AppSecret:', appSecret);
  },
  onFailure(err) {
    console.error('绑定失败:', err.message);
  },
  onQrDisplayed(url) {
    // 始终回调，可自行生成二维码图片、发送给用户等
    console.log('二维码链接:', url);
  },
  onQrExpired() {
    console.log('二维码已过期，正在刷新…');
  },
}, {
  displayQrCodeToConsole: false,
});

// 需要取消时调用 stop()
// stop();

API

qrConnect(options?): Promise<QrConnectCredentials[]>

在控制台展示二维码并等待扫码，返回 Promise。

此模式下始终在控制台打印二维码（displayQrCodeToConsole 固定为 true，不可关闭）。如需自行处理二维码 URL 而不打印，请使用回调风格的 startQrConnect。

参数：

| 名称 | 类型 | 默认值 | 说明 | |------|------|--------|------| | options.source | string | '' | 接入平台标识，留空则显示为"第三方机器人" | | options.signal | AbortSignal | — | 外部取消信号 |

返回值：

interface QrConnectCredentials {
  appId: string;
  appSecret: string;
}

注意： 绑定成功后返回的凭据类型是 QrConnectCredentials[] 数组。目前扫码仅支持绑定单个 QQ 机器人（数组长度为 1），未来可能会拓展支持同时绑定多个 QQ 机器人，建议业务侧提前做好对数组的遍历处理，以便后续平滑升级。

startQrConnect(callbacks, options?): () => void

轮询等待扫码结果（回调风格）。返回一个 stop 函数，调用后可中止流程。

二维码过期后会自动刷新并重新轮询，直到用户扫码成功或主动取消。无论 displayQrCodeToConsole 为何值，onQrDisplayed 都会在轮询开始前回调二维码 URL，供业务自行展示。

callbacks：

| 名称 | 类型 | 说明 | |------|------|------| | onSuccess | (credentials: QrConnectCredentials[]) => void | 扫码成功回调 | | onFailure | (error: Error) => void | 失败或取消回调 | | onQrDisplayed? | (url: string) => void | 二维码 URL 就绪，轮询开始前始终触发 | | onQrExpired? | () => void | 二维码已过期，即将刷新（可选） |

options：

| 名称 | 类型 | 默认值 | 说明 | |------|------|--------|------| | options.displayQrCodeToConsole | boolean | true | 是否在控制台打印二维码 | | options.source | string | '' | 接入平台标识，留空则显示为"第三方机器人" | | options.signal | AbortSignal | — | 外部取消信号 |

取消支持

两种取消方式：

// 方式一：使用返回的 stop 函数
const stop = startQrConnect({ ... });
stop();

// 方式二：使用 AbortController
const ac = new AbortController();
qrConnect({ signal: ac.signal }).catch(console.error);
ac.abort();

协助与反馈

如在使用过程中遇到问题，欢迎前往以下地址查阅已有议题或提交新问题：

https://github.com/tencent-connect/openclaw-qqbot/issues