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

package/dist/{messaging-CyIJY4h2.mjs → messaging-DQwrrd68.mjs}

@@ -1,7 +1,7 @@
-import { u as uploadMediaToDingTalk } from "./media-DUMfXnwJ.mjs";
+import { u as uploadMediaToDingTalk } from "./media-BRqGsKUB.mjs";
 import { n as createLoggerFromConfig } from "./logger-BDWwViGT.mjs";
 import { t as dingtalkHttp } from "./http-client-DFWZgO1n.mjs";
-import { i as getOapiAccessToken, r as getAccessToken, t as DINGTALK_API } from "./utils-CIfI_3Jh.mjs";
+import { i as DINGTALK_API, o as getAccessToken, s as getOapiAccessToken } from "./utils-QEvgZ2uM.mjs";
 import { r as MEDIA_MSG_TYPES } from "./session-DJ4jYqPv.mjs";
 //#region src/services/messaging/card.ts
 const AI_CARD_TEMPLATE_ID = "02fcf2f4-5e02-4a85-b672-46d1f715543e.schema";
@@ -99,10 +99,16 @@ const AICardStatus = {
 	FAILED: "5"
 };
 /**
+* 统一换行符为 \n，避免 CRLF 干扰 Markdown 解析
+*/
+function normalizeLineEndings(text) {
+	return text.replace(/\r\n?/g, "\n");
+}
+/**
 * 确保 Markdown 表格前有空行，否则钉钉无法正确渲染表格
 */
 function ensureTableBlankLines(text) {
-	const lines = text.split("\n");
+	const lines = normalizeLineEndings(text).split("\n");
 	const result = [];
 	const tableDividerRegex = /^\s*\|?\s*:?-+:?\s*(\|?\s*:?-+:?\s*)+\|?\s*$/;
 	const tableRowRegex = /^\s*\|?.*\|.*\|?\s*$/;
@@ -116,6 +122,79 @@ function ensureTableBlankLines(text) {
 	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>`
+*/
+function fixNewlines(text) {
+	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?/;
+	const mergedLines = [];
+	let pendingQuoteLines = [];
+	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();
+	const lines = mergedLines;
+	inCodeBlock = false;
+	const parts = [];
+	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 的所有路径，确保行为一致。
+*/
+function normalizeForCard(content) {
+	return fixNewlines(ensureTableBlankLines(content));
+}
+/**
 * 构建卡片投放请求体
 */
 function buildDeliverBody(cardInstanceId, target, robotCode) {
@@ -205,7 +284,7 @@ async function streamAICard(card, content, finished = false, config, log) {
 			outTrackId: card.cardInstanceId,
 			cardData: { cardParamMap: {
 				flowStatus: AICardStatus.INPUTING,
-				msgContent: content,
+				msgContent: normalizeForCard(content),
 				staticMsgContent: "",
 				sys_full_json_obj: JSON.stringify({ order: ["msgContent"] }),
 				config: JSON.stringify({ autoLayout: true })
@@ -237,12 +316,13 @@ async function streamAICard(card, content, finished = false, config, log) {
 		}
 		card.inputingStarted = true;
 	}
-	const fixedContent = ensureTableBlankLines(content);
+	const fixedContent = normalizeForCard(content);
+	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
@@ -282,7 +362,7 @@ async function streamAICard(card, content, finished = false, config, log) {
 */
 async function finishAICard(card, content, config, log) {
 	if (config) await ensureValidToken(card, config);
-	const fixedContent = ensureTableBlankLines(content);
+	const fixedContent = normalizeForCard(content);
 	log?.info?.(`[DingTalk][AICard] 开始 finish，最终内容长度=${fixedContent.length}`);
 	await streamAICard(card, fixedContent, true, config, log);
 	const body = {
@@ -771,7 +851,7 @@ async function sendMediaToDingTalk(params) {
 			});
 		}
 		let resolvedMediaUrl = mediaUrl;
-		const { toLocalPath } = await import("./media-DEuF7r3G.mjs");
+		const { toLocalPath } = await import("./media-DD7Rlljd.mjs");
 		const _fs = await import("fs");
 		const _path = await import("path");
 		const directPath = toLocalPath(mediaUrl);
@@ -806,7 +886,7 @@ async function sendMediaToDingTalk(params) {
 		}
 		if (mediaType === "video") {
 			const videoMarker = `[DINGTALK_VIDEO]{"path":"${mediaUrl}"}[/DINGTALK_VIDEO]`;
-			const { processVideoMarkers } = await import("./media-DEuF7r3G.mjs");
+			const { processVideoMarkers } = await import("./media-DD7Rlljd.mjs");
 			await processVideoMarkers(videoMarker, "", config, oapiToken, console, true, targetParam);
 			if (text?.trim()) {
 				const result = await sendProactive(config, targetParam, text, {
@@ -830,7 +910,7 @@ async function sendMediaToDingTalk(params) {
 			fileName,
 			fileType: ext || "file"
 		};
-		const { sendFileProactive } = await import("./media-DEuF7r3G.mjs");
+		const { sendFileProactive } = await import("./media-DD7Rlljd.mjs");
 		await sendFileProactive(config, targetParam, fileInfo, uploadResult.mediaId, log);
 		return {
 			ok: true,

package/dist/{runtime-b4xvqwW6.mjs → runtime-BphH7_vR.mjs}

@@ -1,9 +1,9 @@
-import { d as __exportAll } from "./media-DUMfXnwJ.mjs";
+import { d as __exportAll } from "./media-BRqGsKUB.mjs";
 import { a as resolveDingtalkAccount, c as addWildcardAllowFrom, d as hasConfiguredSecretInput, f as normalizeAccountId, l as createDefaultChannelRuntimeState, m as resolveDefaultGroupPolicy, o as resolveDingtalkCredentials, p as resolveAllowlistProviderRuntimeGroupPolicy, r as resolveDefaultDingtalkAccountId, s as DEFAULT_ACCOUNT_ID, t as listDingtalkAccountIds, u as formatDocsLink } from "./accounts-CF4oK_HZ.mjs";
 import { t as createLogger } from "./logger-BDWwViGT.mjs";
 import { t as dingtalkHttp } from "./http-client-DFWZgO1n.mjs";
-import "./utils-CIfI_3Jh.mjs";
-import { n as sendMediaToDingTalk, o as sendTextToDingTalk } from "./messaging-CyIJY4h2.mjs";
+import "./utils-QEvgZ2uM.mjs";
+import { n as sendMediaToDingTalk, o as sendTextToDingTalk } from "./messaging-DQwrrd68.mjs";
 import { createRequire } from "node:module";
 import { z, z as z$1 } from "zod";
 //#region src/secret-input.ts
@@ -905,8 +905,8 @@ async function monitorDingtalkProvider(opts = {}) {
 	const log = createLogger(cfg.channels?.["dingtalk-connector"]?.debug ?? false);
 	const [accountsModule, monitorAccountModule, monitorSingleModule] = await Promise.all([
 		import("./accounts-BSIiLyZa.mjs"),
-		import("./message-handler-_vk6QsWo.mjs"),
-		import("./connection-BZd5NXuh.mjs")
+		import("./message-handler-CPGT1bgU.mjs"),
+		import("./connection-D4uO_J9G.mjs")
 	]);
 	const { resolveDingtalkAccount, listEnabledDingtalkAccounts } = accountsModule;
 	const { handleDingTalkMessage } = monitorAccountModule;

package/dist/{utils-DY1gFCdU.mjs → utils-BqUoUOwd.mjs}

@@ -1,4 +1,4 @@
 import "./logger-BDWwViGT.mjs";
-import { r as getAccessToken, t as DINGTALK_API } from "./utils-CIfI_3Jh.mjs";
+import { i as DINGTALK_API, o as getAccessToken } from "./utils-QEvgZ2uM.mjs";
 import "./session-DJ4jYqPv.mjs";
 export { DINGTALK_API, getAccessToken };

package/dist/utils-QEvgZ2uM.mjs

@@ -0,0 +1,119 @@
+import { n as dingtalkOapiHttp, t as dingtalkHttp } from "./http-client-DFWZgO1n.mjs";
+//#region src/utils/token.ts
+const DINGTALK_API = "https://api.dingtalk.com";
+const DINGTALK_OAPI = "https://oapi.dingtalk.com";
+/**
+* 按 clientId 分桶缓存，避免多账号串 token。
+*/
+const apiTokenCache = /* @__PURE__ */ new Map();
+const oapiTokenCache = /* @__PURE__ */ new Map();
+function cacheKey(config) {
+	const clientId = String(config?.clientId ?? "").trim();
+	if (!clientId) throw new Error("Invalid DingtalkConfig: clientId is required for token caching. Please ensure your configuration includes a valid clientId.");
+	return clientId;
+}
+/**
+* 获取钉钉 Access Token（新版 API）
+*/
+async function getAccessToken(config) {
+	const now = Date.now();
+	const key = cacheKey(config);
+	const cached = apiTokenCache.get(key);
+	if (cached && cached.expiryMs > now + 6e4) return cached.token;
+	const response = await dingtalkHttp.post(`${DINGTALK_API}/v1.0/oauth2/accessToken`, {
+		appKey: config.clientId,
+		appSecret: config.clientSecret
+	});
+	const token = response.data.accessToken;
+	const expireInSec = Number(response.data.expireIn ?? 0);
+	apiTokenCache.set(key, {
+		token,
+		expiryMs: now + expireInSec * 1e3
+	});
+	return token;
+}
+/**
+* 获取钉钉 OAPI Access Token（旧版 API，用于媒体上传等）
+*/
+async function getOapiAccessToken(config) {
+	try {
+		const now = Date.now();
+		const key = cacheKey(config);
+		const cached = oapiTokenCache.get(key);
+		if (cached && cached.expiryMs > now + 6e4) return cached.token;
+		const resp = await dingtalkOapiHttp.get(`${DINGTALK_OAPI}/gettoken`, { params: {
+			appkey: config.clientId,
+			appsecret: config.clientSecret
+		} });
+		if (resp.data?.errcode === 0 && resp.data?.access_token) {
+			const token = String(resp.data.access_token);
+			const expiresInSec = Number(resp.data.expires_in ?? 7200);
+			oapiTokenCache.set(key, {
+				token,
+				expiryMs: now + expiresInSec * 1e3
+			});
+			return token;
+		}
+		return null;
+	} catch {
+		return null;
+	}
+}
+//#endregion
+//#region src/utils/empty-reply.ts
+/**
+* 空回复（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` 配置）。
+* - 单聊：维持原文案，避免对模型本身就输出空的常规场景产生噪音。
+*/
+function pickEmptyReplyFallbackText(isGroup) {
+	return isGroup ? GROUP_FALLBACK_TEXT : DIRECT_FALLBACK_TEXT;
+}
+/**
+* 群聊空回复时给运维的 warn 级别日志指引（含 openclaw.json 修复片段）。
+* 单聊不需要这条 hint，因为单聊空回复多半与配置无关。
+*/
+function emptyGroupReplyLogHint() {
+	return GROUP_FALLBACK_LOG_HINT;
+}
+/**
+* 群聊是否未显式将 OpenClaw `messages.groupChat.visibleReplies` 设为 `"automatic"`。
+*
+* `undefined` / 缺失 / `messages: {}` 均视为未开启（与上游默认 `message_tool_only` 行为一致），
+* 需要 connector 在「本轮无任何用户可见回复」时用 idle 兜底提示配置。
+*/
+function groupChatLacksVisibleRepliesAutomatic(cfg) {
+	return cfg?.messages?.groupChat?.visibleReplies !== "automatic";
+}
+//#endregion
+export { DINGTALK_OAPI as a, DINGTALK_API as i, groupChatLacksVisibleRepliesAutomatic as n, getAccessToken as o, pickEmptyReplyFallbackText as r, getOapiAccessToken as s, emptyGroupReplyLogHint as t };

package/docs/RELEASE_NOTES_V0.8.21-beta.0.md

@@ -0,0 +1,163 @@
+# Release Notes - v0.8.21-beta.0
+
+> **社区验证版本** — 计划经过 ~3 天社区验证后晋升为正式版 `v0.8.21`。  
+> **Community validation release** — planned to promote to GA `v0.8.21` after ~3 days of community validation.
+
+## 🎉 本次重点 / Highlights
+
+本版本聚焦 WebSocket 连接稳定性 + 群聊体验：
+
+1. 修掉本仓 listener 注册时机错乱导致的 ~30s 一次幽灵重连（社区贡献 #566）
+2. 修掉消息处理保活 interval 与 `TIMEOUT_THRESHOLD` 不匹配的兜底失效（#594）
+3. 过滤上游 `dingtalk-stream@2.1.4` SDK 直接走 `console.info` 的噪音（#571 / #536 / #573）
+4. 群聊 @ 机器人空回复时，把无信息的「任务执行完成」改为带 `openclaw.json` 修复指引的可操作文案（#589）
+
+This release focuses on WebSocket stability + group-chat UX:
+
+1. Fix root cause of ~30s phantom reconnect cycle caused by listener-registration timing (community contribution, #566)
+2. Fix message-processing keepalive interval mismatch with `TIMEOUT_THRESHOLD` (#594)
+3. Filter noisy `console.info` calls from upstream `dingtalk-stream@2.1.4` (#571 / #536 / #573)
+4. Group `@` mention's empty-reply fallback now embeds an actionable `openclaw.json` fix hint (#589)
+
+## 🐛 修复 / Fixes
+
+### WebSocket phantom reconnect 根因修复 (#566)
+
+**现象**：约每 30 秒一次的 WebSocket 重连，`Disconnecting.` / `connect success` 成对出现，看起来像连接频繁掉线。
+
+**根因**：`setupPongListener` / `setupMessageListener` / `setupCloseListener` 在 `client.connect()` 之前被调用，此时 `client.socket === undefined`，函数体里 `client.socket?.on(...)` 的可选链让调用静默成 no-op——三个 listener 实际从未挂上。
+
+- pong listener 缺失 → `lastSocketAvailableTime` 不刷新 → 命中 `TIMEOUT_THRESHOLD = 20s` → `doReconnect()` 触发
+- message listener 缺失 → 服务端真实下发的 disconnect topic 也无法响应
+- close listener 缺失 → socket close 不能立即触发重连
+
+**修复**：
+
+- 删除模块初始化时的 no-op setup 调用
+- 初次 `client.connect()` 成功后立即注册三个 listener
+- `doReconnect()` 里把 setup 挪到 `client.connect()` 之后、`await for OPEN` 之前——避免 keepAlive 期间 ping 的 pong 回来时 listener 还没挂被丢的 race window
+
+**致谢**：感谢 [@Majorshi](https://github.com/Majorshi) 提交 [PR #566](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/pull/566)，并感谢 [@lizhiyao](https://github.com/lizhiyao) / [@edokeh](https://github.com/edokeh) / [@jeikl](https://github.com/jeikl) 提前验证修复有效。
+
+### 消息处理保活 interval 兜底 bug (#594)
+
+**根因**：`markMessageProcessingStart` 启动的兜底定时器原本 30s 间隔，但 `TIMEOUT_THRESHOLD` 已在 `d90916b` 中从 90s 降到 20s——30s 间隔无法在 AI 长任务期间防住超时（AI 任务跑到约 21s 就可能触发 keepAlive 幽灵重连，下次刷新还要等 9 秒）。
+
+**修复**：interval 调整为 15s（< `TIMEOUT_THRESHOLD = 20s`），让保活真正生效。同时清理文件头 docstring 与相关注释里的 stale `90 秒超时` 文案。
+
+### 上游 SDK `console.info` 噪音过滤 (#571 / #536 / #573)
+
+**现象**：日志反复出现
+```
+[2026-05-09T07:04:42.420Z] connect success
+Disconnecting.
+[2026-05-09T07:05:12.483Z] connect success
+Disconnecting.
+...
+```
+看起来像连接频繁掉线。
+
+**根因**：
+1. 上游 `dingtalk-stream@2.1.4` SDK 在 `client.cjs:138 / :185` 每次 `disconnect()` / `connect()` 时直接 `console.info(...)`，绕过 logger，在频繁重连场景下会刷屏
+2. 钉钉服务端在 LB / 实例切换等场景下可能下发 `disconnect` topic，客户端需断开重连——这是协议机制
+3. connector 在 `src/core/connection.ts:setupMessageListener` / `setupCloseListener` 中正确处理了重连，消息收发无感
+
+**修复**：
+- 在 `src/core/connection.ts` 新增 `silenceDingtalkStreamConsoleNoise()`：模块级一次性 patch `console.info`，**只过滤 `Disconnecting.` 和 `[time] connect success` 两条精确字符串**，其他 `console.info` 不受影响
+- 在首个账号连上时通过 `printConnectionNoticeOnce()` 打印一次连接生命周期说明，解释过滤动机以及「高频重连不正常」的预期，多 bot 启动时不重复
+- `setupMessageListener` 收到 `disconnect` topic 时加一行 `logger.debug`，便于排查时查看完整生命周期
+
+## 🩹 改进 / Improvements
+
+### 群聊空回复兜底文案带修复指引 (#589)
+
+**现象**：群聊 @ 机器人时只看到「✅ 任务执行完成（无文本输出）」，没有任何模型回复内容。
+
+**根因**：当 OpenClaw `messages.groupChat.visibleReplies` 未设为 `"automatic"` 时，上游 `source-reply-delivery-mode.ts` 对群聊默认走 `message_tool_only`：
+- 不调 `onPartialReply` → connector `accumulatedText` 始终为空
+- 大多数情况下也不调 `deliver(final)` → 三处空 final 兜底全部打到原文案
+
+用户看到的只是一句无信息的「任务执行完成」，完全没线索去查 `openclaw.json`。
+
+**修复**：
+- 新增 `src/utils/empty-reply.ts` 集中兜底文案
+- `reply-dispatcher.ts` 的 `closeStreaming` / `deliver` 空 final 分支：群聊改用带 `openclaw.json` 修复指引的可操作文案
+- 新增 `maybeSendGroupVisibleRepliesIdleNudge`：在 `onIdle` / `onError` 时若本轮无任何用户可见输出（覆盖上游 `message_tool_only` 根本不调 `deliver()` 的盲区），主动 nudge 一条配置指引
+- `core/message-handler.ts` 异步模式同点位分流
+- warn 日志同步打印完整 `openclaw.json` 修复片段，便于运维直接复制
+- **单聊文案保持不变**（`✅ 任务执行完成（无文本输出）`）：单聊空 final 通常是模型本身输出空，不需要指引噪音
+
+### 新群聊兜底文案
+
+```
+ℹ️ 暂未收到模型回复内容。
+若群聊频繁出现该提示，请联系机器人管理员检查 OpenClaw 配置：
+`messages.groupChat.visibleReplies` 需设为 `"automatic"`
+（详见 README / TROUBLESHOOTING.md）。
+```
+
+### 用户/运维侧修复
+
+`~/.openclaw/openclaw.json` 加上：
+
+```json
+{
+  "messages": {
+    "groupChat": { "visibleReplies": "automatic" }
+  }
+}
+```
+
+然后 `openclaw gateway restart`。
+
+> 跟进调研：插件侧直接覆盖 `sourceReplyDeliveryMode: "automatic"` 让用户不需要改 `openclaw.json` 的方案在 [Issue #591](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/issues/591) 跟踪。
+
+## 📚 文档 / Docs
+
+- **TROUBLESHOOTING.md**：新增「群聊 @ 机器人只返回『任务执行完成（无文本输出）』」条目，给出修复步骤
+- `silenceDingtalkStreamConsoleNoise` 周边的注释 / 函数命名 / banner 文案统一收紧（#592）
+- 清理 `src/core/connection.ts` 中的 stale `90 秒超时` 文档残留（#594）
+
+## 🔒 兼容性 / Compatibility
+
+- **API 无变化**、配置 schema 无变化、导出符号无变化
+- 不影响 #437 的心跳超时检测修复语义
+- 单聊行为完全不变（兜底文案、流式行为都保持原样）
+- 已配置 `messages.groupChat.visibleReplies = "automatic"` 的群聊行为完全不变
+
+## 🧪 验证 / Verification
+
+- 单测：`tests/empty-reply.unit.test.ts` 7/7 + `tests/reply-dispatcher` 7/7 通过
+- 多位社区用户已对 #566 修复 +1 验证有效（@lizhiyao / @edokeh / @jeikl）
+- 本机回归（macOS / OpenClaw 2026.5.7）：
+  - 群聊 @ + `messages: {}` → 看到新的可操作指引
+  - 群聊 @ + `visibleReplies = "automatic"` → 恢复正常流式
+  - 单聊空 final → 文案不变
+
+## ⏭ 下一步 / Next steps
+
+- 社区验证 ~3 天稳定后晋升 GA `v0.8.21`
+- [Issue #591](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/issues/591)：插件侧 `sourceReplyDeliveryMode` 调研——下个迭代评估
+
+## 📥 安装升级 / Installation & Upgrade
+
+```bash
+npx openclaw@latest add @dingtalk-real-ai/dingtalk-connector@0.8.21-beta.0
+```
+
+或：
+
+```bash
+npm install @dingtalk-real-ai/dingtalk-connector@beta
+```
+
+## 🔗 相关链接 / Related Links
+
+- [完整变更日志](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/blob/main/CHANGELOG.md)
+- 关联 PRs / issues：#566 / #589 / #592 / #594 / #571 / #536 / #573 / #545
+
+---
+
+**发布日期 / Release Date**：2026-05-17  
+**版本号 / Version**：v0.8.21-beta.0  
+**兼容性 / Compatibility**：OpenClaw Gateway 2026.4.9+

package/docs/RELEASE_NOTES_V0.8.21.md

@@ -0,0 +1,154 @@
+# Release Notes - v0.8.21
+
+> **GA 正式版** — 晋升自 `0.8.21-beta.0`，经社区验证稳定后发布。  
+> **General Availability** — Promoted from `0.8.21-beta.0` after community validation.
+
+## 🎉 本次重点 / Highlights
+
+本版本聚焦 WebSocket 连接稳定性 + 群聊体验，与 `0.8.21-beta.0` 功能完全一致：
+
+1. 修掉本仓 listener 注册时机错乱导致的 ~30s 一次幽灵重连（社区贡献 [#566](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/pull/566)）
+2. 修掉消息处理保活 interval 与 `TIMEOUT_THRESHOLD` 不匹配的兜底失效（[#594](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/pull/594)）
+3. 过滤上游 `dingtalk-stream@2.1.4` SDK 直接走 `console.info` 的噪音（[#571](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/issues/571) / [#536](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/issues/536) / [#573](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/issues/573)）
+4. 群聊 @ 机器人空回复时，把无信息的「任务执行完成」改为带 `openclaw.json` 修复指引的可操作文案（[#589](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/pull/589)）
+
+This release focuses on WebSocket stability + group-chat UX. Functionally identical to `0.8.21-beta.0`:
+
+1. Fix root cause of ~30s phantom reconnect cycle caused by listener-registration timing (community contribution, #566)
+2. Fix message-processing keepalive interval mismatch with `TIMEOUT_THRESHOLD` (#594)
+3. Filter noisy `console.info` calls from upstream `dingtalk-stream@2.1.4` (#571 / #536 / #573)
+4. Group `@` mention's empty-reply fallback now embeds an actionable `openclaw.json` fix hint (#589)
+
+## 🐛 修复 / Fixes
+
+### WebSocket phantom reconnect 根因修复 (#566)
+
+**现象**：约每 30 秒一次的 WebSocket 重连，`Disconnecting.` / `connect success` 成对出现，看起来像连接频繁掉线。
+
+**根因**：`setupPongListener` / `setupMessageListener` / `setupCloseListener` 在 `client.connect()` 之前被调用，此时 `client.socket === undefined`，函数体里 `client.socket?.on(...)` 的可选链让调用静默成 no-op——三个 listener 实际从未挂上。
+
+- pong listener 缺失 → `lastSocketAvailableTime` 不刷新 → 命中 `TIMEOUT_THRESHOLD = 20s` → `doReconnect()` 触发
+- message listener 缺失 → 服务端真实下发的 disconnect topic 也无法响应
+- close listener 缺失 → socket close 不能立即触发重连
+
+**修复**：
+- 删除模块初始化时的 no-op setup 调用
+- 初次 `client.connect()` 成功后立即注册三个 listener
+- `doReconnect()` 里把 setup 挪到 `client.connect()` 之后、`await for OPEN` 之前——避免 keepAlive 期间 ping 的 pong 回来时 listener 还没挂被丢的 race window
+
+**致谢**：感谢 [@Majorshi](https://github.com/Majorshi) 提交 [PR #566](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/pull/566)，并感谢 [@lizhiyao](https://github.com/lizhiyao) / [@edokeh](https://github.com/edokeh) / [@jeikl](https://github.com/jeikl) 验证修复有效。
+
+### 消息处理保活 interval 兜底 bug (#594)
+
+**根因**：`markMessageProcessingStart` 启动的兜底定时器原本 30s 间隔，但 `TIMEOUT_THRESHOLD` 已在 `d90916b` 中从 90s 降到 20s——30s 间隔无法在 AI 长任务期间防住超时（AI 任务跑到约 21s 就可能触发 keepAlive 幽灵重连，下次刷新还要等 9 秒）。
+
+**修复**：interval 调整为 15s（< `TIMEOUT_THRESHOLD = 20s`），让保活真正生效。同时清理文件头 docstring 与相关注释里的 stale `90 秒超时` 文案。
+
+### 上游 SDK `console.info` 噪音过滤 (#571 / #536 / #573)
+
+**现象**：日志反复出现 `Disconnecting.` / `[time] connect success` 成对刷屏。
+
+**修复**：
+- 在 `src/core/connection.ts` 新增 `silenceDingtalkStreamConsoleNoise()`：模块级一次性 patch `console.info`，**只过滤这两条精确字符串**，其他 `console.info` 不受影响
+- 在首个账号连上时通过 `printConnectionNoticeOnce()` 打印一次连接生命周期说明，解释过滤动机以及「高频重连不正常」的预期，多 bot 启动时不重复
+- `setupMessageListener` 收到 `disconnect` topic 时加一行 `logger.debug`，便于排查时查看完整生命周期
+
+## 🩹 改进 / Improvements
+
+### 群聊空回复兜底文案带修复指引 (#589)
+
+**现象**：群聊 @ 机器人时只看到「✅ 任务执行完成（无文本输出）」，没有任何模型回复内容。
+
+**根因**：当 OpenClaw `messages.groupChat.visibleReplies` 未设为 `"automatic"` 时，上游 `source-reply-delivery-mode.ts` 对群聊默认走 `message_tool_only`：
+- 不调 `onPartialReply` → connector `accumulatedText` 始终为空
+- 大多数情况下也不调 `deliver(final)` → 三处空 final 兜底全部打到原文案
+
+**修复**：
+- 新增 `src/utils/empty-reply.ts` 集中兜底文案
+- `reply-dispatcher.ts` 的 `closeStreaming` / `deliver` 空 final 分支：群聊改用带 `openclaw.json` 修复指引的可操作文案
+- 新增 `maybeSendGroupVisibleRepliesIdleNudge`：在 `onIdle` / `onError` 时若本轮无任何用户可见输出（覆盖上游 `message_tool_only` 根本不调 `deliver()` 的盲区），主动 nudge 一条配置指引
+- `core/message-handler.ts` 异步模式同点位分流
+- warn 日志同步打印完整 `openclaw.json` 修复片段
+- **单聊文案保持不变**
+
+### 新群聊兜底文案
+
+```
+ℹ️ 暂未收到模型回复内容。
+若群聊频繁出现该提示，请联系机器人管理员检查 OpenClaw 配置：
+`messages.groupChat.visibleReplies` 需设为 `"automatic"`
+（详见 README / TROUBLESHOOTING.md）。
+```
+
+### 用户/运维侧修复
+
+`~/.openclaw/openclaw.json` 加上：
+
+```json
+{
+  "messages": {
+    "groupChat": { "visibleReplies": "automatic" }
+  }
+}
+```
+
+然后 `openclaw gateway restart`。
+
+> 跟进调研：插件侧直接覆盖 `sourceReplyDeliveryMode: "automatic"` 让用户不需要改 `openclaw.json` 的方案在 [Issue #591](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/issues/591) 跟踪。
+
+## 📚 文档 / Docs
+
+- **TROUBLESHOOTING.md**：新增「群聊 @ 机器人只返回『任务执行完成（无文本输出）』」条目
+- `silenceDingtalkStreamConsoleNoise` 周边的注释 / 函数命名 / banner 文案统一收紧（#592）
+- 清理 `src/core/connection.ts` 中的 stale `90 秒超时` 文档残留（#594）
+
+## 🔒 兼容性 / Compatibility
+
+- **API 无变化**、配置 schema 无变化、导出符号无变化
+- 不影响 #437 的心跳超时检测修复语义
+- 单聊行为完全不变（兜底文案、流式行为都保持原样）
+- 已配置 `messages.groupChat.visibleReplies = "automatic"` 的群聊行为完全不变
+
+## 🧪 验证 / Verification
+
+**已验证组合 / Verified combo**：
+- OpenClaw Gateway `2026.5.7`
+- Connector `0.8.21-beta.0` (已晋升为 `0.8.21`)
+- 平台 macOS（darwin 23.2.0）
+
+**验证场景**：
+- 单 bot 30s 周期重连已消失
+- 群聊 @ + `messages: {}` → 看到新的可操作指引
+- 群聊 @ + `visibleReplies = "automatic"` → 恢复正常流式
+- 单聊空 final → 文案不变
+
+**社区验证**：beta.0（2026-05-17 发布）经过约 2 天社区使用，相关 issue（#571 / #536 / #573 / #545）均确认修复有效。
+
+## 📥 安装升级 / Installation & Upgrade
+
+```bash
+npx openclaw@latest add @dingtalk-real-ai/dingtalk-connector@0.8.21
+```
+
+或：
+
+```bash
+npm install @dingtalk-real-ai/dingtalk-connector@latest
+```
+
+## ⏭ 下一步 / Next steps
+
+- [Issue #591](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/issues/591)：插件侧 `sourceReplyDeliveryMode` 调研（让用户不再需要改 `openclaw.json`）
+- PR #566 review 中 P2 跟进：抽 `attachSocketListeners()` 单一入口 + listener 注册时机回归测试
+
+## 🔗 相关链接 / Related Links
+
+- [完整变更日志 / Full Changelog](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/blob/main/CHANGELOG.md)
+- [Beta release notes (`v0.8.21-beta.0`)](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/blob/main/docs/RELEASE_NOTES_V0.8.21-beta.0.md)
+- 关联 PRs / issues：#566 / #589 / #592 / #594 / #571 / #536 / #573 / #545
+
+---
+
+**发布日期 / Release Date**：2026-05-19  
+**版本号 / Version**：v0.8.21  
+**兼容性 / Compatibility**：OpenClaw Gateway 2026.4.9+

package/docs/TROUBLESHOOTING.md

@@ -14,6 +14,34 @@
 
 ---
 
+## 群聊 @ 机器人只返回「任务执行完成（无文本输出）」或「暂未收到模型回复内容」
+
+**症状**：在群聊里 @ 机器人，只看到兜底文案，单聊却一切正常。
+
+**根因**：上游 OpenClaw 的 `source-reply-delivery-mode.ts` 在群聊场景下默认走 `message_tool_only`，会跳过 `onPartialReply` 回调，导致本插件累积的文本始终为空，最终落到 connector 的空回复兜底分支。
+
+**解决方案**：在 `~/.openclaw/openclaw.json` 顶层添加 / 合并：
+
+```json
+{
+  "messages": {
+    "groupChat": {
+      "visibleReplies": "automatic"
+    }
+  }
+}
+```
+
+然后重启网关让配置生效：
+
+```bash
+openclaw gateway restart
+```
+
+> 本仓库较新版本中，群聊空回复时兜底文案会自带这段修复指引，日志（warn 级别）也会打印完整的 `openclaw.json` 配置片段，便于运维直接修复；若你看到的仍是冷文案「任务执行完成（无文本输出）」，建议升级到最新 connector。
+
+---
+
 ## 配置字段不合法（additional properties）
 
 **症状**：