lightclawbot 1.2.7 → 1.2.9

package/dist/src/config.js

@@ -55,9 +55,36 @@ let globalApiKeyMap = new Map();
 let globalDefaultApiKey = '';
 /** sessionKey → apiKey 直接映射（inbound 处理时写入，tool 执行时读取） */
 const sessionKeyToApiKey = new Map();
-/** 设置 apiKeyMap（gateway 启动时调用） */
-export function setApiKeyMap(map, defaultApiKey) {
-    globalApiKeyMap = map;
+/** 合并单条 account 的 apiKey 到全局映射（gateway 启动时调用） */
+export function addApiKeyToMap(accountId, apiKey) {
+    globalApiKeyMap.set(accountId, apiKey);
+    // 仅在尚未设置 defaultApiKey 时设置（取第一个 account 的 key 作为默认）
+    if (!globalDefaultApiKey) {
+        globalDefaultApiKey = apiKey;
+    }
+}
+/**
+ * 一次性构建全局 apiKeyMap（插件初始化时调用）。
+ *
+ * 遍历配置中所有 accounts，将 accountId→apiKey 映射一次性写入全局 Map，
+ * 避免每个 account 启动 gateway 时覆盖其他 account 的映射。
+ *
+ * @param cfg - OpenClaw 全局配置对象
+ */
+export function buildGlobalApiKeyMap(cfg) {
+    const channels = cfg?.channels;
+    const channelConfig = channels?.[CHANNEL_KEY];
+    if (!channelConfig?.accounts)
+        return;
+    const accounts = channelConfig.accounts;
+    let defaultApiKey = globalDefaultApiKey; // 保留已有的 default
+    for (const [accountId, accountConfig] of Object.entries(accounts)) {
+        if (accountConfig?.apiKey) {
+            globalApiKeyMap.set(accountId, accountConfig.apiKey);
+            if (!defaultApiKey)
+                defaultApiKey = accountConfig.apiKey;
+        }
+    }
     globalDefaultApiKey = defaultApiKey;
 }
 /** 记录 sessionKey → apiKey 映射（inbound 处理消息时调用） */

package/dist/src/gateway.js

@@ -13,7 +13,7 @@
  *   媒体文件处理 → media.ts
  */
 import { NativeSocketClient } from './socket/native-socket.js';
-import { CHANNEL_KEY, WS_URL, API_BASE_URL, SOCKET_PATH, API_PATH_USER_CURRENT, EVENT_MESSAGE_PRIVATE, HEALTH_HEARTBEAT_INTERVAL, setApiKeyMap, } from './config.js';
+import { CHANNEL_KEY, WS_URL, API_BASE_URL, SOCKET_PATH, API_PATH_USER_CURRENT, EVENT_MESSAGE_PRIVATE, HEALTH_HEARTBEAT_INTERVAL, addApiKeyToMap, buildGlobalApiKeyMap, } from './config.js';
 import { generateMsgId } from './dedup.js';
 import { createInboundHandler } from './inbound.js';
 import { bindSocketHandlers, registerSocket, unregisterSocket, flushPendingMessages } from './socket/index.js';
@@ -95,7 +95,7 @@ async function resolveBotClientId(apiKey, log) {
  * @param ctx - Gateway 上下文，包含账户配置、abort 信号和生命周期回调
  */
 export async function startGateway(ctx) {
-    const { account, abortSignal, onReady, onDisconnect, onEvent, log } = ctx;
+    const { account, abortSignal, cfg, onReady, onDisconnect, onEvent, log } = ctx;
     const prefix = `[${CHANNEL_KEY}:${account.accountId}]`;
     // 判断是否存在有效的apikey
     if (!account.apiKey) {
@@ -113,11 +113,13 @@ export async function startGateway(ctx) {
     // 新配置格式：accountId 即为 uin，apiKey 与 uin 一一对应，直接构建映射表
     log?.info(`${prefix} Resolving botClientId for account ${account.accountId}...`);
     const { botClientId, ticket } = await resolveBotClientId(account.apiKey, log);
-    // 构建 uin→apiKey 映射表（新格式下每个 account 只有一条记录）
-    const apiKeyMap = new Map([[account.accountId, account.apiKey]]);
+    // 一次性构建全局 uin→apiKey 映射（遍历所有 accounts，幂等操作）
+    // 解决多账号场景下每个 gateway 启动时覆盖全局 Map 的问题
+    buildGlobalApiKeyMap(cfg);
+    // 将当前 account 的 uin→apiKey 映射合并到全局 config 模块
+    // 确保 gateway 重启/reconnect 时映射仍然完整
+    addApiKeyToMap(account.accountId, account.apiKey);
     log?.info(`${prefix} Bot clientId: ${botClientId}, uin=${account.accountId} → apiKey=***${account.apiKey.slice(-4)}`);
-    // 将映射表写入全局 config 模块，供 inbound 处理时按 uin 查找对应 apiKey
-    setApiKeyMap(apiKeyMap, account.apiKey);
     /** Gateway 是否已被 abort（用于终止消息处理循环） */
     let isAborted = false;
     /** 当前活跃的 WebSocket 实例（断线时为 null） */

package/dist/src/history/message-parser.js

@@ -210,6 +210,28 @@ export function normalizeMessage(msg) {
         const allFiles = [...(textFiles.length > 0 ? textFiles : []), ...(contentFiles ?? [])];
         if (allFiles.length > 0)
             files = deduplicateFiles(allFiles);
+        // 修复：当用户消息有 MediaPath/MediaPaths（OpenClaw 存在附件文件）
+        // 但 files 里没有 uri 时，补上 localfile:// 格式的 uri
+        if (!files || files.some((f) => !f.uri)) {
+            const mediaPaths = Array.isArray(msg.MediaPaths)
+                ? msg.MediaPaths
+                : (typeof msg.MediaPath === "string" ? [msg.MediaPath] : []);
+            if (mediaPaths.length > 0) {
+                const existingFiles = files ?? [];
+                const needInit = existingFiles.length === 0;
+                const updatedFiles = needInit
+                    ? mediaPaths.map((p, i) => ({
+                        name: existingFiles[i]?.name ?? p.split("/").pop() ?? `file-${i}`,
+                        mimeType: existingFiles[i]?.mimeType,
+                        uri: `localfile://${p}`,
+                    }))
+                    : existingFiles.map((f, i) => ({
+                        ...f,
+                        uri: f.uri ?? (mediaPaths[i] ? `localfile://${mediaPaths[i]}` : undefined),
+                    }));
+                files = updatedFiles;
+            }
+        }
     }
     else {
         files = extractContentFiles(msg.content) || undefined;

package/dist/src/history/session-reader.js

@@ -338,8 +338,14 @@ function parseLines(lines, opts) {
             if (!msg || typeof msg !== "object")
                 continue;
             // 过滤 openclaw delivery-mirror 消息（镜像投递，非真实消息）
-            if (msg.model === "delivery-mirror")
-                continue;
+            // 但对 cron 直接投递的消息放行（用户需要看到定时提醒内容）
+            if (msg.model === "delivery-mirror") {
+                const idempotencyKey = msg.idempotencyKey
+                    ?? parsed.idempotencyKey;
+                if (!idempotencyKey || !idempotencyKey.startsWith("cron-direct-delivery:")) {
+                    continue;
+                }
+            }
             // 过滤传输层伪装为 user 的系统注入消息
             if (isSystemInjectedUserMessage(msg))
                 continue;

package/dist/src/outbound.js

@@ -84,17 +84,52 @@ function sendViaSocket(accountId, target, text, replyToId) {
     // 从 socket-registry 中获取当前账户的 socket entry
     const entry = getSocket(resolvedAccountId);
     const msgId = generateOutboundMsgId();
-    // 构造标准消息体，格式与 gateway 入站消息保持一致
+    const fromId = entry?.botClientId ?? getBotClientId(resolvedAccountId) ?? '';
+    // 构造标准消息体，格式与 gateway 入站消息保持一致。
+    //
+    // 协议关键字段说明：
+    //   - kind: 'stream_chunk'
+    //       outbound 由 LLM 工具调用结果（如 message 工具发图/发文）触发，
+    //       归属于"流式回复信号链"的一部分，前端依赖 kind 推导消息状态
+    //       （stream_chunk → 'updating'）。若缺省，前端 statusMap 会兜底到
+    //       typing_stop=='success'，导致内容被独立成一条"已完成回复"气泡，
+    //       与上一段 LLM 文本（已 typing_stop）错位拼接。详见 stream-reply-sink。
+    //   - extra.chatId: ''
+    //       协议规定所有 EVENT_MESSAGE_PRIVATE 必须携带 extra.chatId（多会话分桶）。
+    //       outbound 触发时通常无明确 chatId 上下文（cron / message 工具 / REST 等），
+    //       按协议约定填空字符串落到默认会话。
+    //   - idempotencyKey: 由 ReliableEmitter 在 emitWithAck 内部注入，此处无需显式构造。
     const message = {
         msgId,
         // 优先使用 entry 中缓存的 botClientId，entry 不存在时从 registry 直接查询
-        from: entry?.botClientId ?? getBotClientId(resolvedAccountId) ?? '',
+        from: fromId,
         to: target,
         content: text,
         timestamp: Date.now(),
+        kind: 'stream_chunk',
         // undefined 表示非回复消息，避免发送多余字段
         replyToMsgId: replyToId ?? undefined,
+        extra: { chatId: '' },
     };
+    // 自闭合 typing_stop 帧：与 stream_chunk 共用同一个 msgId / chatId，
+    // content 必须为空字符串（前端 addOrUpdateMessage 会按 oldContent + content 拼接，
+    // 非空 content 会让 caption 文本被复制一遍）。
+    //
+    // 设计理由：
+    //   outbound 通道（如 message 工具调用结果）由 OpenClaw 框架以「独立 messageId」投递，
+    //   不会与上一段 LLM 流式回复合并。仅发 stream_chunk 而无 typing_stop，
+    //   会导致前端这条独立气泡永远停留在 'updating' 状态（loading 转圈）。
+    //   故每条 outbound 消息都自带一帧 typing_stop 收尾，让该气泡正常进入 'success'。
+    const buildClosingFrame = () => ({
+        msgId,
+        from: fromId,
+        to: target,
+        content: '',
+        timestamp: Date.now(),
+        kind: 'typing_stop',
+        replyToMsgId: replyToId ?? undefined,
+        extra: { chatId: '' },
+    });
     if (entry) {
         // 策略 1：Socket 已连接，优先走可靠发送（emitWithAck + 自动重试）
         const emitter = getReliableEmitter(resolvedAccountId);
@@ -105,12 +140,24 @@ function sendViaSocket(accountId, target, text, replyToId) {
                     logger.error(`[${CHANNEL_KEY}] outbound delivery failed after retries: msgId=${msgId}`);
                 }
             });
+            // 紧跟一帧 typing_stop 闭合该 msgId 的流式状态。
+            // ReliableEmitter 内部按 emit 顺序生成 idempotencyKey（字典序 == emit 顺序），
+            // 即便网络层 batch 抖动导致 packet 乱序到达，前端也能按字典序合并出
+            // 「stream_chunk 在前 → typing_stop 在后」的稳定终态。
+            const closingFrame = buildClosingFrame();
+            emitter.emitWithAck(EVENT_MESSAGE_PRIVATE, closingFrame, msgId).then((ok) => {
+                if (!ok) {
+                    logger.warn(`[${CHANNEL_KEY}] outbound closing frame ack timeout: msgId=${msgId}`);
+                }
+            });
             logger.info(`[${CHANNEL_KEY}] outbound sent via reliable WS: to=${target} msgId=${msgId}`);
             return msgId;
         }
         // 策略 2：可靠发送器不可用，直接 emit（兜底，正常情况不应走到此分支）
         try {
             entry.socket.emit(EVENT_MESSAGE_PRIVATE, message);
+            // 同样补一帧 typing_stop；裸 emit 无 ack，无法保证送达，best-effort 即可。
+            entry.socket.emit(EVENT_MESSAGE_PRIVATE, buildClosingFrame());
             logger.info(`[${CHANNEL_KEY}] outbound sent via WS (fallback): to=${target} msgId=${msgId}`);
             return msgId;
         }
@@ -125,6 +172,10 @@ function sendViaSocket(accountId, target, text, replyToId) {
     if (hasEntry(resolvedAccountId)) {
         const buffered = bufferMessage(resolvedAccountId, message);
         if (buffered) {
+            // 顺序 push 一帧 typing_stop，flush 时随业务消息一起按 FIFO 发出。
+            // bufferMessage 失败（队列满）则跳过闭合帧 —— 主消息都没缓冲住，
+            // 闭合帧也没意义；前端会因永远收不到 stream_chunk 而不展示这条气泡。
+            bufferMessage(resolvedAccountId, buildClosingFrame());
             logger.info(`[${CHANNEL_KEY}] outbound buffered (WS reconnecting): to=${target} msgId=${msgId}`);
             return msgId;
         }

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

@@ -17,6 +17,7 @@ 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";
@@ -32,6 +33,56 @@ const LOCALIZED_ABORT_REPLY = "已停止当前回复。";
 function localizeAbortReplyText(text) {
     return OPENCLAW_ABORT_REPLY_RE.test(text.trim()) ? LOCALIZED_ABORT_REPLY : text;
 }
+/** 已知的图片扩展名集合，用于判断是否走 files 渲染（而非 markdown 文本链接）。 */
+const IMAGE_EXTS = new Set(["png", "jpg", "jpeg", "gif", "webp", "svg", "bmp", "ico"]);
+/**
+ * 判断 URL 指向的资源是否为图片（基于文件扩展名）。
+ *
+ * 优先匹配 COS 公网 URL 中的 `filePath=xxx` query 参数；
+ * 回退到 URL 末段。判断失败一律按"非图片"处理（保留文本链接，前端兼容性更好）。
+ */
+function isImageUrl(url) {
+    let candidate = url;
+    const filePathMatch = url.match(/filePath=([^&]+)/);
+    if (filePathMatch) {
+        try {
+            candidate = decodeURIComponent(filePathMatch[1]);
+        }
+        catch {
+            candidate = filePathMatch[1];
+        }
+    }
+    const lastDot = candidate.lastIndexOf(".");
+    if (lastDot < 0)
+        return false;
+    const ext = candidate.slice(lastDot + 1).split(/[?#]/)[0].toLowerCase();
+    return IMAGE_EXTS.has(ext);
+}
+/**
+ * 对 mediaUrls 入口去重：同一文件常以裸路径 `/path/to/x.png` 和带前缀
+ * `file:///path/to/x.png` 两种形式同时出现（如 browser screenshot toolResult），
+ * 不归一就会让前端同时渲染两份"全部文件"卡片（即用户看到的"两个全部文件按钮"）。
+ *
+ * 归一规则：
+ *   - 去掉 `file://` 前缀做"路径键"比较；
+ *   - 保留首次出现的原始字符串（保留 `file://` 与否取决于 mediaList 顺序），
+ *     避免破坏后续 `existsSync` / `mediaUrlsToFiles` 对路径形态的处理。
+ *
+ * 不做内容级去重（buffer hash），因为 data URL 与本地路径同图的归一代价较高，
+ * 且配合"图片不再重复拼 markdown"已能消除可见的重复渲染。
+ */
+function dedupMediaUrls(urls) {
+    const seen = new Set();
+    const result = [];
+    for (const url of urls) {
+        const key = url.startsWith("file://") ? url.slice(7) : url;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        result.push(url);
+    }
+    return result;
+}
 export function createStreamReplyConfig(opts, prefixOptions, signalCtx) {
     const { emitter, targetId, originalMsgId, log, effectiveApiKey, typingAlreadyStarted, sessionKey, agentId } = opts;
     // ── 群聊扩展字段 ──
@@ -80,6 +131,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;
@@ -221,25 +287,44 @@ export function createStreamReplyConfig(opts, prefixOptions, signalCtx) {
         }
     };
     /**
-     * 处理 payload 中的 mediaUrls：COS 上传 → 拼 Markdown 链接 → 推送给用户。
+     * 处理 payload 中的 mediaUrls：去重 → COS 上传 → 与文本同帧推送给用户。
      * 仅在 mediaList 非空时调用。
      *
-     * 群聊模式：通过 stream_chunk 信号帧推送 Markdown 图片/文件链接（带群聊 extra）。
-     * 私聊模式：通过 emitter.sendFiles / emitter.sendReply 推送。
+     * 私聊 / 群聊统一通过 `emitSignal('stream_chunk', ...)` 走信号链，
+     * 复用本轮 replyMsgId（与 stream_chunk 文本同 msgId 合并到同一气泡），
+     * 同时携带 kind / agentId / extra.chatId / chatKind 等协议字段，
+     * 避免前端因 kind 缺失而把媒体帧兜底为 typing_stop 完成态独立气泡。
+     *
+     * 协议约定：
+     *   - 图片由顶层 `files` 字段独家承载（前端文件卡片渲染），
+     *     文本里**不再**额外拼 `![](url)` markdown，避免"两张图"重复渲染。
+     *   - 非图片文件（pdf / 压缩包等）保留 `📎 [filename](url)` 文本链接，
+     *     方便用户复制公网 URL，同时仍透传 files 给前端文件卡片。
      */
     const handleMediaFinal = async (replyText, mediaList) => {
-        const files = await mediaUrlsToFiles(mediaList, log);
+        // 去重：mediaUrls 常包含同一文件的多种引用（裸路径 / file:// 前缀），
+        // 归一后再交给下游处理，避免 files 数组与 publicUrls 数组各自重复一次。
+        const dedupedMediaList = dedupMediaUrls(mediaList);
+        const files = await mediaUrlsToFiles(dedupedMediaList, log);
         const storageConfig = { apiKey: effectiveApiKey };
-        const publicUrls = [];
-        for (const mediaUrl of mediaList) {
+        /** 仅非图片文件需要在文本里给出公网链接，图片由 files 渲染。 */
+        const nonImagePublicLinks = [];
+        for (const mediaUrl of dedupedMediaList) {
             try {
                 const localPath = mediaUrl.startsWith("file://") ? mediaUrl.slice(7) : mediaUrl;
                 if (localPath.startsWith("/") || localPath.match(/^[A-Za-z]:\\/)) {
                     const { existsSync } = await import("node:fs");
                     if (existsSync(localPath)) {
                         const result = await uploadFileToServer(localPath, storageConfig);
-                        publicUrls.push(result.url || "");
-                        log?.info(`[${CHANNEL_KEY}] [stream] Uploaded to COS: ${localPath} → ${result.url}`);
+                        const publicUrl = result.url || "";
+                        log?.info(`[${CHANNEL_KEY}] [stream] Uploaded to COS: ${localPath} → ${publicUrl}`);
+                        // 仅非图片文件保留文本链接（图片由 files 渲染，避免重复）
+                        if (publicUrl && !isImageUrl(publicUrl)) {
+                            const match = publicUrl.match(/filePath=([^&]+)/);
+                            const filePath = match ? decodeURIComponent(match[1]) : "";
+                            const fileName = filePath.split("/").pop() || "file";
+                            nonImagePublicLinks.push(`📎 [${fileName}](${publicUrl})`);
+                        }
                     }
                 }
             }
@@ -248,41 +333,33 @@ 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})` : ""}`;
-                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");
+        if (nonImagePublicLinks.length > 0) {
+            const urlSection = nonImagePublicLinks.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`);
-            }
+        // 没有任何可见内容（既无文本又无文件）→ 直接返回，避免发空帧
+        if (!enrichedText.trim() && files.length === 0) {
             return;
         }
-        // ── 私聊模式：通过 sendFiles / sendReply 推送 ──
-        if (files.length > 0) {
-            emitter.sendFiles(targetId, enrichedText, files, originalMsgId, signalCtx.chatId);
-            emittedUserVisible = true;
-        }
-        else if (enrichedText.trim()) {
-            emitter.sendReply(targetId, enrichedText, originalMsgId, signalCtx.chatId);
+        // ── 群聊模式：通过 stream_chunk 推送（带群聊 extra） ──
+        // 群聊额外把文本累加到 streamedText，让 markComplete 的 aggregatedText 能算上这段。
+        if (isGroupMode) {
+            const delta = enrichedText.trim() ? `\n\n${enrichedText}` : "";
+            if (delta)
+                streamedText += delta;
+            emitSignal(signalCtx, "stream_chunk", delta, { ...(files.length > 0 ? { files } : {}), ...groupSignalExtra }, buildGroupDataExtra('delta'));
             emittedUserVisible = true;
+            log?.info(`[${CHANNEL_KEY}] [stream] handleMediaFinal(group): pushed ${files.length} file(s), ` +
+                `nonImageLinks=${nonImagePublicLinks.length}`);
+            return;
         }
+        // ── 私聊模式：同样通过 stream_chunk 走信号链 ──
+        // 关键：复用 signalCtx.replyMsgId → 与本轮 stream_chunk 文本同 msgId 合并，
+        //       且自动携带 kind/agentId/extra.chatId，前端不再兜底为 typing_stop。
+        emitSignal(signalCtx, "stream_chunk", enrichedText, files.length > 0 ? { files } : undefined);
+        emittedUserVisible = true;
+        log?.info(`[${CHANNEL_KEY}] [stream] handleMediaFinal: pushed ${files.length} file(s) via stream_chunk, ` +
+            `textLen=${enrichedText.length} nonImageLinks=${nonImagePublicLinks.length}`);
     };
     // ────────────────────────────────────────
     // dispatcher
@@ -485,11 +562,19 @@ export function createStreamReplyConfig(opts, prefixOptions, signalCtx) {
             }
             // 在 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, {
@@ -579,15 +664,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, ...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)
@@ -667,6 +780,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)} ` +

package/dist/src/streaming/thinking-formatter.js

@@ -0,0 +1,325 @@
+/**
+ * LightClaw — 思考过程帧（thinking_step）格式化模块
+ *
+ * 职责：把 openclaw 的工具回调（onToolStart / onItemEvent）翻译成
+ * 协议契约里的 `extra.step` 载荷。前端据此渲染：
+ *
+ *   💭 接下来将先执行端口检查，确认浏览器启动状态。     ← stream_chunk（旁白）
+ *   🔧 执行了 exec: lsof -i :9222                      ← thinking_step running
+ *   💭 已找到 9222 端口 PID = 12345                    ← thinking_step done
+ *
+ * 协议见 docs/thinking-step-protocol.md。
+ */
+// ── 工具名 → 类型/中文短句映射 ──
+//
+// 命中规则按"前缀"匹配，避免 sessions_spawn / sessions.spawn 这种命名差异。
+const TOOL_TYPE_RULES = [
+    { test: (n) => n === "exec" || n.startsWith("exec_"), type: "cmd", verb: "执行命令" },
+    { test: (n) => n.startsWith("browser"), type: "browser", verb: "操作浏览器" },
+    { test: (n) => n === "apply_patch" || n.startsWith("str_replace") || n === "edit_file" || n === "write_file", type: "patch", verb: "编辑文件" },
+    { test: (n) => n === "read" || n === "read_file" || n === "view_code_item", type: "tool", verb: "查看文件" },
+    { test: (n) => n.startsWith("web_") || n === "fetch", type: "tool", verb: "访问网页" },
+    { test: (n) => n.includes("session") && n.includes("spawn"), type: "subagent", verb: "派发子任务" },
+    { test: (n) => n === "subagents", type: "subagent", verb: "派发子任务" },
+    { test: (n) => n === "update_plan" || n === "plan", type: "plan", verb: "更新计划" },
+];
+/** 把工具名映射成行级类型 + 默认中文动作短句。 */
+function classifyTool(toolName) {
+    for (const rule of TOOL_TYPE_RULES) {
+        if (rule.test(toolName))
+            return { type: rule.type, verb: rule.verb };
+    }
+    return { type: "tool", verb: `调用 ${toolName}` };
+}
+/** stepId 生成器：调用方应在每次 onToolStart 时调用一次，把返回值缓存到 lastToolStepId 上。 */
+export function genStepId(seed, toolName) {
+    return `step-${seed}-${toolName.replace(/[^a-zA-Z0-9_]/g, "_")}`;
+}
+/**
+ * 把 args 摘要成一行人类可读的字符串。优先级：
+ *   command/cmd/shell > path/file_path/target_file > url/targetUrl > query/keyword > name/title > action > 任意非空字符串
+ *
+ * 注意 `action` 这种枚举型动词字段（值通常是 "open" / "click" 等单词）被刻意降权，
+ * 否则会把更有信息量的 url/targetUrl 压住，导致 running 文案退化为 "执行了 操作浏览器: open"。
+ *
+ * 超长内容会被截断到 160 字符（后接 …），避免占满前端时间线一行。
+ */
+const ARG_SUMMARY_MAX_LEN = 160;
+const ARG_PRIORITY_KEYS = [
+    // 命令/路径类（最有信息量）
+    "command",
+    "cmd",
+    "shell",
+    "path",
+    "file_path",
+    "filepath",
+    "filePath",
+    "target_file",
+    // URL 类（browser 工具常用 targetUrl）
+    "url",
+    "targetUrl",
+    "target_url",
+    "href",
+    // 检索/关键词类
+    "query",
+    "keyword",
+    "text",
+    // 标识符类
+    "name",
+    "title",
+    // 元素定位类（browser 点击/输入常用 targetId / selector）
+    "targetId",
+    "target_id",
+    "selector",
+    // 枚举动词（信息量最低，放最后兜底）
+    "action",
+];
+function truncate(text) {
+    if (text.length <= ARG_SUMMARY_MAX_LEN)
+        return text;
+    return `${text.slice(0, ARG_SUMMARY_MAX_LEN)}…`;
+}
+function summarizeArgs(args) {
+    if (!args || typeof args !== "object")
+        return "";
+    // 1. 优先级 key 命中
+    for (const key of ARG_PRIORITY_KEYS) {
+        const val = args[key];
+        if (typeof val === "string" && val.trim()) {
+            return truncate(val.trim());
+        }
+    }
+    // 2. 任何非空字符串字段
+    for (const [, val] of Object.entries(args)) {
+        if (typeof val === "string" && val.trim()) {
+            return truncate(val.trim());
+        }
+    }
+    // 3. 兜底：序列化整个对象
+    try {
+        const json = JSON.stringify(args);
+        if (json && json !== "{}")
+            return truncate(json);
+    }
+    catch {
+        // 循环引用等场景，忽略
+    }
+    return "";
+}
+// ── browser 工具特化文案 ──
+//
+// 根因：browser 工具下不同 action 对应的有效字段差异很大——
+//   - open  用 targetUrl（用户能识别的 URL）
+//   - click 用 targetId（DOM 元素内部句柄，如 "t1"，无语义信息）
+//   - type  用 text（输入内容）
+//   - scroll/back/forward/screenshot 等几乎没有可读字段
+//
+// 通用 ARG_PRIORITY_KEYS 把这些字段放同一优先级，导致 click 文案退化为
+// "执行了 操作浏览器: t1" 这类用户完全不知所云的内容。这里按 action 分支
+// 显式映射 verb 与可见字段，避免把内部句柄搬到时间线上。
+const BROWSER_ACTION_VERBS = {
+    open: "打开网页",
+    navigate: "打开网页",
+    goto: "打开网页",
+    click: "点击页面元素",
+    tap: "点击页面元素",
+    type: "输入文本",
+    fill: "输入文本",
+    input: "输入文本",
+    scroll: "滚动页面",
+    back: "返回上一页",
+    forward: "前进",
+    reload: "刷新页面",
+    refresh: "刷新页面",
+    screenshot: "页面截图",
+    snapshot: "页面截图",
+    close: "关闭页面",
+};
+/**
+ * 按 browser action 生成 {verb, summary}。
+ * - 命中已知 action：返回特化 verb，且 summary 仅取真正有用户语义的字段（targetId 等内部句柄不进文案）。
+ * - 未命中（含 args 缺失 / action 不在白名单）：返回 null，由调用方回退到通用 summarizeArgs。
+ */
+function summarizeBrowserArgs(args) {
+    if (!args || typeof args !== "object")
+        return null;
+    const action = args.action;
+    if (typeof action !== "string" || !action.trim())
+        return null;
+    const verb = BROWSER_ACTION_VERBS[action.toLowerCase()];
+    if (!verb)
+        return null;
+    const pickString = (...keys) => {
+        for (const k of keys) {
+            const v = args[k];
+            if (typeof v === "string" && v.trim())
+                return truncate(v.trim());
+        }
+        return "";
+    };
+    let summary = "";
+    switch (action.toLowerCase()) {
+        case "open":
+        case "navigate":
+        case "goto":
+            summary = pickString("targetUrl", "url", "target_url", "href");
+            break;
+        case "click":
+        case "tap":
+            // targetId 是 DOM 内部句柄（如 "t1"），毫无可读性，刻意不进文案。
+            // 优先用 agent 自填的 description / label / name；都没有就只显示 verb。
+            summary = pickString("description", "label", "name", "selector");
+            break;
+        case "type":
+        case "fill":
+        case "input":
+            summary = pickString("text", "content", "value");
+            break;
+        // scroll / back / forward / reload / screenshot / close 一般无需附带 summary
+        default:
+            summary = "";
+    }
+    return { verb, summary };
+}
+/**
+ * 把 SDK onItemEvent 给的 title 清掉常见的 toolName 前缀，避免 "browser browser https://..." 这种重复。
+ * 例如 title="browser https://www.baidu.com/..."、toolName="browser" → 返回 "https://www.baidu.com/..."。
+ */
+function stripToolNamePrefix(title, toolName) {
+    if (!title || !toolName)
+        return title;
+    const trimmed = title.trim();
+    if (trimmed.toLowerCase().startsWith(`${toolName.toLowerCase()} `)) {
+        return trimmed.slice(toolName.length + 1).trim();
+    }
+    return trimmed;
+}
+/**
+ * T1：工具开始 → running 帧。
+ *
+ * 文案优先级（自上而下，命中即返回）：
+ *   1. args 摘要（command/path/url/targetUrl/... 见 ARG_PRIORITY_KEYS）
+ *   2. fallbackMeta（来自 SDK onItemEvent 的 payload.meta，通常是裸 URL/路径）
+ *   3. fallbackTitle（去掉 toolName 前缀后的剩余部分）
+ *   4. 兜底：仅 verb，不带摘要
+ *
+ * 设计目的：让 running 帧一次性带上有信息量的内容（如 URL），避免后续 done 帧
+ * 出现 "覆盖还是不覆盖" 的两难。done 帧仍按原策略：summary/title/meta 全空 → text 留空。
+ *
+ * @param stepId         调用方维护的步骤 ID（onToolStart 用 genStepId 生成）
+ * @param seq            时间线位置序号（由 sink 维护的全局自增计数器）
+ * @param toolName       原始工具名
+ * @param args           onToolStart 透传的工具参数（SDK 已提供）
+ * @param fallbackMeta   onItemEvent(start) 透传的 meta，args 摸不出内容时兜底
+ * @param fallbackTitle  onItemEvent(start) 透传的 title，args/meta 都摸不出内容时兜底
+ */
+export function buildRunningStep(stepId, seq, toolName, args, fallbackMeta, fallbackTitle) {
+    const { type, verb: defaultVerb } = classifyTool(toolName);
+    // browser 工具特化：按 action 选择 verb / summary，避免 targetId 这类内部句柄进入文案。
+    // 未命中（无 args / action 不在白名单）时返回 null，回退到通用路径。
+    let verb = defaultVerb;
+    let summary = "";
+    let browserHit = false;
+    if (type === "browser") {
+        const browserSummary = summarizeBrowserArgs(args);
+        if (browserSummary) {
+            verb = browserSummary.verb;
+            summary = browserSummary.summary;
+            browserHit = true;
+        }
+    }
+    // 1. 通用 args 摘要（browser 已特化命中则跳过，避免被通用规则覆盖回 targetId 等无语义内容）
+    if (!browserHit) {
+        summary = summarizeArgs(args);
+    }
+    // 2. args 没摸出内容 → meta 兜底
+    //    注意：browser 特化已命中但 summary 为空（如 screenshot / scroll / back 等无副词 action）时，
+    //    不再回退到 meta / title。原因是 SDK 在这些场景的 meta 多为内部句柄（如 "5" / "7" / "1_124"），
+    //    一旦兜底就会出现 "执行了 页面截图: 5" 这类噪音。命中即视为"verb 已经讲清楚了"。
+    if (!summary && !browserHit && fallbackMeta && fallbackMeta.trim()) {
+        summary = truncate(fallbackMeta.trim());
+    }
+    // 3. meta 也没有 → title 去前缀后兜底（同上，browser 特化命中后不再走 title）
+    if (!summary && !browserHit && fallbackTitle && fallbackTitle.trim()) {
+        const cleaned = stripToolNamePrefix(fallbackTitle, toolName);
+        if (cleaned)
+            summary = truncate(cleaned);
+    }
+    const text = summary ? `执行了 ${verb}: ${summary}` : `执行了 ${verb}`;
+    return {
+        stepId,
+        seq,
+        type,
+        text,
+        status: "running",
+        toolName,
+        detail: summary || undefined,
+    };
+}
+/**
+ * T3：工具结束 → done/error 帧。
+ *
+ * 入参来自 openclaw `onItemEvent` 的 payload，重点字段：
+ *   - itemId    备用 stepId（实测 SDK 随机生成，与 running 时的 stepId 对不上，
+ *               所以本函数优先用 fallbackStepId，由调用方传入 running 时缓存的 lastToolStepId）
+ *   - status    "completed" / "failed" / "error" / ...
+ *   - summary   一行式结果摘要（"已进入腾讯云轻量应用服务器产品页"）
+ *   - title     SDK 给的成品文案（"browser https://www.baidu.com/..."），多数场景是 running 时 URL 的回声
+ *   - meta      SDK 内部分类（多数场景与 title 同源，是 running 文案的回声）
+ *   - progressText 中间态进度文案（不适合做最终态摘要）
+ *
+ * 文案规则（见 docs/thinking-step-protocol.md，v7 收紧）：
+ *   - 成功：**只用 `summary`**（agent 真正写给用户看的结果摘要）。
+ *     summary 为空时 text 留空，前端识别为"无新文案"，仅切状态/图标 spinner→✓，
+ *     保留 running 行的原文本（避免 SDK title/meta 是 running URL 回声，覆盖后出现
+ *     "browser https://www.baidu.com/..." 这类劣化文案）。
+ *   - 失败：summary > `${verb}失败`。**不再**裸取 title / meta / progressText 作为
+ *     主文案，因为实测 SDK 在 onItemEvent(end, status=error) 的 title 常常是
+ *     `"browser"` / `"browser target t1, ref 1_124"` 这类内部句柄回声，对用户无意义。
+ *     verb 已按工具类型分类（如 "操作浏览器" / "执行命令"），保证最低有可读语义。
+ *     title/meta/progressText 改为 detail 折叠展示，方便排障但不污染主文案。
+ */
+export function buildDoneStep(payload, fallbackStepId, seq, fallbackToolName) {
+    // toolName 优先用 fallbackToolName（来自 running 时缓存的 lastToolName，已是正确值），
+    // payload.name 在 onItemEvent 里经常为空 / 取值奇怪，避免把 verb 分类带偏。
+    const toolName = fallbackToolName ?? payload.name ?? "unknown";
+    const { type, verb } = classifyTool(toolName);
+    const isError = payload.status === "failed" ||
+        payload.status === "error" ||
+        payload.status === "cancelled";
+    const summary = (payload.summary ?? "").trim();
+    const title = (payload.title ?? "").trim();
+    const meta = (payload.meta ?? "").trim();
+    const progress = (payload.progressText ?? "").trim();
+    // 成功路径：只采纳 summary（agent 总结的真摘要）。title/meta 实测多为 running 文案回声，
+    //          不再作为成功 done 的 text 来源；progress 是中间态，也不适合做最终态。
+    // 失败路径：v7 收紧 —— 不再裸取 title / meta / progressText（实测多为 SDK 内部句柄回声，
+    //          如 `"browser"` / `"browser target t1, ref 1_124"` 这类对用户无意义的内容）。
+    //          只采纳 summary（agent 写的失败原因）；缺失则用 `${verb}失败`，verb 已按工具
+    //          类型分类（如 "操作浏览器" / "执行命令"），保证有可读语义。
+    //          title/meta/progressText 改为 detail 折叠展示，方便排障但不出现在主文案。
+    const text = isError
+        ? summary || `${verb}失败`
+        : summary;
+    // detail 优先级：失败时把 SDK 的原始 title / meta / progress 拼起来供折叠查看（排障用）；
+    //               成功时仅把进度文案塞进去（与 v5 一致）。
+    let detail;
+    if (isError) {
+        const debugParts = [title, meta, progress].filter((s) => s && s !== text);
+        detail = debugParts.length > 0 ? debugParts.join(" · ") : undefined;
+    }
+    else {
+        detail = progress && progress !== text ? progress : undefined;
+    }
+    return {
+        // stepId 优先用 fallbackStepId（调用方传入的 lastToolStepId），保证前端按 stepId
+        // 合并到 running 那一行；payload.itemId 因 SDK 随机分配，仅作最后兜底。
+        stepId: fallbackStepId || payload.itemId || "unknown",
+        seq,
+        type,
+        text,
+        status: isError ? "error" : "done",
+        toolName,
+        detail,
+    };
+}

package/dist/src/tools/upload-tool.js

@@ -45,7 +45,7 @@ export function registerUploadTool(api) {
         }
         return {
             name: UPLOAD_TOOL_NAME,
-            description: "将 AI 生成的本机文件注册为可下载的引用，返回 `localfile://<绝对路径>` 格式的 Markdown 下载链接。" +
+            description: "重要：将 AI 生成的本机文件注册为可下载的引用，要求必须立马返回 `[<文件名称>]localfile://<绝对路径>` 格式的 Markdown 下载链接；用户可以下载。" +
                 "当需要把生成的文件（图片、文档、代码包等）交付给用户时，必须使用此工具。" +
                 "文件必须先写入磁盘，然后传入绝对路径。单次最多 5 个文件，超出请分批调用。" +
                 "重要：工具返回的 Markdown 链接已是最终格式，请原样使用，不要改写为 https:// 或本机路径字符串。",

package/dist/src/utils/common.js

@@ -53,7 +53,11 @@ export function buildAuthHeaders(apiKey) {
  * 统一的信号发送出口，收敛 typing / stream / tool / usage 控制帧的构造逻辑。
  *
  * - typing_start 不带 replyToMsgId（协议要求）；其余帧都携带。
- * - topLevelExtra 用于透传顶层 kind 相关字段（如 tool_start 的 toolName/toolPhase、tool_end 的 toolIsError）。
+ * - topLevelExtra 用于透传顶层 kind 相关字段：
+ *     · tool_start 的 toolName / toolPhase
+ *     · tool_end   的 toolIsError
+ *     · 群聊场景的 chatKind
+ *     · 媒体附件的 files（与文本同帧投递，确保 kind/agentId/extra 齐全）
  * - innerExtra 用于在 PrivateMessageData.extra 内追加自定义字段（如 usage 帧的 usage 对象）。
  *   chatId 始终由本函数管理，调用方无需也不能在 innerExtra 中传 chatId（会被覆盖）。
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lightclawbot",
-  "version": "1.2.7",
+  "version": "1.2.9",
   "description": "LightClawBot channel plugin with message support, cron jobs, and proactive messaging",
   "type": "module",
   "files": [