@soimy/dingtalk 3.5.2 → 3.5.3

package/src/channel.ts

@@ -1,8 +1,8 @@
 import { randomUUID } from "node:crypto";
 import { DWClient, TOPIC_CARD, TOPIC_ROBOT } from "dingtalk-stream";
+import { jsonResult } from "openclaw/plugin-sdk/channel-actions";
 import type { ChannelMessageActionAdapter } from "openclaw/plugin-sdk/channel-contract";
 import { buildChannelConfigSchema, type OpenClawConfig } from "openclaw/plugin-sdk/core";
-import { jsonResult } from "openclaw/plugin-sdk/telegram-core";
 import { readStringParam } from "openclaw/plugin-sdk/param-readers";
 import { extractToolSend } from "openclaw/plugin-sdk/tool-send";
 import { getAccessToken } from "./auth";
@@ -68,6 +68,7 @@ import {
   formatDingTalkConnectionErrorLog,
   formatDingTalkErrorPayloadLog,
   getCurrentTimestamp,
+  parseBooleanLike,
   resolvePluginDebugLog,
 } from "./utils";
 
@@ -188,29 +189,15 @@ function logInboundCounters(log: any, accountId: string, reason: string): void {
 }
 
 function readBooleanLikeParam(params: Record<string, unknown>, key: string): boolean | undefined {
-  const value = params[key];
-  if (typeof value === "boolean") {
-    return value;
-  }
-  if (typeof value === "number") {
-    if (value === 1) {
-      return true;
-    }
-    if (value === 0) {
-      return false;
-    }
-    return undefined;
-  }
-  if (typeof value === "string") {
-    const normalized = value.trim().toLowerCase();
-    if (["1", "true", "yes", "y", "on"].includes(normalized)) {
-      return true;
-    }
-    if (["0", "false", "no", "n", "off"].includes(normalized)) {
-      return false;
-    }
+  return parseBooleanLike(params[key]);
+}
+
+function readSharedAudioAsVoiceParam(params: Record<string, unknown>): boolean {
+  const sharedValue = readBooleanLikeParam(params, "audioAsVoice");
+  if (sharedValue !== undefined) {
+    return sharedValue;
   }
-  return undefined;
+  return readBooleanLikeParam(params, "asVoice") === true;
 }
 
 function describeDingTalkMessageTool(cfg: OpenClawConfig): {
@@ -261,7 +248,7 @@ const dingtalkMessageActions: ChannelMessageActionAdapter = {
       message = caption;
     }
 
-    const asVoice = readBooleanLikeParam(params, "asVoice") === true;
+    const asVoice = readSharedAudioAsVoiceParam(params);
     const requestedMediaType = readStringParam(params, "mediaType");
 
     const target = resolveOriginalPeerId(stripTargetPrefix(to).targetId);
@@ -507,6 +494,7 @@ export const dingtalkPlugin: DingTalkChannelPlugin = {
       filePath,
       mediaUrl,
       mediaType: providedMediaType,
+      audioAsVoice,
       asVoice,
       accountId,
       mediaLocalRoots,
@@ -570,7 +558,7 @@ export const dingtalkPlugin: DingTalkChannelPlugin = {
         const mediaType = resolveOutboundMediaType({
           mediaType: typeof providedMediaType === "string" ? providedMediaType : undefined,
           mediaPath: actualMediaPath,
-          asVoice: asVoice === true,
+          asVoice: readSharedAudioAsVoiceParam({ audioAsVoice, asVoice }),
         });
         let result;
         try {
@@ -679,6 +667,12 @@ export const dingtalkPlugin: DingTalkChannelPlugin = {
       }
 
       const useConnectionManager = config.useConnectionManager ?? true;
+      const applyStatusPatch = (patch: Record<string, unknown>) => {
+        ctx.setStatus({
+          ...ctx.getStatus(),
+          ...patch,
+        });
+      };
 
       // Factory that creates a fresh DWClient with the TOPIC_ROBOT callback
       // already registered. Each client captures its own reference for
@@ -721,6 +715,14 @@ export const dingtalkPlugin: DingTalkChannelPlugin = {
           };
           try {
             const data = JSON.parse(res.data) as DingTalkInboundMessage;
+            // Record the latest inbound callback arrival for status/UI projection.
+            // This intentionally tracks "message reached the plugin callback" rather
+            // than "message passed dedup and completed processing".
+            applyStatusPatch({
+              connected: true,
+              lastInboundAt: getCurrentTimestamp(),
+              lastEventAt: getCurrentTimestamp(),
+            });
 
             const robotKey = resolveRobotCode(config) || account.accountId;
             const msgId = data.msgId || messageId;
@@ -912,9 +914,10 @@ export const dingtalkPlugin: DingTalkChannelPlugin = {
           nativeStopResolve?.();
         }
 
-        ctx.setStatus({
-          ...ctx.getStatus(),
+        applyStatusPatch({
           running: false,
+          connected: false,
+          lastEventAt: getCurrentTimestamp(),
           lastStopAt: getCurrentTimestamp(),
         });
 
@@ -931,9 +934,10 @@ export const dingtalkPlugin: DingTalkChannelPlugin = {
             `[${account.accountId}] Abort signal already active, skipping connection`,
           );
 
-          ctx.setStatus({
-            ...ctx.getStatus(),
+          applyStatusPatch({
             running: false,
+            connected: false,
+            lastEventAt: getCurrentTimestamp(),
             lastStopAt: getCurrentTimestamp(),
             lastError: "Connection aborted before start",
           });
@@ -956,9 +960,11 @@ export const dingtalkPlugin: DingTalkChannelPlugin = {
         try {
           await client.connect();
           if (!stopped) {
-            ctx.setStatus({
-              ...ctx.getStatus(),
+            applyStatusPatch({
               running: true,
+              connected: true,
+              lastConnectedAt: getCurrentTimestamp(),
+              lastEventAt: getCurrentTimestamp(),
               lastStartAt: getCurrentTimestamp(),
               lastError: null,
             });
@@ -974,9 +980,10 @@ export const dingtalkPlugin: DingTalkChannelPlugin = {
               `[${account.accountId}] Failed to establish connection: ${err.message}`,
             ) ?? `[${account.accountId}] Failed to establish connection: ${err.message}`,
           );
-          ctx.setStatus({
-            ...ctx.getStatus(),
+          applyStatusPatch({
             running: false,
+            connected: false,
+            lastEventAt: getCurrentTimestamp(),
             lastError: err.message || "Connection failed",
           });
           throw err;
@@ -1004,9 +1011,11 @@ export const dingtalkPlugin: DingTalkChannelPlugin = {
             `[${account.accountId}] Connection state changed to: ${state}${error ? ` (${error})` : ""}`,
           );
           if (state === ConnectionState.CONNECTED) {
-            ctx.setStatus({
-              ...ctx.getStatus(),
+            applyStatusPatch({
               running: true,
+              connected: true,
+              lastConnectedAt: getCurrentTimestamp(),
+              lastEventAt: getCurrentTimestamp(),
               lastStartAt: getCurrentTimestamp(),
               lastError: null,
             });
@@ -1027,9 +1036,10 @@ export const dingtalkPlugin: DingTalkChannelPlugin = {
                 `[${account.accountId}] Cleared ${cleared} stale in-flight lock(s) on disconnect`,
               );
             }
-            ctx.setStatus({
-              ...ctx.getStatus(),
+            applyStatusPatch({
               running: false,
+              connected: false,
+              lastEventAt: getCurrentTimestamp(),
               lastError: error || `Connection ${state.toLowerCase()}`,
             });
           }
@@ -1054,9 +1064,11 @@ export const dingtalkPlugin: DingTalkChannelPlugin = {
         await connectionManager.connect();
 
         if (!stopped && connectionManager.isConnected()) {
-          ctx.setStatus({
-            ...ctx.getStatus(),
+          applyStatusPatch({
             running: true,
+            connected: true,
+            lastConnectedAt: getCurrentTimestamp(),
+            lastEventAt: getCurrentTimestamp(),
             lastStartAt: getCurrentTimestamp(),
             lastError: null,
           });
@@ -1079,9 +1091,10 @@ export const dingtalkPlugin: DingTalkChannelPlugin = {
           ) ?? `[${account.accountId}] Failed to establish connection: ${err.message}`,
         );
 
-        ctx.setStatus({
-          ...ctx.getStatus(),
+        applyStatusPatch({
           running: false,
+          connected: false,
+          lastEventAt: getCurrentTimestamp(),
           lastError: err.message || "Connection failed",
         });
         throw err;
@@ -1098,7 +1111,10 @@ export const dingtalkPlugin: DingTalkChannelPlugin = {
     defaultRuntime: {
       accountId: "default",
       running: false,
+      connected: false,
       lastEventAt: null,
+      lastConnectedAt: null,
+      lastInboundAt: null,
       lastStartAt: null,
       lastStopAt: null,
       lastError: null,
@@ -1155,7 +1171,10 @@ export const dingtalkPlugin: DingTalkChannelPlugin = {
         configured: account.configured,
         clientId: account.config?.clientId ?? null,
         running,
+        connected: runtime?.connected ?? snapshot?.connected ?? null,
         lastEventAt: running ? getCurrentTimestamp() : persistedLastEventAt,
+        lastConnectedAt: runtime?.lastConnectedAt ?? snapshot?.lastConnectedAt ?? null,
+        lastInboundAt: runtime?.lastInboundAt ?? snapshot?.lastInboundAt ?? null,
         lastStartAt: runtime?.lastStartAt ?? snapshot?.lastStartAt ?? null,
         lastStopAt: runtime?.lastStopAt ?? snapshot?.lastStopAt ?? null,
         lastError: runtime?.lastError ?? snapshot?.lastError ?? null,

package/src/config-schema.ts

@@ -7,65 +7,78 @@ const AckReactionSchema = z.union([
   z.string().min(1),
 ]);
 
+const CardStreamingModeSchema = z.enum(["off", "answer", "all"]);
+const ContextVisibilitySchema = z.enum(["all", "allowlist", "allowlist_quote"]);
+
+/**
+ * Runtime-parsed DingTalk account config.
+ *
+ * Compatibility note:
+ * - `agentId`, `corpId`, `showThinkingStream`, and `asyncMode` are intentionally
+ *   not parsed here. They remain only in manifest metadata for legacy host/UI
+ *   compatibility and are ignored by the current runtime.
+ */
 const DingTalkAccountConfigShape = {
   /** Account name (optional display name) */
   name: z.string().optional(),
 
-  /** Whether this channel is enabled */
+  /** Enable or disable this DingTalk channel/account without deleting saved credentials. */
   enabled: z.boolean().optional().default(true),
 
-  /** DingTalk App Key (Client ID) - required for authentication */
+  /** DingTalk App Key (Client ID) used to authenticate API and Stream connections. */
   clientId: z.string().optional(),
 
-  /** DingTalk App Secret (Client Secret) - required for authentication */
+  /** DingTalk App Secret (Client Secret) used to obtain DingTalk access tokens. */
   clientSecret: z.string().optional(),
 
-  /** Direct message policy: open, pairing, or allowlist */
+  /** Direct-message access policy: open, pairing, or allowlist. */
   dmPolicy: z.enum(["open", "pairing", "allowlist"]).optional().default("open"),
 
-  /** Group message policy: open, allowlist, or disabled */
+  /** Group-message access policy: open, allowlist, or disabled. */
   groupPolicy: z.enum(["open", "allowlist", "disabled"]).optional().default("open"),
 
-  /** List of allowed user IDs for allowlist policy */
+  /** User IDs allowed when `dmPolicy` is `allowlist`. */
   allowFrom: z.array(z.string()).optional(),
 
-  /** List of allowed user IDs for group allowlist policy */
+  /** Sender IDs allowed when `groupPolicy` is `allowlist`. */
   groupAllowFrom: z.array(z.string()).optional(),
 
-  /** Default disabled. Enabling "all" allows learned displayName lookup but may misroute on stale/duplicate names and is available to all callers until upstream exposes requester authz context. */
+  /** Default disabled. Enabling `all` allows learned displayName lookup but may misroute on stale or duplicate names and is available to all callers until upstream exposes requester authz context. */
   displayNameResolution: z.enum(["disabled", "all"]).optional().default("disabled"),
 
+  /** Controls how much supplemental host context remains visible to the reply runtime. `allowlist_quote` is the safest advanced mode when only explicit quotes or replies should remain visible. */
+  contextVisibility: ContextVisibilitySchema.optional(),
+
+  /** Allowed remote media download hosts, IPs, or CIDRs for media fetches. */
   mediaUrlAllowlist: z.array(z.string()).optional(),
 
-  /** Native ack reaction mode: off, emoji, or kaomoji */
+  /** Native acknowledgement reaction mode: off, emoji, kaomoji, or a custom compatibility string. */
   ackReaction: AckReactionSchema.optional(),
 
+  /** Retention window in days for short-lived message context used by quoting and media recovery. */
   journalTTLDays: z.number().int().min(1).optional().default(DEFAULT_MESSAGE_CONTEXT_TTL_DAYS),
-  /** Enable debug logging */
+  /** Enable verbose DingTalk channel debug logging. */
   debug: z.boolean().optional().default(false),
 
-  /** Message type for replies: markdown or card */
+  /** Default reply delivery mode: markdown or card. */
   messageType: z.enum(["markdown", "card"]).optional().default("markdown"),
 
-  /** Card template ID for AI interactive cards
-   * obtain the template ID from DingTalk Developer Console.
-   * ref: https://github.com/soimy/openclaw-channel-dingtalk/blob/main/README.md#3-%E5%BB%BA%E7%AB%8B%E5%8D%A1%E7%89%87%E6%A8%A1%E6%9D%BF%E5%8F%AF%E9%80%89
-   */
+  /** Deprecated and ignored. AI card replies now always use the built-in DingTalk template contract. Keep only for backward-compatible config parsing. */
   cardTemplateId: z.string().optional(),
 
-  /** Card template key for streaming updates
-   * Default: 'content' - maps to the content field in the card template
-   * This key is used in the streaming API to update specific fields in the card.
-   */
+  /** Deprecated and ignored. The built-in AI card contract owns the streaming field mapping. Keep only for backward-compatible config parsing. */
   cardTemplateKey: z.string().optional().default("content"),
 
-  /** Per-group configuration, keyed by conversationId (supports "*" wildcard) */
+  /** Per-group overrides keyed by conversationId. Supports `*` as a wildcard fallback. */
   groups: z
     .record(
       z.string(),
       z.object({
+        /** Additional system prompt appended for this group. */
         systemPrompt: z.string().optional(),
+        /** Require an explicit @mention before the bot answers in this group. */
         requireMention: z.boolean().optional(),
+        /** Optional per-group sender allowlist for tighter access control than the channel default. */
         groupAllowFrom: z.array(z.string()).optional(),
       }),
     )
@@ -73,59 +86,70 @@ const DingTalkAccountConfigShape = {
 
   /** Connection robustness configuration */
 
-  /** Maximum number of connection attempts before giving up (default: 10) */
+  /** Maximum connection attempts in a single reconnect cycle before backing off or giving up. */
   maxConnectionAttempts: z.number().int().min(1).optional().default(10),
 
-  /** Initial reconnection delay in milliseconds (default: 1000ms) */
+  /** Initial reconnect backoff delay in milliseconds. */
   initialReconnectDelay: z.number().int().min(100).optional().default(1000),
 
-  /** Maximum reconnection delay in milliseconds for exponential backoff (default: 60000ms = 1 minute) */
+  /** Upper bound for reconnect backoff delay in milliseconds. */
   maxReconnectDelay: z.number().int().min(1000).optional().default(60000),
 
-  /** Jitter factor for reconnection delay randomization (0-1, default: 0.3) */
+  /** Randomization factor added to reconnect backoff to avoid synchronized reconnect storms. */
   reconnectJitter: z.number().min(0).max(1).optional().default(0.3),
 
-  /** Maximum number of runtime reconnect cycles before giving up (default: 10) */
+  /** Maximum reconnect cycles before the channel stops retrying and waits for the next lifecycle restart. */
   maxReconnectCycles: z.number().int().min(1).optional().default(10),
 
-  /** Maximum time (ms) for a single reconnect cycle before starting a new cycle (default: 50000) */
+  /** Time limit in milliseconds for one reconnect cycle before starting a fresh cycle. */
   reconnectDeadlineMs: z.number().int().min(5000).optional().default(50000),
 
-  /** Whether to use ConnectionManager (default: true). When false, rely on DWClient native keepAlive+autoReconnect. */
+  /** Enable the plugin connection manager. Disable only when you intentionally rely on DWClient native keepAlive plus autoReconnect behavior. */
   useConnectionManager: z.boolean().optional().default(true),
 
-  /** Maximum inbound media file size in MB (overrides runtime default when set) */
+  /** Maximum inbound media size in MB accepted by the plugin. When omitted, the runtime default is used. */
   mediaMaxMb: z.number().int().min(1).optional(),
 
-  /** Whether to enable underlying stream keepAlive heartbeat; defaults to !useConnectionManager when omitted */
+  /** Enable the underlying Stream client heartbeat. When omitted, runtime derives a default from `useConnectionManager`. */
   keepAlive: z.boolean().optional(),
-  /** Bypass system/global HTTP(S) proxy for DingTalk outbound send/card/upload APIs */
+  /** Bypass global or system HTTP(S) proxy settings for DingTalk send, upload, and card APIs. */
   bypassProxyForSend: z.boolean().optional().default(false),
+  /** Controls the proactive-send permission reminder shown when a conversation has not granted send rights yet. */
   proactivePermissionHint: z
     .object({
+      /** Show the proactive-send permission hint when the runtime detects missing DingTalk proactive permission. */
       enabled: z.boolean().optional().default(true),
+      /** Minimum cooldown in hours before the same proactive permission hint can be shown again. */
       cooldownHours: z.number().int().min(1).max(24 * 30).optional().default(24),
     })
     .optional()
     .default({ enabled: true, cooldownHours: 24 }),
 
-  /** Enable real-time card streaming (default: false).
-   *  When true, card updates are streamed per-token with 300ms throttle for a smoother experience, at the cost of more API calls. */
-  cardRealTimeStream: z.boolean().optional().default(false),
+  /** Deprecated compatibility flag. When true and `cardStreamingMode` is unset, runtime resolves to `cardStreamingMode: "all"`. Do not use in new configs. */
+  cardRealTimeStream: z.boolean().optional(),
+
+  /** Card streaming mode:
+   *  - off: disable incremental streaming
+   *  - answer: stream answer text
+   *  - all: stream answer + reasoning or thinking text */
+  cardStreamingMode: CardStreamingModeSchema.optional(),
+
+  /** Throttle interval in milliseconds between AI card streaming updates. */
+  cardStreamInterval: z.number().int().min(200).optional().default(1000),
 
-  /** AICard degrade duration in milliseconds after trigger errors (default: 30 minutes) */
+  /** Cooldown window in milliseconds after AI card trigger errors. Replies fall back to non-card delivery during this period. */
   aicardDegradeMs: z.number().int().min(60_000).optional().default(30 * 60 * 1000),
 
-  /** Enable local learning loop (default: false) */
+  /** Enable the local feedback-learning loop for notes, reflections, and command-assisted learning. */
   learningEnabled: z.boolean().optional(),
 
-  /** Auto-apply generated reflections into session notes/global rules (default: false) */
+  /** Automatically apply generated learning output into session notes or global rules when available. */
   learningAutoApply: z.boolean().optional(),
 
-  /** Session learning note TTL in milliseconds (default: 6 hours) */
+  /** Retention window in milliseconds for temporary learning notes. */
   learningNoteTtlMs: z.number().int().min(60_000).optional(),
 
-  /** Whether to convert markdown tables to plain text for better rendering on some clients (default: true) */
+  /** Convert markdown tables to plain text before sending when you want more consistent DingTalk rendering. */
   convertMarkdownTables: z.boolean().optional().default(true),
 
   /** @mention the sender after card finalization in group chats.

package/src/config.ts

@@ -26,12 +26,34 @@ function normalizeLearningConfig(
     learningNoteTtlMs: options.applyDefaults
       ? config.learningNoteTtlMs ?? DEFAULT_LEARNING_NOTE_TTL_MS
       : config.learningNoteTtlMs,
+    cardStreamingMode: options.applyDefaults
+      ? (config.cardStreamingMode ?? (config.cardRealTimeStream === true ? "all" : "off"))
+      : config.cardStreamingMode,
   };
 }
 
 function stripRemovedLegacyFields(config: DingTalkConfig): DingTalkConfig {
-  const { verboseRealtimeStream: _verboseRealtimeStream, ...rest } =
-    config as DingTalkConfig & { verboseRealtimeStream?: unknown };
+  const {
+    verboseRealtimeStream: _verboseRealtimeStream,
+    cardStreamReasoning: _cardStreamReasoning,
+    accounts,
+    ...rest
+  } = config as DingTalkConfig & {
+    verboseRealtimeStream?: unknown;
+    cardStreamReasoning?: unknown;
+    accounts?: Record<string, DingTalkConfig | undefined>;
+  };
+  const sanitizedAccounts = accounts
+    ? Object.fromEntries(
+        Object.entries(accounts).map(([accountId, accountConfig]) => [
+          accountId,
+          accountConfig ? stripRemovedLegacyFields(accountConfig) : accountConfig,
+        ]),
+      )
+    : undefined;
+  if (sanitizedAccounts) {
+    return { ...rest, accounts: sanitizedAccounts } as DingTalkConfig;
+  }
   return rest as DingTalkConfig;
 }
 
@@ -84,7 +106,7 @@ export function getConfig(cfg: OpenClawConfig, accountId?: string): DingTalkConf
   }
 
   if (dingtalkCfg.accounts && Object.keys(dingtalkCfg.accounts).length > 0) {
-    return dingtalkCfg;
+    return stripRemovedLegacyFields(dingtalkCfg);
   }
 
   return stripRemovedLegacyFields(normalizeLearningConfig(dingtalkCfg, { applyDefaults: true }));