@zhin.js/adapter-qq 5.0.3 → 6.0.1

package/lib/qq-bind-api.d.ts

@@ -0,0 +1,36 @@
+export type QQBotEnv = 'production' | 'test';
+export declare enum BindStatus {
+    NONE = 0,
+    PENDING = 1,
+    COMPLETED = 2,
+    EXPIRED = 3
+}
+export declare function getQQBotHost(env?: QQBotEnv): string;
+export declare function generateBindKey(): string;
+export declare function buildConnectUrl(taskId: string, source?: string): string;
+/**
+ * AES-256-GCM 解密 base64 密文。
+ * 密文格式: IV(12 bytes) + ciphertext + AuthTag(16 bytes)
+ */
+export declare function decryptSecret(encryptedBase64: string, keyBase64: string): string;
+export interface BindTaskResult {
+    taskId: string;
+    key: string;
+}
+export declare function createBindTask(env?: QQBotEnv, timeoutMs?: number): Promise<BindTaskResult>;
+export interface PollBindResultOk {
+    status: BindStatus;
+    botAppId: string;
+    botEncryptSecret: string;
+    /** 扫码绑定开发者 QQ 的 OpenID（poll_bind_result 返回） */
+    userOpenId: string;
+}
+export declare function parsePollBindResultData(data: {
+    status?: number;
+    bot_appid?: string | number;
+    bot_encrypt_secret?: string;
+    user_openid?: string;
+    userOpenid?: string;
+    openid?: string;
+} | undefined): PollBindResultOk;
+export declare function pollBindResult(taskId: string, env?: QQBotEnv, timeoutMs?: number): Promise<PollBindResultOk>;

package/lib/qq-bind-api.js

@@ -0,0 +1,89 @@
+/**
+ * QQ Bot 扫码绑定协议（内联）
+ * Protocol aligned with @tencent-connect/qqbot-connector@1.1.0 qqbot-session — inlined to avoid runtime dependency.
+ */
+import { createDecipheriv, randomBytes } from 'node:crypto';
+const HOSTS = {
+    production: 'q.qq.com',
+    test: 'test.q.qq.com',
+};
+export var BindStatus;
+(function (BindStatus) {
+    BindStatus[BindStatus["NONE"] = 0] = "NONE";
+    BindStatus[BindStatus["PENDING"] = 1] = "PENDING";
+    BindStatus[BindStatus["COMPLETED"] = 2] = "COMPLETED";
+    BindStatus[BindStatus["EXPIRED"] = 3] = "EXPIRED";
+})(BindStatus || (BindStatus = {}));
+export function getQQBotHost(env = 'production') {
+    return HOSTS[env];
+}
+export function generateBindKey() {
+    return randomBytes(32).toString('base64');
+}
+export function buildConnectUrl(taskId, source = 'zhin') {
+    return `https://${getQQBotHost('production')}/qqbot/openclaw/connect.html?task_id=${encodeURIComponent(taskId)}&source=${encodeURIComponent(source)}&_wv=2`;
+}
+/**
+ * AES-256-GCM 解密 base64 密文。
+ * 密文格式: IV(12 bytes) + ciphertext + AuthTag(16 bytes)
+ */
+export function decryptSecret(encryptedBase64, keyBase64) {
+    const key = Buffer.from(keyBase64, 'base64');
+    const payload = Buffer.from(encryptedBase64, 'base64');
+    const iv = payload.subarray(0, 12);
+    const authTag = payload.subarray(payload.length - 16);
+    const ciphertext = payload.subarray(12, payload.length - 16);
+    const decipher = createDecipheriv('aes-256-gcm', key, iv);
+    decipher.setAuthTag(authTag);
+    return Buffer.concat([decipher.update(ciphertext), decipher.final()]).toString('utf8');
+}
+async function postJson(url, body, timeoutMs) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const res = await fetch(url, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Accept: 'application/json',
+            },
+            body: JSON.stringify(body),
+            signal: controller.signal,
+        });
+        if (!res.ok) {
+            throw new Error(`HTTP ${res.status} from ${url}`);
+        }
+        return (await res.json());
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export async function createBindTask(env = 'production', timeoutMs = 10_000) {
+    const url = `https://${getQQBotHost(env)}/lite/create_bind_task`;
+    const key = generateBindKey();
+    const res = await postJson(url, { key }, timeoutMs);
+    if (res.retcode !== 0) {
+        throw new Error(res.msg ?? 'create_bind_task failed');
+    }
+    if (!res.data?.task_id) {
+        throw new Error('create_bind_task: missing task_id');
+    }
+    return { taskId: res.data.task_id, key };
+}
+export function parsePollBindResultData(data) {
+    return {
+        status: (data?.status ?? BindStatus.NONE),
+        botAppId: String(data?.bot_appid ?? ''),
+        botEncryptSecret: data?.bot_encrypt_secret ?? '',
+        userOpenId: String(data?.user_openid ?? data?.userOpenid ?? data?.openid ?? ''),
+    };
+}
+export async function pollBindResult(taskId, env = 'production', timeoutMs = 10_000) {
+    const url = `https://${getQQBotHost(env)}/lite/poll_bind_result`;
+    const res = await postJson(url, { task_id: taskId }, timeoutMs);
+    if (res.retcode !== 0) {
+        throw new Error(res.msg ?? 'poll_bind_result failed');
+    }
+    return parsePollBindResultData(res.data);
+}

package/lib/qq-bind-flow.d.ts

@@ -0,0 +1,19 @@
+export interface QqBindCredentials {
+    appId: string;
+    appSecret: string;
+    userOpenId?: string;
+}
+export interface QqBindCallbacks {
+    onSuccess: (credentials: QqBindCredentials[]) => void;
+    onFailure: (error: Error) => void;
+    onQrDisplayed?: (url: string) => void | Promise<void>;
+    onQrExpired?: () => void | Promise<void>;
+}
+export interface QqBindFlowOptions {
+    signal?: AbortSignal;
+    source?: string;
+}
+/**
+ * 轮询等待扫码结果（回调风格）。返回 stop 函数可中止流程。
+ */
+export declare function startQqBindFlow(callbacks: QqBindCallbacks, options?: QqBindFlowOptions): () => void;

package/lib/qq-bind-flow.js

@@ -0,0 +1,85 @@
+/**
+ * QQ Bot 扫码绑定流程（内联，等价 qqbot-connector startQrConnect）
+ */
+import { BindStatus, buildConnectUrl, createBindTask, decryptSecret, pollBindResult, } from './qq-bind-api.js';
+const POLL_INTERVAL_MS = 2000;
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(new DOMException('Aborted', 'AbortError'));
+            return;
+        }
+        const timer = setTimeout(resolve, ms);
+        signal?.addEventListener('abort', () => {
+            clearTimeout(timer);
+            reject(new DOMException('Aborted', 'AbortError'));
+        }, { once: true });
+    });
+}
+async function pollUntilResult(taskId, key, signal) {
+    while (!signal?.aborted) {
+        let result;
+        try {
+            result = await pollBindResult(taskId);
+        }
+        catch {
+            await sleep(POLL_INTERVAL_MS, signal);
+            continue;
+        }
+        if (result.status === BindStatus.COMPLETED) {
+            const appSecret = decryptSecret(result.botEncryptSecret, key);
+            return {
+                outcome: 'scanned',
+                appId: result.botAppId,
+                appSecret,
+                userOpenId: result.userOpenId,
+            };
+        }
+        if (result.status === BindStatus.EXPIRED) {
+            return { outcome: 'expired' };
+        }
+        await sleep(POLL_INTERVAL_MS, signal);
+    }
+    throw new DOMException('Aborted', 'AbortError');
+}
+/**
+ * 轮询等待扫码结果（回调风格）。返回 stop 函数可中止流程。
+ */
+export function startQqBindFlow(callbacks, options = {}) {
+    const controller = new AbortController();
+    const signal = options.signal
+        ? AbortSignal.any([controller.signal, options.signal])
+        : controller.signal;
+    void (async () => {
+        for (;;) {
+            if (signal.aborted) {
+                throw new DOMException('Aborted', 'AbortError');
+            }
+            let task;
+            try {
+                task = await createBindTask();
+            }
+            catch (err) {
+                throw new Error(`获取绑定任务失败: ${err instanceof Error ? err.message : String(err)}`, { cause: err });
+            }
+            const connectUrl = buildConnectUrl(task.taskId, options.source ?? 'zhin');
+            await callbacks.onQrDisplayed?.(connectUrl);
+            const pollResult = await pollUntilResult(task.taskId, task.key, signal);
+            if (pollResult.outcome === 'scanned') {
+                callbacks.onSuccess([{
+                        appId: pollResult.appId,
+                        appSecret: pollResult.appSecret,
+                        userOpenId: pollResult.userOpenId || undefined,
+                    }]);
+                return;
+            }
+            await callbacks.onQrExpired?.();
+        }
+    })().catch((err) => {
+        if (err instanceof DOMException && err.name === 'AbortError') {
+            return;
+        }
+        callbacks.onFailure(err instanceof Error ? err : new Error(String(err)));
+    });
+    return () => controller.abort();
+}

package/lib/qq-bind-persist.d.ts

@@ -0,0 +1,12 @@
+import { resolveProjectRoot } from '@zhin.js/adapter';
+export { resolveProjectRoot };
+export interface QqCredentialEnvKeys {
+    appidKey: string;
+    secretKey: string;
+    appidRef: string;
+    secretRef: string;
+}
+/** 按 endpoint 名称生成唯一 env 键（如 `QQ_MY_BOT_APPID`） */
+export declare function buildQqCredentialEnvKeys(endpointName: string): QqCredentialEnvKeys;
+/** 写入或更新 `.env` 中的键值，并同步到当前进程 `process.env` */
+export declare function persistQqCredentialsToEnv(endpointName: string, appId: string, appSecret: string, projectRoot?: string): QqCredentialEnvKeys;

package/lib/qq-bind-persist.js

@@ -0,0 +1,22 @@
+import { buildEndpointEnvKey, persistEndpointEnvValues, resolveProjectRoot, } from '@zhin.js/adapter';
+export { resolveProjectRoot };
+/** 按 endpoint 名称生成唯一 env 键（如 `QQ_MY_BOT_APPID`） */
+export function buildQqCredentialEnvKeys(endpointName) {
+    const appidKey = buildEndpointEnvKey('qq', endpointName, 'appid');
+    const secretKey = buildEndpointEnvKey('qq', endpointName, 'secret');
+    return {
+        appidKey,
+        secretKey,
+        appidRef: `\${${appidKey}}`,
+        secretRef: `\${${secretKey}}`,
+    };
+}
+/** 写入或更新 `.env` 中的键值，并同步到当前进程 `process.env` */
+export function persistQqCredentialsToEnv(endpointName, appId, appSecret, projectRoot) {
+    const keys = buildQqCredentialEnvKeys(endpointName);
+    persistEndpointEnvValues({
+        [keys.appidKey]: appId,
+        [keys.secretKey]: appSecret,
+    }, projectRoot);
+    return keys;
+}

package/lib/qq-endpoint-commands.d.ts

@@ -0,0 +1,38 @@
+/**
+ * `qq endpoint` 命令的业务逻辑（与命令定义文件分离，便于测试）。
+ * 通用部分（权限 / list / remove / 配置写回 / .env 持久化）已迁移到
+ * @zhin.js/adapter 的 createEndpointCommands 套件；本文件保留 QQ 特化的
+ * 扫码绑定 add 流程（经套件 bindFlow 钩子接入）与 cancel，并导出
+ * qqEndpointCommands 供 commands/endpoint/ 下的命令文件默认导出。
+ */
+import { type EndpointCommandReply } from '@zhin.js/adapter';
+import { type QqRuntimeState } from './qq-runtime-state.js';
+export type QqCommandReply = EndpointCommandReply;
+/**
+ * endpoint 管理命令的操作者校验：实例配置声明了 master（顶层或任一端点项）时
+ * 仅 master 可执行 add/cancel/remove；未配置则放行（首个扫码绑定者即为 owner，
+ * legacy applyBindOwnership 会把 operator 写为新端点的 master）。
+ */
+export declare function isQqEndpointOperator(config: unknown, input: unknown): boolean;
+export declare const QQ_ENDPOINT_FORBIDDEN: string;
+/**
+ * 从命令 input（Runtime Message）提取 $reply；非消息来源（如 Host API 调用）降级为 no-op。
+ */
+export declare function extractQqCommandReply(input: unknown): QqCommandReply;
+/** `qq endpoint list`：运行中的 endpoints（本 generation adapter create 注册）+ 配置里的 endpoints */
+export declare function runQqEndpointList(state: QqRuntimeState, projectRoot?: string): string;
+/**
+ * `qq endpoint add [name]`：启动扫码绑定流程。
+ * 返回的 Promise 在二维码链接就绪（或前置失败）时 resolve 为首条回复；
+ * 后续状态（已扫码 / 成功 / 失败 / 过期刷新）通过 reply 推回当前会话。
+ */
+export declare function runQqEndpointAdd(state: QqRuntimeState, name: string | undefined, reply: QqCommandReply, projectRoot?: string): Promise<string>;
+/** `qq endpoint cancel`：中止进行中的绑定流程 */
+export declare function runQqEndpointCancel(state: QqRuntimeState): string;
+/** `qq endpoint remove <name>`：从 zhin.config.yml 移除对应 endpoints 项 */
+export declare function runQqEndpointRemove(_state: QqRuntimeState, name: string, projectRoot?: string): string;
+/**
+ * 通用套件生成的 QQ endpoint 命令（add 经 bindFlow 钩子走扫码绑定）。
+ * commands/endpoint/ 下的 list / add / remove 直接默认导出这三项；cancel 为 QQ 特化，单独定义。
+ */
+export declare const qqEndpointCommands: import("@zhin.js/adapter").EndpointCommands<Readonly<import("@zhin.js/command").CommandDefinition<unknown, unknown, import("@zhin.js/command").CommandMessage>>>;

package/lib/qq-endpoint-commands.js

@@ -0,0 +1,122 @@
+/**
+ * `qq endpoint` 命令的业务逻辑（与命令定义文件分离，便于测试）。
+ * 通用部分（权限 / list / remove / 配置写回 / .env 持久化）已迁移到
+ * @zhin.js/adapter 的 createEndpointCommands 套件；本文件保留 QQ 特化的
+ * 扫码绑定 add 流程（经套件 bindFlow 钩子接入）与 cancel，并导出
+ * qqEndpointCommands 供 commands/endpoint/ 下的命令文件默认导出。
+ */
+import { createEndpointCommands, endpointCommandForbidden, extractEndpointCommandReply, formatEndpointList, isEndpointOperator, removeEndpointByName, } from '@zhin.js/adapter';
+import { defineCommand } from '@zhin.js/command';
+import { startQqBindFlow } from './qq-bind-flow.js';
+import { persistQqCredentialsToEnv } from './qq-bind-persist.js';
+import { addQqEndpointToConfig, listQqEndpointEntries } from './qq-endpoint-config.js';
+import { qqRuntimeStateToken } from './qq-runtime-state.js';
+/**
+ * endpoint 管理命令的操作者校验：实例配置声明了 master（顶层或任一端点项）时
+ * 仅 master 可执行 add/cancel/remove；未配置则放行（首个扫码绑定者即为 owner，
+ * legacy applyBindOwnership 会把 operator 写为新端点的 master）。
+ */
+export function isQqEndpointOperator(config, input) {
+    return isEndpointOperator(config, input);
+}
+export const QQ_ENDPOINT_FORBIDDEN = endpointCommandForbidden('QQ');
+/**
+ * 从命令 input（Runtime Message）提取 $reply；非消息来源（如 Host API 调用）降级为 no-op。
+ */
+export function extractQqCommandReply(input) {
+    return extractEndpointCommandReply(input);
+}
+/** `qq endpoint list`：运行中的 endpoints（本 generation adapter create 注册）+ 配置里的 endpoints */
+export function runQqEndpointList(state, projectRoot) {
+    return formatEndpointList(qqEndpointListSpec, {
+        running: state.endpoints.values(),
+        configured: listQqEndpointEntries(projectRoot),
+        footer: state.bindFlow ? '⚠️ 有进行中的扫码绑定，可用 qq endpoint cancel 取消' : undefined,
+    });
+}
+const qqEndpointListSpec = {
+    adapterKey: 'qq',
+    adapterDisplayName: 'QQ',
+    describeEntry: (entry) => `appid: ${String(entry.appid)}`,
+};
+/**
+ * `qq endpoint add [name]`：启动扫码绑定流程。
+ * 返回的 Promise 在二维码链接就绪（或前置失败）时 resolve 为首条回复；
+ * 后续状态（已扫码 / 成功 / 失败 / 过期刷新）通过 reply 推回当前会话。
+ */
+export function runQqEndpointAdd(state, name, reply, projectRoot) {
+    if (state.bindFlow) {
+        return Promise.resolve('已有进行中的 QQ 机器人绑定，请先发送 qq endpoint cancel 取消后再试');
+    }
+    const endpointName = name?.trim() || undefined;
+    return new Promise((resolve) => {
+        let firstReplied = false;
+        const settle = (text) => {
+            if (!firstReplied) {
+                firstReplied = true;
+                resolve(text);
+                return;
+            }
+            void reply(text);
+        };
+        const stop = startQqBindFlow({
+            onQrDisplayed: (url) => {
+                // QQ 出站当前仅支持纯文本（富媒体未迁移），二维码只能发链接文本
+                settle(`请用手机 QQ 打开以下链接完成扫码绑定（二维码图片出站暂未支持，故发送链接）：\n${url}`);
+            },
+            onQrExpired: async () => {
+                await reply('二维码已过期，正在刷新，请扫描新链接…');
+            },
+            onSuccess: async (credentials) => {
+                state.bindFlow = null;
+                try {
+                    const [{ appId, appSecret }] = credentials;
+                    const finalName = endpointName ?? appId;
+                    const envKeys = persistQqCredentialsToEnv(finalName, appId, appSecret, projectRoot);
+                    const filePath = addQqEndpointToConfig({ name: finalName, appid: envKeys.appidRef, secret: envKeys.secretRef }, projectRoot);
+                    settle(`✅ 绑定成功！endpoint「${finalName}」的凭据已写入 .env，并已追加到 ${filePath} 的 plugins.qq.endpoints。\n` +
+                        '⚠️ 需重启 zhin 后新 endpoint 才会生效。');
+                }
+                catch (error) {
+                    settle(`绑定成功但写入配置失败：${error instanceof Error ? error.message : String(error)}`);
+                }
+            },
+            onFailure: (error) => {
+                state.bindFlow = null;
+                settle(`❌ QQ 绑定失败：${error.message}`);
+            },
+        }, { source: 'zhin' });
+        state.bindFlow = { name: endpointName, stop };
+    });
+}
+/** `qq endpoint cancel`：中止进行中的绑定流程 */
+export function runQqEndpointCancel(state) {
+    if (!state.bindFlow) {
+        return '当前没有进行中的 QQ 绑定流程';
+    }
+    state.bindFlow.stop();
+    state.bindFlow = null;
+    return '已取消进行中的 QQ 绑定流程';
+}
+/** `qq endpoint remove <name>`：从 zhin.config.yml 移除对应 endpoints 项 */
+export function runQqEndpointRemove(_state, name, projectRoot) {
+    return removeEndpointByName(qqEndpointListSpec, name, projectRoot);
+}
+/**
+ * 通用套件生成的 QQ endpoint 命令（add 经 bindFlow 钩子走扫码绑定）。
+ * commands/endpoint/ 下的 list / add / remove 直接默认导出这三项；cancel 为 QQ 特化，单独定义。
+ */
+export const qqEndpointCommands = createEndpointCommands({
+    ...qqEndpointListSpec,
+    fields: [
+        { key: 'appid', required: true, env: true, description: 'QQ 机器人 appid' },
+        { key: 'secret', required: true, env: true, description: 'QQ 机器人 secret' },
+    ],
+    running: (use) => use(qqRuntimeStateToken).endpoints.values(),
+    listFooter: (use) => {
+        const state = use(qqRuntimeStateToken);
+        return state.bindFlow ? '⚠️ 有进行中的扫码绑定，可用 qq endpoint cancel 取消' : undefined;
+    },
+    addDescription: '手机 QQ 扫码绑定机器人，凭据写入 .env 并追加到 zhin.config.yml（重启生效）',
+    bindFlow: ({ name, reply, use }) => runQqEndpointAdd(use(qqRuntimeStateToken), name, reply),
+}, defineCommand);

package/lib/qq-endpoint-config.d.ts

@@ -0,0 +1,17 @@
+export interface QqEndpointConfigEntry {
+    name: string;
+    appid: string;
+    secret: string;
+    [key: string]: unknown;
+}
+/** 定位项目配置文件：ZHIN_CONFIG 指定优先，否则发现 zhin.config.yml/.yaml，都没有则默认新建 zhin.config.yml */
+export declare function findQqConfigFile(projectRoot?: string): string;
+/** 读取 plugins.qq.endpoints（plain JS）；plugins/qq 缺失或形态不符时返回 [] */
+export declare function listQqEndpointEntries(projectRoot?: string): QqEndpointConfigEntry[];
+/** 追加 endpoint 到 plugins.qq.endpoints；name 已存在时报错 */
+export declare function addQqEndpointToConfig(entry: QqEndpointConfigEntry, projectRoot?: string): string;
+/** 按 name 移除 plugins.qq.endpoints 项；不存在返回 false */
+export declare function removeQqEndpointFromConfig(name: string, projectRoot?: string): {
+    removed: boolean;
+    filePath: string;
+};

package/lib/qq-endpoint-config.js

@@ -0,0 +1,22 @@
+/**
+ * zhin.config.yml 中 plugins.qq.endpoints 的读写（Plugin Runtime 版）。
+ * 实现已泛化到 @zhin.js/adapter 的 endpoint-commands 套件（Document 节点级保留注释）；
+ * 本文件仅保留 QQ 专用签名以兼容既有调用与测试。
+ */
+import { addEndpointToConfig, findEndpointConfigFile, listConfiguredEndpoints, removeEndpointFromConfig, } from '@zhin.js/adapter';
+/** 定位项目配置文件：ZHIN_CONFIG 指定优先，否则发现 zhin.config.yml/.yaml，都没有则默认新建 zhin.config.yml */
+export function findQqConfigFile(projectRoot) {
+    return findEndpointConfigFile('qq', projectRoot);
+}
+/** 读取 plugins.qq.endpoints（plain JS）；plugins/qq 缺失或形态不符时返回 [] */
+export function listQqEndpointEntries(projectRoot) {
+    return listConfiguredEndpoints('qq', projectRoot);
+}
+/** 追加 endpoint 到 plugins.qq.endpoints；name 已存在时报错 */
+export function addQqEndpointToConfig(entry, projectRoot) {
+    return addEndpointToConfig('qq', entry, projectRoot);
+}
+/** 按 name 移除 plugins.qq.endpoints 项；不存在返回 false */
+export function removeQqEndpointFromConfig(name, projectRoot) {
+    return removeEndpointFromConfig('qq', name, projectRoot);
+}

package/lib/qq-runtime-state.d.ts

@@ -0,0 +1,17 @@
+export interface QqRunningEndpoint {
+    name: string;
+    mode: string;
+}
+export interface QqBindFlowHandle {
+    /** 绑定期望的 endpoint 名（未指定时为 undefined，成功后取 appId） */
+    name?: string;
+    stop: () => void;
+}
+export interface QqRuntimeState {
+    /** 当前 generation 已成功创建的 endpoint（name → 描述） */
+    readonly endpoints: Map<string, QqRunningEndpoint>;
+    /** 全局单例：同一时间只允许一个扫码绑定流程 */
+    bindFlow: QqBindFlowHandle | null;
+}
+export declare function createQqRuntimeState(): QqRuntimeState;
+export declare const qqRuntimeStateToken: import("@zhin.js/plugin-runtime").Token<QqRuntimeState>;

package/lib/qq-runtime-state.js

@@ -0,0 +1,13 @@
+/**
+ * QQ 插件实例的运行时状态：adapter create() 注册的 endpoint 列表 +
+ * 扫码绑定流程的全局单例。由 plugin.ts setup() provide，
+ * adapter create 与 commands 通过 use(qqRuntimeStateToken) 共享（同一 owner generation）。
+ */
+import { createToken } from '@zhin.js/plugin-runtime';
+export function createQqRuntimeState() {
+    return {
+        endpoints: new Map(),
+        bindFlow: null,
+    };
+}
+export const qqRuntimeStateToken = createToken('zhin.qq.runtime-state', 'QQ adapter runtime state (running endpoints + bind flow singleton)');

package/lib/webhook.js

@@ -21,20 +21,13 @@ export async function handleQqWebhookRequest(request, response, handler) {
         return;
     }
     try {
-        let parsedBody;
-        const raw = await readRequestBodyText(request);
-        if (raw) {
-            try {
-                parsedBody = JSON.parse(raw);
-            }
-            catch {
-                parsedBody = undefined;
-            }
-        }
+        // 不预消费请求流：库的验签必须基于原始字节（JSON.parse → JSON.stringify
+        // 会改变空白/转义/键序导致 401），body 留 undefined 让库自己读流；
+        // 预消费还会让非 JSON body 时库监听已结束的 end 事件而挂死。
         await bot.middleware({
             req: request,
             res: response,
-            request: { body: parsedBody },
+            request: { body: undefined },
         }, async () => undefined);
     }
     catch (error) {

package/lib/ws.d.ts

@@ -1,3 +1,4 @@
+import type { QqOutboundMessage } from './outbound.js';
 import type { QqInboundMessage, ResolvedQqWebsocketConfig } from './protocol.js';
 /** Minimal bot surface used by the endpoint (real qq-official-bot or test mock). */
 export interface QqBotTransport {
@@ -5,10 +6,10 @@ export interface QqBotTransport {
     stop(): Promise<void>;
     on(event: string, listener: (...args: unknown[]) => void): void;
     removeAllListeners(): void;
-    sendPrivateMessage(userId: string, message: string): Promise<unknown>;
-    sendGroupMessage(groupId: string, message: string): Promise<unknown>;
-    sendGuildMessage(channelId: string, message: string): Promise<unknown>;
-    sendDirectMessage?(guildId: string, message: string): Promise<unknown>;
+    sendPrivateMessage(userId: string, message: QqOutboundMessage): Promise<unknown>;
+    sendGroupMessage(groupId: string, message: QqOutboundMessage): Promise<unknown>;
+    sendGuildMessage(channelId: string, message: QqOutboundMessage): Promise<unknown>;
+    sendDirectMessage?(guildId: string, message: QqOutboundMessage): Promise<unknown>;
     getGuilds(): Promise<unknown[]>;
     getChannels(guildId: string): Promise<unknown[]>;
     getChannelInfo(channelId: string): Promise<unknown>;
@@ -19,6 +20,26 @@ export interface QqBotTransport {
     removeMemberRole(guildId: string, channelId: string, userId: string, roleId: string): Promise<boolean>;
 }
 export type CreateQqBot = (config: ResolvedQqWebsocketConfig) => QqBotTransport;
+interface QqOfficialBotLifecycle {
+    stop(): Promise<unknown>;
+    readonly sessionManager: {
+        userClose: boolean;
+        readonly connectionManager?: {
+            destroy(): void;
+        };
+        readonly authManager?: {
+            destroy(): void;
+        };
+    };
+}
+/**
+ * qq-official-bot 1.2.x keeps a second `userClose` flag in Connection.
+ * Session.stop() does not update it, so a normal shutdown is treated as an
+ * unexpected disconnect and starts a reconnect loop. Destroy both managers at
+ * the SDK boundary until upstream exposes a complete public shutdown method.
+ */
+export declare function stopQqOfficialBot(bot: QqOfficialBotLifecycle): Promise<void>;
 export declare function bindQqBotInboundEvents(bot: QqBotTransport, admitRaw: (raw: unknown) => void): void;
 export declare function normalizeQqMessage(raw: unknown): QqInboundMessage | null;
 export declare function defaultCreateBot(config: ResolvedQqWebsocketConfig): QqBotTransport;
+export {};

package/lib/ws.js

@@ -4,6 +4,23 @@
 import path from 'node:path';
 import { Bot, ReceiverMode } from 'qq-official-bot';
 import { getLevel, toLog4jsLevel } from '@zhin.js/logger';
+/**
+ * qq-official-bot 1.2.x keeps a second `userClose` flag in Connection.
+ * Session.stop() does not update it, so a normal shutdown is treated as an
+ * unexpected disconnect and starts a reconnect loop. Destroy both managers at
+ * the SDK boundary until upstream exposes a complete public shutdown method.
+ */
+export async function stopQqOfficialBot(bot) {
+    const session = bot.sessionManager;
+    session.userClose = true;
+    session.connectionManager?.destroy();
+    try {
+        await bot.stop();
+    }
+    finally {
+        session.authManager?.destroy();
+    }
+}
 export function bindQqBotInboundEvents(bot, admitRaw) {
     bot.on('message.group', admitRaw);
     bot.on('message.guild', admitRaw);
@@ -89,7 +106,7 @@ export function defaultCreateBot(config) {
     });
     return {
         start: () => bot.start().then(() => undefined),
-        stop: () => bot.stop().then(() => undefined),
+        stop: () => stopQqOfficialBot(bot),
         on: (event, listener) => {
             bot.on(event, listener);
         },