lightclawbot 1.2.0-beta.3 → 1.2.5

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/session-reader.js

@@ -9,10 +9,9 @@
  *   - 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 { listCronSessions, classifySessionKey, extractCronJobId, extractCronJobIdsFromTranscript, findCronSessionsByJobIds, } from "./cron-utils.js";
-import { loadSessionStore } from "./session-store.js";
 // ============================================================
 // 核心读取：单个 Session
 // ============================================================
@@ -226,6 +225,62 @@ 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));
+    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();
 }
 // ============================================================

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 一一对应 */
@@ -251,7 +265,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);
             }
         }
     };