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

package/CHANGELOG.md

@@ -6,6 +6,22 @@
 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/).
 
+## [0.7.9] - 2026-03-13
+
+### 新增 / Added
+- ✨ **应用层心跳机制** - 钉钉 Stream 客户端使用自定义心跳（WebSocket ping/pong，30 秒间隔、90 秒超时），超时后主动断开并重连，重连失败 5 秒后重试  
+  **Application-layer heartbeat** - Stream client uses custom ping/pong heartbeat (30s interval, 90s timeout), reconnects on timeout with 5s retry on failure
+- ✨ **统一停止与清理** - 停止客户端时通过 `doStop` 统一清理心跳定时器并调用 `client.disconnect()`，确保连接正确关闭  
+  **Unified stop & cleanup** - `doStop` clears heartbeat timer and calls `client.disconnect()` when stopping the client
+
+### 修复 / Fixes
+- 🐛 **长连接静默断开** - 关闭 SDK 激进 keepAlive（8 秒超时），改用应用层心跳，减少因长时间无数据导致的静默断连且无法恢复  
+  **Long-lived connection silent disconnect** - Disabled SDK aggressive keepAlive (8s timeout), use app-layer heartbeat to reduce silent disconnects when idle
+
+### 改进 / Improvements
+- ✅ **DWClient 配置** - 启用 `autoReconnect: true`，设置 `keepAlive: false`，由应用层心跳替代 SDK 心跳，避免与钉钉服务端策略冲突  
+  **DWClient config** - `autoReconnect: true`, `keepAlive: false`; app-layer heartbeat replaces SDK keepAlive to avoid conflicts with server
+
 ## [0.7.8] - 2026-03-13
 
 ### 修复 / Fixes

package/docs/RELEASE_NOTES_V0.7.9.md

@@ -0,0 +1,65 @@
+# Release Notes - v0.7.9
+
+## ✨ 功能与体验改进 / Features & Improvements
+
+- **钉钉 Stream 客户端心跳与重连机制优化 / DingTalk Stream Client Heartbeat & Reconnect**  
+  关闭 DWClient SDK 内置的激进 keepAlive（避免 8 秒超时强制断连），启用应用层自定义心跳：基于 WebSocket ping/pong，30 秒间隔、90 秒超时，超时后主动断开并重连，重连失败时 5 秒后重试，提升长连稳定性。  
+  Disabled the SDK's aggressive keepAlive (which could force disconnect after 8s), and added an application-layer heartbeat: WebSocket ping/pong with 30s interval and 90s timeout; on timeout the client disconnects and reconnects, with a 5s retry on failure, improving long-lived connection stability.
+
+- **DWClient 配置调整 / DWClient Configuration**  
+  启用 `autoReconnect: true` 以在连接断开时自动重连；设置 `keepAlive: false`，由应用层心跳替代 SDK 心跳，避免与钉钉服务端策略冲突。  
+  Enabled `autoReconnect: true` for automatic reconnection on disconnect; set `keepAlive: false` and rely on application-layer heartbeat to avoid conflicts with DingTalk server behavior.
+
+- **统一停止与清理逻辑 / Unified Stop & Cleanup**  
+  停止 Stream 客户端时统一通过 `doStop` 清理心跳定时器并调用 `client.disconnect()`，确保资源释放与连接正确关闭。  
+  When stopping the Stream client, a unified `doStop` now clears the heartbeat timer and calls `client.disconnect()` for consistent resource cleanup and connection closure.
+
+## 🐛 修复 / Fixes
+
+- **长连接被服务端或中间网络提前断开 / Long-lived Connection Premature Disconnect**  
+  通过应用层心跳检测连接活性，超时后主动重连，减少因长时间无数据导致的静默断连且无法恢复的问题。  
+  Application-layer heartbeat detects connection liveness and triggers reconnect on timeout, reducing silent disconnects when the link is idle.
+
+## 📋 技术细节 / Technical Details
+
+### 应用层心跳机制 / Application-Layer Heartbeat
+
+- **参数**：心跳间隔 30 秒（`HEARTBEAT_INTERVAL`），超时 90 秒（`HEARTBEAT_TIMEOUT`），允许约 3 次 ping 无响应后再判定超时。  
+- **流程**：定时器每 30 秒通过 `client.socket?.ping()` 发送 ping；监听 `socket.on('pong')` 更新 `lastPongTime`；若当前时间与 `lastPongTime` 差值超过 90 秒则触发重连。  
+- **重连**：先 `await client.disconnect()`，再 `await client.connect()`，成功后重置 `lastPongTime`；若重连失败则 5 秒后再次尝试 `client.connect()`。  
+- **停止**：`doStop(reason)` 中设置 `stopped = true`、清除心跳定时器、调用 `client.disconnect()`，并记录停止原因与活动。
+
+### DWClient 配置说明 / DWClient Config
+
+- `autoReconnect: true` — 连接断开时由 SDK 参与自动重连。  
+- `keepAlive: false` — 关闭 SDK 内置的激进心跳，避免 8 秒无活动即强制断连，由应用层 30s/90s 心跳替代。
+
+## 📥 安装升级 / 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
+```
+
+## ⚠️ 升级注意事项 / Upgrade Notes
+
+- **向下兼容 / Backward Compatible**：仅调整 Stream 客户端的心跳与重连策略，对现有配置与 API 无破坏性变更。  
+- **长连场景建议**：若依赖钉钉 Stream 长连接，升级后将自动使用新的心跳与重连逻辑，无需额外配置。
+
+## 🔗 相关链接 / 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)
+- [问题反馈 / Issue Feedback](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/issues)
+
+---
+
+**发布日期 / Release Date**：2026-03-13  
+**版本号 / Version**：v0.7.9  
+**兼容性 / Compatibility**：OpenClaw Gateway 0.4.0+

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "dingtalk-connector",
   "name": "DingTalk Channel",
-  "version": "0.7.8",
+  "version": "0.7.9",
   "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.8",
+  "version": "0.7.9",
   "description": "DingTalk (钉钉) channel connector — Stream mode with AI Card streaming",
   "main": "plugin.ts",
   "type": "module",

package/plugin.ts

@@ -3551,15 +3551,15 @@ const dingtalkPlugin = {
 
       ctx.log?.info(`[${account.accountId}] 启动钉钉 Stream 客户端...`);
 
-      // 启用 DWClient 内置的 autoReconnect 和 keepAlive
+      // 配置 DWClient：关闭 SDK 内置的 keepAlive，使用应用层自定义心跳
       // - autoReconnect: 连接断开时自动重连
-      // - keepAlive: 启用心跳机制，防止服务端因长时间无活动而断开连接
+      // - keepAlive: false（关闭 SDK 的激进心跳检测，避免 8 秒超时强制终止连接）
       const client = new DWClient({
         clientId: config.clientId,
         clientSecret: config.clientSecret,
         debug: config.debug || false,
         autoReconnect: true,
-        keepAlive: true,
+        keepAlive: false,
       } as any);
 
       client.registerCallbackListener(TOPIC_ROBOT, async (res: any) => {
@@ -3611,16 +3611,110 @@ 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 秒
+      
+      // 监听 pong 响应（SDK 的 keepAlive=false 时仍然会收到服务端的 pong）
+      client.socket?.on('pong', () => {
+        lastPongTime = Date.now();
+        pendingPingId = null;
+        ctx.log?.debug?.(`[${account.accountId}] 收到 PONG 响应`);
+      });
+      
+      // 启动心跳检测定时器
+      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);
+      
       // 统一的停止逻辑
       const doStop = (reason: string) => {
         if (stopped) return;
         stopped = true;
         ctx.log?.info(`[${account.accountId}] 停止钉钉 Stream 客户端 (${reason})...`);
+        
+        // 清理心跳定时器
+        if (typeof heartbeatTimer !== 'undefined') {
+          clearInterval(heartbeatTimer);
+          ctx.log?.debug?.(`[${account.accountId}] 心跳定时器已清理`);
+        }
+        
         try {
           // 【关键】调用 disconnect() 正确关闭 WebSocket 连接
           client.disconnect();
         } catch (err: any) {
-          ctx.log?.warn?.(`[${account.accountId}] 断开连接时出错: ${err.message}`);
+          ctx.log?.warn?.(`[${account.accountId}] 断开连接时出错：${err.message}`);
         }
         rt.channel.activity.record('dingtalk-connector', account.accountId, 'stop');
       };