@soimy/dingtalk 3.0.0-beta.1 → 3.0.1

package/README.md

@@ -44,10 +44,70 @@ openclaw plugins install -l .
 2. 确保包含 `index.ts`, `openclaw.plugin.json` 和 `package.json`。
 3. 运行 `openclaw plugins list` 确认 `dingtalk` 已显示在列表中。
 
+### 安装后必做：配置插件信任白名单（`plugins.allow`）
+
+从 OpenClaw 新版本开始，如果发现了非内置插件且 `plugins.allow` 为空，会提示：
+
+```text
+[plugins] plugins.allow is empty; discovered non-bundled plugins may auto-load ...
+```
+
+这是一条安全告警（不是安装失败），建议显式写入你信任的插件 id。
+
+#### 步骤 1：确认插件 id
+
+本插件 id 固定为：`dingtalk`（定义于 `openclaw.plugin.json`）。
+
+也可用下面命令查看已发现插件：
+
+```bash
+openclaw plugins list
+```
+
+#### 步骤 2：在 `~/.openclaw/openclaw.json` 添加 `plugins.allow`
+
+```json5
+{
+  "plugins": {
+    "enabled": true,
+    "allow": ["dingtalk"]
+  }
+}
+```
+
+如果你还有其他已安装且需要启用的插件，请一并加入，例如：
+
+```json5
+{
+  "plugins": {
+    "allow": ["dingtalk", "telegram", "voice-call"]
+  }
+}
+```
+
+#### 步骤 3：重启 Gateway
+
+```bash
+openclaw gateway restart
+```
+
+> 注意：如果你之前已经配置过 `plugins.allow`，但没有 `dingtalk`，那么插件不会被加载。请把 `dingtalk` 加入该列表。
+
 ## 更新
 
+`openclaw plugins update` 使用插件 id（不是 npm 包名），并且仅适用于 npm 安装来源。
+
+如果你是通过 npm 安装本插件：
+
+```bash
+openclaw plugins update dingtalk
 ```
-openclaw plugins update @soimy/dingtalk
+
+如果你是本地源码/链接安装（`openclaw plugins install -l .`），请在插件目录更新代码后重启 Gateway：
+
+```bash
+git pull
+openclaw gateway restart
 ```
 
 ## 配置
@@ -140,12 +200,17 @@ openclaw configure --section channels
 
 ### 方法 2：手动配置文件
 
-在 `~/.openclaw/openclaw.json` 的 `channels` 下添加（仅作参考，交互式配置会自动生成）：
+在 `~/.openclaw/openclaw.json` 中添加（仅作参考，交互式配置会自动生成）：
 
-> 只添加dingtalk部分，内容参考上文钉钉开发者配置指南
+> 至少包含 `plugins.allow` 和 `channels.dingtalk` 两部分，内容参考上文钉钉开发者配置指南
 
 ```json5
 {
+  "plugins": {
+    "enabled": true,
+    "allow": ["dingtalk"]
+  },
+
   ...
   "channels": {
     "telegram": { ... },

package/package.json

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

package/src/channel.ts

@@ -30,6 +30,46 @@ import type {
 import { ConnectionState } from "./types";
 import { cleanupOrphanedTempFiles, getCurrentTimestamp } from "./utils";
 
+const processingDedupKeys = new Set<string>();
+const inboundCountersByAccount = new Map<
+  string,
+  {
+    received: number;
+    acked: number;
+    dedupSkipped: number;
+    inflightSkipped: number;
+    processed: number;
+    failed: number;
+    noMessageId: number;
+  }
+>();
+const INBOUND_COUNTER_LOG_EVERY = 10;
+
+function getInboundCounters(accountId: string) {
+  const existing = inboundCountersByAccount.get(accountId);
+  if (existing) {
+    return existing;
+  }
+  const created = {
+    received: 0,
+    acked: 0,
+    dedupSkipped: 0,
+    inflightSkipped: 0,
+    processed: 0,
+    failed: 0,
+    noMessageId: 0,
+  };
+  inboundCountersByAccount.set(accountId, created);
+  return created;
+}
+
+function logInboundCounters(log: any, accountId: string, reason: string): void {
+  const stats = getInboundCounters(accountId);
+  log?.info?.(
+    `[${accountId}] Inbound counters (${reason}): received=${stats.received}, acked=${stats.acked}, processed=${stats.processed}, dedupSkipped=${stats.dedupSkipped}, inflightSkipped=${stats.inflightSkipped}, failed=${stats.failed}, noMessageId=${stats.noMessageId}`,
+  );
+}
+
 // DingTalk Channel Definition (assembly layer).
 // Heavy logic is delegated to service modules for maintainability.
 export const dingtalkPlugin: DingTalkChannelPlugin = {
@@ -254,36 +294,75 @@ export const dingtalkPlugin: DingTalkChannelPlugin = {
 
       client.registerCallbackListener(TOPIC_ROBOT, async (res: any) => {
         const messageId = res.headers?.messageId;
+        const stats = getInboundCounters(account.accountId);
+        stats.received += 1;
         try {
           if (messageId) {
             client.socketCallBackResponse(messageId, { success: true });
+            stats.acked += 1;
           }
           const data = JSON.parse(res.data) as DingTalkInboundMessage;
 
           // Message deduplication key is bot-scoped to avoid cross-account conflicts.
           const robotKey = config.robotCode || config.clientId || account.accountId;
           const msgId = data.msgId || messageId;
+          const dedupKey = msgId ? `${robotKey}:${msgId}` : undefined;
 
-          if (!msgId) {
+          if (!dedupKey) {
             ctx.log?.warn?.(`[${account.accountId}] No message ID available for deduplication`);
-          } else {
-            const dedupKey = `${robotKey}:${msgId}`;
-            if (isMessageProcessed(dedupKey)) {
-              ctx.log?.debug?.(`[${account.accountId}] Skipping duplicate message: ${dedupKey}`);
-              return;
+            stats.noMessageId += 1;
+            await handleDingTalkMessage({
+              cfg,
+              accountId: account.accountId,
+              data,
+              sessionWebhook: data.sessionWebhook,
+              log: ctx.log,
+              dingtalkConfig: config,
+            });
+            stats.processed += 1;
+            if (stats.received % INBOUND_COUNTER_LOG_EVERY === 0) {
+              logInboundCounters(ctx.log, account.accountId, "periodic");
             }
-            markMessageProcessed(dedupKey);
+            return;
           }
 
-          await handleDingTalkMessage({
-            cfg,
-            accountId: account.accountId,
-            data,
-            sessionWebhook: data.sessionWebhook,
-            log: ctx.log,
-            dingtalkConfig: config,
-          });
+          if (isMessageProcessed(dedupKey)) {
+            ctx.log?.debug?.(`[${account.accountId}] Skipping duplicate message: ${dedupKey}`);
+            stats.dedupSkipped += 1;
+            logInboundCounters(ctx.log, account.accountId, "dedup-skipped");
+            return;
+          }
+
+          if (processingDedupKeys.has(dedupKey)) {
+            ctx.log?.debug?.(
+              `[${account.accountId}] Skipping in-flight duplicate message: ${dedupKey}`,
+            );
+            stats.inflightSkipped += 1;
+            logInboundCounters(ctx.log, account.accountId, "inflight-skipped");
+            return;
+          }
+
+          processingDedupKeys.add(dedupKey);
+          try {
+            await handleDingTalkMessage({
+              cfg,
+              accountId: account.accountId,
+              data,
+              sessionWebhook: data.sessionWebhook,
+              log: ctx.log,
+              dingtalkConfig: config,
+            });
+            stats.processed += 1;
+            markMessageProcessed(dedupKey);
+            if (stats.received % INBOUND_COUNTER_LOG_EVERY === 0) {
+              logInboundCounters(ctx.log, account.accountId, "periodic");
+            }
+          } finally {
+            processingDedupKeys.delete(dedupKey);
+          }
         } catch (error: any) {
+          stats.failed += 1;
+          logInboundCounters(ctx.log, account.accountId, "failed");
           ctx.log?.error?.(`[${account.accountId}] Error processing message: ${error.message}`);
         }
       });

package/src/connection-manager.ts

@@ -31,6 +31,21 @@ export class ConnectionManager {
   private attemptCount: number = 0;
   private reconnectTimer?: NodeJS.Timeout;
   private stopped: boolean = false;
+  private connectedAt?: number;
+  private consecutiveUnhealthyChecks: number = 0;
+
+  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 runtimeCounters = {
+    healthUnhealthyChecks: 0,
+    healthTriggeredReconnects: 0,
+    socketCloseEvents: 0,
+    runtimeDisconnects: 0,
+    reconnectAttempts: 0,
+    reconnectSuccess: 0,
+    reconnectFailures: 0,
+  };
 
   // Runtime monitoring resources
   private healthCheckInterval?: NodeJS.Timeout;
@@ -61,6 +76,13 @@ export class ConnectionManager {
     }
   }
 
+  private logRuntimeCounters(reason: string): void {
+    const c = this.runtimeCounters;
+    this.log?.info?.(
+      `[${this.accountId}] Runtime counters (${reason}): healthUnhealthyChecks=${c.healthUnhealthyChecks}, healthTriggeredReconnects=${c.healthTriggeredReconnects}, socketCloseEvents=${c.socketCloseEvents}, runtimeDisconnects=${c.runtimeDisconnects}, reconnectAttempts=${c.reconnectAttempts}, reconnectSuccess=${c.reconnectSuccess}, reconnectFailures=${c.reconnectFailures}`,
+    );
+  }
+
   /**
    * Calculate next reconnection delay with exponential backoff and jitter
    * Formula: delay = min(initialDelay * 2^attempt, maxDelay) * (1 ± jitter)
@@ -130,6 +152,8 @@ export class ConnectionManager {
 
       // Connection successful
       this.state = ConnectionStateEnum.CONNECTED;
+      this.connectedAt = Date.now();
+      this.consecutiveUnhealthyChecks = 0;
       this.notifyStateChange();
       const successfulAttempt = this.attemptCount;
       this.attemptCount = 0; // Reset counter on success
@@ -230,17 +254,51 @@ export class ConnectionManager {
         return;
       }
 
-      // If we believe we're connected but DWClient disagrees, trigger reconnection
-      if (this.state === ConnectionStateEnum.CONNECTED && !client.connected) {
-        this.log?.warn?.(
-          `[${this.accountId}] Connection health check failed - detected disconnection`,
+      if (this.state !== ConnectionStateEnum.CONNECTED) {
+        this.consecutiveUnhealthyChecks = 0;
+        return;
+      }
+
+      const now = Date.now();
+      const withinGraceWindow =
+        this.connectedAt !== undefined &&
+        now - this.connectedAt < ConnectionManager.HEALTH_CHECK_GRACE_MS;
+      if (withinGraceWindow) {
+        this.consecutiveUnhealthyChecks = 0;
+        return;
+      }
+
+      const socketReadyState = (client.socket as { readyState?: number } | undefined)?.readyState;
+      const socketOpen = socketReadyState === 1;
+      const unhealthy = !client.connected && !socketOpen;
+
+      if (!unhealthy) {
+        this.consecutiveUnhealthyChecks = 0;
+        return;
+      }
+
+      this.consecutiveUnhealthyChecks += 1;
+      this.runtimeCounters.healthUnhealthyChecks += 1;
+      if (
+        this.consecutiveUnhealthyChecks <
+        ConnectionManager.HEALTH_CHECK_UNHEALTHY_THRESHOLD
+      ) {
+        this.log?.debug?.(
+          `[${this.accountId}] Connection health check unhealthy (${this.consecutiveUnhealthyChecks}/${ConnectionManager.HEALTH_CHECK_UNHEALTHY_THRESHOLD}) connected=${String(client.connected)} socketReadyState=${socketReadyState ?? "unknown"}`,
         );
-        if (this.healthCheckInterval) {
-          clearInterval(this.healthCheckInterval);
-        }
-        this.handleRuntimeDisconnection();
+        return;
+      }
+
+      this.log?.warn?.(
+        `[${this.accountId}] Connection health check failed - detected disconnection`,
+      );
+      this.runtimeCounters.healthTriggeredReconnects += 1;
+      this.logRuntimeCounters("health-triggered-reconnect");
+      if (this.healthCheckInterval) {
+        clearInterval(this.healthCheckInterval);
       }
-    }, 5000); // Check every 5 seconds
+      this.handleRuntimeDisconnection();
+    }, ConnectionManager.HEALTH_CHECK_INTERVAL_MS);
 
     // Additionally, if we have access to the socket, monitor its events
     // The DWClient uses 'ws' WebSocket library which extends EventEmitter
@@ -251,9 +309,11 @@ export class ConnectionManager {
 
       // Handler for socket close event
       this.socketCloseHandler = (code: number, reason: string) => {
+        this.runtimeCounters.socketCloseEvents += 1;
         this.log?.warn?.(
           `[${this.accountId}] WebSocket closed event (code: ${code}, reason: ${reason || "none"})`,
         );
+        this.logRuntimeCounters("socket-close");
 
         // Only trigger reconnection if we were previously connected and not stopping
         if (!this.stopped && this.state === ConnectionStateEnum.CONNECTED) {
@@ -319,10 +379,13 @@ export class ConnectionManager {
     this.log?.warn?.(
       `[${this.accountId}] Runtime disconnection detected, initiating reconnection...`,
     );
+    this.runtimeCounters.runtimeDisconnects += 1;
 
     this.state = ConnectionStateEnum.DISCONNECTED;
     this.notifyStateChange("Runtime disconnection detected");
     this.attemptCount = 0; // Reset attempt counter for runtime reconnection
+    this.connectedAt = undefined;
+    this.consecutiveUnhealthyChecks = 0;
 
     // Clear any existing timer
     this.clearReconnectTimer();
@@ -349,17 +412,24 @@ export class ConnectionManager {
     }
 
     this.log?.info?.(`[${this.accountId}] Attempting to reconnect...`);
+    this.runtimeCounters.reconnectAttempts += 1;
 
     try {
       await this.connect();
       this.log?.info?.(`[${this.accountId}] Reconnection successful`);
+      this.runtimeCounters.reconnectSuccess += 1;
+      this.logRuntimeCounters("reconnect-success");
     } catch (err: any) {
       if (this.stopped) {
         return;
       }
 
       this.log?.error?.(`[${this.accountId}] Reconnection failed: ${err.message}`);
+      this.runtimeCounters.reconnectFailures += 1;
+      this.logRuntimeCounters("reconnect-failed");
       this.state = ConnectionStateEnum.FAILED;
+      this.connectedAt = undefined;
+      this.consecutiveUnhealthyChecks = 0;
       this.notifyStateChange(err.message);
 
       // Continue runtime recovery instead of getting stuck in FAILED.
@@ -387,6 +457,8 @@ export class ConnectionManager {
 
     this.stopped = true;
     this.state = ConnectionStateEnum.DISCONNECTING;
+    this.connectedAt = undefined;
+    this.consecutiveUnhealthyChecks = 0;
 
     // Clear reconnect timer
     this.clearReconnectTimer();

package/src/group-members-store.ts

@@ -0,0 +1,45 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+function groupMembersFilePath(storePath: string, groupId: string): string {
+  const dir = path.join(path.dirname(storePath), "dingtalk-members");
+  const safeId = groupId.replace(/\+/g, "-").replace(/\//g, "_");
+  return path.join(dir, `${safeId}.json`);
+}
+
+export function noteGroupMember(
+  storePath: string,
+  groupId: string,
+  userId: string,
+  name: string,
+): void {
+  if (!userId || !name) {
+    return;
+  }
+  const filePath = groupMembersFilePath(storePath, groupId);
+  let roster: Record<string, string> = {};
+  try {
+    roster = JSON.parse(fs.readFileSync(filePath, "utf-8"));
+  } catch {}
+  if (roster[userId] === name) {
+    return;
+  }
+  roster[userId] = name;
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, JSON.stringify(roster, null, 2));
+}
+
+export function formatGroupMembers(storePath: string, groupId: string): string | undefined {
+  const filePath = groupMembersFilePath(storePath, groupId);
+  let roster: Record<string, string> = {};
+  try {
+    roster = JSON.parse(fs.readFileSync(filePath, "utf-8"));
+  } catch {
+    return undefined;
+  }
+  const entries = Object.entries(roster);
+  if (entries.length === 0) {
+    return undefined;
+  }
+  return entries.map(([id, name]) => `${name} (${id})`).join(", ");
+}

package/src/inbound-handler.ts

@@ -1,5 +1,3 @@
-import * as fs from "node:fs";
-import * as path from "node:path";
 import axios from "axios";
 import { normalizeAllowFrom, isSenderAllowed, isSenderGroupAllowed } from "./access-control";
 import { getAccessToken } from "./auth";
@@ -14,6 +12,7 @@ import {
   streamAICard,
 } from "./card-service";
 import { resolveGroupConfig } from "./config";
+import { formatGroupMembers, noteGroupMember } from "./group-members-store";
 import { setCurrentLogger } from "./logger-context";
 import { extractMessageContent } from "./message-utils";
 import { registerPeerId } from "./peer-id-registry";
@@ -23,46 +22,6 @@ import type { DingTalkConfig, HandleDingTalkMessageParams, MediaFile } from "./t
 import { AICardStatus } from "./types";
 import { maskSensitiveData } from "./utils";
 
-// ============ Group Members Persistence ============
-
-function groupMembersFilePath(storePath: string, groupId: string): string {
-  const dir = path.join(path.dirname(storePath), "dingtalk-members");
-  const safeId = groupId.replace(/\+/g, "-").replace(/\//g, "_");
-  return path.join(dir, `${safeId}.json`);
-}
-
-function noteGroupMember(storePath: string, groupId: string, userId: string, name: string): void {
-  if (!userId || !name) {
-    return;
-  }
-  const filePath = groupMembersFilePath(storePath, groupId);
-  let roster: Record<string, string> = {};
-  try {
-    roster = JSON.parse(fs.readFileSync(filePath, "utf-8"));
-  } catch {}
-  if (roster[userId] === name) {
-    return;
-  }
-  roster[userId] = name;
-  fs.mkdirSync(path.dirname(filePath), { recursive: true });
-  fs.writeFileSync(filePath, JSON.stringify(roster, null, 2));
-}
-
-function formatGroupMembers(storePath: string, groupId: string): string | undefined {
-  const filePath = groupMembersFilePath(storePath, groupId);
-  let roster: Record<string, string> = {};
-  try {
-    roster = JSON.parse(fs.readFileSync(filePath, "utf-8"));
-  } catch {
-    return undefined;
-  }
-  const entries = Object.entries(roster);
-  if (entries.length === 0) {
-    return undefined;
-  }
-  return entries.map(([id, name]) => `${name} (${id})`).join(", ");
-}
-
 /**
  * Download DingTalk media file via runtime media service (sandbox-compatible).
  * Files are stored in the global media inbound directory.