lightclawbot 1.2.8 → 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/history/message-parser.js

@@ -210,6 +210,28 @@ export function normalizeMessage(msg) {
         const allFiles = [...(textFiles.length > 0 ? textFiles : []), ...(contentFiles ?? [])];
         if (allFiles.length > 0)
             files = deduplicateFiles(allFiles);
+        // 修复：当用户消息有 MediaPath/MediaPaths（OpenClaw 存在附件文件）
+        // 但 files 里没有 uri 时，补上 localfile:// 格式的 uri
+        if (!files || files.some((f) => !f.uri)) {
+            const mediaPaths = Array.isArray(msg.MediaPaths)
+                ? msg.MediaPaths
+                : (typeof msg.MediaPath === "string" ? [msg.MediaPath] : []);
+            if (mediaPaths.length > 0) {
+                const existingFiles = files ?? [];
+                const needInit = existingFiles.length === 0;
+                const updatedFiles = needInit
+                    ? mediaPaths.map((p, i) => ({
+                        name: existingFiles[i]?.name ?? p.split("/").pop() ?? `file-${i}`,
+                        mimeType: existingFiles[i]?.mimeType,
+                        uri: `localfile://${p}`,
+                    }))
+                    : existingFiles.map((f, i) => ({
+                        ...f,
+                        uri: f.uri ?? (mediaPaths[i] ? `localfile://${mediaPaths[i]}` : undefined),
+                    }));
+                files = updatedFiles;
+            }
+        }
     }
     else {
         files = extractContentFiles(msg.content) || undefined;

package/dist/src/outbound.js

@@ -84,17 +84,52 @@ function sendViaSocket(accountId, target, text, replyToId) {
     // 从 socket-registry 中获取当前账户的 socket entry
     const entry = getSocket(resolvedAccountId);
     const msgId = generateOutboundMsgId();
-    // 构造标准消息体，格式与 gateway 入站消息保持一致
+    const fromId = entry?.botClientId ?? getBotClientId(resolvedAccountId) ?? '';
+    // 构造标准消息体，格式与 gateway 入站消息保持一致。
+    //
+    // 协议关键字段说明：
+    //   - kind: 'stream_chunk'
+    //       outbound 由 LLM 工具调用结果（如 message 工具发图/发文）触发，
+    //       归属于"流式回复信号链"的一部分，前端依赖 kind 推导消息状态
+    //       （stream_chunk → 'updating'）。若缺省，前端 statusMap 会兜底到
+    //       typing_stop=='success'，导致内容被独立成一条"已完成回复"气泡，
+    //       与上一段 LLM 文本（已 typing_stop）错位拼接。详见 stream-reply-sink。
+    //   - extra.chatId: ''
+    //       协议规定所有 EVENT_MESSAGE_PRIVATE 必须携带 extra.chatId（多会话分桶）。
+    //       outbound 触发时通常无明确 chatId 上下文（cron / message 工具 / REST 等），
+    //       按协议约定填空字符串落到默认会话。
+    //   - idempotencyKey: 由 ReliableEmitter 在 emitWithAck 内部注入，此处无需显式构造。
     const message = {
         msgId,
         // 优先使用 entry 中缓存的 botClientId，entry 不存在时从 registry 直接查询
-        from: entry?.botClientId ?? getBotClientId(resolvedAccountId) ?? '',
+        from: fromId,
         to: target,
         content: text,
         timestamp: Date.now(),
+        kind: 'stream_chunk',
         // undefined 表示非回复消息，避免发送多余字段
         replyToMsgId: replyToId ?? undefined,
+        extra: { chatId: '' },
     };
+    // 自闭合 typing_stop 帧：与 stream_chunk 共用同一个 msgId / chatId，
+    // content 必须为空字符串（前端 addOrUpdateMessage 会按 oldContent + content 拼接，
+    // 非空 content 会让 caption 文本被复制一遍）。
+    //
+    // 设计理由：
+    //   outbound 通道（如 message 工具调用结果）由 OpenClaw 框架以「独立 messageId」投递，
+    //   不会与上一段 LLM 流式回复合并。仅发 stream_chunk 而无 typing_stop，
+    //   会导致前端这条独立气泡永远停留在 'updating' 状态（loading 转圈）。
+    //   故每条 outbound 消息都自带一帧 typing_stop 收尾，让该气泡正常进入 'success'。
+    const buildClosingFrame = () => ({
+        msgId,
+        from: fromId,
+        to: target,
+        content: '',
+        timestamp: Date.now(),
+        kind: 'typing_stop',
+        replyToMsgId: replyToId ?? undefined,
+        extra: { chatId: '' },
+    });
     if (entry) {
         // 策略 1：Socket 已连接，优先走可靠发送（emitWithAck + 自动重试）
         const emitter = getReliableEmitter(resolvedAccountId);
@@ -105,12 +140,24 @@ function sendViaSocket(accountId, target, text, replyToId) {
                     logger.error(`[${CHANNEL_KEY}] outbound delivery failed after retries: msgId=${msgId}`);
                 }
             });
+            // 紧跟一帧 typing_stop 闭合该 msgId 的流式状态。
+            // ReliableEmitter 内部按 emit 顺序生成 idempotencyKey（字典序 == emit 顺序），
+            // 即便网络层 batch 抖动导致 packet 乱序到达，前端也能按字典序合并出
+            // 「stream_chunk 在前 → typing_stop 在后」的稳定终态。
+            const closingFrame = buildClosingFrame();
+            emitter.emitWithAck(EVENT_MESSAGE_PRIVATE, closingFrame, msgId).then((ok) => {
+                if (!ok) {
+                    logger.warn(`[${CHANNEL_KEY}] outbound closing frame ack timeout: msgId=${msgId}`);
+                }
+            });
             logger.info(`[${CHANNEL_KEY}] outbound sent via reliable WS: to=${target} msgId=${msgId}`);
             return msgId;
         }
         // 策略 2：可靠发送器不可用，直接 emit（兜底，正常情况不应走到此分支）
         try {
             entry.socket.emit(EVENT_MESSAGE_PRIVATE, message);
+            // 同样补一帧 typing_stop；裸 emit 无 ack，无法保证送达，best-effort 即可。
+            entry.socket.emit(EVENT_MESSAGE_PRIVATE, buildClosingFrame());
             logger.info(`[${CHANNEL_KEY}] outbound sent via WS (fallback): to=${target} msgId=${msgId}`);
             return msgId;
         }
@@ -125,6 +172,10 @@ function sendViaSocket(accountId, target, text, replyToId) {
     if (hasEntry(resolvedAccountId)) {
         const buffered = bufferMessage(resolvedAccountId, message);
         if (buffered) {
+            // 顺序 push 一帧 typing_stop，flush 时随业务消息一起按 FIFO 发出。
+            // bufferMessage 失败（队列满）则跳过闭合帧 —— 主消息都没缓冲住，
+            // 闭合帧也没意义；前端会因永远收不到 stream_chunk 而不展示这条气泡。
+            bufferMessage(resolvedAccountId, buildClosingFrame());
             logger.info(`[${CHANNEL_KEY}] outbound buffered (WS reconnecting): to=${target} msgId=${msgId}`);
             return msgId;
         }

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/dist/src/streaming/stream-reply-sink.js

@@ -33,6 +33,56 @@ const LOCALIZED_ABORT_REPLY = "已停止当前回复。";
 function localizeAbortReplyText(text) {
     return OPENCLAW_ABORT_REPLY_RE.test(text.trim()) ? LOCALIZED_ABORT_REPLY : text;
 }
+/** 已知的图片扩展名集合，用于判断是否走 files 渲染（而非 markdown 文本链接）。 */
+const IMAGE_EXTS = new Set(["png", "jpg", "jpeg", "gif", "webp", "svg", "bmp", "ico"]);
+/**
+ * 判断 URL 指向的资源是否为图片（基于文件扩展名）。
+ *
+ * 优先匹配 COS 公网 URL 中的 `filePath=xxx` query 参数；
+ * 回退到 URL 末段。判断失败一律按"非图片"处理（保留文本链接，前端兼容性更好）。
+ */
+function isImageUrl(url) {
+    let candidate = url;
+    const filePathMatch = url.match(/filePath=([^&]+)/);
+    if (filePathMatch) {
+        try {
+            candidate = decodeURIComponent(filePathMatch[1]);
+        }
+        catch {
+            candidate = filePathMatch[1];
+        }
+    }
+    const lastDot = candidate.lastIndexOf(".");
+    if (lastDot < 0)
+        return false;
+    const ext = candidate.slice(lastDot + 1).split(/[?#]/)[0].toLowerCase();
+    return IMAGE_EXTS.has(ext);
+}
+/**
+ * 对 mediaUrls 入口去重：同一文件常以裸路径 `/path/to/x.png` 和带前缀
+ * `file:///path/to/x.png` 两种形式同时出现（如 browser screenshot toolResult），
+ * 不归一就会让前端同时渲染两份"全部文件"卡片（即用户看到的"两个全部文件按钮"）。
+ *
+ * 归一规则：
+ *   - 去掉 `file://` 前缀做"路径键"比较；
+ *   - 保留首次出现的原始字符串（保留 `file://` 与否取决于 mediaList 顺序），
+ *     避免破坏后续 `existsSync` / `mediaUrlsToFiles` 对路径形态的处理。
+ *
+ * 不做内容级去重（buffer hash），因为 data URL 与本地路径同图的归一代价较高，
+ * 且配合"图片不再重复拼 markdown"已能消除可见的重复渲染。
+ */
+function dedupMediaUrls(urls) {
+    const seen = new Set();
+    const result = [];
+    for (const url of urls) {
+        const key = url.startsWith("file://") ? url.slice(7) : url;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        result.push(url);
+    }
+    return result;
+}
 export function createStreamReplyConfig(opts, prefixOptions, signalCtx) {
     const { emitter, targetId, originalMsgId, log, effectiveApiKey, typingAlreadyStarted, sessionKey, agentId } = opts;
     // ── 群聊扩展字段 ──
@@ -237,25 +287,44 @@ export function createStreamReplyConfig(opts, prefixOptions, signalCtx) {
         }
     };
     /**
-     * 处理 payload 中的 mediaUrls：COS 上传 → 拼 Markdown 链接 → 推送给用户。
+     * 处理 payload 中的 mediaUrls：去重 → COS 上传 → 与文本同帧推送给用户。
      * 仅在 mediaList 非空时调用。
      *
-     * 群聊模式：通过 stream_chunk 信号帧推送 Markdown 图片/文件链接（带群聊 extra）。
-     * 私聊模式：通过 emitter.sendFiles / emitter.sendReply 推送。
+     * 私聊 / 群聊统一通过 `emitSignal('stream_chunk', ...)` 走信号链，
+     * 复用本轮 replyMsgId（与 stream_chunk 文本同 msgId 合并到同一气泡），
+     * 同时携带 kind / agentId / extra.chatId / chatKind 等协议字段，
+     * 避免前端因 kind 缺失而把媒体帧兜底为 typing_stop 完成态独立气泡。
+     *
+     * 协议约定：
+     *   - 图片由顶层 `files` 字段独家承载（前端文件卡片渲染），
+     *     文本里**不再**额外拼 `![](url)` markdown，避免"两张图"重复渲染。
+     *   - 非图片文件（pdf / 压缩包等）保留 `📎 [filename](url)` 文本链接，
+     *     方便用户复制公网 URL，同时仍透传 files 给前端文件卡片。
      */
     const handleMediaFinal = async (replyText, mediaList) => {
-        const files = await mediaUrlsToFiles(mediaList, log);
+        // 去重：mediaUrls 常包含同一文件的多种引用（裸路径 / file:// 前缀），
+        // 归一后再交给下游处理，避免 files 数组与 publicUrls 数组各自重复一次。
+        const dedupedMediaList = dedupMediaUrls(mediaList);
+        const files = await mediaUrlsToFiles(dedupedMediaList, log);
         const storageConfig = { apiKey: effectiveApiKey };
-        const publicUrls = [];
-        for (const mediaUrl of mediaList) {
+        /** 仅非图片文件需要在文本里给出公网链接，图片由 files 渲染。 */
+        const nonImagePublicLinks = [];
+        for (const mediaUrl of dedupedMediaList) {
             try {
                 const localPath = mediaUrl.startsWith("file://") ? mediaUrl.slice(7) : mediaUrl;
                 if (localPath.startsWith("/") || localPath.match(/^[A-Za-z]:\\/)) {
                     const { existsSync } = await import("node:fs");
                     if (existsSync(localPath)) {
                         const result = await uploadFileToServer(localPath, storageConfig);
-                        publicUrls.push(result.url || "");
-                        log?.info(`[${CHANNEL_KEY}] [stream] Uploaded to COS: ${localPath} → ${result.url}`);
+                        const publicUrl = result.url || "";
+                        log?.info(`[${CHANNEL_KEY}] [stream] Uploaded to COS: ${localPath} → ${publicUrl}`);
+                        // 仅非图片文件保留文本链接（图片由 files 渲染，避免重复）
+                        if (publicUrl && !isImageUrl(publicUrl)) {
+                            const match = publicUrl.match(/filePath=([^&]+)/);
+                            const filePath = match ? decodeURIComponent(match[1]) : "";
+                            const fileName = filePath.split("/").pop() || "file";
+                            nonImagePublicLinks.push(`📎 [${fileName}](${publicUrl})`);
+                        }
                     }
                 }
             }
@@ -264,41 +333,33 @@ export function createStreamReplyConfig(opts, prefixOptions, signalCtx) {
             }
         }
         let enrichedText = replyText;
-        if (publicUrls.length > 0) {
-            // 判断是否为图片类型（根据 URL 中的文件扩展名）
-            const urlSection = publicUrls
-                .map((url, i) => {
-                const match = url.match(/filePath=([^&]+)/);
-                const filePath = match ? decodeURIComponent(match[1]) : "";
-                const fileName = filePath.split("/").pop() || `file${publicUrls.length > 1 ? ` (${i + 1})` : ""}`;
-                const ext = fileName.split('.').pop()?.toLowerCase() || '';
-                const isImage = ['png', 'jpg', 'jpeg', 'gif', 'webp', 'svg', 'bmp', 'ico'].includes(ext);
-                // 图片使用 Markdown 图片语法，非图片使用链接语法
-                return isImage ? `![${fileName}](${url})` : `📎 [${fileName}](${url})`;
-            })
-                .join("\n");
+        if (nonImagePublicLinks.length > 0) {
+            const urlSection = nonImagePublicLinks.join("\n");
             enrichedText = enrichedText ? `${enrichedText}\n\n${urlSection}` : urlSection;
         }
-        // ── 群聊模式：通过 stream_chunk 推送（带群聊 extra，前端能正确识别） ──
-        if (isGroupMode) {
-            if (enrichedText.trim()) {
-                const delta = `\n\n${enrichedText}`;
-                streamedText += delta;
-                emitSignal(signalCtx, "stream_chunk", delta, groupSignalExtra, buildGroupDataExtra('delta'));
-                emittedUserVisible = true;
-                log?.info(`[${CHANNEL_KEY}] [stream] handleMediaFinal(group): pushed ${publicUrls.length} media as stream_chunk`);
-            }
+        // 没有任何可见内容（既无文本又无文件）→ 直接返回，避免发空帧
+        if (!enrichedText.trim() && files.length === 0) {
             return;
         }
-        // ── 私聊模式：通过 sendFiles / sendReply 推送 ──
-        if (files.length > 0) {
-            emitter.sendFiles(targetId, enrichedText, files, originalMsgId, signalCtx.chatId);
-            emittedUserVisible = true;
-        }
-        else if (enrichedText.trim()) {
-            emitter.sendReply(targetId, enrichedText, originalMsgId, signalCtx.chatId);
+        // ── 群聊模式：通过 stream_chunk 推送（带群聊 extra） ──
+        // 群聊额外把文本累加到 streamedText，让 markComplete 的 aggregatedText 能算上这段。
+        if (isGroupMode) {
+            const delta = enrichedText.trim() ? `\n\n${enrichedText}` : "";
+            if (delta)
+                streamedText += delta;
+            emitSignal(signalCtx, "stream_chunk", delta, { ...(files.length > 0 ? { files } : {}), ...groupSignalExtra }, buildGroupDataExtra('delta'));
             emittedUserVisible = true;
+            log?.info(`[${CHANNEL_KEY}] [stream] handleMediaFinal(group): pushed ${files.length} file(s), ` +
+                `nonImageLinks=${nonImagePublicLinks.length}`);
+            return;
         }
+        // ── 私聊模式：同样通过 stream_chunk 走信号链 ──
+        // 关键：复用 signalCtx.replyMsgId → 与本轮 stream_chunk 文本同 msgId 合并，
+        //       且自动携带 kind/agentId/extra.chatId，前端不再兜底为 typing_stop。
+        emitSignal(signalCtx, "stream_chunk", enrichedText, files.length > 0 ? { files } : undefined);
+        emittedUserVisible = true;
+        log?.info(`[${CHANNEL_KEY}] [stream] handleMediaFinal: pushed ${files.length} file(s) via stream_chunk, ` +
+            `textLen=${enrichedText.length} nonImageLinks=${nonImagePublicLinks.length}`);
     };
     // ────────────────────────────────────────
     // dispatcher

package/dist/src/tools/upload-tool.js

@@ -45,7 +45,7 @@ export function registerUploadTool(api) {
         }
         return {
             name: UPLOAD_TOOL_NAME,
-            description: "将 AI 生成的本机文件注册为可下载的引用，返回 `localfile://<绝对路径>` 格式的 Markdown 下载链接。" +
+            description: "重要：将 AI 生成的本机文件注册为可下载的引用，要求必须立马返回 `[<文件名称>]localfile://<绝对路径>` 格式的 Markdown 下载链接；用户可以下载。" +
                 "当需要把生成的文件（图片、文档、代码包等）交付给用户时，必须使用此工具。" +
                 "文件必须先写入磁盘，然后传入绝对路径。单次最多 5 个文件，超出请分批调用。" +
                 "重要：工具返回的 Markdown 链接已是最终格式，请原样使用，不要改写为 https:// 或本机路径字符串。",

package/dist/src/utils/common.js

@@ -53,7 +53,11 @@ export function buildAuthHeaders(apiKey) {
  * 统一的信号发送出口，收敛 typing / stream / tool / usage 控制帧的构造逻辑。
  *
  * - typing_start 不带 replyToMsgId（协议要求）；其余帧都携带。
- * - topLevelExtra 用于透传顶层 kind 相关字段（如 tool_start 的 toolName/toolPhase、tool_end 的 toolIsError）。
+ * - topLevelExtra 用于透传顶层 kind 相关字段：
+ *     · tool_start 的 toolName / toolPhase
+ *     · tool_end   的 toolIsError
+ *     · 群聊场景的 chatKind
+ *     · 媒体附件的 files（与文本同帧投递，确保 kind/agentId/extra 齐全）
  * - innerExtra 用于在 PrivateMessageData.extra 内追加自定义字段（如 usage 帧的 usage 对象）。
  *   chatId 始终由本函数管理，调用方无需也不能在 innerExtra 中传 chatId（会被覆盖）。
  */

package/package.json

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