@yaoyuanchao/dingtalk 1.4.19 → 1.5.0

package/CHANGELOG.md

@@ -5,6 +5,27 @@ 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).
 
+## [1.5.0] - 2026-01-31
+
+### 🎉 New Feature: Typing Indicator with Auto-Recall
+
+- **Typing Indicator** — When processing a message, automatically sends "⏳ 思考中..." which is silently recalled when the reply is ready. Much better UX than the old `showThinking` option.
+- **Message Recall APIs** — New functions in `api.ts`:
+  - `sendDMMessageWithKey()` — Send DM and return processQueryKey for recall
+  - `sendGroupMessageWithKey()` — Send group message and return processQueryKey
+  - `recallDMMessages()` — Batch recall DM messages
+  - `recallGroupMessages()` — Batch recall group messages
+  - `sendTypingIndicator()` — One-stop helper that returns a cleanup function
+
+### Configuration
+
+- `typingIndicator: false` — Disable typing indicator (default: enabled)
+- `typingIndicatorMessage: "xxx"` — Customize the thinking message
+
+### Changed
+
+- Deprecated `showThinking` option (still works as fallback if `typingIndicator` is explicitly disabled)
+
 ## [1.4.10] - 2026-01-30
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yaoyuanchao/dingtalk",
-  "version": "1.4.19",
+  "version": "1.5.0",
   "type": "module",
   "description": "DingTalk channel plugin for Clawdbot with Stream Mode support",
   "license": "MIT",

package/src/api.ts

@@ -689,3 +689,267 @@ export function textToMarkdownFile(text: string, title?: string): { buffer: Buff
 
   return { buffer, fileName };
 }
+
+// ============================================================================
+// Message Recall (撤回) APIs
+// ============================================================================
+
+/**
+ * Send a DM message and return the processQueryKey for later recall
+ * This is an enhanced version that returns the message ID
+ */
+export async function sendDMMessageWithKey(params: {
+  clientId: string;
+  clientSecret: string;
+  robotCode: string;
+  userId: string;
+  text: string;
+  format?: 'text' | 'markdown';
+}): Promise<{ ok: boolean; processQueryKey?: string; error?: string }> {
+  try {
+    const token = await getDingTalkAccessToken(params.clientId, params.clientSecret);
+    const headers = { "x-acs-dingtalk-access-token": token };
+
+    const useMarkdown = params.format !== 'text';
+    const msgKey = useMarkdown ? 'sampleMarkdown' : 'sampleText';
+    const msgParam = useMarkdown
+      ? JSON.stringify({ title: 'AI', text: params.text })
+      : JSON.stringify({ content: params.text });
+
+    const res = await jsonPost(
+      `${DINGTALK_API_BASE}/robot/oToMessages/batchSend`,
+      {
+        robotCode: params.robotCode,
+        userIds: [params.userId],
+        msgKey,
+        msgParam,
+      },
+      headers,
+    );
+
+    if (res?.code || (res?.errcode && res.errcode !== 0)) {
+      console.warn(`[dingtalk] DM send error:`, res);
+      return { ok: false, error: res.message || res.errmsg };
+    }
+
+    return { 
+      ok: true, 
+      processQueryKey: res.processQueryKey 
+    };
+  } catch (err) {
+    console.warn(`[dingtalk] Error sending DM:`, err);
+    return { ok: false, error: String(err) };
+  }
+}
+
+/**
+ * Send a group message and return the processQueryKey for later recall
+ */
+export async function sendGroupMessageWithKey(params: {
+  clientId: string;
+  clientSecret: string;
+  robotCode: string;
+  conversationId: string;
+  text: string;
+  format?: 'text' | 'markdown';
+}): Promise<{ ok: boolean; processQueryKey?: string; error?: string }> {
+  try {
+    const token = await getDingTalkAccessToken(params.clientId, params.clientSecret);
+    const headers = { "x-acs-dingtalk-access-token": token };
+
+    const useMarkdown = params.format !== 'text';
+    const msgKey = useMarkdown ? 'sampleMarkdown' : 'sampleText';
+    const msgParam = useMarkdown
+      ? JSON.stringify({ title: 'AI', text: params.text })
+      : JSON.stringify({ content: params.text });
+
+    const res = await jsonPost(
+      `${DINGTALK_API_BASE}/robot/groupMessages/send`,
+      {
+        robotCode: params.robotCode,
+        openConversationId: params.conversationId,
+        msgKey,
+        msgParam,
+      },
+      headers,
+    );
+
+    if (res?.code || (res?.errcode && res.errcode !== 0)) {
+      console.warn(`[dingtalk] Group send error:`, res);
+      return { ok: false, error: res.message || res.errmsg };
+    }
+
+    return { 
+      ok: true, 
+      processQueryKey: res.processQueryKey 
+    };
+  } catch (err) {
+    console.warn(`[dingtalk] Error sending group message:`, err);
+    return { ok: false, error: String(err) };
+  }
+}
+
+/**
+ * Recall (撤回) DM messages
+ * Note: This is a "silent recall" - the message just disappears without notification
+ */
+export async function recallDMMessages(params: {
+  clientId: string;
+  clientSecret: string;
+  robotCode: string;
+  userId: string;
+  processQueryKeys: string[];
+}): Promise<{ ok: boolean; successKeys?: string[]; failedKeys?: Record<string, string>; error?: string }> {
+  try {
+    const token = await getDingTalkAccessToken(params.clientId, params.clientSecret);
+    const headers = { "x-acs-dingtalk-access-token": token };
+
+    const res = await jsonPost(
+      `${DINGTALK_API_BASE}/robot/otoMessages/batchRecall`,
+      {
+        robotCode: params.robotCode,
+        chatBotUserId: params.userId,
+        processQueryKeys: params.processQueryKeys,
+      },
+      headers,
+    );
+
+    if (res?.code || (res?.errcode && res.errcode !== 0)) {
+      console.warn(`[dingtalk] DM recall error:`, res);
+      return { ok: false, error: res.message || res.errmsg };
+    }
+
+    return { 
+      ok: true, 
+      successKeys: res.successResult,
+      failedKeys: res.failedResult,
+    };
+  } catch (err) {
+    console.warn(`[dingtalk] Error recalling DM:`, err);
+    return { ok: false, error: String(err) };
+  }
+}
+
+/**
+ * Recall (撤回) group messages
+ */
+export async function recallGroupMessages(params: {
+  clientId: string;
+  clientSecret: string;
+  robotCode: string;
+  conversationId: string;
+  processQueryKeys: string[];
+}): Promise<{ ok: boolean; successKeys?: string[]; failedKeys?: Record<string, string>; error?: string }> {
+  try {
+    const token = await getDingTalkAccessToken(params.clientId, params.clientSecret);
+    const headers = { "x-acs-dingtalk-access-token": token };
+
+    const res = await jsonPost(
+      `${DINGTALK_API_BASE}/robot/groupMessages/recall`,
+      {
+        robotCode: params.robotCode,
+        openConversationId: params.conversationId,
+        processQueryKeys: params.processQueryKeys,
+      },
+      headers,
+    );
+
+    if (res?.code || (res?.errcode && res.errcode !== 0)) {
+      console.warn(`[dingtalk] Group recall error:`, res);
+      return { ok: false, error: res.message || res.errmsg };
+    }
+
+    return { 
+      ok: true, 
+      successKeys: res.successResult,
+      failedKeys: res.failedResult,
+    };
+  } catch (err) {
+    console.warn(`[dingtalk] Error recalling group message:`, err);
+    return { ok: false, error: String(err) };
+  }
+}
+
+/**
+ * Typing indicator helper - sends a "thinking" message that will be recalled
+ * Returns a cleanup function to recall the message
+ */
+export async function sendTypingIndicator(params: {
+  clientId: string;
+  clientSecret: string;
+  robotCode: string;
+  userId?: string;
+  conversationId?: string;
+  message?: string;
+}): Promise<{ cleanup: () => Promise<void>; error?: string }> {
+  const typingMessage = params.message || "⏳ 思考中...";
+  
+  try {
+    if (params.userId) {
+      const result = await sendDMMessageWithKey({
+        clientId: params.clientId,
+        clientSecret: params.clientSecret,
+        robotCode: params.robotCode,
+        userId: params.userId,
+        text: typingMessage,
+        format: 'text',
+      });
+
+      if (!result.ok || !result.processQueryKey) {
+        return { 
+          cleanup: async () => {}, 
+          error: result.error || "Failed to send typing indicator" 
+        };
+      }
+
+      const processQueryKey = result.processQueryKey;
+      return {
+        cleanup: async () => {
+          await recallDMMessages({
+            clientId: params.clientId,
+            clientSecret: params.clientSecret,
+            robotCode: params.robotCode,
+            userId: params.userId!,
+            processQueryKeys: [processQueryKey],
+          });
+        }
+      };
+    }
+
+    if (params.conversationId) {
+      const result = await sendGroupMessageWithKey({
+        clientId: params.clientId,
+        clientSecret: params.clientSecret,
+        robotCode: params.robotCode,
+        conversationId: params.conversationId,
+        text: typingMessage,
+        format: 'text',
+      });
+
+      if (!result.ok || !result.processQueryKey) {
+        return { 
+          cleanup: async () => {}, 
+          error: result.error || "Failed to send typing indicator" 
+        };
+      }
+
+      const processQueryKey = result.processQueryKey;
+      return {
+        cleanup: async () => {
+          await recallGroupMessages({
+            clientId: params.clientId,
+            clientSecret: params.clientSecret,
+            robotCode: params.robotCode,
+            conversationId: params.conversationId!,
+            processQueryKeys: [processQueryKey],
+          });
+        }
+      };
+    }
+
+    return { cleanup: async () => {}, error: "Either userId or conversationId required" };
+  } catch (err) {
+    console.warn(`[dingtalk] Error sending typing indicator:`, err);
+    return { cleanup: async () => {}, error: String(err) };
+  }
+}

package/src/config-schema.ts

@@ -83,6 +83,15 @@ export const dingTalkConfigSchema = z.object({
     ),
   longTextThreshold: z.number().int().positive().default(8000).optional()
     .describe('Character threshold for longTextMode=file (default 8000)'),
+
+  // 消息聚合
+  messageAggregation: z.boolean().default(true)
+    .describe(
+      'Aggregate messages from the same sender within a short time window.\n' +
+      'Useful when DingTalk splits link cards into multiple messages.'
+    ),
+  messageAggregationDelayMs: z.number().int().positive().default(2000).optional()
+    .describe('Time window in milliseconds to wait for additional messages (default 2000)'),
 }).strict();
 
 // 导出配置类型

package/src/monitor.ts

@@ -1,7 +1,36 @@
 import type { DingTalkRobotMessage, ResolvedDingTalkAccount, ExtractedMessage } from "./types.js";
-import { sendViaSessionWebhook, sendMarkdownViaSessionWebhook, sendDingTalkRestMessage, batchGetUserInfo, downloadPicture, downloadMediaFile, cleanupOldMedia, uploadMediaFile, sendFileMessage, textToMarkdownFile } from "./api.js";
+import { sendViaSessionWebhook, sendMarkdownViaSessionWebhook, sendDingTalkRestMessage, batchGetUserInfo, downloadPicture, downloadMediaFile, cleanupOldMedia, uploadMediaFile, sendFileMessage, textToMarkdownFile, sendTypingIndicator } from "./api.js";
 import { getDingTalkRuntime } from "./runtime.js";
 
+// ============================================================================
+// Message Aggregation Buffer
+// ============================================================================
+// When users share links via DingTalk's "share link" feature, the message may
+// arrive as multiple separate messages (text + URL). This buffer aggregates
+// messages from the same sender within a short time window.
+
+interface BufferedMessage {
+  messages: Array<{ text: string; timestamp: number; mediaPath?: string; mediaType?: string }>;
+  timer: ReturnType<typeof setTimeout>;
+  ctx: DingTalkMonitorContext;
+  msg: DingTalkRobotMessage;  // Keep latest msg for reply target
+  replyTarget: any;
+  sessionKey: string;
+  isDm: boolean;
+  senderId: string;
+  senderName: string;
+  conversationId: string;
+}
+
+const messageBuffer = new Map<string, BufferedMessage>();
+const AGGREGATION_DELAY_MS = 2000; // 2 seconds - balance between UX and catching split messages
+
+function getBufferKey(msg: DingTalkRobotMessage, accountId: string): string {
+  return `${accountId}:${msg.conversationId}:${msg.senderId || msg.senderStaffId}`;
+}
+
+// ============================================================================
+
 export interface DingTalkMonitorContext {
   account: ResolvedDingTalkAccount;
   cfg: any;
@@ -696,11 +725,168 @@ async function processInboundMessage(
     account,
   };
 
-  // Send thinking feedback (opt-in)
-  if (account.config.showThinking && msg.sessionWebhook) {
+  // Check if message aggregation is enabled
+  const aggregationEnabled = account.config.messageAggregation !== false;
+  const aggregationDelayMs = account.config.messageAggregationDelayMs ?? AGGREGATION_DELAY_MS;
+
+  if (aggregationEnabled) {
+    // Buffer this message for aggregation
+    await bufferMessageForAggregation({
+      msg, ctx, rawBody, replyTarget, sessionKey, isDm, senderId, senderName, conversationId,
+      mediaPath, mediaType,
+    });
+    return; // Actual dispatch happens when timer fires
+  }
+
+  // No aggregation - dispatch immediately
+  await dispatchMessage({
+    ctx, msg, rawBody, replyTarget, sessionKey, isDm, senderId, senderName, conversationId,
+    mediaPath, mediaType,
+  });
+}
+
+/**
+ * Buffer a message for aggregation with other messages from the same sender.
+ */
+async function bufferMessageForAggregation(params: {
+  msg: DingTalkRobotMessage;
+  ctx: DingTalkMonitorContext;
+  rawBody: string;
+  replyTarget: any;
+  sessionKey: string;
+  isDm: boolean;
+  senderId: string;
+  senderName: string;
+  conversationId: string;
+  mediaPath?: string;
+  mediaType?: string;
+}): Promise<void> {
+  const { msg, ctx, rawBody, replyTarget, sessionKey, isDm, senderId, senderName, conversationId, mediaPath, mediaType } = params;
+  const { account, log } = ctx;
+  const bufferKey = getBufferKey(msg, account.accountId);
+  const aggregationDelayMs = account.config.messageAggregationDelayMs ?? AGGREGATION_DELAY_MS;
+
+  const existing = messageBuffer.get(bufferKey);
+
+  if (existing) {
+    // Add to existing buffer
+    existing.messages.push({ text: rawBody, timestamp: Date.now(), mediaPath, mediaType });
+    // Update to latest msg for reply target (use latest sessionWebhook)
+    existing.msg = msg;
+    existing.replyTarget = replyTarget;
+
+    // Reset timer
+    clearTimeout(existing.timer);
+    existing.timer = setTimeout(() => {
+      flushMessageBuffer(bufferKey);
+    }, aggregationDelayMs);
+
+    log?.info?.(`[dingtalk] Message buffered, total: ${existing.messages.length} messages`);
+  } else {
+    // Create new buffer entry
+    const newEntry: BufferedMessage = {
+      messages: [{ text: rawBody, timestamp: Date.now(), mediaPath, mediaType }],
+      timer: setTimeout(() => {
+        flushMessageBuffer(bufferKey);
+      }, aggregationDelayMs),
+      ctx,
+      msg,
+      replyTarget,
+      sessionKey,
+      isDm,
+      senderId,
+      senderName,
+      conversationId,
+    };
+    messageBuffer.set(bufferKey, newEntry);
+
+    log?.info?.(`[dingtalk] Message buffered (new), waiting ${aggregationDelayMs}ms for more...`);
+  }
+}
+
+/**
+ * Flush the message buffer and dispatch the combined message.
+ */
+async function flushMessageBuffer(bufferKey: string): Promise<void> {
+  const entry = messageBuffer.get(bufferKey);
+  if (!entry) return;
+
+  messageBuffer.delete(bufferKey);
+
+  const { messages, ctx, msg, replyTarget, sessionKey, isDm, senderId, senderName, conversationId } = entry;
+  const { log } = ctx;
+
+  // Combine all messages
+  const combinedText = messages.map(m => m.text).join('\n');
+  // Use the last media if any
+  const lastWithMedia = [...messages].reverse().find(m => m.mediaPath);
+  const mediaPath = lastWithMedia?.mediaPath;
+  const mediaType = lastWithMedia?.mediaType;
+
+  log?.info?.(`[dingtalk] Flushing buffer: ${messages.length} message(s) combined into ${combinedText.length} chars`);
+
+  // Dispatch the combined message
+  await dispatchMessage({
+    ctx, msg, rawBody: combinedText, replyTarget, sessionKey, isDm, senderId, senderName, conversationId,
+    mediaPath, mediaType,
+  });
+}
+
+/**
+ * Dispatch a message to the agent (after aggregation or immediately).
+ */
+async function dispatchMessage(params: {
+  ctx: DingTalkMonitorContext;
+  msg: DingTalkRobotMessage;
+  rawBody: string;
+  replyTarget: any;
+  sessionKey: string;
+  isDm: boolean;
+  senderId: string;
+  senderName: string;
+  conversationId: string;
+  mediaPath?: string;
+  mediaType?: string;
+}): Promise<void> {
+  const { ctx, msg, rawBody, replyTarget, sessionKey, isDm, senderId, senderName, conversationId, mediaPath, mediaType } = params;
+  const { account, cfg, log, setStatus } = ctx;
+  const runtime = getDingTalkRuntime();
+  const isGroup = !isDm;
+
+  // Typing indicator cleanup function (will be called after dispatch completes)
+  let typingCleanup: (() => Promise<void>) | null = null;
+
+  // Send typing indicator (recallable) if enabled
+  // This replaces the old showThinking feature with a better UX - the indicator disappears when reply arrives
+  if (account.config.typingIndicator !== false && account.clientId && account.clientSecret) {
+    try {
+      const typingMessage = account.config.typingIndicatorMessage || '⏳ 思考中...';
+      const robotCode = account.robotCode || account.clientId;
+      
+      const result = await sendTypingIndicator({
+        clientId: account.clientId,
+        clientSecret: account.clientSecret,
+        robotCode,
+        userId: isDm ? senderId : undefined,
+        conversationId: !isDm ? conversationId : undefined,
+        message: typingMessage,
+      });
+      
+      if (result.error) {
+        log?.info?.('[dingtalk] Typing indicator failed: ' + result.error);
+      } else {
+        typingCleanup = result.cleanup;
+        log?.info?.('[dingtalk] Typing indicator sent (will be recalled on reply)');
+      }
+    } catch (err) {
+      log?.info?.('[dingtalk] Typing indicator error: ' + err);
+    }
+  }
+  // Legacy: Send thinking feedback (opt-in, non-recallable) - only if typingIndicator is explicitly disabled
+  else if (account.config.showThinking && replyTarget.sessionWebhook) {
     try {
-      await sendViaSessionWebhook(msg.sessionWebhook, '正在思考...');
-      log?.info?.('[dingtalk] Sent thinking indicator');
+      await sendViaSessionWebhook(replyTarget.sessionWebhook, '正在思考...');
+      log?.info?.('[dingtalk] Sent thinking indicator (legacy, non-recallable)');
     } catch (_) {
       // fire-and-forget, don't block processing
     }
@@ -724,6 +910,20 @@ async function processInboundMessage(
     runtime?.channel?.reply?.dispatchReplyFromConfig
   );
 
+  // Track if we've already cleaned up the typing indicator
+  let typingCleaned = false;
+  const cleanupTyping = async () => {
+    if (typingCleanup && !typingCleaned) {
+      typingCleaned = true;
+      try {
+        await typingCleanup();
+        log?.info?.('[dingtalk] Typing indicator recalled');
+      } catch (err) {
+        log?.info?.('[dingtalk] Failed to recall typing indicator: ' + err);
+      }
+    }
+  };
+
   try {
     if (hasFullPipeline) {
       // Full SDK pipeline: route → session → envelope → dispatch
@@ -731,6 +931,7 @@ async function processInboundMessage(
         runtime, msg, rawBody, account, cfg: actualCfg, sessionKey, isDm,
         senderId, senderName, conversationId, replyTarget,
         mediaPath, mediaType, log, setStatus,
+        onFirstReply: cleanupTyping,
       });
     } else if (runtime?.channel?.reply?.dispatchReplyWithBufferedBlockDispatcher) {
       // Fallback: existing buffered block dispatcher
@@ -763,6 +964,9 @@ async function processInboundMessage(
         cfg: actualCfg,
         dispatcherOptions: {
           deliver: async (payload: any) => {
+            // Recall typing indicator on first delivery
+            await cleanupTyping();
+            
             log?.info?.("[dingtalk] Deliver payload keys: " + Object.keys(payload || {}).join(',') + " text?=" + (typeof payload?.text) + " markdown?=" + (typeof payload?.markdown));
             const textToSend = resolveDeliverText(payload, log);
             if (textToSend) {
@@ -773,10 +977,13 @@ async function processInboundMessage(
             }
           },
           onError: (err: any) => {
+            // Also cleanup on error
+            cleanupTyping().catch(() => {});
             log?.info?.("[dingtalk] Reply error: " + err);
           },
         },
       }).catch((err) => {
+        cleanupTyping().catch(() => {});
         log?.info?.("[dingtalk] Dispatch failed: " + err);
       });
 
@@ -784,8 +991,10 @@ async function processInboundMessage(
       runtime.channel?.activity?.record?.('dingtalk', account.accountId, 'message');
     } else {
       log?.info?.("[dingtalk] Runtime dispatch not available");
+      await cleanupTyping();
     }
   } catch (err) {
+    await cleanupTyping();
     log?.info?.("[dingtalk] Dispatch error: " + err);
   }
 }
@@ -810,10 +1019,13 @@ async function dispatchWithFullPipeline(params: {
   mediaType?: string;
   log?: any;
   setStatus?: (update: Record<string, unknown>) => void;
+  onFirstReply?: () => Promise<void>;
 }): Promise<void> {
   const { runtime: rt, msg, rawBody, account, cfg, isDm,
           senderId, senderName, conversationId, replyTarget,
-          log, setStatus } = params;
+          log, setStatus, onFirstReply } = params;
+  
+  let firstReplyFired = false;
 
   // 1. Resolve agent route
   const route = rt.channel.routing.resolveAgentRoute({
@@ -868,6 +1080,14 @@ async function dispatchWithFullPipeline(params: {
   const { dispatcher, replyOptions, markDispatchIdle } = rt.channel.reply.createReplyDispatcherWithTyping({
     responsePrefix: '',
     deliver: async (payload: any) => {
+      // Recall typing indicator on first delivery
+      if (!firstReplyFired && onFirstReply) {
+        firstReplyFired = true;
+        await onFirstReply().catch((err) => {
+          log?.info?.("[dingtalk] onFirstReply error: " + err);
+        });
+      }
+      
       try {
         log?.info?.("[dingtalk] Pipeline deliver payload keys: " + Object.keys(payload || {}).join(',') + " text?=" + (typeof payload?.text) + " markdown?=" + (typeof payload?.markdown));
         const textToSend = resolveDeliverText(payload, log);
@@ -890,6 +1110,10 @@ async function dispatchWithFullPipeline(params: {
     await rt.channel.reply.dispatchReplyFromConfig({ ctx, cfg, dispatcher, replyOptions });
   } finally {
     markDispatchIdle();
+    // Ensure typing indicator is cleaned up even if no reply was sent
+    if (!firstReplyFired && onFirstReply) {
+      await onFirstReply().catch(() => {});
+    }
   }
 
   // 10. Record activity