@soimy/dingtalk 3.6.11 → 3.7.0

package/src/{send-service.ts → messaging/send-service.ts}

@@ -1,46 +1,42 @@
 import * as path from "node:path";
-import axios from "./http-client";
-import { getAccessToken } from "./auth";
-import { resolveCardRunByConversation, resolveCardRunByOwner } from "./card/card-run-registry";
-
-import {
-  isCardInTerminalState,
-  sendProactiveCardText,
-} from "./card-service";
-import { resolveRobotCode, stripTargetPrefix } from "./config";
-import { getLogger } from "./logger-context";
+import { resolveCardRunByConversation, resolveCardRunByOwner } from "../card/card-run-registry";
+import { isCardInTerminalState, sendProactiveCardText } from "../card/card-service";
+import { getAccessToken } from "../platform/auth";
+import { resolveRobotCode, stripTargetPrefix } from "../platform/config";
+import { getLogger } from "../platform/logger-context";
+import type {
+  AICardInstance,
+  AxiosResponse,
+  DingTalkConfig,
+  DingTalkTrackingMetadata,
+  Logger,
+  ProactiveMessagePayload,
+  QuotedRef,
+  SendMessageOptions,
+  SessionWebhookResponse,
+} from "../platform/types";
+import axios from "../shared/http-client";
+import { formatDingTalkErrorPayloadLog, getProxyBypassOption } from "../shared/utils";
+import { resolveOriginalPeerId } from "../targeting/peer-id-registry";
 import {
   getVoiceDurationMs,
   prepareMediaInput,
   resolveOutboundMediaType,
   uploadMedia as uploadMediaUtil,
 } from "./media-utils";
-import { convertMarkdownTablesToPlainText, detectMarkdownAndExtractTitle } from "./message-utils";
+import type { UploadMediaResult } from "./media-utils";
 import {
   DEFAULT_MESSAGE_CONTEXT_TTL_DAYS,
   DEFAULT_OUTBOUND_SENDER,
   inferConversationChatType,
   upsertOutboundMessageContext,
 } from "./message-context-store";
-import { resolveOriginalPeerId } from "./peer-id-registry";
+import { convertMarkdownTablesToPlainText, detectMarkdownAndExtractTitle } from "./message-utils";
 import {
   deleteProactiveRiskObservation,
   getProactiveRiskObservation,
   recordProactiveRiskObservation,
 } from "./proactive-risk-registry";
-import { formatDingTalkErrorPayloadLog, getProxyBypassOption } from "./utils";
-import type { UploadMediaResult } from "./media-utils";
-import type {
-  AICardInstance,
-  AxiosResponse,
-  DingTalkConfig,
-  DingTalkTrackingMetadata,
-  Logger,
-  ProactiveMessagePayload,
-  QuotedRef,
-  SendMessageOptions,
-  SessionWebhookResponse,
-} from "./types";
 
 export { detectMediaTypeFromExtension } from "./media-utils";
 
@@ -93,7 +89,9 @@ async function replaceMarkdownLocalImages(params: {
 
 type ProactiveTextSendResult = AxiosResponse | { tracking: DingTalkTrackingMetadata };
 
-function isTrackingResult(result: ProactiveTextSendResult): result is { tracking: DingTalkTrackingMetadata } {
+function isTrackingResult(
+  result: ProactiveTextSendResult,
+): result is { tracking: DingTalkTrackingMetadata } {
   return "tracking" in result;
 }
 
@@ -120,7 +118,12 @@ function extractOutboundDeliveryMetadata(payload: unknown): {
     data.tracking && typeof data.tracking === "object"
       ? (data.tracking as Record<string, unknown>)
       : undefined;
-  const messageId = firstTrimmedString(data.messageId, data.msgid, tracking?.messageId, tracking?.msgid);
+  const messageId = firstTrimmedString(
+    data.messageId,
+    data.msgid,
+    tracking?.messageId,
+    tracking?.msgid,
+  );
   const processQueryKey = firstTrimmedString(data.processQueryKey, tracking?.processQueryKey);
   const outTrackId = firstTrimmedString(data.outTrackId, tracking?.outTrackId);
   const cardInstanceId = firstTrimmedString(data.cardInstanceId, tracking?.cardInstanceId);
@@ -152,8 +155,8 @@ function persistOutboundMessageContext(params: {
   }
   params.log?.debug?.(
     `[DingTalk][QuotedRef][Persist] direction=outbound scope=${params.conversationId} ` +
-    `messageType=${params.messageType || "(none)"} processQueryKey=${params.delivery.processQueryKey || "(none)"} ` +
-    `messageId=${params.delivery.messageId || "(none)"} quotedRef=${params.quotedRef ? JSON.stringify(params.quotedRef) : "(none)"}`,
+      `messageType=${params.messageType || "(none)"} processQueryKey=${params.delivery.processQueryKey || "(none)"} ` +
+      `messageId=${params.delivery.messageId || "(none)"} quotedRef=${params.quotedRef ? JSON.stringify(params.quotedRef) : "(none)"}`,
   );
   upsertOutboundMessageContext({
     storePath: params.storePath,
@@ -182,7 +185,9 @@ function buildPersistedOutboundText(text: string, options: SendMessageOptions):
   return text;
 }
 
-function shouldRouteSessionMediaViaProactive(mediaType?: string | null): mediaType is "voice" | "video" | "file" {
+function shouldRouteSessionMediaViaProactive(
+  mediaType?: string | null,
+): mediaType is "voice" | "video" | "file" {
   return mediaType === "voice" || mediaType === "video" || mediaType === "file";
 }
 
@@ -273,12 +278,9 @@ function summarizeSessionWebhookResponse(data: unknown): string {
   }
   const payload = data as Record<string, unknown>;
   const code = extractErrorCodeFromResponseData(payload) || "(none)";
-  const message = firstTrimmedString(
-    payload.message,
-    payload.errmsg,
-    payload.msg,
-    payload.errorMessage,
-  ) || "(none)";
+  const message =
+    firstTrimmedString(payload.message, payload.errmsg, payload.msg, payload.errorMessage) ||
+    "(none)";
   const success =
     typeof payload.success === "boolean"
       ? String(payload.success)
@@ -294,21 +296,15 @@ function summarizeSessionWebhookResponse(data: unknown): string {
   );
 }
 
-function ensureSessionWebhookBusinessSuccess(
-  data: unknown,
-  context: { msgtype: string },
-): void {
+function ensureSessionWebhookBusinessSuccess(data: unknown, context: { msgtype: string }): void {
   if (!data || typeof data !== "object") {
     return;
   }
   const payload = data as Record<string, unknown>;
   const code = extractErrorCodeFromResponseData(payload);
-  const message = firstTrimmedString(
-    payload.message,
-    payload.errmsg,
-    payload.msg,
-    payload.errorMessage,
-  ) || "unknown error";
+  const message =
+    firstTrimmedString(payload.message, payload.errmsg, payload.msg, payload.errorMessage) ||
+    "unknown error";
 
   const hasFailureSuccessFlag = payload.success === false || payload.result === false;
   const hasFailureCode = typeof code === "string" && code !== "" && code !== "0";
@@ -319,7 +315,9 @@ function ensureSessionWebhookBusinessSuccess(
   const reason = [
     code && code !== "0" ? `code=${code}` : "",
     message !== "unknown error" ? `message=${message}` : "",
-  ].filter(Boolean).join(" ");
+  ]
+    .filter(Boolean)
+    .join(" ");
   throw new Error(`Session webhook ${context.msgtype} send failed${reason ? `: ${reason}` : ""}`);
 }
 
@@ -407,7 +405,11 @@ export async function sendProactiveTextOrMarkdown(
     config.convertMarkdownTables !== false
       ? convertMarkdownTablesToPlainText(textWithUploadedLocalImages)
       : textWithUploadedLocalImages;
-  const { useMarkdown, title } = detectMarkdownAndExtractTitle(normalizedText, options, "OpenClaw 提醒");
+  const { useMarkdown, title } = detectMarkdownAndExtractTitle(
+    normalizedText,
+    options,
+    "OpenClaw 提醒",
+  );
 
   log?.debug?.(
     `[DingTalk] Sending proactive message to ${isGroup ? "group" : "user"} ${resolvedTarget} with title "${title}"${proactiveRiskTag}`,
@@ -519,8 +521,9 @@ export async function sendProactiveMedia(
       msgParam = JSON.stringify({ photoURL: mediaId });
     } else if (mediaType === "voice") {
       msgKey = "sampleAudio";
-      const durationMs = uploadedDurationMs
-        ?? await getVoiceDurationMs(mediaPath, mediaType, log, { preReadBuffer: buffer });
+      const durationMs =
+        uploadedDurationMs ??
+        (await getVoiceDurationMs(mediaPath, mediaType, log, { preReadBuffer: buffer }));
       msgParam = JSON.stringify({ mediaId, duration: String(durationMs) });
     } else {
       // sampleVideo requires picMediaId; fallback to sampleFile for broader compatibility.
@@ -614,7 +617,10 @@ export async function sendProactiveMedia(
     ).catch((fallbackErr: any) => ({ __fallbackError: fallbackErr }));
 
     if ((fallback as any)?.__fallbackError) {
-      return { ok: false, error: `${err.message}; fallback failed: ${(fallback as any).__fallbackError?.message || "unknown"}` };
+      return {
+        ok: false,
+        error: `${err.message}; fallback failed: ${(fallback as any).__fallbackError?.message || "unknown"}`,
+      };
     }
 
     const fallbackDelivery = extractOutboundDeliveryMetadata(fallback);
@@ -632,7 +638,9 @@ export async function sendProactiveMedia(
       chatType: inferConversationChatType(options.conversationId || normalizedTarget),
       delivery: {
         ...fallbackDelivery,
-        kind: isTrackingResult(fallback as ProactiveTextSendResult) ? "proactive-card" : "proactive-text",
+        kind: isTrackingResult(fallback as ProactiveTextSendResult)
+          ? "proactive-card"
+          : "proactive-text",
       },
     });
     return { ok: true, data: fallback, messageId: fallbackMessageId };
@@ -675,9 +683,9 @@ export async function sendMedia(
       if (options.conversationId) {
         // conversationId explicitly provided (parsed from sessionKey)
         activeRun = options.expectedCardOwnerId
-          ? resolveCardRunByConversation(accountId, options.conversationId, {
+          ? (resolveCardRunByConversation(accountId, options.conversationId, {
               ownerUserId: options.expectedCardOwnerId,
-            }) ?? resolveCardRunByConversation(accountId, options.conversationId, undefined)
+            }) ?? resolveCardRunByConversation(accountId, options.conversationId, undefined))
           : resolveCardRunByConversation(accountId, options.conversationId, undefined);
       } else if (options.expectedCardOwnerId) {
         // Fallback: when sessionKey=- causes conversationId to be undefined,
@@ -686,7 +694,7 @@ export async function sendMedia(
         if (activeRun) {
           log?.debug?.(
             `[DingTalk] Matched active card by owner-only lookup (conversationId unavailable) ` +
-            `accountId=${accountId} ownerUserId=${options.expectedCardOwnerId} outTrackId=${activeRun.outTrackId}`,
+              `accountId=${accountId} ownerUserId=${options.expectedCardOwnerId} outTrackId=${activeRun.outTrackId}`,
           );
         }
       }
@@ -744,13 +752,16 @@ export async function sendBySession(
           `[DingTalk] Session webhook image will be delivered as markdown media reference mediaId=${uploadResult.mediaId}`,
         );
       } else {
-        const mediaHint = options.mediaUrl || options.mediaPath || options.filePath || "(媒体发送失败)";
+        const mediaHint =
+          options.mediaUrl || options.mediaPath || options.filePath || "(媒体发送失败)";
         text = `${text}\n\n📎 媒体发送失败，兜底链接/路径：${mediaHint}`.trim();
         log?.warn?.("[DingTalk] Media upload failed, falling back to text description");
       }
     } else {
-      const mediaHint = options.mediaUrl || options.mediaPath || options.filePath || "(媒体发送失败)";
-      text = `${text}\n\n📎 当前会话无法直接发送 ${options.mediaType}，兜底链接/路径：${mediaHint}`.trim();
+      const mediaHint =
+        options.mediaUrl || options.mediaPath || options.filePath || "(媒体发送失败)";
+      text =
+        `${text}\n\n📎 当前会话无法直接发送 ${options.mediaType}，兜底链接/路径：${mediaHint}`.trim();
       log?.warn?.(
         `[DingTalk] Session webhook does not support native ${options.mediaType} replies; falling back to text description`,
       );
@@ -768,7 +779,11 @@ export async function sendBySession(
     config.convertMarkdownTables !== false
       ? convertMarkdownTablesToPlainText(textWithUploadedLocalImages)
       : textWithUploadedLocalImages;
-  const { useMarkdown, title } = detectMarkdownAndExtractTitle(normalizedText, options, "Clawdbot 消息");
+  const { useMarkdown, title } = detectMarkdownAndExtractTitle(
+    normalizedText,
+    options,
+    "Clawdbot 消息",
+  );
   const chunks = splitMarkdownChunks(normalizedText, DINGTALK_TEXT_CHUNK_LIMIT);
 
   let lastResult: any = null;
@@ -779,7 +794,13 @@ export async function sendBySession(
       if (options.atUserId && idx === chunks.length - 1) {
         finalText = `${finalText} @${options.atUserId}`;
       }
-      body = { msgtype: "markdown", markdown: { title: chunks.length > 1 ? `${title} (${idx + 1}/${chunks.length})` : title, text: finalText } };
+      body = {
+        msgtype: "markdown",
+        markdown: {
+          title: chunks.length > 1 ? `${title} (${idx + 1}/${chunks.length})` : title,
+          text: finalText,
+        },
+      };
     } else {
       body = { msgtype: "text", text: { content: chunk } };
     }
@@ -808,16 +829,30 @@ export async function sendMessage(
   config: DingTalkConfig,
   conversationId: string,
   text: string,
-  options: SendMessageOptions & { sessionWebhook?: string; card?: AICardInstance; accountId?: string } = {},
-): Promise<{ ok: boolean; error?: string; data?: AxiosResponse; messageId?: string; tracking?: DingTalkTrackingMetadata }> {
+  options: SendMessageOptions & {
+    sessionWebhook?: string;
+    card?: AICardInstance;
+    accountId?: string;
+  } = {},
+): Promise<{
+  ok: boolean;
+  error?: string;
+  data?: AxiosResponse;
+  messageId?: string;
+  tracking?: DingTalkTrackingMetadata;
+}> {
   try {
     const messageType = config.messageType || "markdown";
     const log = options.log || getLogger();
 
-    if (options.sessionWebhook && options.mediaPath && shouldRouteSessionMediaViaProactive(options.mediaType)) {
+    if (
+      options.sessionWebhook &&
+      options.mediaPath &&
+      shouldRouteSessionMediaViaProactive(options.mediaType)
+    ) {
       log?.debug?.(
         `[DingTalk] Session webhook does not support ${options.mediaType} replies reliably; ` +
-        "using proactive media API instead",
+          "using proactive media API instead",
       );
       const proactiveMediaResult = await sendProactiveMedia(
         config,
@@ -829,7 +864,7 @@ export async function sendMessage(
       if (!proactiveMediaResult.ok) {
         log?.warn?.(
           `[DingTalk] Proactive ${options.mediaType} reply failed; falling back to session markdown: ` +
-          (proactiveMediaResult.error || "unknown"),
+            (proactiveMediaResult.error || "unknown"),
         );
         const data = await sendBySession(config, options.sessionWebhook, text, options);
         const delivery = extractOutboundDeliveryMetadata(data);

package/src/{auth.ts → platform/auth.ts}

@@ -1,7 +1,7 @@
+import axios from "../shared/http-client";
+import { retryWithBackoff } from "../shared/utils";
 import { resolveRuntimeConfig } from "./config";
-import axios from "./http-client";
 import type { DingTalkConfig, Logger, TokenInfo } from "./types";
-import { retryWithBackoff } from "./utils";
 
 interface TokenCache {
   accessToken: string;

package/src/platform/channel-status.ts

@@ -1,6 +1,6 @@
-import { getAccessToken } from "../auth";
-import type { DingTalkChannelPlugin } from "../types";
-import { getCurrentTimestamp } from "../utils";
+import { getCurrentTimestamp } from "../shared/utils";
+import { getAccessToken } from "./auth";
+import type { DingTalkChannelPlugin } from "./types";
 
 export function createDingTalkStatus(): NonNullable<DingTalkChannelPlugin["status"]> {
   return {

package/src/{config-schema.ts → platform/config-schema.ts}

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { DEFAULT_MESSAGE_CONTEXT_TTL_DAYS } from "./message-context-store";
+import { DEFAULT_MESSAGE_CONTEXT_TTL_DAYS } from "../messaging/message-context-store";
 import { buildSecretInputSchema } from "./secret-input";
 
 const AckReactionSchema = z.union([
@@ -9,8 +9,51 @@ const AckReactionSchema = z.union([
 ]);
 
 const CardStreamingModeSchema = z.enum(["off", "answer", "all"]);
+const CardTaskProgressRefreshSchema = z.enum(["heartbeat", "interval"]);
 const ContextVisibilitySchema = z.enum(["all", "allowlist", "allowlist_quote"]);
 
+/**
+ * Gateway RPC capability gates (Issue #608, 问题 3).
+ * Shape aligned with the official connector's `tools: { docs, media }` gate;
+ * all capabilities default to enabled for backward compatibility.
+ * Allowlists must list at least one entry when present: an empty list would be
+ * ambiguous, so it is rejected at config-validation time instead of silently
+ * disabling the restriction.
+ */
+const GatewayTargetListSchema = z
+  .array(z.string().regex(/^(user|group):\S+$/, "must be `user:<id>` or `group:<conversationId>`"))
+  .min(1)
+  .optional();
+
+const DingTalkGatewayCapabilitiesSchema = z
+  .object({
+    tools: z
+      .object({
+        /** Enable dingtalk.docs.* and dingtalk-connector.docs.* Gateway RPCs (default: true) */
+        docs: z.boolean().optional(),
+        /** Enable dingtalk-connector.sendToUser/sendToGroup/send proactive-send RPCs (default: true) */
+        proactiveSend: z.boolean().optional(),
+      })
+      .strict()
+      .optional(),
+    docs: z
+      .object({
+        /** When set, docs RPCs only accept these spaceId values (at least one entry) */
+        allowedSpaceIds: z.array(z.string().min(1)).min(1).optional(),
+      })
+      .strict()
+      .optional(),
+    send: z
+      .object({
+        /** When set, proactive-send RPCs only accept these `user:*` / `group:*` targets (at least one entry) */
+        allowedTargets: GatewayTargetListSchema,
+      })
+      .strict()
+      .optional(),
+  })
+  .strict()
+  .optional();
+
 /**
  * Runtime-parsed DingTalk account config.
  *
@@ -121,7 +164,13 @@ const DingTalkAccountConfigShape = {
       /** 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),
+      cooldownHours: z
+        .number()
+        .int()
+        .min(1)
+        .max(24 * 30)
+        .optional()
+        .default(24),
     })
     .optional()
     .default({ enabled: true, cooldownHours: 24 }),
@@ -138,8 +187,26 @@ const DingTalkAccountConfigShape = {
   /** Throttle interval in milliseconds between AI card streaming updates. */
   cardStreamInterval: z.number().int().min(200).optional().default(1000),
 
+  /** Live "task in progress" block on AI cards for long-running tasks.
+   *  - true: always enabled
+   *  - false: always disabled
+   *  - unset (default): enabled, except when `cardStreamingMode` is explicitly `"off"` */
+  cardTaskProgress: z.boolean().optional(),
+
+  /** How tool-driven stage/step changes reach the progress block:
+   *  - heartbeat (effective default): coalesced into the 30s refresh, so a task
+   *    costs one update on appearance plus one per 30s
+   *  - interval: pushed on every correlated tool event, throttled by
+   *    `cardStreamInterval` (more updates, fresher stage label) */
+  cardTaskProgressRefresh: CardTaskProgressRefreshSchema.optional(),
+
   /** 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),
+  aicardDegradeMs: z
+    .number()
+    .int()
+    .min(60_000)
+    .optional()
+    .default(30 * 60 * 1000),
 
   /** Enable the local feedback-learning loop for notes, reflections, and command-assisted learning. */
   learningEnabled: z.boolean().optional(),
@@ -175,7 +242,17 @@ const DingTalkAccountConfigShape = {
       dapiUsage: z.boolean().optional().default(false),
     })
     .optional()
-    .default({ model: true, effort: true, agent: true, taskTime: false, tokens: false, dapiUsage: false }),
+    .default({
+      model: true,
+      effort: true,
+      agent: true,
+      taskTime: false,
+      tokens: false,
+      dapiUsage: false,
+    }),
+
+  /** Gateway RPC capability gates and allowlists (docs RPCs + proactive-send RPCs). Named `gatewayCapabilities` because host `OpenClawConfig` already owns `gateway` and `tools`, and a bare `capabilities` key would collide with this plugin's channel capabilities metadata. */
+  gatewayCapabilities: DingTalkGatewayCapabilitiesSchema,
 } as const;
 
 const DingTalkAccountConfigSchema = z.object(DingTalkAccountConfigShape);