@soimy/dingtalk 3.2.0 → 3.4.0

package/src/types.ts

@@ -17,6 +17,12 @@ import type {
   ChannelGatewayContext as SDKChannelGatewayContext,
   ChannelPlugin as SDKChannelPlugin,
 } from "openclaw/plugin-sdk";
+import { mergeAccountWithDefaults } from "./config";
+
+export type AckReactionMode = "off" | "emoji" | "kaomoji";
+// Accept arbitrary strings for backward compatibility; the recommended
+// explicit modes remain: "off" | "emoji" | "kaomoji".
+export type AckReactionConfigValue = string;
 
 export interface DingtalkPluginModule {
   id: string;
@@ -38,15 +44,18 @@ export interface DingTalkConfig extends OpenClawConfig {
   name?: string;
   enabled?: boolean;
   dmPolicy?: "open" | "pairing" | "allowlist";
-  groupPolicy?: "open" | "allowlist";
+  groupPolicy?: "open" | "allowlist" | "disabled";
   allowFrom?: string[];
+  groupAllowFrom?: string[];
+  displayNameResolution?: "disabled" | "all";
   mediaUrlAllowlist?: string[];
-  showThinking?: boolean;
+  journalTTLDays?: number;
+  ackReaction?: AckReactionConfigValue;
   debug?: boolean;
   messageType?: "markdown" | "card";
   cardTemplateId?: string;
   cardTemplateKey?: string;
-  groups?: Record<string, { systemPrompt?: string }>;
+  groups?: Record<string, { systemPrompt?: string; requireMention?: boolean; groupAllowFrom?: string[] }>;
   accounts?: Record<string, DingTalkConfig>;
   // Connection robustness configuration
   maxConnectionAttempts?: number;
@@ -55,14 +64,40 @@ export interface DingTalkConfig extends OpenClawConfig {
   reconnectJitter?: number;
   /** Maximum number of runtime reconnect cycles before giving up (default: 10) */
   maxReconnectCycles?: number;
+  /** Maximum time (ms) for a single reconnect cycle before giving up and starting a new cycle (default: 50000) */
+  reconnectDeadlineMs?: number;
   /** Whether to use ConnectionManager; when false, use DWClient native keepAlive+autoReconnect */
   useConnectionManager?: boolean;
   /** Maximum inbound media file size in MB (overrides runtime default when set) */
   mediaMaxMb?: number;
+  /** Whether to enable underlying stream keepAlive heartbeat; defaults to !useConnectionManager when omitted */
+  keepAlive?: boolean;
+  /** Bypass system/global HTTP(S) proxy for DingTalk outbound send/card/upload APIs */
+  bypassProxyForSend?: boolean;
   proactivePermissionHint?: {
     enabled?: boolean;
     cooldownHours?: number;
   };
+  /** Enable real-time card streaming (default false, true = 300ms throttled per-token updates) */
+  cardRealTimeStream?: boolean;
+  /** AICard degrade duration in milliseconds after trigger errors (default 30m) */
+  aicardDegradeMs?: number;
+  /** Enable local learning loop (events/reflections/session notes/global rules) */
+  learningEnabled?: boolean;
+  /** Auto-apply generated reflections into session notes/global rules (default false) */
+  learningAutoApply?: boolean;
+  /** Session learning note TTL in milliseconds (default 6h) */
+  learningNoteTtlMs?: number;
+  /** @deprecated Use learningEnabled */
+  feedbackLearningEnabled?: boolean;
+  /** @deprecated Use learningAutoApply */
+  feedbackLearningAutoApply?: boolean;
+  /** @deprecated Use learningNoteTtlMs */
+  feedbackLearningNoteTtlMs?: number;
+  /** Whether to convert markdown tables to plain text for better rendering on some clients (default: true) */
+  convertMarkdownTables?: boolean;
+  /** @mention the sender after card finalization in group chats; value is the message text */
+  cardAtSender?: string;
 }
 
 /**
@@ -77,15 +112,18 @@ export interface DingTalkChannelConfig {
   agentId?: string;
   name?: string;
   dmPolicy?: "open" | "pairing" | "allowlist";
-  groupPolicy?: "open" | "allowlist";
+  groupPolicy?: "open" | "allowlist" | "disabled";
   allowFrom?: string[];
+  groupAllowFrom?: string[];
+  displayNameResolution?: "disabled" | "all";
   mediaUrlAllowlist?: string[];
-  showThinking?: boolean;
+  journalTTLDays?: number;
+  ackReaction?: AckReactionConfigValue;
   debug?: boolean;
   messageType?: "markdown" | "card";
   cardTemplateId?: string;
   cardTemplateKey?: string;
-  groups?: Record<string, { systemPrompt?: string }>;
+  groups?: Record<string, { systemPrompt?: string; requireMention?: boolean; groupAllowFrom?: string[] }>;
   accounts?: Record<string, DingTalkConfig>;
   maxConnectionAttempts?: number;
   initialReconnectDelay?: number;
@@ -93,14 +131,40 @@ export interface DingTalkChannelConfig {
   reconnectJitter?: number;
   /** Maximum number of runtime reconnect cycles before giving up (default: 10) */
   maxReconnectCycles?: number;
+  /** Maximum time (ms) for a single reconnect cycle before giving up and starting a new cycle (default: 50000) */
+  reconnectDeadlineMs?: number;
   /** Whether to use ConnectionManager; when false, use DWClient native keepAlive+autoReconnect */
   useConnectionManager?: boolean;
   /** Maximum inbound media file size in MB (overrides runtime default when set) */
   mediaMaxMb?: number;
+  /** Whether to enable underlying stream keepAlive heartbeat; defaults to !useConnectionManager when omitted */
+  keepAlive?: boolean;
+  /** Bypass system/global HTTP(S) proxy for DingTalk outbound send/card/upload APIs */
+  bypassProxyForSend?: boolean;
   proactivePermissionHint?: {
     enabled?: boolean;
     cooldownHours?: number;
   };
+  /** Enable real-time card streaming (default false, true = 300ms throttled per-token updates) */
+  cardRealTimeStream?: boolean;
+  /** AICard degrade duration in milliseconds after trigger errors (default 30m) */
+  aicardDegradeMs?: number;
+  /** Enable local learning loop (events/reflections/session notes/global rules) */
+  learningEnabled?: boolean;
+  /** Auto-apply generated reflections into session notes/global rules (default false) */
+  learningAutoApply?: boolean;
+  /** Session learning note TTL in milliseconds (default 6h) */
+  learningNoteTtlMs?: number;
+  /** @deprecated Use learningEnabled */
+  feedbackLearningEnabled?: boolean;
+  /** @deprecated Use learningAutoApply */
+  feedbackLearningAutoApply?: boolean;
+  /** @deprecated Use learningNoteTtlMs */
+  feedbackLearningNoteTtlMs?: number;
+  /** Whether to convert markdown tables to plain text for better rendering on some clients (default: true) */
+  convertMarkdownTables?: boolean;
+  /** @mention the sender after card finalization in group chats; value is the message text */
+  cardAtSender?: string;
 }
 
 /**
@@ -145,6 +209,14 @@ export interface MediaFile {
   mimeType: string;
 }
 
+export interface DocInfo {
+  docId: string;
+  title: string;
+  docType: string;
+  creatorId?: string;
+  updatedAt?: number | string;
+}
+
 /**
  * DingTalk incoming message (Stream mode)
  */
@@ -152,19 +224,35 @@ export interface DingTalkInboundMessage {
   msgId: string;
   msgtype: string;
   createAt: number;
+  /**
+   * @ 提及的用户列表（消息顶层，与 text 同级）
+   * 包含通过 @picker 选中的所有真实钉钉用户和机器人
+   * 格式: [{ dingtalkId: "$:LWCP_v1:$xxx" }]
+   */
+  atUsers?: Array<{
+    dingtalkId: string;
+  }>;
   text?: {
     content: string;
     isReplyMsg?: boolean; // 是否是回复消息
     repliedMsg?: {
-      // 被回复的消息
+      msgType?: string;
+      msgId?: string;
+      senderId?: string;
+      createdAt?: number;
       content?: {
         text?: string;
+        downloadCode?: string;
+        fileName?: string;
+        biz_custom_action_url?: string;
         richText?: Array<{
           msgType?: string;
           type?: string;
           content?: string;
+          text?: string;
           code?: string;
           atName?: string;
+          downloadCode?: string;
         }>;
       };
     };
@@ -173,13 +261,17 @@ export interface DingTalkInboundMessage {
     downloadCode?: string;
     fileName?: string;
     recognition?: string;
+    spaceId?: string;
+    fileId?: string;
+    biz_custom_action_url?: string;
     richText?: Array<{
       type: string;
       text?: string;
       atName?: string;
-      downloadCode?: string; // For picture type in richText
+      atUserId?: string;
+      downloadCode?: string;
     }>;
-    quoteContent?: string; // 替代引用格式
+    quoteContent?: string;
   };
   // Legacy 引用格式
   quoteMessage?: {
@@ -191,6 +283,7 @@ export interface DingTalkInboundMessage {
   };
   // 富媒体引用，仅有消息ID的情况（包括手机端和PC端）
   originalMsgId?: string;
+  originalProcessQueryKey?: string;
   conversationType: string;
   conversationId: string;
   conversationTitle?: string;
@@ -201,14 +294,83 @@ export interface DingTalkInboundMessage {
   sessionWebhook: string;
 }
 
+export type QuotedRefKey = "msgId" | "processQueryKey" | "messageId" | "outTrackId" | "cardInstanceId";
+
+export type AttachmentTextSource = "text" | "html" | "pdf" | "docx";
+
+export interface QuotedRef {
+  targetDirection: "inbound" | "outbound";
+  key?: QuotedRefKey;
+  value?: string;
+  fallbackCreatedAt?: number;
+}
+
+/**
+ * Quoted/reply message metadata extracted from repliedMsg.
+ * Populated when isReplyMsg is true; downstream handlers use these fields
+ * to download quoted media or look up cached card content.
+ */
+export interface QuotedInfo {
+  mediaDownloadCode?: string;
+  mediaType?: string;
+  isQuotedFile?: boolean;
+  isQuotedCard?: boolean;
+  isQuotedDocCard?: boolean;
+  cardCreatedAt?: number;
+  processQueryKey?: string;
+  fileCreatedAt?: number;
+  msgId?: string;
+  previewText?: string;
+  previewMessageType?: string;
+  previewFileName?: string;
+  previewSenderId?: string;
+}
+
+/**
+ * @ 提及信息
+ */
+export interface AtMention {
+  /** @ 显示的名字（去除 @ 前缀） */
+  name: string;
+  /** 钉钉用户 ID（如果是 @ 真人） */
+  userId?: string;
+}
+
+/**
+ * Agent 名字匹配结果
+ */
+export interface AgentNameMatch {
+  /** 匹配到的 agent ID */
+  agentId: string;
+  /** 匹配来源：'name' | 'id' */
+  matchSource: "name" | "id";
+  /** 匹配到的名字 */
+  matchedName: string;
+}
+
 /**
  * Extracted message content for unified processing
  */
 export interface MessageContent {
   text: string;
   mediaPath?: string;
+  mediaPaths?: string[];
   mediaType?: string;
+  mediaTypes?: string[];
   messageType: string;
+  docSpaceId?: string;
+  docFileId?: string;
+  quoted?: QuotedInfo;
+  /** @ 提及列表（从文本或 richText 提取的名字） */
+  atMentions?: AtMention[];
+  /**
+   * 通过 @picker 选中的真实钉钉用户的 dingtalkId 列表
+   * - 仅包含真实钉钉用户和机器人，不包含 agent 名
+   * - 用于排除真人：如果 atMentions 中的名字匹配到 agent，说明是 agent；
+   *   如果没匹配到 agent 且有 atUserDingtalkIds，则可能是真人
+   * - 注意：无法将 dingtalkId 映射到具体名字，因为 webhook 不提供此映射
+   */
+  atUserDingtalkIds?: string[];
 }
 
 /**
@@ -218,14 +380,25 @@ export interface SendMessageOptions {
   title?: string;
   useMarkdown?: boolean;
   atUserId?: string | null;
-  log?: any;
+  log?: Logger;
+  conversationId?: string;
   mediaPath?: string;
   filePath?: string;
   mediaUrl?: string;
   mediaType?: "image" | "voice" | "video" | "file";
   accountId?: string;
-  cardUpdateMode?: "replace" | "append" | "finalize";
-  cardFinalize?: boolean;
+  storePath?: string;
+  cardUpdateMode?: "append";
+  quotedRef?: QuotedRef;
+  /** Force markdown/text delivery even when messageType is "card". Bypasses card
+   *  creation while preserving journal writes and other side-effects. */
+  forceMarkdown?: boolean;
+}
+
+export interface DingTalkTrackingMetadata {
+  processQueryKey?: string;
+  outTrackId?: string;
+  cardInstanceId?: string;
 }
 
 /**
@@ -246,6 +419,18 @@ export interface SessionWebhookResponse {
   };
 }
 
+/**
+ * Sub-agent routing options for parameterized message handling
+ */
+export interface SubAgentOptions {
+  /** The agent ID to route to */
+  agentId: string;
+  /** Prefix to add to response messages (e.g., "[AgentName] ") */
+  responsePrefix: string;
+  /** The matched agent name */
+  matchedName: string;
+}
+
 /**
  * Message handler parameters
  */
@@ -254,8 +439,21 @@ export interface HandleDingTalkMessageParams {
   accountId: string;
   data: DingTalkInboundMessage;
   sessionWebhook: string;
-  log?: any;
+  log?: Logger;
   dingtalkConfig: DingTalkConfig;
+  /**
+   * When set, routes message to the specified sub-agent instead of main agent.
+   * This enables reuse of the main message handling logic for sub-agents.
+   */
+  subAgentOptions?: SubAgentOptions;
+  /**
+   * Pre-downloaded media for sub-agent calls.
+   * When set, skips media download to avoid duplication in recursive calls.
+   */
+  preDownloadedMedia?: {
+    mediaPath?: string;
+    mediaType?: string;
+  };
 }
 
 /**
@@ -295,7 +493,7 @@ export interface ResolvedAccount {
 export interface AxiosRequestConfig {
   url?: string;
   method?: string;
-  data?: any;
+  data?: unknown;
   headers?: Record<string, string>;
   responseType?: "arraybuffer" | "json" | "text";
 }
@@ -303,7 +501,7 @@ export interface AxiosRequestConfig {
 /**
  * HTTP response from axios
  */
-export interface AxiosResponse<T = any> {
+export interface AxiosResponse<T = unknown> {
   data: T;
   status: number;
   statusText: string;
@@ -325,15 +523,15 @@ export interface StreamCallbackResponse {
  */
 export interface ReplyDispatchContext {
   responsePrefix?: string;
-  deliver: (payload: any) => Promise<{ ok: boolean; error?: string }>;
+  deliver: (payload: unknown) => Promise<{ ok: boolean; error?: string }>;
 }
 
 /**
  * Reply dispatcher result
  */
 export interface ReplyDispatcherResult {
-  dispatcher: any;
-  replyOptions: any;
+  dispatcher: unknown;
+  replyOptions: unknown;
   markDispatchIdle: () => void;
 }
 
@@ -343,7 +541,7 @@ export interface ReplyDispatcherResult {
 export interface RetryOptions {
   maxRetries?: number;
   baseDelayMs?: number;
-  log?: any;
+  log?: Logger;
 }
 
 /**
@@ -397,7 +595,7 @@ export interface TargetResolutionResult {
  */
 export interface ResolveTargetParams {
   to?: string | null;
-  [key: string]: any;
+  [key: string]: unknown;
 }
 
 /**
@@ -408,7 +606,7 @@ export interface SendTextParams {
   to: string;
   text: string;
   accountId?: string;
-  [key: string]: any;
+  [key: string]: unknown;
 }
 
 /**
@@ -419,7 +617,7 @@ export interface SendMediaParams {
   to: string;
   mediaPath: string;
   accountId?: string;
-  [key: string]: any;
+  [key: string]: unknown;
 }
 
 /**
@@ -428,8 +626,8 @@ export interface SendMediaParams {
 export interface DingTalkOutboundHandler {
   deliveryMode: "direct" | "queued" | "batch";
   resolveTarget: (params: ResolveTargetParams) => TargetResolutionResult;
-  sendText: (params: SendTextParams) => Promise<{ ok: boolean; data?: any; error?: any }>;
-  sendMedia?: (params: SendMediaParams) => Promise<{ ok: boolean; data?: any; error?: any }>;
+  sendText: (params: SendTextParams) => Promise<{ ok: boolean; data?: unknown; error?: unknown }>;
+  sendMedia?: (params: SendMediaParams) => Promise<{ ok: boolean; data?: unknown; error?: unknown }>;
 }
 
 /**
@@ -452,13 +650,18 @@ export type AICardState = (typeof AICardStatus)[keyof typeof AICardStatus];
  */
 export interface AICardInstance {
   cardInstanceId: string;
+  processQueryKey?: string;
   accessToken: string;
   conversationId: string;
+  contextConversationId?: string;
+  accountId?: string;
+  storePath?: string;
   createdAt: number;
   lastUpdated: number;
   state: AICardState; // Current card state: PROCESSING, INPUTING, FINISHED, FAILED
   config?: DingTalkConfig; // Store config reference for token refresh
   lastStreamedContent?: string;
+  outTrackId?: string;
 }
 
 /**
@@ -485,6 +688,14 @@ export enum ConnectionState {
   FAILED = "FAILED",
 }
 
+/**
+ * Factory function that creates a fresh DWClient with callback listeners
+ * already registered. Used by ConnectionManager to create a new client
+ * on reconnection so the new WebSocket can start receiving messages
+ * while the old zombie socket is still being cleaned up.
+ */
+export type StreamClientFactory = () => import("dingtalk-stream").DWClient;
+
 /**
  * Connection manager configuration
  */
@@ -495,6 +706,8 @@ export interface ConnectionManagerConfig {
   jitter: number;
   /** Maximum number of runtime reconnect cycles before giving up (default: 10) */
   maxReconnectCycles?: number;
+  /** Maximum time (ms) for a single reconnect cycle before giving up and starting a new cycle (default: 50000) */
+  reconnectDeadlineMs?: number;
   /** Callback invoked when connection state changes */
   onStateChange?: (state: ConnectionState, error?: string) => void;
 }
@@ -568,7 +781,10 @@ export function resolveDingTalkAccount(
       dmPolicy: dingtalk?.dmPolicy,
       groupPolicy: dingtalk?.groupPolicy,
       allowFrom: dingtalk?.allowFrom,
-      showThinking: dingtalk?.showThinking,
+      groupAllowFrom: dingtalk?.groupAllowFrom,
+      displayNameResolution: dingtalk?.displayNameResolution,
+      journalTTLDays: dingtalk?.journalTTLDays,
+      ackReaction: dingtalk?.ackReaction,
       debug: dingtalk?.debug,
       messageType: dingtalk?.messageType,
       cardTemplateId: dingtalk?.cardTemplateId,
@@ -580,9 +796,22 @@ export function resolveDingTalkAccount(
       maxReconnectDelay: dingtalk?.maxReconnectDelay,
       reconnectJitter: dingtalk?.reconnectJitter,
       maxReconnectCycles: dingtalk?.maxReconnectCycles,
+      reconnectDeadlineMs: dingtalk?.reconnectDeadlineMs,
       useConnectionManager: dingtalk?.useConnectionManager,
       mediaMaxMb: dingtalk?.mediaMaxMb,
+      keepAlive: dingtalk?.keepAlive,
+      bypassProxyForSend: dingtalk?.bypassProxyForSend,
       proactivePermissionHint: dingtalk?.proactivePermissionHint,
+      cardRealTimeStream: dingtalk?.cardRealTimeStream,
+      aicardDegradeMs: dingtalk?.aicardDegradeMs,
+      learningEnabled: dingtalk?.learningEnabled ?? dingtalk?.feedbackLearningEnabled,
+      learningAutoApply: dingtalk?.learningAutoApply ?? dingtalk?.feedbackLearningAutoApply,
+      learningNoteTtlMs: dingtalk?.learningNoteTtlMs ?? dingtalk?.feedbackLearningNoteTtlMs,
+      feedbackLearningEnabled: dingtalk?.feedbackLearningEnabled,
+      feedbackLearningAutoApply: dingtalk?.feedbackLearningAutoApply,
+      feedbackLearningNoteTtlMs: dingtalk?.feedbackLearningNoteTtlMs,
+      convertMarkdownTables: dingtalk?.convertMarkdownTables,
+      cardAtSender: dingtalk?.cardAtSender,
     };
     return {
       ...config,
@@ -591,13 +820,17 @@ export function resolveDingTalkAccount(
     };
   }
 
-  // If named account, get from accounts object
+  // If named account, merge channel-level defaults with account-level overrides
   const accountConfig = dingtalk?.accounts?.[id];
   if (accountConfig) {
+    const merged = mergeAccountWithDefaults(
+      dingtalk as DingTalkConfig,
+      accountConfig,
+    );
     return {
-      ...accountConfig,
+      ...merged,
       accountId: id,
-      configured: Boolean(accountConfig.clientId && accountConfig.clientSecret),
+      configured: Boolean(merged.clientId && merged.clientSecret),
     };
   }