@zhin.js/adapter-qq 1.1.17 → 1.1.19

package/lib/endpoint.js

@@ -1,99 +1,110 @@
+import { Bot } from 'qq-official-bot';
 import { installQqUploadDiagnostics } from './upload-diagnostics.js';
 import { projectQqGuildSenderRoles } from './platform-permit.js';
 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 { createEndpointSpecification, endpointSpec, createEndpointLifecycle, createEndpointOperation, } 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';
 import { sendQqMessages } from './qq-send.js';
 import { formatInboundContent, parseCompoundMessageId, qqInboundConversation, qqOutboundKind, resolveOutboundMessageId, senderDisplayName, } from './protocol.js';
-import { defaultCreateHttpBot, registerQqWebhookRoutes, } from './webhook.js';
-import { bindQqBotInboundEvents, defaultCreateBot, normalizeQqMessage, } from './ws.js';
+import { qqHttpBotOptions, registerQqWebhookRoutes, } from './webhook.js';
+import { bindQqBotInboundEvents, qqWebsocketBotOptions, configureQqWebsocketReceiver, disposeQqAuthorization, normalizeQqMessage, } from './ws.js';
 import { bindQqBotSideEvents, receiveQqSideEvent, } from './side-event-dispatch.js';
-export class QqWebsocketEndpoint extends Endpoint {
+export class QqWebsocketEndpoint extends Bot {
+    [endpointSpec];
+    #receiverResources;
     #logger;
     #options;
-    #createBot;
-    #bot = null;
+    #connection;
+    #stopping;
     #open = false;
+    #executionSignal;
+    #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.#connection !== undefined);
+    #control = createQqEndpointControl(() => this.#requireBot(), (id) => this.recallMessage(id));
     constructor(options) {
-        super();
+        super(qqWebsocketBotOptions(options.config));
         this.#logger = getAdapterLogger('qq', options.config.id);
         this.#lifecycle = createEndpointLifecycle({ name: options.config.id });
         this.#options = options;
-        this.#createBot = options.createBot ?? defaultCreateBot;
-    }
-    get client() {
-        return this.#requireBot();
+        this.#receiverResources = configureQqWebsocketReceiver(this, options.config);
+        const endpoint = this;
+        this[endpointSpec] = createEndpointSpecification(this, {
+            start: signal => this.#startFramework(signal), open: () => this.#openFramework(), close: () => this.#closeFramework(),
+            stop: () => this.#stopFramework(), send: request => this.#sendFramework(request), name: options.config.id,
+            get transportState() { return endpoint.#transportState; }, management: this.#management, control: this.#control,
+        });
+        this.#bindBot(this);
     }
     /** Live endpoint 名（Console/AdapterIndex 展示用，如 bot appid 别名）。 */
     get name() {
         return this.#options.config.id;
     }
-    get transportState() {
+    get #transportState() {
         if (this.#lifecycle.state !== 'open')
             return this.#lifecycle.state;
-        return this.#bot?.transportState ?? this.#lifecycle.state;
+        return this.#receiverResources.state();
     }
-    async start() {
+    async #startFramework(executionSignal) {
+        this.#executionSignal = executionSignal;
         await this.#lifecycle.start(async (handle) => {
-            const bot = this.#createBot(this.#options.config);
-            this.#bot = bot;
-            const releaseUploadDiagnostics = installQqUploadDiagnostics(bot.api, metadata => this.#logger.debug(formatCompact(metadata)));
+            const bot = this;
+            const previousCleanup = this.#cleanup;
+            await previousCleanup?.();
+            const releaseUploadDiagnostics = installQqUploadDiagnostics(bot, metadata => this.#logger.debug(formatCompact(metadata)));
             let cancelled = false;
             const startupAbort = new AbortController();
+            this.#connection = startupAbort;
+            let nativeStart;
             let stopping;
+            let transportClose;
             const stopBot = async () => {
-                try {
-                    bot.removeAllListeners();
-                }
-                catch { /* continue SDK cleanup */ }
-                try {
-                    await bot.stop();
-                }
-                catch { /* best-effort SDK cleanup */ }
+                await super.stop();
+                await nativeStart?.catch(() => undefined);
             };
             const cleanup = () => {
                 cancelled = true;
                 releaseUploadDiagnostics();
                 startupAbort.abort();
-                if (this.#bot === bot)
-                    this.#bot = null;
+                if (transportClose)
+                    this.receiver.off('close', transportClose);
+                if (this.#connection === startupAbort)
+                    this.#connection = undefined;
                 return stopping ??= stopBot();
             };
             this.#cleanup = cleanup;
-            handle.onForceClose(() => { void cleanup(); });
+            handle.onForceClose(() => { void cleanup().catch(() => undefined); });
             try {
-                bot.on('transport.close', () => { if (cancelled || this.#bot !== bot)
-                    return; void cleanup(); handle.notifyClosed(); });
-                this.#bindBot(bot);
-                await awaitQqStartup(bot.start().then(async () => {
-                    if (cancelled)
-                        await stopBot();
-                }, async (error) => {
-                    if (cancelled)
-                        await stopBot();
-                    throw error;
-                }), startupAbort.signal);
+                transportClose = () => {
+                    if (cancelled || this.#connection === undefined)
+                        return;
+                    this.#notifyOffline('transport_close');
+                    void cleanup().catch(() => undefined);
+                    handle.notifyClosed();
+                };
+                this.receiver.on('close', transportClose);
+                nativeStart = super.start();
+                await awaitQqStartup(nativeStart.then(() => undefined), startupAbort.signal);
                 if (cancelled) {
                     // SDK startup may create resources after stop; close this exact old client again.
                     await stopping;
                     return;
                 }
+                this.#offlineNoticeAt = 0;
                 this.#logger.info(`connected (websocket) | appid: ${this.#options.config.appid}`);
             }
             catch (error) {
@@ -101,29 +112,41 @@ 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 });
             }
         });
     }
-    open() {
+    #openFramework() {
         this.#open = true;
     }
-    close() {
+    #closeFramework() {
         this.#open = false;
     }
-    async stop() {
-        this.#open = false;
-        const cleanup = this.#cleanup;
-        this.#cleanup = undefined;
-        await this.#lifecycle.stop();
-        await cleanup?.();
+    async #stopFramework() {
+        this.#stopping ??= Promise.resolve().then(async () => {
+            this.#open = false;
+            const cleanup = this.#cleanup;
+            this.#cleanup = undefined;
+            try {
+                await this.#lifecycle.stop();
+                await cleanup?.();
+            }
+            finally {
+                this.removeAllListeners(undefined);
+                this.#receiverResources.dispose();
+                disposeQqAuthorization(this);
+            }
+        });
+        await this.#stopping;
         this.#logger.debug(formatCompact({ op: 'disconnect' }));
     }
-    async send({ conversation, payload }) {
+    async #sendFramework({ conversation, payload, signal }) {
         // 媒体与 markdown/按钮不能同条发送（msg_type 7 与 2 互斥）：公网图片嵌入 markdown，
         // 拿不到 URL/尺寸的媒体降级为独立消息先发
-        const messages = formatOutboundMessages(payload, { imageSizes: await collectOutboundImageSizes(payload) });
+        const operation = createEndpointOperation({ signal });
+        const messages = formatOutboundMessages(payload, { imageSizes: await operation.prepare(() => collectOutboundImageSizes(payload, { signal })) });
         const body = messages[messages.length - 1];
         const kind = qqOutboundKind(conversation);
         const bot = this.#requireBot();
@@ -134,7 +157,7 @@ export class QqWebsocketEndpoint extends Endpoint {
                 ledger: this.#passiveReplies,
                 activeGate: this.#activeGate,
                 log: fields => this.#logger.warn(formatCompact(fields)),
-            }, conversation, messages);
+            }, { conversation, messages, signal });
         }
         catch (error) {
             const { failure, diagnostic } = qqDeliveryFailure(error);
@@ -150,7 +173,7 @@ export class QqWebsocketEndpoint extends Endpoint {
     async recallMessage(messageId) {
         const { kind, channelId, qqMsgId } = parseCompoundMessageId(messageId);
         const bot = this.#requireBot();
-        await recallQqMessage(bot, kind, channelId, qqMsgId);
+        await recallQqMessage(bot, { kind, channelId, messageId: qqMsgId });
         this.#logger.debug(formatCompact({
             op: 'qq_recall',
             endpoint: this.#options.config.id,
@@ -171,8 +194,10 @@ export class QqWebsocketEndpoint extends Endpoint {
         const roleProjection = projectQqGuildSenderRoles(msg.authorRoles);
         if (msg.id)
             this.#passiveReplies.record(qqOutboundKind(conversation), conversation.id, { id: msg.id });
-        void this.emit('message.receive', {
+        void this[endpointSpec].events.emit('message.receive', {
             conversation,
+            event: msg.event,
+            platformSentAt: msg.platformSentAt,
             message: { conversation, id: msg.id },
             content,
             ...(msg.segments?.length ? { segments: msg.segments } : {}),
@@ -216,13 +241,16 @@ export class QqWebsocketEndpoint extends Endpoint {
         if (this.#seenInteractions.size > 10_000)
             this.#seenInteractions.delete(this.#seenInteractions.keys().next().value);
         // ACK owns only platform loading state, never implies business acceptance.
-        void action.ack().then(ok => { if (ok === false)
-            this.#logger.warn('qq_interaction_ack_failed'); }, () => this.#logger.warn('qq_interaction_ack_failed'));
+        void this[endpointSpec].events.run(() => awaitOwnedAck(action.ack(), this.#executionSignal)).then(ok => { if (ok === false)
+            this.#logger.warn('qq_interaction_ack_failed'); }, () => { if (this.#executionSignal?.aborted)
+            this.#logger.debug('QQ ACK wait cancelled');
+        else
+            this.#logger.warn('qq_interaction_ack_failed'); });
         const conversation = qqInboundConversation(String(this.#options.id), action.message);
         // INTERACTION_CREATE's id is an event_id the reply may answer passively.
         this.#passiveReplies.record(qqOutboundKind(conversation), conversation.id, { event_id: action.message.id });
-        void this.emit('message.receive', {
-            conversation, message: { conversation, id: action.message.id }, content: '',
+        void this[endpointSpec].events.emit('message.receive', {
+            event: action.message.event, conversation, message: { conversation, id: action.message.id }, content: '',
             segments: action.message.segments, sender: { id: action.message.authorId }, endpointId: this.#options.config.id,
             metadata: Object.freeze({ eventType: 'INTERACTION_CREATE', sourceMessageIdAvailable: action.sourceMessageId !== undefined,
                 ...(action.sourceMessageId ? { sourceMessageId: action.sourceMessageId } : {}),
@@ -230,26 +258,50 @@ 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)
-                return;
-            this.#emitPlatformEvent('message', raw);
-            const msg = normalizeQqMessage(raw);
-            if (msg)
-                this.admit(msg);
+            void this[endpointSpec].events.run(() => {
+                if (this.#connection === undefined)
+                    return;
+                this.#emitPlatformEvent('message', raw);
+                const msg = normalizeQqMessage(raw);
+                if (msg)
+                    this.admit(msg);
+            }).catch(() => this.#logger.debug('Native callback was not admitted'));
         });
         bindQqBotSideEvents(bot, (eventName, raw) => {
-            if (this.#bot !== bot)
-                return;
-            this.#emitPlatformEvent(eventName, raw);
-            if (this.admitInteraction(raw))
-                return;
-            receiveQqSideEvent((name, payload) => this.emit(name, payload), this.#options.config.id, bot, eventName, raw, this.#logger);
+            void this[endpointSpec].events.run(() => {
+                if (this.#connection === undefined)
+                    return;
+                this.#emitPlatformEvent(eventName, raw);
+                if (this.admitInteraction(raw))
+                    return;
+                receiveQqSideEvent((name, payload) => this[endpointSpec].events.emit(name, payload), this.#options.config.id, bot, eventName, raw, this.#logger);
+            }).catch(() => this.#logger.debug('Native callback was not admitted'));
         });
     }
     #emitPlatformEvent(name, event) {
-        void this.emitPlatform(name, event).catch((error) => {
+        void this[endpointSpec].events.platform(name, event).catch((error) => {
             this.#logger.warn(formatCompact({
                 op: 'qq_platform_event_failed',
                 event: name,
@@ -258,93 +310,92 @@ export class QqWebsocketEndpoint extends Endpoint {
         });
     }
     #requireBot() {
-        if (!this.#bot)
+        if (!this.#connection)
             throw new EndpointDeliveryError('endpoint_disconnected', 'QQ bot not connected', 'not_sent');
-        return this.#bot;
+        return this;
     }
 }
 /** Webhook / middleware inbound via httpHostToken POST (qq-official-bot Middleware receiver). */
-export class QqHttpEndpoint extends Endpoint {
+export class QqHttpEndpoint extends Bot {
+    [endpointSpec];
     #logger;
     #options;
-    #createBot;
-    #bot = null;
+    #connection;
+    #stopping;
     #open = false;
+    #executionSignal;
+    #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.#connection !== undefined);
+    #control = createQqEndpointControl(() => this.#requireBot(), (id) => this.recallMessage(id));
     constructor(options) {
-        super();
+        super(qqHttpBotOptions(options.config));
         this.#logger = getAdapterLogger('qq', options.config.id);
         this.#lifecycle = createEndpointLifecycle({ name: options.config.id, reconnect: false });
         this.#options = options;
-        this.#createBot = options.createBot ?? defaultCreateHttpBot;
-    }
-    get client() {
-        return this.#requireBot();
+        const endpoint = this;
+        this[endpointSpec] = createEndpointSpecification(this, {
+            start: signal => this.#startFramework(signal), open: () => this.#openFramework(), close: () => this.#closeFramework(),
+            stop: () => this.#stopFramework(), send: request => this.#sendFramework(request), name: options.config.id,
+            get transportState() { return endpoint.#transportState; },
+            management: this.#management, control: this.#control,
+        });
+        this.#bindBot(this);
     }
     /** Live endpoint 名（Console/AdapterIndex 展示用）。 */
     get name() {
         return this.#options.config.id;
     }
-    get transportState() {
+    get #transportState() {
         return this.#lifecycle.state;
     }
-    async start() {
+    async #startFramework(executionSignal) {
+        this.#executionSignal = executionSignal;
         await this.#lifecycle.start(async (handle) => {
-            const bot = this.#createBot(this.#options.config);
-            this.#bot = bot;
-            const releaseUploadDiagnostics = installQqUploadDiagnostics(bot.api, metadata => this.#logger.debug(formatCompact(metadata)));
+            const bot = this;
+            const previousCleanup = this.#cleanup;
+            await previousCleanup?.();
+            const releaseUploadDiagnostics = installQqUploadDiagnostics(bot, metadata => this.#logger.debug(formatCompact(metadata)));
             let cancelled = false;
             const startupAbort = new AbortController();
+            this.#connection = startupAbort;
+            let nativeStart;
             let stopping;
             const routes = [];
             const stopBot = async () => {
-                try {
-                    bot.removeAllListeners();
-                }
-                catch { /* continue SDK cleanup */ }
-                try {
-                    await bot.stop();
-                }
-                catch { /* best-effort SDK cleanup */ }
+                await super.stop();
+                await nativeStart?.catch(() => undefined);
             };
             const cleanup = () => {
                 cancelled = true;
                 releaseUploadDiagnostics();
                 startupAbort.abort();
-                if (this.#bot === bot)
-                    this.#bot = null;
+                if (this.#connection === startupAbort)
+                    this.#connection = undefined;
                 for (const release of routes.splice(0))
                     release();
                 return stopping ??= stopBot();
             };
             this.#cleanup = cleanup;
-            handle.onForceClose(() => { void cleanup(); });
+            handle.onForceClose(() => { void cleanup().catch(() => undefined); });
             try {
-                this.#bindBot(bot);
                 routes.push(...registerQqWebhookRoutes(this.#options.http, {
                     config: this.#options.config,
                     getBot: () => cancelled ? null : bot,
                 }));
-                await awaitQqStartup(bot.start().then(async () => {
-                    if (cancelled)
-                        await stopBot();
-                }, async (error) => {
-                    if (cancelled)
-                        await stopBot();
-                    throw error;
-                }), startupAbort.signal);
+                nativeStart = super.start();
+                await awaitQqStartup(nativeStart.then(() => undefined), startupAbort.signal);
                 if (cancelled) {
                     // SDK startup may create resources after stop; close this exact old client again.
                     await stopping;
                     return;
                 }
+                this.#offlineNoticeAt = 0;
                 this.#logger.info(`connected (${this.#options.config.mode}) | path: ${this.#options.config.webhookPath}`);
             }
             catch (error) {
@@ -352,28 +403,39 @@ export class QqHttpEndpoint extends Endpoint {
                 await cleanup();
                 if (wasCancelled)
                     return;
+                this.#notifyOffline('start_failed');
                 throw error;
             }
         });
     }
-    open() {
+    #openFramework() {
         this.#open = true;
     }
-    close() {
+    #closeFramework() {
         this.#open = false;
     }
-    async stop() {
-        this.#open = false;
-        const cleanup = this.#cleanup;
-        this.#cleanup = undefined;
-        await this.#lifecycle.stop();
-        await cleanup?.();
-        this.#logger.debug(formatCompact({ op: 'disconnect' }));
+    async #stopFramework() {
+        this.#stopping ??= Promise.resolve().then(async () => {
+            this.#open = false;
+            const cleanup = this.#cleanup;
+            this.#cleanup = undefined;
+            try {
+                await this.#lifecycle.stop();
+                await cleanup?.();
+            }
+            finally {
+                this.removeAllListeners(undefined);
+                disposeQqAuthorization(this);
+            }
+            this.#logger.debug(formatCompact({ op: 'disconnect' }));
+        });
+        await this.#stopping;
     }
-    async send({ conversation, payload }) {
+    async #sendFramework({ conversation, payload, signal }) {
         // 媒体与 markdown/按钮不能同条发送（msg_type 7 与 2 互斥）：公网图片嵌入 markdown，
         // 拿不到 URL/尺寸的媒体降级为独立消息先发
-        const messages = formatOutboundMessages(payload, { imageSizes: await collectOutboundImageSizes(payload) });
+        const operation = createEndpointOperation({ signal });
+        const messages = formatOutboundMessages(payload, { imageSizes: await operation.prepare(() => collectOutboundImageSizes(payload, { signal })) });
         const body = messages[messages.length - 1];
         const kind = qqOutboundKind(conversation);
         const bot = this.#requireBot();
@@ -384,7 +446,7 @@ export class QqHttpEndpoint extends Endpoint {
                 ledger: this.#passiveReplies,
                 activeGate: this.#activeGate,
                 log: fields => this.#logger.warn(formatCompact(fields)),
-            }, conversation, messages);
+            }, { conversation, messages, signal });
         }
         catch (error) {
             const { failure, diagnostic } = qqDeliveryFailure(error);
@@ -400,7 +462,7 @@ export class QqHttpEndpoint extends Endpoint {
     async recallMessage(messageId) {
         const { kind, channelId, qqMsgId } = parseCompoundMessageId(messageId);
         const bot = this.#requireBot();
-        await recallQqMessage(bot, kind, channelId, qqMsgId);
+        await recallQqMessage(bot, { kind, channelId, messageId: qqMsgId });
         this.#logger.debug(formatCompact({
             op: 'qq_recall',
             endpoint: this.#options.config.id,
@@ -420,8 +482,10 @@ export class QqHttpEndpoint extends Endpoint {
         const roleProjection = projectQqGuildSenderRoles(msg.authorRoles);
         if (msg.id)
             this.#passiveReplies.record(qqOutboundKind(conversation), conversation.id, { id: msg.id });
-        void this.emit('message.receive', {
+        void this[endpointSpec].events.emit('message.receive', {
             conversation,
+            event: msg.event,
+            platformSentAt: msg.platformSentAt,
             message: { conversation, id: msg.id },
             content,
             ...(msg.segments?.length ? { segments: msg.segments } : {}),
@@ -465,13 +529,16 @@ export class QqHttpEndpoint extends Endpoint {
         if (this.#seenInteractions.size > 10_000)
             this.#seenInteractions.delete(this.#seenInteractions.keys().next().value);
         // ACK owns only platform loading state, never implies business acceptance.
-        void action.ack().then(ok => { if (ok === false)
-            this.#logger.warn('qq_interaction_ack_failed'); }, () => this.#logger.warn('qq_interaction_ack_failed'));
+        void this[endpointSpec].events.run(() => awaitOwnedAck(action.ack(), this.#executionSignal)).then(ok => { if (ok === false)
+            this.#logger.warn('qq_interaction_ack_failed'); }, () => { if (this.#executionSignal?.aborted)
+            this.#logger.debug('QQ ACK wait cancelled');
+        else
+            this.#logger.warn('qq_interaction_ack_failed'); });
         const conversation = qqInboundConversation(String(this.#options.id), action.message);
         // INTERACTION_CREATE's id is an event_id the reply may answer passively.
         this.#passiveReplies.record(qqOutboundKind(conversation), conversation.id, { event_id: action.message.id });
-        void this.emit('message.receive', {
-            conversation, message: { conversation, id: action.message.id }, content: '',
+        void this[endpointSpec].events.emit('message.receive', {
+            event: action.message.event, conversation, message: { conversation, id: action.message.id }, content: '',
             segments: action.message.segments, sender: { id: action.message.authorId }, endpointId: this.#options.config.id,
             metadata: Object.freeze({ eventType: 'INTERACTION_CREATE', sourceMessageIdAvailable: action.sourceMessageId !== undefined,
                 ...(action.sourceMessageId ? { sourceMessageId: action.sourceMessageId } : {}),
@@ -479,26 +546,50 @@ 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)
-                return;
-            this.#emitPlatformEvent('message', raw);
-            const msg = normalizeQqMessage(raw);
-            if (msg)
-                this.admit(msg);
+            void this[endpointSpec].events.run(() => {
+                if (this.#connection === undefined)
+                    return;
+                this.#emitPlatformEvent('message', raw);
+                const msg = normalizeQqMessage(raw);
+                if (msg)
+                    this.admit(msg);
+            }).catch(() => this.#logger.debug('Native callback was not admitted'));
         });
         bindQqBotSideEvents(bot, (eventName, raw) => {
-            if (this.#bot !== bot)
-                return;
-            this.#emitPlatformEvent(eventName, raw);
-            if (this.admitInteraction(raw))
-                return;
-            receiveQqSideEvent((name, payload) => this.emit(name, payload), this.#options.config.id, bot, eventName, raw, this.#logger);
+            void this[endpointSpec].events.run(() => {
+                if (this.#connection === undefined)
+                    return;
+                this.#emitPlatformEvent(eventName, raw);
+                if (this.admitInteraction(raw))
+                    return;
+                receiveQqSideEvent((name, payload) => this[endpointSpec].events.emit(name, payload), this.#options.config.id, bot, eventName, raw, this.#logger);
+            }).catch(() => this.#logger.debug('Native callback was not admitted'));
         });
     }
     #emitPlatformEvent(name, event) {
-        void this.emitPlatform(name, event).catch((error) => {
+        void this[endpointSpec].events.platform(name, event).catch((error) => {
             this.#logger.warn(formatCompact({
                 op: 'qq_platform_event_failed',
                 event: name,
@@ -507,24 +598,41 @@ export class QqHttpEndpoint extends Endpoint {
         });
     }
     #requireBot() {
-        if (!this.#bot)
+        if (!this.#connection)
             throw new EndpointDeliveryError('endpoint_disconnected', 'QQ bot not connected', 'not_sent');
-        return this.#bot;
+        return this;
     }
 }
-function createQqEndpointManagement(requireClient) {
+function createQqEndpointManagement(requireClient, isActive) {
+    const api = () => requireClient();
     return Object.freeze({
-        async listChannels() {
+        // QQ 群（group_openid / member_openid）：官方 v2 群管理接口，部分为白名单能力（11253）。
+        inspectGroupMember: request => inspectQqGroupMember(api(), request),
+        inspectGroupScene: request => inspectQqGroupScene(api(), request),
+        inspectGroupMemberProfile: request => inspectQqGroupMemberProfile(api(), request),
+        moderateGroupMember: request => moderateQqGroupMember({ api: api(), isActive }, request),
+        async listGroupMembers({ groupId, signal }) {
+            const operation = createEndpointOperation({ signal });
+            return operation.run(() => qqGroupService(api()).getMembers(groupId));
+        },
+        async kickGroupMember({ groupId, userId, signal }) {
+            await kickQqGroupMember(api(), { groupId, userId, signal });
+        },
+        async muteGroupMember({ groupId, userId, durationSeconds, signal }) {
+            await muteQqGroupMember(api(), { groupId, userId, durationSeconds, signal });
+        },
+        async listChannels(request = {}) {
+            const operation = createEndpointOperation(request);
             const channels = [];
             const client = requireClient();
-            const guilds = await client.getGuilds();
+            const guilds = await operation.run(() => client.guildService.getList());
             for (const guildValue of Array.isArray(guilds) ? guilds : []) {
                 const guild = asRecord(guildValue);
                 const guildId = String(guild.id ?? guild.guild_id ?? guildValue ?? '');
                 if (!guildId)
                     continue;
                 const guildName = String(guild.name ?? guild.guild_name ?? guildId);
-                const rows = await client.getChannels(guildId);
+                const rows = await operation.run(() => client.channelService.getList(guildId));
                 for (const channelValue of Array.isArray(rows) ? rows : []) {
                     const channel = asRecord(channelValue);
                     const id = String(channel.id ?? channel.channel_id ?? channelValue ?? '');
@@ -546,7 +654,66 @@ function asRecord(value) {
         ? value
         : {};
 }
-async function recallQqMessage(bot, kind, channelId, messageId) {
+/**
+ * Recall + 频道表情回应。recall 同时接受 send() 的复合 ID 与入站原生消息 ID（目标取自 MessageRef.conversation），
+ * 因此群管理员机器人可撤回普通成员 2 分钟内的消息（官方限制由平台执行）。
+ * 表情回应只有频道子频道消息支持（官方无群 / 单聊表情回应接口）。
+ */
+function createQqEndpointControl(requireBot, recallById) {
+    return Object.freeze({
+        recall: async ({ message, signal }) => {
+            if (isCompoundMessageId(message.id))
+                return createEndpointOperation({ signal }).run(() => recallById(message.id));
+            const kind = qqOutboundKind(message.conversation);
+            await createEndpointOperation({ signal }).run(() => recallQqMessage(requireBot(), { kind, channelId: message.conversation.id, messageId: message.id }));
+        },
+        addReaction: async ({ message, emoji, signal }) => {
+            const target = qqGuildReactionTarget(message, emoji);
+            if (!target)
+                return null;
+            await createEndpointOperation({ signal }).run(() => requireBot().reactionService.addGuildMessageReaction(target.channelId, target.messageId, target.type, target.id));
+            return `${target.type}:${target.id}`;
+        },
+        removeReaction: async ({ message, reactionId, signal }) => {
+            const target = qqGuildReactionTarget(message, reactionId);
+            if (!target)
+                return;
+            await createEndpointOperation({ signal }).run(() => requireBot().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];
     if (!recall)
@@ -555,3 +722,15 @@ async function recallQqMessage(bot, kind, channelId, messageId) {
         throw new EndpointDeliveryError('invalid_message_id', 'QQ recall requires a nonempty message ID', 'not_sent');
     await recall.call(bot, channelId, messageId);
 }
+/** Logical cancellation only; the native SDK still owns its already-started ACK. */
+function awaitOwnedAck(operation, signal) {
+    if (!signal)
+        return operation;
+    return new Promise((resolve, reject) => {
+        const abort = () => reject(signal.reason);
+        signal.addEventListener('abort', abort, { once: true });
+        void operation.then(resolve, reject).finally(() => signal.removeEventListener('abort', abort));
+        if (signal.aborted)
+            abort();
+    });
+}