@soimy/dingtalk 3.1.0 → 3.1.2

package/package.json

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

package/src/channel.ts

@@ -381,6 +381,7 @@ export const dingtalkPlugin: DingTalkChannelPlugin = {
         initialDelay: config.initialReconnectDelay ?? 1000,
         maxDelay: config.maxReconnectDelay ?? 60000,
         jitter: config.reconnectJitter ?? 0.3,
+        maxReconnectCycles: config.maxReconnectCycles,
         onStateChange: (state: ConnectionState, error?: string) => {
           if (stopped) {
             return;

package/src/config-schema.ts

@@ -75,6 +75,17 @@ const DingTalkAccountConfigSchema = z.object({
 
   /** Jitter factor for reconnection delay randomization (0-1, default: 0.3) */
   reconnectJitter: z.number().min(0).max(1).optional().default(0.3),
+
+  /** Maximum number of runtime reconnect cycles before giving up (default: 10) */
+  maxReconnectCycles: z.number().int().min(1).optional().default(10),
+
+  proactivePermissionHint: z
+    .object({
+      enabled: z.boolean().optional().default(true),
+      cooldownHours: z.number().int().min(1).max(24 * 30).optional().default(24),
+    })
+    .optional()
+    .default({ enabled: true, cooldownHours: 24 }),
 });
 
 /**

package/src/connection-manager.ts

@@ -37,6 +37,8 @@ export class ConnectionManager {
   private static readonly HEALTH_CHECK_INTERVAL_MS = 5000;
   private static readonly HEALTH_CHECK_GRACE_MS = 3000;
   private static readonly HEALTH_CHECK_UNHEALTHY_THRESHOLD = 2;
+  private static readonly DEFAULT_MAX_RECONNECT_CYCLES = 10;
+  private runtimeReconnectCycles: number = 0;
   private runtimeCounters = {
     healthUnhealthyChecks: 0,
     healthTriggeredReconnects: 0,
@@ -160,6 +162,9 @@ export class ConnectionManager {
 
       this.log?.info?.(`[${this.accountId}] DingTalk Stream client connected successfully`);
 
+      // Reset runtime reconnect cycle counter on successful connection
+      this.runtimeReconnectCycles = 0;
+
       return { success: true, attempt: successfulAttempt };
     } catch (err: any) {
       this.log?.error?.(
@@ -427,17 +432,34 @@ export class ConnectionManager {
       this.log?.error?.(`[${this.accountId}] Reconnection failed: ${err.message}`);
       this.runtimeCounters.reconnectFailures += 1;
       this.logRuntimeCounters("reconnect-failed");
+
+      // Track runtime reconnect cycles to prevent infinite loops
+      this.runtimeReconnectCycles += 1;
+      const maxCycles = this.config.maxReconnectCycles ?? ConnectionManager.DEFAULT_MAX_RECONNECT_CYCLES;
+
+      if (this.runtimeReconnectCycles >= maxCycles) {
+        this.log?.error?.(
+          `[${this.accountId}] Max runtime reconnect cycles (${maxCycles}) reached. Giving up. ` +
+          `Please check network connectivity or restart the gateway.`,
+        );
+        this.state = ConnectionStateEnum.FAILED;
+        this.connectedAt = undefined;
+        this.consecutiveUnhealthyChecks = 0;
+        this.notifyStateChange(`Max runtime reconnect cycles (${maxCycles}) reached`);
+        return;
+      }
+
       this.state = ConnectionStateEnum.FAILED;
       this.connectedAt = undefined;
       this.consecutiveUnhealthyChecks = 0;
       this.notifyStateChange(err.message);
 
-      // Continue runtime recovery instead of getting stuck in FAILED.
-      const delay = this.calculateNextDelay(0);
+      // Continue runtime recovery with exponential backoff based on cycle count
+      const delay = this.calculateNextDelay(Math.min(this.runtimeReconnectCycles - 1, 6)); // Cap at ~64x initial delay
       this.attemptCount = 0;
       this.clearReconnectTimer();
       this.log?.warn?.(
-        `[${this.accountId}] Reconnection cycle failed; scheduling next reconnect in ${(delay / 1000).toFixed(2)}s`,
+        `[${this.accountId}] Reconnection cycle ${this.runtimeReconnectCycles}/${maxCycles} failed; scheduling next reconnect in ${(delay / 1000).toFixed(2)}s`,
       );
       this.reconnectTimer = setTimeout(() => {
         void this.reconnect();

package/src/inbound-handler.ts

@@ -16,12 +16,78 @@ import { formatGroupMembers, noteGroupMember } from "./group-members-store";
 import { setCurrentLogger } from "./logger-context";
 import { extractMessageContent } from "./message-utils";
 import { registerPeerId } from "./peer-id-registry";
+import {
+  clearProactiveRiskObservationsForTest,
+  getProactiveRiskObservationForAny,
+} from "./proactive-risk-registry";
 import { getDingTalkRuntime } from "./runtime";
 import { sendBySession, sendMessage } from "./send-service";
 import type { DingTalkConfig, HandleDingTalkMessageParams, MediaFile } from "./types";
 import { AICardStatus } from "./types";
 import { formatDingTalkErrorPayloadLog, maskSensitiveData } from "./utils";
 
+const DEFAULT_PROACTIVE_HINT_COOLDOWN_HOURS = 24;
+const proactiveHintLastSentAt = new Map<string, number>();
+
+export function resetProactivePermissionHintStateForTest(): void {
+  proactiveHintLastSentAt.clear();
+  clearProactiveRiskObservationsForTest();
+}
+
+function shouldSendProactivePermissionHint(params: {
+  isDirect: boolean;
+  accountId: string;
+  senderId: string;
+  senderStaffId?: string;
+  config: DingTalkConfig;
+  nowMs: number;
+}): boolean {
+  if (!params.isDirect) {
+    return false;
+  }
+
+  const hintConfig = params.config.proactivePermissionHint;
+  if (hintConfig?.enabled === false) {
+    return false;
+  }
+
+  const targetId = (params.senderId || "").trim();
+  if (!targetId) {
+    return false;
+  }
+
+  const riskObservation = getProactiveRiskObservationForAny(
+    params.accountId,
+    [params.senderId, params.senderStaffId],
+    params.nowMs,
+  );
+  if (!riskObservation || riskObservation.source !== "proactive-api") {
+    return false;
+  }
+
+  const cooldownHours =
+    hintConfig?.cooldownHours && hintConfig.cooldownHours > 0
+      ? hintConfig.cooldownHours
+      : DEFAULT_PROACTIVE_HINT_COOLDOWN_HOURS;
+  const cooldownMs = cooldownHours * 60 * 60 * 1000;
+  const key = `${params.accountId}:${targetId}`;
+  const lastSentAt = proactiveHintLastSentAt.get(key) || 0;
+  if (params.nowMs - lastSentAt < cooldownMs) {
+    return false;
+  }
+
+  proactiveHintLastSentAt.set(key, params.nowMs);
+  return true;
+}
+
+function isUnhandledStopReasonText(value: string): boolean {
+  const normalized = value.trim();
+  if (!normalized) {
+    return false;
+  }
+  return /^Unhandled stop reason:\s*[A-Za-z0-9_-]+/i.test(normalized);
+}
+
 /**
  * Download DingTalk media file via runtime media service (sandbox-compatible).
  * Files are stored in the global media inbound directory.
@@ -143,6 +209,31 @@ export async function handleDingTalkMessage(params: HandleDingTalkMessageParams)
   if (groupId) {
     registerPeerId(groupId);
   }
+
+  if (
+    shouldSendProactivePermissionHint({
+      isDirect,
+      accountId,
+      senderId,
+      senderStaffId: data.senderStaffId,
+      config: dingtalkConfig,
+      nowMs: Date.now(),
+    })
+  ) {
+    try {
+      await sendBySession(
+        dingtalkConfig,
+        sessionWebhook,
+        "⚠️ 主动推送可能失败\n\n检测到该用户最近一次主动发送调用返回了权限或目标不可达错误。当前会话回复仍可正常使用，但定时/主动发送可能失败。\n\n建议：\n1) 在钉钉开放平台确认应用已申请并获得主动发送相关权限\n2) 确认目标用户属于当前企业并在应用可见范围内\n3) 使用相同账号进行一次主动发送验证并检查错误码详情",
+        { log },
+      );
+    } catch (err: any) {
+      log?.debug?.(`[DingTalk] Failed to send proactive permission hint: ${err.message}`);
+      if (err?.response?.data !== undefined) {
+        log?.debug?.(formatDingTalkErrorPayloadLog("inbound.proactivePermissionHint", err.response.data));
+      }
+    }
+  }
   if (senderId) {
     registerPeerId(senderId);
   }
@@ -383,6 +474,11 @@ export async function handleDingTalkMessage(params: HandleDingTalkMessageParams)
             return;
           }
 
+          if (typeof textToSend === "string" && isUnhandledStopReasonText(textToSend)) {
+            log?.warn?.(`[DingTalk] Suppressed stop reason from outbound chat content: ${textToSend}`);
+            return;
+          }
+
           if (useCardMode && currentAICard && info?.kind === "final") {
             lastCardContent = textToSend;
             return;
@@ -468,12 +564,21 @@ export async function handleDingTalkMessage(params: HandleDingTalkMessageParams)
       const hasQueuedFinalString = isNonEmptyString(queuedFinal);
 
       if (hasLastCardContent || hasQueuedFinalString) {
-        const finalContent =
+        const finalContentCandidate =
           hasLastCardContent && typeof lastCardContent === "string"
             ? lastCardContent
             : typeof queuedFinal === "string"
               ? queuedFinal
               : "";
+        if (isUnhandledStopReasonText(finalContentCandidate)) {
+          log?.warn?.(
+            `[DingTalk] Suppressed stop reason from AI Card final content: ${finalContentCandidate}`,
+          );
+          currentAICard.state = AICardStatus.FINISHED;
+          currentAICard.lastUpdated = Date.now();
+          return;
+        }
+        const finalContent = finalContentCandidate;
         await finishAICard(currentAICard, finalContent, log);
       } else {
         log?.debug?.(

package/src/onboarding.ts

@@ -106,6 +106,9 @@ function applyAccountConfig(params: {
     ...(input.messageType ? { messageType: input.messageType } : {}),
     ...(input.cardTemplateId ? { cardTemplateId: input.cardTemplateId } : {}),
     ...(input.cardTemplateKey ? { cardTemplateKey: input.cardTemplateKey } : {}),
+    ...(typeof input.maxReconnectCycles === "number"
+      ? { maxReconnectCycles: input.maxReconnectCycles }
+      : {}),
   };
 
   if (useDefault) {
@@ -304,6 +307,35 @@ export const dingtalkOnboardingAdapter: ChannelOnboardingAdapter = {
       initialValue: resolved.groupPolicy ?? "open",
     });
 
+    let maxReconnectCycles: number | undefined;
+    const wantsReconnectLimits = await prompter.confirm({
+      message: "Configure runtime reconnect cycle limit? (recommended)",
+      initialValue: typeof resolved.maxReconnectCycles === "number",
+    });
+    if (wantsReconnectLimits) {
+      const parsedCycles = Number(
+        String(
+          await prompter.text({
+            message: "Max runtime reconnect cycles",
+            placeholder: "10",
+            initialValue: String(resolved.maxReconnectCycles ?? 10),
+            validate: (value) => {
+              const raw = String(value ?? "").trim();
+              const num = Number(raw);
+              if (!raw) {
+                return "Required";
+              }
+              if (!Number.isInteger(num) || num < 1) {
+                return "Must be an integer >= 1";
+              }
+              return undefined;
+            },
+          }),
+        ).trim(),
+      );
+      maxReconnectCycles = Number.isInteger(parsedCycles) && parsedCycles > 0 ? parsedCycles : 10;
+    }
+
     const next = applyAccountConfig({
       cfg,
       accountId,
@@ -319,6 +351,7 @@ export const dingtalkOnboardingAdapter: ChannelOnboardingAdapter = {
         messageType,
         cardTemplateId,
         cardTemplateKey,
+        maxReconnectCycles,
       },
     });
 

package/src/proactive-risk-registry.ts

@@ -0,0 +1,89 @@
+type ProactiveRiskLevel = "low" | "medium" | "high";
+
+export interface ProactiveRiskObservation {
+  accountId: string;
+  targetId: string;
+  level: ProactiveRiskLevel;
+  reason: string;
+  source: string;
+  observedAtMs?: number;
+}
+
+export interface ProactiveRiskSnapshot {
+  level: ProactiveRiskLevel;
+  reason: string;
+  source: string;
+  observedAtMs: number;
+}
+
+const DEFAULT_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+const store = new Map<string, ProactiveRiskSnapshot>();
+
+function keyOf(accountId: string, targetId: string): string {
+  return `${accountId}:${targetId.trim()}`;
+}
+
+export function recordProactiveRiskObservation(observation: ProactiveRiskObservation): void {
+  const targetId = observation.targetId?.trim();
+  if (!observation.accountId || !targetId) {
+    return;
+  }
+
+  store.set(keyOf(observation.accountId, targetId), {
+    level: observation.level,
+    reason: observation.reason,
+    source: observation.source,
+    observedAtMs: observation.observedAtMs ?? Date.now(),
+  });
+}
+
+export function getProactiveRiskObservation(
+  accountId: string,
+  targetId: string,
+  nowMs = Date.now(),
+): ProactiveRiskSnapshot | null {
+  const target = targetId?.trim();
+  if (!accountId || !target) {
+    return null;
+  }
+
+  const key = keyOf(accountId, target);
+  const entry = store.get(key);
+  if (!entry) {
+    return null;
+  }
+  if (nowMs - entry.observedAtMs > DEFAULT_TTL_MS) {
+    store.delete(key);
+    return null;
+  }
+  return entry;
+}
+
+export function getProactiveRiskObservationForAny(
+  accountId: string,
+  targetIds: Array<string | null | undefined>,
+  nowMs = Date.now(),
+): ProactiveRiskSnapshot | null {
+  for (const candidate of targetIds) {
+    if (!candidate) {
+      continue;
+    }
+    const observation = getProactiveRiskObservation(accountId, candidate, nowMs);
+    if (observation) {
+      return observation;
+    }
+  }
+  return null;
+}
+
+export function deleteProactiveRiskObservation(accountId: string, targetId: string): void {
+  const target = targetId?.trim();
+  if (!accountId || !target) {
+    return;
+  }
+  store.delete(keyOf(accountId, target));
+}
+
+export function clearProactiveRiskObservationsForTest(): void {
+  store.clear();
+}

package/src/send-service.ts

@@ -13,6 +13,11 @@ import { getLogger } from "./logger-context";
 import { uploadMedia as uploadMediaUtil } from "./media-utils";
 import { detectMarkdownAndExtractTitle } from "./message-utils";
 import { resolveOriginalPeerId } from "./peer-id-registry";
+import {
+  deleteProactiveRiskObservation,
+  getProactiveRiskObservation,
+  recordProactiveRiskObservation,
+} from "./proactive-risk-registry";
 import { formatDingTalkErrorPayloadLog } from "./utils";
 import type {
   AxiosResponse,
@@ -26,6 +31,38 @@ import { AICardStatus } from "./types";
 
 export { detectMediaTypeFromExtension } from "./media-utils";
 
+function extractErrorCodeFromResponseData(data: unknown): string | null {
+  if (!data || typeof data !== "object") {
+    return null;
+  }
+
+  const payload = data as Record<string, unknown>;
+  const code = payload.code;
+  if (typeof code === "string" && code.trim()) {
+    return code.trim();
+  }
+
+  const subCode = payload.subCode;
+  if (typeof subCode === "string" && subCode.trim()) {
+    return subCode.trim();
+  }
+
+  return null;
+}
+
+function isProactivePermissionOrScopeError(code: string | null): boolean {
+  if (!code) {
+    return false;
+  }
+  return (
+    code.startsWith("Forbidden.AccessDenied") ||
+    code === "invalidParameter.userIds.invalid" ||
+    code === "invalidParameter.userIds.empty" ||
+    code === "invalidParameter.openConversationId.invalid" ||
+    code === "invalidParameter.robotCode.empty"
+  );
+}
+
 /**
  * Wrapper to upload media with shared getAccessToken binding.
  */
@@ -51,6 +88,12 @@ export async function sendProactiveTextOrMarkdown(
   const { targetId, isExplicitUser } = stripTargetPrefix(target);
   const resolvedTarget = resolveOriginalPeerId(targetId);
   const isGroup = !isExplicitUser && resolvedTarget.startsWith("cid");
+  const proactiveRisk = options.accountId
+    ? getProactiveRiskObservation(options.accountId, resolvedTarget)
+    : null;
+  const proactiveRiskTag = proactiveRisk
+    ? ` proactiveRisk=${proactiveRisk.level}:${proactiveRisk.reason}`
+    : "";
 
   const url = isGroup
     ? "https://api.dingtalk.com/v1.0/robot/groupMessages/send"
@@ -59,7 +102,7 @@ export async function sendProactiveTextOrMarkdown(
   const { useMarkdown, title } = detectMarkdownAndExtractTitle(text, options, "OpenClaw 提醒");
 
   log?.debug?.(
-    `[DingTalk] Sending proactive message to ${isGroup ? "group" : "user"} ${resolvedTarget} with title "${title}"`,
+    `[DingTalk] Sending proactive message to ${isGroup ? "group" : "user"} ${resolvedTarget} with title "${title}"${proactiveRiskTag}`,
   );
 
   // DingTalk proactive API uses message templates (sampleMarkdown / sampleText).
@@ -87,6 +130,9 @@ export async function sendProactiveTextOrMarkdown(
       data: payload,
       headers: { "x-acs-dingtalk-access-token": token, "Content-Type": "application/json" },
     });
+    if (options.accountId) {
+      deleteProactiveRiskObservation(options.accountId, resolvedTarget);
+    }
     return result.data;
   } catch (err: unknown) {
     const maybeAxiosError = err as {
@@ -94,13 +140,23 @@ export async function sendProactiveTextOrMarkdown(
       message?: string;
     };
     if (maybeAxiosError?.response) {
+      const errCode = extractErrorCodeFromResponseData(maybeAxiosError.response.data);
+      if (options.accountId && isProactivePermissionOrScopeError(errCode)) {
+        recordProactiveRiskObservation({
+          accountId: options.accountId,
+          targetId: resolvedTarget,
+          level: "high",
+          reason: errCode || "proactive-permission-error",
+          source: "proactive-api",
+        });
+      }
       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)
-        }`,
+        }${proactiveRiskTag}`,
       );
       if (maybeAxiosError.response.data !== undefined) {
         log?.error?.(
@@ -183,16 +239,36 @@ export async function sendProactiveMedia(
       data: payload,
       headers: { "x-acs-dingtalk-access-token": token, "Content-Type": "application/json" },
     });
+    if (options.accountId) {
+      deleteProactiveRiskObservation(options.accountId, resolvedTarget);
+    }
 
     const messageId = result.data?.processQueryKey || result.data?.messageId;
     return { ok: true, data: result.data, messageId };
   } catch (err: any) {
     log?.error?.(`[DingTalk] Failed to send proactive media: ${err.message}`);
+    const normalizedTarget = resolveOriginalPeerId(stripTargetPrefix(target).targetId);
+    const proactiveRisk = options.accountId
+      ? getProactiveRiskObservation(options.accountId, normalizedTarget)
+      : null;
+    const proactiveRiskTag = proactiveRisk
+      ? ` proactiveRisk=${proactiveRisk.level}:${proactiveRisk.reason}`
+      : "";
     if (axios.isAxiosError(err) && err.response) {
+      const errCode = extractErrorCodeFromResponseData(err.response.data);
+      if (options.accountId && isProactivePermissionOrScopeError(errCode)) {
+        recordProactiveRiskObservation({
+          accountId: options.accountId,
+          targetId: normalizedTarget,
+          level: "high",
+          reason: errCode || "proactive-permission-error",
+          source: "proactive-api",
+        });
+      }
       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?.(`[DingTalk] Proactive media response${statusLabel}${proactiveRiskTag}`);
       log?.error?.(formatDingTalkErrorPayloadLog("send.proactiveMedia", err.response.data));
     }
     return { ok: false, error: err.message };

package/src/types.ts

@@ -52,6 +52,12 @@ export interface DingTalkConfig extends OpenClawConfig {
   initialReconnectDelay?: number;
   maxReconnectDelay?: number;
   reconnectJitter?: number;
+  /** Maximum number of runtime reconnect cycles before giving up (default: 10) */
+  maxReconnectCycles?: number;
+  proactivePermissionHint?: {
+    enabled?: boolean;
+    cooldownHours?: number;
+  };
 }
 
 /**
@@ -79,6 +85,12 @@ export interface DingTalkChannelConfig {
   initialReconnectDelay?: number;
   maxReconnectDelay?: number;
   reconnectJitter?: number;
+  /** Maximum number of runtime reconnect cycles before giving up (default: 10) */
+  maxReconnectCycles?: number;
+  proactivePermissionHint?: {
+    enabled?: boolean;
+    cooldownHours?: number;
+  };
 }
 
 /**
@@ -201,6 +213,7 @@ export interface SendMessageOptions {
   filePath?: string;
   mediaUrl?: string;
   mediaType?: "image" | "voice" | "video" | "file";
+  accountId?: string;
 }
 
 /**
@@ -467,6 +480,8 @@ export interface ConnectionManagerConfig {
   initialDelay: number;
   maxDelay: number;
   jitter: number;
+  /** Maximum number of runtime reconnect cycles before giving up (default: 10) */
+  maxReconnectCycles?: number;
   /** Callback invoked when connection state changes */
   onStateChange?: (state: ConnectionState, error?: string) => void;
 }
@@ -551,6 +566,8 @@ export function resolveDingTalkAccount(
       initialReconnectDelay: dingtalk?.initialReconnectDelay,
       maxReconnectDelay: dingtalk?.maxReconnectDelay,
       reconnectJitter: dingtalk?.reconnectJitter,
+      maxReconnectCycles: dingtalk?.maxReconnectCycles,
+      proactivePermissionHint: dingtalk?.proactivePermissionHint,
     };
     return {
       ...config,