@yaoyuanchao/dingtalk 1.3.5 → 1.3.7

package/CHANGELOG.md

@@ -5,6 +5,13 @@ 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.3.6] - 2026-01-28
+
+### Fixed
+
+- **Stream ACK method name** — corrected `socketResponse()` to `socketCallBackResponse()` (the actual SDK method); previous typo caused ACK to silently fail, triggering DingTalk 60-second retry
+- **Audio message handling** — skip .amr file download when DingTalk ASR recognition text is available; prevents agent from being confused by audio attachment and trying Whisper instead of reading the already-transcribed text
+
 ## [1.3.5] - 2026-01-28
 
 ### Fixed

package/package.json

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

package/src/card-api.ts

@@ -0,0 +1,562 @@
+/**
+ * DingTalk Interactive Card API
+ *
+ * 钉钉互动卡片 API 封装，支持：
+ * - 创建卡片实例
+ * - 投放卡片到会话
+ * - 普通更新卡片
+ * - 流式更新卡片（AI 打字机效果）
+ *
+ * 参考文档：
+ * - https://open.dingtalk.com/document/orgapp/api-streamingupdate
+ * - https://github.com/open-dingtalk/dingtalk-card-examples
+ */
+
+import { getDingTalkAccessToken } from "./api.js";
+
+const DINGTALK_API_BASE = "https://api.dingtalk.com/v1.0";
+
+/** HTTP POST with JSON body */
+async function jsonPost(
+  url: string,
+  body: unknown,
+  headers?: Record<string, string>,
+): Promise<any> {
+  const response = await fetch(url, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      ...headers,
+    },
+    body: JSON.stringify(body),
+  });
+
+  const text = await response.text();
+  try {
+    return JSON.parse(text);
+  } catch {
+    return { raw: text, status: response.status };
+  }
+}
+
+/** HTTP PUT with JSON body */
+async function jsonPut(
+  url: string,
+  body: unknown,
+  headers?: Record<string, string>,
+): Promise<any> {
+  const response = await fetch(url, {
+    method: "PUT",
+    headers: {
+      "Content-Type": "application/json",
+      ...headers,
+    },
+    body: JSON.stringify(body),
+  });
+
+  const text = await response.text();
+  try {
+    return JSON.parse(text);
+  } catch {
+    return { raw: text, status: response.status };
+  }
+}
+
+/** Card instance creation parameters */
+export interface CreateCardInstanceParams {
+  clientId: string;
+  clientSecret: string;
+  cardTemplateId: string;
+  outTrackId: string;
+  cardData?: {
+    cardParamMap?: Record<string, string>;
+    cardMediaIdParamMap?: Record<string, string>;
+  };
+  robotCode?: string;
+  callbackType?: "STREAM" | "HTTP";
+  userIdType?: number;
+}
+
+/** Card delivery parameters */
+export interface DeliverCardParams {
+  clientId: string;
+  clientSecret: string;
+  outTrackId: string;
+  openSpaceId: string;
+  robotCode?: string;
+  /** For group delivery */
+  imGroupOpenDeliverModel?: {
+    robotCode: string;
+    atUserIds?: Record<string, string>;
+  };
+  /** For single chat delivery */
+  imRobotOpenDeliverModel?: {
+    spaceType: "IM_ROBOT";
+    robotCode: string;
+  };
+}
+
+/** Card update parameters */
+export interface UpdateCardParams {
+  clientId: string;
+  clientSecret: string;
+  outTrackId: string;
+  cardData: {
+    cardParamMap?: Record<string, string>;
+    cardMediaIdParamMap?: Record<string, string>;
+  };
+  userIdType?: number;
+}
+
+/** Streaming update parameters (AI typewriter effect) */
+export interface StreamingUpdateParams {
+  clientId: string;
+  clientSecret: string;
+  outTrackId: string;
+  /** Unique identifier for this streaming session */
+  key: string;
+  /** Content to append */
+  content: string;
+  /** Whether this is the final update */
+  isFull?: boolean;
+  /** GUID for idempotency */
+  guid?: string;
+}
+
+/** API response with error info */
+export interface CardApiResponse {
+  success: boolean;
+  result?: any;
+  errcode?: number;
+  errmsg?: string;
+  code?: string;
+  message?: string;
+}
+
+/**
+ * Create a card instance
+ *
+ * API: POST /v1.0/card/instances
+ */
+export async function createCardInstance(
+  params: CreateCardInstanceParams,
+): Promise<CardApiResponse> {
+  try {
+    const token = await getDingTalkAccessToken(params.clientId, params.clientSecret);
+
+    const body: Record<string, any> = {
+      cardTemplateId: params.cardTemplateId,
+      outTrackId: params.outTrackId,
+      cardData: params.cardData || { cardParamMap: {} },
+      callbackType: params.callbackType || "STREAM",
+    };
+
+    if (params.robotCode) {
+      body.robotCode = params.robotCode;
+    }
+
+    if (params.userIdType !== undefined) {
+      body.userIdType = params.userIdType;
+    }
+
+    const res = await jsonPost(
+      `${DINGTALK_API_BASE}/card/instances`,
+      body,
+      { "x-acs-dingtalk-access-token": token },
+    );
+
+    if (res.code || res.errcode) {
+      return {
+        success: false,
+        errcode: res.errcode,
+        errmsg: res.errmsg,
+        code: res.code,
+        message: res.message,
+      };
+    }
+
+    return { success: true, result: res };
+  } catch (err) {
+    return {
+      success: false,
+      message: String(err),
+    };
+  }
+}
+
+/**
+ * Add space to card instance
+ *
+ * API: POST /v1.0/card/instances/spaces
+ */
+export async function createCardSpace(
+  clientId: string,
+  clientSecret: string,
+  outTrackId: string,
+  openSpaceId: string,
+): Promise<CardApiResponse> {
+  try {
+    const token = await getDingTalkAccessToken(clientId, clientSecret);
+
+    const res = await jsonPost(
+      `${DINGTALK_API_BASE}/card/instances/spaces`,
+      { outTrackId, openSpaceId },
+      { "x-acs-dingtalk-access-token": token },
+    );
+
+    if (res.code || res.errcode) {
+      return {
+        success: false,
+        errcode: res.errcode,
+        errmsg: res.errmsg,
+        code: res.code,
+        message: res.message,
+      };
+    }
+
+    return { success: true, result: res };
+  } catch (err) {
+    return {
+      success: false,
+      message: String(err),
+    };
+  }
+}
+
+/**
+ * Deliver card to conversation
+ *
+ * API: POST /v1.0/card/instances/deliver
+ */
+export async function deliverCard(
+  params: DeliverCardParams,
+): Promise<CardApiResponse> {
+  try {
+    const token = await getDingTalkAccessToken(params.clientId, params.clientSecret);
+
+    const body: Record<string, any> = {
+      outTrackId: params.outTrackId,
+      openSpaceId: params.openSpaceId,
+    };
+
+    if (params.imGroupOpenDeliverModel) {
+      body.imGroupOpenDeliverModel = params.imGroupOpenDeliverModel;
+    }
+
+    if (params.imRobotOpenDeliverModel) {
+      body.imRobotOpenDeliverModel = params.imRobotOpenDeliverModel;
+    }
+
+    const res = await jsonPost(
+      `${DINGTALK_API_BASE}/card/instances/deliver`,
+      body,
+      { "x-acs-dingtalk-access-token": token },
+    );
+
+    if (res.code || res.errcode) {
+      return {
+        success: false,
+        errcode: res.errcode,
+        errmsg: res.errmsg,
+        code: res.code,
+        message: res.message,
+      };
+    }
+
+    return { success: true, result: res };
+  } catch (err) {
+    return {
+      success: false,
+      message: String(err),
+    };
+  }
+}
+
+/**
+ * Update card data
+ *
+ * API: PUT /v1.0/card/instances
+ */
+export async function updateCard(
+  params: UpdateCardParams,
+): Promise<CardApiResponse> {
+  try {
+    const token = await getDingTalkAccessToken(params.clientId, params.clientSecret);
+
+    const body: Record<string, any> = {
+      outTrackId: params.outTrackId,
+      cardData: params.cardData,
+    };
+
+    if (params.userIdType !== undefined) {
+      body.userIdType = params.userIdType;
+    }
+
+    const res = await jsonPut(
+      `${DINGTALK_API_BASE}/card/instances`,
+      body,
+      { "x-acs-dingtalk-access-token": token },
+    );
+
+    if (res.code || res.errcode) {
+      return {
+        success: false,
+        errcode: res.errcode,
+        errmsg: res.errmsg,
+        code: res.code,
+        message: res.message,
+      };
+    }
+
+    return { success: true, result: res };
+  } catch (err) {
+    return {
+      success: false,
+      message: String(err),
+    };
+  }
+}
+
+/**
+ * Streaming update for AI card (typewriter effect)
+ *
+ * API: PUT /v1.0/card/streaming
+ *
+ * Note: Requires Card.Streaming.Write permission
+ */
+export async function updateCardStreaming(
+  params: StreamingUpdateParams,
+): Promise<CardApiResponse> {
+  try {
+    const token = await getDingTalkAccessToken(params.clientId, params.clientSecret);
+
+    const body: Record<string, any> = {
+      outTrackId: params.outTrackId,
+      key: params.key,
+      content: params.content,
+      isFull: params.isFull ?? false,
+    };
+
+    if (params.guid) {
+      body.guid = params.guid;
+    }
+
+    const res = await jsonPut(
+      `${DINGTALK_API_BASE}/card/streaming`,
+      body,
+      { "x-acs-dingtalk-access-token": token },
+    );
+
+    if (res.code || res.errcode) {
+      return {
+        success: false,
+        errcode: res.errcode,
+        errmsg: res.errmsg,
+        code: res.code,
+        message: res.message,
+      };
+    }
+
+    return { success: true, result: res };
+  } catch (err) {
+    return {
+      success: false,
+      message: String(err),
+    };
+  }
+}
+
+/**
+ * Build openSpaceId for different scenarios
+ */
+export function buildOpenSpaceId(
+  type: "IM_GROUP" | "IM_ROBOT",
+  id: string,
+): string {
+  // Format: dtv1.card//IM_GROUP.{openConversationId}
+  // or: dtv1.card//IM_ROBOT.{senderStaffId}
+  return `dtv1.card//${type}.${id}`;
+}
+
+/**
+ * Generate unique outTrackId
+ */
+export function generateOutTrackId(): string {
+  const timestamp = Date.now();
+  const random = Math.random().toString(36).substring(2, 10);
+  return `card_${timestamp}_${random}`;
+}
+
+/**
+ * High-level: Send a card message to a conversation
+ *
+ * This combines createCardInstance + createCardSpace + deliverCard
+ */
+export async function sendCardMessage(params: {
+  clientId: string;
+  clientSecret: string;
+  robotCode: string;
+  cardTemplateId: string;
+  cardData: Record<string, string>;
+  /** For group chat */
+  openConversationId?: string;
+  /** For single chat (DM) */
+  senderStaffId?: string;
+}): Promise<CardApiResponse & { outTrackId?: string }> {
+  const outTrackId = generateOutTrackId();
+
+  // Determine space type and ID
+  const isGroup = !!params.openConversationId;
+  const spaceType = isGroup ? "IM_GROUP" : "IM_ROBOT";
+  const spaceTargetId = isGroup ? params.openConversationId! : params.senderStaffId!;
+  const openSpaceId = buildOpenSpaceId(spaceType, spaceTargetId);
+
+  // Step 1: Create card instance
+  const createResult = await createCardInstance({
+    clientId: params.clientId,
+    clientSecret: params.clientSecret,
+    cardTemplateId: params.cardTemplateId,
+    outTrackId,
+    cardData: { cardParamMap: params.cardData },
+    robotCode: params.robotCode,
+    callbackType: "STREAM",
+  });
+
+  if (!createResult.success) {
+    console.warn("[dingtalk-card] Failed to create card instance:", createResult);
+    return createResult;
+  }
+
+  // Step 2: Add space
+  const spaceResult = await createCardSpace(
+    params.clientId,
+    params.clientSecret,
+    outTrackId,
+    openSpaceId,
+  );
+
+  if (!spaceResult.success) {
+    console.warn("[dingtalk-card] Failed to create card space:", spaceResult);
+    return spaceResult;
+  }
+
+  // Step 3: Deliver card
+  const deliverParams: DeliverCardParams = {
+    clientId: params.clientId,
+    clientSecret: params.clientSecret,
+    outTrackId,
+    openSpaceId,
+  };
+
+  if (isGroup) {
+    deliverParams.imGroupOpenDeliverModel = {
+      robotCode: params.robotCode,
+    };
+  } else {
+    deliverParams.imRobotOpenDeliverModel = {
+      spaceType: "IM_ROBOT",
+      robotCode: params.robotCode,
+    };
+  }
+
+  const deliverResult = await deliverCard(deliverParams);
+
+  if (!deliverResult.success) {
+    console.warn("[dingtalk-card] Failed to deliver card:", deliverResult);
+    return deliverResult;
+  }
+
+  return { success: true, outTrackId, result: deliverResult.result };
+}
+
+/**
+ * High-level: Send an AI card with streaming support
+ *
+ * Returns a controller object for streaming updates
+ */
+export async function sendStreamingAICard(params: {
+  clientId: string;
+  clientSecret: string;
+  robotCode: string;
+  cardTemplateId: string;
+  /** Initial card data (use flowStatus="0" for loading state) */
+  initialData?: Record<string, string>;
+  /** Key for the streaming content variable in the template */
+  streamingKey?: string;
+  openConversationId?: string;
+  senderStaffId?: string;
+}): Promise<{
+  success: boolean;
+  outTrackId?: string;
+  error?: string;
+  /** Update streaming content */
+  update: (content: string) => Promise<CardApiResponse>;
+  /** Mark streaming as complete */
+  finish: (finalContent: string) => Promise<CardApiResponse>;
+}> {
+  const streamingKey = params.streamingKey || "content";
+
+  // Send initial card with loading state
+  const initialCardData: Record<string, string> = {
+    flowStatus: "0", // 0 = streaming in progress
+    ...params.initialData,
+  };
+
+  const sendResult = await sendCardMessage({
+    clientId: params.clientId,
+    clientSecret: params.clientSecret,
+    robotCode: params.robotCode,
+    cardTemplateId: params.cardTemplateId,
+    cardData: initialCardData,
+    openConversationId: params.openConversationId,
+    senderStaffId: params.senderStaffId,
+  });
+
+  if (!sendResult.success || !sendResult.outTrackId) {
+    return {
+      success: false,
+      error: sendResult.message || sendResult.errmsg || "Failed to send card",
+      update: async () => ({ success: false, message: "Card not initialized" }),
+      finish: async () => ({ success: false, message: "Card not initialized" }),
+    };
+  }
+
+  const outTrackId = sendResult.outTrackId;
+
+  // Return controller
+  return {
+    success: true,
+    outTrackId,
+    update: async (content: string) => {
+      return updateCardStreaming({
+        clientId: params.clientId,
+        clientSecret: params.clientSecret,
+        outTrackId,
+        key: streamingKey,
+        content,
+        isFull: false,
+      });
+    },
+    finish: async (finalContent: string) => {
+      // First update with final content
+      await updateCardStreaming({
+        clientId: params.clientId,
+        clientSecret: params.clientSecret,
+        outTrackId,
+        key: streamingKey,
+        content: finalContent,
+        isFull: true,
+      });
+
+      // Then update flowStatus to complete
+      return updateCard({
+        clientId: params.clientId,
+        clientSecret: params.clientSecret,
+        outTrackId,
+        cardData: {
+          cardParamMap: { flowStatus: "1" }, // 1 = complete
+        },
+      });
+    },
+  };
+}

package/src/config-schema.ts

@@ -9,8 +9,8 @@ export const groupPolicySchema = z.enum(['disabled', 'allowlist', 'open'], {
   description: 'Group chat access control policy',
 });
 
-export const messageFormatSchema = z.enum(['text', 'markdown', 'richtext', 'auto'], {
-  description: 'Message format for bot responses (richtext is an alias for markdown, auto detects markdown features)',
+export const messageFormatSchema = z.enum(['text', 'markdown', 'richtext', 'auto', 'card'], {
+  description: 'Message format for bot responses (richtext is an alias for markdown, auto detects markdown features, card uses interactive cards)',
 });
 
 // DingTalk 配置 Schema
@@ -61,9 +61,25 @@ export const dingTalkConfigSchema = z.object({
       '  - text: Plain text (recommended, supports tables)\n' +
       '  - markdown: DingTalk markdown (limited support, no tables)\n' +
       '  - richtext: Alias for markdown (deprecated, use markdown instead)\n' +
-      '  - auto: Auto-detect markdown features in response'
+      '  - auto: Auto-detect markdown features in response\n' +
+      '  - card: Interactive card (requires cardTemplateId)'
     ),
 
+  // 卡片配置（当 messageFormat 为 card 时使用）
+  card: z.object({
+    templateId: z.string().min(1)
+      .describe('Card template ID from DingTalk card platform (e.g., "xxx.schema")'),
+    title: z.string().optional()
+      .describe('Card title (optional, if template has a title variable)'),
+    streamingEnabled: z.boolean().default(false)
+      .describe('Enable streaming update for AI typewriter effect (costs more API quota)'),
+    streamingKey: z.string().default('content')
+      .describe('Variable key for streaming content in the card template'),
+    fallbackToMarkdown: z.boolean().default(true)
+      .describe('Fall back to markdown when card delivery fails'),
+  }).optional()
+    .describe('Interactive card configuration (required when messageFormat is "card")'),
+
   // 思考反馈
   showThinking: z.boolean().default(false)
     .describe('Send "正在思考..." feedback before AI responds'),

package/src/monitor.ts

@@ -1,5 +1,6 @@
 import type { DingTalkRobotMessage, ResolvedDingTalkAccount, ExtractedMessage } from "./types.js";
 import { sendViaSessionWebhook, sendMarkdownViaSessionWebhook, sendDingTalkRestMessage, batchGetUserInfo, downloadPicture, downloadMediaFile, cleanupOldMedia } from "./api.js";
+import { sendCardMessage, sendStreamingAICard } from "./card-api.js";
 import { getDingTalkRuntime } from "./runtime.js";
 
 export interface DingTalkMonitorContext {
@@ -53,8 +54,9 @@ export async function startDingTalkMonitor(ctx: DingTalkMonitorContext): Promise
 
   client.registerCallbackListener(TOPIC_ROBOT, async (downstream: any) => {
     // Immediately ACK to prevent DingTalk from retrying (60s timeout)
+    // SDK method is socketCallBackResponse, not socketResponse
     try {
-      client.socketResponse(downstream.headers.messageId, { status: 'SUCCESS' });
+      client.socketCallBackResponse(downstream.headers.messageId, { status: 'SUCCESS' });
     } catch (_) { /* best-effort ACK */ }
 
     try {
@@ -318,11 +320,16 @@ async function processInboundMessage(
   // Extract message content using structured extractor
   const extracted = await extractMessageContent(msg, account, log);
 
-  // Download media if present (picture/audio/video/file)
+  // Download media if present (picture/video/file — but skip audio when ASR text exists)
   let mediaPath: string | undefined;
   let mediaType: string | undefined;
 
-  if (extracted.mediaDownloadCode && account.clientId && account.clientSecret) {
+  // For audio messages with successful ASR recognition, use the text directly
+  // and skip downloading the .amr file (which would confuse the agent into
+  // trying Whisper instead of reading the already-transcribed text).
+  const skipMediaDownload = extracted.messageType === 'audio' && !!extracted.text;
+
+  if (!skipMediaDownload && extracted.mediaDownloadCode && account.clientId && account.clientSecret) {
     const robotCode = account.robotCode || account.clientId;
     try {
       const result = await downloadMediaFile(
@@ -342,6 +349,8 @@ async function processInboundMessage(
     } catch (err) {
       log?.warn?.(`[dingtalk] Media download error: ${err}`);
     }
+  } else if (skipMediaDownload) {
+    log?.info?.("[dingtalk] Audio ASR text available, skipping .amr download");
   }
 
   let rawBody = extracted.text;
@@ -741,16 +750,89 @@ function resolveDeliverText(payload: any, log?: any): string | undefined {
   return text || undefined;
 }
 
+/**
+ * Deliver reply using interactive card
+ * Returns true if card was sent successfully, false otherwise
+ */
+async function deliverCardReply(
+  target: any,
+  text: string,
+  cardConfig: { templateId: string; title?: string; streamingEnabled?: boolean; streamingKey?: string },
+  log?: any,
+): Promise<boolean> {
+  try {
+    const { clientId, clientSecret, robotCode } = target.account;
+
+    if (!clientId || !clientSecret) {
+      log?.info?.("[dingtalk-card] Missing credentials for card delivery");
+      return false;
+    }
+
+    const robotCodeValue = robotCode || clientId;
+
+    // Prepare card data - use 'content' as the main variable for markdown content
+    const isStreaming = cardConfig.streamingEnabled;
+    const cardData: Record<string, string> = {
+      content: text,
+      // flowStatus: "0" = streaming, "1" = complete
+      flowStatus: isStreaming ? "0" : "1",
+      // title: use configured title, or "完成" for non-streaming mode
+      title: cardConfig.title || (isStreaming ? "" : "完成"),
+    };
+
+    log?.info?.("[dingtalk-card] Sending card message, templateId=" + cardConfig.templateId);
+
+    const result = await sendCardMessage({
+      clientId,
+      clientSecret,
+      robotCode: robotCodeValue,
+      cardTemplateId: cardConfig.templateId,
+      cardData,
+      openConversationId: target.isDm ? undefined : target.conversationId,
+      senderStaffId: target.isDm ? target.senderId : undefined,
+    });
+
+    if (result.success) {
+      log?.info?.("[dingtalk-card] Card sent successfully, outTrackId=" + result.outTrackId);
+      return true;
+    } else {
+      log?.info?.("[dingtalk-card] Card send failed: " + (result.message || result.errmsg || JSON.stringify(result)));
+      return false;
+    }
+  } catch (err) {
+    log?.info?.("[dingtalk-card] Card delivery error: " + (err instanceof Error ? err.message : String(err)));
+    return false;
+  }
+}
+
 async function deliverReply(target: any, text: string, log?: any): Promise<void> {
   const now = Date.now();
   const chunkLimit = 2000;
   const messageFormat = target.account.config.messageFormat ?? "text";
+  const cardConfig = target.account.config.card;
+
+  // Handle card format
+  if (messageFormat === 'card' && cardConfig?.templateId) {
+    const cardSent = await deliverCardReply(target, text, cardConfig, log);
+    if (cardSent) return;
+
+    // Fallback to markdown if card failed and fallback is enabled
+    if (cardConfig.fallbackToMarkdown !== false) {
+      log?.info?.("[dingtalk] Card delivery failed, falling back to markdown");
+    } else {
+      log?.info?.("[dingtalk] Card delivery failed, no fallback configured");
+      return;
+    }
+  }
 
   // Determine if this message should use markdown format
   let isMarkdown: boolean;
   if (messageFormat === 'auto') {
     isMarkdown = detectMarkdownContent(text);
     log?.info?.("[dingtalk] Auto-detected format: " + (isMarkdown ? "markdown" : "text"));
+  } else if (messageFormat === 'card') {
+    // Card failed, fallback to markdown
+    isMarkdown = true;
   } else {
     // Support both "markdown" and "richtext" (they're equivalent for DingTalk)
     isMarkdown = messageFormat === "markdown" || messageFormat === "richtext";