@tencent-connect/openclaw-qqbot 1.7.0 → 1.7.2

package/src/gateway.ts

@@ -1,14 +1,16 @@
 import WebSocket from "ws";
 import path from "node:path";
 import fs from "node:fs";
-import type { ResolvedQQBotAccount, WSPayload, C2CMessageEvent, GuildMessageEvent, GroupMessageEvent, InteractionEvent, MsgElement } from "./types.js";
+import type { ResolvedQQBotAccount, WSPayload, C2CMessageEvent, GuildMessageEvent, GroupMessageEvent, InteractionEvent, MsgElement, TransportMode } from "./types.js";
 import { MSG_TYPE_QUOTE } from "./types.js";
+import { startWebhookTransport } from "./transport/index.js";
 import { getAccessToken, getGatewayUrl, sendC2CMessage, sendChannelMessage, sendGroupMessage, clearTokenCache, initApiConfig, startBackgroundTokenRefresh, stopBackgroundTokenRefresh, sendC2CInputNotify, onMessageSent, getPluginUserAgent, sendProactiveGroupMessage, acknowledgeInteraction, getApiPluginVersion, setApiLogger } from "./api.js";
 import { loadSession, saveSession, clearSession } from "./session-store.js";
 import { recordKnownUser, flushKnownUsers } from "./known-users.js";
 import { getQQBotRuntime } from "./runtime.js";
 import { isGroupAllowed, resolveGroupName, resolveGroupPrompt, resolveHistoryLimit, resolveGroupPolicy, resolveGroupConfig, resolveIgnoreOtherMentions, resolveMentionPatterns } from "./config.js";
 import { qqbotPlugin, stripMentionText, detectWasMentioned } from "./channel.js";
+import { QQBotApprovalHandler, registerApprovalHandler, unregisterApprovalHandler, getApprovalHandler } from "./approval-handler.js";
 import {
   recordPendingHistoryEntry,
   buildPendingHistoryContext,
@@ -21,7 +23,7 @@ import {
 } from "./group-history.js";
 
 import { setRefIndex, getRefIndex, formatRefEntryForAgent, formatMessageReferenceForAgent, flushRefIndex, type RefAttachmentSummary } from "./ref-index-store.js";
-import { matchSlashCommand, getFrameworkVersion, parseFrameworkDateVersion, type SlashCommandContext, type SlashCommandFileResult } from "./slash-commands.js";
+import { matchSlashCommand, getFrameworkVersion, parseFrameworkDateVersion, type SlashCommandContext, type SlashCommandFileResult, type SlashCommandDelegateResult } from "./slash-commands.js";
 import { createMessageQueue, type QueuedMessage } from "./message-queue.js";
 import { triggerUpdateCheck } from "./update-checker.js";
 import { startImageServer, isImageServerRunning, type ImageServerConfig } from "./image-server.js";
@@ -174,9 +176,27 @@ async function handleInteractionCreate(params: {
     await acknowledgeInteraction(token, event.id, 0, { claw_cfg: ackClawCfg });
     log?.info(`[qqbot:${account.accountId}] Interaction ACK (type=${INTERACTION_TYPE_CONFIG_UPDATE}) sent: ${event.id}, claw_cfg=${JSON.stringify(ackClawCfg)}`);
   } else {
-    // 其他类型：普通 ACK
+    // 普通按钮交互：先 ACK
     await acknowledgeInteraction(token, event.id);
     log?.debug?.(`[qqbot:${account.accountId}] Interaction ACK sent: ${event.id}`);
+
+    // Inline Keyboard 审批按钮（type=1 Callback）
+    // button_data 格式：approve:<approvalId>:<decision>
+    // approvalId 可能是 "exec:uuid" / "plugin:uuid"（带前缀）或纯 "uuid"（无前缀）
+    const buttonData = event.data?.resolved?.button_data ?? "";
+    const m = buttonData.match(/^approve:((?:(?:exec|plugin):)?[0-9a-f-]+):(allow-once|allow-always|deny)$/i);
+    if (m) {
+      const approvalId = m[1]!;
+      const decision = m[2] as "allow-once" | "allow-always" | "deny";
+      const userId = event.group_member_openid || event.user_openid || event.data?.resolved?.user_id || "unknown";
+      log?.info(`[qqbot:${account.accountId}] Approval button clicked: approvalId=${approvalId}, decision=${decision}, user=${userId}, buttonData=${buttonData}`);
+      const handler = getApprovalHandler(account.accountId);
+      if (handler) {
+        void handler.resolveApproval(approvalId, decision);
+      } else {
+        log?.error(`[qqbot:${account.accountId}] Approval button: no handler found for accountId=${account.accountId}`);
+      }
+    }
   }
 }
 
@@ -399,6 +419,21 @@ export async function startGateway(ctx: GatewayContext): Promise<void> {
     throw new Error("QQBot not configured (missing appId or clientSecret)");
   }
 
+  // 安全网：捕获 approval-handler / SDK 内部 WS 握手异步错误（如 403），避免进程崩溃
+  const wsUncaughtHandler = (err: Error) => {
+    if (err.message?.includes("Unexpected server response")) {
+      log?.error(`[qqbot:${account.accountId}] Caught WS handshake error (non-fatal): ${err.message}`);
+      // 不重新抛出，防止进程退出
+    } else {
+      // 非 WS 握手错误，重新抛出交给上层处理
+      throw err;
+    }
+  };
+  process.on("uncaughtException", wsUncaughtHandler);
+  abortSignal.addEventListener("abort", () => {
+    process.removeListener("uncaughtException", wsUncaughtHandler);
+  }, { once: true });
+
   // 启动环境诊断（首次连接时执行）
   const diag = await runDiagnostics();
   if (diag.warnings.length > 0) {
@@ -492,6 +527,13 @@ export async function startGateway(ctx: GatewayContext): Promise<void> {
     log?.info(`[qqbot:${account.accountId}] Image server disabled (no imageServerBaseUrl configured)`);
   }
 
+  // ============ Transport 模式标记 ============
+  const transportMode: TransportMode = account.config.transport ?? "websocket";
+  if (transportMode === "webhook") {
+    log?.info(`[qqbot:${account.accountId}] Using webhook transport mode`);
+  }
+
+  // ============ WebSocket / Webhook 公共初始化 ============
   let reconnectAttempts = 0;
   let isAborted = false;
   let currentWs: WebSocket | null = null;
@@ -517,6 +559,19 @@ export async function startGateway(ctx: GatewayContext): Promise<void> {
     log?.info(`[qqbot:${account.accountId}] Restored session from storage: sessionId=${sessionId}, lastSeq=${lastSeq}`);
   }
 
+  // ============ 审批 Handler ============
+  const approvalHandler = new QQBotApprovalHandler({
+    accountId: account.accountId,
+    appId: account.appId,
+    clientSecret: account.clientSecret,
+    cfg: cfg as any,
+    log,
+  });
+  registerApprovalHandler(account.accountId, approvalHandler);
+  approvalHandler.start().catch((err) => {
+    log?.error(`[qqbot:${account.accountId}] approval-handler: uncaught start error: ${err}`);
+  });
+
   // ============ 消息队列（复用 createMessageQueue，内置群消息合并/淘汰策略） ============
   const msgQueue = createMessageQueue({
     accountId: account.accountId,
@@ -526,7 +581,9 @@ export async function startGateway(ctx: GatewayContext): Promise<void> {
 
   // 斜杠指令拦截：在入队前匹配插件级指令，命中则直接回复，不入队
   // 紧急命令列表：这些命令会立即执行，不进入斜杠匹配流程
-  const URGENT_COMMANDS = ["/stop"];
+  // /stop   — 停止当前 agent run，清空队列
+  // /approve — 审批决策，必须在 agent 等待审批时立即执行，否则死锁
+  const URGENT_COMMANDS = ["/stop", "/approve"];
 
   const trySlashCommandOrEnqueue = async (msg: QueuedMessage): Promise<void> => {
     const content = (msg.content ?? "").trim();
@@ -577,6 +634,16 @@ export async function startGateway(ctx: GatewayContext): Promise<void> {
         return;
       }
 
+      // 委托给 AI 模型：用加工后的 prompt 替换原始消息入队
+      const isDelegateResult = typeof reply === "object" && reply !== null && "delegatePrompt" in reply;
+      if (isDelegateResult) {
+        const delegatePrompt = (reply as SlashCommandDelegateResult).delegatePrompt;
+        log?.info(`[qqbot:${account.accountId}] Slash command delegated to AI: ${content.slice(0, 40)}`);
+        msg.content = delegatePrompt;
+        msgQueue.enqueue(msg);
+        return;
+      }
+
       // 命中插件级指令，直接回复
       log?.info(`[qqbot:${account.accountId}] Slash command matched: ${content}, replying directly`);
       const token = await getAccessToken(account.appId, account.clientSecret);
@@ -635,6 +702,9 @@ export async function startGateway(ctx: GatewayContext): Promise<void> {
     flushKnownUsers();
     // P1-4: 保存引用索引数据
     flushRefIndex();
+    // 停止审批 handler
+    void approvalHandler.stop();
+    unregisterApprovalHandler(account.accountId);
   });
 
   const cleanup = () => {
@@ -694,15 +764,6 @@ export async function startGateway(ctx: GatewayContext): Promise<void> {
         clearTokenCache(account.appId);
         shouldRefreshToken = false;
       }
-      
-      const accessToken = await getAccessToken(account.appId, account.clientSecret);
-      log?.info(`[qqbot:${account.accountId}] ✅ Access token obtained successfully`);
-      const gatewayUrl = await getGatewayUrl(accessToken);
-
-      log?.info(`[qqbot:${account.accountId}] Connecting to ${gatewayUrl}`);
-
-      const ws = new WebSocket(gatewayUrl, { headers: { "User-Agent": getPluginUserAgent() } });
-      currentWs = ws;
 
       const pluginRuntime = getQQBotRuntime();
 
@@ -1457,6 +1518,8 @@ export async function startGateway(ctx: GatewayContext): Promise<void> {
             });
           }
 
+          // 打印 runId 用于调试
+          log?.info?.(`[qqbot:${account.accountId}] Dispatching with runId: ${event.messageId}`);
 
           const dispatchPromise = pluginRuntime.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
             ctx: ctxPayload,
@@ -1728,7 +1791,10 @@ export async function startGateway(ctx: GatewayContext): Promise<void> {
                 }
               },
             },
+          
             replyOptions: {
+              // 使用消息ID作为 runId，用于追踪一次完整的 AI 对话运行
+              runId: event.messageId,
               // 流式模式时禁用 block streaming
               disableBlockStreaming: !useStreaming,
               // 流式模式下注册 onPartialReply 回调，接收流式文本增量
@@ -1824,6 +1890,99 @@ export async function startGateway(ctx: GatewayContext): Promise<void> {
         }); // end runWithRequestContext
       };
 
+      // ============ 统一事件分发（WebSocket/Webhook 共用） ============
+      const dispatchInboundEvent = async (t: string, d: unknown): Promise<void> => {
+        if (t === "C2C_MESSAGE_CREATE") {
+          const ev = d as C2CMessageEvent;
+          recordKnownUser({ openid: ev.author.user_openid, type: "c2c", accountId: account.accountId });
+          const refs = parseRefIndices(ev.message_scene?.ext, ev.message_type, ev.msg_elements);
+          await trySlashCommandOrEnqueue({ type: "c2c", senderId: ev.author.user_openid, content: ev.content, messageId: ev.id, timestamp: ev.timestamp, attachments: ev.attachments, refMsgIdx: refs.refMsgIdx, msgIdx: refs.msgIdx, msgElements: ev.msg_elements, msgType: ev.message_type });
+        } else if (t === "AT_MESSAGE_CREATE") {
+          const ev = d as GuildMessageEvent;
+          recordKnownUser({ openid: ev.author.id, type: "c2c", nickname: ev.author.username, accountId: account.accountId });
+          const refs = parseRefIndices((ev as any).message_scene?.ext, (ev as any).message_type, (ev as any).msg_elements);
+          await trySlashCommandOrEnqueue({ type: "guild", senderId: ev.author.id, senderName: ev.author.username, content: ev.content, messageId: ev.id, timestamp: ev.timestamp, channelId: ev.channel_id, guildId: ev.guild_id, attachments: ev.attachments, refMsgIdx: refs.refMsgIdx, msgIdx: refs.msgIdx, msgType: (ev as any).message_type });
+        } else if (t === "DIRECT_MESSAGE_CREATE") {
+          const ev = d as GuildMessageEvent;
+          recordKnownUser({ openid: ev.author.id, type: "c2c", nickname: ev.author.username, accountId: account.accountId });
+          const refs = parseRefIndices((ev as any).message_scene?.ext, (ev as any).message_type, (ev as any).msg_elements);
+          await trySlashCommandOrEnqueue({ type: "dm", senderId: ev.author.id, senderName: ev.author.username, content: ev.content, messageId: ev.id, timestamp: ev.timestamp, guildId: ev.guild_id, attachments: ev.attachments, refMsgIdx: refs.refMsgIdx, msgIdx: refs.msgIdx, msgType: (ev as any).message_type });
+        } else if (t === "GROUP_AT_MESSAGE_CREATE" || t === "GROUP_MESSAGE_CREATE") {
+          const ev = d as GroupMessageEvent;
+          recordKnownUser({ openid: ev.author.member_openid, type: "group", nickname: ev.author.username, groupOpenid: ev.group_openid, accountId: account.accountId });
+          const refs = parseRefIndices(ev.message_scene?.ext, ev.message_type, ev.msg_elements);
+          await trySlashCommandOrEnqueue({ type: "group", senderId: ev.author.member_openid, senderName: ev.author.username, senderIsBot: ev.author.bot, content: ev.content, messageId: ev.id, timestamp: ev.timestamp, groupOpenid: ev.group_openid, attachments: ev.attachments, refMsgIdx: refs.refMsgIdx, msgIdx: refs.msgIdx, eventType: t, mentions: ev.mentions, messageScene: ev.message_scene, msgElements: ev.msg_elements, msgType: ev.message_type });
+        } else if (t === "GROUP_ADD_ROBOT") {
+          const ev = d as { timestamp: string; group_openid: string; op_member_openid: string };
+          log?.info(`[qqbot:${account.accountId}] Bot added to group: ${ev.group_openid} by ${ev.op_member_openid}`);
+          recordKnownUser({ openid: ev.op_member_openid, type: "group", groupOpenid: ev.group_openid, accountId: account.accountId });
+        } else if (t === "GROUP_DEL_ROBOT") {
+          const ev = d as { timestamp: string; group_openid: string; op_member_openid: string };
+          log?.info(`[qqbot:${account.accountId}] Bot removed from group: ${ev.group_openid} by ${ev.op_member_openid}`);
+        } else if (t === "GROUP_MSG_REJECT") {
+          const ev = d as { timestamp: number; group_openid: string; op_member_openid: string };
+          log?.info(`[qqbot:${account.accountId}] Group ${ev.group_openid} rejected bot proactive messages (by ${ev.op_member_openid})`);
+        } else if (t === "GROUP_MSG_RECEIVE") {
+          const ev = d as { timestamp: number; group_openid: string; op_member_openid: string };
+          log?.info(`[qqbot:${account.accountId}] Group ${ev.group_openid} accepted bot proactive messages (by ${ev.op_member_openid})`);
+        } else if (t === "INTERACTION_CREATE") {
+          const ev = d as InteractionEvent;
+          const resolved = ev.data?.resolved;
+          const sceneDesc = ev.scene ?? (ev.chat_type === 0 ? "guild" : ev.chat_type === 1 ? "group" : "c2c");
+          log?.info(`[qqbot:${account.accountId}] Interaction: scene=${sceneDesc}, type=${ev.data?.type}, button_id=${resolved?.button_id}, button_data=${resolved?.button_data}`);
+          handleInteractionCreate({ event: ev, account, cfg, log }).catch((err) => {
+            log?.error(`[qqbot:${account.accountId}] Failed to handle interaction ${ev.id}: ${err}`);
+          });
+        }
+      };
+
+      // ============ Webhook 模式：共享 handleMessage，不走 WS ============
+      if (transportMode === "webhook") {
+        isConnecting = false;
+        msgQueue.startProcessor(handleMessage);
+        startBackgroundTokenRefresh(account.appId, account.clientSecret, {
+          log: log as { info: (msg: string) => void; error: (msg: string) => void; debug?: (msg: string) => void },
+        });
+
+        await startWebhookTransport({
+          account,
+          abortSignal,
+          onEvent: async (event) => {
+            const { eventType: t, data: d } = event;
+            log?.info(`[qqbot:${account.accountId}:webhook] 📩 Dispatch event: t=${t}, d=${JSON.stringify(d)}`);
+            await dispatchInboundEvent(t, d);
+          },
+          onReady: () => {
+            log?.info(`[qqbot:${account.accountId}:webhook] Transport ready`);
+            log?.info(`[qqbot:${account.accountId}] ✅ Webhook transport started successfully (path: ${account.config.webhook?.path ?? "/qqbot/webhook"})`);
+            onReady?.({ transport: "webhook" });
+            if (_pendingFirstReady.has(account.accountId)) {
+              _pendingFirstReady.delete(account.accountId);
+              sendStartupGreetings(adminCtx, "READY");
+            }
+          },
+          onError: (error) => {
+            log?.error(`[qqbot:${account.accountId}:webhook] Error: ${error.message}`);
+            onError?.(error);
+          },
+          log,
+        });
+
+        stopBackgroundTokenRefresh();
+        unregisterApprovalHandler(account.accountId);
+        return; // webhook transport 结束，不继续 WS 逻辑
+      }
+
+      // ============ WebSocket 模式：获取 token 并建立 WS 连接 ============
+      const accessToken = await getAccessToken(account.appId, account.clientSecret);
+      log?.info(`[qqbot:${account.accountId}] ✅ Access token obtained successfully`);
+      const gatewayUrl = await getGatewayUrl(accessToken);
+
+      log?.info(`[qqbot:${account.accountId}] Connecting to ${gatewayUrl}`);
+
+      const ws = new WebSocket(gatewayUrl, { headers: { "User-Agent": getPluginUserAgent() } });
+      currentWs = ws;
+
       ws.on("open", () => {
         log?.info(`[qqbot:${account.accountId}] WebSocket connected`);
         isConnecting = false; // 连接完成，释放锁
@@ -1946,159 +2105,10 @@ export async function startGateway(ctx: GatewayContext): Promise<void> {
                     appId: account.appId,
                   });
                 }
-              } else if (t === "C2C_MESSAGE_CREATE") {
-                const event = d as C2CMessageEvent;
-                // P1-3: 记录已知用户
-                recordKnownUser({
-                  openid: event.author.user_openid,
-                  type: "c2c",
-                  accountId: account.accountId,
-                });
-                // 解析引用索引
-                const c2cRefs = parseRefIndices(event.message_scene?.ext, event.message_type, event.msg_elements);
-                // 斜杠指令拦截 → 不匹配则入队
-                trySlashCommandOrEnqueue({
-                  type: "c2c",
-                  senderId: event.author.user_openid,
-                  content: event.content,
-                  messageId: event.id,
-                  timestamp: event.timestamp,
-                  attachments: event.attachments,
-                  refMsgIdx: c2cRefs.refMsgIdx,
-                  msgIdx: c2cRefs.msgIdx,
-                  msgElements: event.msg_elements,
-                  msgType: event.message_type,
-                });
-              } else if (t === "AT_MESSAGE_CREATE") {
-                const event = d as GuildMessageEvent;
-                // P1-3: 记录已知用户（频道用户）
-                recordKnownUser({
-                  openid: event.author.id,
-                  type: "c2c", // 频道用户按 c2c 类型存储
-                  nickname: event.author.username,
-                  accountId: account.accountId,
-                });
-                const guildRefs = parseRefIndices((event as any).message_scene?.ext, (event as any).message_type, (event as any).msg_elements);
-                trySlashCommandOrEnqueue({
-                  type: "guild",
-                  senderId: event.author.id,
-                  senderName: event.author.username,
-                  content: event.content,
-                  messageId: event.id,
-                  timestamp: event.timestamp,
-                  channelId: event.channel_id,
-                  guildId: event.guild_id,
-                  attachments: event.attachments,
-                  refMsgIdx: guildRefs.refMsgIdx,
-                  msgIdx: guildRefs.msgIdx,
-                  msgType: (event as any).message_type,
-                });
-              } else if (t === "DIRECT_MESSAGE_CREATE") {
-                const event = d as GuildMessageEvent;
-                // P1-3: 记录已知用户（频道私信用户）
-                recordKnownUser({
-                  openid: event.author.id,
-                  type: "c2c",
-                  nickname: event.author.username,
-                  accountId: account.accountId,
-                });
-                const dmRefs = parseRefIndices((event as any).message_scene?.ext, (event as any).message_type, (event as any).msg_elements);
-                trySlashCommandOrEnqueue({
-                  type: "dm",
-                  senderId: event.author.id,
-                  senderName: event.author.username,
-                  content: event.content,
-                  messageId: event.id,
-                  timestamp: event.timestamp,
-                  guildId: event.guild_id,
-                  attachments: event.attachments,
-                  refMsgIdx: dmRefs.refMsgIdx,
-                  msgIdx: dmRefs.msgIdx,
-                  msgType: (event as any).message_type,
-                });
-              } else if (t === "GROUP_AT_MESSAGE_CREATE") {
-                const event = d as GroupMessageEvent;
-                // 被 @ 的消息，直接入队回复
-                recordKnownUser({
-                  openid: event.author.member_openid,
-                  type: "group",
-                  nickname: event.author.username,
-                  groupOpenid: event.group_openid,
-                  accountId: account.accountId,
-                });
-                const groupRefs = parseRefIndices(event.message_scene?.ext, event.message_type, event.msg_elements);
-                trySlashCommandOrEnqueue({
-                  type: "group",
-                  senderId: event.author.member_openid,
-                  senderName: event.author.username,
-                  content: event.content,
-                  messageId: event.id, 
-                  timestamp: event.timestamp,
-                  groupOpenid: event.group_openid,
-                  attachments: event.attachments,
-                  refMsgIdx: groupRefs.refMsgIdx,
-                  msgIdx: groupRefs.msgIdx,
-                  eventType: "GROUP_AT_MESSAGE_CREATE",
-                  mentions: event.mentions,
-                  messageScene: event.message_scene,
-                  msgElements: event.msg_elements,
-                  msgType: event.message_type,
-                });
-              } else if (t === "GROUP_MESSAGE_CREATE") {
-                const event = d as GroupMessageEvent;
-                recordKnownUser({
-                  openid: event.author.member_openid,
-                  type: "group",
-                  nickname: event.author.username,
-                  groupOpenid: event.group_openid,
-                  accountId: account.accountId,
-                });
-                const groupRefs = parseRefIndices(event.message_scene?.ext, event.message_type, event.msg_elements);
-                trySlashCommandOrEnqueue({
-                  type: "group",
-                  senderId: event.author.member_openid,
-                  senderName: event.author.username,
-                  senderIsBot: event.author.bot,
-                  content: event.content,
-                  messageId: event.id,
-                  timestamp: event.timestamp,
-                  groupOpenid: event.group_openid,
-                  attachments: event.attachments,
-                  refMsgIdx: groupRefs.refMsgIdx,
-                  msgIdx: groupRefs.msgIdx,
-                  eventType: "GROUP_MESSAGE_CREATE",
-                  mentions: event.mentions,
-                  messageScene: event.message_scene,
-                  msgElements: event.msg_elements,
-                  msgType: event.message_type,
-                });
-              } else if (t === "GROUP_ADD_ROBOT") {
-                const event = d as { timestamp: string; group_openid: string; op_member_openid: string };
-                log?.info(`[qqbot:${account.accountId}] Bot added to group: ${event.group_openid} by ${event.op_member_openid}`);
-                recordKnownUser({
-                  openid: event.op_member_openid,
-                  type: "group",
-                  groupOpenid: event.group_openid,
-                  accountId: account.accountId,
-                });
-
-              } else if (t === "GROUP_DEL_ROBOT") {
-                const event = d as { timestamp: string; group_openid: string; op_member_openid: string };
-                log?.info(`[qqbot:${account.accountId}] Bot removed from group: ${event.group_openid} by ${event.op_member_openid}`);
-              } else if (t === "GROUP_MSG_REJECT") {
-                const event = d as { timestamp: number; group_openid: string; op_member_openid: string };
-                log?.info(`[qqbot:${account.accountId}] Group ${event.group_openid} rejected bot proactive messages (by ${event.op_member_openid})`);
-              } else if (t === "GROUP_MSG_RECEIVE") {
-                const event = d as { timestamp: number; group_openid: string; op_member_openid: string };
-                log?.info(`[qqbot:${account.accountId}] Group ${event.group_openid} accepted bot proactive messages (by ${event.op_member_openid})`);
-              } else if (t === "INTERACTION_CREATE") {
-                const event = d as InteractionEvent;
-                const resolved = event.data?.resolved;
-                const sceneDesc = event.scene ?? (event.chat_type === 0 ? "guild" : event.chat_type === 1 ? "group" : "c2c");
-                log?.info(`[qqbot:${account.accountId}] Interaction: scene=${sceneDesc}, type=${event.data?.type}, button_id=${resolved?.button_id}, button_data=${resolved?.button_data}, user=${event.group_member_openid || event.user_openid || resolved?.user_id || "unknown"}`);
-
-                handleInteractionCreate({ event, account, cfg, log }).catch((err) => {
-                  log?.error(`[qqbot:${account.accountId}] Failed to handle interaction ${event.id}: ${err}`);
+              } else {
+                // 所有其他事件统一分发
+                dispatchInboundEvent(t!, d).catch((err) => {
+                  log?.error(`[qqbot:${account.accountId}] Event dispatch error (t=${t}): ${err}`);
                 });
               }
               break;
@@ -2253,8 +2263,10 @@ export async function startGateway(ctx: GatewayContext): Promise<void> {
   // 开始连接
   await connect();
 
-  // 等待 abort 信号
-  return new Promise((resolve) => {
-    abortSignal.addEventListener("abort", () => resolve());
+  // 等待 abort 信号（如果 connect() 返回时 signal 已经 aborted，直接 resolve）
+  if (abortSignal.aborted) return;
+  return new Promise<void>((resolve) => {
+    abortSignal.addEventListener("abort", () => resolve(), { once: true });
   });
 }
+

package/src/onboarding.ts

@@ -23,6 +23,14 @@ interface QQBotChannelConfig {
   imageServerBaseUrl?: string;
   markdownSupport?: boolean;
   allowFrom?: string[];
+  /** HTTP/WebSocket User-Agent 追加后缀 */
+  userAgentSuffix?: string;
+  /** 群消息是否默认需要 @提及才触发回复 */
+  defaultRequireMention?: boolean;
+  /** 消息接收传输方式：websocket（默认）| webhook */
+  transport?: string;
+  /** webhook 传输配置（transport="webhook" 时生效） */
+  webhook?: { path?: string };
   accounts?: Record<string, {
     enabled?: boolean;
     appId?: string;

package/src/openclaw-plugin-sdk.d.ts

@@ -369,19 +369,34 @@ declare module "openclaw/plugin-sdk" {
   /** 群消息策略适配器（resolveRequireMention / resolveToolPolicy / resolveGroupIntroHint） */
   export interface ChannelGroupAdapter {
     /** 是否需要 @机器人才响应 */
-    resolveRequireMention?: (ctx: { cfg: OpenClawConfig; accountId?: string; groupId: string }) => boolean;
+    resolveRequireMention?: (ctx: { cfg: OpenClawConfig; accountId?: string; groupId: string }) => boolean | undefined;
     /** 群聊 AI 工具使用范围 */
-    resolveToolPolicy?: (ctx: { cfg: OpenClawConfig; accountId?: string; groupId: string; senderId?: string }) => "full" | "restricted" | "none";
+    resolveToolPolicy?: (
+      ctx: { cfg: OpenClawConfig; accountId?: string; groupId: string; senderId?: string }
+    ) =>
+      | "full"
+      | "restricted"
+      | "none"
+      | GroupToolPolicyConfig
+      | undefined;
     /** 平台特有的群聊行为提示 */
     resolveGroupIntroHint?: (ctx: { cfg: OpenClawConfig; accountId?: string; groupId: string }) => string | undefined;
     /** 其他适配器方法 */
     [key: string]: unknown;
   }
 
+  /** 工具策略配置（用于把 none/restricted/full 映射为 allow/deny） */
+  export type GroupToolPolicyConfig = {
+    allow: string[];
+    deny?: string[];
+  };
+
   /** @mention 检测与清理适配器（stripMentionText / detectWasMentioned） */
   export interface ChannelMentionAdapter {
     /** 清理 @mention 文本：平台格式→可读格式，去除 @机器人自身 */
     stripMentionText?: (text: string, mentions?: Array<{ member_openid?: string; nickname?: string; is_you?: boolean }>) => string;
+    /** stripMentions：框架回调型（一次性拿到 text + ctx） */
+    stripMentions?: (params: { text: string; ctx: unknown }) => string;
     /** 检测当前消息是否 @了机器人 */
     detectWasMentioned?: (ctx: {
       eventType?: string;
@@ -393,6 +408,14 @@ declare module "openclaw/plugin-sdk" {
     [key: string]: unknown;
   }
 
+  /** 状态摘要构建（仅覆盖当前项目用到的字段） */
+  export interface ChannelPluginStatus {
+    defaultRuntime: Record<string, unknown>;
+    buildChannelSummary?: (ctx: { snapshot: any }) => Record<string, unknown>;
+    buildAccountSnapshot?: (ctx: { account: any; runtime: any }) => Record<string, unknown>;
+    [key: string]: unknown;
+  }
+
   /**
    * 频道插件接口（泛型）
    */
@@ -423,6 +446,8 @@ declare module "openclaw/plugin-sdk" {
     groups?: ChannelGroupAdapter;
     /** @mention 检测与清理适配器 */
     mentions?: ChannelMentionAdapter;
+    /** 状态摘要构建（可选） */
+    status?: ChannelPluginStatus;
     /** 启动函数 */
     start?: (runtime: PluginRuntime) => void | Promise<void>;
     /** 停止函数 */
@@ -579,6 +604,54 @@ declare module "openclaw/plugin-sdk" {
     hasMatchInput?: boolean;
   }): MatchedGroupAccessDecision;
 
+  // ============ 审批运行时类型（minimal） ============
+  // 这些类型只覆盖本项目真实使用到的字段，
+  // 用来消除 strict/noImplicitAny 下的连锁报错。
+
+  export interface ExecApprovalRequest {
+    id: string;
+    expiresAtMs: number;
+    request: {
+      commandPreview?: string;
+      command?: string;
+      cwd?: string;
+      agentId?: string;
+      turnSourceAccountId?: string;
+      sessionKey?: string;
+      turnSourceTo?: string;
+      [key: string]: unknown;
+    };
+  }
+
+  export interface ExecApprovalResolved {
+    id: string;
+    decision: string;
+    [key: string]: unknown;
+  }
+
+  export interface PluginApprovalRequest {
+    id: string;
+    request: {
+      timeoutMs?: number;
+      severity?: "critical" | "info" | string;
+      title: string;
+      description?: string;
+      toolName?: string;
+      pluginId?: string;
+      agentId?: string;
+      turnSourceAccountId?: string;
+      sessionKey?: string;
+      turnSourceTo?: string;
+      [key: string]: unknown;
+    };
+  }
+
+  export interface PluginApprovalResolved {
+    id: string;
+    decision: string;
+    [key: string]: unknown;
+  }
+
   // ============ 其他导出 ============
 
   /** 默认账户 ID 常量 */
@@ -587,3 +660,55 @@ declare module "openclaw/plugin-sdk" {
   /** 规范化账户 ID */
   export function normalizeAccountId(accountId: string | undefined | null): string;
 }
+
+declare module "openclaw/plugin-sdk/approval-runtime" {
+  export interface ExecApprovalReplyMetadata {
+    approvalId: string;
+    approvalSlug: string;
+    allowedDecisions?: string[];
+  }
+  export type ExecApprovalRequest = import("openclaw/plugin-sdk").ExecApprovalRequest;
+  export type ExecApprovalResolved = import("openclaw/plugin-sdk").ExecApprovalResolved;
+  export type PluginApprovalRequest = import("openclaw/plugin-sdk").PluginApprovalRequest;
+  export type PluginApprovalResolved = import("openclaw/plugin-sdk").PluginApprovalResolved;
+  export function getExecApprovalReplyMetadata(payload: { channelData?: unknown }): ExecApprovalReplyMetadata | null;
+}
+
+declare module "openclaw/plugin-sdk/core" {
+  export type OpenClawConfig = import("openclaw/plugin-sdk").OpenClawConfig;
+  export type ChannelPlugin<TAccount = unknown> =
+    import("openclaw/plugin-sdk").ChannelPlugin<TAccount>;
+
+  export const applyAccountNameToChannelSection: typeof import("openclaw/plugin-sdk")
+    .applyAccountNameToChannelSection;
+  export const deleteAccountFromConfigSection: typeof import("openclaw/plugin-sdk")
+    .deleteAccountFromConfigSection;
+  export const setAccountEnabledInConfigSection: typeof import("openclaw/plugin-sdk")
+    .setAccountEnabledInConfigSection;
+
+  // 允许其它 core 导出被逐步补齐（避免引入大量严格类型时频繁改代码）
+  export * from "openclaw/plugin-sdk";
+}
+
+declare module "openclaw/plugin-sdk/gateway-runtime" {
+  export interface EventFrame {
+    event: string;
+    payload: unknown;
+  }
+
+  export interface GatewayClient {
+    start: () => void | Promise<void>;
+    stop: () => void | Promise<void>;
+    request: (method: string, params: unknown) => Promise<unknown>;
+  }
+
+  export function createOperatorApprovalsGatewayClient(options: {
+    config: import("openclaw/plugin-sdk").OpenClawConfig;
+    gatewayUrl?: string;
+    clientDisplayName?: string;
+    onEvent: (evt: EventFrame) => void;
+    onHelloOk?: () => void;
+    onConnectError?: (err: { message: string }) => void;
+    onClose?: (code: number, reason: string) => void;
+  }): Promise<GatewayClient>;
+}