@dingtalk-real-ai/dingtalk-connector 0.8.12 → 0.8.13-beta.0

package/CHANGELOG.md

@@ -5,6 +5,36 @@ 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.13-beta.0] - 2026-04-06
+
+### 修复 / Fixes
+- 🐛 **修复多账号场景下凭据未解析** - `sendText`/`sendMedia` 在多账号模式下 `clientId`/`clientSecret` 可能为 `SecretInput` 对象，导致 API 请求携带无效凭据。现已用 `resolveDingtalkAccount` 返回的已解析值覆盖原始 config  
+  **Fix unresolved credentials in sendText/sendMedia** - In multi-account mode, credentials could be `SecretInput` objects; now resolved values are used
+
+- 🐛 **修复连接错误在 async 回调中无法传播** - `connection.ts` 错误处理使用 `throw` 抛出，但在 async 回调内无法被外层 Promise 捕获。改为 `reject(new Error(...))` 确保 400/401 等错误正确传播  
+  **Fix connection errors not propagating in async callback** - Changed `throw` to `reject()` inside async error handlers
+
+- 🐛 **修复 QPS 限流后立即重试触发再次限流** - 收到 403 QpsLimit 后未更新 `lastUpdateTime`，导致节流检查立即放行。现已同步更新节流时间  
+  **Fix QPS rate limit immediate retry** - `lastUpdateTime` is now synced when skipping a QPS-limited update
+
+- 🐛 **修复 `resolveAllowFrom` 全局过滤误拦截群消息** - `allowFrom` 仅用于私聊白名单，群消息由 `groupAllowFrom` 在内部处理。将 `resolveAllowFrom` 改为返回空列表，禁用框架层全局过滤  
+  **Fix resolveAllowFrom global filter blocking group messages** - Returns `[]` to disable framework-level filtering; internal policy checks handle DM and group separately
+
+### 新增 / Added
+- ✨ **消息路由支持 `group:`/`user:` 前缀** - `sendTextToDingTalk` 和 `sendMediaToDingTalk` 新增 `group:<id>` 和 `user:<id>` 格式解析，与 `gateway-methods.ts` 保持一致，兼容旧版裸 `cid` 前缀  
+  **Message routing supports `group:`/`user:` prefix targets** - Consistent with `gateway-methods.ts`, backward compatible with bare `cid` prefix
+
+### 改进 / Improvements
+- ✅ **兼容 pdf-parse v1 和 v2 API** - `parsePdfFile` 自动检测 pdf-parse 导出格式，v2.x 使用 `PDFParse` 类，v1.x 使用 `default` 函数  
+  **Support both pdf-parse v1 and v2 API** - Auto-detects export format: v2.x class API or v1.x function API
+
+- ✅ **`enableMediaUpload`/`systemPrompt` 移至共享配置** - 这两个字段现在支持多账号模式下每个账号独立配置  
+  **Move `enableMediaUpload`/`systemPrompt` to shared config** - Now configurable per-account in multi-account mode
+
+### 文档 / Documentation
+- 📝 **优化 README 安装验证说明** - 移除版本号硬编码，新增插件未加载时的警示提示  
+  **Improve README plugin verification instructions** - Removed hardcoded version, added warning when plugin is not loaded
+
 ## [0.8.12] - 2026-04-01
 
 ### 修复 / Fixes

package/README.en.md

@@ -122,7 +122,9 @@ registry=https://registry.npmmirror.com
 ```bash
 openclaw plugins list
 ```
-You should see `✓ DingTalk Channel (v0.8.6) - loaded`
+You should see output similar to `✓ DingTalk Channel (vX.X.X) - loaded`.
+
+> ⚠️ **If you don't see `loaded`**, resolve the plugin loading issue before proceeding to Step 3. Otherwise, DingTalk will not appear in `openclaw channels add`.
 
 ---
 

package/README.md

@@ -154,7 +154,9 @@ registry=https://registry.npmmirror.com
 ```bash
 openclaw plugins list
 ```
-你应该看到 `✓ DingTalk Channel (v0.8.6) - loaded`
+你应该看到类似 `✓ DingTalk Channel (vX.X.X) - loaded` 的输出。
+
+> ⚠️ **如果没看到 `loaded`**，请先解决插件加载问题，再进行步骤 3 的配置。否则 `openclaw channels add` 中不会出现钉钉选项。
 
 ---
 

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+

package/docs/RELEASE_NOTES_V0.7.3.md

@@ -0,0 +1,149 @@
+# Release Notes - v0.7.3
+
+## 🔧 兼容性修复版本 / Compatibility Fix Release
+
+本次更新主要修复了 0.7.0 版本引入的默认 Agent 路由回归问题，确保与 0.7.0 之前版本的向下兼容性。
+
+This update primarily fixes the default Agent routing regression introduced in version 0.7.0, ensuring backward compatibility with versions before 0.7.0.
+
+## 🐛 修复 / Fixes
+
+### 1. 默认 Agent 路由兼容性修复 / Default Agent Routing Compatibility Fix
+
+**问题描述 / Issue Description**：  
+在 0.7.0 版本中，默认路由（没有配置 `accountId` 时）从 `main` agent 错误地改成了 `default` agent，导致与 0.7.0 之前版本的行为不一致，可能影响现有用户的配置和会话路由。  
+In version 0.7.0, the default route (when no `accountId` was configured) was incorrectly changed from `main` agent to `default` agent, causing inconsistency with versions before 0.7.0, which may affect existing user configurations and session routing.
+
+**修复内容 / Fix**：
+- 恢复默认路由到 `main` agent，与 0.7.0 之前版本保持一致  
+  Restored default routing to `main` agent, consistent with versions before 0.7.0
+- 使用 `__default__` 作为内部默认账号标识，避免与用户配置的 `default` 账号冲突  
+  Use `__default__` as internal default account identifier to avoid conflicts with user-configured `default` accounts
+- 在 `streamFromGateway` 中将 `__default__` 正确映射到 `main` agent  
+  Correctly map `__default__` to `main` agent in `streamFromGateway`
+
+**影响范围 / Impact**：  
+影响所有使用默认配置（未配置 `accounts`）的用户。修复后，默认路由将恢复到 0.7.0 之前的行为，路由到 `main` agent，确保向下兼容性。  
+Affects all users using default configuration (without `accounts` configuration). After the fix, default routing will be restored to pre-0.7.0 behavior, routing to `main` agent, ensuring backward compatibility.
+
+### 2. 用户配置 `default` 账号映射修复 / User-Configured `default` Account Mapping Fix
+
+**问题描述 / Issue Description**：  
+当用户显式配置名为 `default` 的账号时，系统会错误地将其映射为内部默认账号，导致用户配置的 `default` 账号无法正常使用。  
+When users explicitly configure an account named `default`, the system incorrectly maps it to the internal default account, preventing the user-configured `default` account from working properly.
+
+**修复内容 / Fix**：
+- 使用 `__default__` 作为内部默认账号标识，与用户配置的 `default` 账号区分开  
+  Use `__default__` as internal default account identifier, separate from user-configured `default` accounts
+- 确保用户配置的 `default` 账号能够正常使用  
+  Ensure user-configured `default` accounts can work properly
+
+**影响范围 / Impact**：  
+影响显式配置了名为 `default` 的账号的用户。修复后，用户配置的 `default` 账号将能够正常工作，不会被错误映射。  
+Affects users who explicitly configured an account named `default`. After the fix, user-configured `default` accounts will work properly and will not be incorrectly mapped.
+
+## 🔧 改进 / Improvements
+
+### 1. 代码结构优化 / Code Structure Optimization
+
+**改进内容 / Improvements**：
+- 抽取 `DEFAULT_ACCOUNT_ID` 常量到文件顶部（值为 `__default__`），统一管理默认账号标识  
+  Extracted `DEFAULT_ACCOUNT_ID` constant to file top (value: `__default__`), unified management of default account identifier
+- 更新所有相关代码，使用常量替代硬编码的字符串  
+  Updated all related code to use constants instead of hardcoded strings
+- 提高代码可维护性和可读性  
+  Improved code maintainability and readability
+
+**影响范围 / Impact**：  
+内部代码改进，不影响用户使用，但提高了代码质量和可维护性。  
+Internal code improvements, does not affect user usage, but improves code quality and maintainability.
+
+### 2. API 文档更新 / API Documentation Updates
+
+**改进内容 / Improvements**：
+- 更新 API 文档注释，移除对 `default` 的硬编码引用  
+  Updated API documentation comments, removed hardcoded references to `default`
+- 明确说明 `accountId` 参数为可选，不传则使用默认配置  
+  Clarified that `accountId` parameter is optional, uses default configuration if not provided
+
+**影响范围 / Impact**：  
+文档改进，帮助开发者更好地理解 API 的使用方式。  
+Documentation improvements, helping developers better understand API usage.
+
+## 📋 技术细节 / Technical Details
+
+### 内部实现变更 / Internal Implementation Changes
+
+**变更前 / Before**：
+- 默认账号标识使用 `'default'` 字符串
+- 当 `accountId` 为 `'default'` 时，不发送 `X-OpenClaw-Agent-Id` header，让 gateway 路由到其配置的默认 agent
+
+**变更后 / After**：
+- 默认账号标识使用 `'__default__'` 常量
+- 在 `streamFromGateway` 中，将 `'__default__'` 映射到 `'main'` agent，并发送 `X-OpenClaw-Agent-Id: main` header
+- 用户配置的 `'default'` 账号正常使用，不会被特殊处理
+
+### 相关代码位置 / Related Code Locations
+
+主要修改文件：
+- `plugin.ts` - 核心逻辑修改
+
+关键变更点：
+- 新增 `DEFAULT_ACCOUNT_ID` 常量定义
+- `streamFromGateway` 函数中的 agent 路由逻辑
+- `listAccountIds`、`resolveAccount`、`defaultAccountId` 等配置相关函数
+- API 方法文档注释
+
+## 📥 安装升级 / 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
+```
+
+## ⚠️ 升级注意事项 / Upgrade Notes
+
+### 兼容性说明 / Compatibility Notes
+
+- **向下兼容**：本次更新恢复了 0.7.0 之前版本的默认路由行为，对现有用户完全兼容  
+  **Backward Compatible**: This update restores the default routing behavior of versions before 0.7.0, fully compatible with existing users
+- **无需配置变更**：现有配置无需修改即可正常工作  
+  **No Configuration Changes Required**: Existing configurations work without modification
+- **推荐升级**：使用默认配置的用户强烈建议升级到此版本，以确保正确的 Agent 路由  
+  **Recommended Upgrade**: Users with default configuration are strongly recommended to upgrade to this version to ensure correct Agent routing
+
+### 迁移指南 / Migration Guide
+
+如果您在 0.7.0 或 0.7.1 版本中遇到了默认路由问题，升级到此版本后：
+If you encountered default routing issues in versions 0.7.0 or 0.7.1, after upgrading to this version:
+
+1. **默认路由将自动恢复**：无需任何配置，默认路由将自动恢复到 `main` agent  
+   **Default routing will be automatically restored**: No configuration needed, default routing will automatically restore to `main` agent
+2. **检查 Agent 配置**：确认您的 Gateway 中 `main` agent 的配置是否正确  
+   **Check Agent Configuration**: Verify that your Gateway's `main` agent configuration is correct
+3. **验证路由**：升级后测试会话路由，确认消息正确路由到预期的 agent  
+   **Verify Routing**: Test session routing after upgrade to confirm messages are correctly routed to the expected agent
+
+## 🔗 相关链接 / 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)
+- [Pull Request #108](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/pull/108)
+
+## 🙏 致谢 / Acknowledgments
+
+感谢所有贡献者和用户的支持与反馈！
+Thanks to all contributors and users for their support and feedback! 
+
+---
+
+**发布日期 / Release Date**：2026-03-09  
+**版本号 / Version**：v0.7.3  
+**兼容性 / Compatibility**：OpenClaw Gateway 0.4.0+

package/docs/RELEASE_NOTES_V0.7.4.md

@@ -0,0 +1,206 @@
+# Release Notes - v0.7.4
+
+## 🎉 功能增强版本 / Feature Enhancement Release
+
+本次更新主要新增了按会话区分 Session 的功能，支持单聊、群聊、不同群分别维护独立会话，并提供了记忆隔离/共享的配置选项，让会话管理更加灵活和精细。
+
+This update primarily adds session separation by conversation feature, supporting separate sessions for direct chat, group chat, and different groups, and provides memory isolation/sharing configuration options for more flexible and fine-grained session management.
+
+## ✨ 新增功能 / Added Features
+
+### 1. 按会话区分 Session / Session by Conversation
+
+**功能描述 / Feature Description**：  
+支持按单聊、群聊、不同群分别维护独立会话，单聊与群聊、不同群之间的对话上下文互不干扰。  
+Support separate sessions for direct chat, group chat, and different groups; conversation context is isolated between DMs, group chats, and different groups.
+
+**使用场景 / Use Cases**：
+- ✅ 同一机器人在多个群中服务，希望每个群的对话互不干扰  
+  Same bot serves multiple groups, with isolated conversations per group
+- ✅ 用户既在私聊也在群聊中使用机器人，希望私聊与群聊上下文分离  
+  Users interact with bot in both DMs and group chats, with separated contexts
+- ✅ 不同群之间的对话历史完全隔离  
+  Complete isolation of conversation history between different groups
+
+**配置方式 / Configuration**：
+```json5
+{
+  "channels": {
+    "dingtalk-connector": {
+      "separateSessionByConversation": true  // 默认：true
+    }
+  }
+}
+```
+
+**影响范围 / Impact**：  
+默认启用，所有用户自动获得会话隔离能力。如需兼容旧行为（按用户维度维护 session），可设置 `separateSessionByConversation: false`。  
+Enabled by default, all users automatically get session isolation capability. To maintain old behavior (session per user), set `separateSessionByConversation: false`.
+
+### 2. 记忆隔离/共享配置 / Memory Isolation/Sharing Configuration
+
+**功能描述 / Feature Description**：  
+新增 `sharedMemoryAcrossConversations` 配置，控制单 Agent 场景下是否在不同会话间共享记忆；默认 `false` 实现群聊与私聊、不同群之间的记忆隔离。  
+Added `sharedMemoryAcrossConversations` option to control whether memory is shared across conversations in single-Agent mode; default `false` isolates memory between DMs, group chats, and different groups.
+
+**配置选项 / Configuration Options**：
+- `false`（默认）：不同群聊、群聊与私聊之间的记忆隔离，AI 不会混淆不同场景下的对话历史  
+  `false` (default): Memory isolated between different groups and between DMs and groups, AI won't confuse conversation history across scenarios
+- `true`：单 Agent 场景下，同一用户在不同会话间共享记忆  
+  `true`: In single-Agent mode, same user shares memory across different sessions
+
+**配置方式 / Configuration**：
+```json5
+{
+  "channels": {
+    "dingtalk-connector": {
+      "sharedMemoryAcrossConversations": false  // 默认：false
+    }
+  }
+}
+```
+
+**影响范围 / Impact**：  
+默认关闭，确保不同场景下的记忆隔离。如需跨会话共享记忆，可设置 `sharedMemoryAcrossConversations: true`。  
+Disabled by default, ensuring memory isolation across scenarios. To share memory across sessions, set `sharedMemoryAcrossConversations: true`.
+
+### 3. Gateway Session 格式增强 / Gateway Session Format Enhancement
+
+**功能描述 / Feature Description**：  
+Session key 支持 `group:conversationId` 格式，便于 Gateway 识别群聊场景。  
+Session key supports `group:conversationId` format for Gateway to identify group chat scenarios.
+
+**技术细节 / Technical Details**：
+- 单聊会话：使用 `direct:{userId}` 格式  
+  Direct chat sessions: Use `direct:{userId}` format
+- 群聊会话：使用 `group:{conversationId}` 格式  
+  Group chat sessions: Use `group:{conversationId}` format
+- Gateway 可以根据 Session key 格式识别会话类型  
+  Gateway can identify session type based on Session key format
+
+**影响范围 / Impact**：  
+内部实现改进，不影响用户使用，但提高了 Gateway 对会话类型的识别能力。  
+Internal implementation improvement, does not affect user usage, but improves Gateway's ability to identify session types.
+
+### 4. X-OpenClaw-Memory-User 支持 / X-OpenClaw-Memory-User Support
+
+**功能描述 / Feature Description**：  
+向 Gateway 传递记忆归属用户标识，支持 Gateway 侧记忆管理。  
+Pass memory user identifier to Gateway for memory management.
+
+**技术细节 / Technical Details**：
+- 在请求 Gateway 时，自动添加 `X-OpenClaw-Memory-User` header  
+  Automatically add `X-OpenClaw-Memory-User` header when requesting Gateway
+- Header 值为发送消息的用户 ID，便于 Gateway 进行记忆归属管理  
+  Header value is the user ID who sent the message, facilitating Gateway's memory ownership management
+
+**影响范围 / Impact**：  
+内部实现改进，支持 Gateway 侧更精细的记忆管理能力。  
+Internal implementation improvement, supporting Gateway-side fine-grained memory management capabilities.
+
+## 📋 配置变更 / Configuration Changes
+
+### 新增配置项 / New Configuration Options
+
+| 配置项 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `separateSessionByConversation` | `boolean` | `true` | 是否按单聊/群聊/群区分 session |
+| `sharedMemoryAcrossConversations` | `boolean` | `false` | 是否在不同会话间共享记忆 |
+
+### 配置示例 / Configuration Example
+
+```json5
+{
+  "channels": {
+    "dingtalk-connector": {
+      "enabled": true,
+      "clientId": "dingxxxxxxxxx",
+      "clientSecret": "your_secret_here",
+      "separateSessionByConversation": true,      // 按会话区分 Session
+      "sharedMemoryAcrossConversations": false    // 记忆隔离（默认）
+    }
+  }
+}
+```
+
+## 📥 安装升级 / 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
+```
+
+## ⚠️ 升级注意事项 / Upgrade Notes
+
+### 兼容性说明 / Compatibility Notes
+
+- **向下兼容**：本次更新完全向下兼容，现有配置无需修改即可正常工作  
+  **Backward Compatible**: This update is fully backward compatible, existing configurations work without modification
+- **默认行为变更**：默认启用 `separateSessionByConversation`，会话将按单聊/群聊/群区分  
+  **Default Behavior Change**: `separateSessionByConversation` is enabled by default, sessions will be separated by direct/group/different groups
+- **如需旧行为**：如需保持按用户维度维护 session 的旧行为，可设置 `separateSessionByConversation: false`  
+  **For Old Behavior**: To maintain old behavior of session per user, set `separateSessionByConversation: false`
+
+### 迁移指南 / Migration Guide
+
+升级到此版本后：
+After upgrading to this version:
+
+1. **默认启用会话隔离**：无需任何配置，会话将自动按单聊/群聊/群区分  
+   **Session isolation enabled by default**: No configuration needed, sessions will automatically be separated by direct/group/different groups
+2. **检查会话行为**：确认新的会话隔离行为是否符合预期  
+   **Check session behavior**: Verify that the new session isolation behavior meets expectations
+3. **配置记忆共享**：如需跨会话共享记忆，可设置 `sharedMemoryAcrossConversations: true`  
+   **Configure memory sharing**: To share memory across sessions, set `sharedMemoryAcrossConversations: true`
+4. **恢复旧行为**：如需恢复按用户维度维护 session 的旧行为，设置 `separateSessionByConversation: false`  
+   **Restore old behavior**: To restore old behavior of session per user, set `separateSessionByConversation: false`
+
+## 📋 技术细节 / Technical Details
+
+### 内部实现变更 / Internal Implementation Changes
+
+**变更前 / Before**：
+- Session key 使用用户 ID：`{userId}`
+- 所有会话共享同一个 Session，不区分单聊/群聊
+- 记忆在所有会话间共享
+
+**变更后 / After**：
+- Session key 支持格式：
+  - 单聊：`direct:{userId}`
+  - 群聊：`group:{conversationId}`
+- 默认按单聊/群聊/群区分 Session
+- 默认记忆隔离，可通过配置共享
+
+### 相关代码位置 / Related Code Locations
+
+主要修改文件：
+- `plugin.ts` - 核心逻辑修改
+
+关键变更点：
+- Session key 生成逻辑
+- `streamFromGateway` 函数中的 Session 处理
+- 记忆用户标识传递
+- 配置项解析和验证
+
+## 🔗 相关链接 / 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-09  
+**版本号 / Version**：v0.7.4  
+**兼容性 / Compatibility**：OpenClaw Gateway 0.4.0+