@ryantest/openclaw-qqbot 0.0.2 → 1.6.6-alpha.0

package/dist/src/gateway.js

@@ -18,6 +18,9 @@ import { sendStartupGreetings } from "./admin-resolver.js";
 import { sendWithTokenRetry, sendErrorToTarget, handleStructuredPayload } from "./reply-dispatcher.js";
 import { TypingKeepAlive, TYPING_INPUT_SECOND } from "./typing-keepalive.js";
 import { parseAndSendMediaTags, sendPlainReply } from "./outbound-deliver.js";
+import { createDeliverDebouncer } from "./deliver-debounce.js";
+import { runWithRequestContext } from "./request-context.js";
+import { StreamingController, shouldUseStreaming } from "./streaming.js";
 // QQ Bot intents - 按权限级别分组
 const INTENTS = {
     // 基础权限（默认有）
@@ -65,9 +68,10 @@ async function ensureImageServer(log, publicBaseUrl) {
         return null;
     }
 }
-// 模块级变量：进程生命周期内只有首次为 true
+// 模块级变量：per-account 首次 READY 跟踪
 // 区分 gateway restart（进程重启）和 health-monitor 断线重连
-let isFirstReadyGlobal = true;
+// 每个 account 首次 READY/RESUMED 时从 Set 中移除，之后不再发送问候语
+const _pendingFirstReady = new Set();
 /**
  * 启动 Gateway WebSocket 连接（带自动重连）
  * 支持流式消息发送
@@ -84,6 +88,22 @@ export async function startGateway(ctx) {
             log?.info(`[qqbot:${account.accountId}] ${w}`);
         }
     }
+    // 预检 openclaw runtime 模块是否可正常解析（兼容性诊断）
+    // openclaw 3.23+ 存在 plugin-sdk/root-alias.cjs 回归 bug，
+    // 内置插件（qwen-portal-auth 等）全部加载失败，导致 AI agent 调用返回
+    // "Unable to resolve plugin runtime module"。提前检测并告警。
+    try {
+        const pluginRuntime = getQQBotRuntime();
+        if (pluginRuntime?.channel?.reply?.dispatchReplyWithBufferedBlockDispatcher) {
+            log?.info(`[qqbot:${account.accountId}] Runtime module preflight: OK`);
+        }
+        else {
+            log?.error(`[qqbot:${account.accountId}] ⚠️ Runtime preflight: dispatchReply API 不可用，AI 消息处理可能失败。请检查 openclaw 版本兼容性`);
+        }
+    }
+    catch (preflightErr) {
+        log?.error(`[qqbot:${account.accountId}] ⚠️ Runtime preflight failed: ${preflightErr}. AI 消息处理可能失败`);
+    }
     // 后台版本检查（供 /bot-version、/bot-upgrade 指令被动查询）
     triggerUpdateCheck(log);
     // 初始化 API 配置（markdown 支持）
@@ -158,8 +178,8 @@ export async function startGateway(ctx) {
     let isConnecting = false; // 防止并发连接
     let reconnectTimer = null; // 重连定时器
     let shouldRefreshToken = false; // 下次连接是否需要刷新 token
-    // 使用模块级 isFirstReadyGlobal，确保只有进程级重启才发送问候语
-    // health-monitor 重连不会重新初始化为 true
+    // 标记此 account 为待发问候（进程重启时 Set 里已有，断线重连不会重新加入）
+    _pendingFirstReady.add(account.accountId);
     const adminCtx = { accountId: account.accountId, appId: account.appId, clientSecret: account.clientSecret, log };
     // ============ P1-2: 尝试从持久化存储恢复 Session ============
     // 传入当前 appId，如果 appId 已变更（换了机器人），旧 session 自动失效
@@ -416,7 +436,7 @@ export async function startGateway(ctx) {
                     systemPrompts.push(account.systemPrompt);
                 }
                 // 处理附件（图片等）- 下载到本地供 openclaw 访问
-                const processed = await processAttachments(event.attachments, { accountId: account.accountId, cfg, log });
+                const processed = await processAttachments(event.attachments, { appId: account.appId, peerId, cfg, log });
                 const { attachmentInfo, imageUrls, imageMediaTypes, voiceAttachmentPaths, voiceAttachmentUrls, voiceAsrReferTexts, voiceTranscripts, voiceTranscriptSources, attachmentLocalPaths } = processed;
                 // 语音转录文本注入到用户消息中
                 const voiceText = formatVoiceText(voiceTranscripts);
@@ -525,24 +545,24 @@ export async function startGateway(ctx) {
                 }
                 // ============ 构建 contextInfo（静态/动态分离） ============
                 // 设计原则（参考 Telegram/Discord 做法）：
-                //   - 静态指引：每条消息不变的内容（场景锚定、投递地址、能力说明），
+                //   - 静态指引：每条消息不变的能力声明，
                 //     注入 systemPrompts 前部，session 中虽重复出现但 AI 会自动降权，
                 //     且保证长 session 窗口截断后仍可见。
                 //   - 动态标签：每条消息变化的数据（时间、附件、ASR），
                 //     以紧凑的 [ctx] 块标注在用户消息前，最小化 token 开销。
                 // --- 静态指引（仅注入框架信封未覆盖的 QQBot 特有信息） ---
                 // 框架 formatInboundEnvelope 已提供：平台标识、发送者、时间戳
-                // 这里只补充 QQBot 独有的：投递地址（cron skill 需要）
-                const staticParts = [
-                    `[QQBot] to=${qualifiedTarget}`,
-                ];
+                // 投递地址通过 AsyncLocalStorage 请求上下文传递给 remind 工具，无需在 agentBody 中暴露
+                const staticParts = [];
                 // 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 = [];
                 if (imageUrls.length > 0) {
@@ -647,267 +667,449 @@ export async function startGateway(ctx) {
                 const sendWithRetry = (sendFn) => sendWithTokenRetry(account.appId, account.clientSecret, sendFn, log, account.accountId);
                 // 发送错误提示的辅助函数
                 const sendErrorMessage = (errorText) => sendErrorToTarget(replyCtx, errorText);
-                try {
-                    const messagesConfig = pluginRuntime.channel.reply.resolveEffectiveMessagesConfig(cfg, route.agentId);
-                    // 追踪是否有响应
-                    let hasResponse = false;
-                    let hasBlockResponse = false; // 是否收到了面向用户的 block 回复
-                    let toolDeliverCount = 0; // tool deliver 计数
-                    const toolTexts = []; // 收集所有 tool deliver 文本
-                    const toolMediaUrls = []; // 收集所有 tool deliver 媒体 URL
-                    let toolFallbackSent = false; // 兜底消息是否已发送（只发一次）
-                    const responseTimeout = 120000; // 120秒超时（2分钟，与 TTS/文件生成超时对齐）
-                    const toolOnlyTimeout = 60000; // tool-only 兜底超时：60秒内没有 block 就兜底
-                    const maxToolRenewals = 3; // tool 续期上限：最多续期 3 次（总等待 = 60s × 3 = 180s）
-                    let toolRenewalCount = 0; // 已续期次数
-                    let timeoutId = null;
-                    let toolOnlyTimeoutId = null;
-                    // tool-only 兜底：转发工具产生的实际内容（媒体/文本），而非生硬的提示语
-                    const sendToolFallback = async () => {
-                        // 优先发送工具产出的媒体文件（TTS 语音、生成图片等）
-                        if (toolMediaUrls.length > 0) {
-                            log?.info(`[qqbot:${account.accountId}] Tool fallback: forwarding ${toolMediaUrls.length} media URL(s) from tool deliver(s)`);
-                            const mediaTimeout = 45000; // 单个媒体发送超时 45s
-                            for (const mediaUrl of toolMediaUrls) {
-                                try {
-                                    const result = await Promise.race([
-                                        sendMediaAuto({
-                                            to: qualifiedTarget,
-                                            text: "",
-                                            mediaUrl,
-                                            accountId: account.accountId,
-                                            replyToId: event.messageId,
-                                            account,
-                                        }),
-                                        new Promise((resolve) => setTimeout(() => resolve({ channel: "qqbot", error: `Tool fallback media send timeout (${mediaTimeout / 1000}s)` }), mediaTimeout)),
-                                    ]);
-                                    if (result.error) {
-                                        log?.error(`[qqbot:${account.accountId}] Tool fallback sendMedia error: ${result.error}`);
+                // 使用 AsyncLocalStorage 建立请求级上下文，作用域内所有异步代码
+                // （包括 AI agent 调用、tool execute）都能安全获取当前会话信息，无并发竞态。
+                await runWithRequestContext({ target: qualifiedTarget }, async () => {
+                    try {
+                        const messagesConfig = pluginRuntime.channel.reply.resolveEffectiveMessagesConfig(cfg, route.agentId);
+                        // 追踪是否有响应
+                        let hasResponse = false;
+                        let hasBlockResponse = false; // 是否收到了面向用户的 block 回复
+                        let toolDeliverCount = 0; // tool deliver 计数
+                        const toolTexts = []; // 收集所有 tool deliver 文本
+                        const toolMediaUrls = []; // 收集所有 tool deliver 媒体 URL
+                        let toolFallbackSent = false; // 兜底消息是否已发送（只发一次）
+                        const blockDeliveredMediaUrls = new Set(); // block deliver 已处理的 mediaUrl，用于 tool 后到时去重
+                        const responseTimeout = 120000; // 120秒超时（2分钟，与 TTS/文件生成超时对齐）
+                        const toolOnlyTimeout = 60000; // tool-only 兜底超时：60秒内没有 block 就兜底
+                        const maxToolRenewals = 3; // tool 续期上限：最多续期 3 次（总等待 = 60s × 3 = 180s）
+                        let toolRenewalCount = 0; // 已续期次数
+                        let timeoutId = null;
+                        let toolOnlyTimeoutId = null;
+                        // ============ Deliver Debouncer：合并短时间内连续到达的 block deliver ============
+                        const debounceConfig = account.config?.deliverDebounce;
+                        let debouncer = null;
+                        // tool-only 兜底：转发工具产生的实际内容（媒体/文本），而非生硬的提示语
+                        const sendToolFallback = async () => {
+                            // 优先发送工具产出的媒体文件（TTS 语音、生成图片等）
+                            if (toolMediaUrls.length > 0) {
+                                log?.info(`[qqbot:${account.accountId}] Tool fallback: forwarding ${toolMediaUrls.length} media URL(s) from tool deliver(s)`);
+                                const mediaTimeout = 45000; // 单个媒体发送超时 45s
+                                for (const mediaUrl of toolMediaUrls) {
+                                    try {
+                                        const result = await Promise.race([
+                                            sendMediaAuto({
+                                                to: qualifiedTarget,
+                                                text: "",
+                                                mediaUrl,
+                                                accountId: account.accountId,
+                                                replyToId: event.messageId,
+                                                account,
+                                            }),
+                                            new Promise((resolve) => setTimeout(() => resolve({ channel: "qqbot", error: `Tool fallback media send timeout (${mediaTimeout / 1000}s)` }), mediaTimeout)),
+                                        ]);
+                                        if (result.error) {
+                                            log?.error(`[qqbot:${account.accountId}] Tool fallback sendMedia error: ${result.error}`);
+                                        }
+                                    }
+                                    catch (err) {
+                                        log?.error(`[qqbot:${account.accountId}] Tool fallback sendMedia failed: ${err}`);
                                     }
                                 }
-                                catch (err) {
-                                    log?.error(`[qqbot:${account.accountId}] Tool fallback sendMedia failed: ${err}`);
-                                }
+                                return;
                             }
-                            return;
-                        }
-                        // 其次转发工具产出的文本
-                        if (toolTexts.length > 0) {
-                            const text = toolTexts.slice(-3).join("\n---\n").slice(0, 2000);
-                            log?.info(`[qqbot:${account.accountId}] Tool fallback: forwarding tool text (${text.length} chars)`);
-                            await sendErrorMessage(text);
-                            return;
-                        }
-                        // 既无媒体也无文本，静默处理（仅日志记录）
-                        log?.info(`[qqbot:${account.accountId}] Tool fallback: no media or text collected from ${toolDeliverCount} tool deliver(s), silently dropping`);
-                    };
-                    const timeoutPromise = new Promise((_, reject) => {
-                        timeoutId = setTimeout(() => {
-                            if (!hasResponse) {
-                                reject(new Error("Response timeout"));
+                            // 其次转发工具产出的文本
+                            if (toolTexts.length > 0) {
+                                const text = toolTexts.slice(-3).join("\n---\n").slice(0, 2000);
+                                log?.info(`[qqbot:${account.accountId}] Tool fallback: forwarding tool text (${text.length} chars)`);
+                                await sendErrorMessage(text);
+                                return;
                             }
-                        }, responseTimeout);
-                    });
-                    const dispatchPromise = pluginRuntime.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
-                        ctx: ctxPayload,
-                        cfg,
-                        dispatcherOptions: {
-                            responsePrefix: messagesConfig.responsePrefix,
-                            deliver: async (payload, info) => {
-                                hasResponse = true;
-                                log?.info(`[qqbot:${account.accountId}] deliver called, kind: ${info.kind}, payload keys: ${Object.keys(payload).join(", ")}`);
-                                // ============ 跳过工具调用的中间结果（带兜底保护） ============
-                                if (info.kind === "tool") {
-                                    toolDeliverCount++;
-                                    const toolText = (payload.text ?? "").trim();
-                                    if (toolText) {
-                                        toolTexts.push(toolText);
-                                    }
-                                    // 收集工具产出的媒体 URL（TTS 语音、生成图片等），供 fallback 转发
-                                    if (payload.mediaUrls?.length) {
-                                        toolMediaUrls.push(...payload.mediaUrls);
-                                    }
-                                    if (payload.mediaUrl && !toolMediaUrls.includes(payload.mediaUrl)) {
-                                        toolMediaUrls.push(payload.mediaUrl);
-                                    }
-                                    log?.info(`[qqbot:${account.accountId}] Collected tool deliver #${toolDeliverCount}: text=${toolText.length} chars, media=${toolMediaUrls.length} URLs`);
-                                    // block 已先发送完毕，tool 后到的媒体立即转发（典型场景：AI 先流式输出文本再执行 TTS）
-                                    if (hasBlockResponse && toolMediaUrls.length > 0) {
-                                        log?.info(`[qqbot:${account.accountId}] Block already sent, immediately forwarding ${toolMediaUrls.length} tool media URL(s)`);
-                                        const urlsToSend = [...toolMediaUrls];
-                                        toolMediaUrls.length = 0;
-                                        for (const mediaUrl of urlsToSend) {
-                                            try {
-                                                const result = await sendMediaAuto({
-                                                    to: qualifiedTarget,
-                                                    text: "",
-                                                    mediaUrl,
-                                                    accountId: account.accountId,
-                                                    replyToId: event.messageId,
-                                                    account,
-                                                });
-                                                if (result.error) {
-                                                    log?.error(`[qqbot:${account.accountId}] Tool media immediate forward error: ${result.error}`);
+                            // 既无媒体也无文本，静默处理（仅日志记录）
+                            log?.info(`[qqbot:${account.accountId}] Tool fallback: no media or text collected from ${toolDeliverCount} tool deliver(s), silently dropping`);
+                        };
+                        const timeoutPromise = new Promise((_, reject) => {
+                            timeoutId = setTimeout(() => {
+                                if (!hasResponse) {
+                                    reject(new Error("Response timeout"));
+                                }
+                            }, responseTimeout);
+                        });
+                        // ============ 流式消息控制器 ============
+                        const targetType = event.type === "c2c" ? "c2c"
+                            : event.type === "group" ? "group"
+                                : "channel";
+                        const useStreaming = shouldUseStreaming(account, targetType);
+                        log?.info(`[qqbot:${account.accountId}] Streaming ${useStreaming ? "enabled" : "disabled"} for ${targetType} message from ${event.senderId}`);
+                        let streamingController = null;
+                        /** 创建一个新的 StreamingController 实例（用于初始创建和回复边界时重建） */
+                        const createStreamingController = () => {
+                            const ctrl = new StreamingController({
+                                account,
+                                userId: event.senderId,
+                                replyToMsgId: event.messageId,
+                                eventId: event.messageId,
+                                logPrefix: `[qqbot:${account.accountId}:streaming]`,
+                                log,
+                                mediaContext: {
+                                    account,
+                                    event: {
+                                        type: event.type,
+                                        senderId: event.senderId,
+                                        messageId: event.messageId,
+                                        groupOpenid: event.groupOpenid,
+                                        channelId: event.channelId,
+                                    },
+                                    log,
+                                },
+                                // 回复边界回调：终结旧 controller 后创建新的，用新回复文本继续流式
+                                onReplyBoundary: async (newReplyText) => {
+                                    log?.info(`[qqbot:${account.accountId}] Reply boundary: creating new StreamingController for new reply`);
+                                    const newCtrl = createStreamingController();
+                                    streamingController = newCtrl;
+                                    // 将新回复的初始文本交给新 controller 处理
+                                    await newCtrl.onPartialReply({ text: newReplyText });
+                                },
+                            });
+                            return ctrl;
+                        };
+                        if (useStreaming) {
+                            log?.info(`[qqbot:${account.accountId}] Streaming mode enabled for ${targetType} target`);
+                            streamingController = createStreamingController();
+                        }
+                        const dispatchPromise = pluginRuntime.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
+                            ctx: ctxPayload,
+                            cfg,
+                            dispatcherOptions: {
+                                responsePrefix: messagesConfig.responsePrefix,
+                                deliver: async (payload, info) => {
+                                    hasResponse = true;
+                                    log?.info(`[qqbot:${account.accountId}] deliver called, kind: ${info.kind}, payload keys: ${Object.keys(payload).join(", ")}`);
+                                    // ============ 跳过工具调用的中间结果（带兜底保护） ============
+                                    if (info.kind === "tool") {
+                                        toolDeliverCount++;
+                                        const toolText = (payload.text ?? "").trim();
+                                        if (toolText) {
+                                            toolTexts.push(toolText);
+                                        }
+                                        // 收集工具产出的媒体 URL（TTS 语音、生成图片等），供 fallback 转发
+                                        if (payload.mediaUrls?.length) {
+                                            toolMediaUrls.push(...payload.mediaUrls);
+                                        }
+                                        if (payload.mediaUrl && !toolMediaUrls.includes(payload.mediaUrl)) {
+                                            toolMediaUrls.push(payload.mediaUrl);
+                                        }
+                                        log?.info(`[qqbot:${account.accountId}] Collected tool deliver #${toolDeliverCount}: text=${toolText.length} chars, media=${toolMediaUrls.length} URLs`);
+                                        // block 已先发送完毕，tool 后到的媒体立即转发（典型场景：AI 先流式输出文本再执行 TTS）
+                                        if (hasBlockResponse && toolMediaUrls.length > 0) {
+                                            // 去重：跳过已被 block deliver 的 sendPlainReply 处理过的 URL
+                                            const urlsToSend = toolMediaUrls.filter(url => !blockDeliveredMediaUrls.has(url));
+                                            const skippedCount = toolMediaUrls.length - urlsToSend.length;
+                                            toolMediaUrls.length = 0;
+                                            if (urlsToSend.length === 0) {
+                                                log?.info(`[qqbot:${account.accountId}] All ${skippedCount} tool media URL(s) already handled by block deliver, skipping`);
+                                                return;
+                                            }
+                                            log?.info(`[qqbot:${account.accountId}] Block already sent, immediately forwarding ${urlsToSend.length} tool media URL(s) (deduped from block deliver)`);
+                                            for (const mediaUrl of urlsToSend) {
+                                                try {
+                                                    const result = await sendMediaAuto({
+                                                        to: qualifiedTarget,
+                                                        text: "",
+                                                        mediaUrl,
+                                                        accountId: account.accountId,
+                                                        replyToId: event.messageId,
+                                                        account,
+                                                    });
+                                                    if (result.error) {
+                                                        log?.error(`[qqbot:${account.accountId}] Tool media immediate forward error: ${result.error}`);
+                                                    }
+                                                    else {
+                                                        log?.info(`[qqbot:${account.accountId}] Forwarded tool media (post-block): ${mediaUrl.slice(0, 80)}...`);
+                                                    }
                                                 }
-                                                else {
-                                                    log?.info(`[qqbot:${account.accountId}] Forwarded tool media (post-block): ${mediaUrl.slice(0, 80)}...`);
+                                                catch (err) {
+                                                    log?.error(`[qqbot:${account.accountId}] Tool media immediate forward failed: ${err}`);
                                                 }
                                             }
-                                            catch (err) {
-                                                log?.error(`[qqbot:${account.accountId}] Tool media immediate forward failed: ${err}`);
+                                            return;
+                                        }
+                                        // 兜底已发送，不再续期
+                                        if (toolFallbackSent) {
+                                            return;
+                                        }
+                                        // tool-only 超时保护：收到 tool 但迟迟没有 block 时，启动兜底定时器
+                                        // 续期有上限（maxToolRenewals 次），防止无限工具调用永远不触发兜底
+                                        if (toolOnlyTimeoutId) {
+                                            if (toolRenewalCount < maxToolRenewals) {
+                                                clearTimeout(toolOnlyTimeoutId);
+                                                toolRenewalCount++;
+                                                log?.info(`[qqbot:${account.accountId}] Tool-only timer renewed (${toolRenewalCount}/${maxToolRenewals})`);
+                                            }
+                                            else {
+                                                // 已达续期上限，不再重置，等定时器自然触发兜底
+                                                log?.info(`[qqbot:${account.accountId}] Tool-only timer renewal limit reached (${maxToolRenewals}), waiting for timeout`);
+                                                return;
                                             }
                                         }
+                                        toolOnlyTimeoutId = setTimeout(async () => {
+                                            if (!hasBlockResponse && !toolFallbackSent) {
+                                                toolFallbackSent = true;
+                                                log?.error(`[qqbot:${account.accountId}] Tool-only timeout: ${toolDeliverCount} tool deliver(s) but no block within ${toolOnlyTimeout / 1000}s, sending fallback`);
+                                                try {
+                                                    await sendToolFallback();
+                                                }
+                                                catch (sendErr) {
+                                                    log?.error(`[qqbot:${account.accountId}] Failed to send tool-only fallback: ${sendErr}`);
+                                                }
+                                            }
+                                        }, toolOnlyTimeout);
                                         return;
                                     }
-                                    // 兜底已发送，不再续期
-                                    if (toolFallbackSent) {
-                                        return;
+                                    // 收到 block 回复，清除所有超时定时器
+                                    hasBlockResponse = true;
+                                    // 收到真正回复，立即停止输入状态续期（让 "输入中" 尽快消失）
+                                    typing.keepAlive?.stop();
+                                    if (timeoutId) {
+                                        clearTimeout(timeoutId);
+                                        timeoutId = null;
                                     }
-                                    // tool-only 超时保护：收到 tool 但迟迟没有 block 时，启动兜底定时器
-                                    // 续期有上限（maxToolRenewals 次），防止无限工具调用永远不触发兜底
                                     if (toolOnlyTimeoutId) {
-                                        if (toolRenewalCount < maxToolRenewals) {
-                                            clearTimeout(toolOnlyTimeoutId);
-                                            toolRenewalCount++;
-                                            log?.info(`[qqbot:${account.accountId}] Tool-only timer renewed (${toolRenewalCount}/${maxToolRenewals})`);
+                                        clearTimeout(toolOnlyTimeoutId);
+                                        toolOnlyTimeoutId = null;
+                                    }
+                                    if (toolDeliverCount > 0) {
+                                        log?.info(`[qqbot:${account.accountId}] Block deliver after ${toolDeliverCount} tool deliver(s)`);
+                                    }
+                                    // ============ 流式模式处理 ============
+                                    // 流式模式下，所有 block deliver 内容（含媒体标签）统一交由 StreamingController 处理。
+                                    // StreamingController 内部有重试机制；如果一个分片都没发出去则降级到普通消息。
+                                    if (streamingController && !streamingController.isTerminalPhase) {
+                                        const deliverTextLen = (payload.text ?? "").length;
+                                        const deliverPreview = (payload.text ?? "").slice(0, 40).replace(/\n/g, "\\n");
+                                        log?.debug?.(`[qqbot:${account.accountId}] Streaming deliver entry, textLen=${deliverTextLen}, phase=${streamingController.currentPhase}, sentChunks=${streamingController.sentChunkCount_debug}, preview="${deliverPreview}"`);
+                                        try {
+                                            await streamingController.onDeliver(payload);
+                                            log?.debug?.(`[qqbot:${account.accountId}] Streaming deliver done, phase=${streamingController.currentPhase}`);
+                                        }
+                                        catch (err) {
+                                            // StreamingController 内部已有重试，这里只打日志
+                                            log?.error(`[qqbot:${account.accountId}] Streaming deliver error: ${err}`);
+                                        }
+                                        // 检查是否因流式 API 不可用而需要降级（ensureStreamingStarted 全部失败）
+                                        // 如果需要降级，不 return，让本次 deliver 的 payload.text（全量文本）继续走普通发送逻辑
+                                        if (streamingController.shouldFallbackToStatic) {
+                                            log?.info(`[qqbot:${account.accountId}] Streaming API unavailable, falling back to static for this deliver`);
+                                            // 不 return，继续走普通发送逻辑（payload.text 是完整文本）
                                         }
                                         else {
-                                            // 已达续期上限，不再重置，等定时器自然触发兜底
-                                            log?.info(`[qqbot:${account.accountId}] Tool-only timer renewal limit reached (${maxToolRenewals}), waiting for timeout`);
+                                            // 流式正常处理，不走普通发送逻辑
+                                            pluginRuntime.channel.activity.record({
+                                                channel: "qqbot",
+                                                accountId: account.accountId,
+                                                direction: "outbound",
+                                            });
                                             return;
                                         }
                                     }
-                                    toolOnlyTimeoutId = setTimeout(async () => {
-                                        if (!hasBlockResponse && !toolFallbackSent) {
-                                            toolFallbackSent = true;
-                                            log?.error(`[qqbot:${account.accountId}] Tool-only timeout: ${toolDeliverCount} tool deliver(s) but no block within ${toolOnlyTimeout / 1000}s, sending fallback`);
-                                            try {
-                                                await sendToolFallback();
-                                            }
-                                            catch (sendErr) {
-                                                log?.error(`[qqbot:${account.accountId}] Failed to send tool-only fallback: ${sendErr}`);
+                                    // ============ 实际发送逻辑（可被 debouncer 包裹） ============
+                                    const executeDeliver = async (deliverPayload, _deliverInfo) => {
+                                        // ============ 引用回复 ============
+                                        const quoteRef = event.msgIdx;
+                                        let quoteRefUsed = false;
+                                        const consumeQuoteRef = () => {
+                                            if (quoteRef && !quoteRefUsed) {
+                                                quoteRefUsed = true;
+                                                return quoteRef;
                                             }
+                                            return undefined;
+                                        };
+                                        let replyText = deliverPayload.text ?? "";
+                                        // ============ 媒体标签解析 + 发送 ============
+                                        const deliverEvent = {
+                                            type: event.type,
+                                            senderId: event.senderId,
+                                            messageId: event.messageId,
+                                            channelId: event.channelId,
+                                            groupOpenid: event.groupOpenid,
+                                            msgIdx: event.msgIdx,
+                                        };
+                                        const deliverActx = { 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;
                                         }
-                                    }, toolOnlyTimeout);
-                                    return;
-                                }
-                                // 收到 block 回复，清除所有超时定时器
-                                hasBlockResponse = true;
-                                // 收到真正回复，立即停止输入状态续期（让 "输入中" 尽快消失）
-                                typing.keepAlive?.stop();
-                                if (timeoutId) {
-                                    clearTimeout(timeoutId);
-                                    timeoutId = null;
-                                }
-                                if (toolOnlyTimeoutId) {
-                                    clearTimeout(toolOnlyTimeoutId);
-                                    toolOnlyTimeoutId = null;
-                                }
-                                if (toolDeliverCount > 0) {
-                                    log?.info(`[qqbot:${account.accountId}] Block deliver after ${toolDeliverCount} tool deliver(s)`);
-                                }
-                                // ============ 引用回复 ============
-                                const quoteRef = event.msgIdx;
-                                let quoteRefUsed = false;
-                                const consumeQuoteRef = () => {
-                                    if (quoteRef && !quoteRefUsed) {
-                                        quoteRefUsed = true;
-                                        return quoteRef;
+                                        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;
+                                        // ============ 非结构化消息发送 ============
+                                        // 记录 block deliver 处理的 mediaUrl，供 tool 后到时去重
+                                        if (deliverPayload.mediaUrl)
+                                            blockDeliveredMediaUrls.add(deliverPayload.mediaUrl);
+                                        if (deliverPayload.mediaUrls)
+                                            for (const u of deliverPayload.mediaUrls)
+                                                blockDeliveredMediaUrls.add(u);
+                                        await sendPlainReply(deliverPayload, replyText, deliverEvent, deliverActx, sendWithRetry, consumeQuoteRef, toolMediaUrls);
+                                        pluginRuntime.channel.activity.record({
+                                            channel: "qqbot",
+                                            accountId: account.accountId,
+                                            direction: "outbound",
+                                        });
+                                    };
+                                    // ============ Debounce 合并回复 ============
+                                    if (!debouncer) {
+                                        debouncer = createDeliverDebouncer(debounceConfig, executeDeliver, log, `[qqbot:${account.accountId}:debounce]`);
                                     }
-                                    return undefined;
-                                };
-                                let replyText = payload.text ?? "";
-                                // ============ 媒体标签解析 + 发送 ============
-                                const deliverEvent = {
-                                    type: event.type,
-                                    senderId: event.senderId,
-                                    messageId: event.messageId,
-                                    channelId: event.channelId,
-                                    groupOpenid: event.groupOpenid,
-                                    msgIdx: event.msgIdx,
-                                };
-                                const deliverActx = { 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;
-                                }
-                                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);
-                                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) => {
+                                    log?.error(`[qqbot:${account.accountId}] Dispatch error: ${err}`);
+                                    hasResponse = true;
+                                    if (timeoutId) {
+                                        clearTimeout(timeoutId);
+                                        timeoutId = null;
+                                    }
+                                    // 流式模式：委托给 streaming controller 处理错误
+                                    if (streamingController && !streamingController.isTerminalPhase) {
+                                        try {
+                                            await streamingController.onError(err);
+                                        }
+                                        catch (streamErr) {
+                                            log?.error(`[qqbot:${account.accountId}] Streaming onError failed: ${streamErr}`);
+                                        }
+                                        // 如果 onError 中因无分片发出而降级，不 return，走普通错误处理
+                                        if (streamingController.shouldFallbackToStatic) {
+                                            log?.info(`[qqbot:${account.accountId}] Streaming onError: no chunk sent, falling back to static error handling`);
+                                            // 不 return，继续走普通错误处理
+                                        }
+                                        else {
+                                            return;
+                                        }
+                                    }
+                                    const errMsg = String(err);
+                                    // 兼容 openclaw 3.23+ 的 plugin-sdk/root-alias.cjs 模块解析失败
+                                    if (errMsg.includes("Unable to resolve plugin runtime module") || errMsg.includes("root-alias.cjs")) {
+                                        log?.error(`[qqbot:${account.accountId}] ⚠️ openclaw 框架 runtime 模块解析失败，可能是 openclaw 版本与 plugin-sdk 不兼容。请尝试: npm install -g openclaw@latest && openclaw gateway restart`);
+                                        await sendErrorMessage("⚠️ AI 服务暂时不可用：openclaw 框架运行时模块加载失败。\n\n请管理员执行：\nnpm install -g openclaw@latest\nopenclaw gateway restart\n\n斜杠命令（如 /bot-ping）不受影响。");
+                                        return;
+                                    }
+                                    if (errMsg.includes("401") || errMsg.includes("key") || errMsg.includes("auth")) {
+                                        log?.error(`[qqbot:${account.accountId}] AI auth error: ${errMsg}`);
+                                    }
+                                    else {
+                                        log?.error(`[qqbot:${account.accountId}] AI process error: ${errMsg}`);
+                                    }
+                                },
                             },
-                            onError: async (err) => {
-                                log?.error(`[qqbot:${account.accountId}] Dispatch error: ${err}`);
-                                hasResponse = true;
-                                if (timeoutId) {
-                                    clearTimeout(timeoutId);
-                                    timeoutId = null;
-                                }
-                                // 发送错误提示给用户，显示完整错误信息
-                                const errMsg = String(err);
-                                if (errMsg.includes("401") || errMsg.includes("key") || errMsg.includes("auth")) {
-                                    log?.error(`[qqbot:${account.accountId}] AI auth error: ${errMsg}`);
+                            replyOptions: {
+                                // 流式模式时禁用 block streaming
+                                disableBlockStreaming: !useStreaming,
+                                // 流式模式下注册 onPartialReply 回调，接收流式文本增量
+                                ...(streamingController ? {
+                                    onPartialReply: async (payload) => {
+                                        const textLen = payload.text?.length ?? 0;
+                                        const preview = (payload.text ?? "").slice(0, 40).replace(/\n/g, "\\n");
+                                        log?.debug?.(`[qqbot:${account.accountId}] onPartialReply called, textLen=${textLen}, phase=${streamingController.currentPhase}, isTerminal=${streamingController.isTerminalPhase}, preview="${preview}"`);
+                                        try {
+                                            await streamingController.onPartialReply(payload);
+                                            log?.debug?.(`[qqbot:${account.accountId}] onPartialReply done, phase=${streamingController.currentPhase}`);
+                                        }
+                                        catch (err) {
+                                            // StreamingController 内部已有重试，这里只打日志
+                                            log?.error(`[qqbot:${account.accountId}] Streaming onPartialReply error: ${err}`);
+                                        }
+                                    },
+                                } : {}),
+                            },
+                        });
+                        // 等待分发完成或超时
+                        try {
+                            await Promise.race([dispatchPromise, timeoutPromise]);
+                        }
+                        catch (err) {
+                            if (timeoutId) {
+                                clearTimeout(timeoutId);
+                            }
+                            if (!hasResponse) {
+                                log?.error(`[qqbot:${account.accountId}] No response within timeout`);
+                            }
+                        }
+                        finally {
+                            // 清理 tool-only 兜底定时器
+                            if (toolOnlyTimeoutId) {
+                                clearTimeout(toolOnlyTimeoutId);
+                                toolOnlyTimeoutId = null;
+                            }
+                            // dispatch 完成后，如果只有 tool 没有 block，且尚未发过兜底，立即兜底
+                            if (toolDeliverCount > 0 && !hasBlockResponse && !toolFallbackSent) {
+                                toolFallbackSent = true;
+                                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;
+                            }
+                            // ============ 流式消息收尾 ============
+                            // dispatch 完成后，标记流式控制器已完成并触发 onIdle（发送终结分片）
+                            if (streamingController && !streamingController.isTerminalPhase) {
+                                try {
+                                    streamingController.markFullyComplete();
+                                    await streamingController.onIdle();
+                                    log?.debug?.(`[qqbot:${account.accountId}] Streaming controller finalized`);
                                 }
-                                else {
-                                    log?.error(`[qqbot:${account.accountId}] AI process error: ${errMsg}`);
+                                catch (err) {
+                                    log?.error(`[qqbot:${account.accountId}] Streaming finalization error: ${err}`);
+                                    // 尝试中止
+                                    try {
+                                        await streamingController.abortStreaming();
+                                    }
+                                    catch { /* ignore */ }
                                 }
-                            },
-                        },
-                        replyOptions: {
-                            disableBlockStreaming: true,
-                        },
-                    });
-                    // 等待分发完成或超时
-                    try {
-                        await Promise.race([dispatchPromise, timeoutPromise]);
+                            }
+                            // ============ 流式降级到非流式 ============
+                            // 无需额外处理：如果流式 API 不可用（shouldFallbackToStatic），
+                            // deliver 回调中已自动跳过流式拦截，走普通消息发送逻辑。
+                            // （每次 deliver 收到的都是全量文本，不需要在 controller 内部保存累积文本）
+                            if (streamingController?.shouldFallbackToStatic) {
+                                log?.debug?.(`[qqbot:${account.accountId}] Streaming was degraded to static mode (no chunk sent successfully)`);
+                            }
+                        }
                     }
                     catch (err) {
-                        if (timeoutId) {
-                            clearTimeout(timeoutId);
-                        }
-                        if (!hasResponse) {
-                            log?.error(`[qqbot:${account.accountId}] No response within timeout`);
+                        const errStr = String(err);
+                        log?.error(`[qqbot:${account.accountId}] Message processing failed: ${err}`);
+                        // 兼容 openclaw 3.23+ runtime 模块解析失败：给用户发可操作的提示
+                        if (errStr.includes("Unable to resolve plugin runtime module") || errStr.includes("root-alias.cjs")) {
+                            try {
+                                await sendErrorMessage("⚠️ AI 服务暂时不可用：openclaw 框架运行时模块加载失败。\n\n请管理员执行：\nnpm install -g openclaw@latest\nopenclaw gateway restart\n\n斜杠命令（如 /bot-ping）不受影响。");
+                            }
+                            catch { /* best-effort */ }
                         }
                     }
                     finally {
-                        // 清理 tool-only 兜底定时器
-                        if (toolOnlyTimeoutId) {
-                            clearTimeout(toolOnlyTimeoutId);
-                            toolOnlyTimeoutId = null;
-                        }
-                        // dispatch 完成后，如果只有 tool 没有 block，且尚未发过兜底，立即兜底
-                        if (toolDeliverCount > 0 && !hasBlockResponse && !toolFallbackSent) {
-                            toolFallbackSent = true;
-                            log?.error(`[qqbot:${account.accountId}] Dispatch completed with ${toolDeliverCount} tool deliver(s) but no block deliver, sending fallback`);
-                            await sendToolFallback();
-                        }
+                        // 无论成功/失败/超时，都停止输入状态续期
+                        typing.keepAlive?.stop();
                     }
-                }
-                catch (err) {
-                    log?.error(`[qqbot:${account.accountId}] Message processing failed: ${err}`);
-                }
-                finally {
-                    // 无论成功/失败/超时，都停止输入状态续期
-                    typing.keepAlive?.stop();
-                }
+                }); // end runWithRequestContext
             };
             ws.on("open", () => {
                 log?.info(`[qqbot:${account.accountId}] WebSocket connected`);
@@ -999,11 +1201,11 @@ export async function startGateway(ctx) {
                                 onReady?.(d);
                                 // 仅 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
                             }
@@ -1011,8 +1213,8 @@ export async function startGateway(ctx) {
                                 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 连接时间