lightclawbot 1.2.3 → 1.2.6-beta.0

package/dist/src/history/usage-aggregator.js

@@ -0,0 +1,53 @@
+/**
+ * LightClaw — Usage 轮次聚合、一次问答只展示一次消耗。
+ */
+/**
+ * 把每一轮中除"最后一条" assistant 之外的所有 assistant 消息的 usage 字段删掉。
+ *   - **就地修改** 传入的 messages 数组中的 assistant 消息（不创建新数组）；
+ *   - 同轮内中间 assistant 消息：删掉 usage 字段；
+ *   - 同轮内最后一条 assistant 消息：保持原 usage 不变；
+ *   - 整轮内没有 usage 的消息不做任何修改。
+ *
+ * 调用时机：在 4 个公共读取入口（readSessionHistory / Tail / ByIds / WithCron）
+ *           的最后一步统一调用，确保聚合基于完整对话流。
+ *
+ * @param messages 已 normalize 完成的历史消息数组（按时间正序）
+ */
+export function aggregateUsageByTurn(messages) {
+    // 当前轮内最后一条 assistant 的下标（轮次结束时它的 usage 保留）
+    let lastAssistantIdx = -1;
+    // 当前轮内除"最后一条"之外的 assistant 下标（这些节点的 usage 要被清空）
+    let intermediateAssistantIdxs = [];
+    /** 把当前轮的中间 assistant 节点 usage 全部清空，重置状态准备进入下一轮。 */
+    const flushTurn = () => {
+        for (const idx of intermediateAssistantIdxs) {
+            if (messages[idx]?.usage) {
+                delete messages[idx].usage;
+            }
+        }
+        lastAssistantIdx = -1;
+        intermediateAssistantIdxs = [];
+    };
+    for (let i = 0; i < messages.length; i += 1) {
+        const msg = messages[i];
+        // cron 提醒类消息（带 cronInfo）属于独立的提醒上下文，不参与主会话轮次聚合，
+        // 保留它们各自的 usage 原样展示。
+        if (msg.cronInfo)
+            continue;
+        if (msg.role === "user") {
+            // 新一轮开始前，先把上一轮的中间 assistant usage 清空
+            flushTurn();
+            continue;
+        }
+        if (msg.role !== "assistant")
+            continue; // tool / system 节点不参与
+        // 把上一个"最后一条"挪到中间列表（它的 usage 不再代表轮末，要删）
+        if (lastAssistantIdx >= 0) {
+            intermediateAssistantIdxs.push(lastAssistantIdx);
+        }
+        // 当前节点暂定为"最后一条"
+        lastAssistantIdx = i;
+    }
+    // 处理最后一轮（可能没有后续 user 消息触发 flushTurn）
+    flushTurn();
+}

package/dist/src/inbound.js

@@ -8,7 +8,7 @@
  *   - /stop 及自然语言 abort 由 tryFastAbortFromMessage 统一处理并递归 kill subagent。
  */
 import { emitSignal } from './utils/common.js';
-import { CHANNEL_KEY, MEDIA_MAX_BYTES, resolveEffectiveApiKey, setSessionApiKey, DEFAULT_AGENT_ID, LOCALFILE_SCHEME } from './config.js';
+import { CHANNEL_KEY, MEDIA_MAX_BYTES, resolveEffectiveApiKey, setSessionApiKey, DEFAULT_AGENT_ID, LOCALFILE_SCHEME, } from './config.js';
 import { getLightclawRuntime } from './runtime.js';
 import { createChannelReplyPipeline } from 'openclaw/plugin-sdk/channel-reply-pipeline';
 import { generateMsgId } from './dedup.js';
@@ -45,23 +45,29 @@ export function createInboundHandler(account, emitter, log) {
             peer: { kind: 'direct', id: msg.senderId },
         });
         // route: {"agentId":"main","channel":"lightclawbot","accountId":"default","sessionKey":"agent:main:lightclawbot:direct:100013456706","mainSessionKey":"agent:main:main","lastRoutePolicy":"session","matchedBy":"default"}
-        // 若前端指定了合法的 agentId，则用 buildAgentSessionKey 覆盖 sessionKey 和 agentId，
-        // 实现 Agent 间隔离（sessionKey 含 agentId，不同 Agent 的会话历史完全独立）
-        const route = resolvedAgentId
-            ? {
-                ...baseRoute,
-                agentId: resolvedAgentId,
-                sessionKey: pluginRuntime.channel.routing.buildAgentSessionKey({
-                    agentId: resolvedAgentId,
-                    channel: CHANNEL_KEY,
-                    accountId: baseRoute.accountId,
-                    peer: { kind: 'direct', id: msg.senderId },
-                    dmScope: 'per-channel-peer',
-                }),
-                mainSessionKey: `agent:${resolvedAgentId}:main`,
-            }
-            : baseRoute;
-        log?.info(`[CHANNEL_KEY]: route= ${JSON.stringify(route)}`);
+        // 框架生成的基础 sessionKey 形如：
+        // agent:<agentId>:<channel>:direct:<userId>
+        // 当前端带上 chatId（多会话场景）时，需要在末尾追加 `:<chatId>`，
+        // 形成：agent:<agentId>:<channel>:direct:<userId>:<chatId>，
+        const chatIdSuffix = msg?.chatId?.trim();
+        const appendChatId = (key) => (chatIdSuffix ? `${key}:${chatIdSuffix}` : key);
+        // 用 buildAgentSessionKey 基于 resolvedAgentId 重建 sessionKey 和 agentId，
+        // 实现 Agent 间隔离（sessionKey 含 agentId，不同 Agent 的会话历史完全独立）。
+        // resolvedAgentId 由 DEFAULT_AGENT_ID 兜底，必定有值，故无需再判空。
+        const baseSessionKey = pluginRuntime.channel.routing.buildAgentSessionKey({
+            agentId: resolvedAgentId,
+            channel: CHANNEL_KEY,
+            accountId: baseRoute.accountId,
+            peer: { kind: 'direct', id: msg.senderId },
+            dmScope: 'per-channel-peer',
+        });
+        const route = {
+            ...baseRoute,
+            agentId: resolvedAgentId,
+            sessionKey: appendChatId(baseSessionKey),
+            mainSessionKey: `agent:${resolvedAgentId}:main`,
+        };
+        log?.info(`[CHANNEL_KEY]: route= ${JSON.stringify(route)}, chatId=${chatIdSuffix ?? '-'}`);
         // ---- 步骤 3：权限检查 ----
         // 根据 allowFrom 白名单和 dmPolicy 策略决定是否允许此用户发送命令
         const commandAuthorized = checkAuth(account.allowFrom, account.dmPolicy, msg.senderId);
@@ -77,8 +83,16 @@ export function createInboundHandler(account, emitter, log) {
         const targetId = msg.senderId;
         // 2. 提前发 typing_start（作为"已读回执"，减少 COS 下载/LLM TTFT 期间的无反馈感）
         const replyMsgId = generateMsgId();
-        const signalCtx = { emitter, targetId, replyMsgId, originalMsgId: msg.messageId, agentId: resolvedAgentId };
+        const signalCtx = {
+            emitter,
+            targetId,
+            replyMsgId,
+            originalMsgId: msg.messageId,
+            agentId: resolvedAgentId,
+            chatId: msg.chatId ?? '',
+        };
         emitSignal(signalCtx, 'typing_start');
+        // 注：SignalContext.chatId 是上下文字段，由 emitSignal 内部规整到 extra.chatId 输出
         // 3. 处理文件附件（files[] → 本地存储 + 公网 URL）
         const localMediaPaths = [];
         /** 本地文件 MIME 类型列表，与 localMediaPaths 一一对应 */
@@ -232,6 +246,9 @@ export function createInboundHandler(account, emitter, log) {
             log,
             effectiveApiKey,
             typingAlreadyStarted: true,
+            // 透传 sessionKey + agentId 给 sink，markComplete 时用来从 transcript 兜底读 usage
+            sessionKey: route?.sessionKey,
+            agentId: resolvedAgentId,
         }, { ...prefixOptions, onModelSelected }, signalCtx);
         // 8. 分发给 AI 引擎（真流式）。abort 由 openclaw fast-abort 处理，sink 层
         //    把英文回执汉化；此处仅兜底自身抛错。
@@ -251,7 +268,7 @@ export function createInboundHandler(account, emitter, log) {
             log?.error(`[${CHANNEL_KEY}] Dispatch error: ${errMsg}`);
             // 已推过可见内容时不再追加错误文案，避免打断阅读。
             if (!hasEmittedContent()) {
-                emitter.sendReply(targetId, '抱歉，处理您的消息时出现了问题，请稍后重试', msg.messageId);
+                emitter.sendReply(targetId, '抱歉，处理您的消息时出现了问题，请稍后重试', msg.messageId, msg.chatId);
             }
         }
     };

package/dist/src/socket/chat.js

@@ -0,0 +1,257 @@
+/**
+ * LightClaw — Chat（会话元信息）处理器
+ *
+ * 收敛 EVENT_CHAT_REQUEST 各子类型的处理逻辑，与 handlers.ts 中的
+ * 消息 / 历史 / Agents 等事件处理保持平级解耦，避免 handlers.ts 膨胀。
+ *
+ * 涉及的持久化文件：
+ *   `~/.openclaw/agents/<agentId>/chats/<userId>/chats.json`
+ *    └─ 以 ChatMeta[] 形式存储该用户在该 Agent 下的会话元信息列表
+ *        （不包含消息正文，正文以 jsonl 形式另外存储）
+ *
+ * 四个处理器（对应 data.type）：
+ *   - list：   读取 chats.json 返回 { chats }；文件不存在 / 解析失败
+ *             时返回空数组，不抛错，避免阻塞前端。
+ *   - create： 新建一条会话元数据，chatId = randomUUID()，插入列表最前。
+ *             文件或目录不存在时由 writeChatsFile 递归创建。
+ *   - update： 根据 chatId 修改 title（并置 titleLocked=true + 刷新 updatedAt）；
+ *             文件或条目不存在时回 error，不隐式创建。
+ *   - delete： 根据 chatId 从列表剔除，原子写回；文件或条目不存在时回 error。
+ *
+ * 全部响应均通过 EVENT_CHAT_RESPONSE + ReliableEmitter 发出（带 ACK + 重试）。
+ * 错误处理统一走 createChatErrorSender 生成的回调，保证日志 / 响应结构一致。
+ */
+import { randomUUID } from 'node:crypto';
+import * as fs from 'node:fs';
+import { CHANNEL_KEY, EVENT_CHAT_RESPONSE } from '../config.js';
+import { generateMsgId } from '../dedup.js';
+import { readChatsFile, readChatsFileOrInitDefault, resolveChatsFilePath, writeChatsFile } from '../utils/common.js';
+/**
+ * 生成统一的错误响应发送器。
+ *
+ * 背景：list / create / update / delete 四个 handler 的错误处理结构完全一致：
+ *   1. 打同一格式日志：`[CHANNEL_KEY] Chat <type> error: <msg>`
+ *   2. 通过 EVENT_CHAT_RESPONSE 回同一组基础字段（msgId/from/to/type/agentId/error）
+ * 仅差异项：
+ *   - `type` 不同
+ *   - `chatId` 是否需要回显（update/delete 需要）
+ *   - list 出错时前端期望一个兜底的空列表 `chats: []`，避免 UI 处理 undefined
+ *
+ * 因此将其封装为模块级工厂，handler 开头调用一次即可，避免重复闭包。
+ *
+ * @param ctx   共享上下文（见 ChatErrorSenderContext）
+ * @param extra 额外字段（如 `chatId`、兜底 `chats: []`），会与 error 一并合并到响应体
+ * @returns     ChatErrorSender — 调用时传入错误信息即可
+ */
+function createChatErrorSender(ctx, extra = {}) {
+    const { responseMsgId, botClientId, userId, agentId, type, reliableEmitter, log } = ctx;
+    return (error) => {
+        log?.error(`[${CHANNEL_KEY}] Chat ${type} error: ${error}`);
+        reliableEmitter.emitWithAck(EVENT_CHAT_RESPONSE, {
+            msgId: responseMsgId,
+            from: botClientId,
+            to: userId,
+            type,
+            agentId,
+            timestamp: Date.now(),
+            ...extra,
+            error,
+        }, responseMsgId);
+    };
+}
+/**
+ * 处理 EVENT_CHAT_REQUEST(type=list)：返回该用户在指定 Agent 下的会话列表。
+ *
+ * 行为：
+ *   1. 解析当前用户 + Agent 的 chats.json 绝对路径
+ *   2. 调用 readChatsFileOrInitDefault 读取：文件不存在时**主动落盘一条 chatId=''
+ *      的默认会话兜底条目**，保证前端拉列表永远拿到至少一项；格式异常时返回 []
+ *   3. 通过 EVENT_CHAT_RESPONSE 回 { chats }；若意外抛异常则回 { chats: [], error }
+ *
+ * 为什么 list 路径要主动兜底？
+ *   - 用户首次连接拉列表 → 拿到默认对话 → UI 展示一致，不会出现
+ *     “先空态、首条消息后又凭空多出一项”的诡异闪烁；
+ *   - 兜底是幂等的：若 chats.json 已存在则等价于纯读取，无副作用；
+ *   - 与 ensureSessionInHistory 的被动兜底形成双保险，覆盖“前端跳过 list
+ *     直接发消息”的极端场景。
+ *
+ * 为什么 create/update/delete/history:request 仍走纯只读 readChatsFile？
+ *   - 它们要么是用户主动操作（隐式创建语义已在 create 中处理），
+ *     要么是只读查询（不应有写盘副作用），由 list 路径统一负责兜底即可。
+ */
+export function handleChatList(params) {
+    const { userId, agentId, botClientId, reliableEmitter, log } = params;
+    // 当前用户在当前 Agent 下的会话记录保存路径，即 chats.json 的绝对路径
+    const chatsPath = resolveChatsFilePath(agentId, userId);
+    // 响应 msgId：同时做 ReliableEmitter 的 ack key，成功 / 失败分支共用同一枚
+    const responseMsgId = generateMsgId();
+    // list 出错时，用一个空数组兑底，避免 UI 处理 undefined
+    const sendError = createChatErrorSender({ responseMsgId, botClientId, userId, agentId, type: 'list', reliableEmitter, log }, { chats: [] });
+    try {
+        // 主动兜底读取：文件不存在则落盘一条 chatId='' 的默认会话；存在则等价于纯只读
+        const chats = readChatsFileOrInitDefault(chatsPath);
+        log?.info(`[${CHANNEL_KEY}] Chat list: userId=${userId} agentId=${agentId} count=${chats.length}`);
+        // 正常分支：统一经 ReliableEmitter 发送，依赖其 ACK + 重试保障送达
+        reliableEmitter.emitWithAck(EVENT_CHAT_RESPONSE, {
+            msgId: responseMsgId,
+            from: botClientId,
+            to: userId,
+            type: 'list',
+            agentId,
+            chats,
+            timestamp: Date.now(),
+        }, responseMsgId);
+    }
+    catch (err) {
+        // 兼容 Error / 非 Error 投掷（如字符串 throw），统一拼接为可读消息
+        sendError(err instanceof Error ? err.message : String(err));
+    }
+}
+/**
+ * 处理 EVENT_CHAT_REQUEST(type=create)：新建一条会话元数据。
+ *
+ * 行为：
+ *   1. 解析 `~/.openclaw/agents/<agentId>/chats/<userId>/chats.json`
+ *   2. 文件不存在 → 以空列表起步（writeChatsFile 会递归建目录 + 原子落盘）
+ *   3. 文件存在   → 读取并在头部插入新会话（新建的默认置顶于列表最前）
+ *   4. 新会话默认 `title = '新会话'`，`chatId = randomUUID()`，createdAt = updatedAt = now
+ *   5. 通过 EVENT_CHAT_RESPONSE 返回 { chat: 新建项 }
+ */
+export function handleChatCreate(params) {
+    const { userId, agentId, botClientId, reliableEmitter, log } = params;
+    const chatsPath = resolveChatsFilePath(agentId, userId);
+    // 响应 msgId：成功 / 失败分支共用，侜助前端根据 msgId 反查原请求
+    const responseMsgId = generateMsgId();
+    const sendError = createChatErrorSender({
+        responseMsgId,
+        botClientId,
+        userId,
+        agentId,
+        type: 'create',
+        reliableEmitter,
+        log,
+    });
+    try {
+        // 读取已有列表：文件不存在则返回 [] —— create 是隐式创建语义
+        const existing = readChatsFile(chatsPath);
+        const now = Date.now();
+        const newChat = {
+            chatId: randomUUID(),
+            title: '新会话',
+            // 新建时 titleLocked=false：首条消息后可被自动标题生成策略改写
+            titleLocked: false,
+            createdAt: now,
+            updatedAt: now,
+            pinned: false,
+            // sessionIdHistory：同一 chat 历史上使用过的 sessionId（支持会话分支 / 重置）
+            sessionIdHistory: [],
+        };
+        // 新会话插入到最前，writeChatsFile 会在目录不存在时逐级创建（tmp → rename 原子落盘）
+        const nextChats = [newChat, ...existing];
+        writeChatsFile(chatsPath, nextChats);
+        log?.info(`[${CHANNEL_KEY}] Chat create: userId=${userId} agentId=${agentId} chatId=${newChat.chatId}`);
+        reliableEmitter.emitWithAck(EVENT_CHAT_RESPONSE, {
+            msgId: responseMsgId,
+            from: botClientId,
+            to: userId,
+            type: 'create',
+            agentId,
+            chats: [newChat],
+            timestamp: Date.now(),
+        }, responseMsgId);
+    }
+    catch (err) {
+        sendError(err instanceof Error ? err.message : String(err));
+    }
+}
+export function handleChatUpdate(params) {
+    const { userId, agentId, chatId, title, botClientId, reliableEmitter, log } = params;
+    const chatsPath = resolveChatsFilePath(agentId, userId);
+    const responseMsgId = generateMsgId();
+    // update 错误响应需要回显 chatId，便于前端关联请求
+    const sendError = createChatErrorSender({ responseMsgId, botClientId, userId, agentId, type: 'update', reliableEmitter, log }, { chatId });
+    // title 可能为纯空白字符，trim 后再判断，避免“空标题”落盘
+    const nextTitle = title?.trim();
+    if (!nextTitle) {
+        sendError('Missing title');
+        return;
+    }
+    // 文件必须存在，update 不负责创建（语义上：无源数据则无从更新）
+    if (!fs.existsSync(chatsPath)) {
+        sendError(`Chats file not found: ${chatsPath}`);
+        return;
+    }
+    try {
+        const chats = readChatsFile(chatsPath);
+        // O(n) 线性查找；chats.json 一般单用户单 Agent 规模有限，无需 Map 索引
+        const idx = chats.findIndex((c) => c.chatId === chatId);
+        if (idx < 0) {
+            sendError(`Chat not found: chatId=${chatId}`);
+            return;
+        }
+        // 更新：title + updatedAt + titleLocked
+        // titleLocked=true：用户主动改名后锁定，防止被自动标题生成策略覆盖
+        const updated = {
+            ...chats[idx],
+            title: nextTitle,
+            titleLocked: true,
+            updatedAt: Date.now(),
+        };
+        // 浅拷贝后原位替换，保留其他项的顺序（列表排序给前端决定，后端不托管）
+        const nextChats = [...chats];
+        nextChats[idx] = updated;
+        // 原子落盘：writeChatsFile 内部使用 tmp + rename 保证不损坏原文件
+        writeChatsFile(chatsPath, nextChats);
+        log?.info(`[${CHANNEL_KEY}] Chat update: userId=${userId} agentId=${agentId} chatId=${chatId} title="${nextTitle}"`);
+        reliableEmitter.emitWithAck(EVENT_CHAT_RESPONSE, {
+            msgId: responseMsgId,
+            from: botClientId,
+            to: userId,
+            type: 'update',
+            agentId,
+            chats: [updated],
+            timestamp: Date.now(),
+        }, responseMsgId);
+    }
+    catch (err) {
+        sendError(err instanceof Error ? err.message : String(err));
+    }
+}
+export function handleChatDelete(params) {
+    const { userId, agentId, chatId, botClientId, reliableEmitter, log } = params;
+    const chatsPath = resolveChatsFilePath(agentId, userId);
+    const responseMsgId = generateMsgId();
+    // delete 错误响应需要回显 chatId，便于前端关联请求
+    const sendError = createChatErrorSender({ responseMsgId, botClientId, userId, agentId, type: 'delete', reliableEmitter, log }, { chatId });
+    // 文件必须存在，delete 不负责创建（无文件 == 无可删的项，返回明确错误）
+    if (!fs.existsSync(chatsPath)) {
+        sendError(`Chats file not found: ${chatsPath}`);
+        return;
+    }
+    try {
+        const chats = readChatsFile(chatsPath);
+        // 先确认条目存在再写盘，避免“无效删除”仍触发一次磁盘 IO
+        const idx = chats.findIndex((c) => c.chatId === chatId);
+        if (idx < 0) {
+            sendError(`Chat not found: chatId=${chatId}`);
+            return;
+        }
+        // 剔除目标项，保留其余顺序（不重排，不影响前端缓存的列表索引）
+        const nextChats = chats.filter((c) => c.chatId !== chatId);
+        // 原子落盘：writeChatsFile 内部使用 tmp + rename 保证不损坏原文件
+        writeChatsFile(chatsPath, nextChats);
+        log?.info(`[${CHANNEL_KEY}] Chat delete: userId=${userId} agentId=${agentId} chatId=${chatId} remaining=${nextChats.length}`);
+        reliableEmitter.emitWithAck(EVENT_CHAT_RESPONSE, {
+            msgId: responseMsgId,
+            from: botClientId,
+            to: userId,
+            type: 'delete',
+            agentId,
+            chats: chats.filter((c) => c.chatId === chatId),
+            timestamp: Date.now(),
+        }, responseMsgId);
+    }
+    catch (err) {
+        sendError(err instanceof Error ? err.message : String(err));
+    }
+}