@dingtalk-real-ai/dingtalk-connector 0.8.2 → 0.8.3-beta.1

package/CHANGELOG.md

@@ -5,6 +5,37 @@ 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.3-beta.1] - 2026-03-24
+
+### 修复 / Fixes
+- 🐛 **兼容旧版 OpenClaw Gateway（createPluginRuntimeStore 缺失）** - 修复在旧版 OpenClaw Gateway 上加载插件时报错 `TypeError: (0 , _pluginSdk.createPluginRuntimeStore) is not a function` 的问题。根因是 `src/runtime.ts` 直接从 `openclaw/plugin-sdk` 导入 `createPluginRuntimeStore`，而该函数在旧版 SDK 中并不存在。现已替换为内联实现的 `createRuntimeStore`，功能完全等价，兼容所有版本的 OpenClaw  
+  **Compatible with older OpenClaw Gateway (missing createPluginRuntimeStore)** - Fixed `TypeError: (0 , _pluginSdk.createPluginRuntimeStore) is not a function` when loading the plugin on older OpenClaw Gateway versions. Root cause: `src/runtime.ts` imported `createPluginRuntimeStore` from `openclaw/plugin-sdk`, which doesn't exist in older SDK versions. Replaced with an inline `createRuntimeStore` implementation that is fully equivalent and compatible with all OpenClaw versions
+
+- 🐛 **openclaw 依赖版本约束放宽** - 将 `package.json` 中的 `"openclaw": "^2026.3.0"` 改为 `"openclaw": "*"`，避免版本约束导致安装失败或与用户已安装版本冲突  
+  **Relaxed openclaw dependency version constraint** - Changed `"openclaw": "^2026.3.0"` to `"openclaw": "*"` in `package.json` to avoid installation failures or conflicts with the user's installed version
+
+## [0.8.3] - 2026-03-24
+
+### 修复 / Fixes
+- 🐛 **兼容 OpenClaw Gateway 新版本** - 修复在 OpenClaw Gateway 2026.3.22+ 版本下安装插件时报错 `ERR_PACKAGE_PATH_NOT_EXPORTED: Package subpath './plugin-sdk/compat' is not defined by "exports"` 的问题。根因是 `src/runtime.ts` 使用了已被新版 SDK 移除的 `openclaw/plugin-sdk/compat` 子路径，现已改为从 `openclaw/plugin-sdk` 主入口导入，对所有版本（2026.3.1+）均兼容  
+  **Compatible with newer OpenClaw Gateway versions** - Fixed `ERR_PACKAGE_PATH_NOT_EXPORTED: Package subpath './plugin-sdk/compat' is not defined by "exports"` when installing under OpenClaw Gateway 2026.3.22+. Root cause: `src/runtime.ts` imported from the removed `openclaw/plugin-sdk/compat` sub-path; now imports from the `openclaw/plugin-sdk` main entry, compatible with all versions (2026.3.1+)
+
+- ✅ **AI 卡片流式更新延迟优化** - 改动前 `onReplyStart` 串行等待 AI Card 创建（约 500ms~1s），期间 partial reply 全部丢弃，节流间隔 1000ms 也过于保守。改动后 AI Card 创建改为 fire-and-forget 与 AI 生成并行，节流间隔调整为 500ms，流式内容能更早更频繁地呈现  
+  **AI card progressive update latency improvement** - Previously `onReplyStart` awaited AI Card creation serially (~500ms–1s), discarding all partial replies during that window, with a 1000ms throttle too conservative for short replies. AI Card creation now runs fire-and-forget in parallel with AI generation; throttle reduced to 500ms for earlier and more frequent streaming updates
+
+- 🐛 **多 Agent 路由与 sharedMemoryAcrossConversations 冲突** - 修复配置 `sharedMemoryAcrossConversations: true` 时，多群分配不同 Agent 的 bindings 全部路由到同一 Agent 的问题。路由匹配现在使用专用的 `peerId`（真实 peer 标识，不受会话隔离配置影响），session 构建使用 `sessionPeerId`，两者职责严格分离  
+  **Multi-Agent routing conflict with sharedMemoryAcrossConversations** - Fixed all bindings resolving to the same Agent when `sharedMemoryAcrossConversations: true`. Routing now uses dedicated `peerId` (real peer identifier, unaffected by session isolation config); session construction uses `sessionPeerId` with strict separation of responsibilities
+
+- 🐛 **发送图片失败** - 修复发送图片时出现异常的问题 ([#316](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/issues/316))  
+  **Image sending failure** - Fixed an issue where sending images would fail with an error ([#316](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/issues/316))
+
+- 🐛 **发送人昵称与群名称未正确传递给 AI** - 修复会话上下文中 `SenderName` 字段错误传入用户 ID（而非昵称）、`GroupSubject` 字段错误传入群 ID（而非群名称）的问题，AI 现在能正确获取发送人的钉钉昵称和所在群的名称  
+  **Sender nickname and group name not passed to AI** - Fixed `SenderName` being set to user ID instead of display name, and `GroupSubject` being set to group ID instead of group title; AI now correctly receives the sender's nickname and group name
+
+### 改进 / Improvements
+- ✨ **消息队列繁忙时的即时排队反馈** - 当用户快速连续发送消息、上一条仍在处理中时，新消息现在会立即弹出一条 AI Card 气泡显示排队提示文案，同时贴上"思考中"表情。等轮到该消息处理时，气泡**原地更新**为最终回复内容，不会额外多发一条消息  
+  **Instant queue acknowledgement when busy** - When a user sends messages in quick succession while the previous one is still processing, the new message now immediately shows an AI Card bubble with a queuing acknowledgement and a "thinking" emoji. When it's the message's turn, the same bubble is **updated in place** with the final reply — no extra message is sent
+
 ## [0.8.2] - 2026-03-22
 
 ### 修复 / Fixes

package/docs/AGENT_ROUTING.md

@@ -0,0 +1,335 @@
+# Agent 路由与 SessionKey 规范
+
+本文档是 DingTalk OpenClaw Connector 中 **Agent 路由（bindings）** 和 **SessionKey 构建** 的完整开发规范，供新功能开发和代码审查参考。
+
+涉及文件：
+- `src/utils/session.ts` — `buildSessionContext()` 函数，构建会话上下文
+- `src/core/message-handler.ts` — bindings 路由匹配、sessionKey 构建、消息队列管理
+
+---
+
+## 一、SessionContext 字段总览
+
+`buildSessionContext()` 返回的 `SessionContext` 包含以下字段：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `channel` | `'dingtalk-connector'` | 固定值，标识频道来源 |
+| `accountId` | `string` | 当前钉钉账号 ID |
+| `chatType` | `'direct' \| 'group'` | 会话类型，单聊或群聊 |
+| `peerId` | `string` | **路由匹配专用**，真实 peer 标识（群聊为 `conversationId`，单聊为 `senderId`），**不受任何会话隔离配置影响** |
+| `sessionPeerId` | `string` | **session/memory 隔离键**，用于构建 `sessionKey` 和消息队列 key，**受会话隔离配置影响，可能与 `peerId` 不同** |
+| `conversationId` | `string?` | 群聊会话 ID，单聊时为 `undefined` |
+| `senderName` | `string?` | 发送者昵称 |
+| `groupSubject` | `string?` | 群名称，单聊时为 `undefined` |
+
+其中 `channel`、`accountId`、`chatType`、`conversationId`、`senderName`、`groupSubject` 都是直接从消息原始字段透传的，没有歧义。
+
+**需要特别注意的是 `peerId` 和 `sessionPeerId` 这两个字段**，它们都是 peer 标识，但职责完全不同，**不能混用**：
+
+- **路由匹配（去哪个 Agent）** → 使用 `peerId`
+- **session 隔离（共享多大范围的上下文）** → 使用 `sessionPeerId`
+
+---
+
+## 二、buildSessionContext() 完整逻辑
+
+`buildSessionContext()` 在 `src/utils/session.ts` 中定义，每条消息到达时调用一次，根据消息原始字段和账号配置，决定 `peerId` 和 `sessionPeerId` 的值。
+
+### 2.1 输入参数
+
+| 参数 | 来源 | 说明 |
+|------|------|------|
+| `accountId` | 账号配置 key | 当前钉钉账号标识 |
+| `senderId` | 消息原始字段 `data.senderStaffId` | 发送者 userId |
+| `senderName` | 消息原始字段 `data.senderNick` | 发送者昵称 |
+| `conversationType` | 消息原始字段 `data.conversationType` | `"1"` = 单聊，其他 = 群聊 |
+| `conversationId` | 消息原始字段 `data.conversationId` | 群聊的会话 ID |
+| `groupSubject` | 消息原始字段 `data.conversationTitle` | 群名称 |
+| `separateSessionByConversation` | `config.separateSessionByConversation` | 是否按会话区分 session |
+| `groupSessionScope` | `config.groupSessionScope` | 群聊 session 粒度 |
+| `sharedMemoryAcrossConversations` | `config.sharedMemoryAcrossConversations` | 是否跨会话共享记忆 |
+
+### 2.2 peerId 的计算规则（固定，不受配置影响）
+
+```
+peerId = isDirect ? senderId : (conversationId || senderId)
+```
+
+- 单聊：`peerId = senderId`
+- 群聊：`peerId = conversationId`（无 conversationId 时降级为 senderId）
+
+### 2.3 sessionPeerId 的决策树
+
+配置优先级从高到低，**命中第一条即返回**：
+
+```
+sharedMemoryAcrossConversations === true
+  → sessionPeerId = accountId
+  （所有单聊+群聊共享同一记忆，以 accountId 为 session 键）
+
+separateSessionByConversation === false
+  → sessionPeerId = senderId
+  （按用户维度隔离，不区分群/单聊，同一用户在不同群共享 session）
+
+isDirect（单聊）
+  → sessionPeerId = senderId
+  （每个用户独立 session）
+
+groupSessionScope === 'group_sender'（群聊）
+  → sessionPeerId = `${conversationId}:${senderId}`
+  （群内每个用户独立 session）
+
+默认（群聊）
+  → sessionPeerId = conversationId || senderId
+  （整个群共享一个 session）
+```
+
+### 2.4 各配置组合下的完整取值表
+
+| 配置 | 场景 | `peerId` | `sessionPeerId` |
+|------|------|----------|-----------------|
+| `sharedMemoryAcrossConversations: true` | 单聊 | `senderId` | `accountId` |
+| `sharedMemoryAcrossConversations: true` | 群聊 | `conversationId` | `accountId` |
+| `separateSessionByConversation: false` | 单聊 | `senderId` | `senderId` |
+| `separateSessionByConversation: false` | 群聊 | `conversationId` | `senderId` |
+| `groupSessionScope: "group_sender"` | 群聊 | `conversationId` | `${conversationId}:${senderId}` |
+| 默认 | 单聊 | `senderId` | `senderId` |
+| 默认 | 群聊 | `conversationId` | `conversationId` |
+
+> **注意**：`sharedMemoryAcrossConversations: true` 优先级最高，会覆盖其他所有配置。
+
+---
+
+## 三、Agent 路由规则（Bindings）
+
+### 3.1 路由流程
+
+每条钉钉消息到达后，connector 按以下顺序确定目标 Agent：
+
+```
+消息到达
+  ↓
+buildSessionContext()        ← 构建会话上下文（含 peerId / sessionPeerId）
+  ↓
+遍历 cfg.bindings[]          ← 按顺序逐条匹配，使用 peerId 进行匹配
+  ↓ 命中第一条
+matchedAgentId               ← 使用该 agentId
+  ↓ 全部未命中
+cfg.defaultAgent || 'main'   ← 回退到默认 Agent
+```
+
+### 3.2 Binding 匹配字段
+
+每条 binding 的 `match` 字段支持以下维度，**所有指定的维度必须同时满足**（AND 关系）：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `match.channel` | `string?` | 频道名，固定为 `"dingtalk-connector"`，省略则匹配所有频道 |
+| `match.accountId` | `string?` | 钉钉账号 ID（对应 `accounts` 配置中的 key），省略则匹配所有账号 |
+| `match.peer.kind` | `"direct" \| "group"?` | 会话类型，省略则匹配单聊和群聊 |
+| `match.peer.id` | `string?` | Peer 标识，群聊为 `conversationId`，单聊为 `senderId`，`"*"` 表示通配所有 |
+
+### 3.3 匹配逻辑（源码）
+
+```typescript
+// src/core/message-handler.ts
+for (const binding of cfg.bindings) {
+  const match = binding.match;
+  if (match.channel && match.channel !== 'dingtalk-connector') continue;
+  if (match.accountId && match.accountId !== accountId) continue;
+  if (match.peer) {
+    if (match.peer.kind && match.peer.kind !== sessionContext.chatType) continue;
+    // 使用 peerId（真实 peer 标识），不受会话隔离配置影响
+    if (match.peer.id && match.peer.id !== '*' && match.peer.id !== sessionContext.peerId) continue;
+  }
+  matchedAgentId = binding.agentId;
+  break;
+}
+if (!matchedAgentId) {
+  matchedAgentId = cfg.defaultAgent || 'main';
+}
+```
+
+### 3.4 优先级规则
+
+- **顺序优先**：bindings 数组按顺序遍历，**第一条命中的规则生效**，后续规则不再检查
+- **精确规则放前面**：将指定了 `peer.id` 的精确规则放在通配规则（`peer.id: "*"`）之前，避免通配规则提前拦截
+
+### 3.5 典型配置示例
+
+**多群分配不同 Agent**：
+
+```json
+{
+  "bindings": [
+    {
+      "agentId": "main",
+      "match": {
+        "channel": "dingtalk-connector",
+        "accountId": "groupbot",
+        "peer": { "kind": "group", "id": "cid3RKewszsVbXZYCYmbybVNw==" }
+      }
+    },
+    {
+      "agentId": "organizer",
+      "match": {
+        "channel": "dingtalk-connector",
+        "accountId": "groupbot",
+        "peer": { "kind": "group", "id": "cidqO7Ne7e+myoRu67AguW+HQ==" }
+      }
+    },
+    {
+      "agentId": "atlas",
+      "match": {
+        "channel": "dingtalk-connector",
+        "accountId": "groupbot",
+        "peer": { "kind": "group", "id": "cidekzhmRmaKaJ6vnQezRFZWA==" }
+      }
+    }
+  ]
+}
+```
+
+**单聊走一个 Agent，群聊走另一个**：
+
+```json
+{
+  "bindings": [
+    {
+      "agentId": "personal-assistant",
+      "match": { "channel": "dingtalk-connector", "peer": { "kind": "direct" } }
+    },
+    {
+      "agentId": "group-bot",
+      "match": { "channel": "dingtalk-connector", "peer": { "kind": "group" } }
+    }
+  ]
+}
+```
+
+**精确路由 + 通配兜底**：
+
+```json
+{
+  "bindings": [
+    {
+      "agentId": "vip-agent",
+      "match": { "channel": "dingtalk-connector", "peer": { "kind": "group", "id": "cidVIP..." } }
+    },
+    {
+      "agentId": "main",
+      "match": { "channel": "dingtalk-connector", "peer": { "kind": "group", "id": "*" } }
+    }
+  ]
+}
+```
+
+---
+
+## 四、SessionKey 构建规范
+
+### 4.1 SessionKey 格式
+
+SessionKey 由 SDK 的 `core.channel.routing.buildAgentSessionKey()` 生成，格式为：
+
+```
+agent:{agentId}:{channel}:{peerKind}:{sessionPeerId}
+```
+
+示例：
+- `agent:main:dingtalk-connector:direct:manager7195` — 默认单聊，按用户隔离
+- `agent:main:dingtalk-connector:group:cid3RKewszsVbXZYCYmbybVNw==` — 默认群聊，按群隔离
+- `agent:main:dingtalk-connector:direct:bot1` — `sharedMemoryAcrossConversations=true`，所有会话共享（sessionPeerId = accountId = "bot1"）
+- `agent:main:dingtalk-connector:group:bot1` — 同上，群聊也共享
+
+### 4.2 SessionKey 构建代码规范
+
+```typescript
+// src/core/message-handler.ts
+const dmScope = cfg.session?.dmScope || 'per-channel-peer';
+const sessionKey = core.channel.routing.buildAgentSessionKey({
+  agentId: matchedAgentId,
+  channel: 'dingtalk-connector',       // ✅ 固定值，不能写 'dingtalk'
+  accountId: accountId,
+  peer: {
+    kind: sessionContext.chatType,       // 'direct' | 'group'
+    id: sessionContext.sessionPeerId,    // ✅ 使用 sessionPeerId，不是 peerId
+  },
+  dmScope: dmScope,                      // ✅ 必须传递，影响 sessionKey 格式
+});
+```
+
+**禁止**：
+- 用 `sessionContext.peerId` 构建 sessionKey（`peerId` 是路由匹配专用）
+- 手动拼接 sessionKey 字符串（必须通过 SDK 的 `buildAgentSessionKey` 方法）
+- `channel` 写成 `'dingtalk'`（必须是 `'dingtalk-connector'`）
+
+### 4.3 消息队列 Key 规范
+
+消息队列（`sessionQueues`）用于确保同一会话+Agent 的消息串行处理，避免并发冲突。队列 key 格式：
+
+```
+{sessionPeerId}:{agentId}
+```
+
+**必须与 sessionKey 使用相同的 `sessionPeerId`**，确保隔离策略一致：
+
+```typescript
+// src/core/message-handler.ts
+const baseSessionId = sessionContext.sessionPeerId;
+const queueKey = `${baseSessionId}:${matchedAgentId}`;
+```
+
+这样不同 Agent 可以并发处理，同一 Agent 的同一会话串行处理。
+
+### 4.4 InboundContext 中的 From / To 字段
+
+构建 `ctxPayload` 时，`From` 和 `To` 字段规则如下：
+
+| 字段 | 单聊 | 群聊 |
+|------|------|------|
+| `From` | `senderId` | `senderId` |
+| `To` | `senderId` | `conversationId` |
+| `OriginatingTo` | `senderId` | `conversationId` |
+
+```typescript
+const toField = isDirect ? senderId : data.conversationId;
+// From 始终是 senderId，To 单聊用 senderId，群聊用 conversationId
+```
+
+---
+
+## 五、配置参数速查
+
+### 5.1 会话隔离相关配置
+
+| 配置字段 | 类型 | 默认值 | 说明 |
+|---------|------|--------|------|
+| `sharedMemoryAcrossConversations` | `boolean` | `false` | 所有会话（单聊+群聊）共享同一记忆，优先级最高 |
+| `separateSessionByConversation` | `boolean` | `true` | 是否按会话（群/单聊）区分 session；`false` 时按用户维度 |
+| `groupSessionScope` | `"group" \| "group_sender"` | `"group"` | 群聊 session 粒度；`group_sender` 时群内每人独立 |
+| `session.dmScope` | `string` | `"per-channel-peer"` | 传递给 SDK 的 dmScope 参数，影响 sessionKey 格式 |
+
+### 5.2 路由相关配置
+
+| 配置字段 | 类型 | 说明 |
+|---------|------|------|
+| `bindings` | `Binding[]` | Agent 路由规则列表，按顺序匹配 |
+| `defaultAgent` | `string` | 未命中任何 binding 时的默认 Agent，默认为 `"main"` |
+
+---
+
+## 六、开发规范总结
+
+1. **路由匹配用 `peerId`**：`match.peer.id` 与 `sessionContext.peerId` 比较，`peerId` 始终是真实的 `conversationId`（群）或 `senderId`（单聊），不受任何会话隔离配置影响。
+
+2. **session 构建用 `sessionPeerId`**：`sessionKey` 和 `queueKey` 的构建均使用 `sessionContext.sessionPeerId`，受会话隔离配置影响，决定记忆/上下文的共享范围。
+
+3. **两者职责严格分离**：路由（去哪个 Agent）和记忆隔离（共享多大范围的上下文）是两个独立维度，代码中不能用同一个字段同时承担两种职责。
+
+4. **sessionKey 必须通过 SDK 构建**：使用 `core.channel.routing.buildAgentSessionKey()`，不要手动拼接字符串，`channel` 固定为 `'dingtalk-connector'`，`dmScope` 必须传递。
+
+5. **bindings 顺序即优先级**：精确规则（指定 `peer.id`）必须放在通配规则（`peer.id: "*"`）之前。
+
+6. **`sharedMemoryAcrossConversations` 优先级最高**：该配置开启后，`sessionPeerId` 被强制设为 `accountId`，覆盖其他所有会话隔离配置，但 `peerId` 不受影响，路由仍然正常工作。

package/openclaw.plugin.json

@@ -1,16 +1,21 @@
 {
   "id": "dingtalk-connector",
   "name": "DingTalk Channel",
-  "version": "0.8.2",
+  "version": "0.8.3-beta.1",
   "description": "DingTalk (钉钉) messaging channel via Stream mode with AI Card streaming",
   "author": "DingTalk Real Team",
   "main": "index.ts",
-  "channels": ["dingtalk-connector"],
+  "channels": [
+    "dingtalk-connector"
+  ],
   "configSchema": {
     "type": "object",
     "additionalProperties": false,
     "properties": {
-      "enabled": { "type": "boolean", "default": true }
+      "enabled": {
+        "type": "boolean",
+        "default": true
+      }
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dingtalk-real-ai/dingtalk-connector",
-  "version": "0.8.2",
+  "version": "0.8.3-beta.1",
   "description": "DingTalk (钉钉) channel connector — Stream mode with AI Card streaming",
   "main": "index.ts",
   "type": "module",
@@ -51,7 +51,7 @@
     "fluent-ffmpeg": "^2.1.3",
     "form-data": "^4.0.0",
     "mammoth": "^1.8.0",
-    "openclaw": "^2026.3.0",
+    "openclaw": "^2026.3.23-2",
     "pako": "^2.1.0",
     "pdf-parse": "^1.1.1",
     "zod": "^3.22.0"

package/src/core/connection.ts

@@ -15,8 +15,7 @@
 import type { ClawdbotConfig, RuntimeEnv } from "openclaw/plugin-sdk";
 import type { ResolvedDingtalkAccount } from "../types/index.ts";
 import {
-  isMessageProcessed,
-  markMessageProcessed,
+  checkAndMarkDingtalkMessage,
 } from "../utils/utils-legacy.ts";
 import { createLoggerFromConfig } from "../utils/logger.ts";
 
@@ -489,19 +488,16 @@ export async function monitorSingleAccount(
         logger.warn(`⚠️ 警告：消息没有 messageId`);
       }
 
-      // 消息去重
-      if (messageId && isMessageProcessed(messageId)) {
-        processedCount++;  // ✅ 修复：重复消息也要计入 processedCount
-        logger.warn(`⚠️ 检测到重复消息，跳过处理：messageId=${messageId} (${processedCount}/${receivedCount})`);
+      // 协议层去重（headers.messageId）：拦截同一次投递的重复回调
+      // 注意：业务层去重（data.msgId）在 JSON 解析后执行，两层合并在 checkAndMarkDingtalkMessage 中
+      // 此处仅做协议层的快速预检，避免不必要的 JSON 解析
+      if (messageId && checkAndMarkDingtalkMessage(messageId, undefined)) {
+        processedCount++;
+        logger.warn(`⚠️ 检测到重复消息（协议层），跳过处理：messageId=${messageId} (${processedCount}/${receivedCount})`);
         logger.info(`========== 消息处理结束（重复） ==========\n`);
         return;
       }
 
-      if (messageId) {
-        markMessageProcessed(messageId);
-        logger.info(`标记消息为已处理：messageId=${messageId}`);
-      }
-
       // 异步处理消息
       // ✅ 标记消息处理开始，防止长时间处理触发心跳超时
       markMessageProcessingStart();
@@ -544,6 +540,18 @@ export async function monitorSingleAccount(
           `RobotCode: ${data.robotCode || account.config?.clientId || "N/A"}`,
         );
 
+        // ===== 业务层去重：补充 data.msgId，防止钉钉服务端重发穿透 =====
+        // 协议层已标记了 headers.messageId，此处再补充标记 data.msgId。
+        // 钉钉重发时 headers.messageId 是新值，但 data.msgId 不变，
+        // checkAndMarkDingtalkMessage 会命中 data.msgId 并返回 true 拦截重发。
+        const businessMsgId = data.msgId;
+        if (checkAndMarkDingtalkMessage(undefined, businessMsgId)) {
+          processedCount++;
+          logger.warn(`⚠️ 检测到钉钉服务端重发消息，跳过处理：msgId=${businessMsgId} (${processedCount}/${receivedCount})`);
+          logger.info(`========== 消息处理结束（业务层去重） ==========\n`);
+          return;
+        }
+
         // 记录消息内容（简化版，避免过长）
         let contentPreview = "N/A";
         if (data.text?.content) {

package/src/core/message-handler.ts

@@ -18,8 +18,6 @@
 import type { ClawdbotConfig, RuntimeEnv, HistoryEntry } from "openclaw/plugin-sdk";
 import type { ResolvedDingtalkAccount, DingtalkConfig } from "../types/index.ts";
 import { 
-  isMessageProcessed, 
-  markMessageProcessed, 
   buildSessionContext,
   getAccessToken,
   getOapiAccessToken,
@@ -41,6 +39,8 @@ import {
   AUDIO_MARKER_PATTERN
 } from "../services/media/index.ts";
 import { sendProactive, type AICardTarget } from "../services/messaging/index.ts";
+import { createAICardForTarget, streamAICard, type AICardInstance } from "../services/messaging/card.ts";
+import { QUEUE_BUSY_ACK_PHRASES } from "../utils/constants.ts";
 import { createDingtalkReplyDispatcher, normalizeSlashCommand } from "../reply-dispatcher.ts";
 import { getDingtalkRuntime } from "../runtime.ts";
 import { dingtalkHttp } from '../utils/http-client.ts';
@@ -417,8 +417,7 @@ export async function downloadFileToLocal(
     log?.info?.(`文件下载成功: ${fileName}, size=${buffer.length} bytes, path=${localPath}`);
     return localPath;
   } catch (err: any) {
-    console.error(`[ERROR] downloadFileToLocal 异常: ${err.message}`);
-    console.error(`[ERROR] 异常堆栈:\n${err.stack}`);
+    log?.error?.(`downloadFileToLocal 异常: ${err.message}\n${err.stack}`);
     return null;
   }
 }
@@ -532,15 +531,18 @@ interface HandleMessageParams {
   runtime?: RuntimeEnv;
   log?: any;
   cfg: ClawdbotConfig;
+  /** 队列繁忙时预先创建的 AI Card，处理时直接复用而非新建，实现"占位→更新"效果 */
+  preCreatedCard?: AICardInstance;
+  /** 队列繁忙时已在入队阶段提前贴上了思考中表情，内部处理时跳过重复贴表情 */
+  emotionAlreadyAdded?: boolean;
 }
 
 /**
  * 内部消息处理函数（实际执行消息处理逻辑）
  */
 export async function handleDingTalkMessageInternal(params: HandleMessageParams): Promise<void> {
-  const { accountId, config, data, sessionWebhook, runtime, log: inputLog, cfg } = params;
+  const { accountId, config, data, sessionWebhook, runtime, cfg } = params;
 
-  // 如果传入的 log 为空，则使用基于 config 的 logger
   const log = createLoggerFromConfig(config, `DingTalk:${accountId}`);
 
   const content = extractMessageContent(data);
@@ -695,8 +697,10 @@ export async function handleDingTalkMessageInternal(params: HandleMessageParams)
     sharedMemoryAcrossConversations: config.sharedMemoryAcrossConversations,
   });
 
-  // ===== 解析 agentId 和工作空间路径（在 sessionContext 之后，确保 peerId 与会话隔离策略一致）=====
-  // 使用 sessionContext.peerId 进行匹配，与后续 sessionKey 构建保持一致，避免两次匹配结果不一致
+  // ===== 解析 agentId 和工作空间路径（在 sessionContext 之后，确保 chatType 与会话隔离策略一致）=====
+  // 使用 sessionContext.peerId 进行匹配（真实的 conversationId/senderId，与 match.peer.id 语义一致）。
+  // 注意：不能使用 sessionContext.sessionPeerId，它受 sharedMemoryAcrossConversations 等配置影响，
+  // 可能被设为 accountId，导致不同群/用户的消息匹配到同一个 binding，路由错误。
   let matchedAgentId: string | null = null;
   if (cfg.bindings && cfg.bindings.length > 0) {
     for (const binding of cfg.bindings) {
@@ -892,9 +896,12 @@ export async function handleDingTalkMessageInternal(params: HandleMessageParams)
   if (!userContent && imageLocalPaths.length === 0) return;
 
   // ===== 贴处理中表情 =====
-  addEmotionReply(config, data, log).catch(err => {
-    log?.warn?.(`贴表情失败: ${err.message}`);
-  });
+  // 若队列繁忙时已在入队阶段提前贴过表情，此处跳过，避免重复贴
+  if (!params.emotionAlreadyAdded) {
+    addEmotionReply(config, data, log).catch(err => {
+      log?.warn?.(`贴表情失败: ${err.message}`);
+    });
+  }
 
   // ===== 异步模式：立即回执 + 后台执行 + 主动推送结果 =====
   const asyncMode = config.asyncMode === true;
@@ -946,18 +953,18 @@ export async function handleDingTalkMessageInternal(params: HandleMessageParams)
     const matchedBy = matchedAgentId !== (cfg.defaultAgent || 'main') ? 'binding' : 'default';
     
     // ✅ 使用 SDK 标准方法构建 sessionKey，符合 OpenClaw 规范
-    // 格式：agent:{agentId}:{channel}:{peerKind}:{peerId}
-    // ✅ 修复：使用 sessionContext.peerId，确保会话隔离配置生效
+    // 格式：agent:{agentId}:{channel}:{peerKind}:{sessionPeerId}
+    // ✅ 使用 sessionContext.sessionPeerId 构建 sessionKey，确保会话隔离配置生效
     // ✅ 关键修复：传递 dmScope 参数，让 SDK 使用配置文件中的 session.dmScope 设置
     const dmScope = cfg.session?.dmScope || 'per-channel-peer';
-    log?.info?.(`🔍 构建 sessionKey 前的参数: agentId=${matchedAgentId}, channel=dingtalk-connector, accountId=${accountId}, chatType=${sessionContext.chatType}, peerId=${sessionContext.peerId}, dmScope=${dmScope}`);
+    log?.info?.(`🔍 构建 sessionKey 前的参数: agentId=${matchedAgentId}, channel=dingtalk-connector, accountId=${accountId}, chatType=${sessionContext.chatType}, sessionPeerId=${sessionContext.sessionPeerId}, dmScope=${dmScope}`);
     const sessionKey = core.channel.routing.buildAgentSessionKey({
       agentId: matchedAgentId,
       channel: 'dingtalk-connector',  // ✅ 使用 'dingtalk-connector' 而不是 'dingtalk'
       accountId: accountId,
       peer: {
-        kind: sessionContext.chatType,  // ✅ 使用 sessionContext.chatType
-        id: sessionContext.peerId,      // ✅ 使用 sessionContext.peerId（包含会话隔离逻辑）
+        kind: sessionContext.chatType,       // ✅ 使用 sessionContext.chatType
+        id: sessionContext.sessionPeerId,    // ✅ 使用 sessionContext.sessionPeerId（包含会话隔离逻辑）
       },
       dmScope: dmScope,  // ✅ 传递 dmScope 参数，确保生成完整格式的 sessionKey
     });
@@ -980,15 +987,15 @@ export async function handleDingTalkMessageInternal(params: HandleMessageParams)
       SessionKey: sessionKey,  // ✅ 使用手动匹配的 sessionKey
       AccountId: accountId,
       ChatType: sessionContext.chatType,
-      GroupSubject: isDirect ? undefined : data.conversationId,
-      SenderName: senderId,
+      GroupSubject: isDirect ? undefined : data.conversationTitle,
+      SenderName: senderName,
       SenderId: senderId,
-      Provider: "dingtalk" as const,
-      Surface: "dingtalk" as const,
+      Provider: "dingtalk-connector" as const,
+      Surface: "dingtalk-connector" as const,
       MessageSid: data.msgId,
       Timestamp: Date.now(),
       CommandAuthorized: true,
-      OriginatingChannel: "dingtalk" as const,
+      OriginatingChannel: "dingtalk-connector" as const,
       OriginatingTo: toField,  // ✅ 修复：应该使用 toField，而不是 accountId
     });
 
@@ -1004,6 +1011,7 @@ export async function handleDingTalkMessageInternal(params: HandleMessageParams)
       messageCreateTimeMs: Date.now(),
       sessionWebhook: data.sessionWebhook,
       asyncMode,
+      preCreatedCard: params.preCreatedCard,
     });
 
     // 使用 SDK 的 dispatchReplyFromConfig
@@ -1180,15 +1188,17 @@ export async function handleDingTalkMessage(params: HandleMessageParams): Promis
     sharedMemoryAcrossConversations: config.sharedMemoryAcrossConversations,
   });
 
-  const baseSessionId = queueSessionContext.peerId;
+  const baseSessionId = queueSessionContext.sessionPeerId;
 
   if (!baseSessionId) {
     log?.warn?.('无法构建会话标识，跳过队列管理');
     return handleDingTalkMessageInternal(params);
   }
 
-  // 解析 agentId：使用 sessionContext.peerId 和 sessionContext.chatType 进行匹配
-  // 与 handleDingTalkMessageInternal 中的匹配逻辑保持一致
+  // 解析 agentId：使用 queueSessionContext.peerId（真实 peer 标识）进行匹配
+  // 与 handleDingTalkMessageInternal 中的匹配逻辑保持一致。
+  // 必须使用 peerId 而非 sessionPeerId，原因：sharedMemoryAcrossConversations=true 时
+  // sessionPeerId 被设为 accountId，导致不同群的消息匹配到同一个 binding。
   let matchedAgentId: string | null = null;
   if (cfg.bindings && cfg.bindings.length > 0) {
     for (const binding of cfg.bindings) {
@@ -1218,14 +1228,46 @@ export async function handleDingTalkMessage(params: HandleMessageParams): Promis
     // 更新会话活跃时间
     sessionLastActivity.set(queueKey, Date.now());
 
+    // 检测队列是否繁忙（入队前检查，此时 previousTask 尚未被当前消息覆盖）
+    const isQueueBusy = sessionQueues.has(queueKey);
+
     // 获取该会话+agent的上一个处理任务
     const previousTask = sessionQueues.get(queueKey) || Promise.resolve();
 
+    // 队列繁忙时：立即创建一个 AI Card 显示排队 ACK 文案，并将 Card 实例传入处理任务
+    // 处理完成后 reply-dispatcher 会复用此 Card 更新为最终结果，用户看到的是同一条消息的内容变化
+    let preCreatedCard: AICardInstance | undefined;
+    if (isQueueBusy) {
+      const ackPhrases = QUEUE_BUSY_ACK_PHRASES;
+      const ackText = ackPhrases[Math.floor(Math.random() * ackPhrases.length)];
+      const cardTarget: AICardTarget = isDirect
+        ? { type: 'user', userId: senderId }
+        : { type: 'group', openConversationId: data.conversationId };
+
+      try {
+        const card = await createAICardForTarget(config, cardTarget, log);
+        if (card) {
+          // 用 streamAICard 把 ACK 文案写入 Card（INPUTING 状态，表示正在处理中）
+          await streamAICard(card, ackText, false, config, log);
+          preCreatedCard = card;
+          log?.info?.(`[队列] 队列繁忙，已创建排队 ACK Card，cardInstanceId=${card.cardInstanceId}`);
+        } else {
+          log?.warn?.(`[队列] 创建排队 ACK Card 失败（返回 null），跳过 ACK`);
+        }
+        // 在发送 ACK 的同时立即贴上思考中表情，让用户知道消息已被接收
+        addEmotionReply(config, data, log).catch(err => {
+          log?.warn?.(`[队列] 贴排队表情失败: ${err.message}`);
+        });
+      } catch (ackErr: any) {
+        log?.warn?.(`[队列] 创建排队 ACK Card 异常: ${ackErr?.message || ackErr}`);
+      }
+    }
+
     // 创建当前消息的处理任务
     const currentTask = previousTask
       .then(async () => {
         log?.info?.(`[队列] 开始处理消息，queueKey=${queueKey}`);
-        await handleDingTalkMessageInternal(params);
+        await handleDingTalkMessageInternal({ ...params, preCreatedCard, emotionAlreadyAdded: isQueueBusy });
         log?.info?.(`[队列] 消息处理完成，queueKey=${queueKey}`);
       })
       .catch((err: any) => {
@@ -1243,14 +1285,12 @@ export async function handleDingTalkMessage(params: HandleMessageParams): Promis
     // 更新队列
     sessionQueues.set(queueKey, currentTask);
 
-    // 等待当前任务完成
-    await currentTask;
-    console.log(`[DEBUG] 任务执行完成`);
+    // 不等待任务完成，立即返回，不阻塞 WebSocket 消息接收
+    // 消息处理在后台异步执行，队列保证同一会话+agent的消息串行处理
   } catch (err: any) {
-    console.error(`[DEBUG] 队列管理异常: ${err.message}`);
-    console.error(`[DEBUG] 队列管理异常堆栈: ${err.stack}`);
-    // 如果队列管理失败，直接调用内部处理函数
-    return handleDingTalkMessageInternal(params);
+    log?.error?.(`[队列] 队列管理异常，直接处理: ${err.message}`);
+    // 如果队列管理失败，直接调用内部处理函数（不阻塞）
+    void handleDingTalkMessageInternal(params);
   }
 }
 

package/src/reply-dispatcher.ts

@@ -1,13 +1,21 @@
-import type {
-  ClawdbotConfig,
-  RuntimeEnv,
-  ReplyPayload,
-} from "openclaw/plugin-sdk";
-import {
+// openclaw 2026.3.23+ 将 plugin-sdk 拆分为子模块，旧版本仍从主入口导出。
+// 使用动态 import 兼容新旧两种版本：优先尝试新版子路径，失败则回退到旧版主入口。
+import type { ClawdbotConfig, RuntimeEnv } from "openclaw/plugin-sdk/runtime";
+import type { ReplyPayload } from "openclaw/plugin-sdk/reply-payload";
+
+type ChannelRuntimeModule = {
+  createReplyPrefixOptions: typeof import("openclaw/plugin-sdk/channel-runtime").createReplyPrefixOptions;
+  createTypingCallbacks: typeof import("openclaw/plugin-sdk/channel-runtime").createTypingCallbacks;
+  logTypingFailure: typeof import("openclaw/plugin-sdk/channel-runtime").logTypingFailure;
+};
+
+const {
   createReplyPrefixOptions,
   createTypingCallbacks,
   logTypingFailure,
-} from "openclaw/plugin-sdk";
+}: ChannelRuntimeModule = await import("openclaw/plugin-sdk/channel-runtime").catch(
+  () => import("openclaw/plugin-sdk") as Promise<ChannelRuntimeModule>
+);
 import { resolveDingtalkAccount } from "./config/accounts.ts";
 import { getDingtalkRuntime } from "./runtime.ts";
 import type { DingtalkConfig } from "./types/index.ts";
@@ -56,6 +64,8 @@ export type CreateDingtalkReplyDispatcherParams = {
   messageCreateTimeMs?: number;
   sessionWebhook: string;
   asyncMode?: boolean;
+  /** 队列繁忙时预先创建的 AI Card，startStreaming 时直接复用而非新建 */
+  preCreatedCard?: AICardInstance;
 };
 
 export function createDingtalkReplyDispatcher(params: CreateDingtalkReplyDispatcherParams) {
@@ -69,6 +79,7 @@ export function createDingtalkReplyDispatcher(params: CreateDingtalkReplyDispatc
     accountId,
     sessionWebhook,
     asyncMode = false,
+    preCreatedCard,
   } = params;
 
   const account = resolveDingtalkAccount({ cfg, accountId });
@@ -114,7 +125,7 @@ export function createDingtalkReplyDispatcher(params: CreateDingtalkReplyDispatc
   
   // ✅ 节流控制：避免频繁调用钉钉 API 导致 QPS 限流
   let lastUpdateTime = 0;
-  const updateInterval = 1000; // 最小更新间隔 1000ms（钉钉 QPS 限制：40 次/秒，安全起见设为 1 秒）
+  const updateInterval = 500; // 最小更新间隔 500ms（钉钉 QPS 限制：40 次/秒，保守起见设为 0.5 秒）
 
   // ✅ 错误兜底：防止重复发送错误消息
   const deliveredErrorTypes = new Set<string>();
@@ -227,6 +238,15 @@ export function createDingtalkReplyDispatcher(params: CreateDingtalkReplyDispatc
       log.info(`[DingTalk][startStreaming] AI Card 正在创建中，跳过`);
       return;
     }
+
+    // 若队列繁忙时已预先创建了 Card（显示排队 ACK 文案），直接复用，无需新建
+    // 这样用户看到的是同一条消息从 ACK 文案更新为最终结果，而不是多出一条消息
+    if (preCreatedCard) {
+      log.info(`[DingTalk][startStreaming] 复用预创建 AI Card，cardInstanceId=${preCreatedCard.cardInstanceId}`);
+      currentCardTarget = preCreatedCard;
+      accumulatedText = "";
+      return;
+    }
     
     isCreatingCard = true;
     log.info(`[DingTalk][startStreaming] 开始创建 AI Card...`);
@@ -385,11 +405,12 @@ export function createDingtalkReplyDispatcher(params: CreateDingtalkReplyDispatc
     core.channel.reply.createReplyDispatcherWithTyping({
       ...prefixOptions,
       humanDelay: core.channel.reply.resolveHumanDelayConfig(cfg, agentId),
-      onReplyStart: async () => {
+      onReplyStart: () => {
         deliveredFinalTexts.clear();
         log.info(`[DingTalk][onReplyStart] 开始回复，流式 enabled=${streamingEnabled}`);
         if (streamingEnabled) {
-          await startStreaming();
+          // fire-and-forget：不阻塞 onReplyStart 返回，onPartialReply 会等待 Card 创建完成
+          void startStreaming();
         }
         typingCallbacks.onActive?.();
       },
@@ -666,7 +687,7 @@ export function createDingtalkReplyDispatcher(params: CreateDingtalkReplyDispatc
         }
       },
       }),
-      disableBlockStreaming: true,  // ✅ 强制使用 onPartialReply 而不是 block
+      disableBlockStreaming: true,  // block 内容合并到 final，流式更新通过 onPartialReply 实现
     },
     markDispatchIdle,
     getAsyncModeResponse: () => asyncModeFullResponse,

package/src/runtime.ts

@@ -1,7 +1,32 @@
-import { createPluginRuntimeStore } from "openclaw/plugin-sdk/compat";
 import type { PluginRuntime } from "openclaw/plugin-sdk";
 
+/**
+ * 自实现的运行时存储工厂，避免依赖特定版本 openclaw 是否导出 createPluginRuntimeStore。
+ * 旧版 openclaw 没有导出该函数，直接 import 会导致 TypeError，因此在此处内联实现。
+ */
+function createRuntimeStore<T>(errorMessage: string) {
+  let runtimeValue: T | null = null;
+
+  return {
+    setRuntime: (next: T): void => {
+      runtimeValue = next;
+    },
+    clearRuntime: (): void => {
+      runtimeValue = null;
+    },
+    tryGetRuntime: (): T | null => {
+      return runtimeValue;
+    },
+    getRuntime: (): T => {
+      if (runtimeValue === null) {
+        throw new Error(errorMessage);
+      }
+      return runtimeValue;
+    },
+  };
+}
+
 const { setRuntime: setDingtalkRuntime, getRuntime: getDingtalkRuntime } =
-  createPluginRuntimeStore<PluginRuntime>("DingTalk runtime not initialized");
+  createRuntimeStore<PluginRuntime>("DingTalk runtime not initialized");
 
 export { getDingtalkRuntime, setDingtalkRuntime };

package/src/services/messaging.ts

@@ -6,6 +6,7 @@
 import type { DingtalkConfig } from "../types/index.ts";
 import { DINGTALK_API, getAccessToken, getOapiAccessToken } from "../utils/index.ts";
 import { dingtalkHttp, dingtalkOapiHttp } from "../utils/http-client.ts";
+import { MEDIA_MSG_TYPES } from "../utils/constants.ts";
 import { createLoggerFromConfig } from "../utils/logger.ts";
 import {
   processLocalImages,
@@ -863,8 +864,11 @@ async function sendProactiveInternal(
     log: externalLog,
   } = options;
 
-  // 如果启用 AI Card
-  if (useAICard) {
+  // 图片、音频、视频、文件等媒体类型消息不支持 AI Card，必须走普通消息 API
+  const isMediaMessage = MEDIA_MSG_TYPES.has(msgType as any);
+
+  // 如果启用 AI Card（媒体消息强制跳过）
+  if (useAICard && !isMediaMessage) {
     try {
       const card = await createAICardForTarget(config, target, externalLog);
       if (card) {

package/src/utils/constants.ts

@@ -7,3 +7,24 @@ export const DEFAULT_ACCOUNT_ID = '__default__';
 
 /** 新会话触发命令 */
 export const NEW_SESSION_COMMANDS = ['/new', '/reset', '/clear', '新会话', '重新开始', '清空对话'];
+
+/**
+ * 媒体类消息类型集合。
+ *
+ * 这些消息类型需要通过钉钉原生消息 API 发送，不支持 AI Card 形式，
+ * 在 sendProactiveInternal 中会强制跳过 AI Card 路径。
+ */
+export const MEDIA_MSG_TYPES = new Set(['image', 'voice', 'file', 'video'] as const);
+
+/**
+ * 队列繁忙时的即时 ACK 回复短语。
+ *
+ * 当消息入队时检测到上一条消息仍在处理中，立即从此列表中随机选取一条回复，
+ * 告知用户消息已收到并排队，避免用户以为 Bot 没有响应。
+ * 参考 delivery.rs 中 DINGTALK_ACK_PHRASES_BUSY_ZH_CN 的设计。
+ */
+export const QUEUE_BUSY_ACK_PHRASES = [
+  '上一条还没结束，这条我已经记下，稍后按顺序继续处理。',
+  '当前还在忙，你的新消息已经排队，上一条完成后我马上继续。',
+  '我这边还在处理上一条，这条已加入队列，完成后继续处理。',
+] as const;

package/src/utils/session.ts

@@ -10,7 +10,19 @@ export interface SessionContext {
   channel: 'dingtalk-connector';
   accountId: string;
   chatType: 'direct' | 'group';
+  /**
+   * 真实的 peer 标识，不受任何会话隔离配置影响。
+   * 群聊为 conversationId，单聊为 senderId。
+   * 与配置中 match.peer.id 语义一致，专用于 bindings 路由匹配。
+   */
   peerId: string;
+  /**
+   * 用于 session/memory 隔离的 peer 标识（session 键的一部分）。
+   * 受 sharedMemoryAcrossConversations、separateSessionByConversation、groupSessionScope 等配置影响，
+   * 可能与 peerId 不同（如 sharedMemoryAcrossConversations=true 时被设为 accountId）。
+   * 注意：不要用此字段做 binding 路由匹配，应使用 peerId。
+   */
+  sessionPeerId: string;
   conversationId?: string;
   senderName?: string;
   groupSubject?: string;
@@ -48,13 +60,19 @@ export function buildSessionContext(params: {
   } = params;
   const isDirect = conversationType === '1';
 
+  // peerId：真实的 peer 标识，不受任何会话隔离配置影响，专用于 bindings 路由匹配
+  // 群聊为 conversationId，单聊为 senderId，与配置中 match.peer.id 语义一致
+  const peerId = isDirect ? senderId : (conversationId || senderId);
+
   // sharedMemoryAcrossConversations=true 时，所有会话共享记忆
+  // sessionPeerId 被设为 accountId 以合并记忆，peerId 仍保留真实 peer，供路由匹配使用
   if (sharedMemoryAcrossConversations === true) {
     return {
       channel: 'dingtalk-connector',
       accountId,
       chatType: isDirect ? 'direct' : 'group',
-      peerId: accountId, // 使用 accountId 作为 peerId，实现跨会话记忆共享
+      peerId,
+      sessionPeerId: accountId, // 使用 accountId 作为 sessionPeerId，实现跨会话记忆共享
       conversationId: isDirect ? undefined : conversationId,
       senderName,
       groupSubject: isDirect ? undefined : groupSubject,
@@ -67,19 +85,21 @@ export function buildSessionContext(params: {
       channel: 'dingtalk-connector',
       accountId,
       chatType: isDirect ? 'direct' : 'group',
-      peerId: senderId, // 只用 senderId，不区分会话
+      peerId,
+      sessionPeerId: senderId, // 只用 senderId，不区分会话
       senderName,
     };
   }
 
   // 以下是 separateSessionByConversation=true（默认）的逻辑
   if (isDirect) {
-    // 单聊：peerId 为发送者 ID，由 OpenClaw Gateway 根据 dmScope 配置处理
+    // 单聊：sessionPeerId 为发送者 ID，由 OpenClaw Gateway 根据 dmScope 配置处理
     return {
       channel: 'dingtalk-connector',
       accountId,
       chatType: 'direct',
-      peerId: senderId,
+      peerId,
+      sessionPeerId: senderId,
       senderName,
     };
   }
@@ -91,7 +111,8 @@ export function buildSessionContext(params: {
       channel: 'dingtalk-connector',
       accountId,
       chatType: 'group',
-      peerId: `${conversationId}:${senderId}`,
+      peerId,
+      sessionPeerId: `${conversationId}:${senderId}`,
       conversationId,
       senderName,
       groupSubject,
@@ -103,7 +124,8 @@ export function buildSessionContext(params: {
     channel: 'dingtalk-connector',
     accountId,
     chatType: 'group',
-    peerId: conversationId || senderId,
+    peerId,
+    sessionPeerId: conversationId || senderId,
     conversationId,
     senderName,
     groupSubject,

package/src/utils/utils-legacy.ts

@@ -245,6 +245,41 @@ export function markMessageProcessed(messageId: string): void {
   }
 }
 
+/**
+ * 对钉钉 Stream 消息做双层去重检查，并在首次处理时标记。
+ *
+ * 背景：钉钉 Stream 模式存在两套消息 ID：
+ *   - headers.messageId：WebSocket 协议层的投递 ID，每次重发都会生成新值
+ *   - data.msgId：业务层的用户消息 ID，重发时保持不变
+ *
+ * 因此必须同时检查两个 ID，才能可靠地拦截钉钉服务端的重发消息：
+ *   1. 协议层去重（headers.messageId）：拦截同一次投递的重复回调
+ *   2. 业务层去重（data.msgId）：拦截 ~60 秒后服务端因未收到业务回复而触发的重发
+ *
+ * @param protocolMessageId - res.headers.messageId（WebSocket 协议层投递 ID）
+ * @param businessMsgId     - data.msgId（钉钉业务层消息 ID，来自 JSON.parse(res.data).msgId）
+ * @returns true 表示消息已处理过（应跳过），false 表示首次处理（已标记为已处理）
+ */
+export function checkAndMarkDingtalkMessage(
+  protocolMessageId: string | undefined,
+  businessMsgId: string | undefined,
+): boolean {
+  // 先完整检查两个 ID，再决定是否标记
+  // 不能提前 return，否则命中去重的那条路径会漏掉对另一个 ID 的标记
+  const isProtocolDuplicate = protocolMessageId ? isMessageProcessed(protocolMessageId) : false;
+  const isBusinessDuplicate = businessMsgId ? isMessageProcessed(businessMsgId) : false;
+
+  if (isProtocolDuplicate || isBusinessDuplicate) {
+    return true;
+  }
+
+  // 首次处理：同时标记两个 ID，确保后续任意一个 ID 都能命中去重
+  if (protocolMessageId) markMessageProcessed(protocolMessageId);
+  if (businessMsgId) markMessageProcessed(businessMsgId);
+
+  return false;
+}
+
 // ============ 配置工具 ============
 
 /**