lightclawbot 1.2.6-beta.0 → 1.2.7

package/dist/src/socket/native-socket.js

@@ -14,6 +14,9 @@
  */
 import WebSocket from 'ws';
 import { SOCKET_RECONNECTION_DELAY, SOCKET_RECONNECTION_DELAY_MAX, SOCKET_RECONNECTION_ATTEMPTS } from '../config.js';
+import { getModuleLogger } from '../utils/logger.js';
+/** 模块级日志器 */
+const moduleLog = getModuleLogger('socket.native-socket');
 // ============================================================
 // NativeSocketClient 实现
 // ============================================================
@@ -59,21 +62,19 @@ export class NativeSocketClient {
     // ----------------------------------------------------------
     // 构造函数
     // ----------------------------------------------------------
-    /** 日志对象（可选）。调用方通常传入 GatewayContext.log，用于打印连接/重连/错误等诊断信息。 */
-    log;
+    /** 日志对象，使用公共方法获取。 */
+    log = moduleLog;
     /** 日志前缀，便于在多实例场景下区分日志来源。 */
     logPrefix;
     /**
      * @param url     WebSocket 服务端地址（ws:// 或 wss://），认证所需的 ticket 等参数请直接拼到 URL query 上
      * @param options 连接选项
      *   - path: 连接路径（如 /claw-socket），会附加到 URL
-     *   - log:  日志对象（可选），用于打印连接生命周期与异常信息
      *   - logPrefix: 日志前缀（可选），默认 `[NativeSocket]`
      */
     constructor(url, options = {}) {
         this.url = url;
         this.options = options;
-        this.log = options.log;
         this.logPrefix = options.logPrefix ?? '[NativeSocket]';
         this._connect();
     }
@@ -169,7 +170,7 @@ export class NativeSocketClient {
         };
     }
     disconnect() {
-        this.log?.info(`${this.logPrefix} disconnect() called (wasConnected=${this._connected})`);
+        this.log.info(`${this.logPrefix} disconnect() called (wasConnected=${this._connected})`);
         this._manualDisconnect = true;
         this._clearReconnectTimer();
         const wasConnected = this._connected;
@@ -184,10 +185,10 @@ export class NativeSocketClient {
         // 手动触发重连（用于服务端主动断开后的手动重连场景）
         // 若当前已有活跃连接（CONNECTING 或 OPEN），直接返回，避免连接泄漏
         if (this._ws && (this._ws.readyState === WebSocket.CONNECTING || this._ws.readyState === WebSocket.OPEN)) {
-            this.log?.debug?.(`${this.logPrefix} connect() skipped, already ${this._ws.readyState === WebSocket.OPEN ? 'OPEN' : 'CONNECTING'}`);
+            this.log.debug?.(`${this.logPrefix} connect() skipped, already ${this._ws.readyState === WebSocket.OPEN ? 'OPEN' : 'CONNECTING'}`);
             return this;
         }
-        this.log?.info(`${this.logPrefix} connect() called, manually reconnecting`);
+        this.log.info(`${this.logPrefix} connect() called, manually reconnecting`);
         this._manualDisconnect = false;
         this._reconnectAttempts = 0;
         this._clearReconnectTimer();
@@ -200,14 +201,14 @@ export class NativeSocketClient {
     _connect() {
         // 构建完整 URL（仅拼接 path，认证通过 URL query 参数完成，无需 headers）
         const fullUrl = this._buildUrl();
-        this.log?.info(`${this.logPrefix} Connecting to ${fullUrl}`);
+        this.log.info(`${this.logPrefix} Connecting to ${fullUrl}`);
         try {
             const ws = new WebSocket(fullUrl);
             this._ws = ws;
             ws.onopen = () => {
                 this._reconnectAttempts = 0;
                 this._connected = true;
-                this.log?.info(`${this.logPrefix} WebSocket opened`);
+                this.log.info(`${this.logPrefix} WebSocket opened`);
                 this._dispatch('connect');
             };
             ws.onmessage = (event) => {
@@ -218,7 +219,7 @@ export class NativeSocketClient {
                 this._connected = false;
                 this._id = undefined;
                 this._ws = null;
-                this.log?.info(`${this.logPrefix} WebSocket closed (code=${event.code}, reason="${event.reason}", wasClean=${event.wasClean}, wasConnected=${wasConnected})`);
+                this.log.info(`${this.logPrefix} WebSocket closed (code=${event.code}, reason="${event.reason}", wasClean=${event.wasClean}, wasConnected=${wasConnected})`);
                 // 立即 flush 所有挂起的 ACK，以断开错误立即回调，而非等待超时
                 this._flushPendingAcks(new Error('disconnect'));
                 if (wasConnected) {
@@ -231,14 +232,14 @@ export class NativeSocketClient {
             };
             ws.onerror = (event) => {
                 const detail = event.error?.stack || event.message || 'unknown';
-                this.log?.error(`${this.logPrefix} WebSocket error: ${detail}`);
+                this.log.error(`${this.logPrefix} WebSocket error: ${detail}`);
                 // onerror 后必然触发 onclose，此处只派发 connect_error 事件
                 this._dispatch('connect_error', new Error('WebSocket error'));
             };
         }
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);
-            this.log?.error(`${this.logPrefix} Failed to construct WebSocket: ${message}`);
+            this.log.error(`${this.logPrefix} Failed to construct WebSocket: ${message}`);
             this._dispatch('connect_error', err instanceof Error ? err : new Error(String(err)));
             if (!this._manualDisconnect) {
                 this._scheduleReconnect();
@@ -254,16 +255,16 @@ export class NativeSocketClient {
             msg = JSON.parse(raw);
         }
         catch {
-            this.log?.warn(`${this.logPrefix} Received non-JSON message, ignored`);
+            this.log.warn(`${this.logPrefix} Received non-JSON message, ignored`);
             return; // 忽略非 JSON 消息
         }
         if (!msg.event) {
-            this.log?.warn(`${this.logPrefix} Received message without event field, ignored`);
+            this.log.warn(`${this.logPrefix} Received message without event field, ignored`);
             return;
         }
         // 处理 ACK 回包
         if (msg.event === 'message:ack') {
-            this.log?.info(`${this.logPrefix} Received message ACK ${JSON.stringify(msg)}`);
+            // this.log.info(`${this.logPrefix} Received message ACK ${JSON.stringify(msg)}`);
             // 服务端通过 relatedMsgId 回传上行消息的 msgId，用于匹配挂起的 ACK 记录
             // pendingKey = data.msgId（注册时），relatedMsgId = msgId（服务端回传），两者一致
             const ackData = msg.data;
@@ -276,7 +277,7 @@ export class NativeSocketClient {
                     pending.callback(null);
                 }
                 else {
-                    this.log?.debug?.(`${this.logPrefix} Received ACK for unknown relatedMsgId=${relatedMsgId}`);
+                    this.log.debug?.(`${this.logPrefix} Received ACK for unknown relatedMsgId=${relatedMsgId}`);
                 }
             }
             return;
@@ -286,12 +287,12 @@ export class NativeSocketClient {
             const handshakeData = msg.data;
             if (handshakeData?.id) {
                 this._id = handshakeData.id;
-                this.log?.info(`${this.logPrefix} Handshake received, socket id=${this._id}`);
+                this.log.info(`${this.logPrefix} Handshake received, socket id=${this._id}`);
             }
             return;
         }
         // 分发业务事件
-        this.log?.debug?.(`${this.logPrefix} Dispatch event: ${msg.event}`);
+        this.log.debug?.(`${this.logPrefix} Dispatch event: ${msg.event}`);
         this._dispatch(msg.event, msg.data);
     }
     // ----------------------------------------------------------
@@ -318,14 +319,14 @@ export class NativeSocketClient {
     _scheduleReconnect() {
         // 超过最大重连次数时停止重连
         if (SOCKET_RECONNECTION_ATTEMPTS !== Infinity && this._reconnectAttempts >= SOCKET_RECONNECTION_ATTEMPTS) {
-            this.log?.error(`${this.logPrefix} Max reconnection attempts (${SOCKET_RECONNECTION_ATTEMPTS}) reached, giving up`);
+            this.log.error(`${this.logPrefix} Max reconnection attempts (${SOCKET_RECONNECTION_ATTEMPTS}) reached, giving up`);
             this._dispatch('connect_error', new Error(`Max reconnection attempts (${SOCKET_RECONNECTION_ATTEMPTS}) reached`));
             return;
         }
         // 指数退避延迟：delay = min(base * 2^attempts, max)
         const delay = Math.min(SOCKET_RECONNECTION_DELAY * Math.pow(2, this._reconnectAttempts), SOCKET_RECONNECTION_DELAY_MAX);
         this._reconnectAttempts++;
-        this.log?.warn(`${this.logPrefix} Scheduling reconnect attempt #${this._reconnectAttempts} in ${delay}ms`);
+        this.log.warn(`${this.logPrefix} Scheduling reconnect attempt #${this._reconnectAttempts} in ${delay}ms`);
         this._reconnectTimer = setTimeout(() => {
             this._reconnectTimer = null;
             if (!this._manualDisconnect) {

package/dist/src/socket/registry.js

@@ -11,6 +11,9 @@
  *   仅在 gateway 彻底销毁（cleanup）时才删除 entry。
  */
 import { MAX_PENDING_MESSAGES, EVENT_MESSAGE_PRIVATE } from "../config.js";
+import { getModuleLogger } from '../utils/logger.js';
+/** 模块级日志器 */
+const log = getModuleLogger('socket.registry');
 /** accountId → SocketEntry */
 const registry = new Map();
 // ============================================================
@@ -81,7 +84,7 @@ export function bufferMessage(accountId, message) {
  * 如果有 ReliableEmitter，走可靠发送；否则 fallback 直接 emit。
  * 返回发送成功 / 失败的计数。
  */
-export function flushPendingMessages(accountId, log) {
+export function flushPendingMessages(accountId) {
     const entry = registry.get(accountId);
     if (!entry)
         return { sent: 0, failed: 0 };
@@ -109,12 +112,12 @@ export function flushPendingMessages(accountId, log) {
             }
             catch {
                 failed++;
-                log?.warn(`[socket-registry] Failed to flush buffered message: msgId=${msg.msgId}`);
+                log.warn(`[socket-registry] Failed to flush buffered message: msgId=${msg.msgId}`);
             }
         }
     }
     if (sent > 0 || failed > 0) {
-        log?.info(`[socket-registry] Flushed pending messages: sent=${sent}, failed=${failed}`);
+        log.info(`[socket-registry] Flushed pending messages: sent=${sent}, failed=${failed}`);
     }
     return { sent, failed };
 }

package/dist/src/socket/reliable-emitter.js

@@ -23,12 +23,14 @@
  * @format
  */
 import { EMIT_ACK_TIMEOUT, EMIT_MAX_RETRIES, EMIT_RETRY_BASE_DELAY, EMIT_RETRY_MAX_DELAY, EMIT_PENDING_MAX, } from '../config.js';
+import { getModuleLogger } from '../utils/logger.js';
+/** 模块级日志器 */
+const moduleLog = getModuleLogger('socket.reliable-emitter');
 // ============================================================
 // ReliableEmitter 主类
 // ============================================================
 export class ReliableEmitter {
     getSocket;
-    log;
     /**
      * 待确认消息队列。
      * key = emitId（内部唯一标识），value = PendingMessage。
@@ -57,9 +59,10 @@ export class ReliableEmitter {
      * 业务通道前缀（如 `[lightclawbot]`），使上游日志风格统一。
      */
     logPrefix;
-    constructor(getSocket, log, logPrefix = "[ReliableEmitter]") {
+    /** 模块级日志器引用 */
+    log = moduleLog;
+    constructor(getSocket, logPrefix = "[ReliableEmitter]") {
         this.getSocket = getSocket;
-        this.log = log;
         this.logPrefix = logPrefix;
     }
     // ----------------------------------------------------------
@@ -96,7 +99,7 @@ export class ReliableEmitter {
         //   - data.msgId 保持业务层原值不变，同一条消息的所有重试相同，服务端用它识别消息身份
         const enrichedData = { ...data, idempotencyKey: emitId };
         // 统一的发送日志（含最终 payload），业务层无需再打
-        this.log?.info(`${this.logPrefix} emit: ${JSON.stringify(enrichedData)}`);
+        this.log.info(`${this.logPrefix} emit: ${JSON.stringify(enrichedData)}`);
         return new Promise((resolve) => {
             const entry = {
                 id: emitId,
@@ -112,7 +115,7 @@ export class ReliableEmitter {
             this.pending.set(emitId, entry);
             if (this.paused) {
                 // 断线中，等 resume 统一重发
-                this.log?.info(`${this.logPrefix} Queued while paused: emitId=${emitId}, msgId=${msgId}`);
+                this.log.info(`${this.logPrefix} Queued while paused: emitId=${emitId}, msgId=${msgId}`);
                 return;
             }
             // 正常状态：立即尝试发送
@@ -140,7 +143,7 @@ export class ReliableEmitter {
                 entry.retryTimer = null;
             }
         }
-        this.log?.info(`${this.logPrefix} Paused, ${this.pending.size} message(s) pending`);
+        this.log.info(`${this.logPrefix} Paused, ${this.pending.size} message(s) pending`);
     }
     /**
      * 重连时调用 — 立即重发所有待确认消息。
@@ -156,7 +159,7 @@ export class ReliableEmitter {
         if (!this.paused)
             return;
         this.paused = false;
-        this.log?.info(`${this.logPrefix} Resumed, re-emitting ${this.pending.size} pending message(s)`);
+        this.log.info(`${this.logPrefix} Resumed, re-emitting ${this.pending.size} pending message(s)`);
         for (const entry of this.pending.values()) {
             this.doEmit(entry);
         }
@@ -176,7 +179,7 @@ export class ReliableEmitter {
             entry.resolve(false);
         }
         this.pending.clear();
-        this.log?.info(`${this.logPrefix} Destroyed`);
+        this.log.info(`${this.logPrefix} Destroyed`);
     }
     /**
      * 当前待确认消息数（实时值）。
@@ -228,12 +231,12 @@ export class ReliableEmitter {
                 return;
             if (err) {
                 // ACK 超时或服务端返回错误，安排下一次重试
-                this.log?.warn(`[ReliableEmitter] ACK error: emitId=${entry.id}, msgId=${entry.msgId}, err=${err.message}, retryCount=${entry.retryCount}`);
+                this.log.warn(`[ReliableEmitter] ACK error: emitId=${entry.id}, msgId=${entry.msgId}, err=${err.message}, retryCount=${entry.retryCount}`);
                 this.scheduleRetry(entry);
             }
             else {
                 // 服务端已确认收到，从 pending 队列移除
-                // this.log?.info(
+                // this.log.info(
                 //   `[ReliableEmitter] ACK success: emitId=${entry.id}, msgId=${entry.msgId}, retryCount=${entry.retryCount}`,
                 // );
                 this.confirm(entry.id);
@@ -274,7 +277,7 @@ export class ReliableEmitter {
             // 重试次数耗尽，放弃该消息
             this.pending.delete(entry.id);
             this.stats.totalFailed++;
-            this.log?.error(`${this.logPrefix} Gave up after ${entry.retryCount} retries: emitId=${entry.id}, msgId=${entry.msgId}, ` +
+            this.log.error(`${this.logPrefix} Gave up after ${entry.retryCount} retries: emitId=${entry.id}, msgId=${entry.msgId}, ` +
                 `elapsed=${Date.now() - entry.createdAt}ms`);
             // 通知调用方：消息最终未被确认
             entry.resolve(false);
@@ -284,7 +287,7 @@ export class ReliableEmitter {
         entry.retryCount++;
         this.stats.totalRetries++;
         const delay = this.getRetryDelay(entry.retryCount);
-        this.log?.info(`${this.logPrefix} Retry #${entry.retryCount} in ${delay}ms: emitId=${entry.id}, msgId=${entry.msgId}`);
+        this.log.info(`${this.logPrefix} Retry #${entry.retryCount} in ${delay}ms: emitId=${entry.id}, msgId=${entry.msgId}`);
         entry.retryTimer = setTimeout(() => {
             entry.retryTimer = null;
             // 定时器触发时再次检查是否断线（重试等待期间可能发生断线）
@@ -333,7 +336,7 @@ export class ReliableEmitter {
                 clearTimeout(oldest.retryTimer);
             this.pending.delete(oldest.id);
             this.stats.totalFailed++;
-            this.log?.warn(`${this.logPrefix} Evicted oldest pending: emitId=${oldest.id}, msgId=${oldest.msgId}`);
+            this.log.warn(`${this.logPrefix} Evicted oldest pending: emitId=${oldest.id}, msgId=${oldest.msgId}`);
             oldest.resolve(false);
         }
     }

package/dist/src/socket/service/chat-common.js

@@ -0,0 +1,36 @@
+/**
+ * Chat handler 共享工具函数
+ *
+ * 提供 list / create / update / delete 四个 handler 共用的：
+ *   - createChatErrorSender 工厂函数
+ *   - 模块级日志器
+ *
+ */
+import { CHANNEL_KEY, EVENT_CHAT_RESPONSE } from '../../config.js';
+import { generateMsgId } from '../../dedup.js';
+import { getModuleLogger } from '../../utils/logger.js';
+/** 模块级日志器 */
+export const log = getModuleLogger('socket.chat');
+/**
+ * 生成统一的错误响应发送器。
+ * @param ctx   共享上下文
+ * @param extra 额外字段（如 chatId、兜底 chats: []）
+ */
+export function createChatErrorSender(ctx, extra = {}) {
+    const { responseMsgId, botClientId, userId, agentId, type, reliableEmitter } = 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);
+    };
+}
+/** 生成响应 msgId 的快捷方法 */
+export { generateMsgId };

package/dist/src/socket/service/chat-create.js

@@ -0,0 +1,75 @@
+/**
+ * @file chat-create.ts
+ * @description Chat handler — create（新建会话）
+ *
+ * 新建一条会话元数据，chatId = randomUUID()，插入列表最前。
+ * 文件或目录不存在时由 writeChatsFile 递归创建。
+ */
+import { randomUUID } from 'node:crypto';
+import { CHANNEL_KEY, EVENT_CHAT_RESPONSE } from '../../config.js';
+import { readChatsFile, resolveChatsFilePath, writeChatsFile } from '../../utils/common.js';
+import { log, generateMsgId, createChatErrorSender } from './chat-common.js';
+/**
+ * 创建新的会话元数据
+ * @returns 包含默认值的 ChatMeta 对象
+ */
+function buildNewChatMeta() {
+    const now = Date.now();
+    return {
+        chatId: randomUUID(),
+        title: '新会话',
+        titleLocked: false,
+        createdAt: now,
+        updatedAt: now,
+        pinned: false,
+        sessionIdHistory: [],
+    };
+}
+/**
+ * 发送创建成功响应
+ * @param params - handler 基础参数
+ * @param responseMsgId - 响应消息 ID
+ * @param newChat - 新创建的会话元数据
+ */
+function emitCreateResponse(params, responseMsgId, newChat) {
+    const { botClientId, userId, agentId, reliableEmitter } = params;
+    reliableEmitter.emitWithAck(EVENT_CHAT_RESPONSE, {
+        msgId: responseMsgId,
+        from: botClientId,
+        to: userId,
+        type: 'create',
+        agentId,
+        chats: [newChat],
+        timestamp: Date.now(),
+    }, responseMsgId);
+}
+/**
+ * 处理 EVENT_CHAT_REQUEST(type=create)
+ *
+ * 流程：解析存储路径 → 读取现有会话列表 → 创建新会话 → 写入文件 → 回包
+ *
+ * @param params - Chat handler 通用入参
+ */
+export function handleChatCreate(params) {
+    const { userId, agentId, botClientId, reliableEmitter } = params;
+    const chatsPath = resolveChatsFilePath(agentId, userId);
+    const responseMsgId = generateMsgId();
+    const sendError = createChatErrorSender({
+        responseMsgId,
+        botClientId,
+        userId,
+        agentId,
+        type: 'create',
+        reliableEmitter,
+    });
+    try {
+        const existing = readChatsFile(chatsPath);
+        const newChat = buildNewChatMeta();
+        writeChatsFile(chatsPath, [newChat, ...existing]);
+        log.info(`[${CHANNEL_KEY}] 会话创建成功: userId=${userId}, agentId=${agentId}, chatId=${newChat.chatId}`);
+        emitCreateResponse(params, responseMsgId, newChat);
+    }
+    catch (err) {
+        sendError(err instanceof Error ? err.message : String(err));
+    }
+}

package/dist/src/socket/service/chat-delete.js

@@ -0,0 +1,94 @@
+/**
+ * @file chat-delete.ts
+ * @description Chat handler — delete（删除会话）
+ *
+ * 该模块负责处理会话删除请求：
+ * 1. 根据传入的 chatId 在本地 JSON 文件中定位目标会话
+ * 2. 将目标会话从列表中剔除并原子写回文件
+ * 3. 通过可靠消息通道将删除结果推送给客户端
+ *
+ * 异常处理：
+ * - 会话文件不存在时，返回 error 响应
+ * - 目标 chatId 未找到时，返回 error 响应
+ * - 文件读写异常时，捕获错误并返回 error 响应
+ */
+import * as fs from 'node:fs';
+import { CHANNEL_KEY, EVENT_CHAT_RESPONSE } from '../../config.js';
+import { readChatsFile, resolveChatsFilePath, writeChatsFile } from '../../utils/common.js';
+import { log, generateMsgId, createChatErrorSender } from './chat-common.js';
+/**
+ * 发送删除成功响应
+ *
+ * 通过 reliableEmitter 的 emitWithAck 方法发送带确认机制的响应消息，
+ * 确保客户端能够可靠接收到删除操作的结果。
+ *
+ * @param params - handler 基础参数，包含用户/Agent/Bot 标识及消息发射器
+ * @param responseMsgId - 本次响应的唯一消息 ID，用于客户端消息去重和确认
+ * @param deletedChat - 被删除的会话元数据，回传给客户端用于 UI 同步
+ */
+function emitDeleteResponse(params, responseMsgId, deletedChat) {
+    const { botClientId, userId, agentId, reliableEmitter } = params;
+    // 通过可靠消息通道发送删除成功响应，附带被删除的会话信息
+    reliableEmitter.emitWithAck(EVENT_CHAT_RESPONSE, {
+        msgId: responseMsgId, // 响应消息唯一标识
+        from: botClientId, // 发送方：Bot 客户端 ID
+        to: userId, // 接收方：用户 ID
+        type: 'delete', // 操作类型标识
+        agentId, // 关联的 Agent ID
+        chats: [deletedChat], // 被删除的会话列表（单条）
+        timestamp: Date.now(), // 响应时间戳
+    }, responseMsgId);
+}
+/**
+ * 处理 EVENT_CHAT_REQUEST(type=delete)
+ *
+ * 完整处理流程：
+ * 1. 解构入参，获取用户/Agent/会话标识
+ * 2. 解析会话存储文件路径
+ * 3. 生成本次响应的唯一消息 ID
+ * 4. 创建统一的错误发送器（复用 chat-common 工具函数）
+ * 5. 校验会话文件是否存在（前置守卫）
+ * 6. 读取会话列表，查找目标会话
+ * 7. 过滤掉目标会话，将剩余列表写回文件
+ * 8. 记录操作日志，发送成功响应
+ *
+ * @param params - Chat delete 操作入参，继承自 ChatHandlerParams 并扩展 chatId 字段
+ */
+export function handleChatDelete(params) {
+    // 解构所需参数：用户ID、AgentID、目标会话ID、Bot客户端ID、可靠消息发射器
+    const { userId, agentId, chatId, botClientId, reliableEmitter } = params;
+    // 根据 agentId 和 userId 解析会话列表的本地 JSON 文件路径
+    const chatsPath = resolveChatsFilePath(agentId, userId);
+    // 生成本次响应的唯一消息 ID，用于消息追踪和 ACK 确认
+    const responseMsgId = generateMsgId();
+    // 创建统一的错误响应发送器，封装了错误消息的格式化和发送逻辑
+    const sendError = createChatErrorSender({ responseMsgId, botClientId, userId, agentId, type: 'delete', reliableEmitter }, { chatId });
+    // 前置守卫：检查会话文件是否存在，不存在则直接返回错误
+    if (!fs.existsSync(chatsPath)) {
+        sendError(`会话文件不存在: ${chatsPath}`);
+        return;
+    }
+    try {
+        // 读取当前会话列表（JSON 文件 → ChatMeta[] 数组）
+        const chats = readChatsFile(chatsPath);
+        // 在列表中查找目标会话对象
+        const targetChat = chats.find((c) => c.chatId === chatId);
+        // 目标会话不存在时返回错误响应
+        if (!targetChat) {
+            sendError(`会话不存在: chatId=${chatId}`);
+            return;
+        }
+        // 过滤掉目标会话，得到删除后的剩余列表
+        const remainingChats = chats.filter((c) => c.chatId !== chatId);
+        // 将剩余会话列表原子写回文件（writeChatsFile 内部保证写入的原子性）
+        writeChatsFile(chatsPath, remainingChats);
+        // 记录删除成功日志，包含关键上下文信息便于排查
+        log.info(`[${CHANNEL_KEY}] 会话删除成功: userId=${userId}, agentId=${agentId}, chatId=${chatId}, 剩余=${remainingChats.length}`);
+        // 向客户端发送删除成功响应
+        emitDeleteResponse(params, responseMsgId, targetChat);
+    }
+    catch (err) {
+        // 捕获文件读写等异常，统一通过错误发送器返回给客户端
+        sendError(err instanceof Error ? err.message : String(err));
+    }
+}

package/dist/src/socket/service/chat-list.js

@@ -0,0 +1,82 @@
+/**
+ * @file chat-list.ts
+ * @description Chat handler — list（会话列表查询）
+ *
+ * 该模块负责处理会话列表查询请求：
+ * 1. 根据 agentId + userId 定位本地 JSON 存储文件
+ * 2. 读取并返回该用户在指定 Agent 下的全部会话列表
+ * 3. 通过可靠消息通道将查询结果推送给客户端
+ *
+ * 兜底策略：
+ * - 文件不存在时由 readChatsFileOrInitDefault 主动落盘一条默认会话条目
+ * - 保证前端拉列表永远拿到至少一项，避免空列表导致的 UI 异常
+ */
+// ─── 依赖导入 ────────────────────────────────────────────────────────────────
+/** 通道标识常量和聊天响应事件名 */
+import { CHANNEL_KEY, EVENT_CHAT_RESPONSE } from '../../config.js';
+/** 文件读取工具：readChatsFileOrInitDefault 在文件缺失时自动创建默认条目 */
+import { readChatsFileOrInitDefault, resolveChatsFilePath } from '../../utils/common.js';
+/** 共享工具：模块日志器、消息 ID 生成器、错误发送器工厂 */
+import { log, generateMsgId, createChatErrorSender } from './chat-common.js';
+// ─── 内部辅助函数 ─────────────────────────────────────────────────────────────
+/**
+ * 发送列表查询成功响应
+ *
+ * 通过 reliableEmitter 的 emitWithAck 方法发送带确认机制的响应消息，
+ * 确保客户端能够可靠接收到会话列表数据。
+ *
+ * @param params - handler 基础参数，包含用户/Agent/Bot 标识及消息发射器
+ * @param responseMsgId - 本次响应的唯一消息 ID，用于客户端消息去重和 ACK 确认
+ * @param chats - 完整的会话列表数据，至少包含一条兜底记录
+ */
+function emitListResponse(params, responseMsgId, chats) {
+    const { botClientId, userId, agentId, reliableEmitter } = params;
+    // 通过可靠消息通道发送列表查询成功响应
+    reliableEmitter.emitWithAck(EVENT_CHAT_RESPONSE, {
+        msgId: responseMsgId, // 响应消息唯一标识
+        from: botClientId, // 发送方：Bot 客户端 ID
+        to: userId, // 接收方：用户 ID
+        type: 'list', // 操作类型标识
+        agentId, // 关联的 Agent ID
+        chats, // 会话列表数据（ChatMeta[]）
+        timestamp: Date.now(), // 响应时间戳
+    }, responseMsgId);
+}
+// ─── 导出函数 ─────────────────────────────────────────────────────────────────
+/**
+ * 处理 EVENT_CHAT_REQUEST(type=list)
+ *
+ * 完整处理流程：
+ * 1. 解构入参，获取用户和 Agent 标识
+ * 2. 根据 agentId + userId 解析会话存储文件路径
+ * 3. 生成本次响应的唯一消息 ID
+ * 4. 创建统一的错误发送器（复用 chat-common 工具函数）
+ * 5. 读取会话列表（文件不存在时自动初始化默认条目）
+ * 6. 记录操作日志，发送成功响应
+ *
+ * @param params - Chat handler 通用入参，包含 userId、agentId、botClientId、reliableEmitter
+ */
+export function handleChatList(params) {
+    // 解构直接使用的字段
+    const { userId, agentId } = params;
+    // 根据 agentId 和 userId 解析会话列表的本地 JSON 文件路径
+    // 路径格式：~/.openclaw/agents/<agentId>/chats/<userId>/chats.json
+    const chatsPath = resolveChatsFilePath(agentId, userId);
+    // 生成本次响应的唯一消息 ID，用于消息追踪和 ACK 确认
+    const responseMsgId = generateMsgId();
+    // 创建统一的错误响应发送器
+    // 附加 chats: [] 确保客户端即使收到错误也能正确处理列表字段
+    const sendError = createChatErrorSender({ responseMsgId, botClientId: params.botClientId, userId, agentId, type: 'list', reliableEmitter: params.reliableEmitter }, { chats: [] });
+    try {
+        // 读取会话列表；文件不存在时自动创建并写入一条默认会话，保证返回非空数组
+        const chats = readChatsFileOrInitDefault(chatsPath);
+        // 记录查询成功日志，包含关键上下文信息便于排查
+        log.info(`[${CHANNEL_KEY}] 会话列表查询成功: userId=${userId}, agentId=${agentId}, count=${chats.length}`);
+        // 向客户端发送列表查询成功响应
+        emitListResponse(params, responseMsgId, chats);
+    }
+    catch (err) {
+        // 捕获文件读写等异常，统一通过错误发送器返回给客户端
+        sendError(err instanceof Error ? err.message : String(err));
+    }
+}