lightclawbot 1.2.6 → 1.2.7

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 { DEFAULT_PARTIAL_COALESCE } from "./types.js";
 import { emitSignal } from "../utils/common.js";
 import { readSessionHistoryTail } from "../history/index.js";
 /** 派生/管理 subagent 的工具名；前端可据此特化渲染 tool_start。 */
@@ -33,6 +34,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 = "";
@@ -56,6 +90,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 +188,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'));
     };
     /**
-     * 处理 payload 中的 mediaUrls：COS 上传 → 拼 Markdown 链接 → emit sendReply/sendFiles。
+     * 群聊场景：发送最终完整文本帧
+     * 通过 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 链接 → 推送给用户。
      * 仅在 mediaList 非空时调用。
+     *
+     * 群聊模式：通过 stream_chunk 信号帧推送 Markdown 图片/文件链接（带群聊 extra）。
+     * 私聊模式：通过 emitter.sendFiles / emitter.sendReply 推送。
      */
     const handleMediaFinal = async (replyText, mediaList) => {
         const files = await mediaUrlsToFiles(mediaList, log);
@@ -105,16 +249,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 +298,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 +315,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 +346,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 +382,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 +410,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,6 +466,23 @@ 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，
@@ -323,16 +532,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();
             }
         },
         /**
@@ -344,12 +580,14 @@ export function createStreamReplyConfig(opts, prefixOptions, signalCtx) {
             if (completed)
                 return;
             toolStartCount++;
+            // 强制 flush：前端按"先文本→后工具卡"渲染，buffer 残留若不先发出去会被工具卡插队。
+            flushCoalesceBuffer("tool");
             const toolName = payload.name ?? "unknown";
             const toolPhase = payload.phase ?? "";
             const isSubagentSpawn = SUBAGENT_TOOL_NAMES.has(toolName);
             log?.info(`[${CHANNEL_KEY}] [stream] onToolStart: name=${toolName} phase=${toolPhase}` +
                 (isSubagentSpawn ? " (subagent-spawn)" : ""));
-            emitSignal(signalCtx, "tool_start", "\n\n", { toolName, toolPhase });
+            emitSignal(signalCtx, "tool_start", "\n\n", { toolName, toolPhase, ...groupSignalExtra }, buildGroupDataExtra('delta'));
         },
         onReplyStart: () => {
             if (completed)
@@ -359,6 +597,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 +638,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();
@@ -435,5 +681,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;
+        },
     };
 }

package/dist/src/streaming/types.js

@@ -1,4 +1,23 @@
 /**
  * LightClaw — 流式输出类型定义
  */
-export {};
+/**
+ * 默认聚合参数（详见 ADR-017 数据评估）。
+ *
+ * 调优记录：
+ *   - v1（minChars=24, idleMs=120）：合并率 ~95%（500 字 200+ 帧 → 约 8-9 帧），
+ *     但视觉上"打字一卡一卡"，每 1.2-2 秒才更新一次，且尾部有 ~350ms 停顿感。
+ *   - v2（当前，minChars=24, idleMs=120）：兼顾流畅度与节流效率
+ *     · minChars=24 ≈ 1 句中文/半行英文，承载 ~10 个模型 token / 帧
+ *     · idleMs=120 远低于人眼感知卡顿阈值（约 400-500ms），尾部无停顿感
+ *     · 预估合并率仍 >80%（200+ token → 约 25-30 帧），更新频率 ~1.3-2 帧/秒，
+ *       与主流 Chat 产品（ChatGPT / Claude）网页端体感一致
+ *
+ * 实际合并比可通过 `[coalesce-summary]` 日志中的 `avgTokensPerFrame` 字段观测，
+ * 据此进一步调参。
+ */
+export const DEFAULT_PARTIAL_COALESCE = {
+    minChars: 24,
+    idleMs: 120,
+    flushFirstFrame: true,
+};

package/dist/src/{download-tool.js → tools/download-tool.js}

@@ -7,38 +7,38 @@
  *
  * 工具名: lightclaw_get_file_url
  */
-import * as fs from "node:fs";
-import * as path from "node:path";
-import { getFileDownloadUrl, downloadFileFromServer, uploadFileToServer, } from "./file-storage.js";
-import { formatFileSize } from "./media.js";
-import { resolveEffectiveApiKey } from "./config.js";
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { getFileDownloadUrl, downloadFileFromServer, uploadFileToServer } from '../file-storage.js';
+import { formatFileSize } from '../media.js';
+import { resolveEffectiveApiKey } from '../config.js';
 // ============================================================
 // 工具参数 schema
 // ============================================================
-export const DOWNLOAD_TOOL_NAME = "lightclaw_get_file_url";
+export const DOWNLOAD_TOOL_NAME = 'lightclaw_get_file_url';
 export const downloadToolSchema = {
-    type: "object",
+    type: 'object',
     properties: {
         action: {
-            type: "string",
-            enum: ["get_url", "download_to_local", "upload_and_get_url"],
-            description: "Action to perform: " +
+            type: 'string',
+            enum: ['get_url', 'download_to_local', 'upload_and_get_url'],
+            description: 'Action to perform: ' +
                 "'get_url' — get the public download URL for a previously uploaded file (by filePath); " +
                 "'download_to_local' — download a cloud file to local directory; " +
                 "'upload_and_get_url' — upload a local file and return its public download URL.",
         },
         filePath: {
-            type: "string",
+            type: 'string',
             description: "For 'get_url' and 'download_to_local': the cloud file path (e.g. '2026-03-06/report.pdf'). " +
                 "For 'upload_and_get_url': the local file path to upload.",
         },
         localDir: {
-            type: "string",
+            type: 'string',
             description: "For 'download_to_local' only: the local directory to save the downloaded file. " +
-                "Defaults to the current working directory if not specified.",
+                'Defaults to the current working directory if not specified.',
         },
     },
-    required: ["action", "filePath"],
+    required: ['action', 'filePath'],
 };
 // ============================================================
 // 工具注册（飞书工厂函数模式）
@@ -51,34 +51,34 @@ export function registerDownloadTool(api) {
         const sessionKey = ctx.sessionKey;
         return {
             name: DOWNLOAD_TOOL_NAME,
-            description: "Manage files on cloud storage. " +
-                "Actions: " +
+            description: 'Manage files on cloud storage. ' +
+                'Actions: ' +
                 "(1) 'get_url' — get a public download URL for a previously uploaded file (by its filePath); " +
                 "(2) 'download_to_local' — download a cloud file back to the local filesystem for further processing; " +
                 "(3) 'upload_and_get_url' — upload a single local file and return its public download URL. " +
-                "Note: For batch uploading files to share with users, prefer lightclaw_upload_file instead.",
+                'Note: For batch uploading files to share with users, prefer lightclaw_upload_file instead.',
             parameters: downloadToolSchema,
             async execute(_toolCallId, params) {
                 // 每次 execute 时动态解析 apiKey（多 key 模式下通过 sessionKey 直接获取）
                 const apiKey = resolveEffectiveApiKey({ sessionKey });
                 // log.warn(`[lightclaw_get_file_url] resolved apiKey="${apiKey?.slice(0, 8)}..."`);
                 const { action, filePath, localDir } = params;
-                if (!filePath || typeof filePath !== "string") {
+                if (!filePath || typeof filePath !== 'string') {
                     return {
-                        content: [{ type: "text", text: "Error: filePath is required." }],
+                        content: [{ type: 'text', text: 'Error: filePath is required.' }],
                     };
                 }
                 try {
                     switch (action) {
-                        case "get_url": {
+                        case 'get_url': {
                             const url = getFileDownloadUrl(filePath);
-                            const fileName = filePath.split("/").pop() || filePath;
+                            const fileName = filePath.split('/').pop() || filePath;
                             return {
-                                content: [{ type: "text", text: `[${fileName}](${url})` }],
+                                content: [{ type: 'text', text: `[${fileName}](${url})` }],
                                 details: { action, filePath, url },
                             };
                         }
-                        case "download_to_local": {
+                        case 'download_to_local': {
                             const result = await downloadFileFromServer(filePath, { apiKey });
                             const targetDir = localDir || process.cwd();
                             // 确保目录存在
@@ -88,10 +88,12 @@ export function registerDownloadTool(api) {
                             const targetPath = path.join(targetDir, result.fileName);
                             fs.writeFileSync(targetPath, result.buffer);
                             return {
-                                content: [{
-                                        type: "text",
+                                content: [
+                                    {
+                                        type: 'text',
                                         text: `File downloaded to: ${targetPath} (${formatFileSize(result.buffer.length)}, ${result.contentType})`,
-                                    }],
+                                    },
+                                ],
                                 details: {
                                     action,
                                     filePath,
@@ -101,19 +103,21 @@ export function registerDownloadTool(api) {
                                 },
                             };
                         }
-                        case "upload_and_get_url": {
+                        case 'upload_and_get_url': {
                             if (!fs.existsSync(filePath)) {
                                 return {
-                                    content: [{ type: "text", text: `Error: local file not found: ${filePath}` }],
+                                    content: [{ type: 'text', text: `Error: local file not found: ${filePath}` }],
                                 };
                             }
                             const uploadResult = await uploadFileToServer(filePath, { apiKey });
                             const fileName = path.basename(filePath);
                             return {
-                                content: [{
-                                        type: "text",
+                                content: [
+                                    {
+                                        type: 'text',
                                         text: `File uploaded.\n\n[${fileName}](${uploadResult.url})`,
-                                    }],
+                                    },
+                                ],
                                 details: {
                                     action,
                                     localPath: filePath,
@@ -124,17 +128,19 @@ export function registerDownloadTool(api) {
                         }
                         default:
                             return {
-                                content: [{
-                                        type: "text",
+                                content: [
+                                    {
+                                        type: 'text',
                                         text: `Error: unknown action '${action}'. Use 'get_url', 'download_to_local', or 'upload_and_get_url'.`,
-                                    }],
+                                    },
+                                ],
                             };
                     }
                 }
                 catch (err) {
                     const errMsg = err instanceof Error ? err.message : String(err);
                     return {
-                        content: [{ type: "text", text: `Error: ${errMsg}` }],
+                        content: [{ type: 'text', text: `Error: ${errMsg}` }],
                     };
                 }
             },