@zhin.js/adapter-qq 1.0.84 → 1.1.2

package/lib/protocol.d.ts

@@ -0,0 +1,90 @@
+/** QQ Official Bot protocol helpers. Canonicalization is owned by Core. */
+import type { ConversationRef } from '@zhin.js/im-contract';
+/** One endpoint config after AdapterIndex expands `plugins.<instanceKey>.endpoints`. */
+export interface QqEndpointConfig {
+    readonly id: string;
+    readonly appid: string;
+    readonly secret: string;
+    /** Default `websocket`. `webhook` / `middleware` use httpHostToken POST. */
+    readonly mode?: 'websocket' | 'webhook' | 'middleware';
+    readonly sandbox?: boolean;
+    /** Explicit intents; when omitted, derived from `botKind` (default public). */
+    readonly intents?: readonly string[];
+    /** public | private — drives default intents when `intents` omitted. */
+    readonly botKind?: string;
+    readonly accessTokenUrl?: string;
+    readonly gatewayUrl?: string;
+    readonly webhookPath?: string;
+}
+export interface ResolvedQqWebsocketConfig {
+    readonly context: 'qq';
+    readonly mode: 'websocket';
+    readonly id: string;
+    readonly appid: string;
+    readonly secret: string;
+    readonly sandbox: boolean;
+    readonly intents?: readonly string[];
+    readonly accessTokenUrl?: string;
+    readonly gatewayUrl?: string;
+}
+export interface ResolvedQqHttpConfig {
+    readonly context: 'qq';
+    readonly mode: 'webhook' | 'middleware';
+    readonly id: string;
+    readonly appid: string;
+    readonly secret: string;
+    readonly webhookPath: string;
+    readonly sandbox: boolean;
+}
+export type ResolvedQqConfig = ResolvedQqWebsocketConfig | ResolvedQqHttpConfig;
+export type QqChannelKind = 'private' | 'group' | 'channel' | 'direct';
+export interface QqInboundMessage {
+    readonly id: string;
+    readonly content: string;
+    readonly channelKind: QqChannelKind;
+    readonly channelId: string;
+    readonly authorId: string;
+    readonly authorName: string;
+    readonly authorRoles?: string[];
+    readonly timestamp: number;
+    readonly guildId?: string;
+    readonly rawMessage?: string;
+    /** canonical 入站段（text/mention/face/image/audio/video/file/reply），与 content 同源 */
+    readonly segments?: readonly import('@zhin.js/core').Segment[];
+    /**
+     * 入站是否 @ 当前机器人：统一按 mentions 判定。群场景只认 is_you（@ 另一个
+     * 机器人时 bot:true 但无 is_you，不误判）；bot 回退仅限频道 AT 事件。
+     * 群 GROUP_MESSAGE_CREATE 的非 @ 消息不置位。新 Runtime 纯文本 content 需经
+     * metadata 传递。
+     */
+    readonly mentioned?: boolean;
+}
+export interface QqWireSegment {
+    readonly type: string;
+    readonly data?: Record<string, unknown>;
+}
+export declare function resolveQqConfig(config: QqEndpointConfig): ResolvedQqConfig;
+/**
+ * 入站归一化 → ConversationRef：`direct`（频道私信）映射为 guild 容器内的
+ * private 会话；频道消息的所属 guild 进 `parent`。
+ */
+export declare function qqInboundConversation(endpointKey: string, msg: QqInboundMessage): ConversationRef;
+/** 出站：guild 容器内的 private 会话即 QQ `direct`（频道私信）。 */
+export declare function qqOutboundKind(conversation: ConversationRef): QqChannelKind;
+export declare function senderDisplayName(msg: QqInboundMessage): string;
+export declare function formatInboundContent(msg: QqInboundMessage): string;
+/**
+ * Wire-encode an already-rendered outbound payload into a plain text / QQ Sendable string.
+ * Segment canonicalization is intentionally not done here.
+ */
+export declare function formatOutboundText(payload: unknown): string;
+/**
+ * Parse a compound messageId produced by `send()`: `kind-channelId:qqMsgId`.
+ */
+export declare function parseCompoundMessageId(messageId: string): {
+    kind: QqChannelKind;
+    channelId: string;
+    qqMsgId: string;
+};
+/** 从 QQ API SendResult / 审核回包中解析出站消息 ID */
+export declare function resolveOutboundMessageId(result: unknown): string;

package/lib/protocol.js

@@ -0,0 +1,161 @@
+/** QQ Official Bot protocol helpers. Canonicalization is owned by Core. */
+import { formatCompact, getLogger } from '@zhin.js/logger';
+import { resolveQqIntents } from './qq-intents.js';
+const logger = getLogger('qq');
+export function resolveQqConfig(config) {
+    const id = requiredEndpointField(config.id, 'id');
+    const appid = requiredEndpointField(config.appid, 'appid');
+    const secret = requiredEndpointField(config.secret, 'secret');
+    const mode = config.mode ?? 'websocket';
+    if (mode === 'webhook' || mode === 'middleware') {
+        const webhookPathRaw = config.webhookPath ?? '/qq/webhook';
+        const webhookPath = webhookPathRaw.startsWith('/') ? webhookPathRaw : `/${webhookPathRaw}`;
+        return {
+            context: 'qq',
+            mode,
+            id,
+            appid,
+            secret,
+            webhookPath,
+            sandbox: config.sandbox === true,
+        };
+    }
+    return {
+        context: 'qq',
+        mode: 'websocket',
+        id,
+        appid,
+        secret,
+        sandbox: config.sandbox === true,
+        intents: resolveQqIntents({
+            intents: config.intents,
+            botKind: config.botKind,
+        }),
+        accessTokenUrl: config.accessTokenUrl,
+        gatewayUrl: config.gatewayUrl,
+    };
+}
+function requiredEndpointField(value, field) {
+    if (typeof value !== 'string' || !value.trim()) {
+        throw new TypeError(`QQ endpoint requires a non-empty ${field}`);
+    }
+    return value.trim();
+}
+/**
+ * 入站归一化 → ConversationRef：`direct`（频道私信）映射为 guild 容器内的
+ * private 会话；频道消息的所属 guild 进 `parent`。
+ */
+export function qqInboundConversation(endpointKey, msg) {
+    const kind = msg.channelKind === 'direct' ? 'private' : msg.channelKind;
+    return {
+        endpoint: { id: endpointKey, adapter: endpointKey.split('\0')[0] ?? endpointKey },
+        kind,
+        id: msg.channelId,
+        ...(msg.guildId && (msg.channelKind === 'channel' || msg.channelKind === 'direct')
+            ? { parent: { kind: 'channel', id: msg.guildId } }
+            : {}),
+    };
+}
+/** 出站：guild 容器内的 private 会话即 QQ `direct`（频道私信）。 */
+export function qqOutboundKind(conversation) {
+    if (conversation.kind === 'private' && conversation.parent?.kind === 'channel')
+        return 'direct';
+    return conversation.kind;
+}
+export function senderDisplayName(msg) {
+    return msg.authorName || msg.authorId;
+}
+export function formatInboundContent(msg) {
+    const text = (msg.content || msg.rawMessage || '').trim();
+    return text || '(Empty message)';
+}
+/**
+ * Wire-encode an already-rendered outbound payload into a plain text / QQ Sendable string.
+ * Segment canonicalization is intentionally not done here.
+ */
+export function formatOutboundText(payload) {
+    if (typeof payload === 'string')
+        return payload;
+    const segments = Array.isArray(payload)
+        ? payload
+        : payload && typeof payload === 'object' && 'type' in payload
+            ? [payload]
+            : [];
+    if (segments.length === 0) {
+        return payload == null
+            ? ''
+            : typeof payload === 'object'
+                ? JSON.stringify(payload)
+                : String(payload);
+    }
+    return segments
+        .map((item) => {
+        if (typeof item === 'string')
+            return item;
+        const data = item.data ?? {};
+        switch (item.type) {
+            case 'text':
+                return String(data.text ?? data.content ?? '');
+            case 'at': {
+                const id = String(data.user_id ?? data.qq ?? data.id ?? '');
+                return id ? `<@!${id}>` : '';
+            }
+            case 'image': {
+                const src = String(data.url || data.file || '');
+                // base64/本地路径由 formatOutbound 走媒体上传，文本视图静默省略；
+                // 仅当彻底缺少来源时留痕，避免出站静默降级排障无头绪。
+                if (!src) {
+                    logger.warn(formatCompact({
+                        op: 'qq_outbound_image_dropped',
+                        reason: 'missing_source',
+                    }));
+                    return '';
+                }
+                return /^https?:\/\//.test(src) ? src : '';
+            }
+            case 'reply':
+                return '';
+            default:
+                return data.text != null ? String(data.text) : '';
+        }
+    })
+        .filter(Boolean)
+        .join('');
+}
+/**
+ * Parse a compound messageId produced by `send()`: `kind-channelId:qqMsgId`.
+ */
+export function parseCompoundMessageId(messageId) {
+    const hyphen = messageId.indexOf('-');
+    if (hyphen <= 0)
+        throw new Error(`invalid QQ messageId format: ${messageId}`);
+    const kind = messageId.slice(0, hyphen);
+    if (kind !== 'private' && kind !== 'group' && kind !== 'channel' && kind !== 'direct') {
+        throw new Error(`invalid QQ messageId kind: ${kind}`);
+    }
+    const rest = messageId.slice(hyphen + 1);
+    const colon = rest.indexOf(':');
+    if (colon <= 0)
+        throw new Error(`invalid QQ messageId format: ${messageId}`);
+    return { kind, channelId: rest.slice(0, colon), qqMsgId: rest.slice(colon + 1) };
+}
+/** 从 QQ API SendResult / 审核回包中解析出站消息 ID */
+export function resolveOutboundMessageId(result) {
+    if (!result || typeof result !== 'object') {
+        throw new Error('QQ 发送消息失败：响应为空');
+    }
+    const row = result;
+    const nested = row.data && typeof row.data === 'object'
+        ? row.data
+        : undefined;
+    const audit = (row.message_audit ?? nested?.message_audit);
+    const id = row.id ?? row.message_id ?? audit?.audit_id;
+    if (id == null || id === '') {
+        const code = row.code;
+        const msg = row.message;
+        throw new Error(code != null
+            ? `QQ 发送消息失败（${String(code)}）${msg ? `: ${String(msg)}` : ''}`
+            : 'QQ 发送消息失败：响应缺少消息 ID');
+    }
+    return String(id);
+}

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-bot-kind-prompt.d.ts

@@ -0,0 +1,9 @@
+import { type QqBotKind } from './qq-intents.js';
+/** 从命令/中间件入站消息提取会话键；无法识别时返回 undefined。 */
+export declare function qqCommandSessionKey(input: unknown): string | undefined;
+/**
+ * 解析用户对公域/私域的回复。
+ * 接受：public / private / 公域 / 私域（大小写不敏感，可带前后空白）。
+ */
+export declare function parseQqBotKindAnswer(raw: unknown): QqBotKind | undefined;
+export declare const QQ_BOT_KIND_PROMPT: string;

package/lib/qq-bot-kind-prompt.js

@@ -0,0 +1,37 @@
+import { parseQqBotKind } from './qq-intents.js';
+/** 从命令/中间件入站消息提取会话键；无法识别时返回 undefined。 */
+export function qqCommandSessionKey(input) {
+    const message = input;
+    const conversation = message?.conversation;
+    const adapter = conversation?.endpoint?.adapter;
+    const endpointKey = conversation?.endpoint?.id;
+    const kind = conversation?.kind;
+    const id = conversation?.id;
+    const sender = message?.sender;
+    if (adapter == null
+        || endpointKey == null
+        || (kind !== 'private' && kind !== 'group' && kind !== 'channel')
+        || typeof id !== 'string'
+        || !id
+        || sender == null
+        || String(sender).trim() === '') {
+        return undefined;
+    }
+    return `${String(adapter)}\0${String(endpointKey)}\0${kind}\0${id}\0${String(sender).trim()}`;
+}
+/**
+ * 解析用户对公域/私域的回复。
+ * 接受：public / private / 公域 / 私域（大小写不敏感，可带前后空白）。
+ */
+export function parseQqBotKindAnswer(raw) {
+    const text = String(raw ?? '').trim().toLowerCase();
+    if (!text)
+        return undefined;
+    if (text === '公域' || text === '公开' || text === '1')
+        return 'public';
+    if (text === '私域' || text === '2')
+        return 'private';
+    return parseQqBotKind(text);
+}
+export const QQ_BOT_KIND_PROMPT = '请回复 public（公域）或 private（私域），确认后一次性写入 .env 与配置。\n'
+    + '也可发 qq endpoint cancel 取消。';

package/lib/qq-intents.d.ts

@@ -0,0 +1,27 @@
+/**
+ * QQ 官方机器人 intents 与公域/私域映射。
+ *
+ * 群聊无公/私域之分，两类都订阅 `GROUP_AND_C2C_EVENT`。
+ * 频道消息 intent 不同：
+ * - public（公域）：`PUBLIC_GUILD_MESSAGES`（仅 @ 机器人）
+ * - private（私域）：`GUILD_MESSAGES`（频道全量消息；公域订阅会 Identify 失败）
+ */
+export type QqBotKind = 'public' | 'private';
+export type QqIntent = 'GUILDS' | 'GUILD_MEMBERS' | 'GUILD_MESSAGES' | 'GUILD_MESSAGE_REACTIONS' | 'DIRECT_MESSAGE' | 'GROUP_AND_C2C_EVENT' | 'INTERACTION' | 'MESSAGE_AUDIT' | 'FORUMS_EVENT' | 'AUDIO_ACTION' | 'PUBLIC_GUILD_MESSAGES' | 'GROUP_MEMBER';
+/** 扫码绑定 / 未声明 botKind 时的默认（公域更常见）。 */
+export declare const DEFAULT_QQ_BOT_KIND: QqBotKind;
+export declare const QQ_INTENTS_BY_KIND: Readonly<Record<QqBotKind, readonly QqIntent[]>>;
+/** 解析 botKind：仅接受 `public` / `private`。 */
+export declare function parseQqBotKind(value: unknown): QqBotKind | undefined;
+/**
+ * 解析最终 intents：显式 `intents` 优先；否则按 `botKind`（默认 public）展开。
+ */
+export declare function resolveQqIntents(input: {
+    readonly intents?: readonly string[] | undefined;
+    readonly botKind?: unknown;
+}): readonly QqIntent[];
+/** 添加 endpoint 时写入配置的默认字段（显式展开，便于用户改）。 */
+export declare function defaultQqEndpointIntentFields(botKind?: QqBotKind): {
+    readonly botKind: QqBotKind;
+    readonly intents: readonly QqIntent[];
+};

package/lib/qq-intents.js

@@ -0,0 +1,51 @@
+/**
+ * QQ 官方机器人 intents 与公域/私域映射。
+ *
+ * 群聊无公/私域之分，两类都订阅 `GROUP_AND_C2C_EVENT`。
+ * 频道消息 intent 不同：
+ * - public（公域）：`PUBLIC_GUILD_MESSAGES`（仅 @ 机器人）
+ * - private（私域）：`GUILD_MESSAGES`（频道全量消息；公域订阅会 Identify 失败）
+ */
+/** 扫码绑定 / 未声明 botKind 时的默认（公域更常见）。 */
+export const DEFAULT_QQ_BOT_KIND = 'public';
+/** 公/私域共用：群/C2C、群成员变更、频道基础事件、频道私信。 */
+const QQ_SHARED_INTENTS = Object.freeze([
+    'GROUP_AND_C2C_EVENT',
+    'GROUP_MEMBER',
+    'GUILDS',
+    'GUILD_MEMBERS',
+    'DIRECT_MESSAGE',
+]);
+export const QQ_INTENTS_BY_KIND = Object.freeze({
+    public: Object.freeze([
+        ...QQ_SHARED_INTENTS,
+        'PUBLIC_GUILD_MESSAGES',
+    ]),
+    private: Object.freeze([
+        ...QQ_SHARED_INTENTS,
+        'GUILD_MESSAGES',
+    ]),
+});
+/** 解析 botKind：仅接受 `public` / `private`。 */
+export function parseQqBotKind(value) {
+    if (value === 'public' || value === 'private')
+        return value;
+    return undefined;
+}
+/**
+ * 解析最终 intents：显式 `intents` 优先；否则按 `botKind`（默认 public）展开。
+ */
+export function resolveQqIntents(input) {
+    if (Array.isArray(input.intents) && input.intents.length > 0) {
+        return Object.freeze(input.intents.map(String));
+    }
+    const kind = parseQqBotKind(input.botKind) ?? DEFAULT_QQ_BOT_KIND;
+    return QQ_INTENTS_BY_KIND[kind];
+}
+/** 添加 endpoint 时写入配置的默认字段（显式展开，便于用户改）。 */
+export function defaultQqEndpointIntentFields(botKind = DEFAULT_QQ_BOT_KIND) {
+    return Object.freeze({
+        botKind,
+        intents: QQ_INTENTS_BY_KIND[botKind],
+    });
+}

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

@@ -0,0 +1,30 @@
+export interface QqRunningEndpoint {
+    id: string;
+    mode: string;
+}
+export interface QqBindFlowHandle {
+    /** 绑定期望的 endpoint id（未指定时为 undefined，成功后取 appId） */
+    id?: string;
+    stop: () => void;
+}
+/**
+ * 扫码成功后暂存在内存：确认公域/私域后再一次性写 .env + yaml。
+ * （提前写 .env 会触发 HMR，冲掉 pending。）
+ */
+export interface QqPendingBotKind {
+    readonly endpointId: string;
+    readonly appId: string;
+    readonly appSecret: string;
+    /** 发起 add 的会话键；仅同会话回复可完成选择 */
+    readonly sessionKey: string;
+}
+export interface QqRuntimeState {
+    /** 当前 generation 已成功创建的 endpoint（id → 描述） */
+    readonly endpoints: Map<string, QqRunningEndpoint>;
+    /** 全局单例：同一时间只允许一个扫码绑定流程 */
+    bindFlow: QqBindFlowHandle | null;
+    /** 扫码完成后等待 botKind 选择（凭据仅在内存） */
+    pendingBotKind: QqPendingBotKind | null;
+}
+export declare function createQqRuntimeState(): QqRuntimeState;
+export declare const qqRuntimeStateToken: import("zhin.js").Token<QqRuntimeState>;

package/lib/qq-runtime-state.js

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

package/lib/side-event-dispatch.d.ts

@@ -0,0 +1,10 @@
+import type { EndpointEventEmitter } from 'zhin.js/adapter';
+import { type getAdapterLogger } from '@zhin.js/logger';
+import type { ApproveJoinRequestOptions } from 'qq-official-bot';
+export interface QqSideEventCaller {
+    approveGroupJoinRequest?(groupId: string, userId: string, options: ApproveJoinRequestOptions): Promise<unknown>;
+}
+export declare function bindQqBotSideEvents(bot: {
+    on(event: string, listener: (...args: unknown[]) => void): void;
+}, dispatch: (eventName: string, raw: unknown) => void): void;
+export declare function receiveQqSideEvent(emit: EndpointEventEmitter, endpointKey: string, caller: QqSideEventCaller, eventName: string, raw: unknown, logger: ReturnType<typeof getAdapterLogger>): void;