@zhin.js/adapter-qq 1.0.83 → 1.1.0

package/lib/protocol.d.ts

@@ -0,0 +1,111 @@
+/**
+ * QQ Official Bot protocol helpers — no legacy Adapter/Endpoint / segment-mapper.
+ * Canonicalization is owned by gateway/core before endpoint.send.
+ */
+import type { ConversationRef } from '@zhin.js/im-contract';
+/** Plugin Runtime owner config (`plugins.<instanceKey>` / schema.json). */
+export interface QqAdapterConfig {
+    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;
+    readonly port?: number;
+    readonly path?: string;
+    /** Transitional: legacy root `endpoints[]` with `context: qq`. */
+    readonly endpoints?: ReadonlyArray<{
+        readonly context?: string;
+        readonly id?: string;
+        readonly appid?: string;
+        readonly secret?: string;
+        readonly mode?: 'websocket' | 'webhook' | 'middleware';
+        readonly sandbox?: boolean;
+        readonly intents?: readonly string[];
+        readonly botKind?: string;
+        readonly accessTokenUrl?: string;
+        readonly gatewayUrl?: string;
+        readonly webhookPath?: string;
+        readonly port?: number;
+        readonly path?: 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?: QqAdapterConfig): 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,166 @@
+/**
+ * QQ Official Bot protocol helpers — no legacy Adapter/Endpoint / segment-mapper.
+ * Canonicalization is owned by gateway/core before endpoint.send.
+ */
+import { pickCredential } from 'zhin.js/adapter';
+import { formatCompact, getLogger } from '@zhin.js/logger';
+import { resolveQqIntents } from './qq-intents.js';
+const logger = getLogger('qq');
+export function resolveQqConfig(config = {}) {
+    const entry = config.endpoints?.find((item) => item.context === 'qq' || !item.context);
+    const appid = pickCredential(config.appid, entry?.appid, process.env.QQ_APPID, process.env.QQ_BOT_APPID);
+    const secret = pickCredential(config.secret, entry?.secret, process.env.QQ_SECRET, process.env.QQ_BOT_SECRET);
+    if (!appid || !secret) {
+        throw new TypeError('QQ adapter requires appid + secret (plugins.<key>.appid/secret or endpoints with context: qq)');
+    }
+    const id = (typeof config.id === 'string' && config.id)
+        || (typeof entry?.id === 'string' && entry.id)
+        || process.env.QQ_BOT_NAME
+        || 'qq-bot';
+    const mode = config.mode ?? entry?.mode ?? 'websocket';
+    if (mode === 'webhook' || mode === 'middleware') {
+        const webhookPathRaw = config.webhookPath ?? entry?.webhookPath ?? '/qq/webhook';
+        const webhookPath = webhookPathRaw.startsWith('/') ? webhookPathRaw : `/${webhookPathRaw}`;
+        return {
+            context: 'qq',
+            mode,
+            id,
+            appid,
+            secret,
+            webhookPath,
+            sandbox: config.sandbox === true || entry?.sandbox === true,
+        };
+    }
+    return {
+        context: 'qq',
+        mode: 'websocket',
+        id,
+        appid,
+        secret,
+        sandbox: config.sandbox === true || entry?.sandbox === true,
+        intents: resolveQqIntents({
+            intents: config.intents ?? entry?.intents,
+            botKind: config.botKind ?? entry?.botKind,
+        }),
+        accessTokenUrl: config.accessTokenUrl ?? entry?.accessTokenUrl,
+        gatewayUrl: config.gatewayUrl ?? entry?.gatewayUrl,
+    };
+}
+/**
+ * 入站归一化 → 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-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(endpointId: string): QqCredentialEnvKeys;
+/** 写入或更新 `.env` 中的键值，并同步到当前进程 `process.env` */
+export declare function persistQqCredentialsToEnv(endpointId: 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(endpointId) {
+    const appidKey = buildEndpointEnvKey('qq', endpointId, 'appid');
+    const secretKey = buildEndpointEnvKey('qq', endpointId, 'secret');
+    return {
+        appidKey,
+        secretKey,
+        appidRef: `\${${appidKey}}`,
+        secretRef: `\${${secretKey}}`,
+    };
+}
+/** 写入或更新 `.env` 中的键值，并同步到当前进程 `process.env` */
+export function persistQqCredentialsToEnv(endpointId, appId, appSecret, projectRoot) {
+    const keys = buildQqCredentialEnvKeys(endpointId);
+    persistEndpointEnvValues({
+        [keys.appidKey]: appId,
+        [keys.secretKey]: appSecret,
+    }, projectRoot);
+    return keys;
+}

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-endpoint-commands.d.ts

@@ -0,0 +1,45 @@
+/**
+ * `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 QqBotKind } from './qq-intents.js';
+import { type QqPendingBotKind, 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;
+/**
+ * 完成 pending 的公域/私域选择：一次性写 .env + yaml。
+ * @returns 成功文案；调用方负责清 pending。
+ */
+export declare function completeQqPendingBotKind(pending: QqPendingBotKind, botKind: QqBotKind, projectRoot?: string): string;
+/**
+ * `qq.endpoint add [id]`：启动扫码绑定流程。
+ * 返回的 Promise 在二维码链接就绪（或前置失败）时 resolve 为首条回复；
+ * 后续状态（已扫码 / 成功 / 失败 / 过期刷新）通过 reply 推回当前会话。
+ * 扫码成功后凭据暂存内存并询问公域/私域；确认后一次性写 .env + yaml。
+ */
+export declare function runQqEndpointAdd(state: QqRuntimeState, id: string | undefined, reply: QqCommandReply, projectRoot?: string, input?: unknown): Promise<string>;
+/** `qq.endpoint cancel`：中止进行中的绑定或待选 botKind */
+export declare function runQqEndpointCancel(state: QqRuntimeState): string;
+/** `qq.endpoint remove <id>`：从 zhin.config.yml 移除对应 endpoints 项 */
+export declare function runQqEndpointRemove(_state: QqRuntimeState, id: 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, string | undefined>>>;