@zhin.js/adapter-qq 1.1.17 → 1.1.19

package/src/endpoint.ts

@@ -1,20 +1,40 @@
+import { Bot, ReceiverMode } 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 { EndpointDeliveryError, type MessageRef } 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, type EndpointLifecycle,
-  createRecallEndpointControl,
+  createEndpointSpecification,
+  endpointSpec,
+  type Endpoint,
+  type EndpointSpecification,
+  createEndpointLifecycle,
+  type EndpointLifecycle,
   type EndpointControl,
   type EndpointChannel,
   type EndpointManagement,
   type EndpointSendRequest,
   type EndpointTransportState,
+  type AdapterOutageNotifier,
+  createEndpointOperation,
+  type EndpointGroupRequest,
+  type EndpointMemberRequest,
+  type EndpointMuteRequest,
+  type EndpointManagementRequest,
 } from 'zhin.js/adapter';
 import type { HttpHost } from '@zhin.js/host-http';
 import { formatCompact, getAdapterLogger, truncatePreview } from '@zhin.js/logger';
@@ -34,16 +54,14 @@ import {
   type ResolvedQqWebsocketConfig,
 } from './protocol.js';
 import {
-  defaultCreateHttpBot,
+  qqHttpBotOptions,
   registerQqWebhookRoutes,
-  type CreateQqHttpBot,
   type QqHttpBotTransport,
 } from './webhook.js';
 import {
   bindQqBotInboundEvents,
-  defaultCreateBot,
+  qqWebsocketBotOptions, configureQqWebsocketReceiver, disposeQqAuthorization,
   normalizeQqMessage,
-  type CreateQqBot,
   type QqBotTransport,
 } from './ws.js';
 import {
@@ -52,41 +70,49 @@ import {
   type QqSideEventCaller,
 } from './side-event-dispatch.js';
 
-export type { CreateQqBot, QqBotTransport, QqOfficialApi } from './ws.js';
-export type { CreateQqHttpBot, QqHttpBotTransport } from './webhook.js';
+export type { QqBotTransport, QqOfficialApi } from './ws.js';
+export type { QqHttpBotTransport } from './webhook.js';
 
 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 class QqWebsocketEndpoint extends Endpoint<QqBotTransport> {
+export class QqWebsocketEndpoint extends Bot<ReceiverMode.WEBSOCKET> implements Endpoint {
+  readonly [endpointSpec]: EndpointSpecification;
+  readonly #receiverResources: ReturnType<typeof configureQqWebsocketReceiver>;
   readonly #logger!: ReturnType<typeof getAdapterLogger>;
 
   readonly #options: QqEndpointOptions;
-  readonly #createBot: CreateQqBot;
-  #bot: QqBotTransport | null = null;
+  #connection?: AbortController;
+  #stopping?: Promise<void>;
   #open = false;
+  #executionSignal?: AbortSignal;
+  #offlineNoticeAt = 0;
   readonly #seenInteractions = new Map<string, number>();
   /** Recent msg_id / event_id per conversation, so replies go out as passive messages. */
   readonly #passiveReplies = new QqPassiveReplyLedger();
   readonly #activeGate = new QqActiveMessageGate();
   readonly #lifecycle: EndpointLifecycle;
   #cleanup?: () => Promise<void>;
-  readonly management: EndpointManagement = createQqEndpointManagement(() => this.#requireBot());
-  readonly control: EndpointControl = createRecallEndpointControl((id) => this.recallMessage(id));
+  readonly #management: EndpointManagement = createQqEndpointManagement(() => this.#requireBot(), () => this.#open && this.#connection !== undefined);
+  readonly #control: EndpointControl = createQqEndpointControl(() => this.#requireBot(), (id) => this.recallMessage(id));
 
   constructor(options: QqEndpointOptions) {
-    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(): QqBotTransport {
-    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 别名）。 */
@@ -94,51 +120,60 @@ export class QqWebsocketEndpoint extends Endpoint<QqBotTransport> {
     return this.#options.config.id;
   }
 
-  get transportState(): EndpointTransportState {
+  get #transportState(): EndpointTransportState {
     if (this.#lifecycle.state !== 'open') return this.#lifecycle.state;
-    return this.#bot?.transportState ?? this.#lifecycle.state;
+    return this.#receiverResources.state();
   }
 
-  async start(): Promise<void> {
+  async #startFramework(executionSignal: AbortSignal): Promise<void> {
+    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: Promise<unknown> | undefined;
       let stopping: Promise<void> | undefined;
+      let transportClose: (() => void) | undefined;
       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) {
         const wasCancelled = cancelled;
         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}）`,
@@ -148,27 +183,31 @@ export class QqWebsocketEndpoint extends Endpoint<QqBotTransport> {
     });
   }
 
-  open(): void {
+  #openFramework(): void {
     this.#open = true;
   }
 
-  close(): void {
+  #closeFramework(): void {
     this.#open = false;
   }
 
-  async stop(): Promise<void> {
-    this.#open = false;
-    const cleanup = this.#cleanup;
-    this.#cleanup = undefined;
-    await this.#lifecycle.stop();
-    await cleanup?.();
+  async #stopFramework(): Promise<void> {
+    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 as never); this.#receiverResources.dispose(); disposeQqAuthorization(this); }
+    });
+    await this.#stopping;
     this.#logger.debug(formatCompact({ op: 'disconnect' }));
   }
 
-  async send({ conversation, payload }: EndpointSendRequest): Promise<string> {
+  async #sendFramework({ conversation, payload, signal }: EndpointSendRequest): Promise<string> {
     // 媒体与 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();
@@ -179,7 +218,7 @@ export class QqWebsocketEndpoint extends Endpoint<QqBotTransport> {
         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);
       this.#logger.warn(formatCompact(diagnostic));
@@ -197,7 +236,7 @@ export class QqWebsocketEndpoint extends Endpoint<QqBotTransport> {
   async recallMessage(messageId: string): Promise<void> {
     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,
@@ -219,8 +258,10 @@ export class QqWebsocketEndpoint extends Endpoint<QqBotTransport> {
     );
     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 } : {}),
@@ -259,12 +300,15 @@ export class QqWebsocketEndpoint extends Endpoint<QqBotTransport> {
     this.#seenInteractions.set(action.message.id, now);
     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 } : {}),
@@ -273,30 +317,52 @@ export class QqWebsocketEndpoint extends Endpoint<QqBotTransport> {
     return true;
   }
 
+  #notifyOffline(reason: string): void {
+    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: QqBotTransport): void {
     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 as QqSideEventCaller,
-        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: string, event: unknown): void {
-    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,
@@ -306,8 +372,8 @@ export class QqWebsocketEndpoint extends Endpoint<QqBotTransport> {
   }
 
   #requireBot(): QqBotTransport {
-    if (!this.#bot) throw new EndpointDeliveryError('endpoint_disconnected', 'QQ bot not connected', 'not_sent');
-    return this.#bot;
+    if (!this.#connection) throw new EndpointDeliveryError('endpoint_disconnected', 'QQ bot not connected', 'not_sent');
+    return this;
   }
 }
 
@@ -315,36 +381,43 @@ export interface QqHttpEndpointOptions {
   readonly id: CapabilityId;
   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 class QqHttpEndpoint extends Endpoint<QqHttpBotTransport> {
+export class QqHttpEndpoint extends Bot<ReceiverMode.MIDDLEWARE, 'koa'> implements Endpoint {
+  readonly [endpointSpec]: EndpointSpecification;
   readonly #logger!: ReturnType<typeof getAdapterLogger>;
 
   readonly #options: QqHttpEndpointOptions;
-  readonly #createBot: CreateQqHttpBot;
-  #bot: QqHttpBotTransport | null = null;
+  #connection?: AbortController;
+  #stopping?: Promise<void>;
   #open = false;
+  #executionSignal?: AbortSignal;
+  #offlineNoticeAt = 0;
   readonly #seenInteractions = new Map<string, number>();
   /** Recent msg_id / event_id per conversation, so replies go out as passive messages. */
   readonly #passiveReplies = new QqPassiveReplyLedger();
   readonly #activeGate = new QqActiveMessageGate();
   readonly #lifecycle: EndpointLifecycle;
   #cleanup?: () => Promise<void>;
-  readonly management: EndpointManagement = createQqEndpointManagement(() => this.#requireBot());
-  readonly control: EndpointControl = createRecallEndpointControl((id) => this.recallMessage(id));
+  readonly #management: EndpointManagement = createQqEndpointManagement(() => this.#requireBot(), () => this.#open && this.#connection !== undefined);
+  readonly #control: EndpointControl = createQqEndpointControl(() => this.#requireBot(), (id) => this.recallMessage(id));
 
   constructor(options: QqHttpEndpointOptions) {
-    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(): QqHttpBotTransport {
-    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 展示用）。 */
@@ -352,81 +425,86 @@ export class QqHttpEndpoint extends Endpoint<QqHttpBotTransport> {
     return this.#options.config.id;
   }
 
-  get transportState(): EndpointTransportState {
+  get #transportState(): EndpointTransportState {
     return this.#lifecycle.state;
   }
 
-  async start(): Promise<void> {
+  async #startFramework(executionSignal: AbortSignal): Promise<void> {
+    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: Promise<unknown> | undefined;
       let stopping: Promise<void> | undefined;
       const routes: Array<() => void> = [];
       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) {
         const wasCancelled = cancelled;
         await cleanup();
         if (wasCancelled) return;
+        this.#notifyOffline('start_failed');
         throw error;
       }
     });
   }
 
-  open(): void {
+  #openFramework(): void {
     this.#open = true;
   }
 
-  close(): void {
+  #closeFramework(): void {
     this.#open = false;
   }
 
-  async stop(): Promise<void> {
-    this.#open = false;
-    const cleanup = this.#cleanup;
-    this.#cleanup = undefined;
-    await this.#lifecycle.stop();
-    await cleanup?.();
-    this.#logger.debug(formatCompact({ op: 'disconnect' }));
+  async #stopFramework(): Promise<void> {
+    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 as never); disposeQqAuthorization(this); }
+      this.#logger.debug(formatCompact({ op: 'disconnect' }));
+    });
+    await this.#stopping;
   }
 
-  async send({ conversation, payload }: EndpointSendRequest): Promise<string> {
+  async #sendFramework({ conversation, payload, signal }: EndpointSendRequest): Promise<string> {
     // 媒体与 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();
@@ -437,7 +515,7 @@ export class QqHttpEndpoint extends Endpoint<QqHttpBotTransport> {
         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);
       this.#logger.warn(formatCompact(diagnostic));
@@ -455,7 +533,7 @@ export class QqHttpEndpoint extends Endpoint<QqHttpBotTransport> {
   async recallMessage(messageId: string): Promise<void> {
     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,
@@ -476,8 +554,10 @@ export class QqHttpEndpoint extends Endpoint<QqHttpBotTransport> {
     );
     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 } : {}),
@@ -516,12 +596,15 @@ export class QqHttpEndpoint extends Endpoint<QqHttpBotTransport> {
     this.#seenInteractions.set(action.message.id, now);
     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 } : {}),
@@ -530,30 +613,52 @@ export class QqHttpEndpoint extends Endpoint<QqHttpBotTransport> {
     return true;
   }
 
+  #notifyOffline(reason: string): void {
+    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: QqBotTransport): void {
     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 as QqSideEventCaller,
-        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: string, event: unknown): void {
-    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,
@@ -563,25 +668,43 @@ export class QqHttpEndpoint extends Endpoint<QqHttpBotTransport> {
   }
 
   #requireBot(): QqHttpBotTransport {
-    if (!this.#bot) throw new EndpointDeliveryError('endpoint_disconnected', 'QQ bot not connected', 'not_sent');
-    return this.#bot;
+    if (!this.#connection) throw new EndpointDeliveryError('endpoint_disconnected', 'QQ bot not connected', 'not_sent');
+    return this;
   }
 }
 
 function createQqEndpointManagement(
-  requireClient: () => Pick<QqBotTransport, 'getGuilds' | 'getChannels'>,
+  requireClient: () => QqBotTransport,
+  isActive: () => boolean,
 ): EndpointManagement {
+  const api = () => requireClient();
   return Object.freeze<EndpointManagement>({
-    async listChannels(): Promise<readonly EndpointChannel[]> {
+    // 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 }: EndpointGroupRequest): Promise<readonly unknown[]> {
+      const operation = createEndpointOperation({ signal });
+      return operation.run(() => qqGroupService(api()).getMembers(groupId));
+    },
+    async kickGroupMember({ groupId, userId, signal }: EndpointMemberRequest): Promise<void> {
+      await kickQqGroupMember(api(), { groupId, userId, signal });
+    },
+    async muteGroupMember({ groupId, userId, durationSeconds, signal }: EndpointMuteRequest): Promise<void> {
+      await muteQqGroupMember(api(), { groupId, userId, durationSeconds, signal });
+    },
+    async listChannels(request: EndpointManagementRequest = {}): Promise<readonly EndpointChannel[]> {
+      const operation = createEndpointOperation(request);
       const channels: EndpointChannel[] = [];
       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 ?? '');
@@ -604,10 +727,74 @@ function asRecord(value: unknown): Record<string, unknown> {
     : {};
 }
 
-async function recallQqMessage(bot: QqBotTransport, kind: ReturnType<typeof qqOutboundKind>, channelId: string, messageId: string): Promise<void> {
+/**
+ * Recall + 频道表情回应。recall 同时接受 send() 的复合 ID 与入站原生消息 ID（目标取自 MessageRef.conversation），
+ * 因此群管理员机器人可撤回普通成员 2 分钟内的消息（官方限制由平台执行）。
+ * 表情回应只有频道子频道消息支持（官方无群 / 单聊表情回应接口）。
+ */
+function createQqEndpointControl(
+  requireBot: () => QqBotTransport,
+  recallById: (messageId: string) => Promise<void>,
+): EndpointControl {
+  return Object.freeze<EndpointControl>({
+    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: string): boolean {
+  try { parseCompoundMessageId(id); return true; } catch { return false; }
+}
+
+/** `type:id`（1 系统表情 / 2 emoji）或单个 Unicode emoji（→ type 2 + 码点）。 */
+export function parseQqEmoji(value: string): { type: 1 | 2; id: `${number}` } | null {
+  const explicit = /^([12]):(\d+)$/.exec(value.trim());
+  if (explicit) return { type: Number(explicit[1]) as 1 | 2, id: explicit[2] as `${number}` };
+  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) as `${number}` } : null;
+}
+
+function qqGuildReactionTarget(message: MessageRef, emoji: string) {
+  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: QqBotTransport, { kind, channelId, messageId }: { readonly kind: ReturnType<typeof qqOutboundKind>; readonly channelId: string; readonly messageId: string }): Promise<void> {
   const recall = { private: bot.recallPrivateMessage, group: bot.recallGroupMessage,
     channel: bot.recallGuildMessage, direct: bot.recallDirectMessage }[kind];
   if (!recall) throw new EndpointDeliveryError('recall_unsupported', 'QQ transport does not support recall for this conversation', 'not_sent');
   if (!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<T>(operation: Promise<T>, signal?: AbortSignal): Promise<T> {
+  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();
+  });
+}