lightclawbot 1.2.6 → 1.2.8

package/dist/src/streaming/stream-reply-sink.js

@@ -17,6 +17,8 @@ import { CHANNEL_KEY } from "../config.js";
 import { uploadFileToServer } from "../file-storage.js";
 import { mediaUrlsToFiles } from "../media.js";
 import { createDeltaTrackerState, toStreamDeltaText } from "./delta-tracker.js";
+import { buildRunningStep, buildDoneStep, genStepId } from "./thinking-formatter.js";
+import { DEFAULT_PARTIAL_COALESCE } from "./types.js";
 import { emitSignal } from "../utils/common.js";
 import { readSessionHistoryTail } from "../history/index.js";
 /** 派生/管理 subagent 的工具名；前端可据此特化渲染 tool_start。 */
@@ -33,6 +35,39 @@ function localizeAbortReplyText(text) {
 }
 export function createStreamReplyConfig(opts, prefixOptions, signalCtx) {
     const { emitter, targetId, originalMsgId, log, effectiveApiKey, typingAlreadyStarted, sessionKey, agentId } = opts;
+    // ── 群聊扩展字段 ──
+    const { groupId, runId: optRunId, parentRunId, conversationId, isSubtask, parentMsgId } = opts;
+    /** 是否为群聊模式 */
+    const isGroupMode = !!groupId;
+    /** 群聊场景下可变的 runId（可能由 SDK 回填） */
+    let knownRunId = optRunId;
+    /**
+     * 构建群聊 extra 数据载荷（仅群聊模式使用）
+     * 协议字段与前端 useGroupChat.ts 对齐
+     */
+    const buildGroupDataExtra = (streamStatus) => {
+        if (!isGroupMode)
+            return undefined;
+        const extra = { groupId, agentId, streamStatus };
+        if (knownRunId)
+            extra.runId = knownRunId;
+        if (parentRunId !== undefined && parentRunId !== null)
+            extra.parentRunId = parentRunId;
+        if (conversationId)
+            extra.conversationId = conversationId;
+        if (isSubtask)
+            extra.isSubtask = true;
+        if (parentMsgId)
+            extra.parentMsgId = parentMsgId;
+        return extra;
+    };
+    /** 群聊场景下所有信号帧的顶层 extra（注入 chatKind: 'group'） */
+    const groupSignalExtra = isGroupMode ? { chatKind: 'group' } : undefined;
+    // ── partial 通道二次聚合参数（详见 ADR-017） ──
+    const coalesceCfg = {
+        ...DEFAULT_PARTIAL_COALESCE,
+        ...(opts.partialCoalesce ?? {}),
+    };
     // ── 增量追踪 & 已推送文本 ──
     let partialReplyState = createDeltaTrackerState();
     let streamedText = "";
@@ -46,6 +81,21 @@ export function createStreamReplyConfig(opts, prefixOptions, signalCtx) {
     const counts = { tool: 0, block: 0, final: 0 };
     let toolStartCount = 0;
     let assistantMessageCount = 0;
+    // ── thinking_step 关联：onToolStart 生成 stepId，缓存到这里；
+    //    onItemEvent 拿不到 itemId 时回退到这个 stepId，保证 running ↔ done 能配对。
+    let lastToolStepId = null;
+    let lastToolName = null;
+    // ── onItemEvent(start) 预热信息：
+    //    实测 SDK 时序是 onItemEvent(start) 先于 onToolStart（毫秒级），而工具调用串行，
+    //    所以用一对全局变量缓存最近一次 start 的 meta/title，onToolStart 取走后由 sink 使用。
+    //    args 摸不出内容时（如 browser 工具 args.action="open" 没信息量），running 用这些兜底。
+    let pendingItemMeta = null;
+    let pendingItemTitle = null;
+    // ── thinking_step 时间线序号 ──
+    //    seqCounter: 全局自增，每次 running 帧 +1
+    //    stepIdToSeq: running 时记录 stepId → seq；done 帧复用此 seq，保证合并行的位置稳定
+    let thinkingSeqCounter = 0;
+    const thinkingStepSeqMap = new Map();
     // ── thinking/reasoning 观测（不面向用户，仅为首字延迟归因） ──
     let reasoningChars = 0;
     let reasoningFirstAt = 0;
@@ -56,6 +106,89 @@ export function createStreamReplyConfig(opts, prefixOptions, signalCtx) {
     let completed = false;
     /** openclaw abort 检测：sendFinalReply 收到 abort 文案时置 true，markComplete 据此跳过 NO_REPLY。 */
     let abortDetected = false;
+    // ── Coalescer 状态：缓冲区 + idle 定时器 + 统计 ──
+    let coalesceBuf = "";
+    let idleTimer = null;
+    let firstFrameEmitted = false;
+    /** 自然 flush（size/idle）的最近一次时间戳，用于统计 maxIdleGap */
+    let lastFlushAt = 0;
+    /** 首字（首帧）emit 时刻，用于 firstByteMs 统计 */
+    let firstByteAt = 0;
+    /** 本次会话的 sink 启动时间（首次 onPartialReply 进入时戳一次） */
+    let sinkStartAt = 0;
+    const coalesceStats = {
+        frames: 0,
+        totalChars: 0,
+        triggerStats: { first: 0, size: 0, idle: 0, tool: 0, final: 0, round: 0, block: 0, complete: 0 },
+        maxIdleGap: 0,
+        /** 模型 onPartialReply 累计的 token 增量条数（用于评估 "模型给了多少条" → 合并比） */
+        totalTokenDeltas: 0,
+    };
+    /**
+     * 当前合并周期内累计的模型 token 增量条数。
+     *
+     * - onPartialReply 每收到一个非空 delta 就 +1
+     * - emitChunk 时打入日志后清零
+     * - finalDelta 路径不计入（不是模型流式 token）
+     */
+    let pendingTokenCount = 0;
+    /** 清掉 idle 定时器（不 flush） */
+    const clearIdleTimer = () => {
+        if (idleTimer !== null) {
+            clearTimeout(idleTimer);
+            idleTimer = null;
+        }
+    };
+    /** 重置 idle 定时器：到期触发 idle flush */
+    const armIdleTimer = () => {
+        clearIdleTimer();
+        if (coalesceCfg.idleMs > 0) {
+            idleTimer = setTimeout(() => {
+                idleTimer = null;
+                flushCoalesceBuffer("idle");
+            }, coalesceCfg.idleMs);
+        }
+    };
+    /**
+     * 真正向 socket 发出 stream_chunk 帧 + 维护 coalesceStats。
+     * trigger 仅用于日志归因，行为完全一致。
+     */
+    const emitChunk = (text, trigger) => {
+        if (!text)
+            return;
+        emitSignal(signalCtx, "stream_chunk", text, groupSignalExtra, buildGroupDataExtra('delta'));
+        emittedUserVisible = true;
+        coalesceStats.frames++;
+        coalesceStats.totalChars += text.length;
+        coalesceStats.triggerStats[trigger]++;
+        const now = Date.now();
+        if (firstByteAt === 0)
+            firstByteAt = now;
+        if (lastFlushAt > 0) {
+            const gap = now - lastFlushAt;
+            if (gap > coalesceStats.maxIdleGap)
+                coalesceStats.maxIdleGap = gap;
+        }
+        lastFlushAt = now;
+        // 当前周期内累计的模型 token 增量条数，emit 后清零；final 路径未累加，会显示为 0
+        const tokensInCycle = pendingTokenCount;
+        coalesceStats.totalTokenDeltas += tokensInCycle;
+        pendingTokenCount = 0;
+        log?.info(`[${CHANNEL_KEY}] [stream] [coalesce] flush: trigger=${trigger} ` +
+            `bufLen=${coalesceBuf.length} deltaLen=${text.length} tokens=${tokensInCycle}`);
+    };
+    /**
+     * 把 buffer 中堆积的字符整体 emit 出去并复位 buffer/timer。
+     * 任何强制 flush 路径必须经过这里，保证统计与日志一致。
+     */
+    const flushCoalesceBuffer = (trigger) => {
+        clearIdleTimer();
+        if (!coalesceBuf)
+            return;
+        const payload = coalesceBuf;
+        coalesceBuf = "";
+        emitChunk(payload, trigger);
+    };
     // ── Token 用量 ──
     // 把每一轮的 usage 写入 transcript jsonl（与 history 模块同源），
     // 因此在 markComplete 时从 transcript 末尾读最近一条 assistant 消息的 usage，
@@ -71,17 +204,44 @@ export function createStreamReplyConfig(opts, prefixOptions, signalCtx) {
         if (typingStartSent)
             return;
         typingStartSent = true;
-        emitSignal(signalCtx, "typing_start");
+        emitSignal(signalCtx, "typing_start", "", groupSignalExtra, buildGroupDataExtra('delta'));
     };
-    const sendTypingStop = () => {
+    const sendTypingStop = (streamStatus, finalContent) => {
         if (typingStopSent)
             return;
         typingStopSent = true;
-        emitSignal(signalCtx, "typing_stop");
+        emitSignal(signalCtx, "typing_stop", finalContent ?? "", groupSignalExtra, buildGroupDataExtra(streamStatus ?? 'done'));
+    };
+    /**
+     * 群聊场景：发送最终完整文本帧
+     * 通过 emitter.emit 直接推送完整消息（非信号），前端据此渲染最终气泡内容。
+     */
+    const emitFinalText = (text, streamStatus) => {
+        if (!isGroupMode)
+            return;
+        try {
+            emitter.emit({
+                msgId: signalCtx.replyMsgId,
+                from: emitter.botClientId,
+                to: targetId,
+                content: text,
+                timestamp: Date.now(),
+                replyToMsgId: originalMsgId,
+                agentId,
+                chatKind: 'group',
+                extra: buildGroupDataExtra(streamStatus),
+            });
+        }
+        catch (err) {
+            log?.warn(`[${CHANNEL_KEY}] [stream] emitFinalText failed: ${err}`);
+        }
     };
     /**
-     * 处理 payload 中的 mediaUrls：COS 上传 → 拼 Markdown 链接 → emit sendReply/sendFiles。
+     * 处理 payload 中的 mediaUrls：COS 上传 → 拼 Markdown 链接 → 推送给用户。
      * 仅在 mediaList 非空时调用。
+     *
+     * 群聊模式：通过 stream_chunk 信号帧推送 Markdown 图片/文件链接（带群聊 extra）。
+     * 私聊模式：通过 emitter.sendFiles / emitter.sendReply 推送。
      */
     const handleMediaFinal = async (replyText, mediaList) => {
         const files = await mediaUrlsToFiles(mediaList, log);
@@ -105,16 +265,32 @@ export function createStreamReplyConfig(opts, prefixOptions, signalCtx) {
         }
         let enrichedText = replyText;
         if (publicUrls.length > 0) {
+            // 判断是否为图片类型（根据 URL 中的文件扩展名）
             const urlSection = publicUrls
                 .map((url, i) => {
                 const match = url.match(/filePath=([^&]+)/);
                 const filePath = match ? decodeURIComponent(match[1]) : "";
                 const fileName = filePath.split("/").pop() || `file${publicUrls.length > 1 ? ` (${i + 1})` : ""}`;
-                return `📎 [${fileName}](${url})`;
+                const ext = fileName.split('.').pop()?.toLowerCase() || '';
+                const isImage = ['png', 'jpg', 'jpeg', 'gif', 'webp', 'svg', 'bmp', 'ico'].includes(ext);
+                // 图片使用 Markdown 图片语法，非图片使用链接语法
+                return isImage ? `![${fileName}](${url})` : `📎 [${fileName}](${url})`;
             })
                 .join("\n");
             enrichedText = enrichedText ? `${enrichedText}\n\n${urlSection}` : urlSection;
         }
+        // ── 群聊模式：通过 stream_chunk 推送（带群聊 extra，前端能正确识别） ──
+        if (isGroupMode) {
+            if (enrichedText.trim()) {
+                const delta = `\n\n${enrichedText}`;
+                streamedText += delta;
+                emitSignal(signalCtx, "stream_chunk", delta, groupSignalExtra, buildGroupDataExtra('delta'));
+                emittedUserVisible = true;
+                log?.info(`[${CHANNEL_KEY}] [stream] handleMediaFinal(group): pushed ${publicUrls.length} media as stream_chunk`);
+            }
+            return;
+        }
+        // ── 私聊模式：通过 sendFiles / sendReply 推送 ──
         if (files.length > 0) {
             emitter.sendFiles(targetId, enrichedText, files, originalMsgId, signalCtx.chatId);
             emittedUserVisible = true;
@@ -138,9 +314,11 @@ export function createStreamReplyConfig(opts, prefixOptions, signalCtx) {
             if (completed)
                 return false;
             counts.tool++;
+            // 强制 flush：tool_end 之后 LLM 通常会续写新文本，必须把上一段 buffer 先发出去，避免错位。
+            flushCoalesceBuffer("tool");
             const isError = !!payload.isError;
             log?.info(`[${CHANNEL_KEY}] [stream] sendToolResult: textLen=${payload.text?.length ?? 0} isError=${isError}`);
-            emitSignal(signalCtx, "tool_end", "", { toolIsError: isError });
+            emitSignal(signalCtx, "tool_end", "", { toolIsError: isError, ...groupSignalExtra }, buildGroupDataExtra('delta'));
             return true;
         },
         /** 块回复：文本已由 onPartialReply 推送，这里只处理媒体。 */
@@ -153,6 +331,8 @@ export function createStreamReplyConfig(opts, prefixOptions, signalCtx) {
                 : payload.mediaUrl ? [payload.mediaUrl] : [];
             if (mediaList.length > 0) {
                 log?.info(`[${CHANNEL_KEY}] [stream] sendBlockReply: processing ${mediaList.length} media files`);
+                // 强制 flush：媒体附件要走在文本"已渲染"之后，否则前端会先看到媒体卡再补文字，渲染错乱。
+                flushCoalesceBuffer("block");
                 enqueue(() => handleMediaFinal(payload.text ?? "", mediaList).catch((err) => {
                     log?.error(`[${CHANNEL_KEY}] [stream] sendBlockReply media error: ${err}`);
                 }));
@@ -182,6 +362,8 @@ export function createStreamReplyConfig(opts, prefixOptions, signalCtx) {
                 ? payload.mediaUrls
                 : payload.mediaUrl ? [payload.mediaUrl] : [];
             log?.info(`[${CHANNEL_KEY}] [stream] sendFinalReply: textLen=${replyText.length} mediaCount=${mediaList.length} streamedLen=${streamedText.length} historyRounds=${streamedHistory.length}`);
+            // 强制 flush：尾部增量必须在 buffer 已堆积内容"之后"发，不能让 finalDelta 插队。
+            flushCoalesceBuffer("final");
             if (mediaList.length > 0) {
                 enqueue(() => handleMediaFinal(replyText, mediaList).catch((err) => {
                     log?.error(`[${CHANNEL_KEY}] [stream] sendFinalReply media error: ${err}`);
@@ -216,8 +398,8 @@ export function createStreamReplyConfig(opts, prefixOptions, signalCtx) {
                 partialReplyState.latest = replyText;
             }
             if (delta) {
-                emitSignal(signalCtx, "stream_chunk", delta);
-                emittedUserVisible = true;
+                // 直接走 emitChunk 而非进 buffer：finalDelta 是"本轮兜底尾巴"，必须立即可见。
+                emitChunk(delta, "final");
                 log?.debug?.(`[${CHANNEL_KEY}] [stream] Final delta: ${delta.length} chars`);
             }
             return true;
@@ -244,10 +426,36 @@ export function createStreamReplyConfig(opts, prefixOptions, signalCtx) {
          */
         markComplete: (markOpts) => {
             completed = true;
+            // 强制 flush：buffer 残留必须在 typing_stop 之前发出去；同时也清掉 idle timer 防泄漏。
+            flushCoalesceBuffer("complete");
             const hadStreamedText = streamedText.length > 0 || streamedHistory.length > 0;
             const hadDispatch = counts.tool > 0 || counts.block > 0 || counts.final > 0;
             const hadLLMActivity = toolStartCount > 0 || assistantMessageCount > 0;
             const isAborted = markOpts?.aborted === true || abortDetected;
+            // ── 群聊模式：简化终态处理（不发 usage / NO_REPLY，完整文本合并到 typing_stop 的 content 中） ──
+            if (isGroupMode) {
+                const aggregatedText = streamedHistory.length > 0
+                    ? [...streamedHistory, streamedText].filter(Boolean).join('\n')
+                    : streamedText;
+                if (isAborted) {
+                    log?.info(`[${CHANNEL_KEY}] [stream] markComplete(group): aborted`);
+                    // 将完整文本合并到 typing_stop 的 content 中，前端据此渲染最终气泡
+                    sendTypingStop('aborted', aggregatedText || '已停止');
+                }
+                else if (hadStreamedText || hadDispatch) {
+                    log?.info(`[${CHANNEL_KEY}] [stream] markComplete(group): done ` +
+                        `streamedLen=${streamedText.length} historyRounds=${streamedHistory.length}`);
+                    // 将完整文本合并到 typing_stop 的 content 中，避免额外发送独立消息导致前端重复渲染
+                    sendTypingStop('done', aggregatedText);
+                }
+                else {
+                    // 群聊无内容输出时也发 done（不发 NO_REPLY）
+                    log?.info(`[${CHANNEL_KEY}] [stream] markComplete(group): done (no content)`);
+                    sendTypingStop('failed', '调用 Agent 失败，请稍后重试');
+                }
+                return;
+            }
+            // ── 私聊模式：原有逻辑 ──
             if (isAborted) {
                 log?.info(`[${CHANNEL_KEY}] [stream] markComplete: aborted`);
             }
@@ -274,13 +482,38 @@ export function createStreamReplyConfig(opts, prefixOptions, signalCtx) {
                     `toolStart=${toolStartCount} assistantMsg=${assistantMessageCount} ` +
                     `streamedLen=${streamedText.length} historyRounds=${streamedHistory.length}`);
             }
+            // 会话级聚合统计 summary —— 调参依据（详见 ADR-017）
+            if (coalesceStats.frames > 0) {
+                const durationMs = sinkStartAt > 0 ? Date.now() - sinkStartAt : 0;
+                const firstByteMs = sinkStartAt > 0 && firstByteAt > 0 ? firstByteAt - sinkStartAt : 0;
+                const avgFrameLen = (coalesceStats.totalChars / coalesceStats.frames).toFixed(1);
+                // 平均合并比：每个 emit 帧承载了多少个模型 token 增量
+                const avgTokensPerFrame = coalesceStats.frames > 0
+                    ? (coalesceStats.totalTokenDeltas / coalesceStats.frames).toFixed(1)
+                    : "0";
+                log?.info(`[${CHANNEL_KEY}] [stream] [coalesce-summary] ` +
+                    `frames=${coalesceStats.frames} totalChars=${coalesceStats.totalChars} ` +
+                    `totalTokens=${coalesceStats.totalTokenDeltas} avgTokensPerFrame=${avgTokensPerFrame} ` +
+                    `triggerStats=${JSON.stringify(coalesceStats.triggerStats)} ` +
+                    `avgFrameLen=${avgFrameLen} maxIdleGap=${coalesceStats.maxIdleGap}ms ` +
+                    `firstByteMs=${firstByteMs} durationMs=${durationMs} ` +
+                    `cfg={minChars:${coalesceCfg.minChars},idleMs:${coalesceCfg.idleMs}}`);
+            }
             // 在 typing_stop 之前 emit 一帧 usage（如有）。
             // 数据源：从 transcript jsonl 读最近一条 assistant 消息的 usage（与 history 模块同源）。
-            // abort / 静默 dispatch / NO_REPLY 等异常路径下 transcript 可能没有可读 usage，
-            // 此时不 emit，前端按"无用量数据"渲染。
+            //
+            // 守卫条件（缺一不可）：
+            //   1. 非 abort
+            //   2. sessionKey 已知（否则无 transcript 可读）
+            //   3. 本 sink 真正承载了一次完整的 LLM 输出：hadLLMActivity && (hadStreamedText || hadDispatch)
+            //
+            // 第 3 条尤为关键：当用户连发消息被 openclaw 合并为 followup 时，被合并那条的 sink
+            // 不会有任何 LLM 活动（hadLLMActivity=false），但 transcript 里有上一轮的 usage —— 若
+            // 不加守卫就会把上一轮的 usage 误透给这条消息，前端把它当作"该消息已结束"的终态信号，
+            // 导致后续真正的回复内容不再绑定到这条消息上。
             let usageToEmit;
-            // 非 abort + sessionKey 已知 → 从 transcript 读 usage
-            if (!isAborted && sessionKey) {
+            const sinkProducedOutput = hadLLMActivity && (hadStreamedText || hadDispatch);
+            if (!isAborted && sessionKey && sinkProducedOutput) {
                 try {
                     // 找到本轮最后一条 assistant
                     const tailMessages = readSessionHistoryTail(sessionKey, {
@@ -323,16 +556,43 @@ export function createStreamReplyConfig(opts, prefixOptions, signalCtx) {
     // ────────────────────────────────────────
     const replyOptions = {
         ...prefixOptions,
-        /** AI 每产 token 回调，计算增量后 emit stream_chunk。 */
+        /**
+         * AI 每产 token 回调，计算增量后进 Coalescer：
+         *   - 首帧（flushFirstFrame=true）立即 emit，保证首字延迟 < 100ms
+         *   - 后续追加到 buffer，达到 minChars 即 flush；否则 idle 超过 idleMs 兜底 flush
+         *   - 详见 ADR-017
+         */
         onPartialReply: (payload) => {
             if (completed || !payload.text)
                 return;
             ensureTypingStart();
+            if (sinkStartAt === 0)
+                sinkStartAt = Date.now();
             const delta = toStreamDeltaText(partialReplyState, payload.text);
-            if (delta) {
-                streamedText += delta;
-                emitSignal(signalCtx, "stream_chunk", delta);
-                emittedUserVisible = true;
+            if (!delta)
+                return;
+            // 当前合并周期内的模型 token 增量计数 +1（emit 时清零并打入日志）
+            pendingTokenCount++;
+            streamedText += delta;
+            // 不聚合模式（兜底回滚开关）：minChars/idleMs 任一为 0 时退化为每帧立即 emit
+            if (coalesceCfg.minChars <= 0 || coalesceCfg.idleMs <= 0) {
+                emitChunk(delta, firstFrameEmitted ? "size" : "first");
+                firstFrameEmitted = true;
+                return;
+            }
+            // 首帧立即 flush（含 buffer 中可能已有的内容，但通常为空）
+            if (!firstFrameEmitted && coalesceCfg.flushFirstFrame !== false) {
+                firstFrameEmitted = true;
+                coalesceBuf += delta;
+                flushCoalesceBuffer("first");
+                return;
+            }
+            coalesceBuf += delta;
+            if (coalesceBuf.length >= coalesceCfg.minChars) {
+                flushCoalesceBuffer("size");
+            }
+            else {
+                armIdleTimer();
             }
         },
         /**
@@ -343,13 +603,43 @@ export function createStreamReplyConfig(opts, prefixOptions, signalCtx) {
         onToolStart: (payload) => {
             if (completed)
                 return;
+            // SDK 在 phase=start 和 phase=update 都会回调；只在 start 时认为是"新一次工具调用"，
+            // update 仅作为同一 stepId 的中间态，不重新计 seq、不发 running 帧（避免重复）。
+            const toolPhase = payload.phase ?? "";
+            if (toolPhase !== "start") {
+                // 仍然透传 tool_start 帧（向下兼容旧前端的 update 渲染），但不动 thinking_step。
+                const toolNameForUpdate = payload.name ?? "unknown";
+                log?.info(`[${CHANNEL_KEY}] [stream] onToolStart: name=${toolNameForUpdate} phase=${toolPhase} (skip thinking_step)`);
+                emitSignal(signalCtx, "tool_start", "\n\n", { toolName: toolNameForUpdate, toolPhase, ...groupSignalExtra }, buildGroupDataExtra('delta'));
+                return;
+            }
             toolStartCount++;
+            // 强制 flush：前端按"先文本→后工具卡"渲染，buffer 残留若不先发出去会被工具卡插队。
+            flushCoalesceBuffer("tool");
             const toolName = payload.name ?? "unknown";
-            const toolPhase = payload.phase ?? "";
+            const args = payload.args;
             const isSubagentSpawn = SUBAGENT_TOOL_NAMES.has(toolName);
-            log?.info(`[${CHANNEL_KEY}] [stream] onToolStart: name=${toolName} phase=${toolPhase}` +
+            const argsKeys = args ? Object.keys(args).join(",") : "(none)";
+            log?.info(`[${CHANNEL_KEY}] [stream] onToolStart: name=${toolName} phase=${toolPhase} argsKeys=${argsKeys}` +
                 (isSubagentSpawn ? " (subagent-spawn)" : ""));
-            emitSignal(signalCtx, "tool_start", "\n\n", { toolName, toolPhase });
+            emitSignal(signalCtx, "tool_start", "\n\n", { toolName, toolPhase, ...groupSignalExtra }, buildGroupDataExtra('delta'));
+            // 追加 thinking_step running 帧：和 tool_start 同步发出，前端可二选一渲染。
+            // stepId 缓存到 lastToolStepId，onItemEvent(completed) 没拿到 itemId 时回退使用。
+            const stepId = genStepId(toolStartCount, toolName);
+            lastToolStepId = stepId;
+            lastToolName = toolName;
+            // 分配并记录 seq；done 帧复用此 seq 保证合并行的时间线位置稳定。
+            thinkingSeqCounter += 1;
+            const seq = thinkingSeqCounter;
+            thinkingStepSeqMap.set(stepId, seq);
+            // 取走上一次 onItemEvent(start) 预热的 meta/title 作为 running 文案兜底，
+            // 取后立即清空，避免被下一次调用误用。
+            const fallbackMeta = pendingItemMeta ?? undefined;
+            const fallbackTitle = pendingItemTitle ?? undefined;
+            pendingItemMeta = null;
+            pendingItemTitle = null;
+            const runningStep = buildRunningStep(stepId, seq, toolName, args, fallbackMeta, fallbackTitle);
+            emitSignal(signalCtx, "thinking_step", "", groupSignalExtra, { ...buildGroupDataExtra('delta'), step: runningStep });
         },
         onReplyStart: () => {
             if (completed)
@@ -359,6 +649,10 @@ export function createStreamReplyConfig(opts, prefixOptions, signalCtx) {
         onAgentRunStart: (runId) => {
             if (completed)
                 return;
+            // 群聊场景：若外部未预设 runId，用 SDK 返回的 runId 回填
+            if (isGroupMode && !optRunId && runId) {
+                knownRunId = runId;
+            }
             log?.info(`[${CHANNEL_KEY}] [stream] Agent run started: runId=${runId}`);
         },
         /**
@@ -396,6 +690,10 @@ export function createStreamReplyConfig(opts, prefixOptions, signalCtx) {
             if (completed)
                 return;
             assistantMessageCount++;
+            // 强制 flush：切轮前若不发出 buffer 残留，旋转 streamedText 时会丢失这段未发的字符。
+            flushCoalesceBuffer("round");
+            // 切轮意味着"上一段语义已结束"，重置首帧标记，让下一段开头的首字也能立即可见。
+            firstFrameEmitted = false;
             if (streamedText)
                 streamedHistory.push(streamedText);
             partialReplyState = createDeltaTrackerState();
@@ -421,6 +719,45 @@ export function createStreamReplyConfig(opts, prefixOptions, signalCtx) {
             if (completed)
                 return;
             log?.info(`[${CHANNEL_KEY}] [stream] onItemEvent: ${JSON.stringify(payload)}`);
+            // SDK 在 exec 工具上会同时发 kind=tool 和 kind=command 两份事件，载荷高度重复。
+            // 只采 kind=tool（缺省视为 tool），过滤掉 kind=command 避免时间线重复行。
+            const kind = payload.kind ?? "tool";
+            if (kind === "command")
+                return;
+            // start 帧：预热缓存 meta/title，供紧随其后的 onToolStart 拼 running 文案。
+            // （实测时序：onItemEvent(start) → onToolStart，间隔毫秒级；工具调用串行不会交叉。）
+            const phase = payload.phase ?? "";
+            if (phase === "start") {
+                pendingItemMeta = payload.meta?.trim() || null;
+                pendingItemTitle = payload.title?.trim() || null;
+                return;
+            }
+            // 仅终态事件触发 thinking_step done/error 帧；中间态（running / progress）暂不映射，
+            // 避免协议面被 SDK 内部 phase 噪音污染。
+            const status = payload.status ?? "";
+            const isTerminal = status === "completed" ||
+                status === "done" ||
+                status === "failed" ||
+                status === "error" ||
+                status === "cancelled";
+            if (!isTerminal)
+                return;
+            // stepId 关联策略（重要）：
+            // 实测 openclaw `onItemEvent` 里的 `payload.itemId` 与 `onToolStart` 时生成的
+            // stepId 完全对不上（SDK 内部随机分配），如果直接把 itemId 当 stepId 透传出去，
+            // 前端按 stepId 合并行就永远落空，结果就是"running 一行 + done 又起一行"。
+            // 因此优先复用 running 时缓存的 lastToolStepId，保证 done 帧能就地覆盖到 running 那一行。
+            // 仅当不存在 lastToolStepId（极端兜底）时才退回到 itemId / "item-unknown"。
+            const fallbackStepId = `item-${payload.itemId ?? "unknown"}`;
+            const stepId = lastToolStepId ?? payload.itemId ?? fallbackStepId;
+            // 复用 running 时分配的 seq，保证合并行不漂移。
+            let seq = thinkingStepSeqMap.get(stepId);
+            if (seq === undefined) {
+                thinkingSeqCounter += 1;
+                seq = thinkingSeqCounter;
+            }
+            const doneStep = buildDoneStep(payload, stepId, seq, lastToolName ?? undefined);
+            emitSignal(signalCtx, "thinking_step", "", groupSignalExtra, { ...buildGroupDataExtra('delta'), step: doneStep });
         },
         onTypingCleanup: () => {
             log?.info(`[${CHANNEL_KEY}] [stream] onTypingCleanup: counts=${JSON.stringify(counts)} ` +
@@ -435,5 +772,15 @@ export function createStreamReplyConfig(opts, prefixOptions, signalCtx) {
         replyOptions,
         // 业务辅助：独立于 openclaw ReplyDispatcher 契约暴露，避免污染 dispatcher
         hasEmittedContent: () => emittedUserVisible,
+        // 群聊场景下暴露 emitStart / getRunId，私聊场景为 no-op
+        emitStart: ensureTypingStart,
+        getRunId: () => knownRunId,
+        // 获取本次 run 的最终完整文本（聚合所有轮次），供 AgentRunner 返回给上层写入账本
+        getFinalText: () => {
+            if (streamedHistory.length > 0) {
+                return [...streamedHistory, streamedText].filter(Boolean).join('\n');
+            }
+            return streamedText;
+        },
     };
 }