@jeik/dingtalk-connector 0.8.21-fix1

package/docs/RELEASE_NOTES_V0.8.19.md

@@ -0,0 +1,62 @@
+# Release Notes - v0.8.19
+
+## 🎉 新版本亮点 / Highlights
+
+本次版本新增 **DING 消息** 和 **钉钉文档** 两大能力，并新增 **多 Agent 配置文档**（`MULTI_AGENT_SETUP.md`），帮助用户快速完成多 Agent 部署。
+
+This release adds **DING messaging** and **DingTalk Document** capabilities, and includes a new **Multi-Agent setup guide** (`MULTI_AGENT_SETUP.md`) for quick multi-Agent deployment.
+
+## ✨ 新增 / Added
+
+- **🔔 DING 消息 / DING Messaging**
+  支持向用户/群发送强提醒 DING（应用内/短信/电话），用户授权后即可使用。
+  Send urgent DING reminders (in-app / SMS / phone call) to users or groups; available after user authorization.
+
+- **📄 钉钉文档 / DingTalk Document**
+  支持创建、追加、搜索、列举钉钉文档，用户授权后即可使用。
+  Create, append, search, and list DingTalk documents; available after user authorization.
+
+- **📝 日志 / Reports**
+  支持提交日报/周报、查询历史日志记录，用户授权后即可使用。
+  Submit daily/weekly reports and query historical logs; available after user authorization.
+
+- **插件重复加载检测 / Duplicate plugin load detection**
+  全局 Symbol 自检同一 plugin id 多路径加载，防止 stream 回调冲突。
+  Detects duplicate plugin loads via global Symbol, preventing stream callback conflicts.
+
+## 🐛 修复 / Fixes
+
+- AI Card QPS 限流不再误报用户错误，改为 warn 日志 / QPS throttle no longer sends error to user
+- AI Card 令牌桶新增串行化锁，修复并发击穿 / Token bucket serialization lock fixes concurrency bypass
+- 多 Agent 配置检测改为 OR 条件，放宽触发保护 / Multi-Agent detection relaxed to OR condition
+- CLI 提示文案统一中英文混合 / CLI prompts unified to bilingual format
+
+## ✅ 改进 / Improvements
+
+- 新增多 Agent 配置文档 `docs/MULTI_AGENT_SETUP.md` / Added multi-Agent setup guide `docs/MULTI_AGENT_SETUP.md`
+- DWS CLI 升级提示 / DWS CLI upgrade prompt during install
+- 消息上下文透传 `BotChatbotUserId` / `BotChatbotCorpId` / BotIdentity context passthrough
+- reply-dispatcher 支持 text/markdown 降级发送 + 裸别名检测 / text/markdown fallback with bare alias detection
+
+## 📥 安装升级 / Installation & Upgrade
+
+```bash
+npx openclaw@latest add @dingtalk-real-ai/dingtalk-connector
+```
+
+或指定版本：
+```bash
+npx openclaw@latest add @dingtalk-real-ai/dingtalk-connector@0.8.19
+```
+
+## 🔗 相关链接 / Related Links
+
+- [完整变更日志](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/blob/main/CHANGELOG.md)
+- [使用文档](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/blob/main/README.md)
+- [故障排查](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/blob/main/docs/TROUBLESHOOTING.md)
+
+---
+
+**发布日期 / Release Date**：2026-04-25
+**版本号 / Version**：v0.8.19
+**兼容性 / Compatibility**：OpenClaw Gateway 2026.4.9+

package/docs/RELEASE_NOTES_V0.8.2.md

@@ -0,0 +1,55 @@
+# Release Notes - v0.8.2
+
+## 🎉 新版本亮点 / Highlights
+
+本次更新聚焦于多账号场景下的稳定性与正确性：修复了多账号配置时重复建立连接的问题，优化了 WebSocket 连接管理机制，并改进了消息处理逻辑，使长连接场景下的整体可靠性显著提升。
+
+This release focuses on stability and correctness in multi-account scenarios: it fixes duplicate connection creation when multiple accounts are configured, improves WebSocket connection management, and refines message processing logic for significantly better reliability in long-lived connection scenarios.
+
+## 🐛 修复 / Fixes
+
+- **多账号重复启动问题 / Multi-account Duplicate Startup**  
+  修复了配置多个钉钉账号时，`enabled: false` 的账号仍会建立 WebSocket 连接的问题。现在插件会在启动时正确检查账号的 `enabled` 状态，禁用账号将保持 pending 状态直到 Gateway 停止，不再建立任何连接。  
+  Fixed an issue where accounts with `enabled: false` would still establish WebSocket connections when multiple DingTalk accounts were configured. The plugin now correctly checks the `enabled` state at startup; disabled accounts remain in a pending state until the Gateway stops and no longer create any connections.
+
+- **相同 clientId 账号去重 / Duplicate clientId Deduplication**  
+  修复了多个账号配置相同 `clientId` 时会建立重复连接的问题。通过静态配置分析，同一 `clientId` 只有列表中排在最前面的启用账号才会建立连接，后续重复账号会被自动跳过并记录日志。  
+  Fixed an issue where multiple accounts sharing the same `clientId` would create duplicate connections. Using static configuration analysis, only the first enabled account with a given `clientId` in the list will establish a connection; subsequent duplicates are automatically skipped and logged.
+
+## ✨ 功能与体验改进 / Features & Improvements
+
+- **Onboarding 配置向导优化 / Onboarding Configuration Wizard Improvement**  
+  改进了钉钉连接器的配置引导逻辑：调整了凭据输入顺序（先 Client ID 后 Client Secret），优化了引导文案，使配置流程更清晰易懂。  
+  Improved the DingTalk connector onboarding wizard: adjusted credential input order (Client ID first, then Client Secret), and refined the guidance text for a clearer and more intuitive setup experience.
+
+- **会话 Key 构成遵循 OpenClaw 规范 / Session Key Follows OpenClaw Convention**  
+  会话上下文（sessionKey）的构成现在严格遵循 OpenClaw 标准规则，通过 `channel`、`accountId`、`chatType`、`peerId` 等字段组合唯一标识会话，并支持 `sharedMemoryAcrossConversations` 配置实现跨会话记忆共享。  
+  The session context (sessionKey) now strictly follows OpenClaw conventions, uniquely identifying sessions via `channel`, `accountId`, `chatType`, and `peerId` fields. Also 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.
+
+## 📥 安装升级 / 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-22  
+**版本号 / Version**：v0.8.2  
+**兼容性 / Compatibility**：OpenClaw Gateway 0.4.0+

package/docs/RELEASE_NOTES_V0.8.20.md

@@ -0,0 +1,49 @@
+# Release Notes - v0.8.20
+
+## 🎉 新版本亮点 / Highlights
+
+本次版本聚焦 **OpenClaw 兼容性修复** 和 **DWS CLI 版本管理优化**。修复了插件安装到 `~/.openclaw/extensions/` 时因 ESM 裸说明符解析导致的加载崩溃（Issue #527），并重构了 DWS CLI 的版本升级/降级策略，提升安装体验。
+
+This release focuses on **OpenClaw compatibility fixes** and **DWS CLI version management improvements**. Fixes a plugin load crash caused by ESM bare specifier resolution when installed to `~/.openclaw/extensions/` (Issue #527), and refactors DWS CLI upgrade/downgrade logic for a smoother install experience.
+
+## 🐛 修复 / Fixes
+
+- **OpenClaw 插件加载兼容性 (Issue #527) / Plugin load compatibility**
+  `configSchema` 改为延迟初始化，通过 `createRequire` 解析 `openclaw/plugin-sdk/core`，修复插件安装到 `~/.openclaw/extensions/` 时 ESM 裸说明符解析失败导致的 "Cannot find package 'openclaw'" 崩溃。
+  `configSchema` deferred to lazy init via `createRequire`, fixing "Cannot find package 'openclaw'" crash when plugin is installed to `~/.openclaw/extensions/`.
+
+- **Onboarding 动态导入 / Dynamic import for onboarding**
+  `promptSingleChannelSecretInput` 从静态 import 改为动态 `import()`，避免在 ESM 加载阶段触发同样的裸说明符解析错误。
+  `promptSingleChannelSecretInput` switched from static to dynamic `import()` to avoid bare specifier resolution error during ESM loading.
+
+## ✅ 改进 / Improvements
+
+- **DWS CLI 版本管理重构 / Version management refactor**
+  `ensureDwsCli()` 新增 `compareVersions()` 语义版本比较，支持四种场景：
+  - 目标版本更高 → 自动升级 / Auto-upgrade when target is newer
+  - 本地版本更高 → 询问是否覆盖 / Prompt before downgrade
+  - 版本一致 → 跳过 / Skip when equal
+  - 全新安装 → 显示已安装版本号 / Show version on fresh install
+
+## 📥 安装升级 / Installation & Upgrade
+
+```bash
+npx openclaw@latest add @dingtalk-real-ai/dingtalk-connector
+```
+
+或指定版本：
+```bash
+npx openclaw@latest add @dingtalk-real-ai/dingtalk-connector@0.8.20
+```
+
+## 🔗 相关链接 / Related Links
+
+- [完整变更日志](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/blob/main/CHANGELOG.md)
+- [使用文档](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/blob/main/README.md)
+- [故障排查](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/blob/main/docs/TROUBLESHOOTING.md)
+
+---
+
+**发布日期 / Release Date**：2026-04-28
+**版本号 / Version**：v0.8.20
+**兼容性 / Compatibility**：OpenClaw Gateway 2026.4.9+

package/docs/RELEASE_NOTES_V0.8.3.md

@@ -0,0 +1,63 @@
+# Release Notes - v0.8.3
+
+## 🎉 新版本亮点 / Highlights
+
+本次更新修复了五个问题并带来一项体验改进：与 OpenClaw Gateway 新版本（2026.3.22+）的兼容性问题、多 Agent 路由在 `sharedMemoryAcrossConversations` 配置下的路由错误、发送图片时的异常问题、发送人昵称和群名称未正确传递给 AI 的问题，以及 AI 卡片流式更新（progressive updates）失效的问题；同时优化了消息队列繁忙时的用户体验。
+
+This release fixes five issues and brings one UX improvement: a compatibility issue with newer OpenClaw Gateway versions (2026.3.22+), incorrect multi-Agent routing when `sharedMemoryAcrossConversations` is enabled, an image sending failure, sender nickname and group name not being correctly passed to the AI, and AI card progressive updates not working; plus an improved experience when the message queue is busy.
+
+## 🐛 修复 / Fixes
+
+- **兼容 OpenClaw Gateway 新版本 / Compatible with Newer OpenClaw Gateway Versions**  
+  修复在 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+）均兼容。  
+  Fixed an error `ERR_PACKAGE_PATH_NOT_EXPORTED: Package subpath './plugin-sdk/compat' is not defined by "exports"` when installing the plugin under OpenClaw Gateway 2026.3.22+. The root cause was `src/runtime.ts` importing from the `openclaw/plugin-sdk/compat` sub-path which was removed in newer SDK versions. Now imports from the `openclaw/plugin-sdk` main entry, compatible with all versions (2026.3.1+).
+
+- **AI 卡片流式更新延迟 / AI Card Progressive Updates Delayed**  
+  优化了 AI 卡片流式更新的响应速度。改动前，`onReplyStart` 中 `await startStreaming()` 串行等待 AI Card 创建完成（约 500ms~1s），期间收到的 partial reply 全部被丢弃，Card 创建好之后才开始流式更新；同时节流间隔 1000ms 过于保守，对于 2 秒内完成的短回复几乎跳过所有中间更新。改动后，AI Card 创建改为 fire-and-forget 模式与 AI 生成并行，`onPartialReply` 到来时等待 Card 就绪后立即更新，节流间隔调整为 500ms，流式内容能更早、更频繁地呈现给用户。  
+  Improved AI card progressive update responsiveness. Previously, `await startStreaming()` in `onReplyStart` waited serially for AI Card creation (~500ms–1s), discarding all partial replies received during that window; additionally, the 1000ms throttle interval was too conservative, skipping nearly all intermediate updates for short replies. After the fix, AI Card creation runs in fire-and-forget mode in parallel with AI generation; `onPartialReply` waits for the card to be ready and then updates immediately, with the throttle interval reduced to 500ms for earlier and more frequent streaming updates.
+
+- **消息重复处理（钉钉服务端重发穿透）/ Duplicate Message Processing on DingTalk Server Resend**  
+  修复了 AI 处理耗时超过 ~60 秒时，钉钉服务端重发消息导致 Bot 重复处理的问题。根因是去重逻辑仅使用 `headers.messageId`（WebSocket 协议层投递 ID，每次重发都是新值），未检查 `data.msgId`（业务层消息 ID，重发时保持不变），导致重发消息穿透去重缓存。修复后引入双层去重：协议层（`headers.messageId`）拦截同一次投递的重复回调，业务层（`data.msgId`）拦截服务端重发，两个 ID 同时标记，任意一个命中即可拦截。  
+  Fixed an issue where DingTalk server resent messages (triggered when AI processing exceeds ~60 seconds) caused the Bot to process the same message twice. The root cause was that deduplication only checked `headers.messageId` (WebSocket protocol-layer delivery ID, which changes on every resend), ignoring `data.msgId` (business-layer message ID, which stays the same on resend). After the fix, a two-layer deduplication is applied: protocol-layer (`headers.messageId`) blocks duplicate callbacks from the same delivery, and business-layer (`data.msgId`) blocks server resends. Both IDs are marked simultaneously so either one can trigger deduplication.
+
+- **多 Agent 路由与 sharedMemoryAcrossConversations 冲突 / Multi-Agent Routing Conflict with sharedMemoryAcrossConversations**  
+  修复了配置 `sharedMemoryAcrossConversations: true` 时，多群分配不同 Agent 的 bindings 全部路由到同一个 Agent 的问题。根因是路由匹配错误地使用了 `sessionPeerId`（已被覆盖为 `accountId`）而非真实的 peer 标识。修复后，路由匹配使用专用的 `peerId` 字段（不受会话隔离配置影响），session 构建使用 `sessionPeerId`，两者职责严格分离。  
+  Fixed an issue where all bindings routing different groups to different Agents would resolve to the same Agent when `sharedMemoryAcrossConversations: true` was configured. The root cause was that routing matched against `sessionPeerId` (overridden to `accountId`) instead of the real peer identifier. After the fix, routing uses the dedicated `peerId` field (unaffected by session isolation config), while session construction uses `sessionPeerId`, with strict separation of responsibilities.
+
+- **发送图片失败 / Image Sending Failure**  
+  修复了发送图片时出现异常的问题。([#316](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/issues/316))  
+  Fixed an issue where sending images would fail with an error. ([#316](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/issues/316))
+
+- **发送人昵称与群名称未正确传递给 AI / Sender Nickname and Group Name Not Passed to AI**  
+  修复了会话上下文中 `SenderName` 字段错误传入用户 ID（而非昵称）、`GroupSubject` 字段错误传入群 ID（而非群名称）的问题。修复后，AI 能正确获取发送人的钉钉昵称和所在群的名称，有助于 AI 更好地理解对话场景。  
+  Fixed an issue where the `SenderName` field in the session context was incorrectly set to the user ID instead of the display name, and `GroupSubject` was set to the group ID instead of the group title. After the fix, the AI correctly receives the sender's DingTalk nickname and the group name, enabling better contextual understanding.
+
+## ✨ 功能与体验改进 / Features & Improvements
+
+- **消息队列繁忙时的即时排队反馈 / Instant Queue Acknowledgement When Busy**  
+  当用户快速连续发送消息、上一条仍在处理中时，新消息现在会立即弹出一条 AI Card 气泡，显示"上一条还没结束，这条我已经记下，稍后按顺序继续处理"等提示文案，同时贴上"思考中"表情，让用户第一时间知道消息已被接收并排队。等轮到该消息处理时，这条气泡会**原地更新**为最终回复内容，不会额外多发一条消息。  
+  When a user sends messages in quick succession while the previous one is still being processed, the new message now immediately shows an AI Card bubble with a queuing acknowledgement (e.g. "Still working on the last one, I've noted this down and will continue in order"), along with a "thinking" emoji reaction. When it's the message's turn to be processed, the same bubble is **updated in place** with the final reply — no extra message is sent.
+
+## 📥 安装升级 / 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-23  
+**版本号 / Version**：v0.8.3  
+**兼容性 / Compatibility**：OpenClaw Gateway 0.4.0+

package/docs/RELEASE_NOTES_V0.8.4.md

@@ -0,0 +1,45 @@
+# Release Notes - v0.8.4
+
+## 🎉 新版本亮点 / Highlights
+
+v0.8.4 是一个兼容性修复版本，核心解决了插件在旧版 OpenClaw Gateway 上无法加载的问题。通过将 `createPluginRuntimeStore` 内联实现，插件现在可以在任意版本的 OpenClaw 上正常运行，无需担心版本兼容性。
+
+v0.8.4 is a compatibility fix release that resolves plugin loading failures on older OpenClaw Gateway versions. By inlining the `createPluginRuntimeStore` implementation, the plugin now works correctly on any version of OpenClaw without version compatibility concerns.
+
+## 🐛 修复 / Fixes
+
+- **兼容旧版 OpenClaw Gateway（createPluginRuntimeStore 缺失）/ Compatible with older OpenClaw Gateway (missing createPluginRuntimeStore)**  
+  修复在旧版 OpenClaw Gateway 上加载插件时报错 `TypeError: (0 , _pluginSdk.createPluginRuntimeStore) is not a function` 的问题。根因是 `src/runtime.ts` 直接从 `openclaw/plugin-sdk` 导入 `createPluginRuntimeStore`，而该函数在旧版 SDK 中并不存在。现已将其替换为内联实现的 `createRuntimeStore`，功能完全等价，不再依赖 SDK 版本。  
+  Fixed `TypeError: (0 , _pluginSdk.createPluginRuntimeStore) is not a function` when loading the plugin on older OpenClaw Gateway versions. Root cause: `src/runtime.ts` imported `createPluginRuntimeStore` directly from `openclaw/plugin-sdk`, which doesn't exist in older SDK versions. Replaced with an inline `createRuntimeStore` implementation that is fully equivalent and no longer depends on SDK version.
+
+- **openclaw 依赖版本约束放宽 / Relaxed openclaw dependency version constraint**  
+  将 `package.json` 中的 `"openclaw": "^2026.3.0"` 改为 `"openclaw": "*"`。openclaw 由框架环境提供，插件不应限制其版本范围，避免版本约束导致安装失败或与用户已安装版本冲突。  
+  Changed `"openclaw": "^2026.3.0"` to `"openclaw": "*"` in `package.json`. Since openclaw is provided by the framework environment, the plugin should not restrict its version range to avoid installation failures or conflicts with the user's installed version.
+
+- **群聊消息处理崩溃 / Group chat message processing crash**  
+  修复群聊时报错 `TypeError: Cannot read properties of undefined (reading 'config')` 导致 Agent 无法回复的问题。根因是 `src/policy.ts` 中 `resolveDingtalkGroupToolPolicy` 函数的参数签名与 OpenClaw SDK 的 `ChannelGroupContext` 接口不匹配——函数期望接收 `account: ResolvedDingtalkAccount`，但框架实际传入的是 `{ cfg, groupId, accountId, ... }`，导致 `account` 为 `undefined`。现已修正参数签名，内部通过 `resolveDingtalkAccount()` 正确获取账号信息。单聊不受影响（该函数仅在群聊场景下被框架调用）。  
+  Fixed `TypeError: Cannot read properties of undefined (reading 'config')` crash in group chats that prevented the Agent from replying. Root cause: `resolveDingtalkGroupToolPolicy` in `src/policy.ts` had a parameter signature mismatch with the OpenClaw SDK's `ChannelGroupContext` interface — the function expected `account: ResolvedDingtalkAccount`, but the framework passes `{ cfg, groupId, accountId, ... }`, leaving `account` as `undefined`. Fixed by correcting the parameter signature and resolving the account internally via `resolveDingtalkAccount()`. Direct messages were unaffected (this function is only called by the framework in group chat scenarios).
+
+## 📥 安装升级 / 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-24  
+**版本号 / Version**：v0.8.4  
+**兼容性 / Compatibility**：OpenClaw Gateway 所有版本 / All versions

package/docs/RELEASE_NOTES_V0.8.7.md

@@ -0,0 +1,49 @@
+# Release Notes - v0.8.7
+
+## 🎉 新版本亮点 / Highlights
+
+本次更新专注于**账号配置兼容性**与**网络代理控制**两大核心问题的修复。修复了驼峰命名账号 ID（如 `zhizaoDashuIP`）因大小写规范化导致配置查找失败的问题，同时统一了 WebSocket 连接与媒体下载的代理控制逻辑，确保 `DINGTALK_FORCE_PROXY` 环境变量在所有网络请求中生效一致。
+
+This release focuses on two critical fixes: **account configuration compatibility** and **network proxy control**. It resolves an issue where camelCase account IDs (e.g., `zhizaoDashuIP`) failed to match their configurations due to forced lowercasing, and unifies proxy control logic across WebSocket connections and media downloads so that the `DINGTALK_FORCE_PROXY` environment variable is consistently respected.
+
+## 🐛 修复 / Fixes
+
+- **账号 ID 大小写敏感修复 / Account ID case-sensitivity fix**  
+  修复 `normalizeAccountId` 函数强制将账号 ID 转为小写（`.toLowerCase()`）导致驼峰命名账号（如 `zhizaoDashuIP`）无法匹配配置的问题。现在账号 ID 仅做 `trim()` 处理，保留原始大小写，与配置文件中的 key 严格匹配。  
+  Fixed `normalizeAccountId` forcibly lowercasing account IDs (`.toLowerCase()`), which caused camelCase account IDs (e.g., `zhizaoDashuIP`) to fail configuration lookup. Account IDs are now only trimmed, preserving original casing for strict matching against config keys.
+
+- **WebSocket 连接代理控制统一 / Unified proxy control for WebSocket connections**  
+  修复 `src/core/connection.ts` 中 WebSocket 连接未遵循 `DINGTALK_FORCE_PROXY` 环境变量的问题，现在与 HTTP 请求保持一致的代理控制逻辑。  
+  Fixed WebSocket connections in `src/core/connection.ts` not respecting the `DINGTALK_FORCE_PROXY` environment variable; proxy control is now consistent with HTTP requests.
+
+- **媒体下载代理控制统一 / Unified proxy control for media downloads**  
+  修复 `src/core/message-handler.ts` 中图片/文件下载时代理配置与 HTTP 客户端不一致的问题，确保所有媒体下载请求统一遵循代理控制策略。  
+  Fixed inconsistent proxy configuration for image/file downloads in `src/core/message-handler.ts`; all media download requests now follow the unified proxy control policy.
+
+- **多账号消息去重误判修复 / Multi-account message deduplication false positive fix**  
+  修复多账号（多机器人）场景下，同一条群消息 @多个机器人时，第二个机器人因消息去重缓存未按账号隔离，误将自己收到的消息判定为重复而跳过处理的问题。现在 `checkAndMarkDingtalkMessage` 的去重 key 带有 `accountId` 前缀，不同机器人账号的去重缓存完全隔离。  
+  Fixed a false positive in multi-account (multi-bot) scenarios where a group message mentioning multiple bots caused the second bot to incorrectly skip processing, because the deduplication cache was not scoped per account. The deduplication key in `checkAndMarkDingtalkMessage` now includes an `accountId` prefix, fully isolating each bot's deduplication cache.
+
+## 📥 安装升级 / 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-26  
+**版本号 / Version**：v0.8.7  
+**兼容性 / Compatibility**：OpenClaw Gateway 0.4.0+

package/docs/RELEASE_NOTES_V0.8.8.md

@@ -0,0 +1,63 @@
+# Release Notes - v0.8.8
+
+## 🎉 新版本亮点 / Highlights
+
+本次更新专注于**流式响应稳定性**、**Web UI 状态显示**和**媒体发送正确性**三大核心问题的修复。重构了 AI Card 并发创建逻辑，彻底解决多 block 响应产生多条独立气泡的问题；修复了 Web UI 中 Connected / Last inbound 字段始终显示 n/a 的问题；同时修正了文件发送时参数传递错误导致发送失败的 bug。
+
+This release focuses on three core fixes: **streaming response stability**, **Web UI status display**, and **media sending correctness**. It refactors the AI Card concurrent creation logic to eliminate the multi-bubble issue in multi-block responses, fixes the Web UI showing n/a for Connected/Last inbound fields, and corrects a parameter error that caused file sending to fail.
+
+## 🐛 修复 / Fixes
+
+- **多 block 流式响应产生多条独立气泡 / Multi-block streaming response creates multiple bubbles** ([#369](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/issues/369))  
+  重构 `startStreaming` 的并发控制逻辑，从 `isCreatingCard` 布尔标志改为 `cardCreationPromise`，`await startStreaming()` 天然等待创建完成，彻底消除多 block 响应场景下每个 block 新建独立 AI Card 气泡的问题。  
+  Refactored `startStreaming` concurrency control from a boolean `isCreatingCard` flag to a `cardCreationPromise`. `await startStreaming()` naturally waits for creation to complete, eliminating the issue where each block in a multi-block response created an independent AI Card bubble.
+
+- **Web UI Connected / Last inbound 显示 n/a / Web UI shows n/a for Connected and Last inbound**  
+  在 `src/core/connection.ts` 中新增 `onStatusChange` 回调，在连接建立、断开、收到消息时分别上报 `connected`、`lastConnectedAt`、`lastInboundAt` 字段；同时补全 `buildSessionContext` 在 `separateSessionByConversation: false` 分支中 `conversationId` 和 `groupSubject` 字段的透传。  
+  Added `onStatusChange` callback in `src/core/connection.ts` to report `connected`, `lastConnectedAt`, and `lastInboundAt` fields on connection established, disconnected, and message received events. Also fixed `buildSessionContext` to correctly pass through `conversationId` and `groupSubject` fields in the `separateSessionByConversation: false` branch.
+
+- **AI Card 函数调用参数错误 / AI Card function call parameter error**  
+  修复 `src/reply-dispatcher.ts` 中 `createAICardForTarget`、`streamAICard`、`finishAICard` 的第三个参数从 `params.runtime` 改为 `account.config as DingtalkConfig`，第四个参数补充 `log`，确保函数签名与实现一致。  
+  Fixed the third parameter of `createAICardForTarget`, `streamAICard`, and `finishAICard` in `src/reply-dispatcher.ts` from `params.runtime` to `account.config as DingtalkConfig`, and added `log` as the fourth parameter to match the function signatures.
+
+- **sendFileProactive 参数错误导致文件发送失败 / File sending failure due to wrong sendFileProactive parameter**  
+  修复 `src/services/media.ts` 中 `processFileMarkers` 和 `processRawMediaPaths` 调用 `sendFileProactive` 时错误地传入 `uploadResult.downloadUrl`，现已改为正确的 `uploadResult.cleanMediaId`，确保主动 API 模式下文件消息能正常发送。  
+  Fixed `processFileMarkers` and `processRawMediaPaths` in `src/services/media.ts` incorrectly passing `uploadResult.downloadUrl` to `sendFileProactive`; now correctly uses `uploadResult.cleanMediaId` to ensure file messages are sent successfully in proactive API mode.
+
+- **纯多账号配置下 probe 被跳过 / Probe skipped in pure multi-account config** ([#381](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/issues/381))  
+  修复 `src/onboarding.ts` 的 `getStatus()` 中，纯多账号配置（credentials 仅在 `accounts.*` 下）时 probe 被静默跳过，状态永远显示 "configured (connection not verified)" 的问题。现已改用 `resolveDingtalkAccount()` 统一获取账号信息。  
+  Fixed `getStatus()` in `src/onboarding.ts` silently skipping probe in pure multi-account configs (credentials only under `accounts.*`), causing status to always show "configured (connection not verified)". Now uses `resolveDingtalkAccount()` for unified account resolution.
+
+## ✨ 改进 / Improvements
+
+- **音频时长提取安全性改进 / Audio duration extraction security improvement** ([#134](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/issues/134))  
+  将 `extractAudioDuration` 从直接调用 `child_process.exec` 改为使用 `fluent-ffmpeg` 的 `ffprobe` API，与 `extractVideoMetadata` 保持一致，消除安全扫描误报。  
+  Changed `extractAudioDuration` from directly calling `child_process.exec` to using `fluent-ffmpeg`'s `ffprobe` API, consistent with `extractVideoMetadata`, eliminating false positives in security scans.
+
+- **SDK 接口迁移 / SDK interface migration**  
+  将 `src/onboarding.ts` 中的类型引用从旧版 `ChannelOnboardingAdapter` 迁移到新版 `ChannelSetupWizardAdapter`，并将 `promptSingleChannelSecretInput` 的导入路径从 `openclaw/plugin-sdk` 更新为 `openclaw/plugin-sdk/setup`，适配最新 SDK 接口。  
+  Migrated type references in `src/onboarding.ts` from the legacy `ChannelOnboardingAdapter` to the new `ChannelSetupWizardAdapter`, and updated the import path of `promptSingleChannelSecretInput` from `openclaw/plugin-sdk` to `openclaw/plugin-sdk/setup` to align with the latest SDK interface.
+
+## 📥 安装升级 / 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-29  
+**版本号 / Version**：v0.8.8  
+**兼容性 / Compatibility**：OpenClaw Gateway 0.4.0+

package/docs/RELEASE_NOTES_V0.8.9.md

@@ -0,0 +1,81 @@
+# Release Notes - v0.8.9
+
+## 🎉 新版本亮点 / Highlights
+
+本次更新带来**引用消息完整解析**、**macOS LaunchAgent 兼容性修复**和**多项稳定性改进**。消息处理层新增对引用消息（reply）的递归解析，支持提取引用中的文本、媒体附件和链接；修复了 macOS LaunchAgent 环境下因无效文件描述符导致 WebSocket 连接失败的问题；同时修复了 AI Card 流式关闭的竞争条件、FormData CJS 互操作问题，并锁定 axios 版本以提升依赖稳定性。
+
+This release introduces **quoted message parsing**, **macOS LaunchAgent compatibility**, and **multiple stability improvements**. The message handler now recursively parses quoted (reply) messages, extracting text, media attachments, and URLs. A fix for invalid file descriptors (EBADF) on macOS LaunchAgent environments prevents WebSocket connection failures. Additionally, the AI Card streaming close race condition is fixed, FormData CJS interop issues are resolved, and axios is pinned to v1.6.0 for dependency stability.
+
+## ✨ 功能与体验改进 / Features & Improvements
+
+- **引用消息完整解析 / Quoted message full parsing**  
+  新增 `extractQuotedMsgText` 递归解析引用消息（最多 3 层嵌套），支持 text、richText、picture、video、audio、file、markdown、interactiveCard 等消息类型。引用消息中的媒体附件（图片/视频/音频/文件）会被自动提取并传递给下游处理。引用了含链接的文本消息时，链接会被提取用于 URL 路由（如 alidocs 文档链接）。  
+  Added `extractQuotedMsgText` for recursive quoted message parsing (up to 3 levels), supporting text, richText, picture, video, audio, file, markdown, and interactiveCard message types. Media attachments in quoted messages are automatically extracted and passed downstream. URLs from quoted text messages are extracted for URL routing (e.g., alidocs document links).
+
+- **新增配置项 / New configuration options**  
+  `configSchema` 新增 `asyncMode`、`ackText`、`endpoint`、`debug` 四个配置字段，为异步消息处理和自定义端点提供灵活配置能力。  
+  Added `asyncMode`, `ackText`, `endpoint`, `debug` to `configSchema`, enabling flexible configuration for async message processing and custom endpoints.
+
+- **普通消息本地图片后处理 / Local image post-processing for normal messages**  
+  `sendNormalToUser` 和 `sendNormalToGroup` 新增本地图片上传后处理，发送普通消息时自动将 Markdown 中的本地图片路径上传到钉钉并替换为 media_id，与 AI Card 消息行为保持一致。  
+  Added local image upload post-processing to `sendNormalToUser` and `sendNormalToGroup`, automatically uploading local image paths in Markdown to DingTalk and replacing them with media_id, consistent with AI Card message behavior.
+
+## 🐛 修复 / Fixes
+
+- **macOS LaunchAgent 环境 WebSocket 连接失败 / WebSocket connection failure on macOS LaunchAgent**  
+  修复 macOS LaunchAgent/daemon 环境下，进程启动时 stdin/stdout/stderr（fd 0/1/2）无效（EBADF），导致 Node.js 创建 TCP 连接时出现 EBADF 错误。启动前检测并将无效 fd 重定向到 `/dev/null`。  
+  Fixed EBADF errors when creating TCP connections on macOS LaunchAgent/daemon environments where stdin/stdout/stderr (fd 0/1/2) are invalid at process startup. Invalid file descriptors are now detected and redirected to `/dev/null`.
+
+- **AI Card 流式关闭竞争条件 / AI Card streaming close race condition**  
+  修复 `closeStreaming` 可能被 `onIdle` 和 `onError` 同时触发时的竞争条件。现在在函数开头立即捕获并清空 `currentCardTarget`（snapshot 模式），防止并发调用导致 `finishAICard` 收到 null 参数而崩溃。  
+  Fixed a race condition where `closeStreaming` could be triggered simultaneously by `onIdle` and `onError`. Now captures and clears `currentCardTarget` at function entry (snapshot pattern), preventing concurrent calls from passing null to `finishAICard`.
+
+- **FormData CJS 互操作问题 / FormData CJS interop issue**  
+  将 `form-data` 从动态 `import()` 改为静态 `import`，修复 jiti/ESM 环境下动态导入 CJS 模块时 `.default` 偶发为 `undefined` 导致 `Cannot read properties of undefined (reading 'registry')` 错误的问题。  
+  Changed `form-data` from dynamic `import()` to static `import`, fixing intermittent `Cannot read properties of undefined (reading 'registry')` errors caused by `.default` being `undefined` when dynamically importing CJS modules in jiti/ESM environments.
+
+- **纯文本图片路径误转换 / Bare image path false conversion**  
+  禁用纯文本中本地图片路径的自动转换为图片语法的行为。此前纯文本中出现的本地路径（如 `/path/to/image.png`）会被自动包裹为 `![](mediaId)`，影响用户只想展示路径文本的场景。  
+  Disabled automatic conversion of bare local image paths in plain text to image syntax. Previously, local paths like `/path/to/image.png` in plain text were automatically wrapped as `![](mediaId)`, which was undesirable when users intended to display the path as text.
+
+## 🔧 内部改进 / Internal Improvements
+
+- **Zod Schema 拆分兼容 Web UI / Zod Schema split for Web UI compatibility**  
+  将 `DingtalkConfigSchema` 拆分为 `DingtalkConfigBaseSchema`（纯 ZodObject）和带 `superRefine` 的完整 Schema，解决 `superRefine` 将 Schema 转为 `ZodEffects` 后无法用于 `buildChannelConfigSchema` 生成 JSON Schema 的问题。  
+  Split `DingtalkConfigSchema` into `DingtalkConfigBaseSchema` (pure ZodObject) and the full schema with `superRefine`, fixing incompatibility with `buildChannelConfigSchema` JSON Schema generation.
+
+- **configSchema 类型简化 / configSchema type simplification**  
+  将 `clientId`、`clientSecret`、`allowFrom`、`groupAllowFrom` 等字段的 JSON Schema 从 `oneOf` 联合类型简化为单一 `string` 类型，移除不再需要的 `secretInputJsonSchema`，降低配置复杂度。  
+  Simplified JSON Schema for `clientId`, `clientSecret`, `allowFrom`, `groupAllowFrom` from `oneOf` union types to single `string` type, removing the no-longer-needed `secretInputJsonSchema`.
+
+- **reply-dispatcher logger 统一 / reply-dispatcher logger unification**  
+  将 `reply-dispatcher.ts` 中手动构建的 log 对象替换为 `createLoggerFromConfig`，与项目其他模块的日志规范保持一致。  
+  Replaced manually constructed log object in `reply-dispatcher.ts` with `createLoggerFromConfig`, aligning with the project's logging conventions.
+
+- **锁定 axios 版本 / Pin axios version**  
+  将 `axios` 依赖从 `^1.6.0` 锁定为 `1.6.0`，避免自动升级引入不兼容变更。  
+  Pinned `axios` dependency from `^1.6.0` to `1.6.0` to prevent automatic upgrades from introducing incompatible changes.
+
+## 📥 安装升级 / 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-31  
+**版本号 / Version**：v0.8.9  
+**兼容性 / Compatibility**：OpenClaw Gateway 0.4.0+