@zhin.js/adapter-qq 1.1.4 → 1.1.6

package/src/endpoint.ts

@@ -1,3 +1,8 @@
+import { installQqUploadDiagnostics } from './upload-diagnostics.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';
 /**
  * QQ endpoints — lifecycle, outbound, admit, agent tool surface.
  */
@@ -8,6 +13,7 @@ import {
   type EndpointChannel,
   type EndpointManagement,
   type EndpointSendRequest,
+  type EndpointTransportState,
 } from 'zhin.js/adapter';
 import type { HttpHost } from '@zhin.js/host-http';
 import { formatCompact, getAdapterLogger, truncatePreview } from '@zhin.js/logger';
@@ -59,6 +65,7 @@ export class QqWebsocketEndpoint extends Endpoint<QqBotTransport> {
   readonly #createBot: CreateQqBot;
   #bot: QqBotTransport | null = null;
   #open = false;
+  readonly #seenInteractions = new Map<string, number>();
   readonly #lifecycle: EndpointLifecycle;
   #cleanup?: () => Promise<void>;
   readonly management: EndpointManagement = createQqEndpointManagement(() => this.#requireBot());
@@ -67,7 +74,7 @@ export class QqWebsocketEndpoint extends Endpoint<QqBotTransport> {
   constructor(options: QqEndpointOptions) {
     super();
     this.#logger = getAdapterLogger('qq', options.config.id);
-    this.#lifecycle = createEndpointLifecycle({ name: options.config.id, reconnect: false });
+    this.#lifecycle = createEndpointLifecycle({ name: options.config.id });
     this.#options = options;
     this.#createBot = options.createBot ?? defaultCreateBot;
   }
@@ -81,11 +88,18 @@ export class QqWebsocketEndpoint extends Endpoint<QqBotTransport> {
     return this.#options.config.id;
   }
 
+  get transportState(): EndpointTransportState {
+    if (this.#lifecycle.state !== 'open') return this.#lifecycle.state;
+    return this.#bot?.transportState ?? this.#lifecycle.state;
+  }
+
   async start(): Promise<void> {
     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)));
       let cancelled = false;
+      const startupAbort = new AbortController();
       let stopping: Promise<void> | undefined;
       const stopBot = async () => {
         try { bot.removeAllListeners(); } catch { /* continue SDK cleanup */ }
@@ -93,28 +107,32 @@ export class QqWebsocketEndpoint extends Endpoint<QqBotTransport> {
       };
       const cleanup = () => {
         cancelled = true;
+        releaseUploadDiagnostics();
+        startupAbort.abort();
         if (this.#bot === bot) this.#bot = null;
         return stopping ??= stopBot();
       };
       this.#cleanup = cleanup;
       handle.onForceClose(() => { void cleanup(); });
       try {
+        bot.on('transport.close', () => { if (cancelled || this.#bot !== bot) return; void cleanup(); handle.notifyClosed(); });
         this.#bindBot(bot);
-        await bot.start();
+        await awaitQqStartup(bot.start().then(async () => {
+          if (cancelled) await stopBot();
+        }, async (error) => {
+          if (cancelled) await stopBot();
+          throw error;
+        }), startupAbort.signal);
         if (cancelled) {
           // SDK startup may create resources after stop; close this exact old client again.
           await stopping;
-          await stopBot();
           return;
         }
         this.#logger.info(`connected (websocket) | appid: ${this.#options.config.appid}`);
       } catch (error) {
         const wasCancelled = cancelled;
         await cleanup();
-        if (wasCancelled) {
-          await stopBot();
-          return;
-        }
+        if (wasCancelled) return;
         const raw = error instanceof Error ? error.message : String(error);
         throw new Error(
           `QQ WebSocket 连接失败：请检查 appid/secret 是否配对、网关地址（gatewayUrl/accessTokenUrl）是否可达（原始错误：${raw}）`,
@@ -146,20 +164,26 @@ export class QqWebsocketEndpoint extends Endpoint<QqBotTransport> {
     const kind = qqOutboundKind(conversation);
     const bot = this.#requireBot();
     let result: unknown;
-    switch (kind) {
-      case 'private':
-        result = await bot.sendPrivateMessage(conversation.id, body);
-        break;
-      case 'group':
-        result = await bot.sendGroupMessage(conversation.id, body);
-        break;
-      case 'channel':
-        result = await bot.sendGuildMessage(conversation.id, body);
-        break;
-      case 'direct':
-        if (!bot.sendDirectMessage) throw new Error('QQ direct message not supported by transport');
-        result = await bot.sendDirectMessage(conversation.id, body);
-        break;
+    try {
+      switch (kind) {
+        case 'private':
+          result = await bot.sendPrivateMessage(conversation.id, body);
+          break;
+        case 'group':
+          result = await bot.sendGroupMessage(conversation.id, body);
+          break;
+        case 'channel':
+          result = await bot.sendGuildMessage(conversation.id, body);
+          break;
+        case 'direct':
+          if (!bot.sendDirectMessage) throw new Error('QQ direct message not supported by transport');
+          result = await bot.sendDirectMessage(conversation.id, body);
+          break;
+      }
+    } catch (error) {
+      const { failure, diagnostic } = qqDeliveryFailure(error);
+      this.#logger.warn(formatCompact(diagnostic));
+      throw failure;
     }
     const messageId = `${kind}-${conversation.id}:${resolveOutboundMessageId(result)}`;
     this.#logger.info(
@@ -173,20 +197,7 @@ export class QqWebsocketEndpoint extends Endpoint<QqBotTransport> {
   async recallMessage(messageId: string): Promise<void> {
     const { kind, channelId, qqMsgId } = parseCompoundMessageId(messageId);
     const bot = this.#requireBot();
-    switch (kind) {
-      case 'private':
-        await bot.recallPrivateMessage?.(channelId, qqMsgId);
-        break;
-      case 'group':
-        await bot.recallGroupMessage?.(channelId, qqMsgId);
-        break;
-      case 'channel':
-        await bot.recallGuildMessage?.(channelId, qqMsgId);
-        break;
-      case 'direct':
-        await bot.recallDirectMessage?.(channelId, qqMsgId);
-        break;
-    }
+    await recallQqMessage(bot, kind, channelId, qqMsgId);
     this.#logger.debug(formatCompact({
       op: 'qq_recall',
       endpoint: this.#options.config.id,
@@ -233,6 +244,29 @@ export class QqWebsocketEndpoint extends Endpoint<QqBotTransport> {
     });
   }
 
+  /** Native click only; C2C/group have no platform source message ID. */
+  admitInteraction(raw: unknown): boolean {
+    if (!this.#open) return false;
+    const action = normalizeQqInteraction(raw);
+    if (!action) return false;
+    const now = Date.now();
+    for (const [id, time] of this.#seenInteractions) if (now - time > 300_000) this.#seenInteractions.delete(id);
+    if (this.#seenInteractions.has(action.message.id)) return true;
+    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'));
+    const conversation = qqInboundConversation(String(this.#options.id), action.message);
+    void this.emit('message.receive', {
+      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 } : {}),
+        callbackAssociation: action.sourceMessageId ? 'source-message' : 'payload-conversation-actor' }),
+    }).catch(() => this.#logger.warn('qq_interaction_receive_failed'));
+    return true;
+  }
+
   #bindBot(bot: QqBotTransport): void {
     bindQqBotInboundEvents(bot, (raw) => {
       if (this.#bot !== bot) return;
@@ -243,6 +277,7 @@ export class QqWebsocketEndpoint extends Endpoint<QqBotTransport> {
     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,
@@ -265,7 +300,7 @@ export class QqWebsocketEndpoint extends Endpoint<QqBotTransport> {
   }
 
   #requireBot(): QqBotTransport {
-    if (!this.#bot) throw new Error('QQ bot not connected');
+    if (!this.#bot) throw new EndpointDeliveryError('endpoint_disconnected', 'QQ bot not connected', 'not_sent');
     return this.#bot;
   }
 }
@@ -285,6 +320,7 @@ export class QqHttpEndpoint extends Endpoint<QqHttpBotTransport> {
   readonly #createBot: CreateQqHttpBot;
   #bot: QqHttpBotTransport | null = null;
   #open = false;
+  readonly #seenInteractions = new Map<string, number>();
   readonly #lifecycle: EndpointLifecycle;
   #cleanup?: () => Promise<void>;
   readonly management: EndpointManagement = createQqEndpointManagement(() => this.#requireBot());
@@ -307,11 +343,17 @@ export class QqHttpEndpoint extends Endpoint<QqHttpBotTransport> {
     return this.#options.config.id;
   }
 
+  get transportState(): EndpointTransportState {
+    return this.#lifecycle.state;
+  }
+
   async start(): Promise<void> {
     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)));
       let cancelled = false;
+      const startupAbort = new AbortController();
       let stopping: Promise<void> | undefined;
       const routes: Array<() => void> = [];
       const stopBot = async () => {
@@ -320,6 +362,8 @@ export class QqHttpEndpoint extends Endpoint<QqHttpBotTransport> {
       };
       const cleanup = () => {
         cancelled = true;
+        releaseUploadDiagnostics();
+        startupAbort.abort();
         if (this.#bot === bot) this.#bot = null;
         for (const release of routes.splice(0)) release();
         return stopping ??= stopBot();
@@ -332,21 +376,22 @@ export class QqHttpEndpoint extends Endpoint<QqHttpBotTransport> {
           config: this.#options.config,
           getBot: () => cancelled ? null : bot,
         }));
-        await bot.start();
+        await awaitQqStartup(bot.start().then(async () => {
+          if (cancelled) await stopBot();
+        }, async (error) => {
+          if (cancelled) await stopBot();
+          throw error;
+        }), startupAbort.signal);
         if (cancelled) {
           // SDK startup may create resources after stop; close this exact old client again.
           await stopping;
-          await stopBot();
           return;
         }
         this.#logger.info(`connected (${this.#options.config.mode}) | path: ${this.#options.config.webhookPath}`);
       } catch (error) {
         const wasCancelled = cancelled;
         await cleanup();
-        if (wasCancelled) {
-          await stopBot();
-          return;
-        }
+        if (wasCancelled) return;
         throw error;
       }
     });
@@ -374,20 +419,26 @@ export class QqHttpEndpoint extends Endpoint<QqHttpBotTransport> {
     const kind = qqOutboundKind(conversation);
     const bot = this.#requireBot();
     let result: unknown;
-    switch (kind) {
-      case 'private':
-        result = await bot.sendPrivateMessage(conversation.id, body);
-        break;
-      case 'group':
-        result = await bot.sendGroupMessage(conversation.id, body);
-        break;
-      case 'channel':
-        result = await bot.sendGuildMessage(conversation.id, body);
-        break;
-      case 'direct':
-        if (!bot.sendDirectMessage) throw new Error('QQ direct message not supported by transport');
-        result = await bot.sendDirectMessage(conversation.id, body);
-        break;
+    try {
+      switch (kind) {
+        case 'private':
+          result = await bot.sendPrivateMessage(conversation.id, body);
+          break;
+        case 'group':
+          result = await bot.sendGroupMessage(conversation.id, body);
+          break;
+        case 'channel':
+          result = await bot.sendGuildMessage(conversation.id, body);
+          break;
+        case 'direct':
+          if (!bot.sendDirectMessage) throw new Error('QQ direct message not supported by transport');
+          result = await bot.sendDirectMessage(conversation.id, body);
+          break;
+      }
+    } catch (error) {
+      const { failure, diagnostic } = qqDeliveryFailure(error);
+      this.#logger.warn(formatCompact(diagnostic));
+      throw failure;
     }
     const messageId = `${kind}-${conversation.id}:${resolveOutboundMessageId(result)}`;
     this.#logger.info(
@@ -401,20 +452,7 @@ export class QqHttpEndpoint extends Endpoint<QqHttpBotTransport> {
   async recallMessage(messageId: string): Promise<void> {
     const { kind, channelId, qqMsgId } = parseCompoundMessageId(messageId);
     const bot = this.#requireBot();
-    switch (kind) {
-      case 'private':
-        await bot.recallPrivateMessage?.(channelId, qqMsgId);
-        break;
-      case 'group':
-        await bot.recallGroupMessage?.(channelId, qqMsgId);
-        break;
-      case 'channel':
-        await bot.recallGuildMessage?.(channelId, qqMsgId);
-        break;
-      case 'direct':
-        await bot.recallDirectMessage?.(channelId, qqMsgId);
-        break;
-    }
+    await recallQqMessage(bot, kind, channelId, qqMsgId);
     this.#logger.debug(formatCompact({
       op: 'qq_recall',
       endpoint: this.#options.config.id,
@@ -460,6 +498,29 @@ export class QqHttpEndpoint extends Endpoint<QqHttpBotTransport> {
     });
   }
 
+  /** Native click only; C2C/group have no platform source message ID. */
+  admitInteraction(raw: unknown): boolean {
+    if (!this.#open) return false;
+    const action = normalizeQqInteraction(raw);
+    if (!action) return false;
+    const now = Date.now();
+    for (const [id, time] of this.#seenInteractions) if (now - time > 300_000) this.#seenInteractions.delete(id);
+    if (this.#seenInteractions.has(action.message.id)) return true;
+    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'));
+    const conversation = qqInboundConversation(String(this.#options.id), action.message);
+    void this.emit('message.receive', {
+      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 } : {}),
+        callbackAssociation: action.sourceMessageId ? 'source-message' : 'payload-conversation-actor' }),
+    }).catch(() => this.#logger.warn('qq_interaction_receive_failed'));
+    return true;
+  }
+
   #bindBot(bot: QqBotTransport): void {
     bindQqBotInboundEvents(bot, (raw) => {
       if (this.#bot !== bot) return;
@@ -470,6 +531,7 @@ export class QqHttpEndpoint extends Endpoint<QqHttpBotTransport> {
     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,
@@ -492,7 +554,7 @@ export class QqHttpEndpoint extends Endpoint<QqHttpBotTransport> {
   }
 
   #requireBot(): QqHttpBotTransport {
-    if (!this.#bot) throw new Error('QQ bot not connected');
+    if (!this.#bot) throw new EndpointDeliveryError('endpoint_disconnected', 'QQ bot not connected', 'not_sent');
     return this.#bot;
   }
 }
@@ -532,3 +594,11 @@ function asRecord(value: unknown): Record<string, unknown> {
     ? value as Record<string, unknown>
     : {};
 }
+
+async function recallQqMessage(bot: QqBotTransport, kind: ReturnType<typeof qqOutboundKind>, channelId: string, 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);
+}

package/src/interaction.ts

@@ -0,0 +1,15 @@
+import type { QqInboundMessage } from './protocol.js';
+
+/** qq-official-bot 1.3 normalizes INTERACTION_CREATE to notice.*.action. */
+export function normalizeQqInteraction(raw: unknown): { message: QqInboundMessage; sourceMessageId?: string; ack: () => Promise<unknown> } | null {
+  if (!raw || typeof raw !== 'object') return null;
+  const event = raw as { sub_type?: string; notice_type?: string; notice_id?: string; operator_id?: string; group_id?: string; channel_id?: string; guild_id?: string; data?: { resolved?: { button_data?: unknown; message_id?: unknown; user_id?: string } }; reply?: (code: number) => Promise<unknown> };
+  const resolved = event.data?.resolved;
+  if (event.sub_type !== 'action' || !event.notice_id || typeof resolved?.button_data !== 'string' || typeof event.reply !== 'function') return null;
+  const actor = event.operator_id ?? resolved.user_id;
+  const kind = event.notice_type === 'friend' ? 'private' : event.notice_type === 'group' ? 'group' : event.notice_type === 'guild' ? 'channel' : undefined;
+  const id = kind === 'private' ? actor : kind === 'group' ? event.group_id : event.channel_id;
+  if (!kind || !id || !actor || (kind === 'channel' && !event.guild_id)) return null;
+  const sourceMessageId = typeof resolved.message_id === 'string' && resolved.message_id ? resolved.message_id : undefined;
+  return { message: { id: event.notice_id, content: '', channelKind: kind, channelId: id, authorId: actor, authorName: '', timestamp: Date.now(), ...(event.guild_id ? { guildId: event.guild_id } : {}), segments: [{ type: 'action', data: { payload: resolved.button_data } }] }, ...(sourceMessageId ? { sourceMessageId } : {}), ack: () => event.reply!(0) };
+}

package/src/outbound.ts

@@ -10,10 +10,11 @@
  * - keyboard：data.rows 按钮矩阵展开为 button 段（SDK processButtons 组装
  *   keyboard 载荷）；按钮消息必须带 markdown，故同行文本合并为 markdown 段。
  *   data.id 模板键盘原样透传。
- * 不可映射的段一律降级为文本并 warn（保持既有 fallback 行为）。
+ * canonical share 当前明确 not_sent/unsupported，避免静默丢标题/描述/URL。
+ * 其他未识别段保持既有 data.text fallback；正常发送另受声明的 supported 白名单约束。
  */
 import { formatCompact, getLogger } from '@zhin.js/logger';
-import { isMediaRef } from '@zhin.js/im-contract';
+import { EndpointDeliveryError, isMediaRef } from '@zhin.js/im-contract';
 import type { QqWireSegment } from './protocol.js';
 
 const logger = getLogger('qq');
@@ -30,6 +31,7 @@ interface QqOutboundButtonSpec {
   readonly id?: string;
   readonly label?: string;
   readonly payload?: string;
+  readonly url?: string;
   readonly disabled?: boolean;
   readonly style?: 'primary' | 'danger' | 'secondary';
   readonly mode?: string;
@@ -104,9 +106,9 @@ function normalizeMarkdownSegment(seg: QqWireSegment): QqOutboundElem | null {
 function coreButtonToQq(btn: QqOutboundButtonSpec): Record<string, unknown> {
   const isCommand = btn.mode === 'command';
   const action: Record<string, unknown> = {
-    type: isCommand ? 2 : 0,
+    type: isCommand ? 2 : btn.url ? 0 : 1,
     permission: { type: 2 },
-    data: btn.payload ?? '',
+    data: btn.url ?? btn.payload ?? '',
     click_limit: btn.disabled ? 0 : 10,
     unsupport_tips: btn.disabled ? '该按钮不可用' : '',
   };
@@ -199,6 +201,8 @@ export function formatOutbound(payload: unknown): QqOutboundMessage {
     }
     const data = item.data ?? {};
     switch (item.type) {
+      case 'share':
+        throw new EndpointDeliveryError('unsupported_operation', 'QQ canonical share cards are not implemented', 'not_sent');
       case 'text':
         textBuf += String(data.text ?? data.content ?? '');
         break;
@@ -230,7 +234,7 @@ export function formatOutbound(payload: unknown): QqOutboundMessage {
         break;
       }
       case 'reply': {
-        const id = data.id ?? data.event_id;
+        const id = data.message_id ?? data.id ?? data.event_id;
         if (id == null || id === '') break;
         flushText();
         parts.push({

package/src/protocol.ts

@@ -1,6 +1,6 @@
 /** QQ Official Bot protocol helpers. Canonicalization is owned by Core. */
 
-import type { ConversationKind, ConversationRef } from '@zhin.js/im-contract';
+import { EndpointDeliveryError, type ConversationKind, type ConversationRef } from '@zhin.js/im-contract';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 import { resolveQqIntents } from './qq-intents.js';
 
@@ -20,6 +20,7 @@ export interface QqEndpointConfig {
   readonly botKind?: string;
   readonly accessTokenUrl?: string;
   readonly gatewayUrl?: string;
+  readonly streamProxy?: import('./stream-proxy.js').QqStreamProxy;
   readonly webhookPath?: string;
 }
 
@@ -33,6 +34,7 @@ export interface ResolvedQqWebsocketConfig {
   readonly intents?: readonly string[];
   readonly accessTokenUrl?: string;
   readonly gatewayUrl?: string;
+  readonly streamProxy?: import('./stream-proxy.js').QqStreamProxy;
 }
 
 export interface ResolvedQqHttpConfig {
@@ -96,6 +98,8 @@ export function resolveQqConfig(config: QqEndpointConfig): ResolvedQqConfig {
     };
   }
 
+  if (config.streamProxy && (!Number.isInteger(config.streamProxy.port) || config.streamProxy.port < 1 || config.streamProxy.port > 65535
+    || typeof config.streamProxy.serverName !== 'string' || !config.streamProxy.serverName || /[\s/:@?#]/.test(config.streamProxy.serverName))) throw new TypeError('Invalid QQ streamProxy port/serverName');
   return {
     context: 'qq',
     mode: 'websocket',
@@ -109,6 +113,7 @@ export function resolveQqConfig(config: QqEndpointConfig): ResolvedQqConfig {
     }),
     accessTokenUrl: config.accessTokenUrl,
     gatewayUrl: config.gatewayUrl,
+    ...(config.streamProxy ? { streamProxy: config.streamProxy } : {}),
   };
 }
 
@@ -228,21 +233,25 @@ export function parseCompoundMessageId(messageId: string): {
 /** 从 QQ API SendResult / 审核回包中解析出站消息 ID */
 export function resolveOutboundMessageId(result: unknown): string {
   if (!result || typeof result !== 'object') {
-    throw new Error('QQ 发送消息失败：响应为空');
+    throw new EndpointDeliveryError('delivery_unconfirmed', 'QQ 发送消息失败：响应为空', 'unknown');
   }
   const row = result as Record<string, unknown>;
+  if (typeof row.code === 'number' && Number.isFinite(row.code) && row.code !== 0) {
+    throw new EndpointDeliveryError('platform_rejected', `QQ platform rejected the outbound request (${row.code})`, 'rejected');
+  }
   const nested = row.data && typeof row.data === 'object'
     ? row.data as Record<string, unknown>
     : undefined;
-  const audit = (row.message_audit ?? nested?.message_audit) as Record<string, unknown> | undefined;
-  const id = row.id ?? row.message_id ?? audit?.audit_id;
-  if (id == null || id === '') {
+  const id = row.id ?? row.message_id ?? nested?.id ?? nested?.message_id;
+  if ((typeof id !== 'string' && typeof id !== 'number') || String(id).trim() === '' || (typeof id === 'number' && !Number.isFinite(id))) {
     const code = row.code;
-    const msg = row.message;
-    throw new Error(
+    const rejected = typeof code === 'number' && Number.isFinite(code) && code !== 0;
+    throw new EndpointDeliveryError(
+      rejected ? 'platform_rejected' : 'delivery_unconfirmed',
       code != null
-        ? `QQ 发送消息失败（${String(code)}）${msg ? `: ${String(msg)}` : ''}`
+        ? 'QQ outbound response is unconfirmed'
         : 'QQ 发送消息失败：响应缺少消息 ID',
+      rejected ? 'rejected' : 'unknown',
     );
   }
   return String(id);

package/src/qq-intents.ts

@@ -29,6 +29,7 @@ export const DEFAULT_QQ_BOT_KIND: QqBotKind = 'public';
 /** 公/私域共用：群/C2C、群成员变更、频道基础事件、频道私信。 */
 const QQ_SHARED_INTENTS = Object.freeze([
   'GROUP_AND_C2C_EVENT',
+  'INTERACTION',
   'GROUP_MEMBER',
   'GUILDS',
   'GUILD_MEMBERS',

package/src/start-deadline.ts

@@ -0,0 +1,18 @@
+/** SDK startup must settle; serial endpoint readiness must never wait forever. */
+export async function awaitQqStartup(starting: Promise<void>, signal: AbortSignal): Promise<void> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let aborted!: () => void;
+  const cancelled = new Promise<never>((_resolve, reject) => {
+    aborted = () => reject(new Error('QQ startup stopped'));
+    signal.addEventListener('abort', aborted, { once: true });
+    if (signal.aborted) aborted();
+  });
+  try {
+    await Promise.race([starting, cancelled, new Promise<never>((_resolve, reject) => {
+      timer = setTimeout(() => reject(new Error('QQ startup timed out after 30000ms')), 30_000);
+    })]);
+  } finally {
+    if (timer) clearTimeout(timer);
+    signal.removeEventListener('abort', aborted);
+  }
+}

package/src/stream-proxy.ts

@@ -0,0 +1,20 @@
+import { Agent } from 'node:https';
+import tls from 'node:tls';
+import { getLogger } from '@zhin.js/logger';
+
+export interface QqStreamProxy { readonly port: number; readonly serverName: string }
+
+/** QQ receiver uses this agent only for WSS; discovery/OpenAPI stay unchanged. */
+export function createQqStreamAgent(proxy: QqStreamProxy): Agent {
+  const agent = new Agent({ keepAlive: false });
+  agent.createConnection = options => {
+    const hostname = String(options.hostname ?? options.host ?? '');
+    if (hostname !== proxy.serverName || Number(options.port ?? 443) !== 443) {
+      getLogger('qq').warn(`Stream proxy rejected gateway hostname: ${hostname}`);
+      throw new Error('Qq Stream proxy gateway identity changed; update fixed upstream before retrying');
+    }
+    return tls.connect({ ...options as tls.ConnectionOptions, path: undefined, host: '127.0.0.1', port: proxy.port,
+      servername: hostname, rejectUnauthorized: true });
+  };
+  return agent;
+}

package/src/upload-diagnostics.ts

@@ -0,0 +1,70 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { createHash } from 'node:crypto';
+
+type Row = Record<string, unknown>;
+type Metadata = Record<string, string | number | boolean | undefined>;
+interface Interceptors {
+  use(fulfilled: (value: unknown) => unknown): number;
+  eject(id: number): void;
+}
+interface UploadContext { buffer: Buffer; blockSize?: number; indexBase?: number; finishes: number }
+const row = (value: unknown): Row => value !== null && (typeof value === 'object' || typeof value === 'function') ? value as Row : {};
+const numeric = (value: unknown): number | undefined => { const n = typeof value === 'number' || typeof value === 'string' ? Number(value) : NaN; return Number.isSafeInteger(n) && n >= 0 ? n : undefined; };
+const hash = (buffer: Buffer, algorithm = 'md5') => createHash(algorithm).update(buffer).digest('hex');
+const body = (value: unknown): Row => { if (typeof value !== 'string') return row(value); try { return row(JSON.parse(value)); } catch { return {}; } };
+const stage = (value: unknown): string => typeof value === 'string' ? value.split('?')[0].split('/').at(-1) ?? '' : '';
+
+/** Same complete-set rule as the SDK patch; preserve platform index in ACKs. */
+export function inferQqUploadIndexBase(parts: unknown, fileSize: number, blockSize: number): 0 | 1 | undefined {
+  if (!Number.isSafeInteger(blockSize) || blockSize <= 0 || !fileSize || !Array.isArray(parts)) return undefined;
+  const count = Math.ceil(fileSize / blockSize);
+  if (!parts.length || parts.length !== count) return undefined;
+  let base = Infinity; const indices = new Set<number>();
+  for (const part of parts) { const index = row(part).index; if (typeof index !== 'number' || !Number.isSafeInteger(index)) return undefined; base = Math.min(base, index); indices.add(index); }
+  if ((base !== 0 && base !== 1) || indices.size !== count) return undefined;
+  for (const part of parts) { const item = row(part); const index = item.index as number; if (index < base || index >= base + count || numeric(item.block_size) !== Math.min(blockSize, fileSize - (index - base) * blockSize)) return undefined; }
+  return base;
+}
+
+/** Endpoint-owned observer. Emits only whitelisted numeric/boolean metadata. */
+export function installQqUploadDiagnostics(api: unknown, debug: (metadata: Metadata) => void): () => void {
+  const bot = row(api); const request = row(bot.request); const interceptors = row(request.interceptors);
+  const requests = interceptors.request as Interceptors | undefined; const responses = interceptors.response as Interceptors | undefined;
+  const processor = row(bot.fileProcessor);
+  const original = processor.uploadByChunks;
+  if (!requests?.use || !responses?.use || typeof original !== 'function') return () => {};
+  const storage = new AsyncLocalStorage<UploadContext>(); let active = true;
+  const emit = (metadata: Metadata) => { if (active) { try { debug(metadata); } catch { /* diagnostics never affect delivery */ } } };
+  const wrapped = function(this: unknown, buffer: Buffer, ...args: unknown[]) {
+    return storage.run({ buffer, finishes: 0 }, () => original.call(this, buffer, ...args));
+  };
+  processor.uploadByChunks = wrapped;
+  // Axios request hooks run LIFO, before the SDK authentication/body transformer;
+  // success response hooks run FIFO, after the SDK's identity success hook.
+  const requestId = requests.use(value => {
+    const config = row(value); const data = body(config.data); const context = storage.getStore();
+    if (stage(config.url) === 'upload_prepare') {
+      emit({ op: 'qq_upload_prepare', fileType: numeric(data.file_type), fileSize: numeric(data.file_size), actualSize: context?.buffer.length,
+        ...(context ? { sizeMatch: numeric(data.file_size) === context.buffer.length, hashMatch: data.md5 === hash(context.buffer) && data.sha1 === hash(context.buffer, 'sha1') && data.md5_10m === hash(context.buffer.subarray(0, 10002432)) } : {}) });
+    } else if (stage(config.url) === 'upload_part_finish' && context && context.finishes++ < 8) {
+      const index = numeric(data.part_index); const length = numeric(data.block_size); const blockSize = context.blockSize; const base = context.indexBase;
+      const expected = index !== undefined && blockSize && base !== undefined ? context.buffer.subarray((index - base) * blockSize, (index - base + 1) * blockSize) : undefined;
+      emit({ op: 'qq_upload_part_finish', index, blockSize: length, ...(expected ? { sizeMatch: length === expected.length, hashMatch: data.md5 === hash(expected) } : {}) });
+    }
+    return value;
+  });
+  const responseId = responses.use(value => {
+    const response = row(value); const config = row(response.config);
+    if (stage(config.url) !== 'upload_prepare') return value;
+    const data = row(response.data); const parts = Array.isArray(data.parts) ? data.parts.slice(0, 128).map(row) : undefined;
+    const blockSize = numeric(data.block_size); const context = storage.getStore(); if (context) { context.blockSize = blockSize; context.indexBase = blockSize ? inferQqUploadIndexBase(data.parts, context.buffer.length, blockSize) : undefined; }
+    const indices = parts?.map(part => numeric(part.index)).filter((index): index is number => index !== undefined) ?? [];
+    const sizes = parts?.map(part => numeric(part.block_size)).filter((size): size is number => size !== undefined) ?? [];
+    emit({ op: 'qq_upload_prepared', blockSize, partsPresent: parts !== undefined, partsCount: Array.isArray(data.parts) ? data.parts.length : undefined, inspectedCount: parts?.length,
+      validIndices: indices.length, ...(indices.length ? { minIndex: Math.min(...indices), maxIndex: Math.max(...indices) } : {}),
+      validSizes: sizes.length, ...(sizes.length ? { minPartSize: Math.min(...sizes), maxPartSize: Math.max(...sizes) } : {}),
+      ...(context && blockSize ? { coverageMatch: context.indexBase !== undefined, indexBase: context.indexBase } : {}) });
+    return value;
+  });
+  return () => { active = false; requests.eject(requestId); responses.eject(responseId); if (processor.uploadByChunks === wrapped) processor.uploadByChunks = original; storage.disable(); };
+}