@soimy/dingtalk 3.0.1 → 3.1.0

package/README.md

@@ -439,6 +439,30 @@ openclaw gateway restart
 1. 检查 clientId 和 clientSecret 是否正确
 2. 确认网络可以访问钉钉 API
 
+### 错误 payload 日志规范（`[ErrorPayload]`）
+
+为便于快速定位 4xx/5xx 参数问题，插件会在 API 错误分支输出统一格式日志：
+
+- 通用前缀：`[DingTalk][ErrorPayload][<scope>]`
+- AI Card 前缀：`[DingTalk][AICard][ErrorPayload][<scope>]`
+- 内容格式：`code=<...> message=<...> payload=<...>`（同时保留脱敏后的完整 payload）
+
+常见 scope 示例：
+
+- `send.proactiveMessage` / `send.proactiveMedia` / `send.message`
+- `outbound.sendText` / `outbound.sendMedia`
+- `inbound.downloadMedia` / `inbound.cardFinalize`
+- `card.create` / `card.stream` / `card.stream.retryAfterRefresh`
+- `retry.beforeDecision`
+
+排查建议：
+
+```bash
+openclaw logs | grep "\[ErrorPayload\]"
+```
+
+如果你看到 `code=invalidParameter`，通常优先检查请求 payload 的必填字段（例如 `robotCode`、`userIds`、`msgKey`、`msgParam`）是否完整且格式正确。
+
 ## 开发指南
 
 ### 首次设置

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soimy/dingtalk",
-  "version": "3.0.1",
+  "version": "3.1.0",
   "description": "DingTalk (钉钉) channel plugin for OpenClaw",
   "keywords": [
     "bot",

package/src/card-service.ts

@@ -3,6 +3,7 @@ import axios from "axios";
 import { getAccessToken } from "./auth";
 import { stripTargetPrefix } from "./config";
 import { resolveOriginalPeerId } from "./peer-id-registry";
+import { formatDingTalkErrorPayloadLog } from "./utils";
 import type {
   AICardInstance,
   AICardStreamingRequest,
@@ -207,8 +208,12 @@ export async function createAICard(
   } catch (err: any) {
     log?.error?.(`[DingTalk][AICard] Create failed: ${err.message}`);
     if (err.response) {
+      const status = err.response.status;
+      const statusText = err.response.statusText;
+      const statusLabel = status ? ` status=${status}${statusText ? ` ${statusText}` : ""}` : "";
+      log?.error?.(`[DingTalk][AICard] Create error response${statusLabel}`);
       log?.error?.(
-        `[DingTalk][AICard] Error response: status=${err.response.status} data=${JSON.stringify(err.response.data)}`,
+        formatDingTalkErrorPayloadLog("card.create", err.response.data, "[DingTalk][AICard]"),
       );
     }
     return null;
@@ -221,6 +226,13 @@ export async function streamAICard(
   finished: boolean = false,
   log?: Logger,
 ): Promise<void> {
+  if (card.state === AICardStatus.FINISHED) {
+    log?.debug?.(
+      `[DingTalk][AICard] Skip stream update because card already finalized: outTrackId=${card.cardInstanceId}`,
+    );
+    return;
+  }
+
   // Refresh token defensively before DingTalk 2h token horizon.
   const tokenAge = Date.now() - card.createdAt;
   const tokenRefreshThreshold = 90 * 60 * 1000;
@@ -315,14 +327,28 @@ export async function streamAICard(
         return;
       } catch (retryErr: any) {
         log?.error?.(`[DingTalk][AICard] Retry after token refresh failed: ${retryErr.message}`);
+        if (retryErr.response?.data !== undefined) {
+          log?.error?.(
+            formatDingTalkErrorPayloadLog(
+              "card.stream.retryAfterRefresh",
+              retryErr.response.data,
+              "[DingTalk][AICard]",
+            ),
+          );
+        }
       }
     }
 
     card.state = AICardStatus.FAILED;
     card.lastUpdated = Date.now();
     log?.error?.(
-      `[DingTalk][AICard] Streaming update failed: ${err.message}, resp=${JSON.stringify(err.response?.data)}`,
+      `[DingTalk][AICard] Streaming update failed: ${err.message}`,
     );
+    if (err.response?.data !== undefined) {
+      log?.error?.(
+        formatDingTalkErrorPayloadLog("card.stream", err.response.data, "[DingTalk][AICard]"),
+      );
+    }
     throw err;
   }
 }

package/src/channel.ts

@@ -28,7 +28,7 @@ import type {
   ResolvedAccount,
 } from "./types";
 import { ConnectionState } from "./types";
-import { cleanupOrphanedTempFiles, getCurrentTimestamp } from "./utils";
+import { cleanupOrphanedTempFiles, formatDingTalkErrorPayloadLog, getCurrentTimestamp } from "./utils";
 
 const processingDedupKeys = new Set<string>();
 const inboundCountersByAccount = new Map<
@@ -187,6 +187,9 @@ export const dingtalkPlugin: DingTalkChannelPlugin = {
           typeof result.error === "string" ? result.error : JSON.stringify(result.error),
         );
       } catch (err: any) {
+        if (err?.response?.data !== undefined) {
+          log?.error?.(formatDingTalkErrorPayloadLog("outbound.sendText", err.response.data));
+        }
         throw new Error(
           typeof err?.response?.data === "string"
             ? err.response.data
@@ -261,6 +264,9 @@ export const dingtalkPlugin: DingTalkChannelPlugin = {
           typeof result.error === "string" ? result.error : JSON.stringify(result.error),
         );
       } catch (err: any) {
+        if (err?.response?.data !== undefined) {
+          log?.error?.(formatDingTalkErrorPayloadLog("outbound.sendMedia", err.response.data));
+        }
         throw new Error(
           typeof err?.response?.data === "string"
             ? err.response.data

package/src/inbound-handler.ts

@@ -20,7 +20,7 @@ import { getDingTalkRuntime } from "./runtime";
 import { sendBySession, sendMessage } from "./send-service";
 import type { DingTalkConfig, HandleDingTalkMessageParams, MediaFile } from "./types";
 import { AICardStatus } from "./types";
-import { maskSensitiveData } from "./utils";
+import { formatDingTalkErrorPayloadLog, maskSensitiveData } from "./utils";
 
 /**
  * Download DingTalk media file via runtime media service (sandbox-compatible).
@@ -97,7 +97,9 @@ export async function downloadMedia(
         log.error(
           `[DingTalk] Failed to download media:${statusLabel}${code} message=${err.message}`,
         );
-        if (dataDetail) {
+        if (err.response?.data !== undefined) {
+          log.error(formatDingTalkErrorPayloadLog("inbound.downloadMedia", err.response.data));
+        } else if (dataDetail) {
           log.error(`[DingTalk] downloadMedia response data: ${dataDetail}`);
         }
       } else {
@@ -168,6 +170,9 @@ export async function handleDingTalkMessage(params: HandleDingTalkMessageParams)
           );
         } catch (err: any) {
           log?.debug?.(`[DingTalk] Failed to send access denied message: ${err.message}`);
+          if (err?.response?.data !== undefined) {
+            log?.debug?.(formatDingTalkErrorPayloadLog("inbound.accessDeniedReply", err.response.data));
+          }
         }
 
         return;
@@ -202,6 +207,11 @@ export async function handleDingTalkMessage(params: HandleDingTalkMessageParams)
           );
         } catch (err: any) {
           log?.debug?.(`[DingTalk] Failed to send group access denied message: ${err.message}`);
+          if (err?.response?.data !== undefined) {
+            log?.debug?.(
+              formatDingTalkErrorPayloadLog("inbound.groupAccessDeniedReply", err.response.data),
+            );
+          }
         }
 
         return;
@@ -355,6 +365,9 @@ export async function handleDingTalkMessage(params: HandleDingTalkMessageParams)
       }
     } catch (err: any) {
       log?.debug?.(`[DingTalk] Thinking message failed: ${err.message}`);
+      if (err?.response?.data !== undefined) {
+        log?.debug?.(formatDingTalkErrorPayloadLog("inbound.thinkingMessage", err.response.data));
+      }
     }
   }
 
@@ -370,8 +383,20 @@ export async function handleDingTalkMessage(params: HandleDingTalkMessageParams)
             return;
           }
 
+          if (useCardMode && currentAICard && info?.kind === "final") {
+            lastCardContent = textToSend;
+            return;
+          }
+
           // Tool outputs are rendered into card stream as a separate formatted block.
           if (useCardMode && currentAICard && info?.kind === "tool") {
+            if (isCardInTerminalState(currentAICard.state)) {
+              log?.debug?.(
+                `[DingTalk] Skipping tool stream update because card is terminal: state=${currentAICard.state}`,
+              );
+              return;
+            }
+
             log?.info?.(
               `[DingTalk] Tool result received, streaming to AI Card: ${textToSend.slice(0, 100)}`,
             );
@@ -391,6 +416,9 @@ export async function handleDingTalkMessage(params: HandleDingTalkMessageParams)
           });
         } catch (err: any) {
           log?.error?.(`[DingTalk] Reply failed: ${err.message}`);
+          if (err?.response?.data !== undefined) {
+            log?.error?.(formatDingTalkErrorPayloadLog("inbound.replyDeliver", err.response.data));
+          }
           throw err;
         }
       },
@@ -401,6 +429,12 @@ export async function handleDingTalkMessage(params: HandleDingTalkMessageParams)
         if (!useCardMode || !currentAICard) {
           return;
         }
+        if (isCardInTerminalState(currentAICard.state)) {
+          log?.debug?.(
+            `[DingTalk] Skipping thinking stream update because card is terminal: state=${currentAICard.state}`,
+          );
+          return;
+        }
         const thinkingText = formatContentForCard(payload.text, "thinking");
         if (!thinkingText) {
           return;
@@ -409,6 +443,9 @@ export async function handleDingTalkMessage(params: HandleDingTalkMessageParams)
           await streamAICard(currentAICard, thinkingText, false, log);
         } catch (err: any) {
           log?.debug?.(`[DingTalk] Thinking stream update failed: ${err.message}`);
+          if (err?.response?.data !== undefined) {
+            log?.debug?.(formatDingTalkErrorPayloadLog("inbound.thinkingStream", err.response.data));
+          }
         }
       },
     },
@@ -417,6 +454,13 @@ export async function handleDingTalkMessage(params: HandleDingTalkMessageParams)
   // 5) Finalize card stream if card mode is active.
   if (useCardMode && currentAICard) {
     try {
+      if (isCardInTerminalState(currentAICard.state)) {
+        log?.debug?.(
+          `[DingTalk] Skipping AI Card finalization because card is terminal: state=${currentAICard.state}`,
+        );
+        return;
+      }
+
       const isNonEmptyString = (value: any): boolean =>
         typeof value === "string" && value.trim().length > 0;
 
@@ -440,6 +484,9 @@ export async function handleDingTalkMessage(params: HandleDingTalkMessageParams)
       }
     } catch (err: any) {
       log?.debug?.(`[DingTalk] AI Card finalization failed: ${err.message}`);
+      if (err?.response?.data !== undefined) {
+        log?.debug?.(formatDingTalkErrorPayloadLog("inbound.cardFinalize", err.response.data));
+      }
       try {
         if (currentAICard.state !== AICardStatus.FINISHED) {
           currentAICard.state = AICardStatus.FAILED;

package/src/media-utils.ts

@@ -11,6 +11,7 @@ import * as path from "path";
 import axios from "axios";
 import FormData from "form-data";
 import type { DingTalkConfig, Logger } from "./types";
+import { formatDingTalkErrorPayloadLog } from "./utils";
 
 export type DingTalkMediaType = "image" | "voice" | "video" | "file";
 
@@ -123,7 +124,11 @@ export async function uploadMedia(
     } else {
       log?.error?.(`[DingTalk] Failed to upload media: ${err.message}`);
       if (axios.isAxiosError(err) && err.response) {
-        log?.error?.(`[DingTalk] Upload response: ${JSON.stringify(err.response.data)}`);
+        const status = err.response.status;
+        const statusText = err.response.statusText;
+        const statusLabel = status ? ` status=${status}${statusText ? ` ${statusText}` : ""}` : "";
+        log?.error?.(`[DingTalk] Upload response${statusLabel}`);
+        log?.error?.(formatDingTalkErrorPayloadLog("media.upload", err.response.data));
       }
     }
     return null;

package/src/send-service.ts

@@ -13,6 +13,7 @@ import { getLogger } from "./logger-context";
 import { uploadMedia as uploadMediaUtil } from "./media-utils";
 import { detectMarkdownAndExtractTitle } from "./message-utils";
 import { resolveOriginalPeerId } from "./peer-id-registry";
+import { formatDingTalkErrorPayloadLog } from "./utils";
 import type {
   AxiosResponse,
   DingTalkConfig,
@@ -43,8 +44,8 @@ export async function sendProactiveTextOrMarkdown(
   text: string,
   options: SendMessageOptions = {},
 ): Promise<AxiosResponse> {
-  const token = await getAccessToken(config, options.log);
   const log = options.log || getLogger();
+  const token = await getAccessToken(config, log);
 
   // Support group:/user: prefix and restore original case-sensitive conversationId.
   const { targetId, isExplicitUser } = stripTargetPrefix(target);
@@ -79,13 +80,40 @@ export async function sendProactiveTextOrMarkdown(
     payload.userIds = [resolvedTarget];
   }
 
-  const result = await axios({
-    url,
-    method: "POST",
-    data: payload,
-    headers: { "x-acs-dingtalk-access-token": token, "Content-Type": "application/json" },
-  });
-  return result.data;
+  try {
+    const result = await axios({
+      url,
+      method: "POST",
+      data: payload,
+      headers: { "x-acs-dingtalk-access-token": token, "Content-Type": "application/json" },
+    });
+    return result.data;
+  } catch (err: unknown) {
+    const maybeAxiosError = err as {
+      response?: { status?: number; statusText?: string; data?: unknown };
+      message?: string;
+    };
+    if (maybeAxiosError?.response) {
+      const status = maybeAxiosError.response.status;
+      const statusText = maybeAxiosError.response.statusText;
+      const statusLabel = status ? ` status=${status}${statusText ? ` ${statusText}` : ""}` : "";
+      log?.error?.(
+        `[DingTalk] Failed to send proactive message:${statusLabel} message=${
+          maybeAxiosError.message || String(err)
+        }`,
+      );
+      if (maybeAxiosError.response.data !== undefined) {
+        log?.error?.(
+          formatDingTalkErrorPayloadLog("send.proactiveMessage", maybeAxiosError.response.data),
+        );
+      }
+    } else if (err instanceof Error) {
+      log?.error?.(`[DingTalk] Failed to send proactive message: ${err.message}`);
+    } else {
+      log?.error?.(`[DingTalk] Failed to send proactive message: ${String(err)}`);
+    }
+    throw err;
+  }
 }
 
 export async function sendProactiveMedia(
@@ -161,7 +189,11 @@ export async function sendProactiveMedia(
   } catch (err: any) {
     log?.error?.(`[DingTalk] Failed to send proactive media: ${err.message}`);
     if (axios.isAxiosError(err) && err.response) {
-      log?.error?.(`[DingTalk] Response: ${JSON.stringify(err.response.data)}`);
+      const status = err.response.status;
+      const statusText = err.response.statusText;
+      const statusLabel = status ? ` status=${status}${statusText ? ` ${statusText}` : ""}` : "";
+      log?.error?.(`[DingTalk] Proactive media response${statusLabel}`);
+      log?.error?.(formatDingTalkErrorPayloadLog("send.proactiveMedia", err.response.data));
     }
     return { ok: false, error: err.message };
   }
@@ -276,6 +308,9 @@ export async function sendMessage(
     return { ok: true, data: result };
   } catch (err: any) {
     options.log?.error?.(`[DingTalk] Send message failed: ${err.message}`);
+    if (err?.response?.data !== undefined) {
+      options.log?.error?.(formatDingTalkErrorPayloadLog("send.message", err.response.data));
+    }
     return { ok: false, error: err.message };
   }
 }

package/src/utils.ts

@@ -38,6 +38,55 @@ export function maskSensitiveData(data: unknown): any {
   return masked;
 }
 
+export function formatDingTalkErrorPayload(payload: unknown): string {
+  if (payload === null || payload === undefined) {
+    return "payload=unknown";
+  }
+
+  let code: string | undefined;
+  let message: string | undefined;
+  if (typeof payload === "object" && !Array.isArray(payload)) {
+    const obj = payload as Record<string, unknown>;
+    if (typeof obj.code === "string" || typeof obj.code === "number") {
+      code = String(obj.code);
+    }
+    if (typeof obj.message === "string") {
+      message = obj.message;
+    }
+  }
+
+  let serialized: string;
+  try {
+    serialized = JSON.stringify(maskSensitiveData(payload));
+  } catch {
+    if (typeof payload === "string") {
+      serialized = payload;
+    } else if (typeof payload === "number" || typeof payload === "boolean" || typeof payload === "bigint") {
+      serialized = `${payload}`;
+    } else {
+      serialized = "[unserializable-payload]";
+    }
+  }
+
+  const parts: string[] = [];
+  if (code) {
+    parts.push(`code=${code}`);
+  }
+  if (message) {
+    parts.push(`message=${message}`);
+  }
+  parts.push(`payload=${serialized}`);
+  return parts.join(" ");
+}
+
+export function formatDingTalkErrorPayloadLog(
+  scope: string,
+  payload: unknown,
+  prefix: "[DingTalk]" | "[DingTalk][AICard]" = "[DingTalk]",
+): string {
+  return `${prefix}[ErrorPayload][${scope}] ${formatDingTalkErrorPayload(payload)}`;
+}
+
 /**
  * Cleanup orphaned temp files from dingtalk media
  * Run at startup to clean up files from crashed processes
@@ -98,6 +147,10 @@ export async function retryWithBackoff<T>(
       const isRetryable =
         statusCode === 401 || statusCode === 429 || (statusCode && statusCode >= 500);
 
+      if (err.response?.data !== undefined) {
+        log?.debug?.(formatDingTalkErrorPayloadLog("retry.beforeDecision", err.response.data));
+      }
+
       if (!isRetryable || attempt === maxRetries) {
         throw err;
       }