@dingtalk-real-ai/dingtalk-connector 0.8.20 → 0.8.21

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "dingtalk-connector",
   "name": "DingTalk Channel",
-  "version": "0.8.20",
+  "version": "0.8.21",
   "description": "Official OpenClaw DingTalk channel plugin | 钉钉官方 OpenClaw 插件",
   "author": "DingTalk Real Team",
   "main": "index.ts",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dingtalk-real-ai/dingtalk-connector",
-  "version": "0.8.20",
+  "version": "0.8.21",
   "description": "Official OpenClaw DingTalk channel plugin | 钉钉官方 OpenClaw 插件",
   "type": "module",
   "exports": {

package/src/core/connection.ts

@@ -3,7 +3,7 @@
  *
  * 职责：
  * - 管理单个钉钉账号的 WebSocket 连接
- * - 实现应用层心跳检测（10 秒间隔，90 秒超时）
+ * - 实现应用层心跳检测（10 秒间隔，20 秒超时）
  * - 处理连接重连逻辑，带指数退避
  * - 消息去重（内置 Map，5 分钟 TTL）
  *
@@ -64,6 +64,48 @@ const BASE_BACKOFF_DELAY = 1000; // 1 秒
 /** 最大退避时间（毫秒） */
 const MAX_BACKOFF_DELAY = 30 * 1000; // 30 秒
 
+// ============ 上游 SDK 噪音抑制 ============
+//
+// 背景（#571 / #536 / #573）：
+// 上游 SDK `dingtalk-stream@2.1.4`（client.cjs:138 / :185）在连接建立和断开时
+// 直接调用 `console.info(...)`，输出 `Disconnecting.` / `[time] connect success`
+// 两条字符串。任何触发 `client.disconnect()` + `client.connect()` 的链路
+// （网络抖动、服务端下发 disconnect topic、connector 主动重连等）都会让这两
+// 条日志成对出现，绕过本插件 logger，给运维造成"故障"误判。
+//
+// 这里在模块加载时一次性 patch `console.info`，**只过滤这两条精确字符串**，
+// 其他 console.info 不受影响。connector 自己在 `doReconnect` 流程中通过
+// `logger.info` 输出更友好的连接生命周期日志（受 debug 配置控制）。
+//
+// 此函数不动 keepAlive 心跳逻辑、不动 lastSocketAvailableTime 写入时机、
+// 不动 setupPongListener。
+let _streamNoiseSilenced = false;
+function silenceDingtalkStreamConsoleNoise(): void {
+  if (_streamNoiseSilenced) return;
+  _streamNoiseSilenced = true;
+  const origConsoleInfo = console.info.bind(console);
+  console.info = (...args: any[]) => {
+    const first = args[0];
+    if (typeof first === "string") {
+      if (first === "Disconnecting.") return;
+      if (/^\[[^\]]+\] connect success$/.test(first)) return;
+    }
+    return origConsoleInfo(...args);
+  };
+}
+
+// 一次性提示：解释 SDK console.info 噪音的来源与重连预期，避免多 bot 启动时重复
+let _connectionNoticePrinted = false;
+function printConnectionNoticeOnce(): void {
+  if (_connectionNoticePrinted) return;
+  _connectionNoticePrinted = true;
+  console.log(
+    "[dingtalk-connector] ℹ️  上游 dingtalk-stream SDK 的 `Disconnecting.` / " +
+      "`connect success` 日志已由本插件过滤；真实重连（网络抖动、服务端推 disconnect 等）" +
+      "由 connector 自动处理。正常运行下不应看到高频（≤30s）周期性重连，如有请提 issue。",
+  );
+}
+
 // ============ 监控账号 ============
 
 export async function monitorSingleAccount(
@@ -72,6 +114,11 @@ export async function monitorSingleAccount(
   const { cfg, account, runtime, abortSignal, messageHandler, onStatusChange } = opts;
   const { accountId } = account;
 
+  // 在 dingtalk-stream SDK 被动态 import 之前抑制其 console.info 噪音
+  // （#571 / #536 / #573：SDK 在每次 connect/disconnect 时直接 console.info，
+  // 在频繁重连场景下会刷屏）
+  silenceDingtalkStreamConsoleNoise();
+
   // 保存 cfg 以便传递给 messageHandler
   const clawdbotConfig = cfg;
   const log = runtime?.log;
@@ -166,25 +213,26 @@ export async function monitorSingleAccount(
   
   /**
    * 标记消息处理开始，启动定期更新机制
-   * 在消息处理期间，每 30 秒更新一次 lastSocketAvailableTime
+   * 在消息处理期间，定时刷新 lastSocketAvailableTime
    * 防止长时间处理（如复杂的 AI 任务）触发心跳超时
    */
   function markMessageProcessingStart() {
     activeMessageProcessing = true;
     lastSocketAvailableTime = Date.now();
-    
+
     // 清理旧的定时器（如果存在）
     if (messageProcessingKeepAliveTimer) {
       clearInterval(messageProcessingKeepAliveTimer);
     }
-    
-    // 每 30 秒更新一次，确保不会触发 90 秒超时
+
+    // 每 15 秒更新一次（< TIMEOUT_THRESHOLD = 20s），保证 AI 长任务期间不会
+    // 因为 elapsed 超过 20 秒触发 keepAlive 兜底重连
     messageProcessingKeepAliveTimer = setInterval(() => {
       if (activeMessageProcessing) {
         lastSocketAvailableTime = Date.now();
         logger.debug(`📝 消息处理中，更新 socket 可用时间`);
       }
-    }, 30 * 1000); // 30 秒间隔
+    }, 15 * 1000); // 15 秒间隔
     
     logger.debug(`📝 消息处理开始，启动活跃标记定时器`);
   }
@@ -242,6 +290,12 @@ export async function monitorSingleAccount(
       // 2. 重新建立连接
       await client.connect();
 
+      // 立即注册 socket 事件监听器，避免在等待 OPEN 期间错过 pong/message/close 事件
+      // （keepAlive 期间发的 ping，如果 pong 回来时 listener 还没挂，会被丢，最坏踩到 TIMEOUT_THRESHOLD 边界）
+      setupPongListener();
+      setupMessageListener();
+      setupCloseListener();
+
       // 3. 等待连接真正建立（监听 open 事件，最多等待 10 秒）
       const connectionEstablished = await new Promise<boolean>((resolve) => {
         const timeout = setTimeout(() => {
@@ -313,6 +367,9 @@ export async function monitorSingleAccount(
       try {
         const msg = JSON.parse(data);
         if (msg.type === "SYSTEM" && msg.headers?.topic === "disconnect") {
+          // 钉钉服务端在 LB / 实例切换等场景下可能下发 disconnect topic，
+          // 客户端需立即断开重连；这是协议机制，非故障
+          logger.debug(`收到服务端 disconnect topic，即将重连`);
           if (!isStopped && !isReconnecting) {
             // 立即重连，不退避
             doReconnect(true).catch((err) => {
@@ -371,7 +428,7 @@ export async function monitorSingleAccount(
       try {
         const elapsed = Date.now() - lastSocketAvailableTime;
 
-        // 【超时检测】超过 90 秒未确认 socket 可用，触发重连
+        // 【超时检测】超过 TIMEOUT_THRESHOLD（当前 20s = 2 次心跳未响应），触发重连
         if (elapsed > TIMEOUT_THRESHOLD) {
           logger.info(
             `⚠️ 超时检测：已 ${Math.round(elapsed / 1000)} 秒未确认 socket 可用，触发重连...`,
@@ -449,11 +506,6 @@ export async function monitorSingleAccount(
     logger.debug(`Connection 已停止`);
   }
 
-  // 初始化：设置所有事件监听器
-  setupPongListener();
-  setupMessageListener();
-  setupCloseListener();
-
   return new Promise<void>(async (resolve, reject) => {
     // Handle abort signal
     if (abortSignal) {
@@ -638,12 +690,22 @@ export async function monitorSingleAccount(
     // Connect to DingTalk Stream
     try {
       await client.connect();
+
+      // 注册 socket 事件监听器（必须在 connect 后，此时 client.socket 已创建）
+      setupPongListener();
+      setupMessageListener();
+      setupCloseListener();
+
       logger.info(`Connected to DingTalk Stream successfully`);
       logger.info(`PID: ${process.pid}`);
       logger.info(
-        `✅ 自定义 keepAlive: true (10 秒心跳，90 秒超时), 指数退避重连`,
+        `✅ 自定义 keepAlive: true (10 秒心跳，20 秒超时), 指数退避重连`,
       );
 
+      // 首个账号连上时，打印一次连接生命周期说明，解释 SDK console.info 噪音
+      // 的来源以及"高频重连不正常"的预期（#571 / #536 / #573）
+      printConnectionNoticeOnce();
+
       // 初次连接成功，向框架报告 connected: true
       onStatusChange?.({ connected: true, lastConnectedAt: Date.now() });
 

package/src/core/message-handler.ts

@@ -56,6 +56,10 @@ import { createAICardForTarget, streamAICard, type AICardInstance } from "../ser
 import { QUEUE_BUSY_ACK_PHRASES } from "../utils/constants.ts";
 import { createDingtalkReplyDispatcher } from "../reply-dispatcher.ts";
 import { normalizeSlashCommand } from "../utils/session.ts";
+import {
+  pickEmptyReplyFallbackText,
+  emptyGroupReplyLogHint,
+} from "../utils/empty-reply.ts";
 import { getDingtalkRuntime } from "../runtime.ts";
 import { dingtalkHttp } from '../utils/http-client.ts';
 import { createLoggerFromConfig } from '../utils/index.ts';
@@ -1573,7 +1577,17 @@ export async function handleDingTalkMessageInternal(params: HandleMessageParams)
           );
         }
 
-        const textToSend = finalText.trim() || '✅ 任务执行完成（无文本输出）';
+        // ✅ 异步模式下 final 文本为空时的兜底
+        // 群聊场景下，常见根因是 OpenClaw `messages.groupChat.visibleReplies` 未设为 "automatic"
+        // （详见 src/utils/empty-reply.ts），给运维一份可操作的指引而不是无信息量的「任务执行完成」。
+        let textToSend = finalText.trim();
+        if (!textToSend) {
+          const isGroup = !isDirect;
+          textToSend = pickEmptyReplyFallbackText(isGroup);
+          if (isGroup) {
+            log?.warn?.(`[DingTalk][asyncMode] ${emptyGroupReplyLogHint()}`);
+          }
+        }
         const title =
           textToSend.split('\n')[0]?.replace(/^[#*\s\->]+/, '').trim() || '消息';
         await sendProactive(config, proactiveTarget, textToSend, {

package/src/reply-dispatcher.ts

@@ -47,6 +47,11 @@ import {
   processAudioMarkers,
   uploadAndReplaceFileMarkers,
 } from "./services/media/index.ts";
+import {
+  pickEmptyReplyFallbackText,
+  emptyGroupReplyLogHint,
+  groupChatLacksVisibleRepliesAutomatic,
+} from "./utils/empty-reply.ts";
 
 
 export type CreateDingtalkReplyDispatcherParams = {
@@ -93,7 +98,12 @@ export function createDingtalkReplyDispatcher(params: CreateDingtalkReplyDispatc
   let currentCardTarget: AICardTarget | null = null;
   let accumulatedText = "";
   const deliveredFinalTexts = new Set<string>();
-  
+
+  /** 本轮是否已向用户发出过可见回复（final / 流式更新 / 错误兜底等） */
+  let outboundUserVisibleThisTurn = false;
+  /** 防止 onIdle / onError 重复发送 visibleReplies 配置指引 */
+  let idleConfigNudgeSent = false;
+
   // 异步模式：累积完整响应
   let asyncModeFullResponse = "";
 
@@ -161,6 +171,7 @@ export function createDingtalkReplyDispatcher(params: CreateDingtalkReplyDispatc
       );
       deliveredErrorTypes.add(errorKey);
       lastErrorTime = now;
+      outboundUserVisibleThisTurn = true;
       log.info(`[DingTalk][Fallback] ✅ 错误消息发送成功`);
     } catch (fallbackErr: any) {
       log.error(`[DingTalk][Fallback] ❌ 错误消息发送失败：${fallbackErr.message}`);
@@ -238,6 +249,7 @@ export function createDingtalkReplyDispatcher(params: CreateDingtalkReplyDispatc
         log.info(`[DingTalk][startStreaming] 复用预创建 AI Card，cardInstanceId=${preCreatedCard.cardInstanceId}`);
         currentCardTarget = preCreatedCard as any;
         accumulatedText = "";
+        outboundUserVisibleThisTurn = true;
         return;
       }
 
@@ -294,9 +306,17 @@ export function createDingtalkReplyDispatcher(params: CreateDingtalkReplyDispatc
       let finalText = accumulatedText;
       
       // ✅ 如果累积的文本为空，使用默认提示文案
+      // 群聊场景下，常见根因是 OpenClaw `messages.groupChat.visibleReplies` 未设为
+      // "automatic"（上游 source-reply-delivery-mode.ts 走 message_tool_only 时
+      // 会跳过 onPartialReply，accumulatedText 始终为空）。给运维一份可操作的指引，
+      // 而不是一句无信息量的「任务执行完成」。详见 src/utils/empty-reply.ts。
       if (!finalText.trim()) {
-        finalText = '✅ 任务执行完成（无文本输出）';
-        log.info(`[DingTalk][closeStreaming] 累积文本为空，使用默认提示文案`);
+        const isGroup = !isDirect;
+        finalText = pickEmptyReplyFallbackText(isGroup);
+        log.info(`[DingTalk][closeStreaming] 累积文本为空，使用默认提示文案 (isGroup=${isGroup})`);
+        if (isGroup) {
+          log.warn?.(`[DingTalk][closeStreaming] ${emptyGroupReplyLogHint()}`);
+        }
       }
       
       // 获取 oapiToken 用于媒体处理
@@ -402,6 +422,7 @@ export function createDingtalkReplyDispatcher(params: CreateDingtalkReplyDispatc
         account.config as DingtalkConfig,
         log
       );
+      outboundUserVisibleThisTurn = true;
       log.info(`[DingTalk][closeStreaming] ✅ AI Card 关闭成功`);
     } catch (error: any) {
       log.error(`[DingTalk][closeStreaming] ❌ AI Card 关闭失败：${error?.message || String(error)}`);
@@ -421,6 +442,7 @@ export function createDingtalkReplyDispatcher(params: CreateDingtalkReplyDispatc
               log: params.runtime.log,
             }
           );
+          outboundUserVisibleThisTurn = true;
           log.info(`[DingTalk][closeStreaming] ✅ 降级发送成功`);
         } catch (sendErr: any) {
           log.error(`[DingTalk][closeStreaming] ❌ 降级发送失败：${sendErr.message}`);
@@ -432,6 +454,67 @@ export function createDingtalkReplyDispatcher(params: CreateDingtalkReplyDispatc
     }
   };
 
+  /**
+   * 群聊且 OpenClaw 未配置 `messages.groupChat.visibleReplies=automatic` 时，
+   * 若本轮结束时仍没有任何用户可见输出（上游可能未调用空 final 的 deliver），
+   * 补发与空 final 一致的配置指引，避免只有「思考中」却无声。
+   */
+  const maybeSendGroupVisibleRepliesIdleNudge = async () => {
+    if (isDirect) return;
+    if (!groupChatLacksVisibleRepliesAutomatic(cfg)) return;
+    if (asyncMode) return;
+    if (outboundUserVisibleThisTurn) return;
+    if (idleConfigNudgeSent) return;
+    idleConfigNudgeSent = true;
+    log.info(
+      `[DingTalk][idleNudge] 本轮无用户可见回复且群聊未启用 visibleReplies=automatic，发送配置指引`,
+    );
+    try {
+      const text = pickEmptyReplyFallbackText(true);
+      log.warn(`[DingTalk][idleNudge] ${emptyGroupReplyLogHint()}`);
+      for (const chunk of core.channel.text.chunkTextWithMode(
+        text,
+        textChunkLimit,
+        chunkMode,
+      )) {
+        if (isTextMode) {
+          if (groupReplyMode === 'markdown') {
+            await sendMarkdownMessage(
+              account.config as DingtalkConfig,
+              sessionWebhook,
+              chunk.split('\n')[0]?.replace(/^[#*\s\->]+/, '').slice(0, 20) || 'Message',
+              chunk,
+              { cfg, detectBareAliases: true },
+            );
+          } else {
+            await sendTextMessage(
+              account.config as DingtalkConfig,
+              sessionWebhook,
+              chunk,
+              { cfg, detectBareAliases: true },
+            );
+          }
+        } else {
+          await sendMessage(
+            account.config as DingtalkConfig,
+            sessionWebhook,
+            chunk,
+            {
+              useMarkdown: true,
+              log: params.runtime.log,
+              cfg,
+              detectBareAliases: true,
+            },
+          );
+        }
+      }
+      outboundUserVisibleThisTurn = true;
+      log.info(`[DingTalk][idleNudge] ✅ 配置指引已发送`);
+    } catch (e: any) {
+      log.error(`[DingTalk][idleNudge] 发送失败: ${e?.message || e}`);
+    }
+  };
+
   const { dispatcher, replyOptions, markDispatchIdle } =
     core.channel.reply.createReplyDispatcherWithTyping({
       ...prefixOptions,
@@ -440,6 +523,8 @@ export function createDingtalkReplyDispatcher(params: CreateDingtalkReplyDispatc
         log.info(`[DingTalk][onReplyStart] 开始回复，流式 enabled=${streamingEnabled}`);
         // 每次 onReplyStart 都是全新的回复周期，清空去重集合
         deliveredFinalTexts.clear();
+        outboundUserVisibleThisTurn = false;
+        idleConfigNudgeSent = false;
         if (streamingEnabled) {
           // fire-and-forget：提前创建 AI Card，onPartialReply 会等待创建完成
           void startStreaming();
@@ -482,9 +567,15 @@ export function createDingtalkReplyDispatcher(params: CreateDingtalkReplyDispatc
           info?.kind === "final" && hasText && deliveredFinalTexts.has(text);
         
         // ✅ 如果是 final 响应且没有文本，使用默认提示文案
+        // 群聊空 final 常由 OpenClaw `messages.groupChat.visibleReplies !== "automatic"`
+        // 触发，群聊场景给一句可操作的修复指引；单聊保持原文案。
         if (info?.kind === "final" && !hasText) {
-          text = '✅ 任务执行完成（无文本输出）';
-          log.info(`[DingTalk][deliver] final 响应无文本，使用默认提示文案`);
+          const isGroup = !isDirect;
+          text = pickEmptyReplyFallbackText(isGroup);
+          log.info(`[DingTalk][deliver] final 响应无文本，使用默认提示文案 (isGroup=${isGroup})`);
+          if (isGroup) {
+            log.warn?.(`[DingTalk][deliver] ${emptyGroupReplyLogHint()}`);
+          }
         }
         
         const shouldDeliverText = Boolean(text.trim()) && !skipTextForDuplicateFinal;
@@ -527,6 +618,7 @@ export function createDingtalkReplyDispatcher(params: CreateDingtalkReplyDispatc
                   account.config as DingtalkConfig,
                   log
                 );
+                outboundUserVisibleThisTurn = true;
                 log.info(`[DingTalk][deliver] ✅ block 更新到 AI Card 成功`);
               } catch (streamErr: any) {
                 log.error(`[DingTalk][deliver] ❌ block 更新 AI Card 失败：${streamErr.message}`);
@@ -598,6 +690,7 @@ export function createDingtalkReplyDispatcher(params: CreateDingtalkReplyDispatc
                 );
               }
             }
+            outboundUserVisibleThisTurn = true;
             log.info(`[DingTalk][deliver] ✅ 非流式发送成功`);
             deliveredFinalTexts.add(text);
           } catch (error: any) {
@@ -618,11 +711,13 @@ export function createDingtalkReplyDispatcher(params: CreateDingtalkReplyDispatc
         );
         await closeStreaming();
         typingCallbacks.onIdle?.();
+        await maybeSendGroupVisibleRepliesIdleNudge();
       },
       onIdle: async () => {
         log.info(`[DingTalk][onIdle] 回复空闲，关闭 AI Card`);
         typingCallbacks.onIdle?.();
         await closeStreaming();
+        await maybeSendGroupVisibleRepliesIdleNudge();
       },
       onCleanup: () => {
         log.info(`[DingTalk][onCleanup] 清理回调`);
@@ -685,6 +780,7 @@ export function createDingtalkReplyDispatcher(params: CreateDingtalkReplyDispatc
                 account.config as DingtalkConfig,
                 log
               );
+              outboundUserVisibleThisTurn = true;
               log.debug(`[DingTalk][onPartialReply] ✅ AI Card 更新成功`);
             } catch (err: any) {
               // QPS 限流是瞬时错误：streamAICard 内部已自动退避+重试，

package/src/services/messaging/card.ts

@@ -167,11 +167,18 @@ export type AICardTarget =
 
 // ============ Markdown 格式修正 ============
 
+/**
+ * 统一换行符为 \n，避免 CRLF 干扰 Markdown 解析
+ */
+function normalizeLineEndings(text: string): string {
+  return text.replace(/\r\n?/g, "\n");
+}
+
 /**
  * 确保 Markdown 表格前有空行，否则钉钉无法正确渲染表格
  */
 function ensureTableBlankLines(text: string): string {
-  const lines = text.split("\n");
+  const lines = normalizeLineEndings(text).split("\n");
   const result: string[] = [];
 
   const tableDividerRegex = /^\s*\|?\s*:?-+:?\s*(\|?\s*:?-+:?\s*)+\|?\s*$/;
@@ -202,6 +209,109 @@ function ensureTableBlankLines(text: string): string {
   return result.join("\n");
 }
 
+/**
+ * 将单个 \n 转换为 <br>，保留 \n\n 段落分隔。
+ *
+ * 钉钉 AI Card 渲染器的换行约定：
+ * - 普通文本：用 `<br>` 做换行，`\n` 不创建视觉换行
+ * - 代码块（```）：用 `\n` 做换行，`<br>` 会原样显示为文本
+ * - 列表（- / 1.）、表格（|）、标题（#）：用 `\n` 做语法行分隔
+ * - 引用块（>）：用 `<br>` + lazy continuation，续行不需要 `>`
+ * - 段落间距：`\n\n`
+ *
+ * 本函数按上述约定转换：
+ * - 代码块内：完全保留原始 `\n`
+ * - 连续引用行：合并为一行，`<br>` 连接，去掉续行 `>` 前缀
+ * - 其余：Markdown 块语法行前保留 `\n`，单 `\n` → `<br>`
+ */
+export function fixNewlines(text: string): string {
+  const normalized = normalizeLineEndings(text);
+  const markdownBlockStartPattern =
+    /^(\s{0,3}(?:[-*+]|\d+[.)])[ ])|(\s{0,3}\|)|(\s{0,3}#{1,6}\s)|(\s{0,3}(?:[-*_])\s*(?:[-*_])\s*(?:[-*_]))/;
+  const fencePattern = /^\s{0,3}```/;
+  const quotePattern = /^\s{0,3}>\s?/;
+
+  // 1. 合并连续引用行：仅在代码块外生效；去掉续行的 > 前缀，用 <br> 连接
+  const mergedLines: string[] = [];
+  let pendingQuoteLines: string[] = [];
+  let inCodeBlock = false;
+  const flushPendingQuoteLines = () => {
+    if (pendingQuoteLines.length > 0) {
+      mergedLines.push(pendingQuoteLines.join("<br>"));
+      pendingQuoteLines = [];
+    }
+  };
+
+  for (const line of normalized.split("\n")) {
+    const isFence = fencePattern.test(line);
+
+    if (inCodeBlock) {
+      flushPendingQuoteLines();
+      mergedLines.push(line);
+      if (isFence) {
+        inCodeBlock = false;
+      }
+      continue;
+    }
+
+    if (isFence) {
+      flushPendingQuoteLines();
+      mergedLines.push(line);
+      inCodeBlock = true;
+      continue;
+    }
+
+    if (quotePattern.test(line)) {
+      if (pendingQuoteLines.length === 0) {
+        pendingQuoteLines.push(line);
+      } else {
+        pendingQuoteLines.push(line.replace(quotePattern, ""));
+      }
+    } else {
+      flushPendingQuoteLines();
+      mergedLines.push(line);
+    }
+  }
+  flushPendingQuoteLines();
+
+  // 2. 逐行处理：代码块保留 \n，Markdown 块语法行前保留 \n，其余转 <br>
+  const lines = mergedLines;
+  inCodeBlock = false;
+  const parts: string[] = [];
+
+  for (let i = 0; i < lines.length; i++) {
+    const currentLine = lines[i];
+    const nextInCodeBlock = fencePattern.test(currentLine)
+      ? !inCodeBlock
+      : inCodeBlock;
+
+    if (i < lines.length - 1) {
+      const nextLine = lines[i + 1];
+      const keepNewline =
+        nextInCodeBlock ||
+        currentLine === "" ||
+        nextLine === "" ||
+        fencePattern.test(nextLine) ||
+        markdownBlockStartPattern.test(nextLine);
+      parts.push(currentLine + (keepNewline ? "\n" : "<br>"));
+    } else {
+      parts.push(currentLine);
+    }
+
+    inCodeBlock = nextInCodeBlock;
+  }
+
+  return parts.join("");
+}
+
+/**
+ * 标准化 AI Card 消息内容：先修复表格空行，再处理换行符。
+ * 用于 streamAICard 和 finishAICard 的所有路径，确保行为一致。
+ */
+export function normalizeForCard(content: string): string {
+  return fixNewlines(ensureTableBlankLines(content));
+}
+
 // ============ AI Card 相关 ============
 
 /**
@@ -368,7 +478,7 @@ export async function streamAICard(
       cardData: {
         cardParamMap: {
           flowStatus: AICardStatus.INPUTING,
-          msgContent: content,
+          msgContent: normalizeForCard(content),
           staticMsgContent: "",
           sys_full_json_obj: JSON.stringify({
             order: ["msgContent"],
@@ -417,12 +527,14 @@ export async function streamAICard(
     card.inputingStarted = true;
   }
 
-  const fixedContent = ensureTableBlankLines(content);
+  const fixedContent = normalizeForCard(content);
+  // 未结束的帧去掉末尾 \n，避免先渲染为 <br> 再被下一帧修正的闪烁
+  const streamContent = finished ? fixedContent : fixedContent.replace(/\n+$/, '');
   const body = {
     outTrackId: card.cardInstanceId,
     guid: `${Date.now()}_${Math.random().toString(36).slice(2, 8)}`,
     key: "msgContent",
-    content: fixedContent,
+    content: streamContent,
     isFull: true,
     isFinalize: finished,
     isError: false,
@@ -494,7 +606,7 @@ export async function finishAICard(
   if (config) {
     await ensureValidToken(card, config);
   }
-  const fixedContent = ensureTableBlankLines(content);
+  const fixedContent = normalizeForCard(content);
   log?.info?.(
     `[DingTalk][AICard] 开始 finish，最终内容长度=${fixedContent.length}`,
   );

package/src/utils/empty-reply.ts

@@ -0,0 +1,72 @@
+/**
+ * 空回复（final 文本为空）兜底文案集中处。
+ *
+ * 背景
+ * ----
+ * 群聊场景下用户 @ 机器人后看到「任务执行完成（无文本输出）」，常见根因不是 connector，
+ * 而是上游 OpenClaw 的 reply delivery mode（`source-reply-delivery-mode.ts`）：群聊
+ * 默认走 `message_tool_only`，会跳过 `onPartialReply` 与 `accumulatedText`，
+ * 导致本插件累积的文本始终为空，最后落到 connector 的空回复兜底。
+ *
+ * 修复路径在 OpenClaw 的 `openclaw.json`：
+ *   {
+ *     "messages": {
+ *       "groupChat": { "visibleReplies": "automatic" }
+ *     }
+ *   }
+ *
+ * 本模块的优化目标：让群聊场景看到的兜底文案变成一句可操作的提示，
+ * 并在日志里给运维一份完整指引，而不是一句无信息量的「任务执行完成」。
+ * 单聊场景的兜底文案保持原样（单聊空 final 通常是模型自身输出空）。
+ */
+
+const DIRECT_FALLBACK_TEXT = '✅ 任务执行完成（无文本输出）';
+
+const GROUP_FALLBACK_TEXT = [
+  'ℹ️ 暂未收到模型回复内容。',
+  '若群聊频繁出现该提示，请联系机器人管理员检查 OpenClaw 配置：',
+  '`messages.groupChat.visibleReplies` 需设为 `"automatic"`',
+  '（详见 README / TROUBLESHOOTING.md）。',
+].join('\n');
+
+const GROUP_FALLBACK_LOG_HINT =
+  '群聊 final 文本为空：常见根因是 OpenClaw `messages.groupChat.visibleReplies` ' +
+  '未设为 "automatic"（上游 source-reply-delivery-mode.ts 默认 message_tool_only， ' +
+  '会跳过 partial/accumulated 文本）。' +
+  '请在 openclaw.json 中追加：' +
+  '{ "messages": { "groupChat": { "visibleReplies": "automatic" } } }，' +
+  '然后 `openclaw gateway restart`。详见 docs/TROUBLESHOOTING.md。';
+
+/**
+ * 选取空回复的兜底文案。
+ *
+ * - 群聊：附带修复指引（指向 OpenClaw `messages.groupChat.visibleReplies` 配置）。
+ * - 单聊：维持原文案，避免对模型本身就输出空的常规场景产生噪音。
+ */
+export function pickEmptyReplyFallbackText(isGroup: boolean): string {
+  return isGroup ? GROUP_FALLBACK_TEXT : DIRECT_FALLBACK_TEXT;
+}
+
+/**
+ * 群聊空回复时给运维的 warn 级别日志指引（含 openclaw.json 修复片段）。
+ * 单聊不需要这条 hint，因为单聊空回复多半与配置无关。
+ */
+export function emptyGroupReplyLogHint(): string {
+  return GROUP_FALLBACK_LOG_HINT;
+}
+
+/**
+ * 群聊是否未显式将 OpenClaw `messages.groupChat.visibleReplies` 设为 `"automatic"`。
+ *
+ * `undefined` / 缺失 / `messages: {}` 均视为未开启（与上游默认 `message_tool_only` 行为一致），
+ * 需要 connector 在「本轮无任何用户可见回复」时用 idle 兜底提示配置。
+ */
+export function groupChatLacksVisibleRepliesAutomatic(cfg: any): boolean {
+  return cfg?.messages?.groupChat?.visibleReplies !== 'automatic';
+}
+
+export const __testables = {
+  DIRECT_FALLBACK_TEXT,
+  GROUP_FALLBACK_TEXT,
+  GROUP_FALLBACK_LOG_HINT,
+};

package/src/utils/index.ts

@@ -6,3 +6,4 @@ export * from './constants.ts';
 export * from './token.ts';
 export * from './session.ts';
 export * from './logger.ts';
+export * from './empty-reply.ts';

package/dist/gateway-methods-DtdiDpYK.mjs

@@ -1,2 +0,0 @@
-import { t as registerGatewayMethods } from "./gateway-methods-DI8lkjSd.mjs";
-export { registerGatewayMethods };