lightclawbot 1.2.3 → 1.2.6-beta.0

package/dist/src/channel.js

@@ -1,39 +1,80 @@
 /**
- * LightClaw — ChannelPlugin 主定义
+ * ============================================================================
+ * channel.ts —— Lightclaw Channel Plugin 主入口
+ * ============================================================================
  *
- * 使用 SDK 标准的 createChatChannelPlugin 构建器，
- * 参照官方 Discord/Slack channel 实现。
+ * 本文件通过 OpenClaw 的 Plugin SDK 创建并导出一个「聊天类 Channel 插件」
+ * （`lightclawPlugin`），用于把 Lightclaw（AI 助手 Server）接入到 OpenClaw
+ * 网关体系中，作为一个标准的消息通道（Channel）使用。
  *
- * 结构：
- *   base:     来自 shared.ts 的 createLightclawPluginBase + 扩展字段
- *   security: DM 安全策略
- *   outbound: 出站消息适配器
+ * 该插件主要负责以下几件事：
+ *   1. messaging：目标字符串（user:xxx / channel:xxx）的规范化与识别；
+ *   2. status   ：暴露插件/账户运行时状态，供 OpenClaw 状态面板展示；
+ *   3. gateway  ：账户级别的长连接生命周期管理（启动/停止/登出）；
+ *   4. outbound ：出站消息（文本 / 媒体）的投递策略与发送实现。
+ *
+ * 架构概览：
+ *   OpenClaw  ──启动账户──▶  startAccount()  ──▶  startGateway()  ──▶  Socket.IO WS
+ *          ◀──状态回写──   ctx.setStatus()  ◀── onReady/onEvent/onDisconnect/onError
+ *
+ * ============================================================================
  */
 import { createChatChannelPlugin } from 'openclaw/plugin-sdk/core';
+// ---- 通用工具：文本分片、默认账户 ID 解析 ------------------------------------
 import { chunkText, defaultAccountId } from './utils/index.js';
+// ---- 常量：通道 Key、默认账户 ID、文本分片上限 -------------------------------
 import { CHANNEL_KEY, DEFAULT_ACCOUNT_ID, TEXT_CHUNK_LIMIT } from './config.js';
+// ---- 出站发送：文本 / 媒体两类消息的实际发送实现 -----------------------------
 import { sendText, sendMedia } from './outbound.js';
+// ---- Gateway：账户级别的 Socket.IO 长连接控制器 ------------------------------
 import { startGateway } from './gateway.js';
+// ---- 共享 base：抽取出的通用插件基础配置（避免与其他插件重复） ---------------
 import { createLightclawPluginBase } from './shared.js';
+// ---- Setup 适配器：首次配置 / 登录流程 ---------------------------------------
 import { lightclawSetupAdapter } from './setup-core.js';
+// ---- 目标解析：对 target 字符串做 normalize 和 "是否像 ID" 的预判 -------------
 import { normalizeTarget, looksLikeId } from './messaging.js';
-// ============================================================
-// ChannelPlugin 定义（使用 createChatChannelPlugin）
-// ============================================================
+/**
+ * Lightclaw 聊天通道插件。
+ *
+ * 通过 `createChatChannelPlugin` 工厂创建；泛型 `ResolvedAssistantAccount`
+ * 指定该通道使用的账户类型（OpenClaw 会据此在各回调中注入强类型 account）。
+ *
+ * 导出后由 OpenClaw 主程序在启动阶段加载并注册到 Channel 管理器中。
+ */
 export const lightclawPlugin = createChatChannelPlugin({
+    // ========================================================================
+    // base：插件的核心能力声明（messaging / status / gateway ...）
+    // ========================================================================
     base: {
-        // ---- 来自 shared.ts 的基础定义 ----
+        // 展开共享的 base：包含 setup、channelKey、日志前缀等公用配置
         ...createLightclawPluginBase({
             setup: lightclawSetupAdapter,
         }),
-        // ---- 消息目标解析 ----
+        // ----------------------------------------------------------------------
+        // messaging：消息目标（target）的解析与规范化
+        // ----------------------------------------------------------------------
         messaging: {
-            // 对原始目标字符串进行标准化处理，如去除空格、统一格式、转换编码等，返回标准化后的字符串
+            /**
+             * 对原始目标字符串进行标准化处理。
+             *
+             * 例如：去除前后空格、统一大小写、把 `@xxx` 转为 `user:xxx` 等，
+             * 返回规范化后的字符串，供后续路由匹配使用。
+             */
             normalizeTarget: (target) => {
                 return normalizeTarget(target);
             },
+            /**
+             * 目标解析器：在消息路由阶段帮助框架判断 target 的"形态"。
+             */
             targetResolver: {
-                // 判断一个原始字符串是否看起来像一个 ID，用于在解析前快速分流处理逻辑
+                /**
+                 * 判断一个原始字符串是否看起来像一个 ID（而不是昵称/关键词等），
+                 * 用于在解析前快速分流处理逻辑，避免不必要的远端查询。
+                 *
+                 * @param id         用户输入的原始字符串
+                 * @param normalized 经过 normalizeTarget 规范化后的字符串（可选）
+                 */
                 looksLikeId: (id, normalized) => {
                     return looksLikeId(id, normalized);
                 },
@@ -41,8 +82,14 @@ export const lightclawPlugin = createChatChannelPlugin({
                 hint: `user:<userId> or channel:<groupId>`,
             },
         },
-        // ---- 状态面板 ----
+        // ----------------------------------------------------------------------
+        // status：运行时状态快照的构建与默认值
+        //   - defaultRuntime    ：账户 runtime 的初始值（未启动时回显）
+        //   - buildChannelSummary：整个通道层级的概要状态（所有账户汇总之上的顶层）
+        //   - buildAccountSnapshot：单个账户的详细快照（CLI/面板展示的主体数据）
+        // ----------------------------------------------------------------------
         status: {
+            /** 账户 runtime 的初始状态：未连接、未运行、无错误 */
             defaultRuntime: {
                 accountId: DEFAULT_ACCOUNT_ID,
                 running: false,
@@ -50,6 +97,10 @@ export const lightclawPlugin = createChatChannelPlugin({
                 lastConnectedAt: null,
                 lastError: null,
             },
+            /**
+             * 构建通道级别的汇总状态。
+             * 由 OpenClaw 在查询 `status` 命令时调用。
+             */
             buildChannelSummary: ({ snapshot }) => ({
                 configured: snapshot.configured ?? false,
                 running: snapshot.running ?? false,
@@ -57,10 +108,18 @@ export const lightclawPlugin = createChatChannelPlugin({
                 lastConnectedAt: snapshot.lastConnectedAt ?? null,
                 lastError: snapshot.lastError ?? null,
             }),
+            /**
+             * 构建单个账户的快照。
+             *
+             * @param account 账户元数据（accountId / name / apiKey / enabled 等）
+             * @param runtime 账户运行时状态（由 gateway 回调实时更新）
+             * @param cfg     当前 OpenClaw 完整配置，用于在 account 缺失时回退取默认
+             */
             buildAccountSnapshot: ({ account, runtime, cfg }) => ({
                 accountId: account?.accountId ?? defaultAccountId(cfg),
                 name: account?.name,
                 enabled: account?.enabled ?? false,
+                // configured 表示"是否已配置 apiKey"，是前端判断"是否可启动"的依据
                 configured: Boolean(account?.apiKey),
                 running: runtime?.running ?? false,
                 connected: runtime?.connected ?? false,
@@ -68,24 +127,41 @@ export const lightclawPlugin = createChatChannelPlugin({
                 lastError: runtime?.lastError ?? null,
             }),
         },
-        // ---- Gateway 生命周期（核心！） ----
+        // ----------------------------------------------------------------------
+        // gateway：账户级生命周期（启动 WS 长连接 / 登出清理凭证）
+        // ----------------------------------------------------------------------
         gateway: {
             /**
-             * 启动账户：建立 WS 长连接到 AI 助手 Server
-             * OpenClaw 会在加载配置后为每个 enabled 的账户调用此方法
+             * 启动账户：建立 WS 长连接到 AI 助手 Server。
+             *
+             * OpenClaw 会在加载配置后，为每个 `enabled` 的账户调用此方法。
+             * 方法内部通过 `startGateway` 维持一个带自动重连的 Socket.IO 实例，
+             * 并通过一组回调把连接状态反向写回 OpenClaw 的 runtime 状态。
+             *
+             * @param ctx 插件上下文：
+             *   - account     当前账户解析结果
+             *   - abortSignal 外部取消信号（用户执行 stop 时触发）
+             *   - log         插件作用域的 logger
+             *   - cfg         OpenClaw 完整配置
+             *   - getStatus/setStatus 读写当前 runtime 快照
              */
             startAccount: async (ctx) => {
                 const { account, abortSignal, log, cfg } = ctx;
-                log?.info(`[${CHANNEL_KEY}:${account.accountId}] Starting gateway...`);
+                const preLogFix = `[${CHANNEL_KEY}:${account.accountId}]`;
+                log?.info(`${preLogFix} Starting gateway...`);
                 // 启动并维持一个 Socket.IO Gateway 实例
                 await startGateway({
                     account,
                     abortSignal,
                     cfg,
                     log,
-                    /** WS 连接就绪回调 */
+                    /**
+                     * WS 连接就绪回调：
+                     * 标记 running=true / connected=true，并用当前时间戳初始化
+                     * lastConnectedAt 与 lastEventAt（后者是 health-monitor 的检测基准）。
+                     */
                     onReady: () => {
-                        log?.info(`[${CHANNEL_KEY}:${account.accountId}] Gateway ready: WS connected`);
+                        log?.info(`${preLogFix} Gateway ready: WS connected`);
                         const now = Date.now();
                         ctx.setStatus({
                             ...ctx.getStatus(),
@@ -96,17 +172,24 @@ export const lightclawPlugin = createChatChannelPlugin({
                             lastEventAt: now,
                         });
                     },
-                    /** WS 连接断开回调 */
+                    /**
+                     * WS 连接断开回调：
+                     * 仅把 connected 置为 false；running 保持 true，表示 gateway
+                     * 仍在尝试重连。真正的停止由 abortSignal 触发。
+                     */
                     onDisconnect: () => {
-                        log?.info(`[${CHANNEL_KEY}:${account.accountId}] Gateway ready: WS disconnect`);
+                        log?.info(`${preLogFix} Gateway ready: WS disconnect`);
                         ctx.setStatus({
                             ...ctx.getStatus(),
                             connected: false,
                         });
                     },
-                    /** 错误回调：记录错误信息，不中断重连逻辑（由 gateway 内部处理） */
+                    /**
+                     * 错误回调：记录错误信息到 runtime.lastError。
+                     * 不中断重连逻辑（重连由 gateway 内部自愈机制处理）。
+                     */
                     onError: (error) => {
-                        log?.error(`[${CHANNEL_KEY}:${account.accountId}] Gateway error: ${error.message}`);
+                        log?.error(`${preLogFix} Gateway error: ${error.message}`);
                         ctx.setStatus({
                             ...ctx.getStatus(),
                             lastError: error.message,
@@ -114,11 +197,12 @@ export const lightclawPlugin = createChatChannelPlugin({
                     },
                     /**
                      * 入站事件回调：每次收到消息时调用。
-                     * 刷新 lastEventAt 和 lastInboundAt，
-                     * 通知框架 health-monitor 该连接仍处于活跃状态。
+                     *
+                     * 通过刷新 `lastEventAt` 和 `lastInboundAt`，通知框架
+                     * health-monitor 该连接仍处于活跃状态，避免被判定为 stale 而重连。
                      */
                     onEvent: () => {
-                        log?.info(`[${CHANNEL_KEY}:${account.accountId}] Gateway Ready: WS message enter`);
+                        log?.info(`${preLogFix} Gateway Ready: WS message enter`);
                         ctx.setStatus({
                             ...ctx.getStatus(),
                             lastEventAt: Date.now(),
@@ -127,19 +211,24 @@ export const lightclawPlugin = createChatChannelPlugin({
                     },
                 });
             },
-            /** 登出账户：清除凭证 */
+            /**
+             * 登出账户：从配置中清除该账户的凭证（apiKey）。
+             * 清理 `lightclawbot.accounts[accountId].apiKey`
+             *
+             * 注意：本方法只负责清除凭证字段，不停止 gateway（停止由框架调度）。
+             *
+             * @returns { ok, cleared } cleared=true 表示确实清理了字段
+             */
             logoutAccount: async ({ accountId, cfg }) => {
+                // 拷贝 cfg，避免直接改引用导致上游感知不到变化
                 const nextCfg = { ...cfg };
-                const section = nextCfg.channels?.[CHANNEL_KEY];
+                const lightclawbotConfig = nextCfg?.channels?.[CHANNEL_KEY];
                 let cleared = false;
-                if (section) {
-                    if (accountId === DEFAULT_ACCOUNT_ID && section.apiKeys) {
-                        delete section.apiKeys;
-                        cleared = true;
-                    }
-                    const accounts = section.accounts;
-                    if (accounts?.[accountId]?.apiKeys) {
-                        delete accounts[accountId].apiKeys;
+                if (lightclawbotConfig) {
+                    // 命名账户：凭证挂在 accounts[accountId] 下
+                    const accounts = lightclawbotConfig.accounts;
+                    if (accounts?.[accountId]?.apiKey) {
+                        delete accounts[accountId].apiKey;
                         cleared = true;
                     }
                 }
@@ -147,13 +236,30 @@ export const lightclawPlugin = createChatChannelPlugin({
             },
         },
     },
-    // ---- 出站消息适配器 ----
+    // ========================================================================
+    // outbound：出站消息投递配置
+    //   - base            ：投递策略（模式、分片器、目标解析）
+    //   - attachedResults ：实际发送函数（sendText / sendMedia）
+    // ========================================================================
     outbound: {
         base: {
+            /** 投递模式：direct = 直接发送，不走队列/合并 */
             deliveryMode: 'direct',
+            /** 文本分片器：按 Markdown 语义边界做智能切分 */
             chunker: chunkText,
+            /** 分片模式：markdown 模式会保留代码块、列表等结构完整性 */
             chunkerMode: 'markdown',
+            /** 单条消息文本长度上限（超过会被 chunker 切成多条发送） */
             textChunkLimit: TEXT_CHUNK_LIMIT,
+            /**
+             * 解析投递目标（resolveTarget）：
+             *
+             * 决定一次 outbound 消息最终要发送给谁（to）。
+             * 优先级：
+             *   1. 显式 `to` 参数（用户 / 上层明确指定）；
+             *   2. implicit 模式下，从 `allowFrom` 列表中挑第一个非通配符条目；
+             *   3. 都没有则返回错误，提示用户用 `--to` 指定或配置 allowFrom。
+             */
             resolveTarget: ({ to, allowFrom, mode }) => {
                 // 优先使用显式 to；implicit 模式下回退到 allowFrom 第一个非通配符条目
                 const effectiveTo = to?.trim();
@@ -172,11 +278,26 @@ export const lightclawPlugin = createChatChannelPlugin({
                 };
             },
         },
+        /**
+         * attachedResults：绑定到"工具调用结果投递"这条链路的发送实现。
+         *
+         * OpenClaw 在 assistant 产出工具结果需要推送给外部时，会根据
+         * `channel` 字段路由到这里，调用 sendText / sendMedia 完成实际投递。
+         */
         attachedResults: {
+            /** 通道标识，需与 CHANNEL_KEY 一致，供 OpenClaw 路由匹配 */
             channel: CHANNEL_KEY,
+            /**
+             * 发送纯文本消息。
+             * 参数由框架透传：to 目标、text 内容、accountId 账户、replyToId 回复锚点、cfg 完整配置。
+             */
             sendText: async ({ to, text, accountId, replyToId, cfg }) => {
                 return sendText({ to, text, accountId, replyToId, cfg });
             },
+            /**
+             * 发送带媒体附件的消息（图片 / 文件等）。
+             * text 为附带的文本说明，mediaUrl 为媒体资源 URL。
+             */
             sendMedia: async ({ to, text, mediaUrl, accountId, replyToId, cfg }) => {
                 return sendMedia({ to, text, mediaUrl, accountId, replyToId, cfg });
             },

package/dist/src/config.js

@@ -147,6 +147,10 @@ export const EVENT_HISTORY_REQUEST = 'message:history:request';
 export const EVENT_HISTORY_RESPONSE = 'message:history:response';
 export const EVENT_SESSIONS_REQUEST = 'sessions:request';
 export const EVENT_SESSIONS_RESPONSE = 'sessions:response';
+export const EVENT_AGENTS_REQUEST = 'agents:request';
+export const EVENT_AGENTS_RESPONSE = 'agents:response';
+export const EVENT_CHAT_REQUEST = 'chat:request';
+export const EVENT_CHAT_RESPONSE = 'chat:response';
 // ============================================================
 // 文件下载信令（kind 字段值）
 // ============================================================

package/dist/src/gateway.js

@@ -133,10 +133,19 @@ export async function startGateway(ctx) {
      * - 所有消息都走可靠发送队列，入队即视为"发送成功"，实际 ACK 由 ReliableEmitter 保证
      */
     const emit = (data) => {
+        // 统一保证 chatId 字段存在：全部 EVENT_MESSAGE_PRIVATE 出站消息都通过
+        // `extra.chatId` 携带，调用方未传入时默认为 ''（默认会话）。
+        // 同时保留调用方传入的其他 extra 字段（如 transferData）。
+        const existingExtra = data.extra ?? {};
+        const chatId = typeof existingExtra.chatId === 'string' ? existingExtra.chatId : '';
+        const payload = {
+            ...data,
+            extra: { ...existingExtra, chatId },
+        };
         // 完整发送日志由 ReliableEmitter 打印（含 idempotencyKey）
-        reliableEmitter.emitWithAck(EVENT_MESSAGE_PRIVATE, data, data.msgId).then((ok) => {
+        reliableEmitter.emitWithAck(EVENT_MESSAGE_PRIVATE, payload, payload.msgId).then((ok) => {
             if (!ok)
-                log?.error(`[${CHANNEL_KEY}] Message delivery failed after retries: msgId=${data.msgId}`);
+                log?.error(`[${CHANNEL_KEY}] Message delivery failed after retries: msgId=${payload.msgId}`);
         });
         return true;
     };
@@ -149,7 +158,7 @@ export async function startGateway(ctx) {
      * @param replyToMsgId - 可选，回复对应的原始消息 ID（用于前端展示引用关系）
      * @param agentId      - 可选，目标 Agent ID
      */
-    const sendReply = (targetId, text, replyToMsgId, agentId) => {
+    const sendReply = (targetId, text, replyToMsgId, chatId, agentId) => {
         log?.info(`[${CHANNEL_KEY}] sendReply: ${text} to ${targetId} (replyTo: ${replyToMsgId || 'none'})`);
         return emit({
             msgId: generateMsgId(),
@@ -159,6 +168,7 @@ export async function startGateway(ctx) {
             timestamp: Date.now(),
             replyToMsgId,
             agentId,
+            extra: { chatId: chatId ?? '' },
         });
     };
     /**
@@ -171,7 +181,7 @@ export async function startGateway(ctx) {
      * @param replyToMsgId - 可选，回复对应的原始消息 ID
      * @param agentId      - 可选，目标 Agent ID
      */
-    const sendFiles = (targetId, text, files, replyToMsgId, agentId) => {
+    const sendFiles = (targetId, text, files, replyToMsgId, chatId, agentId) => {
         return emit({
             msgId: generateMsgId(),
             from: botClientId,
@@ -181,6 +191,7 @@ export async function startGateway(ctx) {
             files,
             replyToMsgId,
             agentId,
+            extra: { chatId: chatId ?? '' },
         });
     };
     /** SocketEmitter 抽象：将 emit / sendReply / sendFiles 和 botClientId 打包传给 inbound 处理器 */
@@ -201,7 +212,7 @@ export async function startGateway(ctx) {
             catch (err) {
                 log?.error(`[${CHANNEL_KEY}] Message handler error: ${err}`);
                 try {
-                    emitter.sendReply(msg.senderId, "消息处理异常，请稍后重试。", msg.messageId);
+                    emitter.sendReply(msg.senderId, "消息处理异常，请稍后重试。", msg.messageId, msg.chatId);
                     emitter.emit({
                         msgId: generateMsgId(),
                         from: emitter.botClientId,
@@ -211,6 +222,7 @@ export async function startGateway(ctx) {
                         kind: "typing_stop",
                         replyToMsgId: msg.messageId,
                         agentId: msg.agentId,
+                        extra: { chatId: msg.chatId ?? '' },
                     });
                 }
                 catch (notifyErr) {

package/dist/src/history/index.js

@@ -20,4 +20,4 @@ export { isSystemInjectedUserMessage, extractText, extractRawText, extractThinki
 // ── Cron Utilities ──
 export { isCronSessionKey, isCronRunKey, isCronBaseKey, extractCronJobId, extractCronRunId, classifySessionKey, listCronSessions, groupCronSessionsByJob, extractCronInfoFromText, cleanCronUserMessage, extractCronJobIdsFromTranscript, findCronSessionsByJobIds, } from "./cron-utils.js";
 // ── Session Reader (核心 API) ──
-export { readSessionHistory, readSessionHistoryTail, readCronHistory, readSessionHistoryWithCron, listSessions, } from "./session-reader.js";
+export { readSessionHistory, readSessionHistoryTail, readCronHistory, readSessionHistoryWithCron, readSessionHistoriesByIds, listSessions, } from "./session-reader.js";

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

@@ -11,6 +11,7 @@
  *   - 消息标准化
  */
 import { stripTransportMetadata, extractFileAttachments, deduplicateFiles, } from "./text-processing.js";
+import { normalizeUsage } from "../usage/index.js";
 // ============================================================
 // 系统注入消息检测
 // ============================================================
@@ -227,6 +228,24 @@ export function normalizeMessage(msg) {
             || undefined;
         toolResult = { toolCallId, name, output };
     }
+    // assistant 角色：归一 usage 字段（缺失时 normalizeUsage 返回 null）。
+    // OpenClaw jsonl 在 message 节点上挂 provider/model/api 三个上下文字段，
+    // 传给 normalizeUsage 用于回填到 UnifiedUsage 顶层。
+    const usage = normalizedRole === "assistant"
+        ? normalizeUsage(msg.usage, {
+            provider: typeof msg.provider === "string" ? msg.provider : undefined,
+            model: typeof msg.model === "string" ? msg.model : undefined,
+            api: typeof msg.api === "string" ? msg.api : undefined,
+        })
+        : null;
+    // 过滤全零 usage（来自 LLM 调用失败的场景，如 401 / 404 / 网络异常等）：
+    //   OpenClaw 对错误的 assistant 消息也会落盘 usage 字段，但所有 token 字段全是 0。
+    //   这种数据没有任何信息量，透出反而会误导用户在历史里看到「0 token」当作"无消耗"展示。
+    //   过滤后 HistoryMessage.usage 缺失 → 与"未知/未上报"语义一致，前端按 undefined 渲染即可。
+    const usageIsEmpty = usage
+        && !usage.inputTokens && !usage.outputTokens && !usage.totalTokens
+        && !usage.cachedInputTokens && !usage.cacheWriteTokens && !usage.reasoningTokens;
+    const effectiveUsage = usageIsEmpty ? null : usage;
     // 跳过完全空的消息
     if (!text && !toolCalls && !toolResult && !thinking && !files?.length)
         return null;
@@ -238,5 +257,6 @@ export function normalizeMessage(msg) {
         ...(toolResult && { toolResult }),
         ...(thinking && { thinking }),
         ...(files && files.length > 0 && { files }),
+        ...(effectiveUsage && { usage: effectiveUsage }),
     };
 }

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

@@ -9,10 +9,10 @@
  *   - listSessions()                — 列出所有 session（含 cron 类型标识）
  */
 import fs from "node:fs";
-import { resolveTranscriptPath } from "./session-store.js";
+import { resolveTranscriptPath, loadSessionStore, resolveTranscriptPathBySessionId } from "./session-store.js";
 import { isSystemInjectedUserMessage, normalizeMessage } from "./message-parser.js";
+import { aggregateUsageByTurn } from "./usage-aggregator.js";
 import { listCronSessions, classifySessionKey, extractCronJobId, extractCronJobIdsFromTranscript, findCronSessionsByJobIds, } from "./cron-utils.js";
-import { loadSessionStore } from "./session-store.js";
 // ============================================================
 // 核心读取：单个 Session
 // ============================================================
@@ -31,7 +31,10 @@ export function readSessionHistory(sessionKey, opts) {
         return [];
     try {
         const raw = fs.readFileSync(filePath, "utf-8");
-        return parseTranscriptLines(raw, { limit, chatOnly });
+        const messages = parseTranscriptLines(raw, { limit, chatOnly });
+        // 按"轮次"聚合 usage（详见 aggregateUsageByTurn 注释）
+        aggregateUsageByTurn(messages);
+        return messages;
     }
     catch {
         return [];
@@ -73,7 +76,10 @@ export function readSessionHistoryTail(sessionKey, opts) {
         if (readStart > 0 && lines.length > 0) {
             lines.shift();
         }
-        return parseLines(lines, { limit, chatOnly });
+        const messages = parseLines(lines, { limit, chatOnly });
+        // 按"轮次"聚合 usage（详见 aggregateUsageByTurn 注释）
+        aggregateUsageByTurn(messages);
+        return messages;
     }
     catch {
         return [];
@@ -199,6 +205,10 @@ export function readSessionHistoryWithCron(sessionKey, opts) {
     // 6. 按时间合并
     const merged = [...mainMessages, ...cronMessages]
         .sort((a, b) => (a.timestamp ?? 0) - (b.timestamp ?? 0));
+    // 主会话与 cron 消息合并后再聚合一次：cron 触发的"system: ⏰ ..."类消息
+    // 通常被识别为 user 角色（系统注入），会自然分隔轮次，因此聚合不会把
+    // 主会话和 cron 提醒的 usage 错误合并。
+    aggregateUsageByTurn(merged);
     return merged.length > limit ? merged.slice(-limit) : merged;
 }
 // ============================================================
@@ -226,6 +236,66 @@ export function listSessions(agentId) {
         .sort((a, b) => (b.updatedAt ?? 0) - (a.updatedAt ?? 0));
 }
 // ============================================================
+// 多 SessionId 合并读取（跨 reset 历史回看）
+// ============================================================
+/**
+ * 给定一组 sessionId（按时间序），合并读取它们各自 jsonl 中的消息。
+ *
+ * 适用场景：
+ *   chats.json 的 sessionIdHistory 保存了某 chat 历史上用过的所有 sessionId
+ *   （含已被 reset 归档的旧 ID 和当前在用的 ID）。本函数据此把多份 jsonl
+ *   合并为一份按时间正序的消息流，让前端能跨 reset 看到完整对话历史。
+ *
+ * 实现细节：
+ *   - 通过 resolveTranscriptPathBySessionId 直接按 sessionId 定位文件，
+ *     既能命中活跃文件 <sessionId>.jsonl，也能命中归档文件
+ *     <sessionId>.jsonl.reset.* / .deleted.*；
+ *   - 单份 jsonl 内已按写入顺序自然有序，不同 sessionId 之间通过 timestamp
+ *     做最终归并排序；
+ *   - 仅返回最后 limit 条（保持与 readSessionHistory 一致的行为）。
+ *
+ * @param sessionIds - 该 chat 用过的所有 sessionId（顺序由调用方保证：
+ *                     通常 = chats.json[chatId].sessionIdHistory）
+ * @param opts       - 与 readSessionHistory 一致；agentId 用于路径解析
+ * @returns 按 timestamp 升序合并的消息列表（最多 limit 条）
+ */
+export function readSessionHistoriesByIds(sessionIds, opts) {
+    const limit = opts?.limit ?? 200;
+    const chatOnly = opts?.chatOnly ?? false;
+    if (!Array.isArray(sessionIds) || sessionIds.length === 0)
+        return [];
+    const all = [];
+    // 去重 + 保持顺序：同一 sessionId 出现多次只读一次
+    const seen = new Set();
+    for (const sid of sessionIds) {
+        if (!sid || seen.has(sid))
+            continue;
+        seen.add(sid);
+        const filePath = resolveTranscriptPathBySessionId(sid, opts?.agentId);
+        if (!filePath)
+            continue;
+        try {
+            const raw = fs.readFileSync(filePath, "utf-8");
+            // 单文件先读到上限：避免单段过大撑爆内存；最终还要按 limit 截断
+            const msgs = parseTranscriptLines(raw, { limit, chatOnly });
+            for (const m of msgs)
+                all.push(m);
+        }
+        catch {
+            // 单段读取失败不阻断其他段
+        }
+    }
+    if (all.length === 0)
+        return [];
+    // 多段合并：按 timestamp 升序；无 timestamp 的消息按相对顺序兜底
+    all.sort((a, b) => (a.timestamp ?? 0) - (b.timestamp ?? 0));
+    // 合并后再做 usage 轮次聚合：跨 sessionId 的同一对话回合也能被识别
+    // （注意：每个 sessionId 内部的消息已经在 readSessionHistory 中聚合过一次，
+    //  幂等，再聚合一次结果不变；此处主要解决跨 reset 的轮次合并场景）
+    aggregateUsageByTurn(all);
+    return all.length > limit ? all.slice(-limit) : all;
+}
+// ============================================================
 // 内部工具函数
 // ============================================================
 /**

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

@@ -29,6 +29,7 @@ export function resolveOpenClawHome() {
 export function resolveSessionsDir(agentId) {
     const home = resolveOpenClawHome();
     const id = agentId?.trim() || "main";
+    // 例如：~/.openclaw/agents/main/sessions
     return path.join(home, "agents", id, "sessions");
 }
 // ============================================================
@@ -45,6 +46,7 @@ let _lastStoreFilePath = null;
  * 加载 sessions.json 索引，获取 sessionKey → sessionEntry 映射
  */
 export function loadSessionStore(agentId) {
+    // ~/.openclaw/agents/main/sessions/sessions.json
     const storePath = path.join(resolveSessionsDir(agentId), "sessions.json");
     //   const storePath = path.join(currentDir, "../../sessions/sessions.json").replace("file:", "");
     const loaded = _tryLoadStore(storePath);
@@ -169,3 +171,44 @@ function _findArchivedTranscript(dir, jsonlFileName) {
     }
     return null;
 }
+/**
+ * 直接根据 sessionId 解析 transcript 文件路径（不依赖 sessions.json 索引）。
+ *
+ * 适用场景：
+ *   chats.json 中的 sessionIdHistory 保存了某 chat 历史上用过的所有 sessionId，
+ *   这些 sessionId 在 reset 之后会被框架从 sessions.json 索引中移除（旧条目失效），
+ *   因此无法再通过 sessionKey 反查；只能直接按 sessionId 在磁盘上定位 jsonl。
+ *
+ * 解析顺序：
+ *   1. <sessionsDir>/<sessionId>.jsonl —— 当前在用的 transcript
+ *   2. <sessionsDir>/<sessionId>.jsonl.reset.* / .deleted.* —— 归档 transcript
+ *   3. storeDir 兜底（同 resolveTranscriptPath，离线分析场景）
+ *
+ * 找不到则返回 null。
+ */
+export function resolveTranscriptPathBySessionId(sessionId, agentId) {
+    if (!sessionId || !sessionId.trim())
+        return null;
+    const sessionsDir = resolveSessionsDir(agentId);
+    const jsonlFileName = `${sessionId}.jsonl`;
+    // 1. 标准目录下的活跃 transcript
+    const defaultPath = path.join(sessionsDir, jsonlFileName);
+    if (fs.existsSync(defaultPath))
+        return defaultPath;
+    // 2. 同目录归档文件
+    const archivedPath = _findArchivedTranscript(sessionsDir, jsonlFileName);
+    if (archivedPath)
+        return archivedPath;
+    // 3. storeDir 兜底（离线分析场景）
+    // 注意：getStoreDir() 仅在 loadSessionStore() 成功后才有值，调用方需确保前置条件
+    const storeDir = getStoreDir();
+    if (storeDir && storeDir !== sessionsDir) {
+        const siblingPath = path.join(storeDir, jsonlFileName);
+        if (fs.existsSync(siblingPath))
+            return siblingPath;
+        const archivedInStore = _findArchivedTranscript(storeDir, jsonlFileName);
+        if (archivedInStore)
+            return archivedInStore;
+    }
+    return null;
+}

package/dist/src/history/text-processing.js

@@ -71,6 +71,13 @@ export function stripResidualMetadata(text) {
     result = result.replace(/<file\b[^>]*>.*?<\/file>/gs, "");
     // 移除 "用户发送了文件: filename (size)" 描述文本
     result = result.replace(/用户发送了文件:\s*.+?\s*\([^)]+\)\s*/g, "");
+    // 移除 OpenClaw 媒体消息的结构化包装块：
+    //   [Image] / [Video] / [Audio] / [Document] / [Image 1] 等媒体类型标记行
+    result = result.replace(/^\[[A-Za-z][\w ]*\]\s*$/gm, "");
+    //   "User text:" 单独一行的 label（其后紧跟用户真实输入，需保留输入本身）
+    result = result.replace(/^User text:\s*$/gm, "");
+    //   "Description:\n<AI 对媒体的自动描述>" — 位于消息尾部，直接吃到文本末尾
+    result = result.replace(/^Description:[\s\S]*$/m, "");
     return result.trim();
 }
 // ============================================================