@jeik/dingtalk-connector 0.8.21

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+

package/docs/RELEASE_NOTES_V0.7.5.md

@@ -0,0 +1,267 @@
+# Release Notes - v0.7.5
+
+## 🔧 稳定性修复与架构优化版本 / Stability Fixes & Architecture Optimization Release
+
+本次更新主要修复了 Stream 客户端频繁重连和连接关闭不完整的问题，并重构了会话管理机制，采用 OpenClaw Gateway 统一的 session.dmScope 机制，提升了系统的稳定性和可维护性。
+
+This update primarily fixes Stream client frequent reconnection and incomplete connection closure issues, and refactors the session management mechanism to use OpenClaw Gateway's unified session.dmScope mechanism, improving system stability and maintainability.
+
+## 🐛 修复 / Fixes
+
+### 1. Stream 客户端频繁重连问题修复 / Stream Client Frequent Reconnection Fix
+
+**问题描述 / Issue Description**：  
+`DWClient` 内置的 `autoReconnect` 与框架的 health-monitor 重连机制冲突，导致客户端频繁重连，影响系统稳定性。  
+`DWClient` built-in `autoReconnect` conflicts with framework's health-monitor reconnection mechanism, causing frequent client reconnections and affecting system stability.
+
+**修复内容 / Fix**：
+- 禁用 `DWClient` 内置的 `autoReconnect`  
+  Disabled `DWClient` built-in `autoReconnect`
+- 由框架的 health-monitor 统一管理重连逻辑  
+  Reconnection is now managed by framework's health-monitor
+- 避免双重重连机制冲突  
+  Avoid dual reconnection mechanism conflict
+
+**影响范围 / Impact**：  
+影响所有使用 Stream 模式的用户。修复后，重连逻辑更加稳定，不再出现频繁重连的问题。  
+Affects all users using Stream mode. After the fix, reconnection logic is more stable, no longer experiencing frequent reconnection issues.
+
+### 2. 连接关闭不完整问题修复 / Incomplete Connection Closure Fix
+
+**问题描述 / Issue Description**：  
+`stop()` 方法未正确关闭 WebSocket 连接，导致资源泄漏和连接状态异常。  
+`stop()` method did not correctly close WebSocket connection, causing resource leaks and connection state anomalies.
+
+**修复内容 / Fix**：
+- `stop()` 方法现在正确调用 `client.disconnect()` 关闭 WebSocket 连接  
+  `stop()` method now correctly calls `client.disconnect()` to close WebSocket connection
+- 确保连接资源正确释放  
+  Ensure connection resources are properly released
+
+**影响范围 / Impact**：  
+影响所有使用连接器的用户。修复后，连接关闭更加完整，避免资源泄漏。  
+Affects all users using the connector. After the fix, connection closure is more complete, avoiding resource leaks.
+
+### 3. Gateway 端口连接修复 / Gateway Port Connection Fix
+
+**问题描述 / Issue Description**：  
+修改 gateway 端口后无法连接的问题。  
+Issue where connection fails after modifying gateway port.
+
+**修复内容 / Fix**：
+- 修复端口配置更新后的连接逻辑  
+  Fixed connection logic after port configuration update
+- 确保端口变更后能够正确连接  
+  Ensure correct connection after port changes
+
+**影响范围 / Impact**：  
+影响修改了 Gateway 端口的用户。修复后，端口变更后能够正常连接。  
+Affects users who modified Gateway port. After the fix, connection works normally after port changes.
+
+## 🔄 重构 / Refactoring
+
+### 1. OpenClaw session.dmScope 机制 / OpenClaw session.dmScope Mechanism
+
+**重构内容 / Refactoring**：
+- 会话管理由 OpenClaw Gateway 统一处理  
+  Session management is now handled by OpenClaw Gateway
+- 插件不再内部管理会话超时  
+  Plugin no longer manages session timeout internally
+- 使用 Gateway 的 `session.reset.idleMinutes` 配置控制会话超时  
+  Use Gateway's `session.reset.idleMinutes` configuration to control session timeout
+
+**优势 / Benefits**：
+- ✅ 统一会话管理，减少重复逻辑  
+  Unified session management, reducing duplicate logic
+- ✅ 配置更加集中和标准化  
+  More centralized and standardized configuration
+- ✅ 降低插件复杂度，提高可维护性  
+  Reduce plugin complexity, improve maintainability
+
+**影响范围 / Impact**：  
+架构层面的改进，不影响用户使用，但提高了系统的可维护性和一致性。  
+Architecture-level improvement, does not affect user usage, but improves system maintainability and consistency.
+
+### 2. SessionContext 标准化 / SessionContext Standardization
+
+**重构内容 / Refactoring**：
+- 使用 OpenClaw 标准的 SessionContext JSON 格式传递会话上下文  
+  Use OpenClaw standard SessionContext JSON format for session context
+- 统一会话上下文的数据结构  
+  Unify session context data structure
+- 提高与 Gateway 的兼容性  
+  Improve compatibility with Gateway
+
+**优势 / Benefits**：
+- ✅ 标准化格式，便于 Gateway 解析和处理  
+  Standardized format, easier for Gateway to parse and process
+- ✅ 提高数据一致性和可预测性  
+  Improve data consistency and predictability
+- ✅ 便于未来扩展和维护  
+  Facilitate future expansion and maintenance
+
+**影响范围 / Impact**：  
+内部实现改进，不影响用户使用，但提高了与 Gateway 的兼容性和数据一致性。  
+Internal implementation improvement, does not affect user usage, but improves compatibility with Gateway and data consistency.
+
+## 📋 配置变更 / Configuration Changes
+
+### 新增配置项 / New Configuration Options
+
+| 配置项 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `groupSessionScope` | `'group'` \| `'group_sender'` | `'group'` | 群聊会话隔离策略（仅当 separateSessionByConversation=true 时生效）：`group`=群共享，`group_sender`=群内用户独立 |
+
+### 废弃配置项 / Deprecated Configuration Options
+
+| 配置项 | 状态 | 替代方案 | 说明 |
+|--------|------|----------|------|
+| `sessionTimeout` | ⚠️ 已废弃 | Gateway 的 `session.reset.idleMinutes` | 会话超时由 OpenClaw Gateway 统一管理，详见 [Gateway 配置文档](https://docs.openclaw.ai/gateway/configuration) |
+
+### 配置示例 / Configuration Example
+
+```json5
+{
+  "channels": {
+    "dingtalk-connector": {
+      "enabled": true,
+      "clientId": "dingxxxxxxxxx",
+      "clientSecret": "your_secret_here",
+      "separateSessionByConversation": true,
+      "groupSessionScope": "group",  // 新增：群聊会话隔离策略
+      // "sessionTimeout": 30  // ⚠️ 已废弃，请使用 Gateway 配置
+    }
+  },
+  // Gateway 配置示例
+  "gateway": {
+    "session": {
+      "reset": {
+        "idleMinutes": 30  // 会话超时配置
+      }
+    }
+  }
+}
+```
+
+### 群聊会话隔离策略说明 / Group Session Scope Explanation
+
+`groupSessionScope` 配置仅在 `separateSessionByConversation=true` 时生效：
+
+- **`group`**（默认）：整个群共享一个会话，群内所有用户共用同一个对话上下文  
+  **`group`** (default): Entire group shares one session, all users in the group share the same conversation context
+- **`group_sender`**：群内每个用户独立会话，不同用户的对话上下文互不干扰  
+  **`group_sender`**: Each user in the group has an independent session, conversation contexts of different users do not interfere
+
+## 📥 安装升级 / 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
+- **sessionTimeout 废弃**：旧配置 `sessionTimeout` 仍可使用，但会打印废弃警告日志，建议迁移到 Gateway 配置  
+  **sessionTimeout Deprecated**: Old config `sessionTimeout` still works but will print deprecation warning, recommend migrating to Gateway configuration
+- **推荐升级**：使用 Stream 模式的用户强烈建议升级到此版本，以修复重连和连接关闭问题  
+  **Recommended Upgrade**: Users using Stream mode are strongly recommended to upgrade to this version to fix reconnection and connection closure issues
+
+### 迁移指南 / Migration Guide
+
+升级到此版本后：
+After upgrading to this version:
+
+1. **检查重连行为**：确认重连逻辑是否正常，不再出现频繁重连  
+   **Check reconnection behavior**: Verify reconnection logic is normal, no longer experiencing frequent reconnections
+2. **迁移 sessionTimeout**：如有使用 `sessionTimeout` 配置，建议迁移到 Gateway 的 `session.reset.idleMinutes` 配置  
+   **Migrate sessionTimeout**: If using `sessionTimeout` configuration, recommend migrating to Gateway's `session.reset.idleMinutes` configuration
+3. **配置群聊会话隔离**：如需群内用户独立会话，可设置 `groupSessionScope: "group_sender"`  
+   **Configure group session isolation**: To have independent sessions per user in group, set `groupSessionScope: "group_sender"`
+4. **验证连接关闭**：确认 `stop()` 方法能够正确关闭连接  
+   **Verify connection closure**: Verify that `stop()` method correctly closes connection
+
+### sessionTimeout 迁移步骤 / sessionTimeout Migration Steps
+
+**迁移前 / Before**：
+```json5
+{
+  "channels": {
+    "dingtalk-connector": {
+      "sessionTimeout": 30  // ⚠️ 已废弃
+    }
+  }
+}
+```
+
+**迁移后 / After**：
+```json5
+{
+  "channels": {
+    "dingtalk-connector": {
+      // 移除 sessionTimeout 配置
+    }
+  },
+  "gateway": {
+    "session": {
+      "reset": {
+        "idleMinutes": 30  // 使用 Gateway 配置
+      }
+    }
+  }
+}
+```
+
+## 📋 技术细节 / Technical Details
+
+### 内部实现变更 / Internal Implementation Changes
+
+**变更前 / Before**：
+- `DWClient` 启用 `autoReconnect`，与框架重连机制冲突
+- 插件内部管理会话超时
+- `stop()` 方法未正确关闭 WebSocket 连接
+- SessionContext 格式不统一
+
+**变更后 / After**：
+- `DWClient` 禁用 `autoReconnect`，由框架统一管理重连
+- 会话超时由 Gateway 统一管理
+- `stop()` 方法正确调用 `client.disconnect()` 关闭连接
+- SessionContext 使用 OpenClaw 标准格式
+
+### 相关代码位置 / Related Code Locations
+
+主要修改文件：
+- `plugin.ts` - 核心逻辑修改
+
+关键变更点：
+- `DWClient` 初始化时的 `autoReconnect` 配置
+- `stop()` 方法中的连接关闭逻辑
+- SessionContext 格式标准化
+- 会话超时配置移除
+
+## 🔗 相关链接 / 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)
+- [Gateway 配置文档 / Gateway Configuration](https://docs.openclaw.ai/gateway/configuration)
+- [问题反馈 / 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-10  
+**版本号 / Version**：v0.7.5  
+**兼容性 / Compatibility**：OpenClaw Gateway 0.4.0+