@zhin.js/adapter-qq 1.1.4 → 1.1.5

package/lib/protocol.js

@@ -1,4 +1,5 @@
 /** QQ Official Bot protocol helpers. Canonicalization is owned by Core. */
+import { EndpointDeliveryError } from '@zhin.js/im-contract';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 import { resolveQqIntents } from './qq-intents.js';
 const logger = getLogger('qq');
@@ -20,6 +21,9 @@ export function resolveQqConfig(config) {
             sandbox: config.sandbox === true,
         };
     }
+    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',
@@ -33,6 +37,7 @@ export function resolveQqConfig(config) {
         }),
         accessTokenUrl: config.accessTokenUrl,
         gatewayUrl: config.gatewayUrl,
+        ...(config.streamProxy ? { streamProxy: config.streamProxy } : {}),
     };
 }
 function requiredEndpointField(value, field) {
@@ -142,20 +147,22 @@ export function parseCompoundMessageId(messageId) {
 /** 从 QQ API SendResult / 审核回包中解析出站消息 ID */
 export function resolveOutboundMessageId(result) {
     if (!result || typeof result !== 'object') {
-        throw new Error('QQ 发送消息失败：响应为空');
+        throw new EndpointDeliveryError('delivery_unconfirmed', 'QQ 发送消息失败：响应为空', 'unknown');
     }
     const row = result;
+    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
         : undefined;
-    const audit = (row.message_audit ?? nested?.message_audit);
-    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(code != null
-            ? `QQ 发送消息失败（${String(code)}）${msg ? `: ${String(msg)}` : ''}`
-            : 'QQ 发送消息失败：响应缺少消息 ID');
+        const rejected = typeof code === 'number' && Number.isFinite(code) && code !== 0;
+        throw new EndpointDeliveryError(rejected ? 'platform_rejected' : 'delivery_unconfirmed', code != null
+            ? 'QQ outbound response is unconfirmed'
+            : 'QQ 发送消息失败：响应缺少消息 ID', rejected ? 'rejected' : 'unknown');
     }
     return String(id);
 }

package/lib/qq-intents.js

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

package/lib/start-deadline.d.ts

@@ -0,0 +1,2 @@
+/** SDK startup must settle; serial endpoint readiness must never wait forever. */
+export declare function awaitQqStartup(starting: Promise<void>, signal: AbortSignal): Promise<void>;

package/lib/start-deadline.js

@@ -0,0 +1,21 @@
+/** SDK startup must settle; serial endpoint readiness must never wait forever. */
+export async function awaitQqStartup(starting, signal) {
+    let timer;
+    let aborted;
+    const cancelled = new Promise((_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((_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/lib/stream-proxy.d.ts

@@ -0,0 +1,7 @@
+import { Agent } from 'node:https';
+export interface QqStreamProxy {
+    readonly port: number;
+    readonly serverName: string;
+}
+/** QQ receiver uses this agent only for WSS; discovery/OpenAPI stay unchanged. */
+export declare function createQqStreamAgent(proxy: QqStreamProxy): Agent;

package/lib/stream-proxy.js

@@ -0,0 +1,17 @@
+import { Agent } from 'node:https';
+import tls from 'node:tls';
+import { getLogger } from '@zhin.js/logger';
+/** QQ receiver uses this agent only for WSS; discovery/OpenAPI stay unchanged. */
+export function createQqStreamAgent(proxy) {
+    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, path: undefined, host: '127.0.0.1', port: proxy.port,
+            servername: hostname, rejectUnauthorized: true });
+    };
+    return agent;
+}

package/lib/upload-diagnostics.d.ts

@@ -0,0 +1,6 @@
+type Metadata = Record<string, string | number | boolean | undefined>;
+/** Same complete-set rule as the SDK patch; preserve platform index in ACKs. */
+export declare function inferQqUploadIndexBase(parts: unknown, fileSize: number, blockSize: number): 0 | 1 | undefined;
+/** Endpoint-owned observer. Emits only whitelisted numeric/boolean metadata. */
+export declare function installQqUploadDiagnostics(api: unknown, debug: (metadata: Metadata) => void): () => void;
+export {};

package/lib/upload-diagnostics.js

@@ -0,0 +1,106 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { createHash } from 'node:crypto';
+const row = (value) => value !== null && (typeof value === 'object' || typeof value === 'function') ? value : {};
+const numeric = (value) => { const n = typeof value === 'number' || typeof value === 'string' ? Number(value) : NaN; return Number.isSafeInteger(n) && n >= 0 ? n : undefined; };
+const hash = (buffer, algorithm = 'md5') => createHash(algorithm).update(buffer).digest('hex');
+const body = (value) => { if (typeof value !== 'string')
+    return row(value); try {
+    return row(JSON.parse(value));
+}
+catch {
+    return {};
+} };
+const stage = (value) => 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, fileSize, blockSize) {
+    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();
+    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;
+        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, debug) {
+    const bot = row(api);
+    const request = row(bot.request);
+    const interceptors = row(request.interceptors);
+    const requests = interceptors.request;
+    const responses = interceptors.response;
+    const processor = row(bot.fileProcessor);
+    const original = processor.uploadByChunks;
+    if (!requests?.use || !responses?.use || typeof original !== 'function')
+        return () => { };
+    const storage = new AsyncLocalStorage();
+    let active = true;
+    const emit = (metadata) => { if (active) {
+        try {
+            debug(metadata);
+        }
+        catch { /* diagnostics never affect delivery */ }
+    } };
+    const wrapped = function (buffer, ...args) {
+        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 !== undefined) ?? [];
+        const sizes = parts?.map(part => numeric(part.block_size)).filter((size) => 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(); };
+}

package/lib/ws.d.ts

@@ -1,10 +1,12 @@
 import { Bot, type ApproveJoinRequestOptions } from 'qq-official-bot';
+import type { EndpointTransportState } from 'zhin.js/adapter';
 import type { QqOutboundMessage } from './outbound.js';
 import type { QqInboundMessage, ResolvedQqWebsocketConfig } from './protocol.js';
 /** SDK business surface exposed to plugins without bypassing Endpoint lifecycle ownership. */
 export type QqOfficialApi = Pick<Bot, 'messageService' | 'fileProcessor' | 'guildService' | 'channelService' | 'memberService' | 'permissionService' | 'reactionService' | 'scheduleService' | 'threadService' | 'audioService' | 'botService' | 'groupService' | 'menuPanelService' | 'group' | 'user' | 'channel' | 'direct' | 'guild'>;
 /** Minimal bot surface used by the endpoint (real qq-official-bot or test mock). */
 export interface QqBotTransport {
+    readonly transportState?: EndpointTransportState;
     /** Full qq-official-bot business API; lifecycle remains owned by the Endpoint. */
     readonly api: QqOfficialApi;
     start(): Promise<void>;

package/lib/ws.js

@@ -2,6 +2,7 @@
  * QQ WebSocket transport: bot factory and inbound message normalization.
  */
 import path from 'node:path';
+import { createQqStreamAgent } from './stream-proxy.js';
 import { Bot, ReceiverMode, } from 'qq-official-bot';
 /**
  * qq-official-bot 1.2 used a separate connection manager; 1.3 moved WebSocket
@@ -184,6 +185,7 @@ function extractTextContent(message) {
 }
 export function defaultCreateBot(config) {
     const bot = new Bot({
+        ...{ handleProcessErrors: false },
         appid: config.appid,
         secret: config.secret,
         mode: ReceiverMode.WEBSOCKET,
@@ -195,14 +197,47 @@ export function defaultCreateBot(config) {
         ...(config.accessTokenUrl ? { accessTokenUrl: config.accessTokenUrl } : {}),
         ...(config.gatewayUrl ? { gatewayUrl: config.gatewayUrl } : {}),
     });
+    const receiver = bot.receiver;
+    receiver.config.autoReconnect = false;
+    const agent = config.streamProxy ? createQqStreamAgent(config.streamProxy) : undefined;
+    receiver.config.agent = agent;
+    const receiverListeners = [];
+    // Keep receiver error ownership after Session.start removes its temporary listener.
+    const receiverError = () => { };
+    receiver.on('error', receiverError);
     return {
+        get transportState() {
+            const receiver = bot.receiver;
+            const state = receiver.handler?.ws?.readyState;
+            if (state === 1 && receiver.isReady && receiver.isClosed === false)
+                return 'open';
+            if (state === 0)
+                return 'connecting';
+            if (receiver.isStarted)
+                return 'reconnecting';
+            return 'closed';
+        },
         api: bot,
         start: () => bot.start().then(() => undefined),
-        stop: () => stopQqOfficialBot(bot),
+        stop: async () => {
+            try {
+                await stopQqOfficialBot(bot);
+            }
+            finally {
+                agent?.destroy();
+            }
+        },
         on: (event, listener) => {
-            bot.on(event, listener);
+            if (event === 'transport.close') {
+                receiver.on('close', listener);
+                receiverListeners.push({ event: 'close', listener });
+            }
+            else
+                bot.on(event, listener);
         },
         removeAllListeners: () => {
+            for (const entry of receiverListeners.splice(0))
+                receiver.removeListener(entry.event, entry.listener);
             bot.removeAllListeners(undefined);
         },
         sendPrivateMessage: (userId, message) => bot.sendPrivateMessage(userId, message),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-qq",
-  "version": "1.1.4",
+  "version": "1.1.5",
   "description": "Zhin.js QQ Official adapter for Plugin Runtime (WebSocket gateway)",
   "type": "module",
   "main": "./lib/index.js",
@@ -35,24 +35,24 @@
   },
   "dependencies": {
     "qq-official-bot": "^1.3.0",
-    "@zhin.js/adapter": "1.1.15",
-    "@zhin.js/agent-feature": "1.1.2",
-    "@zhin.js/core": "1.1.39",
+    "@zhin.js/adapter": "1.1.16",
+    "@zhin.js/agent-feature": "1.1.3",
+    "@zhin.js/core": "1.1.40",
     "@zhin.js/feature-kit": "1.1.2",
-    "@zhin.js/host-http": "1.1.2",
-    "@zhin.js/im-contract": "1.1.2",
+    "@zhin.js/host-http": "1.1.3",
+    "@zhin.js/im-contract": "1.1.3",
     "@zhin.js/logger": "1.1.1",
     "@zhin.js/permission": "1.1.3",
-    "@zhin.js/skill": "1.1.2",
-    "@zhin.js/tool": "1.1.2"
+    "@zhin.js/skill": "1.1.3",
+    "@zhin.js/tool": "1.1.3"
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "^1.1.15",
-    "@zhin.js/command": "^1.1.3",
-    "@zhin.js/core": "^1.1.39",
-    "@zhin.js/middleware": "^1.1.2",
-    "zhin.js": "^1.1.4"
+    "@zhin.js/adapter": "^1.1.16",
+    "@zhin.js/command": "^1.1.4",
+    "@zhin.js/core": "^1.1.40",
+    "@zhin.js/middleware": "^1.1.3",
+    "zhin.js": "^1.1.5"
   },
   "peerDependenciesMeta": {
     "@zhin.js/command": {
@@ -73,8 +73,8 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "@zhin.js/host-http": "1.1.2",
-    "zhin.js": "1.1.4"
+    "@zhin.js/host-http": "1.1.3",
+    "zhin.js": "1.1.5"
   },
   "files": [
     "adapters",

package/schema.json

@@ -137,6 +137,26 @@
           "id": {
             "type": "string",
             "description": "QQ bot name"
+          },
+          "streamProxy": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "port",
+              "serverName"
+            ],
+            "properties": {
+              "port": {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 65535
+              },
+              "serverName": {
+                "type": "string",
+                "minLength": 1
+              }
+            },
+            "description": "Optional fixed loopback TCP fault proxy for WSS only; original gateway TLS identity must match serverName."
           }
         },
         "required": [
@@ -150,6 +170,26 @@
       "type": "string",
       "default": "",
       "description": "命令前缀（默认 '' 无前缀，任意文本按命令匹配；如 '/' 要求 / 开头）。endpoints[i] 可逐项覆盖"
+    },
+    "streamProxy": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "port",
+        "serverName"
+      ],
+      "properties": {
+        "port": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 65535
+        },
+        "serverName": {
+          "type": "string",
+          "minLength": 1
+        }
+      },
+      "description": "Optional fixed loopback TCP fault proxy for WSS only; original gateway TLS identity must match serverName."
     }
   },
   "required": [

package/src/delivery-error.ts

@@ -0,0 +1,20 @@
+import { EndpointDeliveryError } from '@zhin.js/im-contract';
+
+/** Project SDK request failures into stable delivery evidence without exposing request data. */
+export function qqDeliveryFailure(error: unknown) {
+  const value = error && typeof error === 'object' ? error as { response?: { status?: unknown; data?: { code?: unknown } }; config?: { url?: unknown }; code?: unknown } : {};
+  const httpStatus = typeof value.response?.status === 'number' ? value.response.status : undefined;
+  let platformCode = typeof value.response?.data?.code === 'number' && Number.isFinite(value.response.data.code) ? value.response.data.code : undefined;
+  let path = typeof value.config?.url === 'string' ? value.config.url.split('?')[0] : '';
+  // Published SDK 1.3 flattens Axios rejection into this exact message format.
+  // Extract only operation suffix and numeric protocol code; never surface the message.
+  const flattened = error instanceof Error ? /^Request "([^"]+)" failed with code\((\d+)\):/.exec(error.message) : null;
+  if (flattened) {
+    path ||= flattened[1].split('?')[0];
+    platformCode ??= Number(flattened[2]);
+  }
+  const stage = /\/upload_prepare$/.test(path) ? 'upload_prepare' : /\/upload_part_finish$/.test(path) ? 'upload_part_finish' : /\/files$/.test(path) ? 'upload_complete' : /\/messages$/.test(path) ? 'send_message' : 'sdk_send';
+  const knownRejection = (httpStatus !== undefined && httpStatus >= 400 && httpStatus < 500) || (!!flattened && platformCode !== undefined && ((platformCode >= 400 && platformCode < 500) || platformCode >= 1000));
+  const failure = error instanceof EndpointDeliveryError ? error : new EndpointDeliveryError(knownRejection ? 'platform_rejected' : 'delivery_unconfirmed', knownRejection ? 'QQ platform rejected the outbound request' : 'QQ outbound request outcome is unknown', knownRejection ? 'rejected' : 'unknown', { cause: error });
+  return { failure, diagnostic: { op: 'qq_delivery_failed', stage, httpStatus, platformCode, code: failure.code, disposition: failure.disposition } };
+}