@dingtalk-real-ai/dingtalk-connector 0.8.15 → 0.8.16

package/CHANGELOG.md

@@ -5,6 +5,22 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.8.16] - 2026-04-16
+
+### 修复 / Fixes
+- 🐛 **AI Card 流式更新 QPS 限流** - 新增全局令牌桶限流器（`cardRateLimiter`），所有会话共享 20 QPS 速率限制，避免多会话并发时总 QPS 叠加超过钉钉 API 限制；遇到 403 QpsLimit 自动退避 2s 后重试  
+  **AI Card streaming QPS rate limiting** - Added global token bucket rate limiter shared across all sessions (20 QPS cap) with automatic 2s backoff and retry on 403 QpsLimit
+
+- 🐛 **streamAICard null card 崩溃** - 修复 `createAICardForTarget` 返回 `null` 后调用方通过 `as any` 绕过类型检查导致 `Cannot read properties of null` 崩溃，添加 null 守卫  
+  **streamAICard null card crash** - Fixed crash when `createAICardForTarget` returns `null` and callers bypass type checking; added null guard
+
+- 🐛 **插件配置格式兼容性** - 修复 `package.json` 中缺少 `openclaw.channels` 数组导致旧版 OpenClaw 框架安装失败的问题，同时保留新版 `openclaw.channel` 对象格式  
+  **Plugin config format compatibility** - Fixed missing `openclaw.channels` array in `package.json` that caused installation failure on older OpenClaw framework versions; both old and new config formats are now present
+
+### 改进 / Improvements
+- ✅ **单实例节流间隔优化** - `reply-dispatcher.ts` 的 `updateInterval` 从 500ms 增大到 800ms，配合全局限流器降低单实例发送频率  
+  **Per-instance throttle interval** - Increased `updateInterval` from 500ms to 800ms to complement global rate limiter
+
 ## [0.8.15] - 2026-04-15
 
 ### 新增 / Added

package/docs/RELEASE_NOTES_V0.8.16.md

@@ -0,0 +1,40 @@
+# Release Notes - v0.8.15-beta.1
+
+## 🎉 新版本亮点 / Highlights
+
+本次 beta 版本主要修复 AI Card 流式更新频繁触发钉钉 QPS 限流的问题，通过引入全局令牌桶限流器，确保多会话并发时不超过钉钉 API 速率限制。
+
+This beta release fixes frequent DingTalk QPS rate limiting during AI Card streaming updates by introducing a global token bucket rate limiter that enforces API rate limits across all concurrent sessions.
+
+## 🐛 修复 / Fixes
+
+- **AI Card 流式更新 QPS 限流 / AI Card streaming QPS rate limiting**  
+  新增全局令牌桶限流器（`cardRateLimiter`），所有会话共享同一速率限制（20 QPS），避免多会话并发时总 QPS 叠加超过钉钉 API 限制（~40 次/秒）。遇到 403 QpsLimit 错误时自动退避 2 秒后重试一次，确保 finalize 等关键更新不丢失。  
+  Added global token bucket rate limiter (`cardRateLimiter`) shared across all sessions (20 QPS cap). Automatically backs off for 2 seconds and retries once on 403 QpsLimit errors, ensuring critical updates like finalize are not lost.
+
+- **streamAICard null card 崩溃 / streamAICard null card crash**  
+  修复 `createAICardForTarget` 创建失败返回 `null` 后，调用方通过 `as any` 绕过类型检查传入 `streamAICard`，导致 `Cannot read properties of null (reading 'tokenExpireTime')` 崩溃的问题。现在 `streamAICard` 入口添加了 null 守卫，安全跳过并打印警告日志。  
+  Fixed crash when `createAICardForTarget` returns `null` and callers bypass type checking with `as any`. Added null guard at `streamAICard` entry point.
+
+## ✅ 改进 / Improvements
+
+- **单实例节流间隔优化 / Per-instance throttle interval optimization**  
+  `reply-dispatcher.ts` 中的 `updateInterval` 从 500ms 增大到 800ms，配合全局限流器降低单实例发送频率，减少不必要的 API 调用。  
+  Increased `updateInterval` from 500ms to 800ms in `reply-dispatcher.ts` to complement the global rate limiter and reduce unnecessary API calls.
+
+## 📥 安装升级 / Installation & Upgrade
+
+```bash
+openclaw plugins install @dingtalk-real-ai/dingtalk-connector@0.8.15-beta.1
+```
+
+## 🔗 相关链接 / Related Links
+
+- [完整变更日志 / Full Changelog](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/blob/main/CHANGELOG.md)
+- [使用文档 / Documentation](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/blob/main/README.md)
+
+---
+
+**发布日期 / Release Date**：2026-04-16  
+**版本号 / Version**：v0.8.16 
+**兼容性 / Compatibility**：OpenClaw Gateway 0.4.0+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dingtalk-real-ai/dingtalk-connector",
-  "version": "0.8.15",
+  "version": "0.8.16",
   "description": "Official OpenClaw DingTalk channel plugin | 钉钉官方 OpenClaw 插件",
   "main": "index.ts",
   "type": "module",
@@ -87,6 +87,9 @@
     }
   },
   "openclaw": {
+    "channels": [
+      "dingtalk-connector"
+    ],
     "extensions": [
       "./index.ts"
     ],
@@ -95,7 +98,10 @@
       "label": "DingTalk",
       "selectionLabel": "DingTalk (钉钉)",
       "blurb": "Official DingTalk plugin with AI Card streaming & multi-agent routing | 钉钉官方插件，支持 AI Card 流式响应与多 Agent 路由",
-      "aliases": ["dingtalk", "钉钉"],
+      "aliases": [
+        "dingtalk",
+        "钉钉"
+      ],
       "order": 33,
       "quickstartAllowFrom": true
     },

package/src/reply-dispatcher.ts

@@ -96,8 +96,10 @@ export function createDingtalkReplyDispatcher(params: CreateDingtalkReplyDispatc
   let asyncModeFullResponse = "";
   
   // ✅ 节流控制：避免频繁调用钉钉 API 导致 QPS 限流
+  // 全局令牌桶限流器已在 streamAICard 内部实现（card.ts），此处的 updateInterval
+  // 作为单实例级别的前置过滤，减少不必要的 streamAICard 调用
   let lastUpdateTime = 0;
-  const updateInterval = 500; // 最小更新间隔 500ms（钉钉 QPS 限制：40 次/秒，保守起见设为 0.5 秒）
+  const updateInterval = 800; // 最小更新间隔 800ms（配合 card.ts 全局限流器，降低单实例发送频率）
 
   // ✅ 错误兜底：防止重复发送错误消息
   const deliveredErrorTypes = new Set<string>();
@@ -460,6 +462,8 @@ export function createDingtalkReplyDispatcher(params: CreateDingtalkReplyDispatc
           if (currentCardTarget) {
             const now = Date.now();
             if (now - lastUpdateTime >= updateInterval) {
+              // ✅ 乐观更新：防止并发回调在 await 期间通过节流检查
+              lastUpdateTime = now;
               try {
                 await streamAICard(
                   currentCardTarget as any,
@@ -468,7 +472,6 @@ export function createDingtalkReplyDispatcher(params: CreateDingtalkReplyDispatc
                   account.config as DingtalkConfig,
                   log
                 );
-                lastUpdateTime = now;
                 log.info(`[DingTalk][deliver] ✅ block 更新到 AI Card 成功`);
               } catch (streamErr: any) {
                 log.error(`[DingTalk][deliver] ❌ block 更新 AI Card 失败：${streamErr.message}`);
@@ -593,6 +596,10 @@ export function createDingtalkReplyDispatcher(params: CreateDingtalkReplyDispatc
             
             log.debug(`[DingTalk][onPartialReply] 更新 AI Card，显示文本长度=${displayContent.length}`);
             
+            // ✅ 乐观更新：在发起 HTTP 请求前立即更新 lastUpdateTime，
+            // 防止并发的 onPartialReply 回调在 await 期间通过节流检查，
+            // 导致多个请求同时打到同一张卡片触发服务端 403 并发保护
+            lastUpdateTime = now;
             try {
               await streamAICard(
                 currentCardTarget as any,
@@ -601,20 +608,12 @@ export function createDingtalkReplyDispatcher(params: CreateDingtalkReplyDispatc
                 account.config as DingtalkConfig,
                 log
               );
-              lastUpdateTime = now;
               log.debug(`[DingTalk][onPartialReply] ✅ AI Card 更新成功`);
             } catch (err: any) {
-              // 安全检查：确保 code 存在且为字符串
-              const errorCode = err.response?.data?.code;
-              if (err.response?.status === 403 && typeof errorCode === 'string' && errorCode.includes('QpsLimit')) {
-                // QPS 限流，跳过本次更新；同步更新节流时间，防止立即重试再次触发限流
-                lastUpdateTime = now;
-                log.warn(`[DingTalk][AICard] QPS 限流，跳过本次更新`);
-              } else {
-                log.error(`[DingTalk][onPartialReply] ❌ AI Card 更新失败：${err.message}`);
-                // ✅ 发送兜底错误消息，但不抛出异常，避免中断后续处理
-                await sendFallbackErrorMessage('sendMessage', err.message);
-              }
+              // QPS 限流已在 streamAICard 内部处理（自动退避+重试），
+              // 到达此处说明重试也失败了，记录错误但不中断流式更新
+              log.error(`[DingTalk][onPartialReply] ❌ AI Card 更新失败：${err.message}`);
+              await sendFallbackErrorMessage('sendMessage', err.message);
             }
           } else {
             log.debug(`[DingTalk][onPartialReply] 节流控制，跳过本次更新（距离上次更新 ${now - lastUpdateTime}ms）`);

package/src/services/messaging/card.ts

@@ -11,6 +11,109 @@ import { dingtalkHttp } from "../../utils/http-client.ts";
 
 const AI_CARD_TEMPLATE_ID = "02fcf2f4-5e02-4a85-b672-46d1f715543e.schema";
 
+/**
+ * 钉钉卡片 API 的最大 QPS（官方限制约 40 次/秒）。
+ * 保守取 20，为 createAICardForTarget / finishAICard 等非流式调用留余量。
+ */
+const CARD_API_MAX_QPS = 20;
+
+/** QPS 限流退避时长（ms），遇到 403 QpsLimit 后暂停发送 */
+const QPS_BACKOFF_DURATION_MS = 2_000;
+
+// ============ 全局令牌桶限流器 ============
+
+/**
+ * 全局令牌桶限流器，所有 streamAICard 调用共享。
+ *
+ * 解决的问题：每个 reply-dispatcher 实例有独立的 500ms 节流间隔，
+ * 但多个会话并发时总 QPS 会叠加超过钉钉 API 限制（40 次/秒），
+ * 导致频繁触发 403 QpsLimit 错误。
+ *
+ * 工作原理：
+ * - 令牌桶以 CARD_API_MAX_QPS 的速率补充令牌
+ * - 每次 API 调用前消耗一个令牌，无令牌时等待
+ * - 遇到 QpsLimit 错误时触发退避，暂停所有调用
+ */
+const cardRateLimiter = {
+  /** 当前可用令牌数 */
+  tokens: CARD_API_MAX_QPS,
+  /** 上次令牌补充时间 */
+  lastRefillTime: Date.now(),
+  /** QPS 退避截止时间（遇到限流错误后设置） */
+  backoffUntil: 0,
+
+  /**
+   * 补充令牌：按时间流逝恢复令牌数
+   */
+  refill(): void {
+    const now = Date.now();
+    const elapsedSeconds = (now - this.lastRefillTime) / 1000;
+    if (elapsedSeconds > 0) {
+      this.tokens = Math.min(
+        CARD_API_MAX_QPS,
+        this.tokens + elapsedSeconds * CARD_API_MAX_QPS,
+      );
+      this.lastRefillTime = now;
+    }
+  },
+
+  /**
+   * 等待直到有可用令牌，或退避期结束
+   * @returns 等待的毫秒数（0 表示无需等待）
+   */
+  async waitForToken(): Promise<number> {
+    let totalWaitMs = 0;
+
+    // 如果处于退避期，先等待退避结束
+    const now = Date.now();
+    if (now < this.backoffUntil) {
+      const backoffWaitMs = this.backoffUntil - now;
+      await sleep(backoffWaitMs);
+      totalWaitMs += backoffWaitMs;
+    }
+
+    this.refill();
+
+    // 如果没有可用令牌，等待直到有令牌
+    if (this.tokens < 1) {
+      const waitMs = Math.ceil((1 - this.tokens) / CARD_API_MAX_QPS * 1000);
+      await sleep(waitMs);
+      totalWaitMs += waitMs;
+      this.refill();
+    }
+
+    this.tokens -= 1;
+    return totalWaitMs;
+  },
+
+  /**
+   * 触发退避：遇到 QpsLimit 错误时调用
+   */
+  triggerBackoff(): void {
+    this.backoffUntil = Date.now() + QPS_BACKOFF_DURATION_MS;
+    // 清空令牌，退避期结束后重新补充
+    this.tokens = 0;
+    this.lastRefillTime = Date.now() + QPS_BACKOFF_DURATION_MS;
+  },
+};
+
+/** 简单的 sleep 工具函数 */
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * 判断错误是否为钉钉 QPS 限流错误
+ */
+function isQpsLimitError(err: any): boolean {
+  const errorCode = err?.response?.data?.code;
+  return (
+    err?.response?.status === 403 &&
+    typeof errorCode === "string" &&
+    errorCode.includes("QpsLimit")
+  );
+}
+
 /** AI Card 状态 */
 const AICardStatus = {
   PROCESSING: "1",
@@ -204,6 +307,9 @@ async function ensureValidToken(
 
 /**
  * 流式更新 AI Card 内容
+ *
+ * 内置全局令牌桶限流：所有会话共享同一速率限制，
+ * 遇到 QpsLimit 错误时自动退避 2 秒后重试一次。
  */
 export async function streamAICard(
   card: AICardInstance,
@@ -212,11 +318,22 @@ export async function streamAICard(
   config?: DingtalkConfig,
   log?: any,
 ): Promise<void> {
+  // 防御 null card（createAICardForTarget 失败返回 null，调用方可能用 as any 绕过类型检查）
+  if (!card) {
+    log?.warn?.(`[DingTalk][AICard] streamAICard 收到 null card，跳过更新`);
+    return;
+  }
   // 确保 token 有效
   if (config) {
     await ensureValidToken(card, config);
   }
   if (!card.inputingStarted) {
+    // 等待全局限流令牌（INPUTING 状态切换也消耗 QPS）
+    const inputingWaitMs = await cardRateLimiter.waitForToken();
+    if (inputingWaitMs > 0) {
+      log?.debug?.(`[DingTalk][AICard] INPUTING 等待限流令牌 ${inputingWaitMs}ms`);
+    }
+
     const statusBody = {
       outTrackId: card.cardInstanceId,
       cardData: {
@@ -246,6 +363,10 @@ export async function streamAICard(
         `[DingTalk][AICard] INPUTING 响应：status=${statusResp.status}`,
       );
     } catch (err: any) {
+      if (isQpsLimitError(err)) {
+        cardRateLimiter.triggerBackoff();
+        log?.warn?.(`[DingTalk][AICard] INPUTING 触发 QPS 限流，退避 ${QPS_BACKOFF_DURATION_MS}ms`);
+      }
       log?.error?.(`[DingTalk][AICard] INPUTING 切换失败：${err.message}`);
       throw err;
     }
@@ -263,6 +384,12 @@ export async function streamAICard(
     isError: false,
   };
 
+  // 等待全局限流令牌
+  const streamWaitMs = await cardRateLimiter.waitForToken();
+  if (streamWaitMs > 0) {
+    log?.debug?.(`[DingTalk][AICard] streaming 等待限流令牌 ${streamWaitMs}ms`);
+  }
+
   log?.info?.(
     `[DingTalk][AICard] PUT /v1.0/card/streaming contentLen=${content.length} isFinalize=${finished}`,
   );
@@ -281,6 +408,31 @@ export async function streamAICard(
       `[DingTalk][AICard] streaming 响应：status=${streamResp.status}`,
     );
   } catch (err: any) {
+    if (isQpsLimitError(err)) {
+      // 触发退避后重试一次，确保 finalize 等关键更新不丢失
+      cardRateLimiter.triggerBackoff();
+      log?.warn?.(`[DingTalk][AICard] streaming 触发 QPS 限流，退避 ${QPS_BACKOFF_DURATION_MS}ms 后重试`);
+      await cardRateLimiter.waitForToken();
+      try {
+        // 重试时更新 guid 避免重复
+        body.guid = `${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+        await dingtalkHttp.put(
+          `${DINGTALK_API}/v1.0/card/streaming`,
+          body,
+          {
+            headers: {
+              "x-acs-dingtalk-access-token": card.accessToken,
+              "Content-Type": "application/json",
+            },
+          },
+        );
+        log?.info?.(`[DingTalk][AICard] streaming 重试成功`);
+        return;
+      } catch (retryErr: any) {
+        log?.error?.(`[DingTalk][AICard] streaming 重试失败：${retryErr.message}`);
+        throw retryErr;
+      }
+    }
     throw err;
   }
 }