@jerryliang122/openclaw-qqbot 1.0.1 → 1.0.2

package/dist/index.d.cts

@@ -1203,6 +1203,8 @@ type Listener = () => void;
 declare function subscribeOutboundMessage(accountId: string, scope: string, targetId: string, listener: Listener): () => void;
 /**
  * 消息发送成功后由出站层调用：通知该会话活跃的 typing 会话补发续期。
+ * 单个监听器抛错只跳过该监听器——此处位于网关发送成功路径上，
+ * 不能让一个坏的订阅方炸掉整条 send 链。
  */
 declare function notifyOutboundMessageSent(accountId: string, scope: string, targetId: string): void;
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jerryliang122/openclaw-qqbot",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "QQ Bot channel plugin for OpenClaw (independently maintained fork)",
   "publishConfig": {
     "access": "public",

package/src/adapter/pairing.ts

@@ -12,6 +12,9 @@ import { spawn } from 'node:child_process';
 import { createRequire } from 'node:module';
 import * as path from 'node:path';
 import { resolveOpenClawCli } from '../features/secret-store-cli.js';
+import { createPluginLogger } from '../utils/plugin-logger.js';
+
+const pairingLog = createPluginLogger({ prefix: '[pairing]' });
 
 export interface PairingApi {
   readAllowFromStore: (params: { channel: string; accountId: string }) => Promise<string[]>;
@@ -64,6 +67,7 @@ export function getPairingApi(): PairingApi {
 }
 
 const APPROVE_TIMEOUT_MS = 30_000;
+const STDERR_TAIL_LIMIT = 500;
 
 async function approveViaCli(params: {
   channel: string;
@@ -82,13 +86,22 @@ async function approveViaCli(params: {
   ];
   return new Promise((resolve) => {
     const child = spawn(cli.cmd, args, { stdio: ['ignore', 'pipe', 'pipe'] });
+    // 收集 stderr 尾部：spawn 失败/非零退出时区分「CLI 坏了」与「码无效」
+    let stderrTail = '';
+    child.stderr?.on('data', (chunk: Buffer) => {
+      stderrTail = (stderrTail + chunk.toString()).slice(-STDERR_TAIL_LIMIT);
+    });
     const timer = setTimeout(() => child.kill('SIGKILL'), APPROVE_TIMEOUT_MS);
-    child.on('error', () => {
+    child.on('error', (err) => {
       clearTimeout(timer);
+      pairingLog.warn(`approve CLI spawn failed: ${err.message}`, { cmd: cli.cmd });
       resolve({ approved: false });
     });
     child.on('close', (codeNum) => {
       clearTimeout(timer);
+      if (codeNum !== 0) {
+        pairingLog.warn(`approve CLI exited ${codeNum}`, { channel: params.channel, accountId: params.accountId, stderr: stderrTail || undefined });
+      }
       resolve({ approved: codeNum === 0 });
     });
   });

package/src/adapter/webhook.ts

@@ -97,7 +97,12 @@ export function createPluginWebhookAdapter(params: {
 function createSharedHandler(path: string, log: PluginLogger) {
   return async (req: any, res: any) => {
     try {
-      const ingress = await import('openclaw/plugin-sdk/webhook-ingress').catch(() => null);
+      const ingress = await import('openclaw/plugin-sdk/webhook-ingress').catch((err) => {
+        // 管线缺失会让所有请求降级到 handleSimple（无签名匹配多账号路由），
+        // 此前完全无痕迹——至少留一条 WARN 说明降级发生及原因
+        log.warn?.(`[webhook] ingress pipeline unavailable, downgrading to simple handler: ${err instanceof Error ? err.message : String(err)}`);
+        return null;
+      });
 
       if (!ingress?.withResolvedWebhookRequestPipeline) {
         await handleSimple(req, res, path, log);
@@ -208,14 +213,20 @@ async function delegateToHandler(handler: WebhookRequestHandler, req: any, res:
 async function handleSimple(req: any, res: any, path: string, log: PluginLogger) {
   try {
     const ct = String(req.headers['content-type'] ?? '');
-    if (!ct.includes('application/json')) { res.statusCode = 400; res.end(JSON.stringify({ error: 'unsupported content type' })); return; }
+    if (!ct.includes('application/json')) {
+      log.debug?.(`[webhook] simple ${req.method ?? '?'} ${path} -> 400 (unsupported content type)`);
+      res.statusCode = 400; res.end(JSON.stringify({ error: 'unsupported content type' })); return;
+    }
 
     const chunks: Buffer[] = [];
     let total = 0;
     for await (const chunk of req) {
       const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
       total += buf.length;
-      if (total > 1_048_576) { res.statusCode = 413; res.end(JSON.stringify({ error: 'too large' })); return; }
+      if (total > 1_048_576) {
+        log.debug?.(`[webhook] simple ${req.method ?? '?'} ${path} -> 413 (too large)`);
+        res.statusCode = 413; res.end(JSON.stringify({ error: 'too large' })); return;
+      }
       chunks.push(buf);
     }
     const rawBody = Buffer.concat(chunks);
@@ -223,12 +234,14 @@ async function handleSimple(req: any, res: any, path: string, log: PluginLogger)
     for (const entry of entries) {
       const resp = await entry.handler({ body: rawBody, headers: mapHeaders(req) });
       if (resp.status < 400) {
+        log.debug?.(`[webhook] simple ${req.method ?? '?'} ${path} -> ${resp.status} (account=${entry.accountId})`);
         res.statusCode = resp.status;
         if (resp.headers) for (const [k, v] of Object.entries(resp.headers)) res.setHeader(k, v as string);
         res.end(resp.body);
         return;
       }
     }
+    log.warn?.(`[webhook] simple ${req.method ?? '?'} ${path} -> 401 (no target matched signature)`);
     res.statusCode = 401; res.end(JSON.stringify({ error: 'invalid signature' }));
   } catch (err) {
     log.error(`Webhook simple handler error: ${(err as Error).message}`);

package/src/commands/bot-approve.ts

@@ -105,7 +105,7 @@ export function botApprove(getRuntime: () => PluginRuntime): SlashCommand {
           cfg.tools.exec ??= {};
           cfg.tools.exec.security = preset.security;
           cfg.tools.exec.ask = preset.ask;
-        });
+        }, ctx.log);
         if (error) return error;
 
         if (arg === 'on') {
@@ -127,7 +127,7 @@ export function botApprove(getRuntime: () => PluginRuntime): SlashCommand {
             if (Object.keys(exec).length === 0) delete cfg.tools.exec;
             if (cfg.tools && Object.keys(cfg.tools).length === 0) delete cfg.tools;
           }
-        });
+        }, ctx.log);
         if (error) return error;
 
         return ['✅ 审批配置已重置', '', '已移除 tools.exec.security 和 tools.exec.ask', '框架将使用默认值（security=deny, ask=on-miss）', '', '如需开启命令执行，请使用 /bot-approve on'].join('\n');

package/src/commands/bot-group-always.ts

@@ -44,7 +44,7 @@ export function botGroupAlways(account: ResolvedQQBotAccount, getRuntime: () =>
 
       const error = await updateAccountConfig(account, getRuntime, (acfg) => {
         (acfg as any).defaultRequireMention = newRequireMention;
-      });
+      }, ctx.log);
       if (error) return error;
 
       // 更新内存中的配置

package/src/commands/bot-streaming.ts

@@ -43,7 +43,7 @@ export function botStreaming(account: ResolvedQQBotAccount, getRuntime: () => Pl
 
       const error = await updateAccountConfig(account, getRuntime, (acfg) => {
         (acfg as any).streaming = { mode: targetEnabled ? 'partial' : 'off' };
-      });
+      }, ctx.log);
       if (error) return error;
 
       account.config.streaming = { mode: targetEnabled ? 'partial' : 'off' };

package/src/commands/config-util.ts

@@ -3,6 +3,10 @@ import type { SlashCommandHandlerContext } from '@tencent-connect/qqbot-nodejs';
 import type { PluginRuntime } from 'openclaw/plugin-sdk';
 import { getAdapters } from '../adapter/resolve.js';
 
+// 最小结构类型：同时兼容 PluginLogger 与 SDK MiddlewareContext 的 Logger
+// （后者的 warn/debug 是可选方法且无 child）——与 quota-manager 的 log 参数同款
+type WarnSink = { warn?: (msg: string, meta?: Record<string, unknown>) => void };
+
 /**
  * 命令授权检查（用于 SlashCommand.authorized 回调）。
  *
@@ -50,6 +54,7 @@ export async function updateAccountConfig(
   account: ResolvedQQBotAccount,
   getRuntime: () => PluginRuntime,
   updater: (accountConfig: Record<string, unknown>) => void,
+  log?: WarnSink,
 ): Promise<string | null> {
   const [err, result] = await resolvePersistFn(getRuntime);
   if (err || !result) return err;
@@ -72,6 +77,7 @@ export async function updateAccountConfig(
     });
     return null;
   } catch (e) {
+    log?.warn?.(`[cmd] account config persist failed: ${e instanceof Error ? e.message : String(e)}`, { accountId: account.accountId });
     return `⚠️ 配置修改失败：${e instanceof Error ? e.message : String(e)}`;
   }
 }
@@ -83,6 +89,7 @@ export async function updateAccountConfig(
 export async function updateGlobalConfig(
   getRuntime: () => PluginRuntime,
   updater: (cfg: any) => void,
+  log?: WarnSink,
 ): Promise<string | null> {
   const [err, result] = await resolvePersistFn(getRuntime);
   if (err || !result) return err;
@@ -91,6 +98,7 @@ export async function updateGlobalConfig(
     await result.persist(updater);
     return null;
   } catch (e) {
+    log?.warn?.(`[cmd] global config persist failed: ${e instanceof Error ? e.message : String(e)}`);
     return `⚠️ 配置修改失败：${e instanceof Error ? e.message : String(e)}`;
   }
 }

package/src/commands/index.ts

@@ -4,7 +4,7 @@
  * 通过 SDK 的 slashCommand 中间件统一注册所有内置命令。
  * 每个命令拆分为独立文件，此处仅编排。
  */
-import type { SlashCommand } from '@tencent-connect/qqbot-nodejs';
+import type { SlashCommand, SlashCommandHandlerContext } from '@tencent-connect/qqbot-nodejs';
 import type { PluginRuntime } from 'openclaw/plugin-sdk';
 import type { ResolvedQQBotAccount } from '../types.js';
 import { botHelp } from './bot-help.js';
@@ -23,6 +23,43 @@ export interface CommandBuildOptions {
   getRuntime: () => PluginRuntime;
 }
 
+// ========== 命令执行审计 ==========
+
+const CMD_AUDIT_RAW_LIMIT = 80;
+
+/**
+ * 审计包装：每个 /bot-* 调用留一条 [cmd] INFO（命令、执行者、scope、
+ * 原始输入截断），授权拒绝留 [cmd] WARN。SDK 的 slashCommand 中间件只在
+ * handler 抛错时输出 ERROR——成功执行与越权尝试此前零痕迹，含
+ * /bot-clear-storage（删存储）、/bot-approve（安全相关）这类操作。
+ *
+ * ctx.log 即网关注入 SDK 的 PluginLogger（带账号前缀与 request-context
+ * 元数据）；warn/debug 在 SDK Logger 接口上是可选方法，须可选链调用。
+ */
+export function withAudit(cmd: SlashCommand): SlashCommand {
+  const name = Array.isArray(cmd.name) ? cmd.name.join('|') : cmd.name;
+  const origHandler = cmd.handler;
+  const origAuthorized = cmd.authorized;
+
+  return {
+    ...cmd,
+    authorized: origAuthorized
+      ? (ctx: SlashCommandHandlerContext) => {
+          const verdict = origAuthorized(ctx);
+          if (verdict !== true) {
+            ctx.log?.warn?.(`[cmd] unauthorized ${name} sender=${ctx.message?.senderId ?? '?'} scope=${ctx.message?.kind ?? '?'}`);
+          }
+          return verdict;
+        }
+      : undefined,
+    handler: async (ctx: SlashCommandHandlerContext) => {
+      const raw = (ctx.command?.raw ?? '').slice(0, CMD_AUDIT_RAW_LIMIT);
+      ctx.log?.info?.(`[cmd] ${name} sender=${ctx.message?.senderId ?? '?'} scope=${ctx.message?.kind ?? '?'} raw="${raw}"`);
+      return origHandler(ctx);
+    },
+  };
+}
+
 /**
  * 构建标准命令列表（匹配后直接回复，不进入 AI）
  */
@@ -32,17 +69,17 @@ export function buildCommandList(account: ResolvedQQBotAccount, opts: CommandBui
   // help 需要访问完整命令列表，延迟绑定
   const help = botHelp(account, () => commands);
   commands.push(
-    help,
-    botPing(),
-    botVersion(account),
-    botMe(),
-    botLogs(opts.getRuntime()),
-    botStreaming(account, opts.getRuntime),
-    botClearStorage(account),
-    botApprove(opts.getRuntime),
-    botGroupAlways(account, opts.getRuntime),
-    botGroupInfo(account),
-    botPairing(opts.getRuntime),
+    withAudit(help),
+    withAudit(botPing()),
+    withAudit(botVersion(account)),
+    withAudit(botMe()),
+    withAudit(botLogs(opts.getRuntime())),
+    withAudit(botStreaming(account, opts.getRuntime)),
+    withAudit(botClearStorage(account)),
+    withAudit(botApprove(opts.getRuntime)),
+    withAudit(botGroupAlways(account, opts.getRuntime)),
+    withAudit(botGroupInfo(account)),
+    withAudit(botPairing(opts.getRuntime)),
   );
 
   return commands;

package/src/dispatch/dispatch.ts

@@ -206,7 +206,7 @@ export async function dispatchToOpenClaw(
     ? new DeliverDebouncer(debounceConfig, async (targetId, mergedText) => {
         const result = await sendText({ to: targetId, text: mergedText, accountId: account.accountId, replyToId: envelope.messageId, account });
         trackOutbound(result, 'debounce');
-      })
+      }, dlog)
     : undefined;
 
   const deliverCtx: DeliverContext = {

package/src/features/approval-capability.ts

@@ -33,6 +33,11 @@ import { DEFAULT_ACCOUNT_ID, resolveQQBotAccount } from "../config.js";
 import { tryGetBotForAccount } from "../bot-instance.js";
 import { getQQBotRuntime } from "../runtime.js";
 import { getAdapters } from "../adapter/resolve.js";
+import { createPluginLogger } from "../utils/plugin-logger.js";
+
+// deliverPending 由框架 approval-delivery-runtime 回调，无 logger 参数可传；
+// 审批卡投递的成功/失败此前只在失败时抛给框架，成功零痕迹
+const approvalLog = createPluginLogger({ prefix: "[approval]" });
 import type { InlineKeyboard, ResolvedQQBotAccount } from "../types.js";
 import {
   buildApprovalKeyboard,
@@ -193,6 +198,7 @@ const qqbotApprovalNativeRuntime = createChannelApprovalNativeRuntimeAdapter<
         accountId && accountId !== DEFAULT_ACCOUNT_ID ? accountId : DEFAULT_ACCOUNT_ID;
       const bot = tryGetBotForAccount(resolvedAccountId);
       if (!bot) {
+        approvalLog.error(`card deliver failed: bot unavailable account=${resolvedAccountId} target=${preparedTarget.type}:${preparedTarget.id}`);
         throw new Error(
           `QQ Bot gateway not running for account "${resolvedAccountId}" — cannot deliver approval`,
         );
@@ -202,12 +208,19 @@ const qqbotApprovalNativeRuntime = createChannelApprovalNativeRuntimeAdapter<
         scope: preparedTarget.type as "c2c" | "group",
         targetId: preparedTarget.id,
       };
-      const result = await bot.sendTextWithKeyboard(
-        replyTarget,
-        pendingPayload.text,
-        pendingPayload.keyboard as never,
-      );
-      const messageId = (result as { id?: string } | undefined)?.id;
+      let result: { id?: string } | undefined;
+      try {
+        result = await bot.sendTextWithKeyboard(
+          replyTarget,
+          pendingPayload.text,
+          pendingPayload.keyboard as never,
+        );
+      } catch (err) {
+        approvalLog.error(`card deliver failed: ${err instanceof Error ? err.message : String(err)}`, { account: resolvedAccountId, target: `${preparedTarget.type}:${preparedTarget.id}` });
+        throw err;
+      }
+      const messageId = result?.id;
+      approvalLog.info(`card delivered account=${resolvedAccountId} target=${preparedTarget.type}:${preparedTarget.id} msgId=${messageId ?? '-'}`);
       return {
         messageId,
         targetType: preparedTarget.type,

package/src/features/credential-backup.ts

@@ -9,6 +9,9 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { getQQBotDataDir } from '../utils/platform.js';
+import { createPluginLogger } from '../utils/plugin-logger.js';
+
+const backupLog = createPluginLogger({ prefix: '[credential-backup]' });
 
 const BACKUP_DIR = 'credential-backup';
 const BACKUP_FILENAME = 'current.json';
@@ -44,8 +47,9 @@ export function saveCredentialBackup(accountId: string, appId: string, clientSec
     const tmpPath = backupPath + '.tmp';
     fs.writeFileSync(tmpPath, JSON.stringify(data, null, 2) + '\n', 'utf8');
     fs.renameSync(tmpPath, backupPath);
-  } catch {
-    // 非关键操作，静默忽略
+  } catch (err) {
+    // 非关键操作，不中断启动；DEBUG 留痕（恢复失败路径在 lifecycle 已有 ERROR）
+    backupLog.debug(`save failed: ${err instanceof Error ? err.message : String(err)}`, { accountId });
   }
 }
 
@@ -60,7 +64,8 @@ export function loadCredentialBackup(accountId?: string): CredentialBackup | nul
       return readBackupFile(backupPath, accountId);
     }
     return null;
-  } catch {
+  } catch (err) {
+    backupLog.debug(`load failed: ${err instanceof Error ? err.message : String(err)}`);
     return null;
   }
 }

package/src/features/history-store.ts

@@ -40,7 +40,14 @@ export function recordOutboundToGroupHistory(
     timestamp: Date.now(),
     isBot: true,
   };
-  void _store?.append?.(historyGroupKey(accountId, groupOpenid), historyEntry, limit);
+  // append 可能返回 Promise（异步后端）；当前 MemoryHistoryStore 为同步，
+  // 但 rejected promise 若不捕获会成为 unhandledRejection——纯防御
+  const appended = _store?.append?.(historyGroupKey(accountId, groupOpenid), historyEntry, limit) as
+    | void
+    | Promise<void>;
+  if (appended && typeof (appended as Promise<void>).catch === 'function') {
+    (appended as Promise<void>).catch(() => {/* 历史缓冲是尽力而为，失败不影响主流程 */});
+  }
 }
 
 /**

package/src/features/quota-manager.ts

@@ -85,6 +85,7 @@ export function checkAndConsumePassiveReplyQuota(
   const { accountId, msgId, scope, log } = params;
 
   if (!msgId) {
+    log?.debug?.(`[${accountId}] passive quota check without msgId (proactive path) scope=${scope}`);
     return { canReply: false, rollback: () => {} };
   }
 
@@ -93,17 +94,19 @@ export function checkAndConsumePassiveReplyQuota(
   const ttl = QUOTA_LIMITS[scope].ttlMs;
 
   let cached = quotaCache.get(key);
-  
+
   // 检查过期：msg_id 过期后不能用于被动回复
   // 这是 QQ Bot 平台限制，API 会返回错误 40034128
   if (cached && now > cached.expiresAt) {
-    // msg_id 已过期，不能用于被动回复
+    // msg_id 已过期，不能用于被动回复（降级决策的日志在 adapter/gateway 层）
+    log?.debug?.(`[${accountId}] passive quota denied (expired): ${key}`);
     return { canReply: false, rollback: () => {} };
   }
 
   // 检查配额
   const limit = QUOTA_LIMITS[scope].count;
   if (cached && cached.count >= limit) {
+    log?.debug?.(`[${accountId}] passive quota denied (exhausted): ${key} count=${cached.count}/${limit}`);
     return { canReply: false, rollback: () => {} };
   }
 

package/src/features/typing-refresh.ts

@@ -43,9 +43,17 @@ export function subscribeOutboundMessage(
 
 /**
  * 消息发送成功后由出站层调用：通知该会话活跃的 typing 会话补发续期。
+ * 单个监听器抛错只跳过该监听器——此处位于网关发送成功路径上，
+ * 不能让一个坏的订阅方炸掉整条 send 链。
  */
 export function notifyOutboundMessageSent(accountId: string, scope: string, targetId: string): void {
   const set = listeners.get(key(accountId, scope, targetId));
   if (!set) return;
-  for (const listener of [...set]) listener();
+  for (const listener of [...set]) {
+    try {
+      listener();
+    } catch {
+      // 监听器自身的问题不应影响发送方与其他监听器
+    }
+  }
 }

package/src/gateway/event-handlers.ts

@@ -122,8 +122,13 @@ export async function handleInteraction(
       const requireMention = updatedCfg?.requireMention ?? true;
       const clawCfg = buildClawCfg(requireMention, [], resolveGroupPolicy(cfg, account.accountId));
       await acknowledgeInteraction(event.id, 0, { claw_cfg: clawCfg });
-    } catch {
-      try { await acknowledgeInteraction(event.id); } catch { /* ignore */ }
+    } catch (err) {
+      log.warn(`interaction update ack failed: ${err instanceof Error ? err.message : String(err)}`);
+      try {
+        await acknowledgeInteraction(event.id);
+      } catch (retryErr) {
+        log.debug(`interaction update ack retry failed: ${retryErr instanceof Error ? retryErr.message : String(retryErr)}`);
+      }
     }
     return;
   }
@@ -162,7 +167,11 @@ async function handleConfigQuery(
     await ack(event.id, 0, { claw_cfg: clawCfg });
   } catch (err) {
     log.warn(`interaction query failed: ${(err as Error)?.message ?? err}, ack without data`);
-    try { await ack(event.id); } catch { /* ignore */ }
+    try {
+      await ack(event.id);
+    } catch (retryErr) {
+      log.debug(`interaction query ack retry failed: ${retryErr instanceof Error ? retryErr.message : String(retryErr)}`);
+    }
   }
 }
 
@@ -193,7 +202,9 @@ async function handleApproval(
   log: PluginLogger,
   ack: (id: string) => Promise<void>,
 ): Promise<void> {
-  try { await ack(event.id); } catch { /* ignore */ }
+  try { await ack(event.id); } catch (err) {
+    log.debug(`[approval] initial ack failed: ${err instanceof Error ? err.message : String(err)}`);
+  }
 
   const buttonData = event.data?.resolved?.button_data;
   if (!buttonData?.startsWith('approve:')) return;
@@ -218,6 +229,10 @@ async function handleApproval(
     return;
   }
 
+  log.info(
+    `[approval] tap operator=${operatorId ?? 'unknown'} approvalId=${parsed.approvalId} kind=${parsed.approvalKind} decision=${parsed.decision} account=${account.accountId}`,
+  );
+
   try {
     const { resolveApprovalOverGateway } = await import('openclaw/plugin-sdk/approval-gateway-runtime');
     await resolveApprovalOverGateway({
@@ -228,6 +243,9 @@ async function handleApproval(
       senderId: operatorId,
       clientDisplayName: 'QQBot Approval Handler',
     });
+    log.info(
+      `[approval] resolved approvalId=${parsed.approvalId} decision=${parsed.decision} operator=${operatorId ?? 'unknown'}`,
+    );
   } catch (err) {
     log.error(`interaction approve error: ${err instanceof Error ? err.message : String(err)}`);
   }
@@ -242,7 +260,9 @@ async function handleQuestion(
   log: PluginLogger,
   ack: (id: string) => Promise<void>,
 ): Promise<void> {
-  try { await ack(event.id); } catch { /* ignore */ }
+  try { await ack(event.id); } catch (err) {
+    log.debug(`[question] initial ack failed: ${err instanceof Error ? err.message : String(err)}`);
+  }
 
   const buttonData = event.data?.resolved?.button_data;
   if (!buttonData) return;
@@ -270,7 +290,7 @@ async function handleQuestion(
       senderId: operatorId,
       clientDisplayName: 'QQBot question',
     });
-    log.debug(`[question] resolved questionId=${parsed.questionId} optionIndex=${parsed.optionIndex} status=${result.status}`);
+    log.info(`[question] resolved questionId=${parsed.questionId} optionIndex=${parsed.optionIndex} status=${result.status} operator=${operatorId ?? 'unknown'}`);
   } catch (err) {
     log.error(`[question] resolve error: ${err instanceof Error ? err.message : String(err)}`);
   }
@@ -308,7 +328,7 @@ async function handleMultiQuestionTap(
 
   if (tap.status === 'unknown' || tap.status === 'terminal') {
     log.info(`[question] multi tap ignored id=${parsed.questionId} status=${tap.status}`);
-    await sendMultiQuestionFeedback(event, account, '该问题已提交或已过期');
+    await sendMultiQuestionFeedback(event, account, '该问题已提交或已过期', log);
     return;
   }
   if (tap.status === 'resolving') {
@@ -322,6 +342,7 @@ async function handleMultiQuestionTap(
       event,
       account,
       `✅ 已记录 ${tap.answeredCount}/${tap.total}\n还剩：${pendingTitles.join('、')}`,
+      log,
     );
     return;
   }
@@ -363,7 +384,7 @@ async function sendMultiQuestionConfirmCard(
   if (!bot) {
     markMultiQuestionResolveFailed(questionId);
     log.error(`[question] confirm card send failed: bot unavailable id=${questionId}`);
-    await sendMultiQuestionFeedbackText(scope, peerId, account, '⚠️ 提交卡发送失败，请直接文字回复答案');
+    await sendMultiQuestionFeedbackText(scope, peerId, account, '⚠️ 提交卡发送失败，请直接文字回复答案', log);
     return;
   }
   try {
@@ -373,7 +394,7 @@ async function sendMultiQuestionConfirmCard(
   } catch (err) {
     markMultiQuestionResolveFailed(questionId);
     log.error(`[question] confirm card send error id=${questionId}: ${err instanceof Error ? err.message : String(err)}`);
-    await sendMultiQuestionFeedbackText(scope, peerId, account, '⚠️ 提交卡发送失败，请直接文字回复答案');
+    await sendMultiQuestionFeedbackText(scope, peerId, account, '⚠️ 提交卡发送失败，请直接文字回复答案', log);
   }
 }
 
@@ -382,11 +403,12 @@ async function sendMultiQuestionFeedback(
   event: InteractionEvent,
   account: ResolvedQQBotAccount,
   text: string,
+  log?: PluginLogger,
 ): Promise<void> {
   const scope = event.group_openid ? 'group' as const : 'c2c' as const;
   const targetId = event.group_openid ?? event.user_openid;
   if (!targetId) return;
-  await sendMultiQuestionFeedbackText(scope, targetId, account, text);
+  await sendMultiQuestionFeedbackText(scope, targetId, account, text, log);
 }
 
 async function sendMultiQuestionFeedbackText(
@@ -394,13 +416,15 @@ async function sendMultiQuestionFeedbackText(
   targetId: string,
   account: ResolvedQQBotAccount,
   text: string,
+  log?: PluginLogger,
 ): Promise<void> {
   const bot = tryGetBotForAccount(account.accountId);
   if (!bot) return;
   try {
     await bot.sendText({ scope, targetId }, text);
-  } catch {
-    // 主动消息可能触发平台限频；回执是锦上添花，吞掉即可
+  } catch (err) {
+    // 主动消息可能触发平台限频；回执是锦上添花，吞掉即可（仅 DEBUG 留痕）
+    log?.debug(`[question] feedback send failed scope=${scope}: ${err instanceof Error ? err.message : String(err)}`);
   }
 }
 

package/src/gateway/lifecycle.ts

@@ -73,6 +73,14 @@ export async function startAccountWithCredentialRecovery(ctx: StartAccountContex
     }
   }
 
+  // 账号启动留痕：哪个账号、以什么凭证来源、什么传输模式启动了
+  // （secret 只打来源不打值）——多账号排障时定位配置实际生效形态
+  log.info(
+    `account starting accountId=${account.accountId} appId=${account.appId || '(none)'}`
+    + ` enabled=${account.enabled ?? true} secretSource=${account.secretSource ?? '?'}`
+    + ` transport=${account.config.transport}${account.config.transport === 'webhook' ? ` path=${account.config.webhook?.path ?? '(default)'}` : ''}`,
+  );
+
   // 创建 gateway 实例并注册
   const gw = new QQBotGateway(account, runtime, log);
   registerGateway(account.accountId, gw);

package/src/gateway/qqbot-gateway.ts

@@ -306,6 +306,25 @@ export class QQBotGateway {
     const { accountId, appId } = this.account;
     const senderName = this.account.config.name ?? appId;
 
+    // 出站成功的统一 INFO 痕迹：gateway 的 sendText/sendMedia/sendVoice/sendVideo/
+    // sendFile 与中间件对 bot.sendText 的直调全部落到这两个被包装的方法上。
+    // 此前成功发送在插件层零日志，只能靠 SDK 的 `<<< Status` 状态行倒推。
+    const MEDIA_KIND_BY_TYPE = new Map<number, string>([
+      [1, 'image'], [2, 'video'], [3, 'voice'], [4, 'file'],
+    ]);
+    const logTx = (
+      kind: string,
+      target: { scope?: string; targetId?: string; msgId?: string },
+      msg: { id?: string },
+      contentLen?: number,
+    ): void => {
+      this.log.info(
+        `[tx] sent kind=${kind} scope=${target.scope ?? '?'} target=${target.targetId ?? '?'}`
+        + ` msgId=${msg.id || '-'} passive=${target.msgId ? 'true' : 'false'}`
+        + (contentLen !== undefined ? ` contentLen=${contentLen}` : ''),
+      );
+    };
+
     const storeEntry = (msg: MessageResponse, content: string, target: { scope: string; targetId?: string }, mediaKind?: string): void => {
       // 出站 id 先登记回声表（不依赖 ext_info.ref_idx 是否返回），
       // 供 inboundGuard 识别平台回投的 bot 自身消息
@@ -352,6 +371,7 @@ export class QQBotGateway {
     const origSendText = this.bot.sendText.bind(this.bot);
     this.bot.sendText = async (target, text, ...rest) => {
       const result = await origSendText(target, text, ...rest);
+      logTx('text', target, result, text.length);
       storeEntry(result, text, target);
       return result;
     };
@@ -361,7 +381,10 @@ export class QQBotGateway {
     this.bot.sendMedia = async (params: any) => {
       const result = await origSendMedia(params);
       const msg = (result as any).message as MessageResponse | undefined;
-      if (msg) storeEntry(msg, '', params.target ?? { scope: '' }, params.mediaKind);
+      if (msg) {
+        logTx(MEDIA_KIND_BY_TYPE.get(params.fileType) ?? 'media', params.target ?? {}, msg);
+        storeEntry(msg, '', params.target ?? { scope: '' }, params.mediaKind);
+      }
       return result;
     };
 

package/src/middleware/access-control.ts

@@ -116,7 +116,9 @@ async function checkPairingMode(
     ].join('\n');
 
     ctx.log?.info?.(`[access] pairing required for ${opts.senderId}`);
-    await ctx.bot.sendText(ctx.replyTarget, reply).catch(() => {/* ignore */});
+    await ctx.bot.sendText(ctx.replyTarget, reply).catch((err: unknown) => {
+      ctx.log?.warn?.(`[access] pairing challenge send failed: ${err instanceof Error ? err.message : String(err)}`);
+    });
     ctx.stop('access:pairing_required');
   } catch (err) {
     ctx.log?.error?.(`[access] pairing error: ${(err as Error).message}`);