lightclawbot 1.1.2 → 1.2.0-beta.1

package/dist/src/socket/handlers.js

@@ -2,30 +2,47 @@
  * LightClaw — Socket.IO 事件处理器
  *
  * 将 socket 事件监听（message:private、history:request、sessions:request）
- * 从 gateway 主逻辑中解耦。
+ * 从 gateway 主逻辑中解耦，使 gateway.ts 只负责连接管理，本模块专注事件处理。
  *
- * 所有出站 socket.emit 通过 ReliableEmitter 实现 ACK 确认 + 自动重试。
+ * 事件处理流程：
+ *   1. message:private  — 接收用户私信，过滤无效消息后入队等待 AI 处理
+ *   2. history:request  — 接收历史消息拉取请求，查询本地存储后返回
+ *   3. sessions:request — 接收会话列表请求，返回所有已存在的会话
+ *
+ * 所有出站 socket.emit 通过 ReliableEmitter 实现 ACK 确认 + 自动重试，
+ * 保证消息在网络抖动时不丢失。
  */
-import { CHANNEL_KEY, EVENT_MESSAGE_PRIVATE, EVENT_HISTORY_REQUEST, EVENT_HISTORY_RESPONSE, EVENT_SESSIONS_REQUEST, EVENT_SESSIONS_RESPONSE, DEFAULT_HISTORY_LIMIT, } from "../config.js";
-import { isDuplicate, debounceHistoryRequest, generateMsgId } from "../dedup.js";
-import { getAssistantRuntime } from "../runtime.js";
-import { readSessionHistoryWithCron, listSessions } from "../history/index.js";
+import { CHANNEL_KEY, EVENT_MESSAGE_PRIVATE, EVENT_HISTORY_REQUEST, EVENT_HISTORY_RESPONSE, DEFAULT_HISTORY_LIMIT, DEFAULT_AGENT_ID, } from '../config.js';
+import { isDuplicate, debounceHistoryRequest, generateMsgId } from '../dedup.js';
+import { getLightclawRuntime } from '../runtime.js';
+import { readSessionHistoryWithCron } from '../history/index.js';
 /**
- * 绑定所有 Socket.IO 事件监听器
+ * 绑定所有 Socket.IO 事件监听器到指定 socket 实例。
+ *
+ * 该函数在 gateway 建立连接后调用一次，后续事件由各监听器自动处理。
+ * 函数本身无副作用，不持有状态，所有状态通过 deps 注入。
+ *
+ * @param socket - 已连接的 Socket.IO 客户端实例
+ * @param deps   - 处理事件所需的外部依赖（账户信息、队列、日志等）
  */
 export function bindSocketHandlers(socket, deps) {
-    const { account, botClientId, log, enqueueMessage, onEvent, reliableEmitter } = deps;
-    // ---- 接收用户消息 ----
+    const { account, botClientId, log, handleMessage, onEvent, reliableEmitter } = deps;
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    // 事件：接收用户私信（message:private）
+    // 职责：对消息做多层过滤，将合法消息放入处理队列
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
     socket.on(EVENT_MESSAGE_PRIVATE, (data, ack) => {
+        // 立即回复 ACK，告知服务端消息已收到，避免服务端重发
         ack?.();
+        // {"msgId":"91647ae9-c123-48e4-9d80-26f2e9a91ac9","from":"100013456706","to":"lhins-jem9a0br","content":"今天天气怎么样","files":[],"timestamp":1776077511044}
         log?.info(`[${CHANNEL_KEY}] Received private message: ${JSON.stringify(data)}，botClientId:${botClientId}`);
-        // 回环防御：过滤自身发出的消息
+        // ① 回环防御：过滤 bot 自身发出的消息，防止自问自答死循环
         if (data.from === botClientId)
             return;
-        // 跳过控制消息（typing / stream 信号），只处理真实用户消息
-        if (data.kind && data.kind !== "text")
+        // ② 跳过控制消息（如 typing 状态、stream 信号等），只处理 kind=text 的真实用户消息
+        if (data.kind && data.kind !== 'text')
             return;
-        // 无内容跳过
+        // ③ 内容校验：消息既无文字内容也无附件文件时，直接丢弃
         const hasContent = data.content?.trim();
         const hasFiles = data.files && data.files.length > 0;
         if (!hasContent && !hasFiles)
@@ -33,19 +50,25 @@ export function bindSocketHandlers(socket, deps) {
         // 去重
         if (isDuplicate(data.msgId))
             return;
-        // 通知框架收到入站事件（更新 lastEventAt，防止 stale-socket 误判）
+        // 通知框架收到入站事件，更新 lastEventAt 时间戳，防止 stale-socket 检测误判断线
         onEvent?.();
-        log?.info(`[${CHANNEL_KEY}] Message from ${data.from}: "${(data.content || "").slice(0, 60)}" files=${data.files?.length ?? 0}`);
-        enqueueMessage({
+        log?.info(`[${CHANNEL_KEY}] Message from Agent: ${data.agentId}, ${data.from}: "${(data.content || '').slice(0, 60)}" files=${data.files?.length ?? 0}`);
+        // /stop 及自然语言 abort 不做旁路，统一交给 openclaw fast-abort。
+        handleMessage({
             senderId: data.from,
-            text: data.content || "",
+            text: data.content || '',
             messageId: data.msgId,
             files: data.files ?? [],
             timestamp: data.timestamp,
+            agentId: data.agentId, // 透传前端指定的 agentId
         });
     });
-    // ---- 历史消息请求 ----
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    // 事件：历史消息请求（history:request）
+    // 职责：根据用户 ID 解析 sessionKey，从本地存储读取历史消息后返回给客户端
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
     socket.on(EVENT_HISTORY_REQUEST, (data, ack) => {
+        // 立即回复 ACK，告知服务端请求已收到
         ack?.();
         if (!data?.from) {
             log?.warn(`[${CHANNEL_KEY}] History request missing userId, ignoring`);
@@ -64,67 +87,67 @@ export function bindSocketHandlers(socket, deps) {
             // 通知框架收到入站事件（更新 lastEventAt，防止 stale-socket 误判）
             onEvent?.();
             try {
-                const pluginRuntime = getAssistantRuntime();
+                // 获取插件运行时，读取最新配置（支持热更新，不缓存旧配置）
+                const pluginRuntime = getLightclawRuntime();
                 const currentCfg = pluginRuntime.config.loadConfig();
-                const route = pluginRuntime.channel.routing.resolveAgentRoute({
+                // 通过路由解析器获取该用户对应的 Agent 路由信息
+                // resolveAgentRoute 会综合账户配置、用户 ID、渠道等信息计算出 sessionKey
+                const baseRoute = pluginRuntime.channel.routing.resolveAgentRoute({
                     cfg: currentCfg,
                     channel: CHANNEL_KEY,
                     accountId: account.accountId,
-                    peer: { kind: "direct", id: data.from },
+                    peer: { kind: 'direct', id: data.from },
+                });
+                // agentId 合法性校验：防止前端传入任意 agentId 访问其他 Agent 的数据
+                const currentCfgTyped = currentCfg;
+                const validAgentIds = currentCfgTyped.agents?.list?.map((a) => a.id) ?? [DEFAULT_AGENT_ID];
+                log?.info(`[${CHANNEL_KEY}], 当前合法的agentId为：${validAgentIds}`);
+                const resolvedAgentId = data.agentId && validAgentIds.includes(data.agentId) ? data.agentId : DEFAULT_AGENT_ID;
+                log?.info(`[${CHANNEL_KEY}], 当前agentId为：${resolvedAgentId}`);
+                // 始终用 effectiveAgentId 调用 buildAgentSessionKey 生成 sessionKey：
+                // - 前端传了合法 agentId → 用它；否则降级到 baseRoute.agentId（框架路由解析出的默认值）
+                const sessionKey = pluginRuntime.channel.routing.buildAgentSessionKey({
+                    agentId: resolvedAgentId,
+                    channel: CHANNEL_KEY,
+                    accountId: baseRoute.accountId,
+                    peer: { kind: 'direct', id: data.from },
+                    dmScope: 'per-channel-peer',
                 });
-                const sessionKey = route?.sessionKey ?? `${CHANNEL_KEY}:dm:${data.from}`;
+                log?.info(`[${CHANNEL_KEY}] userId=${data.from}，当前的sessionKey=${sessionKey}`);
+                // 从本地持久化存储中读取该 session 的历史消息
+                // includeCron: true 表示同时读取定时任务产生的消息（如每日推送）
                 const messages = readSessionHistoryWithCron(sessionKey, {
                     limit: data.limit ?? DEFAULT_HISTORY_LIMIT,
                     chatOnly: data.chatOnly ?? true,
                     includeCron: true,
+                    agentId: resolvedAgentId,
                 });
                 log?.info(`[${CHANNEL_KEY}] History request: userId=${data.from} sessionKey=${sessionKey} found=${messages.length}`);
+                // 过滤掉内容为空的消息（既无文字也无附件），避免客户端渲染空气泡
                 const historyMsgId = generateMsgId();
                 reliableEmitter.emitWithAck(EVENT_HISTORY_RESPONSE, {
                     msgId: historyMsgId,
                     from: botClientId,
                     to: data.from,
                     sessionKey,
-                    messages: messages.filter(msg => !!msg.content.trim() || (msg.files && msg.files.length > 0)),
+                    messages: messages.filter((msg) => !!msg.content.trim() || (msg.files && msg.files.length > 0)),
+                    agentId: resolvedAgentId,
                 }, historyMsgId);
             }
             catch (err) {
+                // 查询失败时返回空列表 + 错误信息，客户端可据此展示错误提示
                 log?.error(`[${CHANNEL_KEY}] History request error: ${err}`);
                 const errorMsgId = generateMsgId();
                 reliableEmitter.emitWithAck(EVENT_HISTORY_RESPONSE, {
                     msgId: errorMsgId,
                     from: botClientId,
                     to: data.from,
-                    sessionKey: "",
+                    sessionKey: '',
                     messages: [],
                     error: err instanceof Error ? err.message : String(err),
+                    agentId: data.agentId || DEFAULT_AGENT_ID,
                 }, errorMsgId);
             }
         });
     });
-    // ---- 会话列表请求 ----
-    socket.on(EVENT_SESSIONS_REQUEST, (data) => {
-        // 通知框架收到入站事件（更新 lastEventAt，防止 stale-socket 误判）
-        onEvent?.();
-        try {
-            const sessions = listSessions();
-            const sessionsMsgId = generateMsgId();
-            reliableEmitter.emitWithAck(EVENT_SESSIONS_RESPONSE, {
-                requestId: data.requestId,
-                sessions,
-                msgId: sessionsMsgId,
-            }, sessionsMsgId);
-        }
-        catch (err) {
-            log?.error(`[${CHANNEL_KEY}] Sessions list error: ${err}`);
-            const sessionsErrMsgId = generateMsgId();
-            reliableEmitter.emitWithAck(EVENT_SESSIONS_RESPONSE, {
-                requestId: data.requestId,
-                sessions: [],
-                error: err instanceof Error ? err.message : String(err),
-                msgId: sessionsErrMsgId,
-            }, sessionsErrMsgId);
-        }
-    });
 }
-//# sourceMappingURL=handlers.js.map

package/dist/src/socket/index.js

@@ -6,4 +6,3 @@
 export { bindSocketHandlers } from "./handlers.js";
 export { registerSocket, unregisterSocket, getSocket, hasEntry, getBotClientId, getReliableEmitter, bufferMessage, flushPendingMessages, getPendingCount, } from "./registry.js";
 export { ReliableEmitter } from "./reliable-emitter.js";
-//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,385 @@
+/**
+ * LightClaw — 原生 WebSocket 封装层（NativeSocketClient）
+ *
+ * 功能：
+ *   1. 基于原生 WebSocket 实现连接管理
+ *   2. 基于事件名的消息分发（on / emit）
+ *   3. 指数退避自动重连
+ *   4. timeout().emit() ACK 链式调用
+ *
+ * 消息协议（与服务端约定）：
+ *   上行：{ event: string; data?: unknown; msgId?: string }
+ *   下行：{ event: string; data?: unknown }
+ *   ACK ：{ event: 'message:ack'; data: { msgId: string; relatedMsgId: string; ... } }
+ */
+import WebSocket from 'ws';
+import { SOCKET_RECONNECTION_DELAY, SOCKET_RECONNECTION_DELAY_MAX, SOCKET_RECONNECTION_ATTEMPTS } from '../config.js';
+// ============================================================
+// NativeSocketClient 实现
+// ============================================================
+/**
+ * 基于 ws 库的 WebSocket 封装，接口与原 socket.io-client 保持兼容。
+ *
+ * 使用方式：
+ * ```ts
+ * // 认证信息请直接拼接到 URL 上（例如 ?ticket=xxx），本类不再处理 auth headers
+ * const socket = new NativeSocketClient(`${WS_URL}?ticket=xxx`, { path: '/claw-socket' });
+ * socket.on('connect', () => { ... });
+ * socket.on('message:private', (data) => { ... });
+ * socket.timeout(5000).emit('message:private', data, (err) => { ... });
+ * socket.disconnect();
+ * ```
+ */
+export class NativeSocketClient {
+    url;
+    options;
+    // ----------------------------------------------------------
+    // 连接状态
+    // ----------------------------------------------------------
+    _connected = false;
+    _id = undefined;
+    _ws = null;
+    /** 是否为主动断开（主动断开时不触发自动重连） */
+    _manualDisconnect = false;
+    // ----------------------------------------------------------
+    // 重连状态
+    // ----------------------------------------------------------
+    _reconnectAttempts = 0;
+    _reconnectTimer = null;
+    // ----------------------------------------------------------
+    // 事件监听器映射表
+    // ----------------------------------------------------------
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    _listeners = new Map();
+    // ----------------------------------------------------------
+    // ACK 挂起队列
+    // ----------------------------------------------------------
+    _pendingAcks = new Map();
+    _ackCounter = 0;
+    // ----------------------------------------------------------
+    // 构造函数
+    // ----------------------------------------------------------
+    /** 日志对象（可选）。调用方通常传入 GatewayContext.log，用于打印连接/重连/错误等诊断信息。 */
+    log;
+    /** 日志前缀，便于在多实例场景下区分日志来源。 */
+    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();
+    }
+    // ----------------------------------------------------------
+    // NativeSocket 接口实现
+    // ----------------------------------------------------------
+    get connected() {
+        return this._connected;
+    }
+    get id() {
+        return this._id;
+    }
+    on(event, listener) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        let listeners = this._listeners.get(event);
+        if (!listeners) {
+            listeners = [];
+            this._listeners.set(event, listeners);
+        }
+        listeners.push(listener);
+        return this;
+    }
+    off(event, listener) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const listeners = this._listeners.get(event);
+        if (!listeners)
+            return this;
+        const idx = listeners.indexOf(listener);
+        if (idx !== -1)
+            listeners.splice(idx, 1);
+        if (listeners.length === 0)
+            this._listeners.delete(event);
+        return this;
+    }
+    removeAllListeners() {
+        this._listeners.clear();
+        return this;
+    }
+    emit(event, ...args) {
+        if (!this._connected || !this._ws)
+            return this;
+        const data = args.length === 1 ? args[0] : args;
+        try {
+            this._ws.send(JSON.stringify({ event, data }));
+        }
+        catch {
+            // 发送失败时静默处理，连接断开会由 onclose 触发后续流程
+        }
+        return this;
+    }
+    timeout(ms) {
+        return {
+            emit: (event, data, callback, msgId) => {
+                // 未连接时立即回调错误
+                if (!this._connected || !this._ws) {
+                    callback(new Error('not connected'));
+                    return;
+                }
+                // ACK 匹配链路说明：
+                //   1. 调用方（ReliableEmitter.doEmit）在 data 中注入：
+                //      - msgId：业务层消息 ID，同一条消息所有重试相同
+                //      - idempotencyKey：emitId，每次 emitWithAck 调用唯一，仅用于服务端去重
+                //   2. 服务端 ACK 通过 relatedMsgId 回传上行消息的 msgId
+                //   3. 此处以 data.msgId 作为 pendingKey 注册到 _pendingAcks
+                //   4. _handleMessage 用 ACK 的 relatedMsgId（= msgId）查找 _pendingAcks，命中回调
+                // 因此 pendingKey 必须与上行 data.msgId 保持一致，而非 idempotencyKey。
+                const dataObj = data;
+                const pendingKey = dataObj?.msgId ??
+                    `_ack_${Date.now().toString(36)}_${(this._ackCounter++).toString(36)}`;
+                // 同一条消息重试时 msgId 相同，新的回调覆盖旧的（旧定时器需先清理，防止泄漏）
+                const existing = this._pendingAcks.get(pendingKey);
+                if (existing) {
+                    clearTimeout(existing.timer);
+                }
+                // 启动超时计时器
+                const timer = setTimeout(() => {
+                    this._pendingAcks.delete(pendingKey);
+                    callback(new Error('timeout'));
+                }, ms);
+                // 注册 ACK 挂起记录，以 pendingKey（= msgId）为 key
+                this._pendingAcks.set(pendingKey, { timer, callback });
+                // 发送消息（data.msgId 供服务端回传 relatedMsgId，data.idempotencyKey 供服务端去重）
+                try {
+                    this._ws.send(JSON.stringify({ event, data }));
+                }
+                catch {
+                    // 发送失败时立即清理并回调错误
+                    clearTimeout(timer);
+                    this._pendingAcks.delete(pendingKey);
+                    callback(new Error('send failed'));
+                }
+            },
+        };
+    }
+    disconnect() {
+        this.log?.info(`${this.logPrefix} disconnect() called (wasConnected=${this._connected})`);
+        this._manualDisconnect = true;
+        this._clearReconnectTimer();
+        const wasConnected = this._connected;
+        this._closeWs();
+        // 主动断开时也需要通知上层，与 socket.io 行为保持一致
+        if (wasConnected) {
+            this._dispatch('disconnect');
+        }
+        return this;
+    }
+    connect() {
+        // 手动触发重连（用于服务端主动断开后的手动重连场景）
+        // 若当前已有活跃连接（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'}`);
+            return this;
+        }
+        this.log?.info(`${this.logPrefix} connect() called, manually reconnecting`);
+        this._manualDisconnect = false;
+        this._reconnectAttempts = 0;
+        this._clearReconnectTimer();
+        this._connect();
+        return this;
+    }
+    // ----------------------------------------------------------
+    // 内部：建立 WebSocket 连接
+    // ----------------------------------------------------------
+    _connect() {
+        // 构建完整 URL（仅拼接 path，认证通过 URL query 参数完成，无需 headers）
+        const fullUrl = this._buildUrl();
+        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._dispatch('connect');
+            };
+            ws.onmessage = (event) => {
+                this._handleMessage(event.data);
+            };
+            ws.onclose = (event) => {
+                const wasConnected = this._connected;
+                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})`);
+                // 立即 flush 所有挂起的 ACK，以断开错误立即回调，而非等待超时
+                this._flushPendingAcks(new Error('disconnect'));
+                if (wasConnected) {
+                    this._dispatch('disconnect');
+                }
+                // 非主动断开时触发自动重连
+                if (!this._manualDisconnect) {
+                    this._scheduleReconnect();
+                }
+            };
+            ws.onerror = (event) => {
+                const detail = event.error?.stack || event.message || 'unknown';
+                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._dispatch('connect_error', err instanceof Error ? err : new Error(String(err)));
+            if (!this._manualDisconnect) {
+                this._scheduleReconnect();
+            }
+        }
+    }
+    // ----------------------------------------------------------
+    // 内部：消息处理
+    // ----------------------------------------------------------
+    _handleMessage(raw) {
+        let msg;
+        try {
+            msg = JSON.parse(raw);
+        }
+        catch {
+            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`);
+            return;
+        }
+        // 处理 ACK 回包
+        if (msg.event === 'message:ack') {
+            this.log?.info(`${this.logPrefix} Received message ACK ${JSON.stringify(msg)}`);
+            // 服务端通过 relatedMsgId 回传上行消息的 msgId，用于匹配挂起的 ACK 记录
+            // pendingKey = data.msgId（注册时），relatedMsgId = msgId（服务端回传），两者一致
+            const ackData = msg.data;
+            const relatedMsgId = ackData?.relatedMsgId;
+            if (relatedMsgId) {
+                const pending = this._pendingAcks.get(relatedMsgId);
+                if (pending) {
+                    clearTimeout(pending.timer);
+                    this._pendingAcks.delete(relatedMsgId);
+                    pending.callback(null);
+                }
+                else {
+                    this.log?.debug?.(`${this.logPrefix} Received ACK for unknown relatedMsgId=${relatedMsgId}`);
+                }
+            }
+            return;
+        }
+        // 处理服务端握手消息（获取 socket id）
+        if (msg.event === '__handshake__') {
+            const handshakeData = msg.data;
+            if (handshakeData?.id) {
+                this._id = handshakeData.id;
+                this.log?.info(`${this.logPrefix} Handshake received, socket id=${this._id}`);
+            }
+            return;
+        }
+        // 分发业务事件
+        this.log?.debug?.(`${this.logPrefix} Dispatch event: ${msg.event}`);
+        this._dispatch(msg.event, msg.data);
+    }
+    // ----------------------------------------------------------
+    // 内部：事件分发
+    // ----------------------------------------------------------
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    _dispatch(event, ...args) {
+        const listeners = this._listeners.get(event);
+        if (!listeners)
+            return;
+        // 遍历前浅拷贝，防止 listener 内部调用 off() 修改原数组导致遍历异常
+        for (const listener of [...listeners]) {
+            try {
+                listener(...args);
+            }
+            catch {
+                // 单个监听器异常不影响其他监听器
+            }
+        }
+    }
+    // ----------------------------------------------------------
+    // 内部：自动重连
+    // ----------------------------------------------------------
+    _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._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._reconnectTimer = setTimeout(() => {
+            this._reconnectTimer = null;
+            if (!this._manualDisconnect) {
+                this._connect();
+            }
+        }, delay);
+    }
+    _clearReconnectTimer() {
+        if (this._reconnectTimer !== null) {
+            clearTimeout(this._reconnectTimer);
+            this._reconnectTimer = null;
+        }
+    }
+    /** 立即清空所有挂起的 ACK，以指定错误回调 */
+    _flushPendingAcks(err) {
+        for (const [, pending] of this._pendingAcks) {
+            clearTimeout(pending.timer);
+            pending.callback(err);
+        }
+        this._pendingAcks.clear();
+    }
+    // ----------------------------------------------------------
+    // 内部：关闭 WebSocket
+    // ----------------------------------------------------------
+    _closeWs() {
+        if (this._ws) {
+            // 移除所有回调，防止 onclose 触发重连
+            this._ws.onopen = null;
+            this._ws.onmessage = null;
+            this._ws.onclose = null;
+            this._ws.onerror = null;
+            try {
+                this._ws.close();
+            }
+            catch {
+                // 忽略关闭时的异常
+            }
+            this._ws = null;
+        }
+        this._connected = false;
+        this._id = undefined;
+        // onclose 被置 null 后不会自动触发，需手动 flush 挂起的 ACK
+        this._flushPendingAcks(new Error('disconnect'));
+    }
+    // ----------------------------------------------------------
+    // 内部：构建完整 URL
+    // ----------------------------------------------------------
+    _buildUrl() {
+        let base = this.url;
+        // 拼接 path（如 /claw-socket）
+        if (this.options.path) {
+            // 确保 base 末尾无斜杠，path 开头有斜杠
+            base = base.replace(/\/$/, '') + this.options.path;
+        }
+        return base;
+    }
+}

package/dist/src/socket/registry.js

@@ -122,4 +122,3 @@ export function flushPendingMessages(accountId, log) {
 export function getPendingCount(accountId) {
     return registry.get(accountId)?.pendingMessages.length ?? 0;
 }
-//# sourceMappingURL=registry.js.map