@soimy/dingtalk 3.1.0 → 3.1.1

package/package.json

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

package/src/config-schema.ts

@@ -75,6 +75,14 @@ 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),
+
+  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/inbound-handler.ts

@@ -16,12 +16,61 @@ 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,
+  recordProactiveRiskObservation,
+} 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.senderStaffId || params.senderId || "").trim();
+  if (!targetId || !/^\d+$/.test(targetId)) {
+    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;
+}
+
 /**
  * Download DingTalk media file via runtime media service (sandbox-compatible).
  * Files are stored in the global media inbound directory.
@@ -143,10 +192,45 @@ 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检测到当前用户标识为纯数字（\`${data.senderStaffId || senderId}\`）。企业内部机器人在定时/主动发送场景中，通常需要企业内部有效用户ID与完整授权。\n\n建议：\n1) 优先使用企业内部用户ID（如 managerXXXX）\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);
   }
 
+  if (isDirect && /^\d+$/.test((data.senderStaffId || senderId || "").trim())) {
+    recordProactiveRiskObservation({
+      accountId,
+      targetId: data.senderStaffId || senderId,
+      level: "high",
+      reason: "numeric-user-id",
+      source: "webhook-hint",
+    });
+  }
+
   // 2) Authorization guard (DM/group policy).
   let commandAuthorized = true;
   if (isDirect) {

package/src/proactive-risk-registry.ts

@@ -0,0 +1,64 @@
+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 clearProactiveRiskObservationsForTest(): void {
+  store.clear();
+}

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 { getProactiveRiskObservation } from "./proactive-risk-registry";
 import { formatDingTalkErrorPayloadLog } from "./utils";
 import type {
   AxiosResponse,
@@ -51,6 +52,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 +66,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).
@@ -100,7 +107,7 @@ export async function sendProactiveTextOrMarkdown(
       log?.error?.(
         `[DingTalk] Failed to send proactive message:${statusLabel} message=${
           maybeAxiosError.message || String(err)
-        }`,
+        }${proactiveRiskTag}`,
       );
       if (maybeAxiosError.response.data !== undefined) {
         log?.error?.(
@@ -188,11 +195,18 @@ export async function sendProactiveMedia(
     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 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,10 @@ export interface DingTalkConfig extends OpenClawConfig {
   initialReconnectDelay?: number;
   maxReconnectDelay?: number;
   reconnectJitter?: number;
+  proactivePermissionHint?: {
+    enabled?: boolean;
+    cooldownHours?: number;
+  };
 }
 
 /**
@@ -79,6 +83,10 @@ export interface DingTalkChannelConfig {
   initialReconnectDelay?: number;
   maxReconnectDelay?: number;
   reconnectJitter?: number;
+  proactivePermissionHint?: {
+    enabled?: boolean;
+    cooldownHours?: number;
+  };
 }
 
 /**
@@ -201,6 +209,7 @@ export interface SendMessageOptions {
   filePath?: string;
   mediaUrl?: string;
   mediaType?: "image" | "voice" | "video" | "file";
+  accountId?: string;
 }
 
 /**
@@ -551,6 +560,7 @@ export function resolveDingTalkAccount(
       initialReconnectDelay: dingtalk?.initialReconnectDelay,
       maxReconnectDelay: dingtalk?.maxReconnectDelay,
       reconnectJitter: dingtalk?.reconnectJitter,
+      proactivePermissionHint: dingtalk?.proactivePermissionHint,
     };
     return {
       ...config,