@tencent-connect/openclaw-qqbot 1.6.4 → 1.6.5-alpha.0

package/src/admin-resolver.ts

@@ -26,48 +26,90 @@ export interface AdminResolverContext {
 
 // ---- 文件路径 ----
 
-function getAdminMarkerFile(accountId: string): string {
+function safeName(id: string): string {
+  return id.replace(/[^a-zA-Z0-9._-]/g, "_");
+}
+
+/** 新版 admin 文件路径（按 accountId + appId 区分） */
+function getAdminMarkerFile(accountId: string, appId: string): string {
+  return path.join(getQQBotDataDir("data"), `admin-${safeName(accountId)}-${safeName(appId)}.json`);
+}
+
+/** 旧版 admin 文件路径（仅按 accountId 区分，用于迁移兼容） */
+function getLegacyAdminMarkerFile(accountId: string): string {
   return path.join(getQQBotDataDir("data"), `admin-${accountId}.json`);
 }
 
 function getUpgradeGreetingTargetFile(accountId: string, appId: string): string {
-  const safeAccountId = accountId.replace(/[^a-zA-Z0-9._-]/g, "_");
-  const safeAppId = appId.replace(/[^a-zA-Z0-9._-]/g, "_");
-  return path.join(getQQBotDataDir("data"), `upgrade-greeting-target-${safeAccountId}-${safeAppId}.json`);
+  return path.join(getQQBotDataDir("data"), `upgrade-greeting-target-${safeName(accountId)}-${safeName(appId)}.json`);
 }
 
 // ---- 管理员 openid 持久化 ----
 
-export function loadAdminOpenId(accountId: string): string | undefined {
+/**
+ * 读取 admin openid（按 accountId + appId 区分）
+ * 兼容策略：新路径优先 → fallback 旧路径 → 自动迁移
+ */
+export function loadAdminOpenId(accountId: string, appId: string): string | undefined {
   try {
-    const file = getAdminMarkerFile(accountId);
-    if (fs.existsSync(file)) {
-      const data = JSON.parse(fs.readFileSync(file, "utf8"));
+    // 1. 先尝试新版路径
+    const newFile = getAdminMarkerFile(accountId, appId);
+    if (fs.existsSync(newFile)) {
+      const data = JSON.parse(fs.readFileSync(newFile, "utf8"));
       if (data.openid) return data.openid;
     }
+
+    // 2. fallback 旧版路径（仅按 accountId）
+    const legacyFile = getLegacyAdminMarkerFile(accountId);
+    if (fs.existsSync(legacyFile)) {
+      const data = JSON.parse(fs.readFileSync(legacyFile, "utf8"));
+      if (data.openid) {
+        // 自动迁移：写到新路径，删除旧文件
+        saveAdminOpenId(accountId, appId, data.openid);
+        try { fs.unlinkSync(legacyFile); } catch { /* ignore */ }
+        return data.openid;
+      }
+    }
   } catch { /* 文件损坏视为无 */ }
   return undefined;
 }
 
-export function saveAdminOpenId(accountId: string, openid: string): void {
+export function saveAdminOpenId(accountId: string, appId: string, openid: string): void {
   try {
-    fs.writeFileSync(getAdminMarkerFile(accountId), JSON.stringify({ openid, savedAt: new Date().toISOString() }));
+    fs.writeFileSync(
+      getAdminMarkerFile(accountId, appId),
+      JSON.stringify({ accountId, appId, openid, savedAt: new Date().toISOString() }),
+    );
   } catch { /* ignore */ }
 }
 
 // ---- 升级问候目标 ----
 
-export function loadUpgradeGreetingTargetOpenId(accountId: string, appId: string): string | undefined {
+export function loadUpgradeGreetingTargetOpenId(accountId: string, appId: string, log?: { info: (msg: string) => void }): string | undefined {
   try {
     const file = getUpgradeGreetingTargetFile(accountId, appId);
     if (fs.existsSync(file)) {
       const data = JSON.parse(fs.readFileSync(file, "utf8")) as { accountId?: string; appId?: string; openid?: string };
-      if (!data.openid) return undefined;
-      if (data.appId && data.appId !== appId) return undefined;
-      if (data.accountId && data.accountId !== accountId) return undefined;
+      if (!data.openid) {
+        log?.info(`[qqbot:${accountId}] upgrade-greeting-target file found but openid is empty`);
+        return undefined;
+      }
+      if (data.appId && data.appId !== appId) {
+        log?.info(`[qqbot:${accountId}] upgrade-greeting-target appId mismatch: file=${data.appId}, current=${appId}`);
+        return undefined;
+      }
+      if (data.accountId && data.accountId !== accountId) {
+        log?.info(`[qqbot:${accountId}] upgrade-greeting-target accountId mismatch: file=${data.accountId}, current=${accountId}`);
+        return undefined;
+      }
+      log?.info(`[qqbot:${accountId}] upgrade-greeting-target loaded: openid=${data.openid}`);
       return data.openid;
+    } else {
+      log?.info(`[qqbot:${accountId}] upgrade-greeting-target file not found: ${file}`);
     }
-  } catch { /* 文件损坏视为无 */ }
+  } catch (err) {
+    log?.info(`[qqbot:${accountId}] upgrade-greeting-target file read error: ${err}`);
+  }
   return undefined;
 }
 
@@ -84,15 +126,15 @@ export function clearUpgradeGreetingTargetOpenId(accountId: string, appId: strin
 
 /**
  * 解析管理员 openid：
- * 1. 优先读持久化文件（稳定）
+ * 1. 优先读持久化文件（按 accountId + appId 区分）
  * 2. fallback 取第一个私聊用户，并写入文件锁定
  */
-export function resolveAdminOpenId(ctx: Pick<AdminResolverContext, "accountId" | "log">): string | undefined {
-  const saved = loadAdminOpenId(ctx.accountId);
+export function resolveAdminOpenId(ctx: Pick<AdminResolverContext, "accountId" | "appId" | "log">): string | undefined {
+  const saved = loadAdminOpenId(ctx.accountId, ctx.appId);
   if (saved) return saved;
   const first = listKnownUsers({ accountId: ctx.accountId, type: "c2c", sortBy: "firstSeenAt", sortOrder: "asc", limit: 1 })[0]?.openid;
   if (first) {
-    saveAdminOpenId(ctx.accountId, first);
+    saveAdminOpenId(ctx.accountId, ctx.appId, first);
     ctx.log?.info(`[qqbot:${ctx.accountId}] Auto-detected admin openid: ${first} (persisted)`);
   }
   return first;
@@ -100,19 +142,19 @@ export function resolveAdminOpenId(ctx: Pick<AdminResolverContext, "accountId" |
 
 // ---- 启动问候语 ----
 
-/** 异步发送启动问候语（仅发给管理员） */
+/** 异步发送启动问候语（优先发给升级触发者，fallback 发给管理员） */
 export function sendStartupGreetings(ctx: AdminResolverContext, trigger: "READY" | "RESUMED"): void {
   (async () => {
-    const plan = getStartupGreetingPlan();
+    const plan = getStartupGreetingPlan(ctx.accountId, ctx.appId);
     if (!plan.shouldSend || !plan.greeting) {
       ctx.log?.info(`[qqbot:${ctx.accountId}] Skipping startup greeting (${plan.reason ?? "debounced"}, trigger=${trigger})`);
       return;
     }
 
-    const upgradeTargetOpenId = loadUpgradeGreetingTargetOpenId(ctx.accountId, ctx.appId);
+    const upgradeTargetOpenId = loadUpgradeGreetingTargetOpenId(ctx.accountId, ctx.appId, ctx.log);
     const targetOpenId = upgradeTargetOpenId || resolveAdminOpenId(ctx);
     if (!targetOpenId) {
-      markStartupGreetingFailed(plan.version, "no-admin");
+      markStartupGreetingFailed(ctx.accountId, ctx.appId, plan.version, "no-admin");
       ctx.log?.info(`[qqbot:${ctx.accountId}] Skipping startup greeting (no admin or known user)`);
       return;
     }
@@ -126,14 +168,14 @@ export function sendStartupGreetings(ctx: AdminResolverContext, trigger: "READY"
         sendProactiveC2CMessage(token, targetOpenId, plan.greeting),
         new Promise((_, reject) => setTimeout(() => reject(new Error("Startup greeting send timeout (10s)")), GREETING_TIMEOUT_MS)),
       ]);
-      markStartupGreetingSent(plan.version);
+      markStartupGreetingSent(ctx.accountId, ctx.appId, plan.version);
       if (upgradeTargetOpenId) {
         clearUpgradeGreetingTargetOpenId(ctx.accountId, ctx.appId);
       }
       ctx.log?.info(`[qqbot:${ctx.accountId}] Sent startup greeting to ${receiverType}: ${targetOpenId}`);
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
-      markStartupGreetingFailed(plan.version, message);
+      markStartupGreetingFailed(ctx.accountId, ctx.appId, plan.version, message);
       ctx.log?.error(`[qqbot:${ctx.accountId}] Failed to send startup greeting: ${message}`);
     }
   })();

package/src/deliver-debounce.ts

@@ -0,0 +1,229 @@
+/**
+ * 出站消息合并回复（Deliver Debounce）模块
+ *
+ * 解决的问题：
+ * 当 openclaw 框架层的 embedded agent 超时或快速连续产生多次 deliver 时，
+ * 用户会在短时间内收到大量碎片消息（消息轰炸）。
+ *
+ * 解决方案：
+ * 在 deliver 回调和实际发送之间加入 debounce 层。
+ * 短时间内（windowMs）连续到达的多条纯文本 deliver 会被合并为一条消息发送。
+ * 含媒体的 deliver 会立即 flush 已缓冲的文本并正常处理媒体。
+ */
+
+import type { DeliverDebounceConfig } from "./types.js";
+
+// ============ 默认值 ============
+
+const DEFAULT_WINDOW_MS = 1500;
+const DEFAULT_MAX_WAIT_MS = 8000;
+const DEFAULT_SEPARATOR = "\n\n---\n\n";
+
+// ============ 类型定义 ============
+
+export interface DeliverPayload {
+  text?: string;
+  mediaUrls?: string[];
+  mediaUrl?: string;
+}
+
+export interface DeliverInfo {
+  kind: string;
+}
+
+/** 实际执行发送的回调 */
+export type DeliverExecutor = (payload: DeliverPayload, info: DeliverInfo) => Promise<void>;
+
+// ============ DeliverDebouncer 类 ============
+
+export class DeliverDebouncer {
+  private readonly windowMs: number;
+  private readonly maxWaitMs: number;
+  private readonly separator: string;
+  private readonly executor: DeliverExecutor;
+  private readonly log?: {
+    info: (msg: string) => void;
+    error: (msg: string) => void;
+  };
+  private readonly prefix: string;
+
+  /** 缓冲中的文本片段 */
+  private bufferedTexts: string[] = [];
+  /** 缓冲中最后一次 deliver 的 info（用于 flush 时传递 kind） */
+  private lastInfo: DeliverInfo | null = null;
+  /** 缓冲中最后一次 deliver 的 payload（非文本字段，如 mediaUrls） */
+  private lastPayload: DeliverPayload | null = null;
+  /** debounce 定时器 */
+  private debounceTimer: ReturnType<typeof setTimeout> | null = null;
+  /** 最大等待定时器（从第一条 deliver 开始计算） */
+  private maxWaitTimer: ReturnType<typeof setTimeout> | null = null;
+  /** 是否正在 flush */
+  private flushing = false;
+  /** 已销毁标记 */
+  private disposed = false;
+
+  constructor(
+    config: DeliverDebounceConfig | undefined,
+    executor: DeliverExecutor,
+    log?: { info: (msg: string) => void; error: (msg: string) => void },
+    prefix = "[debounce]",
+  ) {
+    this.windowMs = config?.windowMs ?? DEFAULT_WINDOW_MS;
+    this.maxWaitMs = config?.maxWaitMs ?? DEFAULT_MAX_WAIT_MS;
+    this.separator = config?.separator ?? DEFAULT_SEPARATOR;
+    this.executor = executor;
+    this.log = log;
+    this.prefix = prefix;
+  }
+
+  /**
+   * 接收一次 deliver 调用。
+   * - 纯文本 deliver → 缓冲并设置 debounce 定时器
+   * - 含媒体 deliver → 先 flush 已缓冲文本，再直接执行当前 deliver
+   */
+  async deliver(payload: DeliverPayload, info: DeliverInfo): Promise<void> {
+    if (this.disposed) return;
+
+    const hasMedia = Boolean(
+      (payload.mediaUrls && payload.mediaUrls.length > 0) || payload.mediaUrl,
+    );
+    const text = (payload.text ?? "").trim();
+
+    // 含媒体的 deliver：立即 flush 缓冲 + 直接执行
+    if (hasMedia) {
+      this.log?.info(`${this.prefix} Media deliver detected, flushing ${this.bufferedTexts.length} buffered text(s) first`);
+      await this.flush();
+      await this.executor(payload, info);
+      return;
+    }
+
+    // 空文本 deliver：直接透传（不缓冲）
+    if (!text) {
+      await this.executor(payload, info);
+      return;
+    }
+
+    // 纯文本 deliver：缓冲
+    this.bufferedTexts.push(text);
+    this.lastInfo = info;
+    this.lastPayload = payload;
+
+    this.log?.info(
+      `${this.prefix} Buffered text #${this.bufferedTexts.length} (${text.length} chars), window=${this.windowMs}ms`,
+    );
+
+    // 重置 debounce 定时器
+    if (this.debounceTimer) {
+      clearTimeout(this.debounceTimer);
+    }
+    this.debounceTimer = setTimeout(() => {
+      this.flush().catch((err) => {
+        this.log?.error(`${this.prefix} Flush error (debounce timer): ${err}`);
+      });
+    }, this.windowMs);
+
+    // 首次缓冲时启动最大等待定时器
+    if (this.bufferedTexts.length === 1) {
+      if (this.maxWaitTimer) {
+        clearTimeout(this.maxWaitTimer);
+      }
+      this.maxWaitTimer = setTimeout(() => {
+        this.log?.info(`${this.prefix} Max wait (${this.maxWaitMs}ms) reached, force flushing`);
+        this.flush().catch((err) => {
+          this.log?.error(`${this.prefix} Flush error (max wait timer): ${err}`);
+        });
+      }, this.maxWaitMs);
+    }
+  }
+
+  /**
+   * 将缓冲中的文本合并为一条消息发送
+   */
+  async flush(): Promise<void> {
+    if (this.flushing || this.bufferedTexts.length === 0) return;
+    this.flushing = true;
+
+    // 清除定时器
+    if (this.debounceTimer) {
+      clearTimeout(this.debounceTimer);
+      this.debounceTimer = null;
+    }
+    if (this.maxWaitTimer) {
+      clearTimeout(this.maxWaitTimer);
+      this.maxWaitTimer = null;
+    }
+
+    // 取出缓冲
+    const texts = this.bufferedTexts;
+    const info = this.lastInfo!;
+    const lastPayload = this.lastPayload!;
+    this.bufferedTexts = [];
+    this.lastInfo = null;
+    this.lastPayload = null;
+
+    try {
+      if (texts.length === 1) {
+        // 只有一条，直接透传原始 payload
+        this.log?.info(`${this.prefix} Flushing single buffered text (${texts[0].length} chars)`);
+        await this.executor({ ...lastPayload, text: texts[0] }, info);
+      } else {
+        // 多条合并
+        const merged = texts.join(this.separator);
+        this.log?.info(
+          `${this.prefix} Merged ${texts.length} buffered texts into one (${merged.length} chars)`,
+        );
+        await this.executor({ ...lastPayload, text: merged }, info);
+      }
+    } finally {
+      this.flushing = false;
+    }
+  }
+
+  /**
+   * 销毁：flush 剩余缓冲并清除定时器
+   */
+  async dispose(): Promise<void> {
+    this.disposed = true;
+    if (this.debounceTimer) {
+      clearTimeout(this.debounceTimer);
+      this.debounceTimer = null;
+    }
+    if (this.maxWaitTimer) {
+      clearTimeout(this.maxWaitTimer);
+      this.maxWaitTimer = null;
+    }
+    // flush 剩余
+    if (this.bufferedTexts.length > 0) {
+      this.flushing = false; // 确保 flush 能执行
+      await this.flush();
+    }
+  }
+
+  /** 当前是否有缓冲中的文本 */
+  get hasPending(): boolean {
+    return this.bufferedTexts.length > 0;
+  }
+
+  /** 缓冲中的文本数量 */
+  get pendingCount(): number {
+    return this.bufferedTexts.length;
+  }
+}
+
+// ============ 工厂函数 ============
+
+/**
+ * 根据配置创建 debouncer 或返回 null（禁用时）
+ */
+export function createDeliverDebouncer(
+  config: DeliverDebounceConfig | undefined,
+  executor: DeliverExecutor,
+  log?: { info: (msg: string) => void; error: (msg: string) => void },
+  prefix?: string,
+): DeliverDebouncer | null {
+  // 未配置时默认启用
+  if (config?.enabled === false) {
+    return null;
+  }
+  return new DeliverDebouncer(config, executor, log, prefix);
+}

package/src/gateway.ts

@@ -20,6 +20,8 @@ import { sendStartupGreetings, type AdminResolverContext } from "./admin-resolve
 import { sendWithTokenRetry, sendErrorToTarget, handleStructuredPayload, type ReplyContext, type MessageTarget } from "./reply-dispatcher.js";
 import { TypingKeepAlive, TYPING_INPUT_SECOND } from "./typing-keepalive.js";
 import { parseAndSendMediaTags, sendPlainReply, type DeliverEventContext, type DeliverAccountContext } from "./outbound-deliver.js";
+import { createDeliverDebouncer, type DeliverDebouncer } from "./deliver-debounce.js";
+import { runWithRequestContext } from "./request-context.js";
 
 // QQ Bot intents - 按权限级别分组
 const INTENTS = {
@@ -86,9 +88,10 @@ async function ensureImageServer(log?: GatewayContext["log"], publicBaseUrl?: st
   }
 }
 
-// 模块级变量：进程生命周期内只有首次为 true
+// 模块级变量：per-account 首次 READY 跟踪
 // 区分 gateway restart（进程重启）和 health-monitor 断线重连
-let isFirstReadyGlobal = true;
+// 每个 account 首次 READY/RESUMED 时从 Set 中移除，之后不再发送问候语
+const _pendingFirstReady = new Set<string>();
 
 /**
  * 启动 Gateway WebSocket 连接（带自动重连）
@@ -186,8 +189,8 @@ export async function startGateway(ctx: GatewayContext): Promise<void> {
   let isConnecting = false; // 防止并发连接
   let reconnectTimer: ReturnType<typeof setTimeout> | null = null; // 重连定时器
   let shouldRefreshToken = false; // 下次连接是否需要刷新 token
-  // 使用模块级 isFirstReadyGlobal，确保只有进程级重启才发送问候语
-  // health-monitor 重连不会重新初始化为 true
+  // 标记此 account 为待发问候（进程重启时 Set 里已有，断线重连不会重新加入）
+  _pendingFirstReady.add(account.accountId);
 
   const adminCtx: AdminResolverContext = { accountId: account.accountId, appId: account.appId, clientSecret: account.clientSecret, log };
 
@@ -621,7 +624,7 @@ export async function startGateway(ctx: GatewayContext): Promise<void> {
 
         // ============ 构建 contextInfo（静态/动态分离） ============
         // 设计原则（参考 Telegram/Discord 做法）：
-        //   - 静态指引：每条消息不变的内容（场景锚定、投递地址、能力说明），
+        //   - 静态指引：每条消息不变的能力声明，
         //     注入 systemPrompts 前部，session 中虽重复出现但 AI 会自动降权，
         //     且保证长 session 窗口截断后仍可见。
         //   - 动态标签：每条消息变化的数据（时间、附件、ASR），
@@ -629,17 +632,17 @@ export async function startGateway(ctx: GatewayContext): Promise<void> {
 
         // --- 静态指引（仅注入框架信封未覆盖的 QQBot 特有信息） ---
         // 框架 formatInboundEnvelope 已提供：平台标识、发送者、时间戳
-        // 这里只补充 QQBot 独有的：投递地址（cron skill 需要）
-        const staticParts: string[] = [
-          `[QQBot] to=${qualifiedTarget}`,
-        ];
+        // 投递地址通过 AsyncLocalStorage 请求上下文传递给 remind 工具，无需在 agentBody 中暴露
+        const staticParts: string[] = [];
         // TTS 能力声明：仅在启用时告知 AI 可以发语音（媒体标签用法由 qqbot-media SKILL.md 提供）
         // STT 无需声明：转写结果已在动态上下文的 ASR 行中，AI 自然可见
         if (hasTTS) staticParts.push("语音合成已启用");
-        const staticInstruction = staticParts.join(" | ");
 
-        // 静态指引作为 systemPrompts 的首项注入
-        systemPrompts.unshift(staticInstruction);
+        // 仅在有静态指引时注入 systemPrompts
+        if (staticParts.length > 0) {
+          const staticInstruction = staticParts.join(" | ");
+          systemPrompts.unshift(staticInstruction);
+        }
 
         // --- 动态上下文（仅框架信封未覆盖的附件信息） ---
         const dynLines: string[] = [];
@@ -757,6 +760,9 @@ export async function startGateway(ctx: GatewayContext): Promise<void> {
         // 发送错误提示的辅助函数
         const sendErrorMessage = (errorText: string) => sendErrorToTarget(replyCtx, errorText);
 
+        // 使用 AsyncLocalStorage 建立请求级上下文，作用域内所有异步代码
+        // （包括 AI agent 调用、tool execute）都能安全获取当前会话信息，无并发竞态。
+        await runWithRequestContext({ target: qualifiedTarget }, async () => {
         try {
           const messagesConfig = pluginRuntime.channel.reply.resolveEffectiveMessagesConfig(cfg, route.agentId);
 
@@ -774,6 +780,10 @@ export async function startGateway(ctx: GatewayContext): Promise<void> {
           let timeoutId: ReturnType<typeof setTimeout> | null = null;
           let toolOnlyTimeoutId: ReturnType<typeof setTimeout> | null = null;
 
+          // ============ Deliver Debouncer：合并短时间内连续到达的 block deliver ============
+          const debounceConfig = account.config?.deliverDebounce;
+          let debouncer: DeliverDebouncer | null = null as DeliverDebouncer | null;
+
           // tool-only 兜底：转发工具产生的实际内容（媒体/文本），而非生硬的提示语
           const sendToolFallback = async (): Promise<void> => {
             // 优先发送工具产出的媒体文件（TTS 语音、生成图片等）
@@ -924,63 +934,82 @@ export async function startGateway(ctx: GatewayContext): Promise<void> {
                   log?.info(`[qqbot:${account.accountId}] Block deliver after ${toolDeliverCount} tool deliver(s)`);
                 }
 
-                // ============ 引用回复 ============
-                const quoteRef = event.msgIdx;
-                let quoteRefUsed = false;
-                const consumeQuoteRef = (): string | undefined => {
-                  if (quoteRef && !quoteRefUsed) {
-                    quoteRefUsed = true;
-                    return quoteRef;
+                // ============ 实际发送逻辑（可被 debouncer 包裹） ============
+                const executeDeliver = async (deliverPayload: { text?: string; mediaUrls?: string[]; mediaUrl?: string }, _deliverInfo: { kind: string }) => {
+                  // ============ 引用回复 ============
+                  const quoteRef = event.msgIdx;
+                  let quoteRefUsed = false;
+                  const consumeQuoteRef = (): string | undefined => {
+                    if (quoteRef && !quoteRefUsed) {
+                      quoteRefUsed = true;
+                      return quoteRef;
+                    }
+                    return undefined;
+                  };
+
+                  let replyText = deliverPayload.text ?? "";
+
+                  // ============ 媒体标签解析 + 发送 ============
+                  const deliverEvent: DeliverEventContext = {
+                    type: event.type,
+                    senderId: event.senderId,
+                    messageId: event.messageId,
+                    channelId: event.channelId,
+                    groupOpenid: event.groupOpenid,
+                    msgIdx: event.msgIdx,
+                  };
+                  const deliverActx: DeliverAccountContext = { account, qualifiedTarget, log };
+
+                  const mediaResult = await parseAndSendMediaTags(
+                    replyText, deliverEvent, deliverActx, sendWithRetry, consumeQuoteRef,
+                  );
+                  if (mediaResult.handled) {
+                    pluginRuntime.channel.activity.record({
+                      channel: "qqbot",
+                      accountId: account.accountId,
+                      direction: "outbound",
+                    });
+                    return;
                   }
-                  return undefined;
-                };
+                  replyText = mediaResult.normalizedText;
 
-                let replyText = payload.text ?? "";
+                  // ============ 结构化载荷检测与分发 ============
+                  const recordOutboundActivity = () => pluginRuntime.channel.activity.record({
+                    channel: "qqbot",
+                    accountId: account.accountId,
+                    direction: "outbound",
+                  });
+                  const handled = await handleStructuredPayload(replyCtx, replyText, recordOutboundActivity);
+                  if (handled) return;
 
-                // ============ 媒体标签解析 + 发送 ============
-                const deliverEvent: DeliverEventContext = {
-                  type: event.type,
-                  senderId: event.senderId,
-                  messageId: event.messageId,
-                  channelId: event.channelId,
-                  groupOpenid: event.groupOpenid,
-                  msgIdx: event.msgIdx,
-                };
-                const deliverActx: DeliverAccountContext = { account, qualifiedTarget, log };
+                  // ============ 非结构化消息发送 ============
+                  await sendPlainReply(
+                    deliverPayload, replyText, deliverEvent, deliverActx,
+                    sendWithRetry, consumeQuoteRef, toolMediaUrls,
+                  );
 
-                const mediaResult = await parseAndSendMediaTags(
-                  replyText, deliverEvent, deliverActx, sendWithRetry, consumeQuoteRef,
-                );
-                if (mediaResult.handled) {
                   pluginRuntime.channel.activity.record({
                     channel: "qqbot",
                     accountId: account.accountId,
                     direction: "outbound",
                   });
-                  return;
-                }
-                replyText = mediaResult.normalizedText;
-
-                // ============ 结构化载荷检测与分发 ============
-                const recordOutboundActivity = () => pluginRuntime.channel.activity.record({
-                  channel: "qqbot",
-                  accountId: account.accountId,
-                  direction: "outbound",
-                });
-                const handled = await handleStructuredPayload(replyCtx, replyText, recordOutboundActivity);
-                if (handled) return;
+                };
 
-                // ============ 非结构化消息发送 ============
-                await sendPlainReply(
-                  payload, replyText, deliverEvent, deliverActx,
-                  sendWithRetry, consumeQuoteRef, toolMediaUrls,
-                );
+                // ============ Debounce 合并回复 ============
+                if (!debouncer) {
+                  debouncer = createDeliverDebouncer(
+                    debounceConfig,
+                    executeDeliver,
+                    log,
+                    `[qqbot:${account.accountId}:debounce]`,
+                  );
+                }
 
-                pluginRuntime.channel.activity.record({
-                  channel: "qqbot",
-                  accountId: account.accountId,
-                  direction: "outbound",
-                });
+                if (debouncer) {
+                  await debouncer.deliver(payload, info);
+                } else {
+                  await executeDeliver(payload, info);
+                }
               },
               onError: async (err: unknown) => {
                 log?.error(`[qqbot:${account.accountId}] Dispatch error: ${err}`);
@@ -1026,6 +1055,11 @@ export async function startGateway(ctx: GatewayContext): Promise<void> {
               log?.error(`[qqbot:${account.accountId}] Dispatch completed with ${toolDeliverCount} tool deliver(s) but no block deliver, sending fallback`);
               await sendToolFallback();
             }
+            // 销毁 debouncer，flush 剩余缓冲的文本
+            if (debouncer) {
+              await debouncer.dispose();
+              debouncer = null;
+            }
           }
         } catch (err) {
           log?.error(`[qqbot:${account.accountId}] Message processing failed: ${err}`);
@@ -1033,6 +1067,7 @@ export async function startGateway(ctx: GatewayContext): Promise<void> {
           // 无论成功/失败/超时，都停止输入状态续期
           typing.keepAlive?.stop();
         }
+        }); // end runWithRequestContext
       };
 
       ws.on("open", () => {
@@ -1131,18 +1166,18 @@ export async function startGateway(ctx: GatewayContext): Promise<void> {
 
                 // 仅 startGateway 后的首次 READY 才发送上线通知
                 // ws 断线重连（resume 失败后重新 Identify）产生的 READY 不发送
-                if (!isFirstReadyGlobal) {
+                if (!_pendingFirstReady.has(account.accountId)) {
                   log?.info(`[qqbot:${account.accountId}] Skipping startup greeting (reconnect READY, not first startup)`);
                 } else {
-                  isFirstReadyGlobal = false;
+                  _pendingFirstReady.delete(account.accountId);
                   sendStartupGreetings(adminCtx, "READY");
                 } // end isFirstReady
               } else if (t === "RESUMED") {
                 log?.info(`[qqbot:${account.accountId}] Session resumed`);
                 onReady?.(d); // 通知框架连接已恢复，避免 health-monitor 误判 disconnected
                 // RESUMED 也属于首次启动（gateway restart 通常走 resume）
-                if (isFirstReadyGlobal) {
-                  isFirstReadyGlobal = false;
+                if (_pendingFirstReady.has(account.accountId)) {
+                  _pendingFirstReady.delete(account.accountId);
                   sendStartupGreetings(adminCtx, "RESUMED");
                 }
                 // P1-2: 更新 Session 连接时间