@dingtalk-real-ai/dingtalk-connector 0.7.9 → 0.7.10

package/CHANGELOG.md

@@ -1,10 +1,44 @@
 # Changelog
 
-本文档记录所有重要的变更。格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.0.0/)，
-版本号遵循 [Semantic Versioning](https://semver.org/lang/zh-CN/)。
+All notable changes to this project will be documented in this file.
 
-This document records all significant changes. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
-and version numbers follow [Semantic Versioning](https://semver.org/).
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.7.10] - 2026-03-16
+
+### 新增 / Added
+- ✨ **WebSocket 心跳重连机制优化** - 关闭 DWClient 的 `autoConnect`，采用应用层自动重连机制（修复 DWClient 重连 bug）；添加指数退避重连策略，避免雪崩效应；使用 WebSocket 原生 Ping 进行心跳检测  
+  **WebSocket heartbeat & reconnect optimization** - Disabled DWClient's `autoConnect`, implemented app-layer auto-reconnect (fixing DWClient bug); added exponential backoff to avoid avalanche; using WebSocket native Ping for heartbeat
+- ✨ **socket-manager 模块** - 新增模块统一管理 WebSocket 连接生命周期，包括心跳检测、自动重连、指数退避、事件监听等  
+  **socket-manager module** - New module for unified WebSocket connection lifecycle management, including heartbeat, auto-reconnect, exponential backoff, event listening
+- ✨ **debug 参数** - 添加 `debug` 配置项控制详细日志输出，便于问题排查  
+  **debug parameter** - Added `debug` config to control detailed log output for easier troubleshooting
+- ✨ **WebSocket 无限重连机制** - 移除最大重连次数限制，实现无限重连，确保长连接服务的高可用性  
+  **WebSocket infinite reconnection** - Removed maximum reconnection attempt limit, implemented infinite reconnection to ensure high availability for long-lived connection services
+
+### 修复 / Fixes
+- 🐛 **修复 DWClient 重连 bug** - DWClient 内置重连机制存在缺陷，通过应用层重连机制替代，确保连接稳定可靠  
+  **Fixed DWClient reconnect bug** - DWClient's built-in reconnect has defects; replaced with app-layer reconnect for stable connection
+- 🐛 **长连接静默断开** - 通过应用层心跳检测连接活性，超时后主动重连，减少因长时间无数据导致的静默断连且无法恢复  
+  **Long-lived connection silent disconnect** - App-layer heartbeat detects liveness and triggers reconnect on timeout, reducing silent disconnects when idle
+### 改进 / Improvements
+- ✅ **DWClient 配置** - 设置 `autoReconnect: false`、`keepAlive: false`，由应用层接管重连和心跳，避免与钉钉服务端策略冲突  
+  **DWClient config** - Set `autoReconnect: false`, `keepAlive: false`; app-layer takes over reconnect and heartbeat to avoid server conflicts
+- ✅ **指数退避策略** - 公式 `baseBackoffDelay * Math.pow(2, attempt) + jitter(0-1s)`，最大退避 30 秒，避免雪崩效应  
+  **Exponential backoff strategy** - Formula `baseBackoffDelay * Math.pow(2, attempt) + jitter(0-1s)`, max 30s backoff to avoid avalanche effect
+- ✅ **统一事件监听** - `pong`、`message`、`close`、`open` 四个事件统一管理和清理，提升代码可维护性  
+  **Unified event listening** - `pong`, `message`, `close`, `open` events managed and cleaned up uniformly, improving maintainability
+- ✅ **配置简化** - 从 `SocketManagerConfig` 中移除 `maxReconnectAttempts` 配置项，简化配置复杂度  
+  **Configuration simplification** - Removed `maxReconnectAttempts` from `SocketManagerConfig`, simplifying configuration
+- ✅ **日志输出优化** - 更新重连日志格式，移除最大次数显示（从 "尝试 X/5" 改为 "尝试 X"）  
+  **Log output optimization** - Updated reconnection log format, removed maximum attempt display (from "attempt X/5" to "attempt X")
+
+### 技术细节 / Technical Details
+- **退避策略**：指数退避 + 随机抖动，公式 `baseBackoffDelay * Math.pow(2, attempt) + jitter(0-1s)`  
+- **最大退避**：30 秒（由 `maxBackoffDelay` 限制）  
+- **重置条件**：重连成功后 `reconnectAttempts` 归零  
+- **立即重连**：心跳检测失败、WebSocket close、disconnect 消息触发时立即重连，不退避  
 
 ## [0.7.9] - 2026-03-13
 
@@ -243,5 +277,4 @@ and version numbers follow [Semantic Versioning](https://semver.org/).
 - 新增"多 Agent 配置"章节，提供详细的配置示例和说明  
   Added "Multi-Agent Configuration" section with detailed configuration examples and instructions
 - 补充常见问题解答  
-  Added FAQ section
-
+  Added FAQ section

package/README.md

@@ -3,7 +3,7 @@
 
 以下提供两种方案连接到 [OpenClaw](https://openclaw.ai) Gateway，分别是钉钉机器人和钉钉 DEAP Agent。
 
-> 📝 **版本信息**：当前版本 v0.7.7 | [查看变更日志](CHANGELOG.md) | [发布说明](docs/RELEASE_NOTES_V0.7.7.md) | [发布指南](RELEASE.md)
+> 📝 **版本信息**：当前版本 v0.7.10 | [查看变更日志](CHANGELOG.md) | [发布说明](docs/RELEASE_NOTES_V0.7.10.md) | [发布指南](RELEASE.md)
 
 ## 快速导航
 

package/docs/RELEASE_NOTES_V0.7.10.md

@@ -0,0 +1,40 @@
+# Release Notes - v0.7.10
+
+## ✨ 功能与体验改进 / Features & Improvements
+
+- **WebSocket 心跳重连机制优化 / WebSocket Reconnection**  
+  WebSocket 会持续尝试重连，保留指数退避策略（1s → 2s → 4s → 8s → 16s → 30s），避免雪崩效应。重连成功后重置计数器，下次失败从 1 秒开始退避。  
+  Removed maximum reconnection attempt limit, implemented infinite reconnection mechanism. WebSocket will continuously attempt to reconnect without giving up. Exponential backoff strategy retained (1s → 2s → 4s → 8s → 16s → 30s) to avoid avalanche effect. Counter resets on successful reconnection, starting from 1 second on next failure.
+
+- **配置简化 / Configuration Simplification**  
+  从 `SocketManagerConfig` 中移除 `maxReconnectAttempts` 配置项，简化配置复杂度。  
+  Removed `maxReconnectAttempts` configuration from `SocketManagerConfig`, simplifying configuration complexity.
+
+- **日志输出优化 / Log Output Optimization**  
+  更新重连日志格式，移除最大次数显示（从 "尝试 X/5" 改为 "尝试 X"），更清晰地展示重连进度。  
+  Updated reconnection log format, removed maximum attempt display (from "attempt X/5" to "attempt X"), providing clearer reconnection progress.
+
+
+## 📥 安装升级 / Installation & Upgrade
+
+```bash
+# 通过 npm 安装最新版本 / Install latest version via npm
+openclaw plugins install @dingtalk-real-ai/dingtalk-connector
+
+# 或升级现有版本 / Or upgrade existing version
+openclaw plugins update dingtalk-connector
+
+# 通过 Git 安装 / Install via Git
+openclaw plugins install https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector.git
+```
+
+## 🔗 相关链接 / Related Links
+
+- [完整变更日志 / Full Changelog](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/blob/main/CHANGELOG.md)
+- [使用文档 / Documentation](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/blob/main/README.md)
+
+---
+
+**发布日期 / Release Date**：2026-03-16  
+**版本号 / Version**：v0.7.10  
+**兼容性 / Compatibility**：OpenClaw Gateway 0.4.0+

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "dingtalk-connector",
   "name": "DingTalk Channel",
-  "version": "0.7.9",
+  "version": "0.7.10",
   "description": "DingTalk (钉钉) messaging channel via Stream mode with AI Card streaming",
   "author": "DingTalk Real Team",
   "channels": ["dingtalk-connector"],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dingtalk-real-ai/dingtalk-connector",
-  "version": "0.7.9",
+  "version": "0.7.10",
   "description": "DingTalk (钉钉) channel connector — Stream mode with AI Card streaming",
   "main": "plugin.ts",
   "type": "module",

package/plugin.ts

@@ -11,6 +11,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
 import type { ClawdbotPluginApi, PluginRuntime, ClawdbotConfig } from 'clawdbot/plugin-sdk';
+import { createSocketManager, addToPendingAckQueue, removeFromPendingAckQueue, clearPendingAckQueue } from './src/socket-manager';
 
 // ============ 常量 ============
 
@@ -1263,6 +1264,7 @@ async function finishAICard(
           order: ['msgContent'],  // 只声明实际使用的字段，避免部分客户端显示空占位
         }),
       },
+      cardUpdateOptions:{updateCardDataByKey:true}
     },
   };
 
@@ -1469,47 +1471,64 @@ async function* streamFromGateway(options: GatewayOptions, accountId: string): A
 
   log?.info?.(`[DingTalk][Gateway] POST ${gatewayUrl}, session=${sessionKey}, accountId=${accountId}, agentId=${agentId}, peerKind=${peerKind}, messages=${messages.length}`);
 
-  const response = await fetch(gatewayUrl, {
-    method: 'POST',
-    headers,
-    body: JSON.stringify({
-      model: 'main',
-      messages,
-      stream: true,
-      user: sessionKey,  // 用于 session 持久化
-    }),
-  });
+  // 【TLS 模式修复】保存原始 TLS 设置，用于 finally 块中恢复
+  const originalRejectUnauthorized = process.env.NODE_TLS_REJECT_UNAUTHORIZED;
+  
+  try {
+    // TLS 模式：如果是 HTTPS URL，临时禁用证书验证（用于自签名证书场景）
+    if (gatewayUrl.startsWith('https://')) {
+      process.env.NODE_TLS_REJECT_UNAUTHORIZED = '0';
+      log?.debug?.(`[DingTalk][Gateway] TLS 模式：已临时禁用证书验证`);
+    }
 
-  log?.info?.(`[DingTalk][Gateway] 响应 status=${response.status}, ok=${response.ok}, hasBody=${!!response.body}`);
+    const response = await fetch(gatewayUrl, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify({
+        model: 'main',
+        messages,
+        stream: true,
+        user: sessionKey,  // 用于 session 持久化
+      }),
+    });
 
-  if (!response.ok || !response.body) {
-    const errText = response.body ? await response.text() : '(no body)';
-    log?.error?.(`[DingTalk][Gateway] 错误响应: ${errText}`);
-    throw new Error(`Gateway error: ${response.status} - ${errText}`);
-  }
+    log?.info?.(`[DingTalk][Gateway] 响应 status=${response.status}, ok=${response.ok}, hasBody=${!!response.body}`);
 
-  const reader = response.body.getReader();
-  const decoder = new TextDecoder();
-  let buffer = '';
+    if (!response.ok || !response.body) {
+      const errText = response.body ? await response.text() : '(no body)';
+      log?.error?.(`[DingTalk][Gateway] 错误响应：${errText}`);
+      throw new Error(`Gateway error: ${response.status} - ${errText}`);
+    }
 
-  while (true) {
-    const { done, value } = await reader.read();
-    if (done) break;
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
 
-    buffer += decoder.decode(value, { stream: true });
-    const lines = buffer.split('\n');
-    buffer = lines.pop() || '';
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
 
-    for (const line of lines) {
-      if (!line.startsWith('data: ')) continue;
-      const data = line.slice(6).trim();
-      if (data === '[DONE]') return;
+      buffer += decoder.decode(value, { stream: true });
+      const lines = buffer.split('\n');
+      buffer = lines.pop() || '';
 
-      try {
-        const chunk = JSON.parse(data);
-        const content = chunk.choices?.[0]?.delta?.content;
-        if (content) yield content;
-      } catch {}
+      for (const line of lines) {
+        if (!line.startsWith('data: ')) continue;
+        const data = line.slice(6).trim();
+        if (data === '[DONE]') return;
+
+        try {
+          const chunk = JSON.parse(data);
+          const content = chunk.choices?.[0]?.delta?.content;
+          if (content) yield content;
+        } catch {}
+      }
+    }
+  } finally {
+    // 【TLS 模式修复】恢复原始 TLS 证书验证设置，避免影响其他 HTTPS 请求
+    if (gatewayUrl.startsWith('https://')) {
+      process.env.NODE_TLS_REJECT_UNAUTHORIZED = originalRejectUnauthorized;
+      log?.debug?.(`[DingTalk][Gateway] TLS 模式：已恢复证书验证设置`);
     }
   }
 }
@@ -1864,7 +1883,11 @@ async function createAICardForTarget(
     const createBody = {
       cardTemplateId: AI_CARD_TEMPLATE_ID,
       outTrackId: cardInstanceId,
-      cardData: { cardParamMap: {} },
+      cardData: {
+        cardParamMap: {
+          config: JSON.stringify({ autoLayout: true }),  // 启用宽屏模式
+        },
+      },
       callbackType: 'STREAM',
       imGroupOpenSpaceModel: { supportForward: true },
       imRobotOpenSpaceModel: { supportForward: true },
@@ -2950,7 +2973,7 @@ async function handleDingTalkMessage(params: {
       const finalContent = accumulated.trim();
       if (finalContent.length === 0) {
         log?.info?.(`[DingTalk][AICard] 内容为空（纯媒体消息），使用默认提示`);
-        await finishAICard(card, '✅ 媒体已发送', log);
+        await finishAICard(card, '当前没有可展示的回复内容', log);
       } else {
         await finishAICard(card, finalContent, log);
       }
@@ -3550,27 +3573,49 @@ const dingtalkPlugin = {
       }
 
       ctx.log?.info(`[${account.accountId}] 启动钉钉 Stream 客户端...`);
+      ctx.log?.info(`[${account.accountId}] 配置信息：clientId=${config.clientId}, endpoint=${config.endpoint || '默认'}`);
 
-      // 配置 DWClient：关闭 SDK 内置的 keepAlive，使用应用层自定义心跳
-      // - autoReconnect: 连接断开时自动重连
+      // 配置 DWClient：关闭 SDK 内置的 keepAlive 和 autoReconnect，使用应用层自定义心跳和重连
+      // - autoReconnect: false（关闭 SDK 的自动重连，避免与应用层重连冲突）
       // - keepAlive: false（关闭 SDK 的激进心跳检测，避免 8 秒超时强制终止连接）
+      // - endpoint: 可选，自定义钉钉 API 网关地址，默认使用 SDK 内置的 https://api.dingtalk.com/v1.0/gateway/connections/open
       const client = new DWClient({
         clientId: config.clientId,
         clientSecret: config.clientSecret,
         debug: config.debug || false,
-        autoReconnect: true,
+        autoReconnect: false,  // ← 关闭 SDK 的自动重连，使用应用层重连
         keepAlive: false,
+        // ← 可选：自定义 endpoint，如使用内网代理或测试环境。如果不配置或配置错误，使用 SDK 默认值
+        ...(config.endpoint ? { endpoint: config.endpoint } : {}),
       } as any);
 
+      ctx.log?.info(`[${account.accountId}] DWClient 初始化完成，endpoint=${client.getConfig()?.endpoint || '默认'}`);
+
       client.registerCallbackListener(TOPIC_ROBOT, async (res: any) => {
         const messageId = res.headers?.messageId;
         ctx.log?.info?.(`[DingTalk] 收到 Stream 回调, messageId=${messageId}, headers=${JSON.stringify(res.headers)}`);
 
-        // 【关键修复】立即确认回调，避免钉钉服务器因超时而重发
-        // 钉钉 Stream 模式要求及时响应，否则约60秒后会重发消息
+        // 【关键修复】检查 WebSocket 状态后再确认回调，避免在 CONNECTING 状态下发送失败
         if (messageId) {
-          client.socketCallBackResponse(messageId, { success: true });
-          ctx.log?.info?.(`[DingTalk] 已立即确认回调: messageId=${messageId}`);
+          if (client.socket?.readyState === 1) {  // 1 = OPEN
+            client.socketCallBackResponse(messageId, { success: true });
+            ctx.log?.info?.(`[DingTalk] 已立即确认回调：messageId=${messageId}`);
+          } else {
+            ctx.log?.warn?.(`[DingTalk] WebSocket 未就绪 (readyState=${client.socket?.readyState})，延迟确认回调：messageId=${messageId}`);
+            // 【关键修复】将消息 ID 加入待确认队列，等待 WebSocket 打开后批量确认
+            pendingAckQueue.add(messageId);
+            // 等待 WebSocket 打开后再确认（兼容旧逻辑，但主要依赖 open 事件）
+            setTimeout(() => {
+              if (client.socket?.readyState === 1) {
+                client.socketCallBackResponse(messageId, { success: true });
+                pendingAckQueue.delete(messageId);  // 确认成功后从队列移除
+                ctx.log?.info?.(`[DingTalk] 延迟确认回调成功：messageId=${messageId}`);
+              } else {
+                ctx.log?.warn?.(`[DingTalk] 延迟确认回调失败：WebSocket 仍未就绪，messageId=${messageId}，将在 open 事件中批量确认`);
+                // 不再从队列移除，等待 open 事件处理
+              }
+            }, 500);  // 【关键修复】增加延迟时间到 500ms，确保 WebSocket 有足够时间打开
+          }
         }
 
         // 【消息去重】检查是否已处理过该消息
@@ -3604,6 +3649,19 @@ const dingtalkPlugin = {
       });
 
       await client.connect();
+      
+      // 【关键修复】等待 WebSocket 完全打开后再继续
+      // 避免 Gateway 重启后 WebSocket 还在 CONNECTING 状态就开始处理消息
+      if (client.socket) {
+        if (client.socket.readyState !== 1) {  // 1 = OPEN
+          ctx.log?.info?.(`[${account.accountId}] 等待 WebSocket 打开...`);
+          await new Promise((resolve) => {
+            client.socket!.once('open', resolve);
+            setTimeout(resolve, 5000);  // 最多等 5 秒
+          });
+        }
+      }
+      
       ctx.log?.info(`[${account.accountId}] 钉钉 Stream 客户端已连接`);
 
       const rt = getRuntime();
@@ -3611,92 +3669,25 @@ const dingtalkPlugin = {
 
       let stopped = false;
       
-      // 【应用层心跳机制】基于 WebSocket ping/pong 的主动心跳检测
-      // - 心跳间隔：30 秒
-      // - 超时时间：90 秒（允许 3 次 ping 无响应）
-      // - 检测方式：主动发送 ping，等待 pong 响应
-      let lastPongTime = Date.now();
-      let pendingPingId: string | null = null;
-      const HEARTBEAT_INTERVAL = 30 * 1000; // 30 秒
-      const HEARTBEAT_TIMEOUT = 90 * 1000;  // 90 秒
+      // 【关键修复】待确认消息队列：重连期间暂存需要确认的消息 ID
+      const pendingAckQueue = new Set<string>();
       
-      // 监听 pong 响应（SDK 的 keepAlive=false 时仍然会收到服务端的 pong）
-      client.socket?.on('pong', () => {
-        lastPongTime = Date.now();
-        pendingPingId = null;
-        ctx.log?.debug?.(`[${account.accountId}] 收到 PONG 响应`);
+      // 【使用 SocketManager 统一管理 WebSocket 连接、心跳、重连】
+      const debugMode = config.debug || false;
+      const socketManager = createSocketManager(client, {
+        accountId: account.accountId,
+        log: ctx.log,
+        stopped: () => stopped,
+        onReconnect: () => {
+          // 重连成功后的回调（如果需要）
+        },
+        pendingAckQueue,
+        client,
+        debug: debugMode,
       });
       
-      // 启动心跳检测定时器
-      const heartbeatTimer = setInterval(async () => {
-        if (stopped) {
-          clearInterval(heartbeatTimer);
-          return;
-        }
-        
-        const elapsed = Date.now() - lastPongTime;
-        
-        // 如果超过 90 秒没有收到 pong，认为连接已断开
-        if (elapsed > HEARTBEAT_TIMEOUT) {
-          ctx.log?.warn?.(`[${account.accountId}] ⚠️ 心跳超时：已 ${Math.round(elapsed / 1000)} 秒未收到 PONG，触发重连...`);
-          
-          // 【关键修复】主动重连：先断开再重新建立连接
-          try {
-            // 1. 先断开旧连接
-            await client.disconnect();
-            ctx.log?.info?.(`[${account.accountId}] 已断开旧连接`);
-            
-            // 2. 重新建立连接
-            ctx.log?.info?.(`[${account.accountId}] 正在重新建立连接...`);
-            await client.connect();
-            
-            // 3. 重置最后 pong 时间，避免立即再次触发重连
-            lastPongTime = Date.now();
-            pendingPingId = null;
-            
-            ctx.log?.info?.(`[${account.accountId}] ✅ 重连成功`);
-          } catch (err: any) {
-            ctx.log?.error?.(`[${account.accountId}] ❌ 重连失败：${err.message}`);
-            // 重连失败后，等待 5 秒后再次尝试
-            ctx.log?.info?.(`[${account.accountId}] 5 秒后再次尝试重连...`);
-            setTimeout(async () => {
-              try {
-                await client.connect();
-                lastPongTime = Date.now();
-                pendingPingId = null;
-                ctx.log?.info?.(`[${account.accountId}] ✅ 重试重连成功`);
-              } catch (retryErr: any) {
-                ctx.log?.error?.(`[${account.accountId}] ❌ 重试重连失败：${retryErr.message}`);
-              }
-            }, 5000);
-          }
-          return;
-        }
-        
-        // 如果还有 ping 在等待响应，检查是否超时
-        if (pendingPingId) {
-          ctx.log?.debug?.(`[${account.accountId}] 心跳检测：等待 PONG 响应中...`);
-          return;
-        }
-        
-        // 主动发送 ping 消息
-        try {
-          const pingId = `ping_${Date.now()}`;
-          pendingPingId = pingId;
-          
-          // 通过 WebSocket 直接发送 ping（使用 SDK 的 socket）
-          client.socket?.ping(JSON.stringify({
-            type: 'PING',
-            id: pingId,
-            timestamp: Date.now()
-          }));
-          
-          ctx.log?.debug?.(`[${account.accountId}] 发送 PING 请求：${pingId}`);
-        } catch (err: any) {
-          ctx.log?.error?.(`[${account.accountId}] 发送 PING 失败：${err.message}`);
-          // 发送失败也计入超时
-        }
-      }, HEARTBEAT_INTERVAL);
+      // 启动 keepAlive 机制
+      const stopKeepAlive = socketManager.startKeepAlive();
       
       // 统一的停止逻辑
       const doStop = (reason: string) => {
@@ -3704,12 +3695,14 @@ const dingtalkPlugin = {
         stopped = true;
         ctx.log?.info(`[${account.accountId}] 停止钉钉 Stream 客户端 (${reason})...`);
         
-        // 清理心跳定时器
-        if (typeof heartbeatTimer !== 'undefined') {
-          clearInterval(heartbeatTimer);
-          ctx.log?.debug?.(`[${account.accountId}] 心跳定时器已清理`);
+        // 清理 keepAlive 定时器
+        if (typeof stopKeepAlive === 'function') {
+          stopKeepAlive();
         }
         
+        // 清理 SocketManager
+        socketManager.stop();
+        
         try {
           // 【关键】调用 disconnect() 正确关闭 WebSocket 连接
           client.disconnect();
@@ -4052,7 +4045,6 @@ const plugin = {
       respond(true, { docs });
     });
 
-    api.logger?.info('[DingTalk] 插件已注册（支持主动发送 AI Card 消息、文档读写）');
   },
 };
 

package/src/socket-manager.ts

@@ -0,0 +1,312 @@
+/**
+ * DingTalk WebSocket Socket 管理器
+ * 
+ * 负责管理 DingTalk Stream 客户端的 WebSocket 连接、心跳检测、自动重连等生命周期
+ */
+
+import type { DWClient } from 'dingtalk-stream';
+
+export interface SocketManagerOptions {
+  accountId: string;
+  log?: any;
+  stopped: () => boolean;
+  onReconnect?: () => void;
+  pendingAckQueue?: Set<string>;  // 待确认消息队列
+  client?: any;  // DWClient 实例，用于批量确认消息
+  debug?: boolean;  // 是否开启 debug 日志
+}
+
+export interface SocketManagerConfig {
+  /** 心跳间隔（毫秒） */
+  heartbeatInterval: number;
+  /** 超时阈值（毫秒） */
+  timeoutThreshold: number;
+  /** 基础退避时间（毫秒） */
+  baseBackoffDelay: number;
+  /** 最大退避时间（毫秒） */
+  maxBackoffDelay: number;
+}
+
+export interface SocketManager {
+  /** 启动 keepAlive 机制，返回清理函数 */
+  startKeepAlive: () => () => void;
+  /** 停止并清理所有资源 */
+  stop: () => void;
+}
+
+/**
+ * 创建 Socket 管理器
+ * 
+ * @param client - DingTalk Stream 客户端实例
+ * @param options - 配置选项
+ * @returns SocketManager 实例
+ */
+export function createSocketManager(
+  client: DWClient,
+  options: SocketManagerOptions
+): SocketManager {
+  const { accountId, log, stopped, onReconnect, pendingAckQueue: externalPendingAckQueue, client: externalClient, debug = false } = options;
+  
+  // 使用传入的 pendingAckQueue 或创建新的
+  const pendingAckQueue = externalPendingAckQueue || new Set<string>();
+  const targetClient = externalClient || client;
+  
+  // 【业界最佳实践配置】
+  const config: SocketManagerConfig = {
+    heartbeatInterval: 10 * 1000,      // 10 秒心跳间隔
+    timeoutThreshold: 90 * 1000,       // 90 秒超时阈值
+    baseBackoffDelay: 1000,            // 基础退避 1 秒
+    maxBackoffDelay: 30 * 1000,        // 最大退避 30 秒
+  };
+  
+  // 日志辅助函数
+  const debugLog = (...args: any[]) => {
+    if (debug && log) {
+      log?.info?.(...args);
+    }
+  };
+  
+  // 状态管理
+  let lastSocketAvailableTime = Date.now();
+  let isReconnecting = false;
+  let reconnectAttempts = 0;
+  
+  // 定时器引用
+  let keepAliveTimer: NodeJS.Timeout | null = null;
+  
+  /**
+   * 计算指数退避延迟（带抖动）
+   */
+  function calculateBackoffDelay(attempt: number): number {
+    const exponentialDelay = config.baseBackoffDelay * Math.pow(2, attempt);
+    const jitter = Math.random() * 1000;  // 0-1 秒随机抖动
+    return Math.min(exponentialDelay + jitter, config.maxBackoffDelay);
+  }
+  
+  /**
+   * 统一重连函数，带指数退避（无限重连）
+   */
+  async function doReconnect(immediate = false) {
+    if (isReconnecting) {
+      log?.debug?.(`[${accountId}] 正在重连中，跳过`);
+      return;
+    }
+    
+    isReconnecting = true;
+    
+    // 应用指数退避（非立即重连时）
+    if (!immediate && reconnectAttempts > 0) {
+      const delay = calculateBackoffDelay(reconnectAttempts);
+      log?.info?.(`[${accountId}] ⏳ 等待 ${Math.round(delay / 1000)} 秒后重连 (尝试 ${reconnectAttempts + 1})`);
+      await new Promise(resolve => setTimeout(resolve, delay));
+    }
+    
+    try {
+      // 1. 先断开旧连接（检查 WebSocket 状态）
+      if (client.socket?.readyState === 1 || client.socket?.readyState === 3) {
+        await client.disconnect();
+        log?.info?.(`[${accountId}] 已断开旧连接`);
+      }
+      
+      // 2. 重新建立连接
+      await client.connect();
+      
+      // 3. 重置 socket 可用时间和重连计数
+      lastSocketAvailableTime = Date.now();
+      reconnectAttempts = 0;  // 重连成功，重置计数
+      
+      log?.info?.(`[${accountId}] ✅ 重连成功`);
+      
+      // 调用外部回调
+      if (onReconnect) {
+        onReconnect();
+      }
+    } catch (err: any) {
+      reconnectAttempts++;
+      log?.error?.(`[${accountId}] 重连失败：${err.message} (尝试 ${reconnectAttempts})`);
+      throw err;
+    } finally {
+      isReconnecting = false;
+    }
+  }
+  
+  /**
+   * 监听 pong 响应（更新 socket 可用时间）
+   */
+  function setupPongListener() {
+    client.socket?.on('pong', () => {
+      lastSocketAvailableTime = Date.now();
+      log?.debug?.(`[${accountId}] 收到 PONG 响应`);
+    });
+  }
+  
+  /**
+   * 监听 WebSocket message 事件，收到 disconnect 消息时立即触发重连
+   */
+  function setupMessageListener() {
+    client.socket?.on('message', (data: any) => {
+      try {
+        const msg = JSON.parse(data);
+        if (msg.type === 'SYSTEM' && msg.headers?.topic === 'disconnect') {
+          if (!stopped() && !isReconnecting) {
+            // 立即重连，不退避
+            doReconnect(true).catch(err => {
+              log?.error?.(`[${accountId}] 重连失败：${err.message}`);
+            });
+          }
+        }
+      } catch (e) {
+        // 忽略解析错误
+      }
+    });
+  }
+  
+  /**
+   * 监听 WebSocket close 事件，服务端主动断开时立即触发重连
+   */
+  function setupCloseListener() {
+    client.socket?.on('close', (code, reason) => {
+      log?.info?.(`[${accountId}] WebSocket close: code=${code}, reason=${reason || '未知'}, stopped=${stopped()}`);
+      
+      if (stopped()) {
+        return;
+      }
+
+      // 立即重连，不退避
+      setTimeout(() => {
+        doReconnect(true).catch(err => {
+          log?.error?.(`[${accountId}] 重连失败：${err.message}`);
+        });
+      }, 0);
+    });
+  }
+  
+  /**
+   * 监听 WebSocket open 事件，批量确认重连期间积压的消息
+   */
+  function setupOpenListener() {
+    client.socket?.on('open', () => {
+      if (pendingAckQueue.size > 0) {
+        log?.info?.(`[${accountId}] WebSocket 已打开，批量确认 ${pendingAckQueue.size} 条积压消息`);
+        for (const msgId of pendingAckQueue) {
+          try {
+            targetClient.socketCallBackResponse(msgId, { success: true });
+            log?.info?.(`[DingTalk] 批量确认成功：messageId=${msgId}`);
+          } catch (err: any) {
+            log?.error?.(`[DingTalk] 批量确认失败：messageId=${msgId}, error=${err.message}`);
+          }
+        }
+        pendingAckQueue.clear();
+      }
+    });
+  }
+  
+  /**
+   * 启动 keepAlive 机制（单定时器 + 指数退避）
+   * 
+   * 业界最佳实践：
+   * - 单定时器：每 10 秒检查一次，同时完成心跳和超时检测
+   * - 使用 WebSocket 原生 Ping
+   * - 指数退避重连：避免雪崩效应
+   */
+  function startKeepAlive(): () => void {
+    debugLog(`[${accountId}] 🚀 启动 keepAlive 定时器，间隔=${config.heartbeatInterval / 1000}秒`);
+    
+    keepAliveTimer = setInterval(async () => {
+      if (stopped()) {
+        if (keepAliveTimer) clearInterval(keepAliveTimer);
+        return;
+      }
+      
+      try {
+        const elapsed = Date.now() - lastSocketAvailableTime;
+        
+        // 【超时检测】超过 90 秒未确认 socket 可用，触发重连
+        if (elapsed > config.timeoutThreshold) {
+          log?.info?.(`[${accountId}] ⚠️ 超时检测：已 ${Math.round(elapsed / 1000)} 秒未确认 socket 可用，触发重连...`);
+          await doReconnect();
+          return;
+        }
+        
+        // 【心跳检测】检查 socket 状态
+        const socketState = client.socket?.readyState;
+        debugLog(`[${accountId}] 🔍 心跳检测：socket 状态=${socketState}, elapsed=${Math.round(elapsed / 1000)}s`);
+        
+        if (socketState !== 1) {
+          log?.info?.(`[${accountId}] ⚠️ 心跳检测：socket 状态=${socketState}，触发重连...`);
+          await doReconnect(true);  // 立即重连，不退避
+          return;
+        }
+        
+        // 【发送原生 Ping】更新可用时间
+        try {
+          client.socket?.ping();
+          lastSocketAvailableTime = Date.now();
+          debugLog(`[${accountId}] 💓 发送 PING 心跳成功`);
+        } catch (err: any) {
+          log?.warn?.(`[${accountId}] 发送 PING 失败：${err.message}`);
+          // 发送失败也计入超时
+        }
+      } catch (err: any) {
+        log?.error?.(`[${accountId}] keepAlive 检测失败：${err.message}`);
+      }
+    }, config.heartbeatInterval);  // 每 10 秒检测一次
+    
+    debugLog(`[${accountId}] ✅ keepAlive 定时器已启动`);
+    
+    // 返回清理函数
+    return () => {
+      if (keepAliveTimer) clearInterval(keepAliveTimer);
+      keepAliveTimer = null;
+      debugLog(`[${accountId}] keepAlive 定时器已清理`);
+    };
+  }
+  
+  /**
+   * 停止并清理所有资源
+   */
+  function stop() {
+    // 清理定时器
+    if (keepAliveTimer) clearInterval(keepAliveTimer);
+    keepAliveTimer = null;
+    
+    // 清理事件监听器（WebSocket 会自动清理）
+    if (client.socket) {
+      client.socket.removeAllListeners();
+    }
+    
+    log?.debug?.(`[${accountId}] SocketManager 已停止`);
+  }
+  
+  // 初始化：设置所有事件监听器
+  setupPongListener();
+  setupMessageListener();
+  setupCloseListener();
+  setupOpenListener();
+  
+  return {
+    startKeepAlive,
+    stop,
+  };
+}
+
+/**
+ * 添加消息到待确认队列
+ */
+export function addToPendingAckQueue(queue: Set<string>, messageId: string) {
+  queue.add(messageId);
+}
+
+/**
+ * 从待确认队列移除消息
+ */
+export function removeFromPendingAckQueue(queue: Set<string>, messageId: string) {
+  queue.delete(messageId);
+}
+
+/**
+ * 清空待确认队列
+ */
+export function clearPendingAckQueue(queue: Set<string>) {
+  queue.clear();
+}