@zhin.js/adapter-qq 1.1.18 → 1.1.19

package/lib/endpoint.js

@@ -1,3 +1,4 @@
+import { Bot } from 'qq-official-bot';
 import { installQqUploadDiagnostics } from './upload-diagnostics.js';
 import { projectQqGuildSenderRoles } from './platform-permit.js';
 import { qqDeliveryFailure } from './delivery-error.js';
@@ -8,21 +9,24 @@ import { inspectQqGroupMember, inspectQqGroupMemberProfile, inspectQqGroupScene,
 /**
  * QQ endpoints — lifecycle, outbound, admit, agent tool surface.
  */
-import { Endpoint, createEndpointLifecycle, } 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. */
@@ -30,72 +34,71 @@ export class QqWebsocketEndpoint extends Endpoint {
     #activeGate = new QqActiveMessageGate();
     #lifecycle;
     #cleanup;
-    management = createQqEndpointManagement(() => this.#requireBot(), () => this.#open && this.#bot !== null);
-    control = createQqEndpointControl(() => this.#requireBot(), (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)
+                transportClose = () => {
+                    if (cancelled || this.#connection === undefined)
                         return;
                     this.#notifyOffline('transport_close');
-                    void cleanup();
+                    void cleanup().catch(() => undefined);
                     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);
+                };
+                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;
@@ -115,24 +118,35 @@ export class QqWebsocketEndpoint extends Endpoint {
             }
         });
     }
-    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();
@@ -143,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);
@@ -159,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,
@@ -180,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 } : {}),
@@ -225,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 } : {}),
@@ -261,24 +280,28 @@ export class QqWebsocketEndpoint extends Endpoint {
     }
     #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,
@@ -287,18 +310,20 @@ 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. */
@@ -306,70 +331,65 @@ export class QqHttpEndpoint extends Endpoint {
     #activeGate = new QqActiveMessageGate();
     #lifecycle;
     #cleanup;
-    management = createQqEndpointManagement(() => this.#requireBot(), () => this.#open && this.#bot !== null);
-    control = createQqEndpointControl(() => this.#requireBot(), (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;
@@ -388,24 +408,34 @@ export class QqHttpEndpoint extends Endpoint {
             }
         });
     }
-    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();
@@ -416,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);
@@ -432,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,
@@ -452,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 } : {}),
@@ -497,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 } : {}),
@@ -533,24 +568,28 @@ export class QqHttpEndpoint extends Endpoint {
     }
     #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,
@@ -559,39 +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, isActive) {
-    const api = () => requireClient().api;
+    const api = () => requireClient();
     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);
+        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) {
-            await kickQqGroupMember(api(), groupId, userId);
+        async kickGroupMember({ groupId, userId, signal }) {
+            await kickQqGroupMember(api(), { groupId, userId, signal });
         },
-        async muteGroupMember(groupId, userId, durationSeconds) {
-            await muteQqGroupMember(api(), groupId, userId, durationSeconds);
+        async muteGroupMember({ groupId, userId, durationSeconds, signal }) {
+            await muteQqGroupMember(api(), { groupId, userId, durationSeconds, signal });
         },
-        async listChannels() {
+        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 ?? '');
@@ -620,24 +661,24 @@ function asRecord(value) {
  */
 function createQqEndpointControl(requireBot, recallById) {
     return Object.freeze({
-        recall: async (message) => {
+        recall: async ({ message, signal }) => {
             if (isCompoundMessageId(message.id))
-                return recallById(message.id);
+                return createEndpointOperation({ signal }).run(() => recallById(message.id));
             const kind = qqOutboundKind(message.conversation);
-            await recallQqMessage(requireBot(), kind, message.conversation.id, message.id);
+            await createEndpointOperation({ signal }).run(() => recallQqMessage(requireBot(), { kind, channelId: message.conversation.id, messageId: message.id }));
         },
-        addReaction: async (message, emoji) => {
+        addReaction: async ({ message, emoji, signal }) => {
             const target = qqGuildReactionTarget(message, emoji);
             if (!target)
                 return null;
-            await requireBot().api.reactionService.addGuildMessageReaction(target.channelId, target.messageId, target.type, target.id);
+            await createEndpointOperation({ signal }).run(() => requireBot().reactionService.addGuildMessageReaction(target.channelId, target.messageId, target.type, target.id));
             return `${target.type}:${target.id}`;
         },
-        removeReaction: async (message, reactionId) => {
+        removeReaction: async ({ message, reactionId, signal }) => {
             const target = qqGuildReactionTarget(message, reactionId);
             if (!target)
                 return;
-            await requireBot().api.reactionService.deleteGuildMessageReaction(target.channelId, target.messageId, target.type, target.id);
+            await createEndpointOperation({ signal }).run(() => requireBot().reactionService.deleteGuildMessageReaction(target.channelId, target.messageId, target.type, target.id));
         },
     });
 }
@@ -672,7 +713,7 @@ function qqGuildReactionTarget(message, emoji) {
     const parsed = parseQqEmoji(emoji);
     return parsed ? { channelId, messageId, ...parsed } : null;
 }
-async function recallQqMessage(bot, kind, channelId, messageId) {
+async function recallQqMessage(bot, { kind, channelId, messageId }) {
     const recall = { private: bot.recallPrivateMessage, group: bot.recallGroupMessage,
         channel: bot.recallGuildMessage, direct: bot.recallDirectMessage }[kind];
     if (!recall)
@@ -681,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();
+    });
+}