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

package/CHANGELOG.md

@@ -6,6 +6,38 @@
 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
+- 🐛 **AI 卡片模版与渲染优化** - 更新 AI 卡片模版 ID，使卡片样式与最新官方规范保持一致，并提升多终端展示效果  
+  **AI card template & rendering optimization** - Updated the AI card template ID to match the latest official standard and improved rendering across clients
+- 🐛 **Markdown 表格渲染修复** - 在发送到钉钉前自动为 Markdown 表格头部补充必要空行，避免因缺少空行导致表格被当作普通文本渲染  
+  **Markdown table rendering fix** - Automatically inserts required blank lines before Markdown table headers to prevent DingTalk from rendering tables as plain text
+- 🐛 **消息去重逻辑优化** - 将消息去重维度从「账号 + 消息 ID」简化为单一「消息 ID」，避免多账号场景下的重复处理或误判  
+  **Message de-duplication optimization** - Simplified de-duplication from `(accountId, messageId)` to `messageId` only, preventing duplicate handling or misjudgment in multi-account scenarios
+
+### 改进 / Improvements
+- ✅ **统一 Markdown 修正管道** - 对 AI 卡片流式内容、最终内容、普通 Markdown 消息及 `sampleMarkdown` 卡片文本统一应用 Markdown 修正规则，确保表格等格式在各入口行为一致  
+  **Unified Markdown normalization pipeline** - Applies the same Markdown normalization to streaming AI card content, final content, regular Markdown messages, and `sampleMarkdown` card text for consistent behavior
+- ✅ **AI 卡片状态内容一致性** - 在完成 AI 卡片时，对展示内容和写入 `cardParamMap.msgContent` 的内容使用同一份 Markdown 修正结果，确保用户看到的内容与内部状态一致  
+  **Consistent AI card status content** - Ensures the same normalized Markdown is used both for the visible content and `cardParamMap.msgContent` when finishing AI cards
+
 ## [0.7.7] - 2026-03-13
 
 ### 新增 / Added

package/docs/RELEASE_NOTES_V0.7.8.md

@@ -0,0 +1,101 @@
+# Release Notes - v0.7.8
+
+## ✨ 功能与体验改进 / Features & Improvements
+
+- **AI 卡片模版更新与展示效果优化 / AI Card Template & Rendering Improvements**  
+  升级钉钉 AI 卡片模版 ID，使卡片样式与最新官方规范保持一致，并优化多终端的展示效果与兼容性。  
+  Updated the DingTalk AI card template ID to align with the latest official template standard, improving visual consistency and compatibility across different clients.
+
+- **Markdown 表格渲染修复与自动优化 / Markdown Table Rendering Fix & Auto-Adjustment**  
+  新增 Markdown 预处理逻辑，在发送到钉钉前自动为表格头部补充必要的空行，避免因缺少空行导致的表格无法正确渲染问题；支持缩进表格场景。  
+  Added a Markdown preprocessing step that automatically inserts a blank line before table headers when needed, ensuring DingTalk renders tables correctly, including indented table cases.
+
+- **统一的 Markdown 修正管道 / Unified Markdown Normalization Pipeline**  
+  对 AI 卡片流式更新、AI 卡片最终内容提交、普通 Markdown 消息发送以及卡片 `sampleMarkdown` 内容，统一通过同一套 Markdown 修正函数进行处理，确保所有下发到钉钉的文本在表格渲染等细节上行为一致。  
+  Unified the Markdown normalization logic used for streaming AI card updates, final AI card content, regular Markdown messages, and `sampleMarkdown` card payloads, ensuring consistent behavior of table rendering and formatting in DingTalk.
+
+- **AI 卡片状态信息更准确 / More Accurate AI Card Status Content**  
+  在完成 AI 卡片时，对用于展示的内容与写入 `cardParamMap` 中的 `msgContent` 同步应用 Markdown 修正逻辑，保证用户看到的内容与卡片内部状态字段保持完全一致。  
+  When finalizing AI cards, the same Markdown fixes are now applied both to the displayed content and the `msgContent` stored in `cardParamMap`, keeping the visible card and its internal state in sync.
+
+## 🐛 修复 / Fixes
+
+- **Markdown 表格无法正确显示的问题 / Incorrect Markdown Table Rendering**  
+  修复了部分场景下 Markdown 表格前缺少空行，导致钉钉不将其识别为表格而当作普通文本渲染的问题；现在会自动检测表头与分隔行模式并在需要时插入空行。  
+  Fixed an issue where missing blank lines before Markdown tables caused DingTalk to render them as plain text; the connector now detects table headers and divider lines and inserts a blank line when necessary.
+
+- **消息去重维度优化 / Message De-duplication Scope Optimization**  
+  优化消息去重逻辑，从「按账号+消息 ID」改为仅基于「消息 ID」维度标记与判断，避免在多账号场景中出现某些重复消息未被正确拦截或误判的情况。  
+  Improved the message de-duplication mechanism by switching from an account-scoped `(accountId, messageId)` key to a global `messageId` key, preventing edge cases where duplicate messages across accounts might not be handled correctly.
+
+## 📋 技术细节 / Technical Details
+
+### AI 卡片模版 & 内容处理 / AI Card Template & Content Handling
+
+- 更新 `AI_CARD_TEMPLATE_ID` 为新的模版 ID，以匹配最新的钉钉 AI 卡片样式规范。  
+- 新增 `ensureTableBlankLines(text: string)` 工具函数：  
+  - 将文本按行拆分，识别包含竖线的表格行与 `---` 分隔行。  
+  - 当前行看起来像表头、下一行是分隔行、且前一行既不是空行也不是表格行时，会在表头前插入一个空行。  
+  - 支持带缩进的表格写法，保持原有内容顺序与缩进风格不变。  
+- 在以下路径中统一使用 `ensureTableBlankLines`：  
+  - AI 卡片流式内容更新（`streamAICard`）中的 `content` 字段。  
+  - AI 卡片结束时（`finishAICard`）的最终内容与日志长度统计。  
+  - 普通 Markdown 消息发送（`sendMarkdownMessage`），在追加 `@user` 之前先做表格修正。  
+  - `buildMsgPayload` 中 `sampleMarkdown` 类型的 `text` 字段。  
+- 为单元测试导出 `__testables.ensureTableBlankLines`，便于在不依赖具体业务逻辑的情况下验证 Markdown 修正规则。
+
+### 消息去重逻辑 / Message De-duplication Logic
+
+- 去重检查由 `isMessageProcessed(accountId, messageId)` 简化为 `isMessageProcessed(messageId)`，对同一消息 ID 统一判重。  
+- 标记逻辑由 `markMessageProcessed(accountId, messageId)` 更新为 `markMessageProcessed(messageId)`，减少多账号场景下可能出现的重复处理路径。  
+- 保持原有日志信息与跳过处理分支不变，仅调整内部去重键值结构。
+
+## 📥 安装升级 / 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
+
+### 兼容性说明 / Compatibility Notes
+
+- **向下兼容 / Backward Compatible**：本次为小版本修复和体验优化更新，在保留 v0.7.x 既有行为的前提下增强了 Markdown 表格渲染与消息去重逻辑，对现有配置完全兼容。  
+- **Markdown 表格渲染更稳定 / More Robust Markdown Tables**：即便原始内容中未严格遵守表格前空行的写法，Connector 也会自动做最小化修正，以提高在钉钉中的可读性。  
+- **消息去重语义更清晰 / Clearer De-duplication Semantics**：以 `messageId` 为唯一维度进行去重，更贴合钉钉消息唯一标识的语义。
+
+### 验证步骤 / Verification Steps
+
+升级到此版本后，建议进行以下验证：
+
+1. **AI 卡片模版与渲染验证 / AI Card Template & Rendering Verification**  
+   - 触发一次典型的 AI 卡片对话，观察新模版下的卡片布局与字段展示是否符合预期。  
+   - 在含有多段文字与表格的回复中，确认卡片内 Markdown 表格渲染正常。  
+
+2. **Markdown 表格兼容性验证 / Markdown Table Compatibility Verification**  
+   - 通过机器人发送包含 Markdown 表格的消息（包含表头、分隔行与多列数据），且故意在表格前省略空行。  
+   - 在移动端及 PC 端查看，确认钉钉能够正确以表格形式渲染内容。  
+
+3. **消息去重行为验证 / Message De-duplication Behavior Verification**  
+   - 在相同会话中模拟重复推送同一个 `messageId` 的回调（或快速重复发送同一条消息）。  
+   - 确认日志中出现去重命中提示，并且业务处理逻辑只执行一次。
+
+## 🔗 相关链接 / 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.8  
+**兼容性 / Compatibility**：OpenClaw Gateway 0.4.0+
+

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.7",
+  "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.7",
+  "version": "0.7.9",
   "description": "DingTalk (钉钉) channel connector — Stream mode with AI Card streaming",
   "main": "plugin.ts",
   "type": "module",

package/plugin.ts

@@ -1103,7 +1103,7 @@ async function processFileMarkers(
 
 const DINGTALK_API = 'https://api.dingtalk.com';
 const DINGTALK_OAPI = 'https://oapi.dingtalk.com';
-const AI_CARD_TEMPLATE_ID = '382e4302-551d-4880-bf29-a30acfab2e71.schema';
+const AI_CARD_TEMPLATE_ID = '02fcf2f4-5e02-4a85-b672-46d1f715543e.schema';
 
 // flowStatus 值与 Python SDK AICardStatus 一致（cardParamMap 的值必须是字符串）
 const AICardStatus = {
@@ -1141,6 +1141,45 @@ async function createAICard(
   return createAICardForTarget(config, target, log);
 }
 
+/**
+ * 确保 Markdown 表格前有空行，否则钉钉无法正确渲染表格。
+ *
+ * 逐行向前看：当前行像表头（含 `|`）且下一行是分隔行时，
+ * 若前一行非空且非表格行，则在表头前插入空行。
+ * 支持缩进表格（行首有空白字符）。
+ */
+function ensureTableBlankLines(text: string): string {
+  const lines = text.split('\n');
+  const result: string[] = [];
+
+  // 匹配表格分隔行 (例如 | --- | --- | 或 --- | ---)
+  const tableDividerRegex = /^\s*\|?\s*:?-+:?\s*(\|?\s*:?-+:?\s*)+\|?\s*$/;
+  // 匹配包含竖线的表格行
+  const tableRowRegex = /^\s*\|?.*\|.*\|?\s*$/;
+
+  const isDivider = (line: string) => line.includes('|') && tableDividerRegex.test(line);
+
+  for (let i = 0; i < lines.length; i++) {
+    const currentLine = lines[i];
+    const nextLine = lines[i + 1] ?? '';
+
+    // 逻辑：
+    // 1. 当前行看起来像表头（包含 |）
+    // 2. 下一行是分隔行（---）
+    // 3. 前一行不是空行且不是表格行
+    if (
+      tableRowRegex.test(currentLine) &&
+      isDivider(nextLine) &&
+      i > 0 && lines[i - 1].trim() !== '' && !tableRowRegex.test(lines[i - 1])
+    ) {
+      result.push('');
+    }
+
+    result.push(currentLine);
+  }
+  return result.join('\n');
+}
+
 // 流式更新 AI Card 内容
 async function streamAICard(
   card: AICardInstance,
@@ -1177,11 +1216,12 @@ async function streamAICard(
   }
 
   // 调用 streaming API 更新内容
+  const fixedContent = ensureTableBlankLines(content);
   const body = {
     outTrackId: card.cardInstanceId,
     guid: `${Date.now()}_${Math.random().toString(36).slice(2, 8)}`,
     key: 'msgContent',
-    content: content,
+    content: fixedContent,
     isFull: true,  // 全量替换
     isFinalize: finished,
     isError: false,
@@ -1205,10 +1245,11 @@ async function finishAICard(
   content: string,
   log?: any,
 ): Promise<void> {
-  log?.info?.(`[DingTalk][AICard] 开始 finish，最终内容长度=${content.length}`);
+  const fixedContent = ensureTableBlankLines(content);
+  log?.info?.(`[DingTalk][AICard] 开始 finish，最终内容长度=${fixedContent.length}`);
 
   // 1. 先用最终内容关闭流式通道（isFinalize=true），确保卡片显示替换后的内容
-  await streamAICard(card, content, true, log);
+  await streamAICard(card, fixedContent, true, log);
 
   // 2. 更新卡片状态为 FINISHED
   const body = {
@@ -1216,7 +1257,7 @@ async function finishAICard(
     cardData: {
       cardParamMap: {
         flowStatus: AICardStatus.FINISHED,
-        msgContent: content,
+        msgContent: fixedContent,
         staticMsgContent: '',
         sys_full_json_obj: JSON.stringify({
           order: ['msgContent'],  // 只声明实际使用的字段，避免部分客户端显示空占位
@@ -1698,7 +1739,7 @@ async function sendMarkdownMessage(
   options: any = {},
 ): Promise<any> {
   const token = await getAccessToken(config);
-  let text = markdown;
+  let text = ensureTableBlankLines(markdown);
   if (options.atUserId) text = `${text} @${options.atUserId}`;
 
   const body: any = {
@@ -2235,7 +2276,7 @@ function buildMsgPayload(
         msgKey: 'sampleMarkdown',
         msgParam: {
           title: title || content.split('\n')[0].replace(/^[#*\s\->]+/, '').slice(0, 20) || 'Message',
-          text: content,
+          text: ensureTableBlankLines(content),
         },
       };
     case 'link':
@@ -3510,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) => {
@@ -3532,15 +3573,15 @@ const dingtalkPlugin = {
           ctx.log?.info?.(`[DingTalk] 已立即确认回调: messageId=${messageId}`);
         }
 
-        // 【消息去重】检查是否已处理过该消息（按账号维度隔离）
-        if (messageId && isMessageProcessed(account.accountId, messageId)) {
+        // 【消息去重】检查是否已处理过该消息
+        if (messageId && isMessageProcessed(messageId)) {
           ctx.log?.warn?.(`[DingTalk][${account.accountId}] 检测到重复消息，跳过处理: messageId=${messageId}`);
           return;
         }
 
-        // 标记消息为已处理（按账号维度隔离）
+        // 标记消息为已处理
         if (messageId) {
-          markMessageProcessed(account.accountId, messageId);
+          markMessageProcessed(messageId);
         }
 
         // 异步处理消息（不阻塞回调确认）
@@ -3570,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');
       };
@@ -3939,6 +4074,8 @@ export {
 // ============ 测试辅助导出 ============
 // 仅用于单元测试，避免在业务代码中直接依赖内部实现细节
 export const __testables = {
+  // Markdown 修正
+  ensureTableBlankLines,
   // 会话 & 去重
   normalizeSlashCommand,
   buildSessionContext,