lightclawbot 1.2.6 → 1.2.8

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/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}` }],
                     };
                 }
             },