lightclawbot 1.1.2 → 1.2.0-beta.1

package/dist/src/gateway.js

@@ -1,144 +1,155 @@
 /**
- * LightClaw — Socket.IO Gateway
+ * LightClaw — WebSocket Gateway
  *
  * 连接编排层：
  * 1. 管理 Socket.IO 连接生命周期（连接/断开/重连/防重入）
- * 2. 维护消息队列，串行处理入站消息
+ * 2. 分发入站消息（fire-and-forget），并发/abort 由 openclaw 自己处理
  * 3. 提供 socket emit 抽象供子模块使用
  *
- * 消息处理逻辑 → inbound.ts
- * 事件监听绑定 → socket-handlers.ts
- * 去重/节流/ID → dedup.ts
- * 媒体文件处理 → media.ts
+ * 子模块分工：
+ *   消息处理逻辑 → inbound.ts
+ *   事件监听绑定 → socket-handlers.ts
+ *   去重/节流/ID → dedup.ts
+ *   媒体文件处理 → media.ts
  */
-import { io } from "socket.io-client";
-import { CHANNEL_KEY, WS_URL, API_BASE_URL, SOCKET_PATH, SOCKET_RECONNECTION_DELAY, SOCKET_RECONNECTION_DELAY_MAX, SOCKET_RECONNECTION_ATTEMPTS, API_PATH_USER_CURRENT, EVENT_MESSAGE_PRIVATE, MESSAGE_QUEUE_SIZE, MESSAGE_QUEUE_WARN_THRESHOLD, QUEUE_POLL_INTERVAL, HEALTH_HEARTBEAT_INTERVAL, buildAuthHeaders, buildMultiAuthHeaders, setApiKeyMap, } from "./config.js";
-import { generateMsgId } from "./dedup.js";
-import { createInboundHandler } from "./inbound.js";
-import { bindSocketHandlers, registerSocket, unregisterSocket, flushPendingMessages } from "./socket/index.js";
-import { ReliableEmitter } from "./socket/reliable-emitter.js";
-import { formatCosUrls } from "./format-urls.js";
+import { NativeSocketClient } from './socket/native-socket.js';
+import { CHANNEL_KEY, WS_URL, API_BASE_URL, SOCKET_PATH, API_PATH_USER_CURRENT, EVENT_MESSAGE_PRIVATE, HEALTH_HEARTBEAT_INTERVAL, setApiKeyMap, } from './config.js';
+import { generateMsgId } from './dedup.js';
+import { createInboundHandler } from './inbound.js';
+import { bindSocketHandlers, registerSocket, unregisterSocket, flushPendingMessages } from './socket/index.js';
+import { ReliableEmitter } from './socket/reliable-emitter.js';
+import { buildAuthHeaders } from './utils/index.js';
 // ============================================================
 // Gateway 实例追踪（防止同一 accountId 创建多个连接）
 // ============================================================
-/** accountId → cleanup function */
+/**
+ * 全局 Gateway 实例注册表。
+ * key   = accountId
+ * value = cleanup 函数（销毁 socket、定时器、可靠发送器等所有资源）
+ *
+ * 在 startGateway 入口处检查此 Map，若已存在则先销毁旧实例，
+ * 避免同一账号同时持有多个 WebSocket 连接。
+ */
 const activeGateways = new Map();
 /**
- * 对每个 apiKey 调 /user/current，一次性获取 botClientId 和 uin→apiKey 映射。
+ * 通过 /user/current 接口解析 botClientId。
  *
- * 所有 key 共享同一个 botId（来自 data.client.extra），
- * 但每个 key 对应不同的 uin（= data.id）。
+ * 新配置格式下，accountId 即为 uin，apiKey 与 uin 一一对应，
+ * 无需并发请求多个 key，只需用当前账户的 apiKey 请求一次即可获取 botClientId。
  *
- * 映射表大小 = apiKeys 数量（静态、固定），不会随消息增多而增长。
+ * @param apiKey - 当前账户的 apiKey
+ * @param log    - 可选的日志对象
+ * @returns      - Bot 的 clientId
+ * @throws       - 若无法解析出 botClientId，则抛出错误
  */
-async function resolveApiKeyIdentities(allApiKeys, log) {
+async function resolveBotClientId(apiKey, log) {
     const url = `${API_BASE_URL}${API_PATH_USER_CURRENT}`;
-    const apiKeyMap = new Map();
-    let botClientId = "";
-    // 并发请求所有 key
-    const results = await Promise.allSettled(allApiKeys.map(async (key) => {
-        const resp = await fetch(url, {
-            method: "GET",
-            headers: buildAuthHeaders(key),
-        });
-        if (!resp.ok) {
-            const body = await resp.text().catch(() => "");
-            throw new Error(`HTTP ${resp.status} ${resp.statusText}${body ? ` — ${body}` : ""}`);
-        }
-        const result = (await resp.json());
-        if (result.code !== 0) {
-            throw new Error(`code=${result.code}, message=${result.message ?? "unknown"}`);
-        }
-        return { key, result };
-    }));
-    // 按原始顺序处理结果
-    for (let i = 0; i < results.length; i++) {
-        const key = allApiKeys[i];
-        const settled = results[i];
-        if (settled.status === "rejected") {
-            log?.warn(`[${CHANNEL_KEY}] Failed to resolve uin for apiKey ***${key.slice(-4)}: ${settled.reason}`);
-            continue;
-        }
-        const { result } = settled.value;
-        // 提取 uin
-        const uin = result.data?.id;
-        if (!uin) {
-            log?.warn(`[${CHANNEL_KEY}] Missing data.id for apiKey ***${key.slice(-4)}`);
-            continue;
-        }
-        // 提取 botId（只需从第一个成功的 key 中获取一次）
-        if (!botClientId) {
-            const extra = result.data?.client?.extra;
-            if (!extra) {
-                log?.warn(`[${CHANNEL_KEY}] Missing data.client.extra for apiKey ***${key.slice(-4)}`);
-                continue;
-            }
-            let parsed;
-            try {
-                parsed = JSON.parse(extra);
-            }
-            catch {
-                log?.warn(`[${CHANNEL_KEY}] data.client.extra is not valid JSON for apiKey ***${key.slice(-4)}: ${extra}`);
-                continue;
-            }
-            if (!parsed.botId) {
-                log?.warn(`[${CHANNEL_KEY}] Missing botId in data.client.extra for apiKey ***${key.slice(-4)}: ${extra}`);
-                continue;
-            }
-            botClientId = parsed.botId;
-        }
-        // uin 和 botClientId 都成功获取后，才加入映射
-        apiKeyMap.set(uin, key);
-        log?.info(`[${CHANNEL_KEY}] Mapped uin=${uin} → apiKey=***${key.slice(-4)}`);
+    const resp = await fetch(url, {
+        method: 'POST',
+        headers: buildAuthHeaders(apiKey),
+    });
+    if (!resp.ok) {
+        const body = await resp.text().catch(() => '');
+        throw new Error(`[${CHANNEL_KEY}] ${API_PATH_USER_CURRENT} HTTP ${resp.status} ${resp.statusText}${body ? ` — ${body}` : ''}`);
+    }
+    const result = (await resp.json());
+    if (result.code !== 0) {
+        throw new Error(`[${CHANNEL_KEY}] ${API_PATH_USER_CURRENT} code=${result.code}, message=${result.message ?? 'unknown'}`);
+    }
+    const extra = result.data?.client?.extra;
+    if (!extra) {
+        throw new Error(`[${CHANNEL_KEY}] Missing data.client.extra in ${API_PATH_USER_CURRENT} response`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(extra);
     }
-    if (!botClientId) {
-        throw new Error(`[${CHANNEL_KEY}] Failed to resolve botClientId from any apiKey`);
+    catch {
+        throw new Error(`[${CHANNEL_KEY}] data.client.extra is not valid JSON: ${extra}`);
     }
-    return { botClientId, apiKeyMap };
+    if (!parsed.botId) {
+        throw new Error(`[${CHANNEL_KEY}] Missing botId in data.client.extra: ${extra}`);
+    }
+    log?.info(`[${CHANNEL_KEY}] Resolved botClientId: ${parsed.botId}`);
+    return {
+        botClientId: parsed.botId,
+        ticket: result?.data?.ticket || '',
+    };
 }
 // ============================================================
 // 核心：启动 Gateway
 // ============================================================
+/**
+ * 启动并维持一个 WebSocket Gateway 实例。
+ *
+ * 整体流程：
+ * 1. 防重入检查：若同一 accountId 已有活跃 gateway，先销毁旧实例
+ * 2. 调用 /user/current 解析 botClientId 和 uin→apiKey 映射
+ * 3. 创建 ReliableEmitter（可靠发送器）和 SocketEmitter 抽象
+ * 4. 创建入站消息处理器和串行消息队列
+ * 5. 建立 WebSocket 连接，绑定生命周期事件和业务事件
+ * 6. 返回一个永不 resolve 的 Promise，直到 abortSignal 触发才退出
+ *    （框架约定：Promise resolve = gateway 已退出，会触发 auto-restart）
+ *
+ * @param ctx - Gateway 上下文，包含账户配置、abort 信号和生命周期回调
+ */
 export async function startGateway(ctx) {
     const { account, abortSignal, onReady, onDisconnect, onEvent, log } = ctx;
-    if (!account.allApiKeys.length) {
-        throw new Error(`[${CHANNEL_KEY}] Missing apiKeys in config`);
+    // 判断是否存在有效的apikey
+    if (!account.apiKey) {
+        log?.error(`[${CHANNEL_KEY}:${account.accountId}] apiKey is not exist`);
+        throw new Error(`[${CHANNEL_KEY}] Missing apiKey in config`);
     }
-    // 防重入：如果同一 accountId 已有活跃 gateway，先销毁
+    // 判断 accountId 在缓存中是否存在，避免同一账号同时持有多个 WebSocket 连接
+    // 防重入：如果同一 accountId 已有活跃 gateway，先销毁旧实例再创建新实例
     const existingCleanup = activeGateways.get(account.accountId);
     if (existingCleanup) {
-        log?.warn(`[${CHANNEL_KEY}] Destroying existing gateway for account ${account.accountId} before creating new one`);
+        log?.warn(`[${CHANNEL_KEY}:${account.accountId}] Destroying existing gateway for account ${account.accountId} before creating new one`);
         existingCleanup();
     }
-    // 通过 HTTP 接口获取 Bot 身份 & uin→apiKey 映射（一次性完成）
-    const { allApiKeys } = account;
-    log?.info(`[${CHANNEL_KEY}] Resolving identities for ${allApiKeys.length} apiKey(s)...`);
-    const { botClientId, apiKeyMap } = await resolveApiKeyIdentities(allApiKeys, log);
-    log?.info(`[${CHANNEL_KEY}] Bot clientId: ${botClientId}, apiKey map: ${apiKeyMap.size} entries`);
+    // 通过 HTTP 接口获取 Bot 的 clientId（botClientId）
+    // 新配置格式：accountId 即为 uin，apiKey 与 uin 一一对应，直接构建映射表
+    log?.info(`[${CHANNEL_KEY}: ${account.accountId}] Resolving botClientId for account ${account.accountId}...`);
+    const { botClientId, ticket } = await resolveBotClientId(account.apiKey, log);
+    // 构建 uin→apiKey 映射表（新格式下每个 account 只有一条记录）
+    const apiKeyMap = new Map([[account.accountId, account.apiKey]]);
+    log?.info(`[${CHANNEL_KEY}] Bot clientId: ${botClientId}, uin=${account.accountId} → apiKey=***${account.apiKey.slice(-4)}`);
+    // 将映射表写入全局 config 模块，供 inbound 处理时按 uin 查找对应 apiKey
     setApiKeyMap(apiKeyMap, account.apiKey);
+    /** Gateway 是否已被 abort（用于终止消息处理循环） */
     let isAborted = false;
+    /** 当前活跃的 WebSocket 实例（断线时为 null） */
     let currentSocket = null;
+    /** health-monitor 心跳定时器（连接时启动，断线时清除） */
     let healthHeartbeatTimer = null;
     // ---- 可靠发送器（所有出站 emit 都通过此实例） ----
+    // ReliableEmitter 负责：断线时缓冲消息、重连后 flush、ACK 超时重试
     const reliableEmitter = new ReliableEmitter(() => currentSocket, log);
-    // ---- Socket.IO 发送抽象 ----
+    // ---- WebSocket 发送抽象 ----
+    /**
+     * 底层 emit：将 PrivateMessageData 通过 ReliableEmitter 发送给客户端。
+     * - 统一对 content 字段执行 formatCosUrls（将内部 COS 路径转换为公网 URL）
+     * - 所有消息都走可靠发送队列，入队即视为"发送成功"，实际 ACK 由 ReliableEmitter 保证
+     */
     const emit = (data) => {
-        // 统一拦截：所有出站消息的 content 都过一遍 formatCosUrls
-        const outgoing = data.content
-            ? { ...data, content: formatCosUrls(data.content) }
-            : data;
-        log?.info(`[${CHANNEL_KEY}] emit: ${JSON.stringify(outgoing)}`);
-        // 所有消息都走可靠发送（入队即视为"发送成功"）
-        reliableEmitter.emitWithAck(EVENT_MESSAGE_PRIVATE, outgoing, outgoing.msgId)
-            .then(ok => {
-            if (!ok) {
-                log?.error(`[${CHANNEL_KEY}] Message delivery failed after retries: msgId=${outgoing.msgId}`);
-            }
+        // 完整发送日志由 ReliableEmitter 打印（含 idempotencyKey）
+        reliableEmitter.emitWithAck(EVENT_MESSAGE_PRIVATE, data, data.msgId).then((ok) => {
+            if (!ok)
+                log?.error(`[${CHANNEL_KEY}] Message delivery failed after retries: msgId=${data.msgId}`);
         });
         return true;
     };
-    const sendReply = (targetId, text, replyToMsgId) => {
-        log?.info(`[${CHANNEL_KEY}] sendReply: ${text} to ${targetId} (replyTo: ${replyToMsgId || "none"})`);
+    /**
+     * 发送文本回复消息。
+     * 自动生成 msgId 和 timestamp，封装为 PrivateMessageData 后调用 emit。
+     *
+     * @param targetId     - 接收方用户 ID
+     * @param text         - 回复文本内容
+     * @param replyToMsgId - 可选，回复对应的原始消息 ID（用于前端展示引用关系）
+     * @param agentId      - 可选，目标 Agent ID
+     */
+    const sendReply = (targetId, text, replyToMsgId, agentId) => {
+        log?.info(`[${CHANNEL_KEY}] sendReply: ${text} to ${targetId} (replyTo: ${replyToMsgId || 'none'})`);
         return emit({
             msgId: generateMsgId(),
             from: botClientId,
@@ -146,9 +157,20 @@ export async function startGateway(ctx) {
             content: text,
             timestamp: Date.now(),
             replyToMsgId,
+            agentId,
         });
     };
-    const sendFiles = (targetId, text, files, replyToMsgId) => {
+    /**
+     * 发送带文件附件的消息。
+     * 自动生成 msgId 和 timestamp，封装为 PrivateMessageData 后调用 emit。
+     *
+     * @param targetId     - 接收方用户 ID
+     * @param text         - 消息文本（可为空字符串）
+     * @param files        - 文件附件列表（{name, mimeType, bytes} 格式）
+     * @param replyToMsgId - 可选，回复对应的原始消息 ID
+     * @param agentId      - 可选，目标 Agent ID
+     */
+    const sendFiles = (targetId, text, files, replyToMsgId, agentId) => {
         return emit({
             msgId: generateMsgId(),
             from: botClientId,
@@ -157,61 +179,55 @@ export async function startGateway(ctx) {
             timestamp: Date.now(),
             files,
             replyToMsgId,
+            agentId,
         });
     };
+    /** SocketEmitter 抽象：将 emit / sendReply / sendFiles 和 botClientId 打包传给 inbound 处理器 */
     const emitter = { emit, sendReply, sendFiles, botClientId };
     // ---- 入站消息处理器 ----
+    // createInboundHandler 返回一个异步函数，负责处理单条用户消息（文件处理、路由、AI 分发、回复）
     const handleInboundMessage = createInboundHandler(account, emitter, log);
-    // ---- 消息队列 ----
-    const messageQueue = [];
-    let messageProcessorRunning = false;
-    let queueNotify = null;
-    const enqueueMessage = (msg) => {
-        if (messageQueue.length >= MESSAGE_QUEUE_SIZE) {
-            const dropped = messageQueue.shift();
-            log?.error(`[${CHANNEL_KEY}] Queue full, dropped message from ${dropped?.senderId}`);
-        }
-        if (messageQueue.length >= MESSAGE_QUEUE_WARN_THRESHOLD) {
-            log?.warn(`[${CHANNEL_KEY}] Queue size: ${messageQueue.length}/${MESSAGE_QUEUE_SIZE}`);
-        }
-        messageQueue.push(msg);
-        // 唤醒处理器
-        queueNotify?.();
-    };
-    /** 等待队列中有新消息，或超时后返回 */
-    const waitForMessage = () => {
-        if (messageQueue.length > 0)
-            return Promise.resolve();
-        return new Promise((resolve) => {
-            const timer = setTimeout(() => { queueNotify = null; resolve(); }, QUEUE_POLL_INTERVAL);
-            queueNotify = () => { clearTimeout(timer); queueNotify = null; resolve(); };
-        });
-    };
-    const startMessageProcessor = () => {
-        if (messageProcessorRunning)
+    // ---- 消息处理（fire-and-forget） ----
+    // 不做串行队列：并发/abort 由 openclaw 的 session 写锁 + followup queue 负责。
+    // 这里仅兜底 inbound 自身未捕获的异常。
+    const handleMessage = (msg) => {
+        if (isAborted)
             return;
-        messageProcessorRunning = true;
-        const loop = async () => {
-            while (!isAborted) {
-                await waitForMessage();
-                while (messageQueue.length > 0 && !isAborted) {
-                    const msg = messageQueue.shift();
-                    try {
-                        await handleInboundMessage(msg);
-                    }
-                    catch (err) {
-                        log?.error(`[${CHANNEL_KEY}] Message handler error: ${err}`);
-                    }
+        void (async () => {
+            try {
+                await handleInboundMessage(msg);
+            }
+            catch (err) {
+                log?.error(`[${CHANNEL_KEY}] Message handler error: ${err}`);
+                try {
+                    emitter.sendReply(msg.senderId, "消息处理异常，请稍后重试。", msg.messageId);
+                    emitter.emit({
+                        msgId: generateMsgId(),
+                        from: emitter.botClientId,
+                        to: msg.senderId,
+                        content: "",
+                        timestamp: Date.now(),
+                        kind: "typing_stop",
+                        replyToMsgId: msg.messageId,
+                        agentId: msg.agentId,
+                    });
+                }
+                catch (notifyErr) {
+                    log?.error(`[${CHANNEL_KEY}] Failed to notify user about handler error: ${notifyErr}`);
                 }
             }
-            messageProcessorRunning = false;
-        };
-        loop().catch((err) => {
-            log?.error(`[${CHANNEL_KEY}] Message processor crashed: ${err}`);
-            messageProcessorRunning = false;
-        });
+        })();
     };
     // ---- 生命周期 ----
+    /**
+     * 销毁当前 Gateway 实例，释放所有资源：
+     * - 设置 isAborted 标志，终止消息处理循环
+     * - 销毁 ReliableEmitter（清空发送队列、取消重试）
+     * - 清除 health-monitor 心跳定时器
+     * - 从 socket 注册表中注销（unregisterSocket）
+     * - 从 activeGateways 中移除自身
+     * - 断开并销毁 WebSocket 连接
+     */
     const cleanup = () => {
         isAborted = true;
         reliableEmitter.destroy();
@@ -228,32 +244,46 @@ export async function startGateway(ctx) {
         }
         log?.info(`[${CHANNEL_KEY}] Gateway cleaned up`);
     };
+    // 将 cleanup 注册到全局 Map，供防重入检查和外部销毁使用
     activeGateways.set(account.accountId, cleanup);
-    // ---- Socket.IO 连接 ----
-    const validApiKeys = [...apiKeyMap.values()];
-    log?.info(`[${CHANNEL_KEY}] Connecting to ${WS_URL}`);
-    const socket = io(WS_URL, {
-        auth: buildMultiAuthHeaders(validApiKeys),
-        path: SOCKET_PATH,
-        forceNew: true,
-        reconnection: true,
-        reconnectionAttempts: SOCKET_RECONNECTION_ATTEMPTS,
-        reconnectionDelay: SOCKET_RECONNECTION_DELAY,
-        reconnectionDelayMax: SOCKET_RECONNECTION_DELAY_MAX,
-        transports: ['websocket']
+    // ---- WebSocket 连接 ----
+    // 采用 ticket 作为 query 参数进行认证，不再使用 header 方式
+    // 为兼容已有的 path 选项，仍通过 options.path 传入 /claw-socket
+    const ticketQuery = ticket ? `?ticket=${encodeURIComponent(ticket)}` : '';
+    log?.info(`[${CHANNEL_KEY}] Connecting to ${WS_URL}${SOCKET_PATH}${ticketQuery}`);
+    // 使用原生 WebSocket 封装层建立连接
+    const socket = new NativeSocketClient(WS_URL, {
+        // 认证：ticket 作为 URL query 参数，替代 Authorization header
+        path: `${SOCKET_PATH}${ticketQuery}&enableMultiLogin=false`,
+        // 注入日志对象，便于 NativeSocketClient 内部打印连接/重连/错误等诊断信息
+        log,
+        logPrefix: `[${CHANNEL_KEY}:${account.accountId}:NativeSocket]`,
     });
     currentSocket = socket;
-    socket.on("connect", () => {
-        log?.info(`[${CHANNEL_KEY}] Connected (id=${socket.id}, botClientId=${botClientId})`);
+    /**
+     * 连接成功事件处理。
+     * 触发时机：首次连接成功 或 断线重连成功。
+     * 职责：
+     * 1. 注册 socket 到全局注册表（供 outbound 模块查找）
+     * 2. 恢复 ReliableEmitter 的发送能力（resume）
+     * 3. 启动消息处理循环（首次连接时启动，重连时幂等）
+     * 4. Flush 断线期间缓冲的 outbound 消息
+     * 5. 启动 health-monitor 心跳定时器
+     * 6. 通知框架 gateway 已就绪（onReady）
+     */
+    socket.on('connect', () => {
+        log?.info(`[${CHANNEL_KEY}] Connected (accountId=${account.accountId}, id=${socket.id}, botClientId=${botClientId})`);
+        // 注册到全局 socket 注册表，供 outbound.ts 查找 socket 实例
         registerSocket(account.accountId, socket, botClientId, reliableEmitter);
+        // 恢复可靠发送器（断线时已 pause，重连后需要 resume 才能继续发送）
         reliableEmitter.resume();
-        startMessageProcessor();
-        // 重连后 flush 断线期间缓冲的 outbound 消息
+        // 重连后 flush 断线期间缓冲的 outbound 消息（主动发送场景）
         const { sent, failed } = flushPendingMessages(account.accountId, log);
         if (sent > 0 || failed > 0) {
             log?.info(`[${CHANNEL_KEY}] Flushed buffered outbound messages: sent=${sent}, failed=${failed}`);
         }
-        // 启动 health-monitor 心跳：定期刷新 lastEventAt，防止空闲期被误判 stale-socket
+        // 启动 health-monitor 心跳：定期刷新 lastEventAt，防止空闲期被框架误判销毁
+        // 重连时先清除旧定时器，再重新创建
         if (healthHeartbeatTimer)
             clearInterval(healthHeartbeatTimer);
         healthHeartbeatTimer = setInterval(() => {
@@ -264,44 +294,60 @@ export async function startGateway(ctx) {
         }, HEALTH_HEARTBEAT_INTERVAL);
         onReady?.();
     });
-    // 绑定业务事件处理器
+    // 绑定业务事件处理器（message:private 等），委托给 socket-handlers.ts
     bindSocketHandlers(socket, {
         account,
         botClientId,
         log,
-        enqueueMessage,
+        handleMessage,
         onEvent,
         reliableEmitter,
     });
-    socket.on("connect_error", (err) => {
-        log?.error(`[${CHANNEL_KEY}] connect_error: ${err.message}`);
+    /**
+     * 连接错误事件处理。
+     * 触发时机：WebSocket 握手或认证失败时。
+     * 注意：NativeSocketClient 会自动重试，此处仅记录日志。
+     */
+    socket.on('connect_error', (err) => {
+        const message = err instanceof Error ? err.message : String(err);
+        log?.error(`[${CHANNEL_KEY}] connect_error: ${message}`);
     });
-    socket.on("disconnect", (reason) => {
+    /**
+     * 断线事件处理。
+     * 触发时机：网络中断、服务端主动断开、客户端主动断开等。
+     * 职责：
+     * 1. 暂停 ReliableEmitter（断线期间消息进入缓冲队列）
+     * 2. 清除 health-monitor 心跳定时器（避免在未连接状态下假装活跃）
+     * 3. 通知框架 gateway 已断线（onDisconnect）
+     * 4. 若是服务端主动断开（io server disconnect），手动触发重连
+     *
+     * 注意：断线时不调用 unregisterSocket，保留 entry 以便 outbound 消息可以缓冲。
+     * 仅在 cleanup（gateway 彻底销毁）时才 unregisterSocket。
+     */
+    socket.on('disconnect', (reason) => {
         log?.info(`[${CHANNEL_KEY}] Disconnected: ${reason}`);
+        // 暂停可靠发送器，断线期间的消息将进入内存缓冲队列
         reliableEmitter.pause();
         // 断线时停止心跳，避免在未连接状态下假装活跃
         if (healthHeartbeatTimer) {
             clearInterval(healthHeartbeatTimer);
             healthHeartbeatTimer = null;
         }
-        // 注意：断线时不调用 unregisterSocket，保留 entry 以便 outbound 消息可以缓冲。
-        // 仅在 cleanup（gateway 彻底销毁）时才 unregisterSocket。
         onDisconnect?.();
-        if (reason === "io server disconnect") {
-            // 服务端主动断开，需要手动重连
+        if (reason === 'io server disconnect') {
+            // 服务端主动断开（如 token 过期、服务重启），需要手动触发重连
             log?.warn(`[${CHANNEL_KEY}] Server forced disconnect, attempting manual reconnect...`);
             socket.connect();
         }
     });
     // ---- 保持 Promise 挂起直到 abort ----
-    // 框架认为 startAccount 返回的 Promise resolve = gateway 已退出，会触发 auto-restart。
-    // 因此必须让 Promise 一直挂起，直到 abortSignal 触发才 resolve。
+    // 框架约定：startAccount 返回的 Promise resolve = gateway 已退出，会触发 auto-restart。
+    // 因此必须让 Promise 一直挂起，直到 abortSignal 触发（框架主动停止账号）才 resolve。
     return new Promise((resolve) => {
-        abortSignal.addEventListener("abort", () => {
+        abortSignal.addEventListener('abort', () => {
             cleanup();
             log?.info(`[${CHANNEL_KEY}] Gateway aborted`);
             resolve();
         });
     });
 }
-//# sourceMappingURL=gateway.js.map

package/dist/src/history/cron-utils.js

@@ -288,4 +288,3 @@ export function findCronSessionsByJobIds(cronJobIds, agentId) {
     })
         .sort((a, b) => (a.updatedAt ?? 0) - (b.updatedAt ?? 0)); // 时间正序
 }
-//# sourceMappingURL=cron-utils.js.map

package/dist/src/history/index.js

@@ -21,4 +21,3 @@ export { isSystemInjectedUserMessage, extractText, extractRawText, extractThinki
 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";
-//# sourceMappingURL=index.js.map

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

@@ -240,4 +240,3 @@ export function normalizeMessage(msg) {
         ...(files && files.length > 0 && { files }),
     };
 }
-//# sourceMappingURL=message-parser.js.map

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

@@ -267,6 +267,9 @@ function parseLines(lines, opts) {
             const msg = parsed?.message;
             if (!msg || typeof msg !== "object")
                 continue;
+            // 过滤 openclaw delivery-mirror 消息（镜像投递，非真实消息）
+            if (msg.model === "delivery-mirror")
+                continue;
             // 过滤传输层伪装为 user 的系统注入消息
             if (isSystemInjectedUserMessage(msg))
                 continue;
@@ -284,4 +287,3 @@ function parseLines(lines, opts) {
     // 只返回最后 limit 条
     return messages.length > limit ? messages.slice(-limit) : messages;
 }
-//# sourceMappingURL=session-reader.js.map

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

@@ -169,4 +169,3 @@ function _findArchivedTranscript(dir, jsonlFileName) {
     }
     return null;
 }
-//# sourceMappingURL=session-store.js.map

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

@@ -130,4 +130,3 @@ export function deduplicateFiles(files) {
     }
     return [...seen.values()];
 }
-//# sourceMappingURL=text-processing.js.map

package/dist/src/history/types.js

@@ -4,4 +4,3 @@
  * 集中定义历史消息相关的类型，供 history/ 模块内部和外部统一使用。
  */
 export {};
-//# sourceMappingURL=types.js.map