@zhin.js/adapter-qq 1.1.4 → 1.1.6

package/CHANGELOG.md

@@ -1,5 +1,55 @@
 # @zhin.js/adapter-qq
 
+## 1.1.6
+
+### Patch Changes
+
+- 2cdb181: Upgrade kook-client to ^1.0.5 and qq-official-bot to ^1.3.1, which include the upstream lifecycle and upload fixes. Remove local SDK patches and validate the published SDK directly in regression fixtures.
+- Updated dependencies [badcc1f]
+  - @zhin.js/core@1.1.41
+  - @zhin.js/feature-kit@1.1.3
+  - @zhin.js/adapter@1.1.17
+  - @zhin.js/agent-feature@1.1.4
+  - @zhin.js/skill@1.1.4
+  - @zhin.js/tool@1.1.4
+  - @zhin.js/host-http@1.1.4
+  - @zhin.js/permission@1.1.4
+
+## 1.1.5
+
+### Patch Changes
+
+- b9b3953: Fix adapter connection races, transport health reporting, candidate rollback and delivery acknowledgement boundaries. Separate generation admission from locally observed connectivity, reject unconfirmed message receipts, and mark uncertain delivery results without recommending automatic replay.
+
+  Class and compact endpoints should expose a `transportState` getter to report physical connection or local listener health. Unobserved endpoints now report an unknown transport and remain offline in diagnostics. Platform stability tiers remain unchanged until real account acceptance evidence is available.
+
+- b9b3953: Bound QQ startup to 30 seconds with cancellation and late-client cleanup, own asynchronous CLI startup failures, and patch qq-official-bot session startup so authentication/receiver failures reject the returned promise without orphan rejection or lost synchronous readiness.
+
+  Encode native QQ callback buttons with official action type 1, subscribe to interaction events by default, and map SDK action notices into canonical clicks with platform ACK and honest source-message association metadata.
+
+  Reject outbound messages containing segments excluded by an explicit adapter supported policy, and reject unimplemented QQ share cards instead of silently dropping title/description/URL while confirming neighboring text.
+
+- b9b3953: Reject QQ outbound responses carrying a nonzero platform error even when they contain a message ID. Classify DingTalk HTTP client rejection separately from uncertain server/network outcomes and avoid exposing raw platform response text in delivery errors.
+- b9b3953: Add an optional fixed loopback WSS fault proxy that preserves gateway Host/SNI and TLS peer verification. Move reconnect ownership to EndpointLifecycle and keep QQ authentication, discovery, message APIs and uploads direct. Extend the pinned SDK patch with instance-scoped WebSocket agent/factory and reconnect controls, and opt adapters out of SDK process-level error handlers to prevent listener accumulation.
+- Updated dependencies [b9b3953]
+- Updated dependencies [b9b3953]
+- Updated dependencies [b9b3953]
+- Updated dependencies [b9b3953]
+- Updated dependencies [b9b3953]
+- Updated dependencies [b9b3953]
+- Updated dependencies [b9b3953]
+- Updated dependencies [b9b3953]
+- Updated dependencies [b9b3953]
+- Updated dependencies [b9b3953]
+- Updated dependencies [b9b3953]
+  - @zhin.js/adapter@1.1.16
+  - @zhin.js/im-contract@1.1.3
+  - @zhin.js/core@1.1.40
+  - @zhin.js/host-http@1.1.3
+  - @zhin.js/tool@1.1.3
+  - @zhin.js/skill@1.1.3
+  - @zhin.js/agent-feature@1.1.3
+
 ## 1.1.4
 
 ### Patch Changes

package/README.md

@@ -182,3 +182,30 @@ payload 的回跳映射。图片、音频、视频和文件仍沿 canonical `Med
 ## 许可证
 
 MIT License
+
+### 发送回执与未知结果
+
+发送成功回执只接受平台真实消息 ID。网络超时、断线、缺少消息 ID 的响应会报告 `deliveryUnknown`，框架不会自动重发；手动重发可能重复发送。
+
+QQ 返回 `message_audit.audit_id` 仅表示审核任务，不能用作消息 ID，不能据此声明消息已投递。
+
+QQ SDK 启动须在 30 秒内完成，否则端点启动失败并清理该客户端；迟到就绪会再次清理旧客户端。超时不表示凭据错误，应结合网关、认证网络与权限检查。
+
+`qq-official-bot` 1.3.1 已包含 SDK Session.start 的 async Promise executor 修复：认证/接收器启动异常由启动 Promise 正确拒绝，ready 监听先于启动注册，启动结束清理临时监听。已实际验证本机 dummy 403 认证失败经完整 CLI 退出 1，无未处理 rejection；不等价于真实 QQ 账号联网验收。
+
+原生按钮按腾讯协议编码：type=0 URL 跳转、type=1 回调、type=2 指令。默认订阅包含 INTERACTION（1<<26）；用户显式 intents 保留原值，需自行加入 INTERACTION 才能收到回调。SDK notice.*.action 映射为 canonical action，并独立 PUT ACK解除loading；ACK不代表业务处理成功。私聊/群聊平台不提供源消息ID，metadata 明确 sourceMessageIdAvailable=false，以唯一payload、完整端点/会话与操作者关联；频道提供源ID时严格保留。参考：[腾讯官方消息按钮协议](https://github.com/tencent-connect/bot-docs/blob/main/docs/develop/api-v2/server-inter/message/trans/msg-btn.md)。
+
+QQ 当前未实现 canonical `share` 的标题/描述/URL 消息卡片。适配器显式 supported 不含 share，探针及正常统一发送均整体返回 unsupported；不会仅发送旁边的样本文字并记分享成功。直接 endpoint 编码也明确 not_sent，避免绕过能力检查后静默丢失。
+
+分片上传兼容平台返回的完整连续 0-based 或 1-based 序号。字节偏移使用
+`(index - base) * block_size`，分片完成通知保留平台原序号；重复、缺片、异常大小或空
+分片集合会在 PUT 前拒绝。官方文档示例为 0-based，实机曾返回单片 `index: 1`。
+当前官方预上传合同未说明 `parts: []` 是合法秒传响应，因此未将空集合视为已上传；
+若后续取得该合同证据，应补独立回归后支持。debug 诊断仅记录数值和匹配状态，SDK
+原始 debug 继续关闭，避免输出凭据及上传地址。
+
+### WebSocket 受控故障入口
+
+可选 `streamProxy: { port: 18443, serverName: "实际网关 hostname" }` 将 WSS 的 TCP 连接导向 `127.0.0.1:port`。需代理固定转发到相同官方网关的 443 端口；SDK 每次仍动态调用 `getWsUrl()`，hostname/443 不匹配会拒绝连接并只记录 hostname，不能自动绕过代理。原始 URL、HTTP Host、TLS SNI 保留，证书验证始终开启。不要填带 query 的 URL。
+
+仅 WSS 入站、心跳和会话认证经过此代理；AppSecret 换 token、网关发现 HTTP、消息 API 和媒体上传仍直连。故障恢复由 `createEndpointLifecycle` 负责，SDK 内置重连关闭，避免双重重连。此入口用于受控网络验收，不提供全局代理或 TLS 验证绕过。

package/lib/delivery-error.d.ts

@@ -0,0 +1,13 @@
+import { EndpointDeliveryError } from '@zhin.js/im-contract';
+/** Project SDK request failures into stable delivery evidence without exposing request data. */
+export declare function qqDeliveryFailure(error: unknown): {
+    failure: EndpointDeliveryError;
+    diagnostic: {
+        op: string;
+        stage: string;
+        httpStatus: number | undefined;
+        platformCode: number | undefined;
+        code: string;
+        disposition: "not_sent" | "rejected" | "unknown";
+    };
+};

package/lib/delivery-error.js

@@ -0,0 +1,19 @@
+import { EndpointDeliveryError } from '@zhin.js/im-contract';
+/** Project SDK request failures into stable delivery evidence without exposing request data. */
+export function qqDeliveryFailure(error) {
+    const value = error && typeof error === 'object' ? error : {};
+    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 } };
+}

package/lib/endpoint.d.ts

@@ -1,7 +1,7 @@
 /**
  * QQ endpoints — lifecycle, outbound, admit, agent tool surface.
  */
-import { Endpoint, type EndpointControl, type EndpointManagement, type EndpointSendRequest } from 'zhin.js/adapter';
+import { Endpoint, type EndpointControl, type EndpointManagement, type EndpointSendRequest, type EndpointTransportState } from 'zhin.js/adapter';
 import type { HttpHost } from '@zhin.js/host-http';
 import type { CapabilityId } from 'zhin.js';
 import { type QqInboundMessage, type ResolvedQqHttpConfig, type ResolvedQqWebsocketConfig } from './protocol.js';
@@ -22,6 +22,7 @@ export declare class QqWebsocketEndpoint extends Endpoint<QqBotTransport> {
     get client(): QqBotTransport;
     /** Live endpoint 名（Console/AdapterIndex 展示用，如 bot appid 别名）。 */
     get name(): string;
+    get transportState(): EndpointTransportState;
     start(): Promise<void>;
     open(): void;
     close(): void;
@@ -30,6 +31,8 @@ export declare class QqWebsocketEndpoint extends Endpoint<QqBotTransport> {
     recallMessage(messageId: string): Promise<void>;
     /** Test / internal: admit a message when open. */
     admit(msg: QqInboundMessage): void;
+    /** Native click only; C2C/group have no platform source message ID. */
+    admitInteraction(raw: unknown): boolean;
 }
 export interface QqHttpEndpointOptions {
     readonly id: CapabilityId;
@@ -46,6 +49,7 @@ export declare class QqHttpEndpoint extends Endpoint<QqHttpBotTransport> {
     get client(): QqHttpBotTransport;
     /** Live endpoint 名（Console/AdapterIndex 展示用）。 */
     get name(): string;
+    get transportState(): EndpointTransportState;
     start(): Promise<void>;
     open(): void;
     close(): void;
@@ -53,4 +57,6 @@ export declare class QqHttpEndpoint extends Endpoint<QqHttpBotTransport> {
     send({ conversation, payload }: EndpointSendRequest): Promise<string>;
     recallMessage(messageId: string): Promise<void>;
     admit(msg: QqInboundMessage): void;
+    /** Native click only; C2C/group have no platform source message ID. */
+    admitInteraction(raw: unknown): boolean;
 }

package/lib/endpoint.js

@@ -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.
  */
@@ -14,6 +19,7 @@ export class QqWebsocketEndpoint extends Endpoint {
     #createBot;
     #bot = null;
     #open = false;
+    #seenInteractions = new Map();
     #lifecycle;
     #cleanup;
     management = createQqEndpointManagement(() => this.#requireBot());
@@ -21,7 +27,7 @@ export class QqWebsocketEndpoint extends Endpoint {
     constructor(options) {
         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;
     }
@@ -32,11 +38,18 @@ export class QqWebsocketEndpoint extends Endpoint {
     get name() {
         return this.#options.config.id;
     }
+    get transportState() {
+        if (this.#lifecycle.state !== 'open')
+            return this.#lifecycle.state;
+        return this.#bot?.transportState ?? this.#lifecycle.state;
+    }
     async start() {
         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;
             const stopBot = async () => {
                 try {
@@ -50,6 +63,8 @@ export class QqWebsocketEndpoint extends Endpoint {
             };
             const cleanup = () => {
                 cancelled = true;
+                releaseUploadDiagnostics();
+                startupAbort.abort();
                 if (this.#bot === bot)
                     this.#bot = null;
                 return stopping ??= stopBot();
@@ -57,12 +72,20 @@ export class QqWebsocketEndpoint extends Endpoint {
             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}`);
@@ -70,10 +93,8 @@ export class QqWebsocketEndpoint extends Endpoint {
             catch (error) {
                 const wasCancelled = cancelled;
                 await cleanup();
-                if (wasCancelled) {
-                    await stopBot();
+                if (wasCancelled)
                     return;
-                }
                 const raw = error instanceof Error ? error.message : String(error);
                 throw new Error(`QQ WebSocket 连接失败：请检查 appid/secret 是否配对、网关地址（gatewayUrl/accessTokenUrl）是否可达（原始错误：${raw}）`, { cause: error });
             }
@@ -98,21 +119,28 @@ export class QqWebsocketEndpoint extends Endpoint {
         const kind = qqOutboundKind(conversation);
         const bot = this.#requireBot();
         let result;
-        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(`send ${kind}:${conversation.id}`
@@ -123,20 +151,7 @@ export class QqWebsocketEndpoint extends Endpoint {
     async recallMessage(messageId) {
         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,
@@ -180,6 +195,35 @@ export class QqWebsocketEndpoint extends Endpoint {
             }));
         });
     }
+    /** Native click only; C2C/group have no platform source message ID. */
+    admitInteraction(raw) {
+        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) {
         bindQqBotInboundEvents(bot, (raw) => {
             if (this.#bot !== bot)
@@ -193,6 +237,8 @@ export class QqWebsocketEndpoint extends Endpoint {
             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);
         });
     }
@@ -207,7 +253,7 @@ export class QqWebsocketEndpoint extends Endpoint {
     }
     #requireBot() {
         if (!this.#bot)
-            throw new Error('QQ bot not connected');
+            throw new EndpointDeliveryError('endpoint_disconnected', 'QQ bot not connected', 'not_sent');
         return this.#bot;
     }
 }
@@ -218,6 +264,7 @@ export class QqHttpEndpoint extends Endpoint {
     #createBot;
     #bot = null;
     #open = false;
+    #seenInteractions = new Map();
     #lifecycle;
     #cleanup;
     management = createQqEndpointManagement(() => this.#requireBot());
@@ -236,11 +283,16 @@ export class QqHttpEndpoint extends Endpoint {
     get name() {
         return this.#options.config.id;
     }
+    get transportState() {
+        return this.#lifecycle.state;
+    }
     async start() {
         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;
             const routes = [];
             const stopBot = async () => {
@@ -255,6 +307,8 @@ export class QqHttpEndpoint extends Endpoint {
             };
             const cleanup = () => {
                 cancelled = true;
+                releaseUploadDiagnostics();
+                startupAbort.abort();
                 if (this.#bot === bot)
                     this.#bot = null;
                 for (const release of routes.splice(0))
@@ -269,11 +323,17 @@ export class QqHttpEndpoint extends Endpoint {
                     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}`);
@@ -281,10 +341,8 @@ export class QqHttpEndpoint extends Endpoint {
             catch (error) {
                 const wasCancelled = cancelled;
                 await cleanup();
-                if (wasCancelled) {
-                    await stopBot();
+                if (wasCancelled)
                     return;
-                }
                 throw error;
             }
         });
@@ -308,21 +366,28 @@ export class QqHttpEndpoint extends Endpoint {
         const kind = qqOutboundKind(conversation);
         const bot = this.#requireBot();
         let result;
-        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(`send ${kind}:${conversation.id}`
@@ -333,20 +398,7 @@ export class QqHttpEndpoint extends Endpoint {
     async recallMessage(messageId) {
         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,
@@ -389,6 +441,35 @@ export class QqHttpEndpoint extends Endpoint {
             }));
         });
     }
+    /** Native click only; C2C/group have no platform source message ID. */
+    admitInteraction(raw) {
+        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) {
         bindQqBotInboundEvents(bot, (raw) => {
             if (this.#bot !== bot)
@@ -402,6 +483,8 @@ export class QqHttpEndpoint extends Endpoint {
             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);
         });
     }
@@ -416,7 +499,7 @@ export class QqHttpEndpoint extends Endpoint {
     }
     #requireBot() {
         if (!this.#bot)
-            throw new Error('QQ bot not connected');
+            throw new EndpointDeliveryError('endpoint_disconnected', 'QQ bot not connected', 'not_sent');
         return this.#bot;
     }
 }
@@ -454,3 +537,12 @@ function asRecord(value) {
         ? value
         : {};
 }
+async function recallQqMessage(bot, kind, channelId, messageId) {
+    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/lib/interaction.d.ts

@@ -0,0 +1,7 @@
+import type { QqInboundMessage } from './protocol.js';
+/** qq-official-bot 1.3 normalizes INTERACTION_CREATE to notice.*.action. */
+export declare function normalizeQqInteraction(raw: unknown): {
+    message: QqInboundMessage;
+    sourceMessageId?: string;
+    ack: () => Promise<unknown>;
+} | null;

package/lib/interaction.js

@@ -0,0 +1,16 @@
+/** qq-official-bot 1.3 normalizes INTERACTION_CREATE to notice.*.action. */
+export function normalizeQqInteraction(raw) {
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const event = raw;
+    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/lib/outbound.js

@@ -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';
 const logger = getLogger('qq');
 /**
  * 解析 image/audio/video/file 段的投递源（canonical MediaRef 唯一来源）：
@@ -82,9 +83,9 @@ function normalizeMarkdownSegment(seg) {
 function coreButtonToQq(btn) {
     const isCommand = btn.mode === 'command';
     const action = {
-        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 ? '该按钮不可用' : '',
     };
@@ -173,6 +174,8 @@ export function formatOutbound(payload) {
         }
         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;
@@ -207,7 +210,7 @@ export function formatOutbound(payload) {
                 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();

package/lib/protocol.d.ts

@@ -1,5 +1,5 @@
 /** QQ Official Bot protocol helpers. Canonicalization is owned by Core. */
-import type { ConversationRef } from '@zhin.js/im-contract';
+import { type ConversationRef } from '@zhin.js/im-contract';
 /** One endpoint config after AdapterIndex expands `plugins.<instanceKey>.endpoints`. */
 export interface QqEndpointConfig {
     readonly id: string;
@@ -14,6 +14,7 @@ export interface QqEndpointConfig {
     readonly botKind?: string;
     readonly accessTokenUrl?: string;
     readonly gatewayUrl?: string;
+    readonly streamProxy?: import('./stream-proxy.js').QqStreamProxy;
     readonly webhookPath?: string;
 }
 export interface ResolvedQqWebsocketConfig {
@@ -26,6 +27,7 @@ export interface ResolvedQqWebsocketConfig {
     readonly intents?: readonly string[];
     readonly accessTokenUrl?: string;
     readonly gatewayUrl?: string;
+    readonly streamProxy?: import('./stream-proxy.js').QqStreamProxy;
 }
 export interface ResolvedQqHttpConfig {
     readonly context: 'qq';