@jeik/dingtalk-connector 0.8.21

package/docs/DINGTALK_MANUAL_SETUP.md

@@ -0,0 +1,50 @@
+# 钉钉手动创建与手动配置流程
+
+当一键扫码授权不可用、扫码失败，或你希望手动控制配置时，可使用本流程。
+
+## 1) 手动创建钉钉机器人
+
+### 1.1 创建应用
+
+1. 访问 [钉钉开放平台](https://open-dev.dingtalk.com/)
+2. 点击 **"应用开发"**
+
+![创建应用](images/image-1.png)
+
+### 1.2 添加机器人能力
+
+1. 在应用详情页，点击一键创建 OpenClaw 机器人应用
+
+![创建OpenClaw机器人应用](images/image-2.png)
+
+### 1.3 获取凭证
+
+1. 完成创建并获取 **"凭证与基础信息"**
+2. 复制你的 **AppKey**（Client ID）
+3. 复制你的 **AppSecret**（Client Secret）
+
+![完成创建](images/image-3.png)
+![获取凭证](images/image-4.png)
+
+> ⚠️ **重要**：`clientId` 和 `clientSecret` 是机器人的唯一凭证，请合理保存。
+
+## 2) 手动配置 OpenClaw
+
+编辑配置文件：
+
+- macOS / Linux：`~/.openclaw/openclaw.json`
+- Windows：`C:\Users\<你的用户名>\.openclaw\openclaw.json`
+
+```json
+{
+  "channels": {
+    "dingtalk-connector": {
+      "enabled": true,
+      "clientId": "dingxxxxxxxxx",
+      "clientSecret": "your_app_secret"
+    }
+  }
+}
+```
+
+> 💡 **提示**：如果文件已有内容，在 `channels` 节点下添加 `dingtalk-connector` 部分即可。

package/docs/MULTI_AGENT_SETUP.md

@@ -0,0 +1,306 @@
+# Connector 插件配置多 Agent — 辅助文档 2.0
+
+> [dingtalk-connector GitHub 官网](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector)
+
+## 一、实操：从零配置多 Agent
+
+### 前提条件
+
+- OpenClaw 已安装且正常运行（`openclaw -v` ≥ 2026.4.9）
+- 已有一个可用的钉钉机器人（作为第一个 Agent）
+
+### Step 1：在钉钉开放平台创建新机器人
+
+[手动创建机器人](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/blob/main/docs/DINGTALK_MANUAL_SETUP.md)
+
+### Step 2：创建 Agent 配置目录
+
+每个 Agent 需要一个独立的配置目录，里面放 `agent.md` 文件定义 Agent 的人格和能力。
+
+```bash
+# 创建 Agent 目录
+mkdir -p ~/.openclaw/agents/dev-agent/agent
+
+# 写入 systemPrompt（这是 Agent 的"人格定义"）
+cat > ~/.openclaw/agents/dev-agent/agent/agent.md << 'EOF'
+你是一个开发助手，擅长代码审查、技术方案设计和 Bug 排查。
+回复时请在第一行加上标识：🔵 [Dev Agent]
+EOF
+```
+
+> 💡 **建议**：给每个 Agent 的 systemPrompt 加上明显不同的标识（如 emoji + 名称），方便测试时一眼区分回复来自哪个 Agent。
+
+### Step 3：编辑 openclaw.json
+
+编辑 `~/.openclaw/openclaw.json`，需要修改三个部分：
+
+#### 3.1 注册 Agent（agents.list）
+
+```jsonc
+"agents": {
+  "list": [
+    { "id": "main" },
+    {
+      "id": "dev-agent",
+      "name": "开发助手",
+      "agentDir": "/Users/你的用户名/.openclaw/agents/dev-agent/agent"
+    }
+  ]
+}
+```
+
+#### 3.2 注册机器人账号（channels.dingtalk-connector.accounts）
+
+将**所有机器人**都放到 `accounts` 里，每个 key 是你自定义的账号名：
+
+```jsonc
+"channels": {
+  "dingtalk-connector": {
+    "enabled": true,
+    "accounts": {
+      "main-bot": {
+        "enabled": true,
+        "name": "主机器人",
+        "clientId": "原有机器人的AppKey",
+        "clientSecret": "原有机器人的AppSecret"
+      },
+      "dev-bot": {
+        "enabled": true,
+        "name": "开发助手机器人",
+        "clientId": "新机器人的AppKey（Step 1 获取）",
+        "clientSecret": "新机器人的AppSecret（Step 1 获取）"
+      }
+    }
+  }
+}
+```
+
+> **关于顶层 `clientId` / `clientSecret` 是否保留：**
+>
+> - **单机器人场景（未配置 `accounts`）**：**必须保留**。框架直接读取顶层凭证启动唯一的机器人，这是最简配置。
+> - **多机器人场景（已配置 `accounts`）**：**建议删除**。一旦配置了 `accounts`，框架**只会启动 `accounts` 里列出的机器人**，顶层凭证不再作为独立账号启动。如果某个 account 省略了 `clientId`/`clientSecret`，会从顶层继承（fallback），但这容易造成误解（"为什么删了 account 里的凭证还能连上？"）。**推荐做法**：每个 account 都写明自己的凭证，删除顶层的 `clientId`/`clientSecret`，避免歧义。
+>
+> ⚠️ **重要**：一旦配置了 `accounts`，原来顶层的 `clientId`/`clientSecret` 不再自动作为独立账号启动，必须也放进 `accounts` 里才会被启动。
+
+#### 3.3 绑定机器人到 Agent（bindings）
+
+通过 `accountId` 将每个机器人绑定到对应的 Agent：
+
+```jsonc
+"bindings": [
+  {
+    "agentId": "main",
+    "match": {
+      "channel": "dingtalk-connector",
+      "accountId": "main-bot"
+    }
+  },
+  {
+    "agentId": "dev-agent",
+    "match": {
+      "channel": "dingtalk-connector",
+      "accountId": "dev-bot"
+    }
+  }
+]
+```
+
+**效果**：`main-bot` 收到的所有消息（无论群聊还是单聊）都路由到 `main` Agent，`dev-bot` 收到的所有消息都路由到 `dev-agent`。
+
+### Step 4：重启 OpenClaw
+
+```bash
+openclaw gateway restart
+```
+
+### Step 5：验证
+
+查看启动日志，确认两个机器人都成功连接：
+
+```bash
+tail -f ~/.openclaw/logs/gateway.log | grep dingtalk
+```
+
+应该看到：
+
+```plaintext
+[dingtalk-connector] starting dingtalk-connector[dev-bot] (mode: stream, ...)
+[dingtalk-connector] starting dingtalk-connector[main-bot] (mode: stream, ...)
+```
+
+如果看到 `auto-restart attempt` 或 `Authentication failed (401)`，说明 clientId/clientSecret 不正确或机器人未开启 Stream 模式，请回到 Step 1 检查。
+
+### Step 6：测试
+
+将两个机器人都拉入同一个群聊，分别 @它们发消息：
+
+| 操作 | 预期结果 |
+| --- | --- |
+| @主机器人 "你是谁" | 回复来自 main Agent |
+| @开发助手机器人 "你是谁" | 回复带 🔵 [Dev Agent] 标识 |
+
+---
+
+## 二、完整配置示例
+
+以下是一个包含 3 个机器人 × 3 个 Agent 的完整配置：
+
+```jsonc
+{
+  "agents": {
+    "defaults": {
+      "model": { "primary": "bailian/qwen3.5-plus" }
+    },
+    "list": [
+      { "id": "main" },
+      {
+        "id": "dev-agent",
+        "name": "开发助手",
+        "agentDir": "~/.openclaw/agents/dev-agent/agent"
+      },
+      {
+        "id": "pm-agent",
+        "name": "项目经理",
+        "agentDir": "~/.openclaw/agents/pm-agent/agent"
+      }
+    ]
+  },
+  "channels": {
+    "dingtalk-connector": {
+      "enabled": true,
+      "accounts": {
+        "main-bot": {
+          "enabled": true,
+          "name": "通用助手",
+          "clientId": "ding_main_appkey",
+          "clientSecret": "main_app_secret"
+        },
+        "dev-bot": {
+          "enabled": true,
+          "name": "开发助手机器人",
+          "clientId": "ding_dev_appkey",
+          "clientSecret": "dev_app_secret"
+        },
+        "pm-bot": {
+          "enabled": true,
+          "name": "项目经理机器人",
+          "clientId": "ding_pm_appkey",
+          "clientSecret": "pm_app_secret"
+        }
+      }
+    }
+  },
+  "bindings": [
+    { "agentId": "main",      "match": { "channel": "dingtalk-connector", "accountId": "main-bot" } },
+    { "agentId": "dev-agent",  "match": { "channel": "dingtalk-connector", "accountId": "dev-bot" } },
+    { "agentId": "pm-agent",   "match": { "channel": "dingtalk-connector", "accountId": "pm-bot" } }
+  ]
+}
+```
+
+---
+
+## 三、协作模式：多 Agent 信息接力
+
+当多个 Agent 在同一个群里时，它们可以通过**钉钉文档**进行异步协作——Agent A 写入文档，Agent B 读取文档，实现"信息接力"。
+
+### 3.1 协作工具
+
+| 工具 | 作用 |
+| --- | --- |
+| `docs.create` | 创建协作文档（协作起点） |
+| `docs.append` | 追加处理进度或中间产物 |
+| `docs.read` | 读取协作文档的最新内容 |
+
+### 3.2 协作场景示例
+
+```plaintext
+用户 @项目经理机器人："帮我整理一下本周的需求清单"
+  └─ pm-agent 调用 docs.create 创建《本周需求清单.md》
+  └─ pm-agent 在群里回复文档链接
+
+用户 @开发助手机器人："看看需求清单，给出技术方案"
+  └─ dev-agent 调用 docs.read 读取需求清单
+  └─ dev-agent 调用 docs.append 追加技术方案
+  └─ dev-agent 在群里回复方案摘要
+```
+
+### 3.3 跨 Agent 消息推送
+
+通过 Gateway Methods，一个 Agent 可以主动向其他群/用户发送消息：
+
+```plaintext
+运维 Agent 检测到异常
+  └─ 调用 gateway.call('dingtalk-connector.sendToGroup', { ... })
+  └─ 向"紧急处理群"发送报警
+  └─ 该群的值班 Agent 自动接收并开始处理
+```
+
+---
+
+## 四、每个 Account 的独立配置
+
+每个 account 可以独立覆盖以下配置（不配则继承顶层默认值）：
+
+| 配置项 | 说明 | 示例 |
+| --- | --- | --- |
+| `dmPolicy` | 单聊策略 | `"open"` / `"allowlist"` |
+| `groupPolicy` | 群聊策略 | `"open"` / `"allowlist"` / `"disabled"` |
+| `requireMention` | 群聊是否需要 @机器人 | `true` / `false` |
+| `systemPrompt` | 系统提示词 | `"你是一个代码专家"` |
+| `asyncMode` | 异步模式 | `true` / `false` |
+| `groupSessionScope` | 群聊会话隔离 | `"group"` / `"group_sender"` |
+
+示例：让 dev-bot 在群聊中不需要 @就能响应：
+
+```jsonc
+"accounts": {
+  "dev-bot": {
+    "clientId": "...",
+    "clientSecret": "...",
+    "requireMention": false
+  }
+}
+```
+
+---
+
+## 五、常见问题
+
+### Q1：机器人连接失败，日志显示 `Authentication failed (401)`
+
+**原因**：clientId 或 clientSecret 不正确，或机器人未开启 Stream 模式。
+
+**解决**：
+
+1. 去钉钉开放平台确认 AppKey/AppSecret 是否正确
+2. 确认消息接收模式是 **Stream 模式**
+3. 确认机器人已**发布上线**（不是"开发中"状态）
+
+### Q2：配置了 accounts 后，原来的机器人不工作了
+
+**原因**：一旦配置了 `accounts`，框架只启动 `accounts` 里的机器人。顶层的 clientId/clientSecret 变成了基础默认值，不再作为独立账号启动。
+
+**解决**：把原来的机器人也加到 `accounts` 里。
+
+### Q3：同一个群里两个机器人，怎么确保消息不会路由错？
+
+**原理**：每个机器人维护独立的 WebSocket 连接。用户 @机器人A 时，只有机器人A 收到消息（accountId = A 的 key），bindings 中 `accountId` 匹配确保路由到正确的 Agent。两个机器人之间完全隔离，不会串。
+
+### Q4：如何获取群聊的 conversationId（CID）？
+
+在群聊中 @任意已连接的机器人，发送任意消息。开启 `debug: true` 后，从日志中可以看到：
+
+```plaintext
+处理消息: accountId=xxx, data= { "conversationId": "cidXXXXX", ... }
+```
+
+或者直接在群里问机器人"当前群的 conversationId 是什么"。
+
+---
+
+## 六、后续的改进方向
+
+后续将优化为**通过命令行的形式配置多 Agent**，而**非用户自己去改相应的配置文件**。
+
+connector 优化 ing，后续将提供更简便的多 Agent 配置方式，有问题请提 [Issue](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/issues) 😍

package/docs/RELEASE_NOTES_V0.7.10.md

@@ -0,0 +1,40 @@
+# Release Notes - v0.7.10
+
+## ✨ 功能与体验改进 / Features & Improvements
+
+- **WebSocket 心跳重连机制优化 / WebSocket Reconnection**  
+  WebSocket 会持续尝试重连，保留指数退避策略（1s → 2s → 4s → 8s → 16s → 30s），避免雪崩效应。重连成功后重置计数器，下次失败从 1 秒开始退避。  
+  Removed maximum reconnection attempt limit, implemented infinite reconnection mechanism. WebSocket will continuously attempt to reconnect without giving up. Exponential backoff strategy retained (1s → 2s → 4s → 8s → 16s → 30s) to avoid avalanche effect. Counter resets on successful reconnection, starting from 1 second on next failure.
+
+- **配置简化 / Configuration Simplification**  
+  从 `SocketManagerConfig` 中移除 `maxReconnectAttempts` 配置项，简化配置复杂度。  
+  Removed `maxReconnectAttempts` configuration from `SocketManagerConfig`, simplifying configuration complexity.
+
+- **日志输出优化 / Log Output Optimization**  
+  更新重连日志格式，移除最大次数显示（从 "尝试 X/5" 改为 "尝试 X"），更清晰地展示重连进度。  
+  Updated reconnection log format, removed maximum attempt display (from "attempt X/5" to "attempt X"), providing clearer reconnection progress.
+
+
+## 📥 安装升级 / Installation & Upgrade
+
+```bash
+# 通过 npm 安装最新版本 / Install latest version via npm
+openclaw plugins install @dingtalk-real-ai/dingtalk-connector
+
+# 或升级现有版本 / Or upgrade existing version
+openclaw plugins update dingtalk-connector
+
+# 通过 Git 安装 / Install via Git
+openclaw plugins install https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector.git
+```
+
+## 🔗 相关链接 / 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-03-16  
+**版本号 / Version**：v0.7.10  
+**兼容性 / Compatibility**：OpenClaw Gateway 0.4.0+

package/docs/RELEASE_NOTES_V0.7.2.md

@@ -0,0 +1,143 @@
+# Release Notes - v0.7.2
+
+## ✨ 功能增强版本 / Feature Enhancement Release
+
+本次更新新增异步模式功能，并修复了多个关键问题，提升了连接器的稳定性和用户体验。
+
+This update adds async mode functionality and fixes several critical issues, improving connector stability and user experience.
+
+## ✨ 新增功能 / New Features
+
+### 1. 异步模式 / Async Mode
+
+**功能描述 / Feature Description**：立即回执用户消息，后台处理任务，然后主动推送最终结果作为独立消息  
+Immediately acknowledge user messages, process in background, then push the final result as a separate message
+
+**使用场景 / Use Cases**：
+- 处理耗时较长的任务（如文档分析、代码生成等）  
+  Processing time-consuming tasks (e.g., document analysis, code generation)
+- 需要给用户即时反馈的场景  
+  Scenarios requiring immediate user feedback
+- 希望将处理过程和结果分离的场景  
+  Scenarios where separating processing and results is desired
+
+**配置方式 / Configuration**：
+
+```json5
+{
+  "channels": {
+    "dingtalk-connector": {
+      "asyncMode": true,              // 启用异步模式 / Enable async mode
+      "ackText": "🫡 任务已接收"  // 可选：自定义回执消息 / Optional: Custom ack message
+    }
+  }
+}
+```
+
+**工作流程 / Workflow**：
+1. **立即回执** - 用户发送消息后，连接器立即发送回执消息  
+   **Immediate Acknowledgment** - Connector immediately sends acknowledgment message after user sends message
+2. **后台处理** - 连接器在后台调用 Gateway 处理任务，支持文件附件和图片  
+   **Background Processing** - Connector processes task in background via Gateway, supports file attachments and images
+3. **推送结果** - 处理完成后，连接器主动推送最终结果作为独立消息  
+   **Push Result** - After processing completes, connector proactively pushes final result as separate message
+
+**影响范围 / Impact**：所有用户均可选择启用此功能，默认关闭，不影响现有使用方式  
+All users can optionally enable this feature. Default is off, does not affect existing usage.
+
+## 🐛 修复 / Fixes
+
+### 1. 异步模式下 Agent 路由问题修复 / Agent Routing Fix in Async Mode
+
+**问题描述 / Issue Description**：异步模式下 `streamFromGateway` 调用时缺少 `accountId` 参数，导致会话路由到 undefined agent  
+In async mode, `streamFromGateway` was called without `accountId`, causing sessions to route to undefined agent
+
+**修复内容 / Fix**：
+- 修复 `streamFromGateway` 调用，正确传递 `accountId` 参数  
+  Fixed `streamFromGateway` call to correctly pass `accountId` parameter
+- 确保异步模式下 Agent 路由正常工作  
+  Ensures Agent routing works correctly in async mode
+
+**影响范围 / Impact**：影响使用异步模式的用户，修复后异步模式下的 Agent 路由将正常工作  
+Affects users using async mode. After the fix, Agent routing in async mode will work correctly.
+
+### 2. 默认 Agent 路由修复 / Default Agent Routing Fix
+
+**问题描述 / Issue Description**：当 `accountId` 为 `'default'` 时，仍然发送 `X-OpenClaw-Agent-Id` header，导致路由异常  
+When `accountId` is `'default'`, `X-OpenClaw-Agent-Id` header was still sent, causing routing issues
+
+**修复内容 / Fix**：
+- 当 `accountId` 为 `'default'` 时跳过 `X-OpenClaw-Agent-Id` header  
+  Skip `X-OpenClaw-Agent-Id` header when `accountId` is `'default'`
+- 让 gateway 路由到其配置的默认 agent  
+  Let gateway route to its configured default agent
+
+**影响范围 / Impact**：影响使用默认 Agent 配置的用户，修复后默认 Agent 路由将正常工作  
+Affects users with default Agent configuration. After the fix, default Agent routing will work correctly.
+
+### 3. 异步模式内容处理修复 / Async Mode Content Fix
+
+**问题描述 / Issue Description**：异步模式使用原始 `content.text`，未包含文件附件内容  
+Async mode used raw `content.text`, did not include file attachment content
+
+**修复内容 / Fix**：
+- 使用 `userContent`（包含文件附件）替代原始 `content.text`  
+  Use `userContent` (includes file attachments) instead of raw `content.text`
+- 确保文件附件内容正确传递给 Gateway  
+  Ensures file attachment content is correctly passed to Gateway
+
+**影响范围 / Impact**：影响使用异步模式且发送文件附件的用户，修复后文件附件将正确处理  
+Affects users using async mode and sending file attachments. After the fix, file attachments will be processed correctly.
+
+### 4. 异步模式图片支持修复 / Async Mode Image Support Fix
+
+**问题描述 / Issue Description**：异步模式下未将图片路径传递给 Gateway stream  
+Image paths were not passed to Gateway stream in async mode
+
+**修复内容 / Fix**：
+- 将 `imageLocalPaths` 传递给 gateway stream  
+  Pass `imageLocalPaths` to gateway stream
+- 确保图片在异步模式下正确处理  
+  Ensures images are processed correctly in async mode
+
+**影响范围 / Impact**：影响使用异步模式且发送图片的用户，修复后图片将正确处理  
+Affects users using async mode and sending images. After the fix, images will be processed correctly.
+
+## 🔧 配置更新 / Configuration Updates
+
+### 新增配置项 / New Configuration Options
+
+- **`asyncMode`**（类型：`boolean`，默认：`false`）- 启用异步模式  
+  **`asyncMode`** (type: `boolean`, default: `false`) - Enable async mode
+- **`ackText`**（类型：`string`，默认：`'🫡 任务已接收，处理中...'`）- 自定义回执消息文本  
+  **`ackText`** (type: `string`, default: `'🫡 任务已接收，处理中...'`) - Custom ack message text
+
+## 📥 安装升级 / Installation & Upgrade
+
+```bash
+# 通过 npm 安装最新版本 / Install latest version via npm
+openclaw plugins install @dingtalk-real-ai/dingtalk-connector
+
+# 或升级现有版本 / Or upgrade existing version
+openclaw plugins update dingtalk-connector
+
+# 通过 Git 安装 / Install via Git
+openclaw plugins install https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector.git
+```
+
+## 🔗 相关链接 / 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)
+- [问题反馈 / Issue Feedback](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/issues)
+
+## 🙏 致谢 / Acknowledgments
+
+感谢所有贡献者和用户的支持与反馈！  
+Thanks to all contributors and users for their support and feedback!
+
+---
+
+**发布日期 / Release Date**：2026-03-05  
+**版本号 / Version**：v0.7.2  
+**兼容性 / Compatibility**：OpenClaw Gateway 0.4.0+