@dingtalk-real-ai/dingtalk-connector 0.8.1 → 0.8.3

package/CHANGELOG.md

@@ -5,6 +5,48 @@ 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] - 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
+- 🐛 **多账号重复启动问题** - 修复 `enabled: false` 的账号仍会建立 WebSocket 连接的问题，禁用账号现在正确保持 pending 状态直到 Gateway 停止  
+  **Multi-account duplicate startup** - Fixed accounts with `enabled: false` still establishing WebSocket connections; disabled accounts now correctly remain in a pending state until the Gateway stops
+
+- 🐛 **相同 clientId 账号去重** - 修复多个账号配置相同 `clientId` 时建立重复连接的问题，通过静态配置分析确保同一 `clientId` 只有列表中第一个启用账号建立连接  
+  **Duplicate clientId deduplication** - Fixed duplicate connections when multiple accounts share the same `clientId`; static config analysis now ensures only the first enabled account per `clientId` establishes a connection
+
+
+### 改进 / Improvements
+- ✅ **Onboarding 配置向导优化** - 改进钉钉连接器配置引导逻辑，调整凭据输入顺序（先 Client ID 后 Client Secret），优化引导文案  
+  **Onboarding wizard improvement** - Improved DingTalk connector onboarding flow, adjusted credential input order (Client ID first, then Client Secret), and refined guidance text
+
+- ✅ **会话 Key 遵循 OpenClaw 规范** - 会话上下文按 OpenClaw 标准规则构建，通过 `channel`、`accountId`、`chatType`、`peerId` 唯一标识会话，支持 `sharedMemoryAcrossConversations` 跨会话记忆共享  
+  **Session key follows OpenClaw convention** - Session context now built per OpenClaw standard rules, uniquely identified via `channel`, `accountId`, `chatType`, `peerId`; supports `sharedMemoryAcrossConversations` for cross-conversation memory sharing
+
+- ✅ **消息处理逻辑优化** - 重构消息处理流程，提升消息响应速度和处理可靠性，确保消息按序正确处理  
+  **Message processing logic optimization** - Refactored message processing flow to improve response speed and reliability, ensuring messages are processed correctly in order
+
 ## [0.8.1] - 2026-03-20
 
 ### 修复 / 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.1",
+  "version": "0.8.3",
   "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.1",
+  "version": "0.8.3",
   "description": "DingTalk (钉钉) channel connector — Stream mode with AI Card streaming",
   "main": "index.ts",
   "type": "module",

package/src/channel.ts

@@ -495,64 +495,64 @@ export const dingtalkPlugin: ChannelPlugin<ResolvedDingtalkAccount> = {
   gateway: {
     startAccount: async (ctx) => {
       const account = resolveDingtalkAccount({ cfg: ctx.cfg, accountId: ctx.accountId });
-      const logger = createLogger(account.config?.debug ?? false, 'DingTalk:Gateway');
+
+      // 检查账号是否启用和配置
+      if (!account.enabled) {
+        ctx.log?.info?.(`dingtalk-connector[${ctx.accountId}] is disabled, skipping startup`);
+        // 返回一个永不 resolve 的 Promise，保持 pending 状态直到 abort
+        return new Promise<void>((resolve) => {
+          if (ctx.abortSignal?.aborted) {
+            resolve();
+            return;
+          }
+          ctx.abortSignal?.addEventListener('abort', () => resolve(), { once: true });
+        });
+      }
       
-      logger.info(`startAccount 被调用：accountId=${ctx.accountId}`);
-      try {
-        logger.info('='.repeat(60));
-        logger.info('开始加载 provider 模块...');
-        const monitorModule = await import("./core/provider.ts");
-        logger.info(`monitor module 加载完成`);
-        logger.info(`monitor module keys: ${Object.keys(monitorModule).join(', ')}`);
-        logger.info(`monitorModule 类型: ${typeof monitorModule}`);
-        logger.info(`monitorModule 是否为 null: ${monitorModule === null}`);
-        logger.info(`monitorModule 是否为 undefined: ${monitorModule === undefined}`);
-        
-        // 使用 Object.getOwnPropertyDescriptor 检查属性
-        const descriptor = Object.getOwnPropertyDescriptor(monitorModule, 'monitorSingleAccount');
-        logger.info(`monitorSingleAccount descriptor: ${JSON.stringify(descriptor)}`);
-        
-        // 尝试安全地访问 monitorSingleAccount
-        let monitorSingleAccountType = 'unknown';
-        try {
-          monitorSingleAccountType = typeof monitorModule.monitorSingleAccount;
-        } catch (e) {
-          monitorSingleAccountType = `error: ${e.message}`;
-        }
-        logger.info(`monitorModule.monitorSingleAccount: ${monitorSingleAccountType}`);
-        
-        logger.info(`monitorModule.monitorDingtalkProvider: ${typeof monitorModule.monitorDingtalkProvider}`);
-        
-        // 使用直接属性访问而不是解构
-        const monitorDingtalkProvider = monitorModule.monitorDingtalkProvider;
-        logger.info(`解构 monitorDingtalkProvider 完成: ${typeof monitorDingtalkProvider}`);
-        
-        if (!monitorDingtalkProvider) {
-          ctx.log?.error?.(`monitorDingtalkProvider 未找到！可用导出: ${Object.keys(monitorModule).join(', ')}`);
-          throw new Error("monitorDingtalkProvider not found in monitor module");
+      if (!account.configured) {
+        throw new Error(`DingTalk account "${ctx.accountId}" is not properly configured`);
+      }
+      
+      // 去重检查：如果列表中排在当前账号之前的账号已使用相同 clientId，则跳过当前账号
+      // 使用静态配置分析（而非运行时状态），避免并发竞态条件
+      // 规则：同一 clientId 只有列表中第一个启用且已配置的账号才会建立连接
+      if (account.clientId) {
+        const clientId = String(account.clientId);
+        const allAccountIds = listDingtalkAccountIds(ctx.cfg);
+        const currentIndex = allAccountIds.indexOf(ctx.accountId);
+        const priorAccountWithSameClientId = allAccountIds.slice(0, currentIndex).find((otherId) => {
+          const other = resolveDingtalkAccount({ cfg: ctx.cfg, accountId: otherId });
+          return other.enabled && other.configured && other.clientId && String(other.clientId) === clientId;
+        });
+        if (priorAccountWithSameClientId) {
+          ctx.log?.info?.(
+            `dingtalk-connector[${ctx.accountId}] skipped: clientId "${clientId.substring(0, 8)}..." is already used by account "${priorAccountWithSameClientId}"`
+          );
+          return new Promise<void>((resolve) => {
+            if (ctx.abortSignal?.aborted) {
+              resolve();
+              return;
+            }
+            ctx.abortSignal?.addEventListener('abort', () => resolve(), { once: true });
+          });
         }
-        logger.info(`monitorDingtalkProvider 找到`);
-        
-        logger.info(`account 解析完成: ${account.accountId}, enabled=${account.enabled}, configured=${account.configured}`);
-        
-        ctx.setStatus({ accountId: ctx.accountId, port: null });
-        ctx.log?.info(
-          `starting dingtalk-connector[${ctx.accountId}] (mode: stream)`,
-        );
-        logger.info(`准备调用 monitorDingtalkProvider`);
-        
-        const result = await monitorDingtalkProvider({
+      }
+
+      ctx.setStatus({ accountId: ctx.accountId, port: null });
+      ctx.log?.info(
+        `starting dingtalk-connector[${ctx.accountId}] (mode: stream)`,
+      );
+      try {
+        return await monitorDingtalkProvider({
           config: ctx.cfg,
           runtime: ctx.runtime,
           abortSignal: ctx.abortSignal,
           accountId: ctx.accountId,
         });
-        logger.info(`monitorDingtalkProvider 调用完成`);
-        return result;
-      } catch (error) {
-        ctx.log?.error?.(`startAccount 发生错误: ${error.message}`);
-        ctx.log?.error?.(`错误堆栈: ${error.stack}`);
-        throw error;
+      } catch (err: any) {
+        // 打印真实错误到 stderr，绕过框架 log 系统（框架的 runtime.log 可能未初始化）
+        ctx.log?.error(`[dingtalk-connector][${ctx.accountId}] startAccount error:`, err?.message ?? err, err?.stack);
+        throw err;
       }
     },
   },

package/src/config/accounts.ts

@@ -222,9 +222,21 @@ export function resolveDingtalkAccount(params: {
 
 /**
  * List all enabled and configured accounts.
+ * Deduplicates by clientId to avoid creating multiple connections with the same credentials.
  */
 export function listEnabledDingtalkAccounts(cfg: ClawdbotConfig): ResolvedDingtalkAccount[] {
-  return listDingtalkAccountIds(cfg)
+  const accounts = listDingtalkAccountIds(cfg)
     .map((accountId) => resolveDingtalkAccount({ cfg, accountId }))
     .filter((account) => account.enabled && account.configured);
+  
+  // Deduplicate by clientId to avoid multiple connections with same credentials
+  const seen = new Set<string>();
+  return accounts.filter((account) => {
+    if (!account.clientId) return true;
+    if (seen.has(account.clientId)) {
+      return false;
+    }
+    seen.add(account.clientId);
+    return true;
+  });
 }