@zhin.js/adapter-qq 1.1.17 → 1.1.18

package/lib/endpoint.d.ts

@@ -1,7 +1,7 @@
 /**
  * QQ endpoints — lifecycle, outbound, admit, agent tool surface.
  */
-import { Endpoint, type EndpointControl, type EndpointManagement, type EndpointSendRequest, type EndpointTransportState } from 'zhin.js/adapter';
+import { Endpoint, type EndpointControl, type EndpointManagement, type EndpointSendRequest, type EndpointTransportState, type AdapterOutageNotifier } from 'zhin.js/adapter';
 import type { HttpHost } from '@zhin.js/host-http';
 import type { CapabilityId } from 'zhin.js';
 import { type QqInboundMessage, type ResolvedQqHttpConfig, type ResolvedQqWebsocketConfig } from './protocol.js';
@@ -13,6 +13,8 @@ export interface QqEndpointOptions {
     readonly id: CapabilityId;
     readonly config: ResolvedQqWebsocketConfig;
     readonly createBot?: CreateQqBot;
+    /** Out-of-band outage notifier; absent in tests/hosts without outbound. */
+    readonly notifier?: AdapterOutageNotifier;
 }
 export declare class QqWebsocketEndpoint extends Endpoint<QqBotTransport> {
     #private;
@@ -39,6 +41,8 @@ export interface QqHttpEndpointOptions {
     readonly http: HttpHost;
     readonly config: ResolvedQqHttpConfig;
     readonly createBot?: CreateQqHttpBot;
+    /** Out-of-band outage notifier; absent in tests/hosts without outbound. */
+    readonly notifier?: AdapterOutageNotifier;
 }
 /** Webhook / middleware inbound via httpHostToken POST (qq-official-bot Middleware receiver). */
 export declare class QqHttpEndpoint extends Endpoint<QqHttpBotTransport> {
@@ -60,3 +64,8 @@ export declare class QqHttpEndpoint extends Endpoint<QqHttpBotTransport> {
     /** Native click only; C2C/group have no platform source message ID. */
     admitInteraction(raw: unknown): boolean;
 }
+/** `type:id`（1 系统表情 / 2 emoji）或单个 Unicode emoji（→ type 2 + 码点）。 */
+export declare function parseQqEmoji(value: string): {
+    type: 1 | 2;
+    id: `${number}`;
+} | null;

package/lib/endpoint.js

@@ -4,10 +4,11 @@ import { qqDeliveryFailure } from './delivery-error.js';
 import { normalizeQqInteraction } from './interaction.js';
 import { awaitQqStartup } from './start-deadline.js';
 import { EndpointDeliveryError } from '@zhin.js/im-contract';
+import { inspectQqGroupMember, inspectQqGroupMemberProfile, inspectQqGroupScene, kickQqGroupMember, moderateQqGroupMember, muteQqGroupMember, qqGroupService, } from './group-admin.js';
 /**
  * QQ endpoints — lifecycle, outbound, admit, agent tool surface.
  */
-import { Endpoint, createEndpointLifecycle, createRecallEndpointControl, } from 'zhin.js/adapter';
+import { Endpoint, createEndpointLifecycle, } from 'zhin.js/adapter';
 import { formatCompact, getAdapterLogger, truncatePreview } from '@zhin.js/logger';
 import { collectOutboundImageSizes, formatOutboundMessages } from './outbound.js';
 import { QqActiveMessageGate, QqPassiveReplyLedger } from './passive-reply.js';
@@ -22,14 +23,15 @@ export class QqWebsocketEndpoint extends Endpoint {
     #createBot;
     #bot = null;
     #open = false;
+    #offlineNoticeAt = 0;
     #seenInteractions = new Map();
     /** Recent msg_id / event_id per conversation, so replies go out as passive messages. */
     #passiveReplies = new QqPassiveReplyLedger();
     #activeGate = new QqActiveMessageGate();
     #lifecycle;
     #cleanup;
-    management = createQqEndpointManagement(() => this.#requireBot());
-    control = createRecallEndpointControl((id) => this.recallMessage(id));
+    management = createQqEndpointManagement(() => this.#requireBot(), () => this.#open && this.#bot !== null);
+    control = createQqEndpointControl(() => this.#requireBot(), (id) => this.recallMessage(id));
     constructor(options) {
         super();
         this.#logger = getAdapterLogger('qq', options.config.id);
@@ -78,8 +80,13 @@ export class QqWebsocketEndpoint extends Endpoint {
             this.#cleanup = cleanup;
             handle.onForceClose(() => { void cleanup(); });
             try {
-                bot.on('transport.close', () => { if (cancelled || this.#bot !== bot)
-                    return; void cleanup(); handle.notifyClosed(); });
+                bot.on('transport.close', () => {
+                    if (cancelled || this.#bot !== bot)
+                        return;
+                    this.#notifyOffline('transport_close');
+                    void cleanup();
+                    handle.notifyClosed();
+                });
                 this.#bindBot(bot);
                 await awaitQqStartup(bot.start().then(async () => {
                     if (cancelled)
@@ -94,6 +101,7 @@ export class QqWebsocketEndpoint extends Endpoint {
                     await stopping;
                     return;
                 }
+                this.#offlineNoticeAt = 0;
                 this.#logger.info(`connected (websocket) | appid: ${this.#options.config.appid}`);
             }
             catch (error) {
@@ -101,6 +109,7 @@ export class QqWebsocketEndpoint extends Endpoint {
                 await cleanup();
                 if (wasCancelled)
                     return;
+                this.#notifyOffline('start_failed');
                 const raw = error instanceof Error ? error.message : String(error);
                 throw new Error(`QQ WebSocket 连接失败：请检查 appid/secret 是否配对、网关地址（gatewayUrl/accessTokenUrl）是否可达（原始错误：${raw}）`, { cause: error });
             }
@@ -230,6 +239,26 @@ export class QqWebsocketEndpoint extends Endpoint {
         }).catch(() => this.#logger.warn('qq_interaction_receive_failed'));
         return true;
     }
+    #notifyOffline(reason) {
+        const notifier = this.#options.notifier;
+        if (!notifier?.configured)
+            return;
+        const now = Date.now();
+        if (now - this.#offlineNoticeAt < 60_000)
+            return;
+        this.#offlineNoticeAt = now;
+        const text = `[Zhin] QQ 机器人 ${this.#options.config.id} 掉线（${reason}）。正在自动重连。\n`
+            + '恢复：在 QQ 回复 `qq endpoint add` 重新扫码绑定，或打开 Console 的 QQ 页面。';
+        void notifier.send(text).then((sent) => {
+            if (sent)
+                return;
+            this.#logger.warn(formatCompact({
+                op: 'qq_notify_failed',
+                endpoint: this.#options.config.id,
+                reason,
+            }));
+        });
+    }
     #bindBot(bot) {
         bindQqBotInboundEvents(bot, (raw) => {
             if (this.#bot !== bot)
@@ -270,14 +299,15 @@ export class QqHttpEndpoint extends Endpoint {
     #createBot;
     #bot = null;
     #open = false;
+    #offlineNoticeAt = 0;
     #seenInteractions = new Map();
     /** Recent msg_id / event_id per conversation, so replies go out as passive messages. */
     #passiveReplies = new QqPassiveReplyLedger();
     #activeGate = new QqActiveMessageGate();
     #lifecycle;
     #cleanup;
-    management = createQqEndpointManagement(() => this.#requireBot());
-    control = createRecallEndpointControl((id) => this.recallMessage(id));
+    management = createQqEndpointManagement(() => this.#requireBot(), () => this.#open && this.#bot !== null);
+    control = createQqEndpointControl(() => this.#requireBot(), (id) => this.recallMessage(id));
     constructor(options) {
         super();
         this.#logger = getAdapterLogger('qq', options.config.id);
@@ -345,6 +375,7 @@ export class QqHttpEndpoint extends Endpoint {
                     await stopping;
                     return;
                 }
+                this.#offlineNoticeAt = 0;
                 this.#logger.info(`connected (${this.#options.config.mode}) | path: ${this.#options.config.webhookPath}`);
             }
             catch (error) {
@@ -352,6 +383,7 @@ export class QqHttpEndpoint extends Endpoint {
                 await cleanup();
                 if (wasCancelled)
                     return;
+                this.#notifyOffline('start_failed');
                 throw error;
             }
         });
@@ -479,6 +511,26 @@ export class QqHttpEndpoint extends Endpoint {
         }).catch(() => this.#logger.warn('qq_interaction_receive_failed'));
         return true;
     }
+    #notifyOffline(reason) {
+        const notifier = this.#options.notifier;
+        if (!notifier?.configured)
+            return;
+        const now = Date.now();
+        if (now - this.#offlineNoticeAt < 60_000)
+            return;
+        this.#offlineNoticeAt = now;
+        const text = `[Zhin] QQ 机器人 ${this.#options.config.id} 掉线（${reason}）。正在自动重连。\n`
+            + '恢复：在 QQ 回复 `qq endpoint add` 重新扫码绑定，或打开 Console 的 QQ 页面。';
+        void notifier.send(text).then((sent) => {
+            if (sent)
+                return;
+            this.#logger.warn(formatCompact({
+                op: 'qq_notify_failed',
+                endpoint: this.#options.config.id,
+                reason,
+            }));
+        });
+    }
     #bindBot(bot) {
         bindQqBotInboundEvents(bot, (raw) => {
             if (this.#bot !== bot)
@@ -512,8 +564,23 @@ export class QqHttpEndpoint extends Endpoint {
         return this.#bot;
     }
 }
-function createQqEndpointManagement(requireClient) {
+function createQqEndpointManagement(requireClient, isActive) {
+    const api = () => requireClient().api;
     return Object.freeze({
+        // QQ 群（group_openid / member_openid）：官方 v2 群管理接口，部分为白名单能力（11253）。
+        inspectGroupMember: (group, user, signal) => inspectQqGroupMember(api(), group, user, signal),
+        inspectGroupScene: (group, signal) => inspectQqGroupScene(api(), group, signal),
+        inspectGroupMemberProfile: (group, user, signal) => inspectQqGroupMemberProfile(api(), group, user, signal),
+        moderateGroupMember: (group, user, action, signal) => moderateQqGroupMember(api(), group, user, action, signal, isActive),
+        async listGroupMembers(groupId) {
+            return qqGroupService(api()).getMembers(groupId);
+        },
+        async kickGroupMember(groupId, userId) {
+            await kickQqGroupMember(api(), groupId, userId);
+        },
+        async muteGroupMember(groupId, userId, durationSeconds) {
+            await muteQqGroupMember(api(), groupId, userId, durationSeconds);
+        },
         async listChannels() {
             const channels = [];
             const client = requireClient();
@@ -546,6 +613,65 @@ function asRecord(value) {
         ? value
         : {};
 }
+/**
+ * Recall + 频道表情回应。recall 同时接受 send() 的复合 ID 与入站原生消息 ID（目标取自 MessageRef.conversation），
+ * 因此群管理员机器人可撤回普通成员 2 分钟内的消息（官方限制由平台执行）。
+ * 表情回应只有频道子频道消息支持（官方无群 / 单聊表情回应接口）。
+ */
+function createQqEndpointControl(requireBot, recallById) {
+    return Object.freeze({
+        recall: async (message) => {
+            if (isCompoundMessageId(message.id))
+                return recallById(message.id);
+            const kind = qqOutboundKind(message.conversation);
+            await recallQqMessage(requireBot(), kind, message.conversation.id, message.id);
+        },
+        addReaction: async (message, emoji) => {
+            const target = qqGuildReactionTarget(message, emoji);
+            if (!target)
+                return null;
+            await requireBot().api.reactionService.addGuildMessageReaction(target.channelId, target.messageId, target.type, target.id);
+            return `${target.type}:${target.id}`;
+        },
+        removeReaction: async (message, reactionId) => {
+            const target = qqGuildReactionTarget(message, reactionId);
+            if (!target)
+                return;
+            await requireBot().api.reactionService.deleteGuildMessageReaction(target.channelId, target.messageId, target.type, target.id);
+        },
+    });
+}
+function isCompoundMessageId(id) {
+    try {
+        parseCompoundMessageId(id);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** `type:id`（1 系统表情 / 2 emoji）或单个 Unicode emoji（→ type 2 + 码点）。 */
+export function parseQqEmoji(value) {
+    const explicit = /^([12]):(\d+)$/.exec(value.trim());
+    if (explicit)
+        return { type: Number(explicit[1]), id: explicit[2] };
+    const chars = [...value.trim().replace(/\uFE0F/g, '')];
+    if (chars.length !== 1)
+        return null;
+    const code = chars[0].codePointAt(0);
+    return code > 0x7f ? { type: 2, id: String(code) } : null;
+}
+function qqGuildReactionTarget(message, emoji) {
+    let kind = qqOutboundKind(message.conversation);
+    let channelId = message.conversation.id;
+    let messageId = message.id;
+    if (isCompoundMessageId(message.id))
+        ({ kind, channelId, qqMsgId: messageId } = parseCompoundMessageId(message.id));
+    if (kind !== 'channel' || !channelId || !messageId)
+        return null;
+    const parsed = parseQqEmoji(emoji);
+    return parsed ? { channelId, messageId, ...parsed } : null;
+}
 async function recallQqMessage(bot, kind, channelId, messageId) {
     const recall = { private: bot.recallPrivateMessage, group: bot.recallGroupMessage,
         channel: bot.recallGuildMessage, direct: bot.recallDirectMessage }[kind];

package/lib/group-admin.d.ts

@@ -0,0 +1,36 @@
+/**
+ * QQ 群（group_openid / member_openid）管理：只走官方 v2 群管理接口。
+ *
+ * 官方限制（https://bot.q.qq.com/wiki/develop/api-v2/autogen/）：
+ * - 成员列表 / 成员信息 / 批量移除 / 黑名单 / 入群申请多为白名单能力，无权限返回 11253；
+ * - 禁言与入群审批要求机器人是群管理员；禁言最长 30 天，只能禁言普通成员；
+ * - 没有「机器人所在群列表」「好友列表」「退群」「设管理员」「群公告」等接口。
+ */
+import type { GroupBotState, GroupMemberInfo } from 'qq-official-bot';
+import type { GroupMemberProfile, GroupModerationAction, GroupModerationMember, GroupSceneFacts } from 'zhin.js/adapter';
+import type { QqOfficialApi } from './ws.js';
+/** 官方 restrict_chat_setting 上限：30 天。 */
+export declare const QQ_GROUP_MUTE_MAX_SECONDS: number;
+export type QqGroupService = QqOfficialApi['groupService'];
+export declare function qqGroupService(api: Partial<QqOfficialApi> | undefined): QqGroupService;
+export declare function isQqGroupManagerRole(role: unknown): role is 'owner' | 'admin';
+/** RFC3339 → epoch ms；非法或未来时间返回 undefined（从不猜测）。 */
+export declare function parseQqTime(value: unknown, { allowFuture }?: {
+    allowFuture?: boolean | undefined;
+}): number | undefined;
+/** 只读、实时：机器人在群里的状态（角色、是否允许主动消息、接收设置）。 */
+export declare function qqGroupBotState(api: Partial<QqOfficialApi> | undefined, groupId: string): Promise<GroupBotState>;
+export declare function qqGroupMember(api: Partial<QqOfficialApi> | undefined, groupId: string, userId: string): Promise<GroupMemberInfo>;
+/** 禁言 / 解除禁言一个普通成员；0 = 解除。 */
+export declare function muteQqGroupMember(api: Partial<QqOfficialApi> | undefined, groupId: string, userId: string, durationSeconds: number): Promise<void>;
+/** 移出一个成员；可选同时加入群黑名单。平台未确认 success 时抛错，不把未确认当成功。 */
+export declare function kickQqGroupMember(api: Partial<QqOfficialApi> | undefined, groupId: string, userId: string, addToBlacklist?: boolean): Promise<{
+    blacklistFailed: boolean;
+}>;
+/** 自动审核用：机器人与目标成员的实时角色；平台只允许管理员处置普通成员（且非机器人）。 */
+export declare function inspectQqGroupMember(api: Partial<QqOfficialApi> | undefined, groupId: string, userId: string, signal: AbortSignal): Promise<GroupModerationMember>;
+export declare function moderateQqGroupMember(api: Partial<QqOfficialApi> | undefined, groupId: string, userId: string, action: GroupModerationAction, signal: AbortSignal, isActive: () => boolean): Promise<void>;
+/** ADR 0041 场景事实：一次群信息读取；官方群信息不含群主/管理员/全员禁言，留作 unknown。 */
+export declare function inspectQqGroupScene(api: Partial<QqOfficialApi> | undefined, groupId: string, signal: AbortSignal): Promise<GroupSceneFacts>;
+/** ADR 0041 成员事实：一次成员读取（群名片/头衔/禁言到期官方不提供）。 */
+export declare function inspectQqGroupMemberProfile(api: Partial<QqOfficialApi> | undefined, groupId: string, userId: string, signal: AbortSignal): Promise<GroupMemberProfile>;

package/lib/group-admin.js

@@ -0,0 +1,113 @@
+/** 官方 restrict_chat_setting 上限：30 天。 */
+export const QQ_GROUP_MUTE_MAX_SECONDS = 30 * 24 * 60 * 60;
+export function qqGroupService(api) {
+    const service = api?.groupService;
+    if (!service)
+        throw new Error('QQ group management API is unavailable on this transport');
+    return service;
+}
+export function isQqGroupManagerRole(role) {
+    return role === 'owner' || role === 'admin';
+}
+function platformRole(role) {
+    return role === 'owner' || role === 'admin' || role === 'member' ? role : undefined;
+}
+function requireId(value, what) {
+    const id = typeof value === 'string' ? value.trim() : '';
+    if (!id || /[\s/?#]/.test(id))
+        throw new Error(`Invalid QQ ${what}`);
+    return id;
+}
+/** RFC3339 → epoch ms；非法或未来时间返回 undefined（从不猜测）。 */
+export function parseQqTime(value, { allowFuture = false } = {}) {
+    if (typeof value !== 'string' || !value)
+        return undefined;
+    const at = Date.parse(value);
+    if (!Number.isFinite(at) || at <= 0)
+        return undefined;
+    if (!allowFuture && at > Date.now())
+        return undefined;
+    return at;
+}
+/** 只读、实时：机器人在群里的状态（角色、是否允许主动消息、接收设置）。 */
+export async function qqGroupBotState(api, groupId) {
+    return qqGroupService(api).getBotState(requireId(groupId, 'group id'));
+}
+export async function qqGroupMember(api, groupId, userId) {
+    return qqGroupService(api).getMemberInfo(requireId(groupId, 'group id'), requireId(userId, 'member id'));
+}
+/** 禁言 / 解除禁言一个普通成员；0 = 解除。 */
+export async function muteQqGroupMember(api, groupId, userId, durationSeconds) {
+    if (!Number.isSafeInteger(durationSeconds) || durationSeconds < 0 || durationSeconds > QQ_GROUP_MUTE_MAX_SECONDS) {
+        throw new RangeError(`QQ group mute duration must be 0..${QQ_GROUP_MUTE_MAX_SECONDS} seconds`);
+    }
+    const member = requireId(userId, 'member id');
+    await qqGroupService(api).setMemberMute(requireId(groupId, 'group id'), [durationSeconds === 0
+            ? { op: 'del', member_openid: member, mute_expire_at: '' }
+            : { op: 'add', member_openid: member, mute_expire_at: new Date(Date.now() + durationSeconds * 1000).toISOString() }]);
+}
+/** 移出一个成员；可选同时加入群黑名单。平台未确认 success 时抛错，不把未确认当成功。 */
+export async function kickQqGroupMember(api, groupId, userId, addToBlacklist = false) {
+    const member = requireId(userId, 'member id');
+    const result = await qqGroupService(api).removeMembers(requireId(groupId, 'group id'), {
+        member_openids: [member],
+        ...(addToBlacklist ? { add_to_member_blacklist: true } : {}),
+    });
+    if (result?.remove_members_result !== 'success')
+        throw new Error('QQ did not confirm the member removal');
+    return { blacklistFailed: addToBlacklist && (result.add_to_member_blacklist_fail_openids ?? []).includes(member) };
+}
+/** 自动审核用：机器人与目标成员的实时角色；平台只允许管理员处置普通成员（且非机器人）。 */
+export async function inspectQqGroupMember(api, groupId, userId, signal) {
+    signal.throwIfAborted();
+    const [self, member] = await Promise.all([qqGroupBotState(api, groupId), qqGroupMember(api, groupId, userId)]);
+    signal.throwIfAborted();
+    const role = member.member_openid === userId ? platformRole(member.member_role) : undefined;
+    const joinedAt = parseQqTime(member.joined_at);
+    return {
+        canModerate: isQqGroupManagerRole(self.member_role) && self.member_openid !== userId
+            && member.member_openid === userId && role === 'member' && member.bot !== true,
+        ...(role ? { platformRole: role } : {}),
+        ...(joinedAt ? { joinedAt } : {}),
+    };
+}
+export async function moderateQqGroupMember(api, groupId, userId, action, signal, isActive) {
+    const member = await inspectQqGroupMember(api, groupId, userId, signal);
+    signal.throwIfAborted();
+    if (!isActive() || !member.canModerate)
+        throw new Error('Group moderation permission is unavailable');
+    if (action.type === 'kick') {
+        if (!Number.isSafeInteger(action.maxMembershipAgeMs) || action.maxMembershipAgeMs <= 0
+            || !member.joinedAt || member.joinedAt !== action.joinedAt
+            || Date.now() - member.joinedAt > action.maxMembershipAgeMs) {
+            throw new Error('Group membership no longer matches the approved newcomer window');
+        }
+        await kickQqGroupMember(api, groupId, userId);
+        return;
+    }
+    if (!Number.isSafeInteger(action.durationSeconds) || action.durationSeconds <= 0) {
+        throw new Error('Invalid group mute duration');
+    }
+    await muteQqGroupMember(api, groupId, userId, Math.min(action.durationSeconds, QQ_GROUP_MUTE_MAX_SECONDS));
+}
+/** ADR 0041 场景事实：一次群信息读取；官方群信息不含群主/管理员/全员禁言，留作 unknown。 */
+export async function inspectQqGroupScene(api, groupId, signal) {
+    signal.throwIfAborted();
+    const info = await qqGroupService(api).getInfo(requireId(groupId, 'group id'));
+    signal.throwIfAborted();
+    if (info?.group_openid && info.group_openid !== groupId)
+        return {};
+    const name = typeof info?.group_name === 'string' && info.group_name.trim() ? info.group_name.trim() : undefined;
+    const memberCount = Number.isSafeInteger(info?.group_member_num) && info.group_member_num > 0 ? info.group_member_num : undefined;
+    return { ...(name ? { name } : {}), ...(memberCount ? { memberCount } : {}) };
+}
+/** ADR 0041 成员事实：一次成员读取（群名片/头衔/禁言到期官方不提供）。 */
+export async function inspectQqGroupMemberProfile(api, groupId, userId, signal) {
+    signal.throwIfAborted();
+    const member = await qqGroupMember(api, groupId, userId);
+    signal.throwIfAborted();
+    if (member.member_openid !== userId)
+        return {};
+    const role = platformRole(member.member_role);
+    return role ? { platformRole: role } : {};
+}

package/lib/protocol.d.ts

@@ -1,5 +1,6 @@
 /** QQ Official Bot protocol helpers. Canonicalization is owned by Core. */
 import { type ConversationRef } from '@zhin.js/im-contract';
+import { type AdapterNotifyTarget, type ResolvedAdapterNotifyTarget } from 'zhin.js/adapter';
 /** One endpoint config after AdapterIndex expands `plugins.<instanceKey>.endpoints`. */
 export interface QqEndpointConfig {
     readonly id: string;
@@ -16,6 +17,8 @@ export interface QqEndpointConfig {
     readonly gatewayUrl?: string;
     readonly streamProxy?: import('./stream-proxy.js').QqStreamProxy;
     readonly webhookPath?: string;
+    /** Optional out-of-band outage notification target (usually an ICQQ instance). */
+    readonly notify?: AdapterNotifyTarget;
 }
 export interface ResolvedQqWebsocketConfig {
     readonly context: 'qq';
@@ -28,6 +31,7 @@ export interface ResolvedQqWebsocketConfig {
     readonly accessTokenUrl?: string;
     readonly gatewayUrl?: string;
     readonly streamProxy?: import('./stream-proxy.js').QqStreamProxy;
+    readonly notify?: ResolvedAdapterNotifyTarget;
 }
 export interface ResolvedQqHttpConfig {
     readonly context: 'qq';
@@ -37,6 +41,7 @@ export interface ResolvedQqHttpConfig {
     readonly secret: string;
     readonly webhookPath: string;
     readonly sandbox: boolean;
+    readonly notify?: ResolvedAdapterNotifyTarget;
 }
 export type ResolvedQqConfig = ResolvedQqWebsocketConfig | ResolvedQqHttpConfig;
 export type QqChannelKind = 'private' | 'group' | 'channel' | 'direct';

package/lib/protocol.js

@@ -2,12 +2,14 @@
 import { EndpointDeliveryError } from '@zhin.js/im-contract';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 import { resolveQqIntents } from './qq-intents.js';
+import { resolveAdapterNotifyTarget } from 'zhin.js/adapter';
 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';
+    const notify = resolveAdapterNotifyTarget(config.notify);
     if (mode === 'webhook' || mode === 'middleware') {
         const webhookPathRaw = config.webhookPath ?? '/qq/webhook';
         const webhookPath = webhookPathRaw.startsWith('/') ? webhookPathRaw : `/${webhookPathRaw}`;
@@ -19,6 +21,7 @@ export function resolveQqConfig(config) {
             secret,
             webhookPath,
             sandbox: config.sandbox === true,
+            ...(notify ? { notify } : {}),
         };
     }
     if (config.streamProxy && (!Number.isInteger(config.streamProxy.port) || config.streamProxy.port < 1 || config.streamProxy.port > 65535
@@ -38,6 +41,7 @@ export function resolveQqConfig(config) {
         accessTokenUrl: config.accessTokenUrl,
         gatewayUrl: config.gatewayUrl,
         ...(config.streamProxy ? { streamProxy: config.streamProxy } : {}),
+        ...(notify ? { notify } : {}),
     };
 }
 function requiredEndpointField(value, field) {

package/lib/qq-console-spec.d.ts

@@ -0,0 +1,17 @@
+/**
+ * QQ Console 页面元数据（浏览器与服务端共享；不要在这里 import 服务端代码）。
+ *
+ * QQ 的 endpoint 不走通用「字段表单」：`qq endpoint add` 是扫码绑定流程，
+ * 因此 `canAdd: false`，改由 `qq-console.ts` 的 `qq-bind-*` 动作完成。
+ */
+import type { AdapterConsoleField } from 'zhin.js/adapter';
+export declare const qqConsoleSpec: {
+    readonly adapterKey: "qq";
+    readonly adapterDisplayName: "QQ";
+    readonly fields: readonly AdapterConsoleField[];
+    readonly canAdd: false;
+    readonly canRemove: true;
+    readonly docsUrl: "https://zhin.js.org/adapters/qq";
+    readonly readPermission: "qq:read";
+    readonly writePermission: "qq:write";
+};

package/lib/qq-console-spec.js

@@ -0,0 +1,10 @@
+export const qqConsoleSpec = {
+    adapterKey: 'qq',
+    adapterDisplayName: 'QQ',
+    fields: [],
+    canAdd: false,
+    canRemove: true,
+    docsUrl: 'https://zhin.js.org/adapters/qq',
+    readPermission: 'qq:read',
+    writePermission: 'qq:write',
+};

package/lib/qq-console.d.ts

@@ -0,0 +1,11 @@
+import { type QqEndpointWriteResult } from './qq-endpoint-write.js';
+import type { QqRuntimeState } from './qq-runtime-state.js';
+import type { EndpointConfigurationStore } from 'zhin.js/adapter';
+/** 启动 Console 扫码；resolve 时二维码链接已就绪。 */
+export declare function startQqConsoleBind(state: QqRuntimeState, id?: string): Promise<{
+    readonly url: string;
+}>;
+/** 扫码成功后选择公域 / 私域并写回配置。 */
+export declare function completeQqConsoleBind(state: QqRuntimeState, store: EndpointConfigurationStore, kindValue: unknown): Promise<QqEndpointWriteResult>;
+/** 取消 Console 绑定（也可用于收拾聊天命令发起的流程）。 */
+export declare function cancelQqConsoleBind(state: QqRuntimeState): boolean;

package/lib/qq-console.js

@@ -0,0 +1,116 @@
+/**
+ * QQ Console 扫码绑定：把原本只能在聊天里执行的 `qq endpoint add` 流程
+ * 搬到 Console 页面。
+ *
+ * - `start` 返回扫码链接；后续状态写入 `state.consoleBind`，页面轮询 status。
+ * - 扫码成功后凭据只留在内存，等页面选择公域 / 私域再一次性写 `.env` + 配置。
+ * - 与聊天命令共享 `state.bindFlow` 单例，同一时间只允许一个绑定流程。
+ */
+import { PluginConsoleRpcError } from 'zhin.js';
+import { startQqBindFlow } from './qq-bind-flow.js';
+import { writeQqEndpointWithBotKind } from './qq-endpoint-write.js';
+import { parseQqBotKind } from './qq-intents.js';
+/** 启动 Console 扫码；resolve 时二维码链接已就绪。 */
+export function startQqConsoleBind(state, id) {
+    if (state.bindFlow || state.pendingBotKind) {
+        throw new PluginConsoleRpcError('conflict', '已有扫码绑定流程在进行，请先完成或取消');
+    }
+    if (state.consoleBind?.pending) {
+        throw new PluginConsoleRpcError('conflict', '已经扫码成功，请先选择公域或私域');
+    }
+    const endpointId = id?.trim() || undefined;
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const stop = startQqBindFlow({
+            onQrDisplayed: (url) => {
+                state.consoleBind = {
+                    state: 'waiting',
+                    url,
+                    message: '请用手机 QQ 扫码',
+                    startedAt: state.consoleBind?.startedAt ?? Date.now(),
+                };
+                if (settled)
+                    return;
+                settled = true;
+                resolve({ url });
+            },
+            onQrExpired: () => {
+                state.consoleBind = {
+                    state: 'waiting',
+                    ...(state.consoleBind?.url ? { url: state.consoleBind.url } : {}),
+                    message: '二维码已过期，正在刷新…',
+                    startedAt: state.consoleBind?.startedAt ?? Date.now(),
+                };
+            },
+            onSuccess: (credentials) => {
+                state.bindFlow = null;
+                const [first] = credentials;
+                if (!first) {
+                    state.consoleBind = {
+                        state: 'failed',
+                        error: '扫码结果为空，请重新扫码',
+                        startedAt: state.consoleBind?.startedAt ?? Date.now(),
+                    };
+                    return;
+                }
+                state.consoleBind = {
+                    state: 'scanned',
+                    ...(state.consoleBind?.url ? { url: state.consoleBind.url } : {}),
+                    message: '已扫码，请选择公域或私域',
+                    startedAt: state.consoleBind?.startedAt ?? Date.now(),
+                    pending: {
+                        endpointId: endpointId ?? first.appId,
+                        appId: first.appId,
+                        appSecret: first.appSecret,
+                    },
+                };
+            },
+            onFailure: (error) => {
+                state.bindFlow = null;
+                state.consoleBind = {
+                    state: 'failed',
+                    error: error.message,
+                    startedAt: state.consoleBind?.startedAt ?? Date.now(),
+                };
+                if (settled)
+                    return;
+                settled = true;
+                reject(new PluginConsoleRpcError('unavailable', error.message));
+            },
+        }, { source: 'zhin' });
+        state.bindFlow = { id: endpointId, stop, locale: 'zh-CN' };
+    });
+}
+/** 扫码成功后选择公域 / 私域并写回配置。 */
+export async function completeQqConsoleBind(state, store, kindValue) {
+    const pending = state.consoleBind?.pending;
+    if (!pending) {
+        throw new PluginConsoleRpcError('conflict', '还没有扫码成功，请先扫码绑定');
+    }
+    const botKind = parseQqBotKind(kindValue);
+    if (!botKind) {
+        throw new PluginConsoleRpcError('invalid_input', '请选择公域（public）或私域（private）');
+    }
+    try {
+        const result = await writeQqEndpointWithBotKind({ ...pending, botKind }, store);
+        state.consoleBind = null;
+        return result;
+    }
+    catch {
+        throw new PluginConsoleRpcError('unavailable', '写入配置失败，请检查配置文件和 .env 的权限');
+    }
+}
+/** 取消 Console 绑定（也可用于收拾聊天命令发起的流程）。 */
+export function cancelQqConsoleBind(state) {
+    const active = Boolean(state.bindFlow || state.pendingBotKind || state.consoleBind);
+    try {
+        state.bindFlow?.stop();
+    }
+    catch {
+        // best effort
+    }
+    state.bindFlow = null;
+    state.pendingBotKind = null;
+    state.consoleBind = null;
+    return active;
+}