@jerryliang122/openclaw-qqbot 1.0.1 → 1.0.3

package/src/middleware/secret-capture.ts

@@ -49,14 +49,16 @@ async function replyToUser(
       try {
         await ctx.bot.sendText(ctx.replyTarget, text);
         return;
-      } catch {
+      } catch (err) {
         rollback();
-        // 落到主动降级
+        ctx.log?.warn?.(`[secret] passive reply failed, falling back to proactive: ${err instanceof Error ? err.message : String(err)}`);
       }
     }
   }
   const proactiveTarget = { scope: 'c2c' as const, targetId: ctx.message.senderId as string };
-  await ctx.bot.sendText(proactiveTarget, text).catch(() => {/* 尽力而为 */});
+  await ctx.bot.sendText(proactiveTarget, text).catch((err: unknown) => {
+    ctx.log?.warn?.(`[secret] proactive reply failed: ${err instanceof Error ? err.message : String(err)}`);
+  });
 }
 
 function formatSetFailure(name: string, result: SecretsStoreSetResult): string {

package/src/outbound/debounce.ts

@@ -13,6 +13,9 @@ const DEFAULT_WINDOW_MS = 1500;
 const DEFAULT_MAX_WAIT_MS = 8000;
 const DEFAULT_SEPARATOR = '\n\n---\n\n';
 
+// 最小结构类型：兼容 PluginLogger 与 SDK Logger（与 config-util 同款）
+type WarnSink = { warn?: (msg: string, meta?: Record<string, unknown>) => void };
+
 interface PendingDeliver {
   texts: string[];
   firstAt: number;
@@ -26,15 +29,18 @@ export class DeliverDebouncer {
   private readonly maxWaitMs: number;
   private readonly separator: string;
   private readonly flush: (targetId: string, mergedText: string) => Promise<void>;
+  private readonly log?: WarnSink;
 
   constructor(
     config: DeliverDebounceConfig | undefined,
     flush: (targetId: string, mergedText: string) => Promise<void>,
+    log?: WarnSink,
   ) {
     this.windowMs = config?.windowMs ?? DEFAULT_WINDOW_MS;
     this.maxWaitMs = config?.maxWaitMs ?? DEFAULT_MAX_WAIT_MS;
     this.separator = config?.separator ?? DEFAULT_SEPARATOR;
     this.flush = flush;
+    this.log = log;
   }
 
   get enabled(): boolean {
@@ -60,7 +66,7 @@ export class DeliverDebouncer {
       if (Date.now() - existing.firstAt >= this.maxWaitMs) {
         await this.doFlush(targetId);
       } else {
-        existing.timer = setTimeout(() => this.doFlush(targetId), this.windowMs);
+        existing.timer = setTimeout(() => this.scheduledFlush(targetId), this.windowMs);
       }
       return;
     }
@@ -70,13 +76,24 @@ export class DeliverDebouncer {
       const pending: PendingDeliver = {
         texts: [text],
         firstAt: Date.now(),
-        timer: setTimeout(() => this.doFlush(targetId), this.windowMs),
+        timer: setTimeout(() => this.scheduledFlush(targetId), this.windowMs),
         resolve,
       };
       this.pending.set(targetId, pending);
     });
   }
 
+  /**
+   * 定时器触发的 flush：promise 被 setTimeout 回调丢弃，失败若不就地
+   * 捕获会成为 unhandledRejection——记 WARN 封口（pending.resolve 在
+   * doFlush 的 finally 中仍会执行，入队方不会被悬挂）。
+   */
+  private scheduledFlush(targetId: string): void {
+    void this.doFlush(targetId).catch((err: unknown) => {
+      this.log?.warn?.(`[debounce] timer flush failed target=${targetId}: ${err instanceof Error ? err.message : String(err)}`);
+    });
+  }
+
   private async doFlush(targetId: string): Promise<void> {
     const pending = this.pending.get(targetId);
     if (!pending) return;

package/src/outbound-adapter.ts

@@ -28,6 +28,11 @@ import { isApprovalPayload } from './features/approval-utils.js';
 import { TEXT_CHUNK_LIMIT } from './constants.js';
 import { tryGetQQBotRuntime } from './runtime.js';
 import { getAdapters } from './adapter/resolve.js';
+import { createPluginLogger } from './utils/plugin-logger.js';
+
+// 契约入口（框架直发 / message 工具 / cron announce）无调用方 logger 可传，
+// 用模块级 logger 兜底——frameworkSink 每次调用时 resolve，register 早期自动降级 console
+const alog = createPluginLogger({ prefix: '[outbound]' });
 
 export type SendTextFn = (params: {
   to: string;
@@ -178,6 +183,8 @@ export function createQQBotOutboundAdapter(params: QQBotOutboundAdapterParams):
       if (canReply && replyToId && result.error) {
         rollback();
         log?.debug?.(`[${resolvedAccountId}] rollback quota: send failed`);
+      } else if (!canReply) {
+        log?.info?.(`[${resolvedAccountId}] [quota] fallback to proactive media send: quota exhausted or no msgId`);
       }
 
       return result;
@@ -287,6 +294,7 @@ export function createQQBotChannelOutbound(params: QQBotOutboundAdapterParams =
         accountId: ctx.accountId ?? undefined,
         replyToId: resolvePassiveFirstReplyToId(ctx.to, ctx.replyToId),
         account,
+        log: alog,
       });
       if (result.error) throw new Error(result.error);
       return { channel: 'qqbot', messageId: result.messageId ?? '' };
@@ -302,7 +310,8 @@ export function createQQBotChannelOutbound(params: QQBotOutboundAdapterParams =
         accountId: resolvedAccountId,
         replyToId: resolvePassiveFirstReplyToId(ctx.to, ctx.replyToId),
         account,
-        agentId: resolveMCPAgentId(ctx.to, resolvedAccountId, ctx.cfg),
+        agentId: resolveMCPAgentId(ctx.to, resolvedAccountId, ctx.cfg, alog),
+        log: alog,
       });
       if (result.error) throw new Error(result.error);
       return { channel: 'qqbot', messageId: result.messageId ?? '' };

package/src/setup/finalize.ts

@@ -49,13 +49,14 @@ async function linkViaQrCode(cfg: OpenClawConfig, _accountId: string, prompter:
   }
 }
 
-async function linkViaManual(cfg: OpenClawConfig, _accountId: string, prompter: Prompter): Promise<OpenClawConfig> {
+async function linkViaManual(cfg: OpenClawConfig, _accountId: string, prompter: Prompter, rt: Runtime): Promise<OpenClawConfig> {
   const appIdInput = await prompter.text({ message: '请输入 QQ Bot AppID', validate: (v) => v.trim() ? undefined : 'AppID 不能为空' });
   const secret = await prompter.text({ message: '请输入 QQ Bot AppSecret', validate: (v) => v.trim() ? undefined : 'AppSecret 不能为空' });
   const appId = appIdInput.trim();
   const key = resolveAccountKey(cfg, appId);
   let next = applyQQBotAccountConfig(cfg, key, { appId, clientSecret: secret.trim() });
   next = applyAccountDefaults(next, key);
+  rt.log(`手动绑定完成！账户: ${key} (AppID: ${appId})`);
   await prompter.note('✔ QQ Bot 配置完成！', 'QQ Bot');
   return next;
 }
@@ -82,7 +83,7 @@ export async function finalizeQQBotSetup(params: {
   if (mode === 'qr') {
     next = await linkViaQrCode(next, accountId, params.prompter, params.runtime);
   } else if (mode === 'manual') {
-    next = await linkViaManual(next, accountId, params.prompter);
+    next = await linkViaManual(next, accountId, params.prompter, params.runtime);
   } else if (!configured) {
     await params.prompter.note('您可以稍后运行以下命令重新配置：\n  openclaw channels add', 'QQ Bot');
   }

package/src/tools/platform.ts

@@ -2,6 +2,11 @@ import type { OpenClawPluginApi } from 'openclaw/plugin-sdk';
 import { listQQBotAccountIds } from '../config.js';
 import { getBotForAccount } from '../bot-instance.js';
 import { getRequestAccountId } from '../request-context.js';
+import { createPluginLogger } from '../utils/plugin-logger.js';
+
+// 工具 execute 无 logger 参数；request-context 活跃期间 enrichMeta
+// 自动带上 accountId/openId/messageId
+const toolLog = createPluginLogger({ prefix: '[tool:platform]' });
 
 // ========== JSON Schema ==========
 
@@ -111,6 +116,7 @@ export function registerPlatformTool(api: OpenClawPluginApi): void {
         try {
           const bot = getBotForAccount(accountId);
           const apiGateway = bot.api;
+          const startedAt = Date.now();
 
           let data: unknown;
           switch (method) {
@@ -131,10 +137,12 @@ export function registerPlatformTool(api: OpenClawPluginApi): void {
               break;
           }
 
+          toolLog.info(`${method} ${p.path} ok (${Date.now() - startedAt}ms)`, { accountId });
           return json(data);
         } catch (err: unknown) {
           const errMsg = err instanceof Error ? err.message : String(err);
           const apiErr = err as { httpStatus?: number; bizCode?: number; path?: string };
+          toolLog.warn(`${method} ${p.path} failed status=${apiErr.httpStatus ?? '?'} code=${apiErr.bizCode ?? '?'}: ${errMsg}`, { accountId });
           return json({
             error: errMsg,
             status: apiErr.httpStatus,

package/src/tools/secret-input.ts

@@ -22,8 +22,13 @@ import {
 } from '../features/secret-input-store.js';
 import { getRequestAccountId, getRequestTarget } from '../request-context.js';
 import { parseTarget } from '../outbound/target.js';
+import { createPluginLogger } from '../utils/plugin-logger.js';
 import type { InlineKeyboard, KeyboardButton } from '../types.js';
 
+// 工具 execute 无 logger 参数可传；request-context 在工具执行期间处于活跃，
+// 模块级 logger 的 enrichMeta 会自动带上 accountId/openId/messageId
+const toolLog = createPluginLogger({ prefix: '[tool:secret-input]' });
+
 // ========== JSON Schema ==========
 
 const SecretInputSchema = {
@@ -162,11 +167,14 @@ export function registerSecretInputTool(api: OpenClawPluginApi): void {
           );
         } catch (err) {
           cancelPendingSecretInput(accountId, parsed.targetId);
+          toolLog.error(`card send failed: ${err instanceof Error ? err.message : String(err)}`, { name, accountId });
           return json({
             error: `密钥输入卡片发送失败：${err instanceof Error ? err.message : String(err)}`,
           });
         }
 
+        toolLog.info(`card sent, pending registered name=${name} ttlMinutes=${DEFAULT_SECRET_INPUT_TTL_MS / 60_000}`);
+
         return json({
           ok: true,
           name,

package/src/types-plugin.ts

@@ -69,6 +69,7 @@ export interface TypingParams {
   replyToId: string;
   log?: {
     debug?: (message: string) => void;
+    warn?: (message: string) => void;
   };
 }
 

package/src/typing-lifecycle.ts

@@ -59,14 +59,17 @@ export async function startTypingWithRenewal(
 
   log?.debug?.(`[${accountId}] typing started: ${sessionKey}`);
 
-  const timer = setTimeout(async () => {
-    await handleTypingRenewal({
+  const timer = setTimeout(() => {
+    // promise 被 setTimeout 回调丢弃，失败不就地捕获会成为 unhandledRejection
+    void handleTypingRenewal({
       sessionKey,
       accountId,
       to,
       replyToId,
       log,
       sendTyping,
+    }).catch((err: unknown) => {
+      log?.warn?.(`[${accountId}] typing renewal error: ${err instanceof Error ? err.message : String(err)}`);
     });
   }, TYPING_RENEWAL_MS);
 
@@ -120,8 +123,10 @@ async function handleTypingRenewal(
   state.renewalCount += 1;
   log?.debug?.(`[${accountId}] typing renewed #${state.renewalCount}: ${sessionKey}`);
 
-  state.timer = setTimeout(async () => {
-    await handleTypingRenewal(params);
+  state.timer = setTimeout(() => {
+    void handleTypingRenewal(params).catch((err: unknown) => {
+      log?.warn?.(`[${accountId}] typing renewal error: ${err instanceof Error ? err.message : String(err)}`);
+    });
   }, TYPING_RENEWAL_MS);
 
   activeTypingSessions.set(sessionKey, state);

package/skills/qqbot-remind/SKILL.md

@@ -1,159 +0,0 @@
----
-name: qqbot-remind
-description: QQBot 定时提醒。支持一次性和周期性提醒的创建、查询、取消。当通过 QQ 通道通信且涉及提醒/定时任务时使用。
-metadata: {"openclaw":{"emoji":"⏰","requires":{"config":["channels.qqbot"]}}}
----
-
-# QQ Bot 定时提醒
-
-## ⚠️ 强制规则
-
-**当用户提到「提醒」「闹钟」「定时」「X分钟/小时后」「每天X点」「叫我」等任何涉及延时或定时的请求时，你必须调用工具，绝对不能只用自然语言回复说"好的，我会提醒你"！**
-
-你没有内存或后台线程，口头承诺"到时候提醒"是无效的——只有调用工具才能真正注册定时任务。
-
----
-
-## 推荐流程（优先使用 `qqbot_remind` 工具）
-
-**第一步**：调用 `qqbot_remind` 工具，传入简单参数：
-
-| 参数 | 说明 | 示例 |
-|------|------|------|
-| `action` | 操作类型 | `"add"` / `"list"` / `"remove"` |
-| `content` | 提醒内容 | `"喝水"` |
-| `to` | 目标地址（可选，系统自动获取，通常无需填写） | — |
-| `time` | 时间（相对时间或 cron 表达式） | `"5m"` / `"1h30m"` / `"0 8 * * *"` |
-| `jobId` | 任务 ID（仅 remove） | `"xxx"` |
-
-**第二步**：`qqbot_remind` 会返回 `cronParams`，你必须**立即**将 `cronParams` 的值**原样**作为参数调用 `cron` 工具。**禁止修改、省略或重组 `cronParams` 中的任何字段**（尤其是 `delivery` 对象中的 `accountId`）。
-
-**第三步**：根据 `cron` 工具的返回结果，回复用户。
-
-### 示例
-
-用户说："5分钟后提醒我喝水"
-
-1. 调用 `qqbot_remind`：`{ "action": "add", "content": "喝水", "time": "5m" }`
-2. 收到返回的 `cronParams` → 立即调用 `cron` 工具，参数为该 `cronParams`
-3. 回复用户：`⏰ 好的，5分钟后提醒你喝水~`
-
----
-
-## 备用方案（直接使用 `cron` 工具）
-
-> 仅当 `qqbot_remind` 工具不可用时使用以下方式。
-
-### 核心规则
-
-> **payload.kind 必须是 `"agentTurn"`，绝对不能用 `"systemEvent"`！**
-> `systemEvent` 只在 AI 会话内部注入文本，用户收不到 QQ 消息。
-
-**5 个不可更改字段**：
-
-| 字段 | 固定值 | 原因 |
-|------|--------|------|
-| `payload.kind` | `"agentTurn"` | `systemEvent` 不会发 QQ 消息 |
-| `delivery.mode` | `"announce"` | 投递模式 |
-| `delivery.channel` | `"qqbot"` | QQ 通道标识 |
-| `delivery.to` | 用户 openid | 从 `To` 字段获取 |
-| `sessionTarget` | `"isolated"` | 隔离会话避免污染 |
-
-> `delivery.accountId` 必须填写当前会话的账户 ID（如果已知），以确保多账户场景下消息通过正确的机器人账户发送。
-
-> `schedule.atMs` 必须是**绝对毫秒时间戳**（如 `1770733800000`），不支持 `"5m"` 等相对字符串。
-> 计算方式：`当前时间戳ms + 延迟毫秒`。
-
-### 一次性提醒（schedule.kind = "at"）
-
-```json
-{
-  "action": "add",
-  "job": {
-    "name": "{任务名}",
-    "schedule": { "kind": "at", "atMs": "{当前时间戳ms + N*60000}" },
-    "sessionTarget": "isolated",
-    "wakeMode": "now",
-    "deleteAfterRun": true,
-    "payload": {
-      "kind": "agentTurn",
-      "message": "你是一个暖心的提醒助手。请用温暖、有趣的方式提醒用户：{提醒内容}。要求：(1) 不要回复HEARTBEAT_OK (2) 不要解释你是谁 (3) 直接输出一条暖心的提醒消息 (4) 可以加一句简短的鸡汤或关怀的话 (5) 控制在2-3句话以内 (6) 用emoji点缀"
-    },
-    "delivery": {
-      "mode": "announce",
-      "channel": "qqbot",
-      "to": "{openid}",
-      "accountId": "{accountId}"
-    }
-  }
-}
-```
-
-### 周期提醒（schedule.kind = "cron"）
-
-```json
-{
-  "action": "add",
-  "job": {
-    "name": "{任务名}",
-    "schedule": { "kind": "cron", "expr": "0 8 * * *", "tz": "Asia/Shanghai" },
-    "sessionTarget": "isolated",
-    "wakeMode": "now",
-    "payload": {
-      "kind": "agentTurn",
-      "message": "你是一个暖心的提醒助手。请用温暖、有趣的方式提醒用户：{提醒内容}。要求：(1) 不要回复HEARTBEAT_OK (2) 不要解释你是谁 (3) 直接输出一条暖心的提醒消息 (4) 可以加一句简短的鸡汤或关怀的话 (5) 控制在2-3句话以内 (6) 用emoji点缀"
-    },
-    "delivery": {
-      "mode": "announce",
-      "channel": "qqbot",
-      "to": "{openid}",
-      "accountId": "{accountId}"
-    }
-  }
-}
-```
-
-> 周期任务**不加** `deleteAfterRun`。群聊 `to` 格式为 `"qqbot:group:{group_openid}"`。
-
----
-
-## cron 表达式速查
-
-| 场景 | expr |
-|------|------|
-| 每天早上8点 | `"0 8 * * *"` |
-| 每天晚上10点 | `"0 22 * * *"` |
-| 工作日早上9点 | `"0 9 * * 1-5"` |
-| 每周一早上9点 | `"0 9 * * 1"` |
-| 每周末上午10点 | `"0 10 * * 0,6"` |
-| 每小时整点 | `"0 * * * *"` |
-
-> 周期提醒必须加 `"tz": "Asia/Shanghai"`。
-
----
-
-## AI 决策指南
-
-| 用户说法 | action | time 格式 |
-|----------|--------|-----------|
-| "5分钟后提醒我喝水" | `add` | `"5m"` |
-| "1小时后提醒开会" | `add` | `"1h"` |
-| "每天8点提醒我打卡" | `add` | `"0 8 * * *"` |
-| "工作日早上9点提醒" | `add` | `"0 9 * * 1-5"` |
-| "我有哪些提醒" | `list` | — |
-| "取消喝水提醒" | `remove` | — |
-| "修改提醒时间" | `remove` → `add` | — |
-| "提醒我"（无时间） | **需追问** | — |
-
-纯相对时间（"5分钟后"、"1小时后"）可直接计算，无需确认。时间模糊或缺失时需追问。
-
----
-
-## 回复模板
-
-- 一次性：`⏰ 好的，{时间}后提醒你{内容}~`
-- 周期：`⏰ 收到，{周期}提醒你{内容}~`
-- 查询无结果：`📋 目前没有提醒哦~ 说"5分钟后提醒我xxx"试试？`
-- 删除成功：`✅ 已取消"{名称}"`
-
-openclaw cron add \ --name "下班提醒" \ --at "2026-03-26T21:42:31+08:00" \ --message "test" \ --to …``