@tencent-connect/openclaw-qqbot 1.7.1 → 2.0.0

package/src/dispatch/dispatch.ts

@@ -0,0 +1,352 @@
+/**
+ * 消息转发 — 入站消息 → OpenClaw AI
+ *
+ * 核心职责：
+ * 1. 从 SDK MiddlewareContext 构建 OpenClaw 标准信封
+ * 2. 通过 runtime-adapter 将消息交给 AI 处理
+ *
+ * 架构说明：
+ * - 所有 runtime.channel.* 访问均通过 runtime-adapter 隔离
+ * - log: 前缀由 PluginLogger + 框架自动注入，消息体不重复 accountId
+ */
+import type { MiddlewareContext, QQBotInboundMessage } from '@tencent-connect/qqbot-nodejs';
+import type { PluginRuntime } from 'openclaw/plugin-sdk';
+import type { ResolvedQQBotAccount } from '../types.js';
+import type { PluginLogger } from '../utils/plugin-logger.js';
+import { buildEnvelope } from './envelope-builder.js';
+import { assembleBody, type AssembledBody } from './body-assembler.js';
+import { sendText, getGateway } from '../outbound/outbound-service.js';
+import { sendMedia } from '../outbound/media-send.js';
+import { deliverReply, type DeliverPayload, type DeliverInfo, type DeliverContext } from '../outbound/deliver-pipeline.js';
+import { buildCtxPayload } from './ctx-builder.js';
+
+import { DeliverDebouncer } from '../outbound/debounce.js';
+import { StreamingController, shouldUseStreaming } from '../outbound/streaming-controller.js';
+import { getAdapters } from '../adapter/resolve.js';
+import { clearGroupHistory } from '../features/history-store.js';
+
+
+/**
+ * 将经过中间件处理的入站消息转发给 OpenClaw AI
+ */
+export async function dispatchToOpenClaw(
+  ctx: MiddlewareContext,
+  msg: QQBotInboundMessage,
+  account: ResolvedQQBotAccount,
+  runtime: PluginRuntime,
+  log?: PluginLogger,
+): Promise<void> {
+  const dlog = log?.child('dispatch');
+  const adapters = getAdapters(runtime, dlog);
+  const envelope = buildEnvelope(ctx, msg, account);
+
+  dlog?.debug(`received sender=${envelope.senderId} scope=${envelope.chatScope} msgId=${envelope.messageId}`);
+
+  if (!adapters.dispatchReply) {
+    dlog?.error(`runtime adapter dispatchReply not available (openclaw=${adapters.version})`);
+    return;
+  }
+
+  const assembled: AssembledBody =
+    ((ctx.state as Record<string, unknown>).assembledBody as AssembledBody | undefined) ??
+    assembleBody(ctx, msg, account);
+
+  const cfg = adapters.getConfig?.() ?? {};
+
+  const route = adapters.resolveAgentRoute?.({
+    cfg,
+    channel: 'qqbot',
+    accountId: account.accountId,
+    peer: {
+      kind: envelope.chatScope === 'group' ? 'group' : 'direct',
+      id: envelope.chatScope === 'group' ? (envelope.groupId ?? envelope.senderId) : envelope.senderId,
+    },
+  }) ?? { sessionKey: `qqbot:${account.accountId}:${envelope.senderId}`, accountId: account.accountId };
+
+  const qualifiedTarget = envelope.targetId;
+  const agentId = route.agentId ?? 'default';
+  const storePath = adapters.resolveStorePath?.((cfg as any)?.session?.store, { agentId }) ?? '';
+
+  const ctxPayload = buildCtxPayload({ assembled, envelope, route, msg, ctx, adapters });
+
+  const ttsRuntime = (runtime as any)?.tts ?? (runtime as any)?.channel?.runtimeContexts?.get?.('tts');
+
+  const debounceConfig = account.config?.deliverDebounce;
+  const debouncer = debounceConfig?.enabled !== false
+    ? new DeliverDebouncer(debounceConfig, (targetId, mergedText) =>
+        sendText({ to: targetId, text: mergedText, accountId: account.accountId, replyToId: envelope.messageId, account }).then(() => {}),
+      )
+    : undefined;
+
+  const deliverCtx: DeliverContext = {
+    qualifiedTarget,
+    accountId: account.accountId,
+    replyToId: envelope.messageId,
+    chatScope: envelope.chatScope === 'group' ? 'group' : 'direct',
+    cfg,
+    debouncer: debouncer?.enabled ? debouncer : undefined,
+    sendText: (to, text) => sendText({ to, text, accountId: account.accountId, replyToId: envelope.messageId, account }),
+    sendMedia: (to, source, opts) => sendMedia({
+      to,
+      source,
+      text: opts?.text ?? '',
+      replyToId: envelope.messageId,
+      accountId: account.accountId,
+      agentId: route.agentId,
+      log: deliverCtx.log,
+    }),
+    textToSpeech: ttsRuntime?.textToSpeech
+      ? (params) => ttsRuntime.textToSpeech(params)
+      : undefined,
+    audioFileToSilkBase64: ttsRuntime?.audioFileToSilkBase64
+      ? (audioPath: string) => ttsRuntime.audioFileToSilkBase64(audioPath)
+      : undefined,
+    log: log?.child('deliver'),
+    agentId: route.agentId ?? 'default',
+  };
+
+  const streamingEnabled = shouldUseStreaming(
+    account,
+    envelope.chatScope === 'group' ? 'group' : 'c2c',
+  );
+
+  const streamingController = streamingEnabled
+    ? createStreamingController(envelope, account, log?.child('streaming'))
+    : null;
+
+  if (streamingController) {
+    dlog?.debug(`streaming enabled for ${envelope.senderId}`);
+  }
+
+  const deliveredMediaUrls = new Set<string>();
+  const deliveredTexts = new Set<string>();
+
+  if (!adapters.inboundRun) {
+    // 低版本：手动 session + dispatchReply 直调
+    if (adapters.recordInboundSession) {
+      try {
+        await adapters.recordInboundSession({
+          storePath,
+          sessionKey: route.sessionKey,
+          ctx: ctxPayload,
+        });
+      } catch { /* best-effort */ }
+    }
+    await adapters.dispatchReply!({
+      ctx: ctxPayload,
+      cfg,
+      dispatcherOptions: {
+        deliver: async (payload: DeliverPayload, info?: DeliverInfo) => {
+          const text = payload.text?.trim() ?? '';
+          // 低版本无 block/final 协议，流式启动后 final 仍需跳过（降级除外）
+          if (!payload.mediaUrl && !payload.mediaUrls?.length
+            && text
+            && (deliveredTexts.has(text)
+              || (streamingController?.hasStarted && !streamingController?.shouldFallbackToStatic))
+          ) {
+            return;
+          }
+          const filteredPayload = deliveredMediaUrls.size > 0
+            ? {
+                ...payload,
+                mediaUrl: payload.mediaUrl && !deliveredMediaUrls.has(payload.mediaUrl)
+                  ? payload.mediaUrl : undefined,
+                mediaUrls: payload.mediaUrls?.filter((u) => !deliveredMediaUrls.has(u)),
+              }
+            : payload;
+          await deliverReply(filteredPayload, info, deliverCtx);
+          if (text) deliveredTexts.add(text);
+          // 记录已投递媒体（流式路径可能已先发送）
+          for (const u of filteredPayload.mediaUrls ?? []) deliveredMediaUrls.add(u);
+          if (filteredPayload.mediaUrl) deliveredMediaUrls.add(filteredPayload.mediaUrl);
+        },
+      },
+      replyOptions: {
+        abortSignal: ctx.signal,
+        runId: envelope.messageId,
+        ...(streamingController
+          ? {
+              onPartialReply: async (p: { text?: string }) => {
+                if (p.text) await streamingController.onPartialReply(p.text);
+              },
+            }
+          : {}),
+      },
+    });
+    if (streamingController && !streamingController.isTerminal) {
+      await streamingController.finalize();
+    }
+    if (debouncer) await debouncer.flushAll();
+  } else {
+    await adapters.inboundRun!({
+      channel: 'qqbot',
+      accountId: route.accountId,
+      raw: envelope,
+      adapter: {
+        ingest: (raw: any) => ({
+          id: envelope.messageId,
+          rawText: assembled.rawBody,
+          textForAgent: assembled.agentBody,
+          textForCommands: assembled.rawBody,
+          raw,
+        }),
+        resolveTurn: (_input: unknown, _eventClass: unknown, _preflight: unknown) => ({
+          channel: 'qqbot',
+          accountId: route.accountId,
+          routeSessionKey: route.sessionKey,
+          storePath,
+          ctxPayload,
+          recordInboundSession: adapters.recordInboundSession,
+          record: {
+            onRecordError: (err: unknown) => {
+              dlog?.error(`Session record error: ${err}`);
+            },
+          },
+          runDispatch: () => {
+            return adapters.dispatchReply!({
+              ctx: ctxPayload,
+              cfg,
+              dispatcherOptions: {
+                deliver: async (payload: DeliverPayload, info?: DeliverInfo) => {
+                  try {
+                    const kind = (info as any)?.kind as string | undefined;
+                    const text = payload.text?.trim() ?? '';
+                    const hasMedia = !!(payload.mediaUrl || payload.mediaUrls?.length);
+                    dlog?.debug(`deliver kind=${kind ?? 'none'} textLen=${text.length} voice=${!!payload.audioAsVoice} media=${hasMedia}`);
+
+                    // ── 1. block: 媒体/语音立即发送，文本留给流式 ──
+                    if (kind === 'block') {
+                      if (payload.audioAsVoice) {
+                        await deliverReply(payload, info, deliverCtx);
+                      } else {
+                        await forwardMediaUrls(payload, deliverCtx, deliveredMediaUrls, dlog);
+                      }
+                    }
+
+                    // ── 2. 流式路径：流式已启动且未降级 → 跳过静态发送 ──
+                    if (streamingController?.hasStarted && !streamingController.shouldFallbackToStatic) {
+                      if (kind !== 'block') await streamingController.finalize();
+                      if (!streamingController.shouldFallbackToStatic) return;
+                      dlog?.warn(`streaming fallback to static`);
+                    }
+
+                    // ── 3. 文本去重：同文本已发过 → 跳过 ──
+                    if (kind === 'final' && !hasMedia && text && deliveredTexts.has(text)) {
+                      return;
+                    }
+
+                    // ── 4. tool 媒体：立即转发 ──
+                    if (kind === 'tool') {
+                      await forwardMediaUrls(payload, deliverCtx, deliveredMediaUrls, dlog);
+                      return;
+                    }
+
+                    // ── 5. 默认路径：过滤已发媒体 + 发送 ──
+                    const filteredPayload = filterDeliveredMedia(payload, deliveredMediaUrls);
+                    await deliverReply(filteredPayload, info, deliverCtx);
+                    if (text) deliveredTexts.add(text);
+                  } catch (err) {
+                    dlog?.error(`deliver error: ${err instanceof Error ? err.message : String(err)}`);
+                  }
+                },
+            },
+            replyOptions: {
+              abortSignal: ctx.signal,
+              runId: envelope.messageId,
+              ...(streamingController
+                ? {
+                    onPartialReply: async (p: { text?: string }) => {
+                      if (p.text) await streamingController.onPartialReply(p.text);
+                    },
+                  }
+                : {}),
+            },
+          });
+        },
+      }),
+    },
+  });
+  }
+ 
+  dlog?.debug(`inboundRun completed sessionKey=${route.sessionKey}`);
+
+  // 群消息回复后清空历史缓存（避免下次 @ 时重复组包）
+  if (envelope.chatScope === 'group') {
+    clearGroupHistory(account.accountId, envelope.groupId ?? envelope.senderId);
+  }
+
+  if (streamingController && !streamingController.isTerminal) {
+    await streamingController.finalize();
+  }
+
+  if (debouncer) {
+    await debouncer.flushAll();
+  }
+}
+
+function createStreamingController(
+  envelope: ReturnType<typeof buildEnvelope>,
+  account: ResolvedQQBotAccount,
+  log?: PluginLogger,
+): StreamingController | null {
+  const gw = getGateway(account.accountId);
+  if (!gw) {
+    log?.error(`cannot enable streaming — gateway not running`);
+    return null;
+  }
+  return new StreamingController({
+    gateway: gw,
+    target: {
+      scope: 'c2c',
+      targetId: envelope.senderId,
+      msgId: envelope.messageId,
+    },
+    accountId: account.accountId,
+    replyToId: envelope.messageId,
+    log,
+  });
+}
+
+// ── 辅助函数 ──
+
+/** 提取 payload 中的媒体 URL 并逐个发送（去重） */
+async function forwardMediaUrls(
+  payload: DeliverPayload,
+  ctx: DeliverContext,
+  delivered: Set<string>,
+  log?: PluginLogger,
+): Promise<void> {
+  const urls: string[] = [];
+  if (payload.mediaUrls?.length) urls.push(...payload.mediaUrls);
+  if (payload.mediaUrl && !urls.includes(payload.mediaUrl)) urls.push(payload.mediaUrl);
+  const newUrls = urls.filter((u) => !delivered.has(u));
+  for (const url of newUrls) {
+    try {
+      await sendMedia({
+        to: ctx.qualifiedTarget,
+        source: url,
+        text: '',
+        replyToId: ctx.replyToId,
+        accountId: ctx.accountId,
+        log: ctx.log,
+        agentId: ctx.agentId,
+      });
+      delivered.add(url);
+    } catch (err) {
+      log?.error(`media forward failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+}
+
+/** 过滤已发送的媒体 URL */
+function filterDeliveredMedia(
+  payload: DeliverPayload,
+  delivered: Set<string>,
+): DeliverPayload {
+  if (delivered.size === 0) return payload;
+  return {
+    ...payload,
+    mediaUrl: payload.mediaUrl && !delivered.has(payload.mediaUrl) ? payload.mediaUrl : undefined,
+    mediaUrls: payload.mediaUrls?.filter((u) => !delivered.has(u)),
+  };
+}

package/src/dispatch/envelope-builder.ts

@@ -0,0 +1,112 @@
+/**
+ * 信封构建器
+ *
+ * 将 SDK MiddlewareContext 中由各中间件填充的 state 数据
+ * 转换为 OpenClaw 框架标准的 InboundMessage 结构。
+ */
+import type { MiddlewareContext, QQBotInboundMessage, HistoryEntry, ResolvedQuote } from '@tencent-connect/qqbot-nodejs';
+import type { ResolvedQQBotAccount } from '../types.js';
+
+/**
+ * OpenClaw 入站消息结构（传递给 runtime.channel.dispatch）
+ */
+export interface OpenClawInboundMessage {
+  channelId: string;
+  accountId: string;
+  targetId: string;
+  chatScope: 'direct' | 'group';
+  senderId: string;
+  senderName?: string;
+  messageId: string;
+  content: string;
+  history?: Array<{ role: string; content: string; senderId?: string; senderName?: string }>;
+  quote?: { content: string; senderId: string; attachments?: unknown[] };
+  attachments?: unknown[];
+  /** 入站图片 URL 列表（从附件中提取） */
+  imageUrls?: string[];
+  groupId?: string;
+  systemPrompt?: string;
+}
+
+/**
+ * 将 HistoryEntry 转换为 OpenClaw 历史格式
+ */
+function mapHistory(
+  entries: HistoryEntry[] | undefined,
+): OpenClawInboundMessage['history'] {
+  if (!entries || entries.length === 0) return undefined;
+  return entries.map((e) => ({
+    role: 'user',
+    content: e.content,
+    senderId: e.senderId,
+    senderName: e.senderName,
+  }));
+}
+
+/**
+ * 将 ResolvedQuote 转换为 OpenClaw quote 格式
+ */
+function mapQuote(
+  quote: ResolvedQuote | undefined,
+): OpenClawInboundMessage['quote'] {
+  if (!quote) return undefined;
+  return {
+    content: quote.text,
+    senderId: quote.entry?.senderId ?? '',
+    attachments: quote.attachments as unknown[],
+  };
+}
+
+/**
+ * 从 SDK 中间件上下文构建 OpenClaw InboundMessage
+ */
+export function buildEnvelope(
+  ctx: MiddlewareContext,
+  msg: QQBotInboundMessage,
+  account: ResolvedQQBotAccount,
+): OpenClawInboundMessage {
+  const scope = msg.replyTarget.scope;
+  const targetId = scope === 'group'
+    ? `qqbot:group:${msg.replyTarget.targetId}`
+    : `qqbot:c2c:${msg.replyTarget.targetId}`;
+
+  // envelope 是 string 类型，直接作为 content 使用；回退到原始消息内容
+  const envelope = ctx.state.envelope as string | undefined;
+  let content = envelope ?? msg.content;
+
+  // 将语音转录文本和附件信息注入到 content 中
+  const processed = ctx.state.processedAttachments as
+    | { voiceText?: string; imageUrls?: string[]; otherInfo?: string }
+    | undefined;
+
+  if (processed) {
+    const parts: string[] = [];
+    if (processed.voiceText) {
+      parts.push(processed.voiceText);
+    }
+    if (content) {
+      parts.push(content);
+    }
+    if (processed.otherInfo) {
+      parts.push(processed.otherInfo);
+    }
+    content = parts.join('\n');
+  }
+
+  return {
+    channelId: 'qqbot',
+    accountId: account.accountId,
+    targetId,
+    chatScope: scope === 'group' ? 'group' : 'direct',
+    senderId: msg.senderId,
+    senderName: msg.senderName,
+    messageId: msg.messageId,
+    content,
+    history: mapHistory(ctx.state.history as HistoryEntry[] | undefined),
+    quote: mapQuote(ctx.state.quote as ResolvedQuote | undefined),
+    attachments: msg.attachments,
+    imageUrls: processed?.imageUrls,
+    groupId: scope === 'group' ? msg.replyTarget.targetId : undefined,
+    systemPrompt: account.systemPrompt,
+  };
+}

package/src/dispatch/index.ts

@@ -0,0 +1,2 @@
+export { dispatchToOpenClaw } from './dispatch.js';
+export { buildEnvelope } from './envelope-builder.js';

package/src/{approval-handler.ts → features/approval-handler.ts}

@@ -10,75 +10,11 @@
  */
 
 import type { OpenClawConfig } from "openclaw/plugin-sdk";
-import { createRequire } from "node:module";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-import {
-  getAccessToken,
-  sendC2CMessageWithInlineKeyboard,
-  sendGroupMessageWithInlineKeyboard,
-} from "./api.js";
-import type { InlineKeyboard, KeyboardButton } from "./types.js";
-
-// ─── 动态加载 gateway-runtime（兼容不同安装环境） ────────
-
-function loadGatewayRuntime(): { createOperatorApprovalsGatewayClient: (...args: any[]) => Promise<GatewayClient> } {
-  const req = createRequire(import.meta.url);
-  const currentFile = fileURLToPath(import.meta.url);
-  const pluginRoot = path.resolve(path.dirname(currentFile), "..", "..");
-  const fs = req("node:fs") as typeof import("node:fs");
-
-  // 尝试从找到的 openclaw 根目录加载 gateway-runtime.js
-  const tryLoadFromRoot = (root: string) => {
-    for (const rel of ["dist/plugin-sdk/gateway-runtime.js", "plugin-sdk/gateway-runtime.js"]) {
-      const p = path.join(root, rel);
-      try {
-        if (fs.existsSync(p)) return req(p);
-      } catch { /* try next */ }
-    }
-    return null;
-  };
-
-  // 策略 1: link-sdk-core.cjs findOpenclawRoot
-  try {
-    const { findOpenclawRoot } = req(path.join(pluginRoot, "scripts", "link-sdk-core.cjs")) as {
-      findOpenclawRoot: (root: string) => string | null;
-    };
-    const root = findOpenclawRoot(pluginRoot);
-    if (root) {
-      const mod = tryLoadFromRoot(root);
-      if (mod) return mod;
-    }
-  } catch { /* fallback */ }
-
-  // 策略 2: process.argv[1] 反推（当前进程就是 openclaw）
-  try {
-    const entry = process.argv[1];
-    if (entry) {
-      const realEntry = fs.realpathSync(entry);
-      let dir = path.dirname(realEntry);
-      for (let i = 0; i < 6; i++) {
-        const mod = tryLoadFromRoot(dir);
-        if (mod) return mod;
-        const parent = path.dirname(dir);
-        if (parent === dir) break;
-        dir = parent;
-      }
-    }
-  } catch { /* fallback */ }
-
-  throw new Error("Cannot find openclaw/plugin-sdk/gateway-runtime (all strategies failed)");
-}
-
-// ─── 动态加载的模块类型（兼容旧版框架） ───────────────────────
-
-/** gateway-runtime 模块的接口（动态 import） */
-type GatewayClient = {
-  start: () => void | Promise<void>;
-  stop: () => void | Promise<void>;
-  request: (method: string, params: unknown) => Promise<unknown>;
-};
+import { getBotForAccount } from "../bot-instance.js";
+import type { PluginLogger } from '../utils/plugin-logger.js';
+import type { InlineKeyboard, KeyboardButton } from "../types.js";
 
+import { loadApprovalGatewayRuntime, type ApprovalGatewayClient } from '../adapter/gateway.js';
 type EventFrame = {
   event: string;
   payload: unknown;
@@ -139,11 +75,7 @@ export interface QQBotApprovalHandlerOpts {
   clientSecret: string;
   cfg: OpenClawConfig;
   gatewayUrl?: string;
-  log?: {
-    info: (msg: string) => void;
-    error: (msg: string) => void;
-    debug?: (msg: string) => void;
-  };
+  log?: PluginLogger;
 }
 
 type ApprovalKind = "exec" | "plugin";
@@ -255,11 +187,12 @@ function resolveTarget(
 // ─── Handler 类 ──────────────────────────────────────────────
 
 export class QQBotApprovalHandler {
-  private gatewayClient: GatewayClient | null = null;
+  private gatewayClient: ApprovalGatewayClient | null = null;
   private pending = new Map<string, PendingEntry>();
   private requestCache = new Map<string, CachedApprovalRequest>();
   private opts: QQBotApprovalHandlerOpts;
   private started = false;
+  private connected = false;
 
   constructor(opts: QQBotApprovalHandlerOpts) {
     this.opts = opts;
@@ -269,14 +202,12 @@ export class QQBotApprovalHandler {
     if (this.started) return;
     this.started = true;
     const { log } = this.opts;
-    log?.info(`[qqbot:${this.opts.accountId}] approval-handler: starting`);
+    log?.debug?.(`[qqbot:${this.opts.accountId}] approval-handler: starting`);
 
     // 动态加载 gateway-runtime（兼容旧版框架 / pnpm 环境）
-    let gatewayRuntime: { createOperatorApprovalsGatewayClient: (...args: any[]) => Promise<GatewayClient> };
-    try {
-      gatewayRuntime = loadGatewayRuntime();
-    } catch (err) {
-      log?.error(`[qqbot:${this.opts.accountId}] approval-handler: gateway-runtime module not available, approval feature disabled. Error: ${err}`);
+    const gatewayRuntime = loadApprovalGatewayRuntime();
+    if (!gatewayRuntime) {
+      log?.debug?.(`[qqbot:${this.opts.accountId}] approval-handler: gateway-runtime not available, approval disabled`);
       this.started = false;
       return;
     }
@@ -287,9 +218,15 @@ export class QQBotApprovalHandler {
         gatewayUrl: this.opts.gatewayUrl,
         clientDisplayName: "QQBot Approval Handler",
         onEvent: (evt: EventFrame) => this.handleGatewayEvent(evt),
-        onHelloOk: () => log?.info(`[qqbot:${this.opts.accountId}] approval-handler: connected to gateway`),
+        onHelloOk: () => {
+          this.connected = true;
+          log?.debug?.(`[qqbot:${this.opts.accountId}] approval-handler: connected to gateway`);
+        },
         onConnectError: (err: { message: string }) => log?.error(`[qqbot:${this.opts.accountId}] approval-handler: connect error: ${err.message}`),
-        onClose: (code: number, reason: string) => log?.debug?.(`[qqbot:${this.opts.accountId}] approval-handler: gateway closed: ${code} ${reason}`),
+        onClose: (code: number, reason: string) => {
+          this.connected = false;
+          log?.debug?.(`[qqbot:${this.opts.accountId}] approval-handler: gateway closed: ${code} ${reason}`);
+        },
       });
       this.gatewayClient.start();
       setApprovalFeatureAvailable(true);
@@ -305,11 +242,14 @@ export class QQBotApprovalHandler {
     for (const entry of this.pending.values()) clearTimeout(entry.timeoutId);
     this.pending.clear();
     this.requestCache.clear();
-    this.gatewayClient?.stop();
+    await this.gatewayClient?.stop();
     this.gatewayClient = null;
-    this.opts.log?.info(`[qqbot:${this.opts.accountId}] approval-handler: stopped`);
+    this.opts.log?.debug(`[qqbot:${this.opts.accountId}] approval-handler: stopped`);
   }
 
+  /** gateway 是否已建立连接 */
+  get isConnected(): boolean { return this.connected; }
+
   /** 检查是否有指定 shortId 对应的 pending 审批 */
   hasShortId(shortId: string): boolean {
     for (const id of this.pending.keys()) {
@@ -323,7 +263,10 @@ export class QQBotApprovalHandler {
     approvalId: string,
     decision: "allow-once" | "allow-always" | "deny"
   ): Promise<boolean> {
-    if (!this.gatewayClient) return false;
+    if (!this.gatewayClient) {
+      this.opts.log?.warn(`[qqbot:${this.opts.accountId}] approval-handler: resolve ignored ${approvalId} → gatewayClient not ready`);
+      return false;
+    }
 
     // 查找完整 ID：支持完整 ID（exec:uuid / plugin:uuid）、纯 UUID、或 shortId（8位）
     let fullId = approvalId;
@@ -351,11 +294,11 @@ export class QQBotApprovalHandler {
     const isPending = this.pending.has(fullId);
     const isCached = this.requestCache.has(fullId);
 
-    this.opts.log?.info(`[qqbot:${this.opts.accountId}] approval-handler: resolving ${fullId} (input=${approvalId}) kind=${kind} → ${decision}, pending=${isPending}, cached=${isCached}`);
+    this.opts.log?.debug?.(`[qqbot:${this.opts.accountId}] approval-handler: resolving ${fullId} (input=${approvalId}) kind=${kind} → ${decision}, pending=${isPending}, cached=${isCached}`);
 
     try {
       await this.gatewayClient.request(method, { id: fullId, decision });
-      this.opts.log?.info(`[qqbot:${this.opts.accountId}] approval-handler: RPC success ${toShortId(fullId)} → ${decision} (method=${method})`);
+      this.opts.log?.debug(`[qqbot:${this.opts.accountId}] approval-handler: RPC success ${toShortId(fullId)} → ${decision} (method=${method})`);
       return true;
     } catch (err) {
       this.opts.log?.error(`[qqbot:${this.opts.accountId}] approval-handler: resolve failed: ${err}`);
@@ -384,7 +327,10 @@ export class QQBotApprovalHandler {
 
     // 只处理本账号的请求
     const reqAccountId = (request.request as any).turnSourceAccountId?.trim();
-    if (reqAccountId && reqAccountId !== accountId) return;
+    if (reqAccountId && reqAccountId !== accountId) {
+      log?.debug?.(`[qqbot:${accountId}] approval-handler: ${kind} ${shortId} ignored → account mismatch (req=${reqAccountId})`);
+      return;
+    }
 
     // 解析投递目标
     const sessionKey = (request.request as any).sessionKey;
@@ -419,12 +365,12 @@ export class QQBotApprovalHandler {
     await new Promise((r) => setTimeout(r, 2000));
 
     try {
-      const token = await getAccessToken(appId, clientSecret);
-      if (target.type === "c2c") {
-        await sendC2CMessageWithInlineKeyboard(token, target.id, text, keyboard);
-      } else {
-        await sendGroupMessageWithInlineKeyboard(token, target.id, text, keyboard);
-      }
+      const bot = getBotForAccount(accountId);
+      const target_reply = {
+        scope: target.type as "c2c" | "group",
+        targetId: target.id,
+      };
+      await bot.sendTextWithKeyboard(target_reply, text, keyboard as any);
       log?.info(`[qqbot:${accountId}] approval-handler: sent ${kind} approval ${shortId}`);
 
       const timeoutId = setTimeout(() => {