lightclawbot 1.2.9 → 1.2.10

package/dist/src/config.js

@@ -42,6 +42,18 @@ export const SOCKET_PATH = '/ws/agent';
 export const SOCKET_RECONNECTION_DELAY = 1000;
 export const SOCKET_RECONNECTION_DELAY_MAX = 30000;
 export const SOCKET_RECONNECTION_ATTEMPTS = Infinity;
+/** 首次重连随机抖动上限（ms），用于打散服务发布后的集中重连 */
+export const SOCKET_RECONNECTION_INITIAL_JITTER_MAX = 10_000;
+/** 后续指数退避随机抖动比例，0.5 表示在 50%~150% 区间内随机 */
+export const SOCKET_RECONNECTION_JITTER_RATIO = 0.5;
+/** WebSocket 协议级 ping 间隔（ms），需小于 ai-server 60s 在线 TTL */
+export const WS_PING_INTERVAL_MS = 20_000;
+/** WebSocket heartbeat 首次 ping 随机抖动上限（ms），用于避免重连后 ping 周期对齐 */
+export const WS_HEARTBEAT_INITIAL_JITTER_MAX = WS_PING_INTERVAL_MS;
+/** WebSocket pong 等待超时时间（ms） */
+export const WS_PONG_TIMEOUT_MS = 10_000;
+/** 连续 pong 超时次数阈值，达到后判定连接半开并主动重连 */
+export const WS_MAX_MISSED_PONG = 2;
 // ============================================================
 // HTTP Header 配置
 // ============================================================

package/dist/src/gateway.js

@@ -77,6 +77,30 @@ async function resolveBotClientId(apiKey, log) {
         ticket: result?.data?.ticket || '',
     };
 }
+/**
+ * 获取 Bot clientId 与 ticket，失败或 ticket 为空时额外重试一次。
+ * @param apiKey - 当前账户的 apiKey
+ * @param log - 可选日志对象
+ */
+export async function resolveBotClientIdWithRetry(apiKey, log) {
+    let lastError;
+    for (let attempt = 0; attempt < 2; attempt++) {
+        try {
+            const result = await resolveBotClientId(apiKey, log);
+            if (result.ticket || attempt === 1)
+                return result;
+            lastError = new Error(`[${CHANNEL_KEY}] Missing ticket in ${API_PATH_USER_CURRENT} response`);
+        }
+        catch (error) {
+            lastError = error;
+        }
+        if (attempt === 0) {
+            const message = lastError instanceof Error ? lastError.message : String(lastError);
+            log?.warn(`[${CHANNEL_KEY}] Failed to resolve ticket, retrying once: ${message}`);
+        }
+    }
+    throw lastError instanceof Error ? lastError : new Error(String(lastError));
+}
 // ============================================================
 // 核心：启动 Gateway
 // ============================================================
@@ -112,7 +136,7 @@ export async function startGateway(ctx) {
     // 通过 HTTP 接口获取 Bot 的 clientId（botClientId）
     // 新配置格式：accountId 即为 uin，apiKey 与 uin 一一对应，直接构建映射表
     log?.info(`${prefix} Resolving botClientId for account ${account.accountId}...`);
-    const { botClientId, ticket } = await resolveBotClientId(account.apiKey, log);
+    const { botClientId, ticket: initialTicket } = await resolveBotClientIdWithRetry(account.apiKey, log);
     // 一次性构建全局 uin→apiKey 映射（遍历所有 accounts，幂等操作）
     // 解决多账号场景下每个 gateway 启动时覆盖全局 Map 的问题
     buildGlobalApiKeyMap(cfg);
@@ -306,14 +330,26 @@ export async function startGateway(ctx) {
     // 将 cleanup 注册到全局 Map，供防重入检查和外部销毁使用
     activeGateways.set(account.accountId, cleanup);
     // ---- 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}`);
+    // 采用 ticket 作为 query 参数进行认证，不再使用 header 方式。
+    // ai-server ticket 是一次性凭证，因此每次建连/重连前都必须重新获取 fresh ticket。
+    // 首次连接复用启动阶段已获取的 ticket；后续重连再重新请求，避免浪费未消费 ticket。
+    let nextTicket = initialTicket;
+    const buildSocketQuery = async () => {
+        const freshTicket = nextTicket || (await resolveBotClientIdWithRetry(account.apiKey, log)).ticket;
+        nextTicket = '';
+        if (!freshTicket) {
+            throw new Error(`[${CHANNEL_KEY}] Missing ticket in ${API_PATH_USER_CURRENT} response`);
+        }
+        return {
+            ticket: freshTicket,
+            enableMultiLogin: false,
+        };
+    };
     // 使用原生 WebSocket 封装层建立连接
     const socket = new NativeSocketClient(WS_URL, {
-        // 认证：ticket 作为 URL query 参数，替代 Authorization header
-        path: `${SOCKET_PATH}${ticketQuery}&enableMultiLogin=false`,
+        // 认证：每次连接前由动态 query 获取 fresh ticket，避免自动重连复用旧 ticket 触发 401。
+        path: SOCKET_PATH,
+        query: buildSocketQuery,
         logPrefix: `[${CHANNEL_KEY}:${account.accountId}:NativeSocket]`,
     });
     currentSocket = socket;

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

@@ -13,7 +13,7 @@
  *   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';
+import { SOCKET_RECONNECTION_DELAY, SOCKET_RECONNECTION_DELAY_MAX, SOCKET_RECONNECTION_ATTEMPTS, SOCKET_RECONNECTION_INITIAL_JITTER_MAX, SOCKET_RECONNECTION_JITTER_RATIO, WS_PING_INTERVAL_MS, WS_HEARTBEAT_INITIAL_JITTER_MAX, WS_PONG_TIMEOUT_MS, WS_MAX_MISSED_PONG, } from '../config.js';
 import { getModuleLogger } from '../utils/logger.js';
 /** 模块级日志器 */
 const moduleLog = getModuleLogger('socket.native-socket');
@@ -25,8 +25,11 @@ const moduleLog = getModuleLogger('socket.native-socket');
  *
  * 使用方式：
  * ```ts
- * // 认证信息请直接拼接到 URL 上（例如 ?ticket=xxx），本类不再处理 auth headers
- * const socket = new NativeSocketClient(`${WS_URL}?ticket=xxx`, { path: '/claw-socket' });
+ * // path 仅表达路径；ticket 等鉴权参数通过 query 传入，可用异步函数在重连前刷新
+ * const socket = new NativeSocketClient(WS_URL, {
+ *   path: '/ws/agent',
+ *   query: async () => ({ ticket: await fetchTicket() }),
+ * });
  * socket.on('connect', () => { ... });
  * socket.on('message:private', (data) => { ... });
  * socket.timeout(5000).emit('message:private', data, (err) => { ... });
@@ -42,6 +45,8 @@ export class NativeSocketClient {
     _connected = false;
     _id = undefined;
     _ws = null;
+    /** 是否正在构建或发起连接，避免异步 query 获取期间重复建连 */
+    _connecting = false;
     /** 是否为主动断开（主动断开时不触发自动重连） */
     _manualDisconnect = false;
     // ----------------------------------------------------------
@@ -50,6 +55,14 @@ export class NativeSocketClient {
     _reconnectAttempts = 0;
     _reconnectTimer = null;
     // ----------------------------------------------------------
+    // WebSocket 协议级心跳状态
+    // ----------------------------------------------------------
+    _heartbeatInitialTimer = null;
+    _pingTimer = null;
+    _pongTimeoutTimer = null;
+    _lastPingAt = 0;
+    _missedPongCount = 0;
+    // ----------------------------------------------------------
     // 事件监听器映射表
     // ----------------------------------------------------------
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -67,16 +80,17 @@ export class NativeSocketClient {
     /** 日志前缀，便于在多实例场景下区分日志来源。 */
     logPrefix;
     /**
-     * @param url     WebSocket 服务端地址（ws:// 或 wss://），认证所需的 ticket 等参数请直接拼到 URL query 上
+     * @param url     WebSocket 服务端地址（ws:// 或 wss://）
      * @param options 连接选项
-     *   - path: 连接路径（如 /claw-socket），会附加到 URL
+     *   - path: 连接路径（如 /ws/agent），仅表达路径语义
+     *   - query: 静态或动态查询参数；ticket 等鉴权参数应放在这里
      *   - logPrefix: 日志前缀（可选），默认 `[NativeSocket]`
      */
     constructor(url, options = {}) {
         this.url = url;
         this.options = options;
         this.logPrefix = options.logPrefix ?? '[NativeSocket]';
-        this._connect();
+        void this._connect();
     }
     // ----------------------------------------------------------
     // NativeSocket 接口实现
@@ -184,38 +198,63 @@ export class NativeSocketClient {
     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'}`);
+        if (this._connecting || (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();
+        void this._connect();
         return this;
     }
     // ----------------------------------------------------------
     // 内部：建立 WebSocket 连接
     // ----------------------------------------------------------
-    _connect() {
-        // 构建完整 URL（仅拼接 path，认证通过 URL query 参数完成，无需 headers）
-        const fullUrl = this._buildUrl();
-        this.log.info(`${this.logPrefix} Connecting to ${fullUrl}`);
+    async _connect() {
+        if (this._connecting || (this._ws && (this._ws.readyState === WebSocket.CONNECTING || this._ws.readyState === WebSocket.OPEN))) {
+            this.log.debug?.(`${this.logPrefix} _connect() skipped, connection already in progress or open`);
+            return;
+        }
+        this._connecting = true;
+        let fullUrl;
+        try {
+            // 构建完整 URL（仅拼接 path，认证通过 URL query 参数完成，无需 headers）
+            fullUrl = await this._buildUrl();
+        }
+        catch (err) {
+            this._connecting = false;
+            const message = err instanceof Error ? err.message : String(err);
+            this.log.error(`${this.logPrefix} Failed to build WebSocket URL: ${message}`);
+            this._dispatch('connect_error', err instanceof Error ? err : new Error(message));
+            if (!this._manualDisconnect) {
+                this._scheduleReconnect();
+            }
+            return;
+        }
+        this.log.info(`${this.logPrefix} Connecting to ${this._maskUrl(fullUrl)}`);
         try {
             const ws = new WebSocket(fullUrl);
             this._ws = ws;
             ws.onopen = () => {
+                this._connecting = false;
                 this._reconnectAttempts = 0;
                 this._connected = true;
                 this.log.info(`${this.logPrefix} WebSocket opened`);
+                this._startHeartbeat();
                 this._dispatch('connect');
             };
             ws.onmessage = (event) => {
                 this._handleMessage(event.data);
             };
+            ws.on('pong', () => {
+                this._handleHeartbeatPong();
+            });
             ws.onclose = (event) => {
                 const wasConnected = this._connected;
+                this._stopHeartbeat();
+                this._connecting = false;
                 this._connected = false;
                 this._id = undefined;
                 this._ws = null;
@@ -238,6 +277,7 @@ export class NativeSocketClient {
             };
         }
         catch (err) {
+            this._connecting = false;
             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)));
@@ -314,8 +354,103 @@ export class NativeSocketClient {
         }
     }
     // ----------------------------------------------------------
+    // 内部：WebSocket 协议级心跳
+    // ----------------------------------------------------------
+    _startHeartbeat() {
+        this._stopHeartbeat();
+        this._missedPongCount = 0;
+        const initialDelay = this._randomDelay(0, WS_HEARTBEAT_INITIAL_JITTER_MAX);
+        this.log.info(`${this.logPrefix} WebSocket heartbeat started (initialDelay=${initialDelay}ms, interval=${WS_PING_INTERVAL_MS}ms, timeout=${WS_PONG_TIMEOUT_MS}ms, maxMissed=${WS_MAX_MISSED_PONG})`);
+        this._heartbeatInitialTimer = setTimeout(() => {
+            this._heartbeatInitialTimer = null;
+            this._sendHeartbeatPing();
+            this._pingTimer = setInterval(() => {
+                this._sendHeartbeatPing();
+            }, WS_PING_INTERVAL_MS);
+        }, initialDelay);
+    }
+    _stopHeartbeat() {
+        if (this._heartbeatInitialTimer !== null) {
+            clearTimeout(this._heartbeatInitialTimer);
+            this._heartbeatInitialTimer = null;
+        }
+        if (this._pingTimer !== null) {
+            clearInterval(this._pingTimer);
+            this._pingTimer = null;
+        }
+        if (this._pongTimeoutTimer !== null) {
+            clearTimeout(this._pongTimeoutTimer);
+            this._pongTimeoutTimer = null;
+        }
+        this._lastPingAt = 0;
+        this._missedPongCount = 0;
+    }
+    _sendHeartbeatPing() {
+        if (!this._ws || this._ws.readyState !== WebSocket.OPEN)
+            return;
+        if (this._pongTimeoutTimer !== null) {
+            clearTimeout(this._pongTimeoutTimer);
+            this._pongTimeoutTimer = null;
+        }
+        this._lastPingAt = Date.now();
+        try {
+            this._ws.ping();
+            this.log.debug?.(`${this.logPrefix} WebSocket ping sent`);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            this._terminateStaleConnection(`ping failed: ${message}`);
+            return;
+        }
+        this._pongTimeoutTimer = setTimeout(() => {
+            this._pongTimeoutTimer = null;
+            this._missedPongCount++;
+            this.log.warn(`${this.logPrefix} WebSocket pong timeout (missed=${this._missedPongCount}/${WS_MAX_MISSED_PONG})`);
+            if (this._missedPongCount >= WS_MAX_MISSED_PONG) {
+                this._terminateStaleConnection('pong timeout');
+            }
+        }, WS_PONG_TIMEOUT_MS);
+    }
+    _handleHeartbeatPong() {
+        const rtt = this._lastPingAt > 0 ? Date.now() - this._lastPingAt : 0;
+        if (this._pongTimeoutTimer !== null) {
+            clearTimeout(this._pongTimeoutTimer);
+            this._pongTimeoutTimer = null;
+        }
+        this._missedPongCount = 0;
+        this.log.debug?.(`${this.logPrefix} WebSocket pong received (rtt=${rtt}ms)`);
+    }
+    _terminateStaleConnection(reason) {
+        if (!this._ws)
+            return;
+        this.log.warn(`${this.logPrefix} WebSocket stale detected: ${reason}, terminating connection`);
+        this._stopHeartbeat();
+        try {
+            this._ws.terminate();
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            this.log.error(`${this.logPrefix} WebSocket terminate failed: ${message}`);
+        }
+    }
+    // ----------------------------------------------------------
     // 内部：自动重连
     // ----------------------------------------------------------
+    _randomDelay(min, max) {
+        const normalizedMin = Math.max(0, Math.floor(min));
+        const normalizedMax = Math.max(normalizedMin, Math.floor(max));
+        return normalizedMin + Math.floor(Math.random() * (normalizedMax - normalizedMin + 1));
+    }
+    _getReconnectDelay() {
+        const baseDelay = Math.min(SOCKET_RECONNECTION_DELAY * Math.pow(2, this._reconnectAttempts), SOCKET_RECONNECTION_DELAY_MAX);
+        if (this._reconnectAttempts === 0) {
+            return this._randomDelay(SOCKET_RECONNECTION_DELAY, SOCKET_RECONNECTION_INITIAL_JITTER_MAX);
+        }
+        const jitterRange = Math.max(0, SOCKET_RECONNECTION_JITTER_RATIO);
+        const minDelay = Math.floor(baseDelay * Math.max(0, 1 - jitterRange));
+        const maxDelay = Math.min(SOCKET_RECONNECTION_DELAY_MAX, Math.floor(baseDelay * (1 + jitterRange)));
+        return this._randomDelay(minDelay, maxDelay);
+    }
     _scheduleReconnect() {
         // 超过最大重连次数时停止重连
         if (SOCKET_RECONNECTION_ATTEMPTS !== Infinity && this._reconnectAttempts >= SOCKET_RECONNECTION_ATTEMPTS) {
@@ -323,14 +458,13 @@ export class NativeSocketClient {
             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);
+        const delay = this._getReconnectDelay();
         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 (jittered)`);
         this._reconnectTimer = setTimeout(() => {
             this._reconnectTimer = null;
             if (!this._manualDisconnect) {
-                this._connect();
+                void this._connect();
             }
         }, delay);
     }
@@ -352,6 +486,7 @@ export class NativeSocketClient {
     // 内部：关闭 WebSocket
     // ----------------------------------------------------------
     _closeWs() {
+        this._stopHeartbeat();
         if (this._ws) {
             // 移除所有回调，防止 onclose 触发重连
             this._ws.onopen = null;
@@ -366,6 +501,7 @@ export class NativeSocketClient {
             }
             this._ws = null;
         }
+        this._connecting = false;
         this._connected = false;
         this._id = undefined;
         // onclose 被置 null 后不会自动触发，需手动 flush 挂起的 ACK
@@ -374,13 +510,40 @@ export class NativeSocketClient {
     // ----------------------------------------------------------
     // 内部：构建完整 URL
     // ----------------------------------------------------------
-    _buildUrl() {
-        let base = this.url;
-        // 拼接 path（如 /claw-socket）
+    async _buildUrl() {
+        let base = this.url.replace(/\/$/, '');
         if (this.options.path) {
-            // 确保 base 末尾无斜杠，path 开头有斜杠
-            base = base.replace(/\/$/, '') + this.options.path;
+            const path = this.options.path.startsWith('/')
+                ? this.options.path
+                : `/${this.options.path}`;
+            base += path;
+        }
+        const query = typeof this.options.query === 'function'
+            ? await this.options.query()
+            : this.options.query;
+        const searchParams = new URLSearchParams();
+        Object.entries(query ?? {}).forEach(([key, value]) => {
+            if (value === undefined || value === null || value === '')
+                return;
+            searchParams.set(key, String(value));
+        });
+        const queryString = searchParams.toString();
+        if (!queryString)
+            return base;
+        return `${base}${base.includes('?') ? '&' : '?'}${queryString}`;
+    }
+    /** 对连接 URL 中的敏感 query 做日志脱敏 */
+    _maskUrl(url) {
+        try {
+            const parsed = new URL(url);
+            const ticket = parsed.searchParams.get('ticket');
+            if (ticket) {
+                parsed.searchParams.set('ticket', `${ticket.slice(0, 6)}...${ticket.slice(-4)}`);
+            }
+            return parsed.toString();
+        }
+        catch {
+            return url.replace(/([?&]ticket=)([^&]+)/, (_match, prefix, value) => (`${prefix}${value.slice(0, 6)}...${value.slice(-4)}`));
         }
-        return base;
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lightclawbot",
-  "version": "1.2.9",
+  "version": "1.2.10",
   "description": "LightClawBot channel plugin with message support, cron jobs, and proactive messaging",
   "type": "module",
   "files": [