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

package/CHANGELOG.md

@@ -5,6 +5,51 @@ All notable changes to this project will be documented in this file.
 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).
 
+## [Unreleased]
+
+## [0.8.21] - 2026-05-19
+
+晋升自 `0.8.21-beta.0` 的 GA 版本，与 beta.0 内容完全一致，经过社区验证后正式发布。  
+GA promotion of `0.8.21-beta.0` after community validation; functionally identical to the beta.
+
+### 升级 / Upgrade
+
+\`\`\`bash
+npx openclaw@latest add @dingtalk-real-ai/dingtalk-connector@0.8.21
+\`\`\`
+
+以下内容沿用自 `0.8.21-beta.0` 的修复与改进 / Same fixes and improvements as `0.8.21-beta.0`：
+
+## [0.8.21-beta.0] - 2026-05-17
+
+### 修复 / Fixes
+- 🐛 **WebSocket phantom reconnect 根因修复 (#566)** — `setupPongListener` / `setupMessageListener` / `setupCloseListener` 原本在 `client.connect()` 之前调用，此时 `client.socket === undefined`，可选链让三个 listener 静默 no-op，从未真正挂上。pong 没人接 → `lastSocketAvailableTime` 不更新 → 命中 `TIMEOUT_THRESHOLD = 20s` → 约 30 秒一次的幽灵重连。本次把 setup 移到 `client.connect()` 之后（初次连接 + `doReconnect` 两条路径都覆盖），并放在 `await for OPEN` 之前，消除 race window。感谢 @Majorshi 贡献。  
+  **Root-cause fix for WebSocket phantom reconnect (#566)** — `setupPongListener` / `setupMessageListener` / `setupCloseListener` were called before `client.connect()` when `client.socket === undefined`, so optional-chaining silently no-op'd and the three listeners were never attached. With no pong handler, `lastSocketAvailableTime` never refreshed, hit `TIMEOUT_THRESHOLD = 20s`, and triggered a phantom reconnect every ~30s. This release moves the setup calls to right after `client.connect()` (covering both initial connect and `doReconnect`), before the OPEN await, eliminating the race window. Credit: @Majorshi.
+
+- 🐛 **消息处理保活 interval 兜底 bug (#594)** — `markMessageProcessingStart` 启动的兜底定时器原本 30s 间隔，但 `TIMEOUT_THRESHOLD` 早已从 90s 降到 20s，30s 间隔无法在 AI 长任务期间防住超时（约 21s 就可能触发幽灵重连，下次刷新还要等 9 秒）。本次改为 15s 间隔（< TIMEOUT_THRESHOLD），让保活真正生效。  
+  **Fix message-processing keepalive interval (#594)** — The fallback `setInterval` in `markMessageProcessingStart` was 30s, but `TIMEOUT_THRESHOLD` had since dropped from 90s to 20s — the 30s interval couldn't prevent the timeout during long AI tasks (could trigger phantom reconnect around the 21s mark, with the next refresh 9s away). This release changes the interval to 15s (< TIMEOUT_THRESHOLD) so the safety net actually works.
+
+- 🐛 **过滤上游 SDK `console.info` 噪音 (#571 / #536 / #573)** — 上游 `dingtalk-stream@2.1.4` SDK 在 `client.cjs:138 / :185` 每次 `disconnect()` / `connect()` 时直接 `console.info("Disconnecting.")` / `connect success`，绕过 logger，在频繁重连场景下会刷屏。本次在 `src/core/connection.ts` 加 `silenceDingtalkStreamConsoleNoise()`：模块级一次性 patch `console.info`，**只过滤这两条精确字符串**，其他 `console.info` 不受影响。同时在首个账号连上时通过 `printConnectionNoticeOnce()` 打印一次连接生命周期说明，解释过滤动机以及"高频重连不正常"的预期。  
+  **Filter upstream SDK `console.info` noise (#571 / #536 / #573)** — Upstream `dingtalk-stream@2.1.4` SDK calls `console.info("Disconnecting.")` / `connect success` directly (`client.cjs:138 / :185`) on every `disconnect()` / `connect()`, bypassing the logger and spamming logs in frequent-reconnect scenarios. This release adds `silenceDingtalkStreamConsoleNoise()` in `src/core/connection.ts`: a module-level one-time `console.info` patch that filters **only these two exact strings**, leaving other `console.info` untouched. It also prints a one-time connection-lifecycle notice via `printConnectionNoticeOnce()` on first connect explaining the filter and setting the expectation that high-frequency reconnects are not normal.
+
+### 改进 / Improvements
+- 🩹 **群聊空回复兜底文案带修复指引 (#589)** — 当 OpenClaw `messages.groupChat.visibleReplies` 未设为 `"automatic"` 时，群聊 @ 机器人会因上游 `source-reply-delivery-mode.ts` 走 `message_tool_only` 而拿不到流式 token，最终落到 connector 空回复兜底；以前固定文案「任务执行完成（无文本输出）」无信息量，现群聊场景改为带 `openclaw.json` 配置修复指引的提示，并在 warn 日志中打印完整片段；同时在 `onIdle` / `onError` 时若本轮无任何用户可见输出，主动 nudge 一条配置指引，覆盖上游根本不调 `deliver()` 的盲区。单聊文案保持不变。  
+  **Group-chat empty-reply fallback now ships actionable hint (#589)** — When OpenClaw’s `messages.groupChat.visibleReplies` is not `"automatic"`, group `@` mentions hit `message_tool_only` upstream and the connector’s accumulated text stays empty, falling through to a cold fallback. The group-chat fallback message now embeds the exact `openclaw.json` fix snippet, and the warn-level log prints the full hint for operators. A new idle nudge in `onIdle` / `onError` proactively sends the same hint when no user-visible output happens this turn — covering the case where upstream never calls `deliver()` at all. DM fallback text unchanged.
+
+### 文档 / Docs
+- 📚 **TROUBLESHOOTING (#589)** — 新增「群聊 @ 机器人只返回『任务执行完成（无文本输出）』」条目，给出 `messages.groupChat.visibleReplies = "automatic"` 修复步骤。  
+  **TROUBLESHOOTING (#589)** — Added "Group `@` only returns 'Task done (no text output)'" entry with the `messages.groupChat.visibleReplies = "automatic"` fix.
+
+- 📚 **`silenceDingtalkStreamConsoleNoise` 文案与函数命名收紧 (#592)** — `printLoadBalanceNoticeOnce` → `printConnectionNoticeOnce`，banner 文案改为「SDK noise 已过滤 + 真实重连 connector 自动处理 + 高频重连不正常」的预期；相关注释同步收紧，去掉对重连频率的强归因。  
+  **Tighten copy & rename for `silenceDingtalkStreamConsoleNoise` (#592)** — Renamed `printLoadBalanceNoticeOnce` to `printConnectionNoticeOnce`; banner copy now reads "SDK noise filtered + real reconnects handled by connector + high-frequency reconnects are not expected"; related comments tightened.
+
+- 📚 **清理 stale `90 秒` 文档残留 (#594)** — 文件头 docstring 与消息处理保活注释里的 `90 秒超时` → `20 秒超时`，与实际 `TIMEOUT_THRESHOLD` 保持一致。  
+  **Clean up stale `90s` doc references (#594)** — File-header docstring and message-processing keepalive comments updated from `90s timeout` to `20s timeout`, matching the actual `TIMEOUT_THRESHOLD`.
+
+### 说明 / Notes
+- 不改动 `startKeepAlive` / `setupPongListener` / `lastSocketAvailableTime` 写入时机的语义，不影响 #437 的心跳超时检测修复。  
+  No changes to `startKeepAlive` / `setupPongListener` / `lastSocketAvailableTime` write semantics — does not affect the #437 heartbeat-timeout fix.
+
 ## [0.8.20] - 2026-04-28
 
 ### 修复 / Fixes

package/README.en.md

@@ -104,11 +104,27 @@ openclaw gateway restart
 
 ---
 
+## Feedback & Community
+
+Before filing an Issue / PR, please skim the pinned notice — clear context helps us debug faster:
+
+- English: [[READ FIRST] #585](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/issues/585)
+- 中文：[【提 Issue 前必看】#584](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/issues/584)
+
+Quick routing:
+
+- **Other DingTalk product / open-platform capabilities** (outside this connector) → [DingTalk developer ticket center](https://applink.dingtalk.com/client/aiAgent?assistantId=381bb5860c264d33bc184c51db776fa7&from=development)
+- **OpenClaw upstream** (gateway, models, channels, etc.) → [openclaw/openclaw Issues](https://github.com/openclaw/openclaw/issues)
+- **`dingtalk-workspace-cli` (dws)** (DingTalk workspace CLI behavior) → [dingtalk-workspace-cli Issues](https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/issues)
+- **This connector** → [GitHub Issues](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/issues)
+
+---
+
 ## Contributing
 
-Community contributions are welcome! If you find a bug or have feature suggestions, please submit an [Issue](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/issues) or Pull Request.
+PRs are welcome — small, well-described changes with clear verification land fastest; for larger changes, please open an Issue first. Doc-style reference: [#514](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/pull/514/changes) · code-style reference: [#581](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/pull/581).
 
-For major changes, we recommend discussing with us first via an Issue.
+> **Quarterly thanks**: each quarter, the top 3 PR contributors get a small gift or an invite to a DingTalk on-site visit (details per quarterly announcement). Thanks for co-building the community.
 
 ---
 

package/README.md

@@ -104,11 +104,27 @@ openclaw gateway restart
 
 ---
 
+## 反馈与社区
+
+提 Issue / PR 前，建议先看一眼置顶说明（信息完整能帮我们更快定位问题）：
+
+- 中文：[【提 Issue 前必看】#584](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/issues/584)
+- English: [[READ FIRST] #585](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/issues/585)
+
+简要分流：
+
+- **钉钉其他业务能力**（非本 connector 范畴）→ [钉钉开发者侧工单入口](https://applink.dingtalk.com/client/aiAgent?assistantId=381bb5860c264d33bc184c51db776fa7&from=development)
+- **OpenClaw 本体**（网关、模型、多通道等）→ [openclaw/openclaw Issues](https://github.com/openclaw/openclaw/issues)
+- **dws（钉钉工作空间 CLI）** → [dingtalk-workspace-cli Issues](https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/issues)
+- **本仓库 connector** → [GitHub Issues](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/issues)
+
+---
+
 ## 贡献
 
-欢迎社区贡献！如果你发现 Bug 或有功能建议，请提交 [Issue](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/issues) 或 Pull Request。
+欢迎提交 Pull Request：改动越小、描述与验证步骤越清晰，越容易合入；较大改动建议先开 Issue 同步。文档类参考 [#514](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/pull/514/changes)，代码类参考 [#581](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/pull/581)。
 
-对于较大的改动，建议先通过 Issue 与我们讨论。
+> **季度致谢**：每个季度对 PR 贡献量居前 3 位的伙伴提供小礼品或钉钉参观交流机会（细则以当季公告为准），感谢大家对社区共建的支持。
 
 ---
 

package/dist/{connection-BZd5NXuh.mjs → connection-D4uO_J9G.mjs}

@@ -6,7 +6,7 @@ import * as fs from "fs";
 *
 * 职责：
 * - 管理单个钉钉账号的 WebSocket 连接
-* - 实现应用层心跳检测（10 秒间隔，90 秒超时）
+* - 实现应用层心跳检测（10 秒间隔，20 秒超时）
 * - 处理连接重连逻辑，带指数退避
 * - 消息去重（内置 Map，5 分钟 TTL）
 *
@@ -23,9 +23,30 @@ const TIMEOUT_THRESHOLD = 20 * 1e3;
 const BASE_BACKOFF_DELAY = 1e3;
 /** 最大退避时间（毫秒） */
 const MAX_BACKOFF_DELAY = 30 * 1e3;
+let _streamNoiseSilenced = false;
+function silenceDingtalkStreamConsoleNoise() {
+	if (_streamNoiseSilenced) return;
+	_streamNoiseSilenced = true;
+	const origConsoleInfo = console.info.bind(console);
+	console.info = (...args) => {
+		const first = args[0];
+		if (typeof first === "string") {
+			if (first === "Disconnecting.") return;
+			if (/^\[[^\]]+\] connect success$/.test(first)) return;
+		}
+		return origConsoleInfo(...args);
+	};
+}
+let _connectionNoticePrinted = false;
+function printConnectionNoticeOnce() {
+	if (_connectionNoticePrinted) return;
+	_connectionNoticePrinted = true;
+	console.log("[dingtalk-connector] ℹ️  上游 dingtalk-stream SDK 的 `Disconnecting.` / `connect success` 日志已由本插件过滤；真实重连（网络抖动、服务端推 disconnect 等）由 connector 自动处理。正常运行下不应看到高频（≤30s）周期性重连，如有请提 issue。");
+}
 async function monitorSingleAccount(opts) {
 	const { cfg, account, runtime, abortSignal, messageHandler, onStatusChange } = opts;
 	const { accountId } = account;
+	silenceDingtalkStreamConsoleNoise();
 	const clawdbotConfig = cfg;
 	const log = runtime?.log;
 	const { createLoggerFromConfig } = await import("./logger-BeHWErmX.mjs");
@@ -75,7 +96,7 @@ async function monitorSingleAccount(opts) {
 	let messageProcessingKeepAliveTimer = null;
 	/**
 	* 标记消息处理开始，启动定期更新机制
-	* 在消息处理期间，每 30 秒更新一次 lastSocketAvailableTime
+	* 在消息处理期间，定时刷新 lastSocketAvailableTime
 	* 防止长时间处理（如复杂的 AI 任务）触发心跳超时
 	*/
 	function markMessageProcessingStart() {
@@ -87,7 +108,7 @@ async function monitorSingleAccount(opts) {
 				lastSocketAvailableTime = Date.now();
 				logger.debug(`📝 消息处理中，更新 socket 可用时间`);
 			}
-		}, 30 * 1e3);
+		}, 15 * 1e3);
 		logger.debug(`📝 消息处理开始，启动活跃标记定时器`);
 	}
 	/**
@@ -126,6 +147,9 @@ async function monitorSingleAccount(opts) {
 				logger.info(`已断开旧连接`);
 			}
 			await client.connect();
+			setupPongListener();
+			setupMessageListener();
+			setupCloseListener();
 			if (!await new Promise((resolve) => {
 				const timeout = setTimeout(() => {
 					resolve(false);
@@ -180,6 +204,7 @@ async function monitorSingleAccount(opts) {
 			try {
 				const msg = JSON.parse(data);
 				if (msg.type === "SYSTEM" && msg.headers?.topic === "disconnect") {
+					logger.debug(`收到服务端 disconnect topic，即将重连`);
 					if (!isStopped && !isReconnecting) doReconnect(true).catch((err) => {
 						logger.error(`[${accountId}] 重连失败：${err.message}`);
 					});
@@ -263,9 +288,6 @@ async function monitorSingleAccount(opts) {
 		if (client.socket) client.socket.removeAllListeners();
 		logger.debug(`Connection 已停止`);
 	}
-	setupPongListener();
-	setupMessageListener();
-	setupCloseListener();
 	return new Promise(async (resolve, reject) => {
 		if (abortSignal) {
 			const onAbort = async () => {
@@ -367,9 +389,13 @@ async function monitorSingleAccount(opts) {
 		};
 		try {
 			await client.connect();
+			setupPongListener();
+			setupMessageListener();
+			setupCloseListener();
 			logger.info(`Connected to DingTalk Stream successfully`);
 			logger.info(`PID: ${process.pid}`);
-			logger.info(`✅ 自定义 keepAlive: true (10 秒心跳，90 秒超时), 指数退避重连`);
+			logger.info(`✅ 自定义 keepAlive: true (10 秒心跳，20 秒超时), 指数退避重连`);
+			printConnectionNoticeOnce();
 			onStatusChange?.({
 				connected: true,
 				lastConnectedAt: Date.now()

package/dist/entry-bundled.mjs

@@ -23,7 +23,7 @@ var entry_bundled_default = defineBundledChannelEntry({
 		exportName: "setDingtalkRuntime"
 	},
 	async registerFull(api) {
-		const { registerGatewayMethods } = await import("./gateway-methods-DtdiDpYK.mjs");
+		const { registerGatewayMethods } = await import("./gateway-methods-B0_tBGPn.mjs");
 		registerGatewayMethods(api);
 	}
 });

package/dist/gateway-methods-B0_tBGPn.mjs

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

package/dist/{gateway-methods-DI8lkjSd.mjs → gateway-methods-BNuB2wXl.mjs}

@@ -1,7 +1,7 @@
 import { a as resolveDingtalkAccount, t as listDingtalkAccountIds } from "./accounts-CF4oK_HZ.mjs";
 import { t as dingtalkHttp } from "./http-client-DFWZgO1n.mjs";
-import { r as getAccessToken, t as DINGTALK_API } from "./utils-CIfI_3Jh.mjs";
-import { c as prepareMultiBotMentions, i as sendProactive, s as buildBotMentionTable, u as finishAICard } from "./messaging-CyIJY4h2.mjs";
+import { i as DINGTALK_API, o as getAccessToken } from "./utils-QEvgZ2uM.mjs";
+import { c as prepareMultiBotMentions, i as sendProactive, s as buildBotMentionTable, u as finishAICard } from "./messaging-DQwrrd68.mjs";
 import { c as getUnionId, d as recallEmotionReply } from "./utils-legacy-CALCPP1t.mjs";
 //#region src/docs.ts
 var DingtalkDocsClient = class {

package/dist/index.mjs

@@ -1,5 +1,5 @@
-import { a as initDingtalkPluginConfigSchema, i as dingtalkPlugin, n as setDingtalkRuntime } from "./runtime-b4xvqwW6.mjs";
-import { t as registerGatewayMethods } from "./gateway-methods-DI8lkjSd.mjs";
+import { a as initDingtalkPluginConfigSchema, i as dingtalkPlugin, n as setDingtalkRuntime } from "./runtime-BphH7_vR.mjs";
+import { t as registerGatewayMethods } from "./gateway-methods-BNuB2wXl.mjs";
 //#region index.ts
 /**
 * 检测同一 plugin id 在多个路径被加载的情况。

package/dist/{media-DUMfXnwJ.mjs → media-BRqGsKUB.mjs}

@@ -1,5 +1,5 @@
 import { n as dingtalkOapiHttp, t as dingtalkHttp } from "./http-client-DFWZgO1n.mjs";
-import { n as DINGTALK_OAPI } from "./utils-CIfI_3Jh.mjs";
+import { a as DINGTALK_OAPI } from "./utils-QEvgZ2uM.mjs";
 import { createRequire } from "node:module";
 import * as fs from "fs";
 import * as path from "path";
@@ -287,7 +287,7 @@ async function extractAudioDuration(filePath, log) {
 */
 async function sendVideoMessage(config, sessionWebhook, fileName, mediaId, log, metadata) {
 	try {
-		const token = await (await import("./utils-DY1gFCdU.mjs")).getAccessToken(config);
+		const token = await (await import("./utils-BqUoUOwd.mjs")).getAccessToken(config);
 		const videoMessage = {
 			msgtype: "video",
 			video: {
@@ -315,8 +315,8 @@ async function sendVideoMessage(config, sessionWebhook, fileName, mediaId, log,
 */
 async function sendVideoProactive(config, target, videoMediaId, picMediaId, metadata, log) {
 	try {
-		const token = await (await import("./utils-DY1gFCdU.mjs")).getAccessToken(config);
-		const { DINGTALK_API } = await import("./utils-DY1gFCdU.mjs");
+		const token = await (await import("./utils-BqUoUOwd.mjs")).getAccessToken(config);
+		const { DINGTALK_API } = await import("./utils-BqUoUOwd.mjs");
 		const msgParam = {
 			duration: metadata?.duration.toString() || "60000",
 			videoMediaId,
@@ -361,8 +361,8 @@ async function sendVideoProactive(config, target, videoMediaId, picMediaId, meta
 */
 async function sendAudioProactive(config, target, fileName, mediaId, log, durationMs) {
 	try {
-		const token = await (await import("./utils-DY1gFCdU.mjs")).getAccessToken(config);
-		const { DINGTALK_API } = await import("./utils-DY1gFCdU.mjs");
+		const token = await (await import("./utils-BqUoUOwd.mjs")).getAccessToken(config);
+		const { DINGTALK_API } = await import("./utils-BqUoUOwd.mjs");
 		const msgParam = {
 			mediaId,
 			duration: durationMs && durationMs > 0 ? durationMs.toString() : "60000"
@@ -399,8 +399,8 @@ async function sendAudioProactive(config, target, fileName, mediaId, log, durati
 */
 async function sendFileProactive(config, target, fileInfo, mediaId, log) {
 	try {
-		const token = await (await import("./utils-DY1gFCdU.mjs")).getAccessToken(config);
-		const { DINGTALK_API } = await import("./utils-DY1gFCdU.mjs");
+		const token = await (await import("./utils-BqUoUOwd.mjs")).getAccessToken(config);
+		const { DINGTALK_API } = await import("./utils-BqUoUOwd.mjs");
 		const resolvedFileName = fileInfo.fileName || path.basename(fileInfo.path);
 		const msgParam = {
 			mediaId,

package/dist/{media-DEuF7r3G.mjs → media-DD7Rlljd.mjs}

@@ -1,2 +1,2 @@
-import { a as processVideoMarkers, i as processRawMediaPaths, l as toLocalPath, s as sendFileProactive } from "./media-DUMfXnwJ.mjs";
+import { a as processVideoMarkers, i as processRawMediaPaths, l as toLocalPath, s as sendFileProactive } from "./media-BRqGsKUB.mjs";
 export { processRawMediaPaths, processVideoMarkers, sendFileProactive, toLocalPath };

package/dist/{message-handler-_vk6QsWo.mjs → message-handler-CPGT1bgU.mjs}

@@ -1,10 +1,10 @@
-import { u as uploadMediaToDingTalk } from "./media-DUMfXnwJ.mjs";
+import { u as uploadMediaToDingTalk } from "./media-BRqGsKUB.mjs";
 import { a as resolveDingtalkAccount } from "./accounts-CF4oK_HZ.mjs";
-import { r as CHANNEL_ID, t as getDingtalkRuntime } from "./runtime-b4xvqwW6.mjs";
+import { r as CHANNEL_ID, t as getDingtalkRuntime } from "./runtime-BphH7_vR.mjs";
 import { n as createLoggerFromConfig } from "./logger-BDWwViGT.mjs";
 import { t as dingtalkHttp } from "./http-client-DFWZgO1n.mjs";
-import { i as getOapiAccessToken } from "./utils-CIfI_3Jh.mjs";
-import { a as sendTextMessage, d as isQpsLimitError, f as streamAICard, i as sendProactive, l as createAICardForTarget, r as sendMessage, t as sendMarkdownMessage, u as finishAICard } from "./messaging-CyIJY4h2.mjs";
+import { n as groupChatLacksVisibleRepliesAutomatic, r as pickEmptyReplyFallbackText, s as getOapiAccessToken, t as emptyGroupReplyLogHint } from "./utils-QEvgZ2uM.mjs";
+import { a as sendTextMessage, d as isQpsLimitError, f as streamAICard, i as sendProactive, l as createAICardForTarget, r as sendMessage, t as sendMarkdownMessage, u as finishAICard } from "./messaging-DQwrrd68.mjs";
 import { a as QUEUE_BUSY_ACK_PHRASES, n as normalizeSlashCommand, t as buildSessionContext } from "./session-DJ4jYqPv.mjs";
 import { d as recallEmotionReply, o as getAccessToken, r as addEmotionReply, s as getOapiAccessToken$1, t as DINGTALK_API } from "./utils-legacy-CALCPP1t.mjs";
 import "./chunk-upload-6p9cf3UB.mjs";
@@ -222,6 +222,10 @@ function createDingtalkReplyDispatcher(params) {
 	let currentCardTarget = null;
 	let accumulatedText = "";
 	const deliveredFinalTexts = /* @__PURE__ */ new Set();
+	/** 本轮是否已向用户发出过可见回复（final / 流式更新 / 错误兜底等） */
+	let outboundUserVisibleThisTurn = false;
+	/** 防止 onIdle / onError 重复发送 visibleReplies 配置指引 */
+	let idleConfigNudgeSent = false;
 	let asyncModeFullResponse = "";
 	const detectedDwsProducts = /* @__PURE__ */ new Set();
 	const DWS_PRODUCT_PATTERN = /\bdws\s+(aitable|calendar|chat|contact|todo|approval|attendance|report|ding|workbench|devdoc)\b/;
@@ -257,6 +261,7 @@ function createDingtalkReplyDispatcher(params) {
 			});
 			deliveredErrorTypes.add(errorKey);
 			lastErrorTime = now;
+			outboundUserVisibleThisTurn = true;
 			log.info(`[DingTalk][Fallback] ✅ 错误消息发送成功`);
 		} catch (fallbackErr) {
 			log.error(`[DingTalk][Fallback] ❌ 错误消息发送失败：${fallbackErr.message}`);
@@ -301,6 +306,7 @@ function createDingtalkReplyDispatcher(params) {
 				log.info(`[DingTalk][startStreaming] 复用预创建 AI Card，cardInstanceId=${preCreatedCard.cardInstanceId}`);
 				currentCardTarget = preCreatedCard;
 				accumulatedText = "";
+				outboundUserVisibleThisTurn = true;
 				return;
 			}
 			log.info(`[DingTalk][startStreaming] 开始创建 AI Card...`);
@@ -338,8 +344,10 @@ function createDingtalkReplyDispatcher(params) {
 		try {
 			let finalText = accumulatedText;
 			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()}`);
 			}
 			const oapiToken = await getOapiAccessToken(account.config);
 			const target = isDirect ? {
@@ -356,7 +364,7 @@ function createDingtalkReplyDispatcher(params) {
 				finalText = await processAudioMarkers(finalText, "", account.config, oapiToken, log, true, target);
 				finalText = await uploadAndReplaceFileMarkers(finalText, "", account.config, oapiToken, log, true, target);
 				log.info(`[DingTalk][closeStreaming] 准备调用 processRawMediaPaths`);
-				const { processRawMediaPaths } = await import("./media-DEuF7r3G.mjs");
+				const { processRawMediaPaths } = await import("./media-DD7Rlljd.mjs");
 				finalText = await processRawMediaPaths(finalText, account.config, oapiToken, log, target);
 				log.info(`[DingTalk][closeStreaming] processRawMediaPaths 处理完成`);
 			} else log.warn(`[DingTalk][closeStreaming] oapiToken 为空，跳过媒体处理`);
@@ -389,6 +397,7 @@ function createDingtalkReplyDispatcher(params) {
 			log.info(`[DingTalk][closeStreaming] 准备调用 finishAICard，文本长度=${finalText.length}`);
 			log.debug(`[DingTalk][closeStreaming] 最终发送内容长度=${finalText.length}`);
 			await finishAICard(cardSnapshot, finalText, account.config, log);
+			outboundUserVisibleThisTurn = true;
 			log.info(`[DingTalk][closeStreaming] ✅ AI Card 关闭成功`);
 		} catch (error) {
 			log.error(`[DingTalk][closeStreaming] ❌ AI Card 关闭失败：${error?.message || String(error)}`);
@@ -399,6 +408,7 @@ function createDingtalkReplyDispatcher(params) {
 					useMarkdown: true,
 					log: params.runtime.log
 				});
+				outboundUserVisibleThisTurn = true;
 				log.info(`[DingTalk][closeStreaming] ✅ 降级发送成功`);
 			} catch (sendErr) {
 				log.error(`[DingTalk][closeStreaming] ❌ 降级发送失败：${sendErr.message}`);
@@ -407,12 +417,50 @@ function createDingtalkReplyDispatcher(params) {
 			accumulatedText = "";
 		}
 	};
+	/**
+	* 群聊且 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, sessionWebhook, chunk.split("\n")[0]?.replace(/^[#*\s\->]+/, "").slice(0, 20) || "Message", chunk, {
+				cfg,
+				detectBareAliases: true
+			});
+			else await sendTextMessage(account.config, sessionWebhook, chunk, {
+				cfg,
+				detectBareAliases: true
+			});
+			else await sendMessage(account.config, sessionWebhook, chunk, {
+				useMarkdown: true,
+				log: params.runtime.log,
+				cfg,
+				detectBareAliases: true
+			});
+			outboundUserVisibleThisTurn = true;
+			log.info(`[DingTalk][idleNudge] ✅ 配置指引已发送`);
+		} catch (e) {
+			log.error(`[DingTalk][idleNudge] 发送失败: ${e?.message || e}`);
+		}
+	};
 	const { dispatcher, replyOptions, markDispatchIdle } = core.channel.reply.createReplyDispatcherWithTyping({
 		...prefixOptions,
 		humanDelay: core.channel.reply.resolveHumanDelayConfig(cfg, agentId),
 		onReplyStart: () => {
 			log.info(`[DingTalk][onReplyStart] 开始回复，流式 enabled=${streamingEnabled}`);
 			deliveredFinalTexts.clear();
+			outboundUserVisibleThisTurn = false;
+			idleConfigNudgeSent = false;
 			if (streamingEnabled) startStreaming();
 			typingCallbacks.onActive?.();
 		},
@@ -432,7 +480,7 @@ function createDingtalkReplyDispatcher(params) {
 					const oapiToken = await getOapiAccessToken(account.config);
 					if (oapiToken) {
 						log.info(`[DingTalk][deliver] 检测到 final 响应，准备处理裸露文件路径`);
-						const { processRawMediaPaths } = await import("./media-DEuF7r3G.mjs");
+						const { processRawMediaPaths } = await import("./media-DD7Rlljd.mjs");
 						text = await processRawMediaPaths(text, account.config, oapiToken, log, target);
 						log.info(`[DingTalk][deliver] 裸露文件路径处理完成`);
 					}
@@ -443,8 +491,10 @@ function createDingtalkReplyDispatcher(params) {
 			const hasText = Boolean(text.trim());
 			const skipTextForDuplicateFinal = info?.kind === "final" && hasText && deliveredFinalTexts.has(text);
 			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()}`);
 			}
 			if (!(Boolean(text.trim()) && !skipTextForDuplicateFinal)) {
 				log.info(`[DingTalk][deliver] 跳过发送：hasText=${hasText}, skipTextForDuplicateFinal=${skipTextForDuplicateFinal}`);
@@ -468,6 +518,7 @@ function createDingtalkReplyDispatcher(params) {
 						lastUpdateTime = now;
 						try {
 							await streamAICard(currentCardTarget, text, false, account.config, log);
+							outboundUserVisibleThisTurn = true;
 							log.info(`[DingTalk][deliver] ✅ block 更新到 AI Card 成功`);
 						} catch (streamErr) {
 							log.error(`[DingTalk][deliver] ❌ block 更新 AI Card 失败：${streamErr.message}`);
@@ -504,6 +555,7 @@ function createDingtalkReplyDispatcher(params) {
 						cfg,
 						detectBareAliases: true
 					});
+					outboundUserVisibleThisTurn = true;
 					log.info(`[DingTalk][deliver] ✅ 非流式发送成功`);
 					deliveredFinalTexts.add(text);
 				} catch (error) {
@@ -519,11 +571,13 @@ function createDingtalkReplyDispatcher(params) {
 			params.runtime.error?.(`dingtalk[${account.accountId}] ${info.kind} reply failed: ${String(error)}`);
 			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] 清理回调`);
@@ -559,6 +613,7 @@ function createDingtalkReplyDispatcher(params) {
 						lastUpdateTime = now;
 						try {
 							await streamAICard(currentCardTarget, displayContent, false, account.config, log);
+							outboundUserVisibleThisTurn = true;
 							log.debug(`[DingTalk][onPartialReply] ✅ AI Card 更新成功`);
 						} catch (err) {
 							if (isQpsLimitError(err)) log.warn(`[DingTalk][onPartialReply] AI Card 流式更新遇到 QPS 限流，已在内部退避重试；本次跳过，等待下一次 partial 更新补齐内容`);
@@ -1696,13 +1751,19 @@ async function handleDingTalkMessageInternal(params) {
 				finalText = await processVideoMarkers(finalText, "", config, oapiToken, log, true, mediaTarget);
 				finalText = await processAudioMarkers(finalText, "", config, oapiToken, log, true, mediaTarget);
 				finalText = await uploadAndReplaceFileMarkers(finalText, "", config, oapiToken, log, true, mediaTarget);
-				const { processRawMediaPaths } = await import("./media-DEuF7r3G.mjs");
+				const { processRawMediaPaths } = await import("./media-DD7Rlljd.mjs");
 				finalText = await processRawMediaPaths(finalText, config, oapiToken, log, mediaTarget);
 			}
-			const textToSend = finalText.trim() || "✅ 任务执行完成（无文本输出）";
+			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, {
 				msgType: "markdown",
-				title: textToSend.split("\n")[0]?.replace(/^[#*\s\->]+/, "").trim() || "消息",
+				title,
 				useAICard: false,
 				fallbackToNormal: true,
 				log