@dingtalk-real-ai/dingtalk-connector 0.7.5 → 0.7.7

package/.github/workflows/issue-to-AI-table.yml

@@ -0,0 +1,52 @@
+# Issue 变更推送到 Webhook
+# 当有 Issue 变更时，发送指定格式的数据到 webhook
+name: 📤 Issue Webhook Notification
+
+on:
+  issues:
+    types: [opened, reopened, closed, edited, labeled, unlabeled]
+
+jobs:
+  notify:
+    runs-on: ubuntu-latest
+    steps:
+      - name: 📬 Send Issue to Webhook
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const webhook = process.env.ISSUE_WEBHOOK_URL;
+            if (!webhook) {
+              console.log('⚠️ ISSUE_WEBHOOK_URL not set, skipping notification');
+              return;
+            }
+            
+            const payload = context.payload;
+            const issue = payload.issue;
+            const action = payload.action;
+            
+            // 构建指定格式的数据
+            const webhookPayload = {
+              action: action,
+              issue: {
+                id: issue.id,
+                number: issue.number,
+                title: issue.title,
+                body: issue.body,
+                state: issue.state,
+                html_url: issue.html_url
+              }
+            };
+            
+            const response = await fetch(webhook, {
+              method: 'POST',
+              headers: { 'Content-Type': 'application/json' },
+              body: JSON.stringify(webhookPayload)
+            });
+            
+            if (response.ok) {
+              console.log('✅ Webhook notification sent successfully');
+            } else {
+              console.log('❌ Failed to send webhook notification:', response.status, response.statusText);
+            }
+        env:
+          ISSUE_WEBHOOK_URL: ${{ secrets.DINGTALK_AI_TABLE_WEBHOOK }}

package/CHANGELOG.md

@@ -6,6 +6,34 @@
 This document records all significant changes. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and version numbers follow [Semantic Versioning](https://semver.org/).
 
+## [0.7.7] - 2026-03-13
+
+### 新增 / Added
+- ✨ **自定义 Gateway URL 支持** - 新增 `gatewayBaseUrl` 配置项，支持通过自定义 URL（如 Nginx 反向代理到 TLS/HTTPS Gateway）访问 Gateway  
+  **Custom Gateway URL support** - Added `gatewayBaseUrl` option to allow using a custom URL (e.g., Nginx reverse proxy to a TLS/HTTPS Gateway)
+- ✨ **钉钉「思考中」表情反馈** - 在处理用户消息期间为原消息贴上「🤔思考中」表情，处理结束后自动撤回，清晰展示处理进度  
+  **DingTalk “thinking” emotion feedback** - Attaches a “🤔 Thinking” emotion to the original user message while processing and automatically recalls it after completion to clearly indicate progress
+- ✨ **测试基础设施完善** - 引入 Vitest 及多种测试脚本（run/watch/coverage/ui/integration），为后续自动化测试和回归验证提供基础  
+  **Improved testing infrastructure** - Introduced Vitest and multiple test scripts (run/watch/coverage/ui/integration) to enable better automated and regression testing
+- ✨ **Issue Webhook 工作流** - 新增 GitHub Actions 工作流，将 Issue 变更以统一 JSON 格式推送到配置的 Webhook  
+  **Issue webhook workflow** - Added a GitHub Actions workflow to push Issue changes as unified JSON payloads to a configured webhook
+
+### 修复 / Fixes
+- 🐛 **媒体元数据与缩略图提取更健壮** - ffprobe 或缩略图生成失败时不再中断主流程，而是返回默认元数据或空缩略图  
+  **More robust media metadata & thumbnail extraction** - ffprobe or thumbnail generation failures no longer abort the main flow but return default metadata or a null thumbnail instead
+- 🐛 **音频时长提取兼容性改进** - 使用动态 `import('child_process')` 替代 `require('child_process')`，提升在不同运行环境下的兼容性  
+  **Audio duration extraction compatibility** - Replaced `require('child_process')` with dynamic `import('child_process')` to improve compatibility across environments
+- 🐛 **主动消息用户列表校验** - 为主动消息的 `userIds` 列表增加空值过滤，避免因无效用户 ID 导致请求失败  
+  **Proactive message user list validation** - Added empty value filtering for the `userIds` list in proactive messages to prevent request failures caused by invalid IDs
+
+## [0.7.6] - 2026-03-12
+
+### 修复 / Fixes
+- 🐛 **Gateway 端口连接修复** - 修复修改 gateway 端口后无法连接的问题，确保配置中的 `gateway.port` 能够正确生效  
+  **Gateway port connection fix** - Fixed issue where connection fails after modifying gateway port, ensuring that `gateway.port` in configuration takes effect correctly
+- 🐛 **新会话命令修复** - 修复新会话命令（`/new`、`/reset`、`/clear`、`新会话` 等）未真正清理会话的问题，统一将命令透传到 Gateway 由 Gateway 统一处理会话重置  
+  **New session command fix** - Fixed issue where new session commands (`/new`, `/reset`, `/clear`, `新会话`, etc.) did not actually clear sessions, commands are now forwarded to Gateway for unified session reset handling
+
 ## [0.7.5] - 2026-03-10
 
 ### 修复 / Fixes
@@ -13,6 +41,8 @@ and version numbers follow [Semantic Versioning](https://semver.org/).
   **Fixed Stream client frequent reconnection issue** - Disabled `DWClient` built-in `autoReconnect`, reconnection is now managed by framework's health-monitor to avoid dual reconnection mechanism conflict
 - 🐛 **修复连接关闭不完整问题** - `stop()` 方法现在正确调用 `client.disconnect()` 关闭 WebSocket 连接  
   **Fixed incomplete connection closure** - `stop()` method now correctly calls `client.disconnect()` to close WebSocket connection
+- 🐛 **Gateway 端口连接修复** - 修复修改 gateway 端口后无法连接的问题
+  **Gateway port connection fix** - Fixed issue where connection fails after modifying gateway port
 
 ### 重构 / Refactoring
 - ✅ **OpenClaw session.dmScope 机制** - 会话管理由 OpenClaw Gateway 统一处理，插件不再内部管理会话超时  

package/README.md

@@ -1,8 +1,9 @@
-# DingTalk OpenClaw Connector
+# Offical DingTalk OpenClaw Connector 
+## 钉钉官方OpenClaw连接器
 
 以下提供两种方案连接到 [OpenClaw](https://openclaw.ai) Gateway，分别是钉钉机器人和钉钉 DEAP Agent。
 
-> 📝 **版本信息**：当前版本 v0.7.4 | [查看变更日志](CHANGELOG.md) | [发布说明](docs/RELEASE_NOTES_V0.7.4.md) | [发布指南](RELEASE.md)
+> 📝 **版本信息**：当前版本 v0.7.7 | [查看变更日志](CHANGELOG.md) | [发布说明](docs/RELEASE_NOTES_V0.7.7.md) | [发布指南](RELEASE.md)
 
 ## 快速导航
 
@@ -86,6 +87,7 @@ openclaw plugins install -l .
   "channels": {
     "dingtalk-connector": {
       "enabled": true,
+      "gatewayBaseUrl": "http://localhost:18789", // 可选：如果Gateway地址是TLS/HTTPS，see PR #117
       "clientId": "dingxxxxxxxxx",       // 钉钉 AppKey
       "clientSecret": "your_secret_here", // 钉钉 AppSecret
       "gatewayToken": "",                 // 可选：Gateway 认证 token, openclaw.json配置中 gateway.auth.token 的值 
@@ -97,19 +99,17 @@ openclaw plugins install -l .
       "asyncMode": false,                 // 可选：异步模式，立即回执用户消息，后台处理并推送结果（默认：false）
       "ackText": "🫡 任务已接收"      // 可选：异步模式下的回执消息文本（默认：'🫡 任务已接收，处理中...'）
     }
-  },
-  "gateway": { // gateway通常是已有的节点，配置时注意把http部分追加到已有节点下
-    "http": {
-      "endpoints": {
-        "chatCompletions": {
-          "enabled": true
-        }
-      }
-    }
   }
 }
 ```
 
+执行配置命令
+
+```bash
+openclaw config set gateway.http.endpoints.chatCompletions.enabled true
+```
+
+
 或者在 OpenClaw Dashboard 页面配置：
 
 <img width="1916" height="1996" alt="image" src="https://github.com/user-attachments/assets/00b585ca-c1df-456c-9c65-7345a718b94b" />
@@ -129,21 +129,20 @@ openclaw plugins list  # 确认 dingtalk-connector 已加载
 ## 创建钉钉机器人
 
 1. 打开 [钉钉开放平台](https://open.dingtalk.com/)
-2. 进入 **应用开发** → **企业内部开发** → 创建应用
-3. 添加 **机器人** 能力，消息接收模式选择 **Stream 模式**
-4. 开通权限：
-   - `Card.Streaming.Write` - AI Card 流式响应
-   - `Card.Instance.Write` - AI Card 实例写入
-   - `qyapi_robot_sendmsg` - 主动发送消息
-   - 如需使用文档 API 功能，还需开通文档相关权限
-5. **发布应用**，记录 **AppKey** 和 **AppSecret**
+2. 进入 **应用开发** → **企业内部开发** → 创建openclaw机器人
+   <img width="2529" height="961" alt="image" src="https://github.com/user-attachments/assets/4163dc50-808c-43c2-84bd-a1e8dde42e05" />
+3. 创建好机器人后，保存一下生成的clientId和clientSecret, 后续配置参数需要
+   <img width="687" height="540" alt="image" src="https://github.com/user-attachments/assets/c036ea46-9750-4814-8c24-3e4b54bd2788" />
+
+   或者在机器人详情中 也可以拿到
+   <img width="1527" height="377" alt="image" src="https://github.com/user-attachments/assets/3cf2a661-ed81-441d-9cda-024a6a5377cc" />
 
 ## 配置参考
 
 | 配置项 | 环境变量 | 说明 |
 |--------|----------|------|
-| `clientId` | `DINGTALK_CLIENT_ID` | 钉钉 AppKey |
-| `clientSecret` | `DINGTALK_CLIENT_SECRET` | 钉钉 AppSecret |
+| `clientId` | `DINGTALK_CLIENT_ID` | 上一步创建openclaw机器人给到的 clinetId |
+| `clientSecret` | `DINGTALK_CLIENT_SECRET` | 上一步创建openclaw机器人给到的 clientSecret |
 | `gatewayToken` | `OPENCLAW_GATEWAY_TOKEN` | Gateway 认证 token（可选） |
 | `gatewayPassword` | — | Gateway 认证 password（可选，与 token 二选一） |
 | `sessionTimeout` | — | ⚠️ 已废弃，请使用 Gateway 的 [`session.reset.idleMinutes`](https://docs.openclaw.ai/gateway/configuration) 配置 |
@@ -547,6 +546,39 @@ openclaw plugins install @dingtalk-real-ai/dingtalk-connector
 | `mammoth` | Word 文档（.docx）解析 |
 | `pdf-parse` | PDF 文档解析 |
 
+### Q: Stream 客户端连接 400 错误
+
+日志中出现 `channel exited: Request failed with status code 400`，表示钉钉 Stream 连接失败。
+
+**常见原因：**
+
+| 原因 | 排查方法 |
+|------|----------|
+| **应用未发布** | 钉钉开放平台 → 应用 → 版本管理 → 确认已发布 |
+| **凭证错误** | 检查 `clientId`/`clientSecret` 是否有空格或换行 |
+| **非 Stream 模式** | 确认机器人消息接收模式为 **Stream 模式** |
+| **IP 白名单限制** | 检查应用是否设置了 IP 白名单 |
+
+**排查步骤：**
+
+1. **验证凭证有效性**
+   ```bash
+   curl -X POST "https://api.dingtalk.com/v1.0/oauth2/accessToken" \
+     -H "Content-Type: application/json" \
+     -d '{"appKey": "你的clientId", "appSecret": "你的clientSecret"}'
+   ```
+   - 返回 `accessToken` → 凭证正确
+   - 返回 `400`/`invalid` → 凭证错误或应用未发布
+
+2. **检查应用状态**
+   - 登录 [钉钉开放平台](https://open-dev.dingtalk.com/)
+   - 确认应用已发布（版本管理 → 发布）
+   - 确认机器人已启用且为 Stream 模式
+
+3. **重新发布应用**
+   - 修改任何配置后，必须点击 **保存** → **发布**
+
+
 # 方案二：钉钉 DEAP Agent 集成
 
 通过将钉钉 [DEAP](https://deap.dingtalk.com) Agent 与 [OpenClaw](https://openclaw.ai) Gateway 连接，实现自然语言驱动的本地设备操作能力。
@@ -646,6 +678,9 @@ openclaw gateway start
 
    <img width="3426" height="1752" alt="配置 OpenClaw 技能参数" src="https://github.com/user-attachments/assets/bc725789-382f-41b5-bbdb-ba8f29923d5c" />
 
+注意 OpenClaw 属于一个MCP，还需要配置他的触发规则，满足规则的情况下才会使用这个MCP:
+<img width="1088" height="526" alt="image" src="https://github.com/user-attachments/assets/8b0b6f6d-70ff-4edc-b674-7a24126aadfa" />
+
 4. 发布 Agent：
 
    <img width="3416" height="1762" alt="发布 Agent" src="https://github.com/user-attachments/assets/3f8c3fdb-5f2b-4a4b-8896-35202e713bf3" />

package/docs/RELEASE_NOTES_V0.7.4.md

@@ -1,10 +1,10 @@
 # Release Notes - v0.7.4
 
-## 🎉 会话隔离与记忆管理增强版本 / Session Isolation & Memory Management Enhancement Release
+## 🎉 功能增强版本 / Feature Enhancement Release
 
-本次更新引入了强大的会话隔离和记忆管理功能，支持按单聊、群聊、不同群分别维护独立会话，并提供了灵活的记忆共享配置选项。
+本次更新主要新增了按会话区分 Session 的功能，支持单聊、群聊、不同群分别维护独立会话，并提供了记忆隔离/共享的配置选项，让会话管理更加灵活和精细。
 
-This update introduces powerful session isolation and memory management features, supporting separate sessions for direct chat, group chat, and different groups, with flexible memory sharing configuration options.
+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
 
@@ -16,11 +16,11 @@ Support separate sessions for direct chat, group chat, and different groups; con
 
 **使用场景 / Use Cases**：
 - ✅ 同一机器人在多个群中服务，希望每个群的对话互不干扰  
-  Same bot serving multiple groups, with isolated conversations per group
+  Same bot serves multiple groups, with isolated conversations per group
 - ✅ 用户既在私聊也在群聊中使用机器人，希望私聊与群聊上下文分离  
-  Users using the bot in both DMs and group chats, with separated contexts
-- ✅ 不同群聊之间的对话历史完全隔离  
-  Complete conversation history isolation between different groups
+  Users interact with bot in both DMs and group chats, with separated contexts
+- ✅ 不同群之间的对话历史完全隔离  
+  Complete isolation of conversation history between different groups
 
 **配置方式 / Configuration**：
 ```json5
@@ -35,79 +35,77 @@ Support separate sessions for direct chat, group chat, and different groups; con
 
 **影响范围 / Impact**：  
 默认启用，所有用户自动获得会话隔离能力。如需兼容旧行为（按用户维度维护 session），可设置 `separateSessionByConversation: false`。  
-Enabled by default, all users automatically get session isolation capability. To maintain backward compatibility (user-level sessions), set `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.
+新增 `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.
 
-**使用场景 / Use Cases**：
-- ✅ **记忆隔离**（默认）：不同群聊、群聊与私聊之间的记忆隔离，AI 不会混淆不同场景下的对话历史  
-  **Memory Isolation** (default): Memory isolated between different groups and between DMs and groups, AI won't confuse conversation history across scenarios
-- ✅ **记忆共享**：单 Agent 场景下，同一用户在不同会话间共享记忆，AI 可以记住用户在不同场景下的偏好  
-  **Memory Sharing**: In single-Agent mode, same user shares memory across conversations, AI can remember user preferences across scenarios
+**配置选项 / 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（记忆隔离）
+      "sharedMemoryAcrossConversations": false  // 默认：false
     }
   }
 }
 ```
 
 **影响范围 / Impact**：  
-默认关闭记忆共享，确保不同场景下的记忆隔离。需要跨会话共享记忆的用户可设置 `sharedMemoryAcrossConversations: true`。  
-Memory sharing disabled by default, ensuring memory isolation across scenarios. Users needing cross-conversation memory sharing can set `sharedMemoryAcrossConversations: true`.
+默认关闭，确保不同场景下的记忆隔离。如需跨会话共享记忆，可设置 `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, enabling more precise session management.
+Session key 支持 `group:conversationId` 格式，便于 Gateway 识别群聊场景。  
+Session key supports `group:conversationId` format for Gateway to identify group chat scenarios.
 
 **技术细节 / Technical Details**：
-- 单聊会话：使用 `direct:{senderId}` 格式  
-  Direct chat sessions: Use `direct:{senderId}` format
+- 单聊会话：使用 `direct:{userId}` 格式  
+  Direct chat sessions: Use `direct:{userId}` format
 - 群聊会话：使用 `group:{conversationId}` 格式  
   Group chat sessions: Use `group:{conversationId}` format
-- Gateway 可以根据会话格式自动识别会话类型  
-  Gateway can automatically identify session types based on session format
+- Gateway 可以根据 Session key 格式识别会话类型  
+  Gateway can identify session type based on Session key format
 
 **影响范围 / Impact**：  
-内部实现改进，提升 Gateway 的会话识别能力，用户无需额外配置。  
-Internal implementation improvement, enhances Gateway's session identification capability, no additional configuration required.
+内部实现改进，不影响用户使用，但提高了 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, enabling finer-grained memory control.
+向 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 可以根据用户 ID 管理记忆  
-  Header value is sender ID, Gateway can manage memory based on user ID
-- 支持记忆隔离和共享的灵活配置  
-  Supports flexible configuration for memory isolation and sharing
+- Header 值为发送消息的用户 ID，便于 Gateway 进行记忆归属管理  
+  Header value is the user ID who sent the message, facilitating Gateway's memory ownership management
 
 **影响范围 / Impact**：  
-内部实现改进，增强 Gateway 的记忆管理能力，用户无需额外配置。  
-Internal implementation improvement, enhances Gateway's memory management capability, no additional configuration required.
+内部实现改进，支持 Gateway 侧更精细的记忆管理能力。  
+Internal implementation improvement, supporting Gateway-side fine-grained memory management capabilities.
 
-## 📋 配置说明 / Configuration
+## 📋 配置变更 / Configuration Changes
 
 ### 新增配置项 / New Configuration Options
 
 | 配置项 | 类型 | 默认值 | 说明 |
 |--------|------|--------|------|
 | `separateSessionByConversation` | `boolean` | `true` | 是否按单聊/群聊/群区分 session |
-| `sharedMemoryAcrossConversations` | `boolean` | `false` | 单 Agent 场景下是否在不同会话间共享记忆 |
+| `sharedMemoryAcrossConversations` | `boolean` | `false` | 是否在不同会话间共享记忆 |
 
 ### 配置示例 / Configuration Example
 
@@ -118,10 +116,8 @@ Internal implementation improvement, enhances Gateway's memory management capabi
       "enabled": true,
       "clientId": "dingxxxxxxxxx",
       "clientSecret": "your_secret_here",
-      // 会话隔离配置
-      "separateSessionByConversation": true,  // 按单聊/群聊/群区分 session
-      // 记忆管理配置
-      "sharedMemoryAcrossConversations": false  // 不同会话间记忆隔离
+      "separateSessionByConversation": true,      // 按会话区分 Session
+      "sharedMemoryAcrossConversations": false    // 记忆隔离（默认）
     }
   }
 }
@@ -144,54 +140,42 @@ openclaw plugins install https://github.com/DingTalk-Real-AI/dingtalk-openclaw-c
 
 ### 兼容性说明 / Compatibility Notes
 
-- **向下兼容**：本次更新完全向后兼容，现有配置无需修改即可正常工作  
+- **向下兼容**：本次更新完全向下兼容，现有配置无需修改即可正常工作  
   **Backward Compatible**: This update is fully backward compatible, existing configurations work without modification
-- **默认行为变更**：默认启用 `separateSessionByConversation: true`，会话将按单聊/群聊/群区分  
-  **Default Behavior Change**: `separateSessionByConversation: true` enabled by default, sessions will be separated by direct/group/different groups
-- **推荐升级**：所有用户建议升级到此版本，以获得更好的会话隔离和记忆管理能力  
-  **Recommended Upgrade**: All users are recommended to upgrade to this version for better session isolation and memory management
+- **默认行为变更**：默认启用 `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
 
-如果您希望保持旧的行为（按用户维度维护 session，不区分单聊/群聊），可以设置：
-If you want to maintain old behavior (user-level sessions, no distinction between DMs and group chats), you can set:
-
-```json5
-{
-  "channels": {
-    "dingtalk-connector": {
-      "separateSessionByConversation": false
-    }
-  }
-}
-```
-
-### 行为对比 / Behavior Comparison
-
-| 配置 | 会话隔离策略 | 适用场景 |
-|------|-------------|---------|
-| `separateSessionByConversation: true`（默认） | 按单聊/群聊/群区分 | 多群服务、私聊与群聊分离 |
-| `separateSessionByConversation: false` | 按用户维度维护 | 兼容旧行为，统一用户会话 |
+升级到此版本后：
+After upgrading to this version:
 
-| 配置 | 记忆策略 | 适用场景 |
-|------|---------|---------|
-| `sharedMemoryAcrossConversations: false`（默认） | 记忆隔离 | 不同场景记忆独立 |
-| `sharedMemoryAcrossConversations: true` | 记忆共享 | 跨场景记忆共享 |
+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 格式
-- 所有会话共享相同的记忆空间
-- 无法区分单聊和群聊场景
+- Session key 使用用户 ID：`{userId}`
+- 所有会话共享同一个 Session，不区分单聊/群聊
+- 记忆在所有会话间共享
 
 **变更后 / After**：
-- Session key 支持 `direct:{senderId}` 和 `group:{conversationId}` 格式
-- 支持按会话隔离记忆，或跨会话共享记忆
-- Gateway 可以根据会话格式自动识别会话类型
-- 通过 `X-OpenClaw-Memory-User` header 传递记忆归属用户
+- Session key 支持格式：
+  - 单聊：`direct:{userId}`
+  - 群聊：`group:{conversationId}`
+- 默认按单聊/群聊/群区分 Session
+- 默认记忆隔离，可通过配置共享
 
 ### 相关代码位置 / Related Code Locations
 
@@ -199,10 +183,10 @@ If you want to maintain old behavior (user-level sessions, no distinction betwee
 - `plugin.ts` - 核心逻辑修改
 
 关键变更点：
-- `buildSessionContext` 函数 - 构建标准会话上下文
-- Session key 生成逻辑 - 支持 `direct:` 和 `group:` 前缀
-- Gateway 请求逻辑 - 添加 `X-OpenClaw-Memory-User` header
-- 配置解析逻辑 - 新增 `separateSessionByConversation` 和 `sharedMemoryAcrossConversations` 配置项
+- Session key 生成逻辑
+- `streamFromGateway` 函数中的 Session 处理
+- 记忆用户标识传递
+- 配置项解析和验证
 
 ## 🔗 相关链接 / Related Links