@zhin.js/adapter-qq 1.0.84 → 1.1.2

package/lib/side-event-dispatch.js

@@ -0,0 +1,114 @@
+import { receiveOneBotLikeSideEvent } from '@zhin.js/core';
+import { formatCompact } from '@zhin.js/logger';
+export function bindQqBotSideEvents(bot, dispatch) {
+    // qq-official-bot emits every dotted prefix. Listening at `notice` once avoids
+    // dispatching e.g. notice.group.member.increase three times.
+    bot.on('notice', (raw) => dispatch(resolveQqSideEventName(raw), raw));
+}
+function resolveQqSideEventName(raw) {
+    if (!raw || typeof raw !== 'object')
+        return 'notice';
+    const record = raw;
+    return ['notice', record.notice_type, record.sub_type]
+        .filter((part) => part != null && String(part) !== '')
+        .map(String)
+        .join('.');
+}
+function toOneBotLikeRaw(eventName, raw) {
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const record = raw;
+    const asId = (value) => {
+        if (typeof value === 'string' || typeof value === 'number')
+            return value;
+        return undefined;
+    };
+    const asTime = (value) => {
+        const n = typeof value === 'number' ? value : Number(value);
+        if (Number.isFinite(n) && n > 0)
+            return n;
+        const date = typeof value === 'string' ? Date.parse(value) : Number.NaN;
+        return Number.isFinite(date) ? date : Date.now();
+    };
+    if (eventName === 'notice.group.join_request') {
+        return {
+            ...record,
+            post_type: 'request',
+            request_type: 'group',
+            flag: record.join_request_id != null ? String(record.join_request_id) : undefined,
+            user_id: asId(record.user_id),
+            group_id: asId(record.group_id),
+            comment: formatJoinRequestComment(record.verify_info),
+            time: asTime(record.time ?? record.timestamp ?? record.apply_at),
+        };
+    }
+    if (eventName.startsWith('notice.')) {
+        const memberChange = eventName.match(/^notice\.group(?:\.member)?\.(increase|decrease)$/);
+        const memberUserId = asId(record.user_id)
+            ?? asId(record.bot?.self_id);
+        return {
+            ...record,
+            post_type: 'notice',
+            notice_type: memberChange ? `group_${memberChange[1]}` : eventName.replace(/^notice\./, ''),
+            ...(memberChange && memberUserId != null ? { user_id: memberUserId } : {}),
+            time: asTime(record.time ?? record.timestamp),
+        };
+    }
+    return null;
+}
+function formatJoinRequestComment(value) {
+    if (typeof value === 'string')
+        return value;
+    if (!value || typeof value !== 'object')
+        return undefined;
+    const verify = value;
+    if (typeof verify.verify_message === 'string')
+        return verify.verify_message;
+    if (!Array.isArray(verify.review_qa_list))
+        return undefined;
+    const lines = verify.review_qa_list.flatMap((item) => {
+        const question = typeof item?.question === 'string' ? item.question : '';
+        const answer = typeof item?.answer === 'string' ? item.answer : '';
+        return question || answer ? [`${question}${question && answer ? ': ' : ''}${answer}`] : [];
+    });
+    return lines.length > 0 ? lines.join('\n') : undefined;
+}
+export function receiveQqSideEvent(emit, endpointKey, caller, eventName, raw, logger) {
+    if (!emit)
+        return;
+    const mapped = toOneBotLikeRaw(eventName, raw);
+    if (!mapped)
+        return;
+    const isJoinRequest = eventName === 'notice.group.join_request';
+    const joinRaw = isJoinRequest && raw && typeof raw === 'object'
+        ? raw
+        : undefined;
+    void receiveOneBotLikeSideEvent(emit, {
+        adapter: 'qq',
+        endpointKey,
+        platform: 'qq',
+        raw: mapped,
+        ...(isJoinRequest && caller.approveGroupJoinRequest && joinRaw ? {
+            approve: async (flag, remark) => {
+                await caller.approveGroupJoinRequest(String(joinRaw.group_id ?? ''), String(joinRaw.user_id ?? ''), {
+                    op: 'approve',
+                    join_request_id: String(joinRaw.join_request_id ?? flag),
+                });
+            },
+            reject: async (flag, reason) => {
+                await caller.approveGroupJoinRequest(String(joinRaw.group_id ?? ''), String(joinRaw.user_id ?? ''), {
+                    op: 'decline',
+                    join_request_id: String(joinRaw.join_request_id ?? flag),
+                    ...(reason ? { reject_reason: reason } : {}),
+                });
+            },
+        } : {}),
+    }).catch((err) => {
+        logger.warn(formatCompact({
+            op: 'qq_side_event_failed',
+            endpoint: endpointKey,
+            event: eventName,
+            error: err instanceof Error ? err.message : String(err),
+        }));
+    });
+}

package/lib/webhook.d.ts

@@ -0,0 +1,18 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { HttpHost, HttpRouteRegistration } from '@zhin.js/host-http';
+import type { ResolvedQqHttpConfig } from './protocol.js';
+import type { QqBotTransport } from './ws.js';
+export type QqHttpBotTransport = QqBotTransport & {
+    middleware: (ctx: unknown, next: () => Promise<void>) => Promise<unknown>;
+};
+export type CreateQqHttpBot = (config: ResolvedQqHttpConfig) => QqHttpBotTransport;
+export interface QqWebhookHandler {
+    readonly config: ResolvedQqHttpConfig;
+    getBot(): (QqHttpBotTransport & {
+        middleware?: QqHttpBotTransport['middleware'];
+    }) | null;
+}
+export declare function registerQqWebhookRoutes(http: HttpHost, handler: QqWebhookHandler): HttpRouteRegistration[];
+export declare function handleQqWebhookRequest(request: IncomingMessage, response: ServerResponse, handler: QqWebhookHandler): Promise<void>;
+export declare function readRequestBodyText(request: IncomingMessage): Promise<string>;
+export declare function defaultCreateHttpBot(config: ResolvedQqHttpConfig): QqHttpBotTransport;

package/lib/webhook.js

@@ -0,0 +1,103 @@
+/**
+ * QQ HTTP webhook / middleware inbound via httpHostToken POST.
+ */
+import path from 'node:path';
+import { Bot, ReceiverMode } from 'qq-official-bot';
+import { getLogger } from '@zhin.js/logger';
+const logger = getLogger('qq');
+export function registerQqWebhookRoutes(http, handler) {
+    const webhookPath = handler.config.webhookPath;
+    return [
+        http.route('POST', webhookPath, async (request, response) => {
+            await handleQqWebhookRequest(request, response, handler);
+        }, { summary: 'QQ webhook callback', tags: ['qq'] }),
+    ];
+}
+export async function handleQqWebhookRequest(request, response, handler) {
+    const bot = handler.getBot();
+    if (!bot?.middleware) {
+        response.writeHead(503, { 'Content-Type': 'text/plain' });
+        response.end('QQ receiver not ready');
+        return;
+    }
+    try {
+        // 不预消费请求流：库的验签必须基于原始字节（JSON.parse → JSON.stringify
+        // 会改变空白/转义/键序导致 401），body 留 undefined 让库自己读流；
+        // 预消费还会让非 JSON body 时库监听已结束的 end 事件而挂死。
+        await bot.middleware({
+            req: request,
+            res: response,
+            request: { body: undefined },
+        }, async () => undefined);
+    }
+    catch (error) {
+        logger.error('QQ webhook error:', error);
+        if (!response.headersSent) {
+            response.writeHead(500, { 'Content-Type': 'text/plain' });
+            response.end('Internal Server Error');
+        }
+    }
+}
+export async function readRequestBodyText(request) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of request) {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        size += buffer.length;
+        if (size > 1_048_576) {
+            request.destroy();
+            throw new Error('Request body exceeds 1MB');
+        }
+        chunks.push(buffer);
+    }
+    return Buffer.concat(chunks).toString('utf8');
+}
+export function defaultCreateHttpBot(config) {
+    const bot = new Bot({
+        appid: config.appid,
+        secret: config.secret,
+        mode: ReceiverMode.MIDDLEWARE,
+        platform: 'koa',
+        sandbox: config.sandbox,
+        dataDir: path.join(process.cwd(), 'data', 'qq'),
+        // 关闭内置 log4js，与 WebSocket 模式一致走 zhin adapter logger
+        logLevel: 'off',
+    });
+    return {
+        api: bot,
+        start: () => bot.start().then(() => undefined),
+        stop: () => bot.stop().then(() => undefined),
+        on: (event, listener) => {
+            bot.on(event, listener);
+        },
+        removeAllListeners: () => {
+            bot.removeAllListeners(undefined);
+        },
+        sendPrivateMessage: (userId, message) => bot.sendPrivateMessage(userId, message),
+        sendGroupMessage: (groupId, message) => bot.sendGroupMessage(groupId, message),
+        sendGuildMessage: (channelId, message) => bot.sendGuildMessage(channelId, message),
+        sendDirectMessage: (guildId, message) => bot.sendDirectMessage(guildId, message),
+        recallPrivateMessage: (userId, messageId) => bot.recallPrivateMessage(userId, messageId),
+        recallGroupMessage: (groupId, messageId) => bot.recallGroupMessage(groupId, messageId),
+        recallGuildMessage: (channelId, messageId) => bot.recallGuildMessage(channelId, messageId),
+        recallDirectMessage: (guildId, messageId) => bot.recallDirectMessage(guildId, messageId),
+        getGuilds: () => bot.guildService.getList(),
+        getChannels: (guildId) => bot.channelService.getList(guildId),
+        getChannelInfo: (channelId) => bot.channelService.getInfo(channelId),
+        getGuildMember: (guildId, userId) => bot.memberService.getGuildMemberInfo(guildId, userId),
+        getGuildRoles: (guildId) => bot.guildService.getRoles(guildId),
+        createGuildRole: (guildId, name, color) => bot.guildService.createRole(guildId, { name, color: color || 0, hoist: 0 }),
+        addMemberRole: async (guildId, channelId, userId, roleId) => {
+            await bot.memberService.addMemberRole(guildId, channelId, userId, roleId);
+            return true;
+        },
+        removeMemberRole: async (guildId, channelId, userId, roleId) => {
+            await bot.memberService.removeMemberRole(guildId, channelId, userId, roleId);
+            return true;
+        },
+        approveGroupJoinRequest: (groupId, userId, options) => bot
+            .approveGroupJoinRequest?.(groupId, userId, options)
+            ?? Promise.reject(new Error('approveGroupJoinRequest is not available')),
+        middleware: (ctx, next) => bot.middleware(ctx, next),
+    };
+}

package/lib/ws.d.ts

@@ -0,0 +1,55 @@
+import { Bot, type ApproveJoinRequestOptions } from 'qq-official-bot';
+import type { QqOutboundMessage } from './outbound.js';
+import type { QqInboundMessage, ResolvedQqWebsocketConfig } from './protocol.js';
+/** SDK business surface exposed to plugins without bypassing Endpoint lifecycle ownership. */
+export type QqOfficialApi = Pick<Bot, 'messageService' | 'fileProcessor' | 'guildService' | 'channelService' | 'memberService' | 'permissionService' | 'reactionService' | 'scheduleService' | 'threadService' | 'audioService' | 'botService' | 'groupService' | 'menuPanelService' | 'group' | 'user' | 'channel' | 'direct' | 'guild'>;
+/** Minimal bot surface used by the endpoint (real qq-official-bot or test mock). */
+export interface QqBotTransport {
+    /** Full qq-official-bot business API; lifecycle remains owned by the Endpoint. */
+    readonly api: QqOfficialApi;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    on(event: string, listener: (...args: unknown[]) => void): void;
+    removeAllListeners(): void;
+    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>;
+    recallPrivateMessage?(userId: string, messageId: string): Promise<unknown>;
+    recallGroupMessage?(groupId: string, messageId: string): Promise<unknown>;
+    recallGuildMessage?(channelId: string, messageId: string): Promise<unknown>;
+    recallDirectMessage?(guildId: string, messageId: string): Promise<unknown>;
+    getGuilds(): Promise<unknown[]>;
+    getChannels(guildId: string): Promise<unknown[]>;
+    getChannelInfo(channelId: string): Promise<unknown>;
+    getGuildMember(guildId: string, userId: string): Promise<unknown>;
+    getGuildRoles(guildId: string): Promise<unknown[]>;
+    createGuildRole(guildId: string, name: string, color?: number): Promise<unknown>;
+    addMemberRole(guildId: string, channelId: string, userId: string, roleId: string): Promise<boolean>;
+    removeMemberRole(guildId: string, channelId: string, userId: string, roleId: string): Promise<boolean>;
+    approveGroupJoinRequest?(groupId: string, userId: string, options: ApproveJoinRequestOptions): Promise<unknown>;
+}
+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 used a separate connection manager; 1.3 moved WebSocket
+ * ownership into the receiver, but Session.stop() still leaves the auth refresh
+ * manager alive. Mark the session closed, clean up legacy connections when
+ * present, stop the receiver, then destroy auth refresh at the SDK boundary.
+ */
+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

@@ -0,0 +1,234 @@
+/**
+ * QQ WebSocket transport: bot factory and inbound message normalization.
+ */
+import path from 'node:path';
+import { Bot, ReceiverMode, } from 'qq-official-bot';
+/**
+ * qq-official-bot 1.2 used a separate connection manager; 1.3 moved WebSocket
+ * ownership into the receiver, but Session.stop() still leaves the auth refresh
+ * manager alive. Mark the session closed, clean up legacy connections when
+ * present, stop the receiver, then destroy auth refresh at the SDK boundary.
+ */
+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);
+    bot.on('message.private', admitRaw);
+}
+export function normalizeQqMessage(raw) {
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const msg = raw;
+    if (msg.message_id == null)
+        return null;
+    let channelKind = 'private';
+    let channelId = '';
+    const isGroup = msg.message_type === 'group'
+        || (msg.message_type == null && (msg.group_id != null || msg.group_openid != null));
+    const isGuild = msg.message_type === 'guild'
+        || (msg.message_type == null && !isGroup && msg.guild_id != null && msg.channel_id != null);
+    if (isGuild) {
+        channelKind = msg.sub_type === 'direct' ? 'direct' : 'channel';
+        channelId = channelKind === 'direct'
+            ? String(msg.guild_id ?? '')
+            : String(msg.channel_id ?? '');
+    }
+    else if (isGroup) {
+        channelKind = 'group';
+        channelId = String(msg.group_id ?? msg.group_openid ?? '');
+    }
+    else {
+        channelKind = 'private';
+        channelId = String(msg.user_id ?? msg.author?.user_openid ?? msg.author?.id ?? '');
+    }
+    if (!channelId)
+        return null;
+    const authorId = String(msg.sender?.user_id
+        ?? msg.user_id
+        ?? msg.author?.member_openid
+        ?? msg.author?.user_openid
+        ?? msg.author?.id
+        ?? '');
+    const content = extractTextContent(msg.message) || msg.raw_message || '';
+    const segments = extractCanonicalSegments(msg.message);
+    const rawRoles = msg.member?.roles ?? msg.sender?.roles;
+    const authorRoles = Array.isArray(rawRoles) ? rawRoles.map(String) : undefined;
+    // 统一按 mentions 判定 @：is_you 精确标识当前机器人（群载荷实测字段）。
+    // 群里 @ 另一个机器人时 mentions 带 bot:true 但无 is_you，不能误判为 @ 当前机器人，
+    // 故群场景只认 is_you；bot 回退仅限频道 AT_MESSAGE_CREATE（该事件仅 @ 当前
+    // 机器人时下发，其 mentions 无 is_you）。
+    const mentioned = Array.isArray(msg.mentions)
+        && msg.mentions.some((m) => m?.is_you === true || (m?.bot === true && channelKind !== 'group'));
+    return {
+        id: String(msg.message_id),
+        content,
+        channelKind,
+        channelId,
+        authorId,
+        authorName: msg.sender?.user_name || msg.author?.username || authorId,
+        authorRoles,
+        timestamp: Date.now(),
+        guildId: msg.guild_id != null ? String(msg.guild_id) : undefined,
+        rawMessage: msg.raw_message,
+        ...(segments.length > 0 ? { segments } : {}),
+        ...(mentioned ? { mentioned: true } : {}),
+    };
+}
+/**
+ * SDK 解析后的消息段（text/at/face/image/video/audio/file/reply）→ canonical Segment[]。
+ * 附件段的 url 已由 SDK 归一（补 https:// 前缀）；mime 无法从载荷得知时按类型给默认。
+ */
+function extractCanonicalSegments(message) {
+    if (!Array.isArray(message))
+        return [];
+    const out = [];
+    for (const seg of message) {
+        if (!seg || typeof seg !== 'object')
+            continue;
+        const item = seg;
+        const type = item.type ?? '';
+        const data = item.data ?? {};
+        switch (type) {
+            case 'text': {
+                const text = String(data.text ?? '');
+                if (text)
+                    out.push({ type: 'text', data: { text } });
+                break;
+            }
+            case 'at': {
+                const target = String(data.user_id ?? data.id ?? '');
+                if (!target)
+                    break;
+                const name = typeof data.username === 'string' && data.username
+                    ? data.username
+                    : undefined;
+                out.push({ type: 'mention', data: name ? { target, name } : { target } });
+                break;
+            }
+            case 'face': {
+                const id = data.id;
+                if (id == null)
+                    break;
+                out.push({ type: 'face', data: { id: id } });
+                break;
+            }
+            case 'image':
+            case 'video':
+            case 'audio':
+            case 'file': {
+                const url = typeof data.url === 'string' ? data.url : '';
+                if (!url)
+                    break;
+                const media = {
+                    kind: 'url',
+                    value: url,
+                    mime_type: defaultMimeForSegment(type),
+                    ...(typeof data.name === 'string' && data.name ? { file_name: data.name } : {}),
+                    ...(typeof data.size === 'number' ? { size: data.size } : {}),
+                };
+                if (type === 'image')
+                    out.push({ type: 'image', data: { media } });
+                else if (type === 'video')
+                    out.push({ type: 'video', data: { media } });
+                else if (type === 'audio')
+                    out.push({ type: 'audio', data: { media } });
+                else
+                    out.push({ type: 'file', data: { media, ...(media.file_name ? { name: media.file_name } : {}) } });
+                break;
+            }
+            case 'reply': {
+                const messageId = String(data.id ?? data.message_id ?? '');
+                if (messageId)
+                    out.push({ type: 'reply', data: { message_id: messageId } });
+                break;
+            }
+            default:
+                break;
+        }
+    }
+    return out;
+}
+function defaultMimeForSegment(type) {
+    switch (type) {
+        case 'image': return 'image/jpeg';
+        case 'video': return 'video/mp4';
+        case 'audio': return 'audio/mpeg';
+        default: return undefined;
+    }
+}
+function extractTextContent(message) {
+    if (typeof message === 'string')
+        return message;
+    if (!Array.isArray(message))
+        return '';
+    return message
+        .map((seg) => {
+        if (!seg || typeof seg !== 'object')
+            return '';
+        const item = seg;
+        if (item.type === 'text')
+            return String(item.data?.text ?? item.text ?? '');
+        return '';
+    })
+        .join('');
+}
+export function defaultCreateBot(config) {
+    const bot = new Bot({
+        appid: config.appid,
+        secret: config.secret,
+        mode: ReceiverMode.WEBSOCKET,
+        sandbox: config.sandbox,
+        dataDir: path.join(process.cwd(), 'data', 'qq'),
+        // 关闭 qq-official-bot 内置 log4js，入/出站由 getAdapterLogger('qq', …) 统一格式
+        logLevel: 'off',
+        ...(config.intents ? { intents: config.intents } : {}),
+        ...(config.accessTokenUrl ? { accessTokenUrl: config.accessTokenUrl } : {}),
+        ...(config.gatewayUrl ? { gatewayUrl: config.gatewayUrl } : {}),
+    });
+    return {
+        api: bot,
+        start: () => bot.start().then(() => undefined),
+        stop: () => stopQqOfficialBot(bot),
+        on: (event, listener) => {
+            bot.on(event, listener);
+        },
+        removeAllListeners: () => {
+            bot.removeAllListeners(undefined);
+        },
+        sendPrivateMessage: (userId, message) => bot.sendPrivateMessage(userId, message),
+        sendGroupMessage: (groupId, message) => bot.sendGroupMessage(groupId, message),
+        sendGuildMessage: (channelId, message) => bot.sendGuildMessage(channelId, message),
+        sendDirectMessage: (guildId, message) => bot.sendDirectMessage(guildId, message),
+        recallPrivateMessage: (userId, messageId) => bot.recallPrivateMessage(userId, messageId),
+        recallGroupMessage: (groupId, messageId) => bot.recallGroupMessage(groupId, messageId),
+        recallGuildMessage: (channelId, messageId) => bot.recallGuildMessage(channelId, messageId),
+        recallDirectMessage: (guildId, messageId) => bot.recallDirectMessage(guildId, messageId),
+        getGuilds: () => bot.guildService.getList(),
+        getChannels: (guildId) => bot.channelService.getList(guildId),
+        getChannelInfo: (channelId) => bot.channelService.getInfo(channelId),
+        getGuildMember: (guildId, userId) => bot.memberService.getGuildMemberInfo(guildId, userId),
+        getGuildRoles: (guildId) => bot.guildService.getRoles(guildId),
+        createGuildRole: (guildId, name, color) => bot.guildService.createRole(guildId, { name, color: color || 0, hoist: 0 }),
+        addMemberRole: async (guildId, channelId, userId, roleId) => {
+            await bot.memberService.addMemberRole(guildId, channelId, userId, roleId);
+            return true;
+        },
+        removeMemberRole: async (guildId, channelId, userId, roleId) => {
+            await bot.memberService.removeMemberRole(guildId, channelId, userId, roleId);
+            return true;
+        },
+        approveGroupJoinRequest: (groupId, userId, options) => bot
+            .approveGroupJoinRequest?.(groupId, userId, options)
+            ?? Promise.reject(new Error('approveGroupJoinRequest is not available')),
+    };
+}

package/middlewares/bot-kind-reply/index.js

@@ -0,0 +1,47 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineMiddleware } from 'zhin.js/middleware';
+import { endpointConfigurationStoreToken } from 'zhin.js/adapter';
+import { completeQqPendingBotKind, } from '../../commands/qq/endpoint/definition.js';
+import { parseQqBotKindAnswer, qqCommandSessionKey, QQ_BOT_KIND_PROMPT, } from "../../lib/qq-bot-kind-prompt.js";
+import { qqRuntimeStateToken } from "../../lib/qq-runtime-state.js";
+/**
+ * 扫码绑定成功后，在同一会话收取 public/private（或 公域/私域）回复并写入 intents。
+ * 非待确认会话、或内容无法识别为 botKind 时放行后续中间件/命令。
+ */
+export default defineMiddleware({
+    target: 'inbound',
+    phase: 'before-dispatch',
+    order: -50,
+    async handle(context, next) {
+        const state = context.use(qqRuntimeStateToken);
+        const pending = state.pendingBotKind;
+        if (!pending) {
+            await next();
+            return;
+        }
+        const sessionKey = qqCommandSessionKey(context.input);
+        if (!sessionKey || sessionKey !== pending.sessionKey) {
+            await next();
+            return;
+        }
+        const raw = String(context.input.content ?? '').trim();
+        // 让 qq endpoint cancel 等命令继续走命令链
+        if (raw.toLowerCase().startsWith('qq endpoint')) {
+            await next();
+            return;
+        }
+        const botKind = parseQqBotKindAnswer(raw);
+        if (!botKind) {
+            await context.input.$reply?.(`未识别「${raw}」。${QQ_BOT_KIND_PROMPT}`);
+            return;
+        }
+        try {
+            const text = await completeQqPendingBotKind(pending, botKind, context.use(endpointConfigurationStoreToken));
+            state.pendingBotKind = null;
+            await context.input.$reply?.(text);
+        }
+        catch (error) {
+            await context.input.$reply?.(`写入配置失败：${error instanceof Error ? error.message : String(error)}`);
+        }
+    },
+});

package/middlewares/bot-kind-reply/index.ts

@@ -0,0 +1,65 @@
+import { defineMiddleware } from 'zhin.js/middleware';
+import type { CommandMessage } from 'zhin.js/command';
+import { endpointConfigurationStoreToken } from 'zhin.js/adapter';
+import {
+  completeQqPendingBotKind,
+} from '../../commands/qq/endpoint/definition.js';
+import {
+  parseQqBotKindAnswer,
+  qqCommandSessionKey,
+  QQ_BOT_KIND_PROMPT,
+} from '../../src/qq-bot-kind-prompt.js';
+import { qqRuntimeStateToken } from '../../src/qq-runtime-state.js';
+
+/**
+ * 扫码绑定成功后，在同一会话收取 public/private（或 公域/私域）回复并写入 intents。
+ * 非待确认会话、或内容无法识别为 botKind 时放行后续中间件/命令。
+ */
+export default defineMiddleware<CommandMessage>({
+  target: 'inbound',
+  phase: 'before-dispatch',
+  order: -50,
+  async handle(context, next) {
+    const state = context.use(qqRuntimeStateToken);
+    const pending = state.pendingBotKind;
+    if (!pending) {
+      await next();
+      return;
+    }
+
+    const sessionKey = qqCommandSessionKey(context.input);
+    if (!sessionKey || sessionKey !== pending.sessionKey) {
+      await next();
+      return;
+    }
+
+    const raw = String(context.input.content ?? '').trim();
+    // 让 qq endpoint cancel 等命令继续走命令链
+    if (raw.toLowerCase().startsWith('qq endpoint')) {
+      await next();
+      return;
+    }
+
+    const botKind = parseQqBotKindAnswer(raw);
+    if (!botKind) {
+      await context.input.$reply?.(
+        `未识别「${raw}」。${QQ_BOT_KIND_PROMPT}`,
+      );
+      return;
+    }
+
+    try {
+      const text = await completeQqPendingBotKind(
+        pending,
+        botKind,
+        context.use(endpointConfigurationStoreToken),
+      );
+      state.pendingBotKind = null;
+      await context.input.$reply?.(text);
+    } catch (error) {
+      await context.input.$reply?.(
+        `写入配置失败：${error instanceof Error ? error.message : String(error)}`,
+      );
+    }
+  },
+});