@jeik/dingtalk-connector 0.8.21-fix1

package/docs/RELEASE_NOTES_V0.8.10.md

@@ -0,0 +1,49 @@
+# Release Notes - v0.8.10
+
+## 🎉 新版本亮点 / Highlights
+
+本次更新修复了 **OpenClaw SDK 升级后 Gateway Methods 配置访问失败**的关键问题，并**锁定 axios 版本**以提升依赖稳定性。
+
+This release fixes a **critical Gateway Methods configuration access failure** after OpenClaw SDK upgrade, and **pins the axios version** for improved dependency stability.
+
+## 🐛 修复 / Fixes
+
+- **Gateway Methods 配置访问失败 / Gateway Methods config access failure** ([#397](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/issues/397))  
+  修复 SDK 升级后 `GatewayRequestContext.deps` 类型变更（`CliDeps = { [channelId: string]: unknown }`），导致 `context.deps.config` 为 `undefined`，所有 Gateway RPC 方法（sendToUser、sendToGroup、send、docs.*、status、probe）调用时抛出 `Cannot read properties of undefined (reading 'channels')` 错误。现在通过 SDK 提供的 `loadConfig()` 函数（从 `openclaw/plugin-sdk/config-runtime` 导出）获取完整配置，替代原来的 `context.deps.config` 访问方式。  
+  Fixed `context.deps.config` being `undefined` after SDK upgrade where `GatewayRequestContext.deps` type changed to `CliDeps = { [channelId: string]: unknown }`. All Gateway RPC methods (sendToUser, sendToGroup, send, docs.*, status, probe) threw `Cannot read properties of undefined (reading 'channels')`. Now uses SDK's `loadConfig()` function (exported from `openclaw/plugin-sdk/config-runtime`) to obtain the full configuration.
+
+- **锁定 axios 版本避免兼容性问题 / Pin axios version to prevent compatibility issues** ([#396](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/issues/396))  
+  将 `axios` 依赖从 `^1.6.0` 锁定为 `1.6.0`，避免 npm install 时自动升级到不兼容的新版本导致运行时错误。  
+  Pinned `axios` dependency from `^1.6.0` to `1.6.0` to prevent automatic upgrades to incompatible versions during `npm install`.
+
+## 🔧 内部改进 / Internal Improvements
+
+- **connection.ts 动态 import 优化** - 将 `createLoggerFromConfig` 从静态 import 改为动态 import，避免潜在的循环依赖问题。  
+  **connection.ts dynamic import optimization** - Changed `createLoggerFromConfig` from static to dynamic import to avoid potential circular dependency issues.
+
+- **单元测试适配** - 更新 Gateway Methods 单元测试，mock `openclaw/plugin-sdk/config-runtime` 的 `loadConfig` 函数，替代原来的 `context.deps.config` mock 方式。  
+  **Unit test adaptation** - Updated Gateway Methods unit tests to mock `loadConfig` from `openclaw/plugin-sdk/config-runtime` instead of the deprecated `context.deps.config`.
+
+## 📥 安装升级 / 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.10  
+**兼容性 / Compatibility**：OpenClaw Gateway 0.4.0+

package/docs/RELEASE_NOTES_V0.8.11.md

@@ -0,0 +1,51 @@
+# Release Notes - v0.8.11
+
+## 🎉 新版本亮点 / Highlights
+
+本次更新**升级 Zod 至 v4**，并通过 SDK 的 `buildChannelConfigSchema` 自动生成 `configSchema`，同时**优化依赖结构**大幅减小安装体积。
+
+This release **upgrades Zod to v4** with auto-generated `configSchema` via SDK's `buildChannelConfigSchema`, and **optimizes dependency structure** to significantly reduce installation size.
+
+## ✨ 功能与体验改进 / Features & Improvements
+
+- **升级 Zod v4 + 自动生成 configSchema / Upgrade Zod v4 + auto-generate configSchema**  
+  将 Zod 从 v3 升级至 v4（`zod@^4.3.6`），利用 Zod v4 的 `toJSONSchema()` 能力，通过 SDK 提供的 `buildChannelConfigSchema()` 自动从 Zod Schema 生成 JSON Schema，替代原来手动维护的 `configSchema.schema` 对象，确保配置验证与类型定义始终同步。  
+  Upgraded Zod from v3 to v4 (`zod@^4.3.6`), leveraging Zod v4's `toJSONSchema()` capability to auto-generate JSON Schema via SDK's `buildChannelConfigSchema()`, replacing the manually maintained `configSchema.schema` object to ensure config validation stays in sync with type definitions.
+
+## 📦 依赖优化 / Dependency Optimization
+
+- **openclaw 移至 peerDependencies / Move openclaw to peerDependencies**  
+  将 `openclaw` 从 `dependencies` 移至 `peerDependencies`（标记为 optional），避免插件安装时重复安装宿主框架，大幅减小 `node_modules` 体积。  
+  Moved `openclaw` from `dependencies` to `peerDependencies` (marked as optional), preventing duplicate installation of the host framework and significantly reducing `node_modules` size.
+
+- **ffmpeg 相关包移至 optionalDependencies / Move ffmpeg packages to optionalDependencies**  
+  将 `fluent-ffmpeg`、`@ffmpeg-installer/ffmpeg`、`@ffprobe-installer/ffprobe` 移至 `optionalDependencies`，这些包仅在视频/音频转码场景使用（通过动态 require 加载），安装失败不影响核心功能。  
+  Moved `fluent-ffmpeg`, `@ffmpeg-installer/ffmpeg`, `@ffprobe-installer/ffprobe` to `optionalDependencies`. These packages are only used for video/audio transcoding (loaded via dynamic require) and won't affect core functionality if installation fails.
+
+- **移除未使用的 pako 依赖 / Remove unused pako dependency**  
+  移除了未被任何代码引用的 `pako` 包。  
+  Removed the `pako` package which was not referenced by any code.
+
+## 📥 安装升级 / 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-04-01  
+**版本号 / Version**：v0.8.11  
+**兼容性 / Compatibility**：OpenClaw Gateway 0.4.0+

package/docs/RELEASE_NOTES_V0.8.12.md

@@ -0,0 +1,63 @@
+# Release Notes - v0.8.12
+
+## 🎉 新版本亮点 / Highlights
+
+本次更新**修复了 v0.8.11 安装后启动崩溃的问题**（[#419](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/issues/419)），同时**大幅精简依赖体积**，移除了约 100MB 的非核心依赖，并**清理了无效的代理禁用代码**。
+
+This release **fixes the startup crash after v0.8.11 installation** ([#419](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/issues/419)), **significantly reduces dependency size** by removing ~100MB of non-core dependencies, and **removes ineffective proxy bypass code**.
+
+## 🐛 修复 / Fixes
+
+- **修复 v0.8.11 安装后启动崩溃 / Fix startup crash after v0.8.11 installation** ([#419](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/issues/419))  
+  v0.8.11 将 `mammoth` 和 `pdf-parse` 从 `dependencies` 移至 `optionalDependencies`，但代码中仍使用静态 `import`，导致模块加载阶段立即报错 `Cannot find module 'mammoth'`，插件无法启动。现已改为动态 `import` + 优雅降级：缺失时打印警告并跳过，不影响核心功能。  
+  v0.8.11 moved `mammoth` and `pdf-parse` from `dependencies` to `optionalDependencies`, but the code still used static `import`, causing immediate `Cannot find module 'mammoth'` error at module load time. Now uses dynamic `import` with graceful degradation: prints a warning and skips when missing, without affecting core functionality.
+
+## 📦 依赖优化 / Dependency Optimization
+
+- **移除大体积非核心依赖 / Remove large non-core dependencies**  
+  将 `pdf-parse`（~21MB）、`fluent-ffmpeg`（~12MB）、`@ffmpeg-installer/ffmpeg`（~70MB）、`@ffprobe-installer/ffprobe` 从 `optionalDependencies` 中移除。这些包均已改为动态 `import`，缺失时优雅降级，需要时用户可手动安装。仅保留 `mammoth`（~2MB）在 `optionalDependencies` 中。  
+  Removed `pdf-parse` (~21MB), `fluent-ffmpeg` (~12MB), `@ffmpeg-installer/ffmpeg` (~70MB), `@ffprobe-installer/ffprobe` from `optionalDependencies`. All packages now use dynamic `import` with graceful degradation. Users can manually install them when needed. Only `mammoth` (~2MB) remains in `optionalDependencies`.
+
+## 🧹 代码清理 / Code Cleanup
+
+- **移除无效的代理禁用代码 / Remove ineffective proxy bypass code**  
+  经源码分析，`dingtalk-stream` SDK 的 WebSocket 连接使用 `ws` 库直接建立，不经过 axios 也不受 `axios.defaults.proxy` 影响。之前在 `connection.ts` 中设置 `axios.defaults.proxy = false` 以及 `http-client.ts` 中的 `proxy: getProxyConfig()` 对 WebSocket 连接无效。现已移除 `src/utils/proxy-config.ts` 模块及所有相关代理配置代码。  
+  Source code analysis revealed that `dingtalk-stream` SDK's WebSocket connection uses the `ws` library directly, bypassing axios entirely. The previous `axios.defaults.proxy = false` in `connection.ts` and `proxy: getProxyConfig()` in `http-client.ts` had no effect on WebSocket connections. Removed `src/utils/proxy-config.ts` module and all related proxy configuration code.
+
+## 📥 安装升级 / 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
+```
+
+### 可选依赖手动安装 / Optional Dependencies
+
+```bash
+# Word 文档解析（自动安装，~2MB）
+# mammoth is auto-installed as optionalDependency
+
+# PDF 文档解析（需手动安装）
+npm install pdf-parse
+
+# 视频/音频转码（需手动安装）
+npm install fluent-ffmpeg @ffmpeg-installer/ffmpeg @ffprobe-installer/ffprobe
+```
+
+## 🔗 相关链接 / Related Links
+
+- [Issue #419](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/issues/419)
+- [完整变更日志 / 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-04-01  
+**版本号 / Version**：v0.8.12  
+**兼容性 / Compatibility**：OpenClaw Gateway 0.4.0+

package/docs/RELEASE_NOTES_V0.8.13-beta.0.md

@@ -0,0 +1,69 @@
+# Release Notes - v0.8.13-beta.0
+
+## 🎉 新版本亮点 / Highlights
+
+本次更新修复了**多账号凭据解析错误**（SecretInput 对象未展开导致发送失败）、**连接错误无法被正确捕获**（async 回调中 throw 无效），以及**消息路由支持 `group:`/`user:` 前缀**，同时兼容 pdf-parse v1/v2 双版本 API，并修复了 QPS 限流后立即重试的问题。
+
+This release fixes **multi-account credential resolution** (SecretInput objects not unwrapped before sending), **connection errors not propagating correctly** (throw inside async callbacks replaced with reject), and adds **`group:`/`user:` prefix support in message routing**, along with pdf-parse v1/v2 compatibility and a QPS throttle retry fix.
+
+## 🐛 修复 / Fixes
+
+- **修复多账号场景下发送消息时凭据未解析 / Fix unresolved credentials in sendText/sendMedia**  
+  `sendText` 和 `sendMedia` 在多账号模式下，`clientId`/`clientSecret` 可能为 `SecretInput` 对象或 `undefined`，导致 API 请求携带无效凭据。现已在调用前用 `resolveDingtalkAccount` 返回的已解析值覆盖原始 config。  
+  In multi-account mode, `clientId`/`clientSecret` could be `SecretInput` objects or `undefined`, causing API requests with invalid credentials. Now the resolved values from `resolveDingtalkAccount` are used to override the raw config.
+
+- **修复连接错误在 async 回调中无法传播 / Fix connection errors not propagating in async callback**  
+  `connection.ts` 的错误处理在 async 回调内使用 `throw` 抛出错误，但错误无法被外层 Promise 捕获，导致 400/401 等连接失败被静默忽略。已改为 `reject(new Error(...))` 确保错误正确传播。  
+  Error handlers in `connection.ts` used `throw` inside async callbacks, making errors uncatchable by the outer Promise. Changed to `reject(new Error(...))` to ensure proper error propagation for 400/401 and other connection failures.
+
+- **修复 QPS 限流后立即重试导致再次触发限流 / Fix QPS rate limit immediate retry**  
+  收到 403 QpsLimit 响应后，`lastUpdateTime` 未更新，导致下一次节流检查立即放行并再次触发限流。现已在跳过更新时同步 `lastUpdateTime`。  
+  After receiving a 403 QpsLimit response, `lastUpdateTime` was not updated, causing the throttle check to immediately allow the next attempt. Now `lastUpdateTime` is synced when skipping an update.
+
+- **修复 `resolveAllowFrom` 全局过滤误拦截群消息 / Fix resolveAllowFrom global filter incorrectly blocking group messages**  
+  框架层使用 `resolveAllowFrom` 对所有消息（含群消息）做全局发送者过滤，但 `allowFrom` 原意只用于私聊白名单。群消息有独立的 `groupAllowFrom` 字段控制，由 `message-handler.ts` 内部处理。现已将 `resolveAllowFrom` 改为返回空列表，禁用框架层全局过滤。  
+  The framework used `resolveAllowFrom` to filter all incoming messages (including group messages), but `allowFrom` was intended only for DM whitelisting. Group messages have a separate `groupAllowFrom` field handled internally by `message-handler.ts`. Now returns `[]` to disable framework-level global filtering.
+
+## ✨ 功能改进 / Improvements
+
+- **消息路由支持 `group:`/`user:` 前缀 / Message routing supports `group:`/`user:` prefix targets**  
+  `sendTextToDingTalk` 和 `sendMediaToDingTalk` 新增对 `group:<openConversationId>` 和 `user:<userId>` 格式的目标解析，与 `gateway-methods.ts` 中的逻辑保持一致，兼容旧版裸 `cid` 前缀格式。  
+  `sendTextToDingTalk` and `sendMediaToDingTalk` now support `group:<openConversationId>` and `user:<userId>` prefixed targets, consistent with `gateway-methods.ts` logic, while maintaining backward compatibility with bare `cid`-prefixed targets.
+
+- **兼容 pdf-parse v1 和 v2 API / Support both pdf-parse v1 and v2 API**  
+  `parsePdfFile` 现在自动检测 pdf-parse 模块导出格式：v2.x 使用 `PDFParse` 类（class API），v1.x 使用 `default` 函数，均可正确解析 PDF 文件。  
+  `parsePdfFile` now auto-detects the pdf-parse export format: v2.x uses the `PDFParse` class API, v1.x uses the `default` function — both are handled correctly.
+
+- **将 `enableMediaUpload`/`systemPrompt` 移至共享配置 / Move `enableMediaUpload`/`systemPrompt` to shared config shape**  
+  这两个字段现在位于 `DingtalkSharedConfigShape`，在多账号模式下每个账号可独立配置，而不是只能在顶层配置。  
+  These fields are now in `DingtalkSharedConfigShape`, allowing per-account configuration in multi-account mode instead of only top-level.
+
+## 📝 文档 / Documentation
+
+- **优化 README 安装验证说明 / Improve README plugin verification instructions**  
+  移除了版本号硬编码（`v0.8.6`），改为通用版本占位符，并新增"如果没看到 `loaded`"的警示提示，避免用户在插件未正确加载时继续配置步骤。  
+  Removed hardcoded version number (`v0.8.6`), replaced with generic version placeholder, and added a warning for when `loaded` is not shown to prevent users from proceeding with configuration before the plugin is properly loaded.
+
+## 📥 安装升级 / Installation & Upgrade
+
+```bash
+# 安装 beta 版本 / Install beta version
+openclaw plugins install @dingtalk-real-ai/dingtalk-connector@0.8.13-beta.0
+
+# 或升级现有版本 / 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#v0.8.13
+```
+
+## 🔗 相关链接 / 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-04-06  
+**版本号 / Version**：v0.8.13-beta.0  
+**兼容性 / Compatibility**：OpenClaw Gateway 0.4.0+

package/docs/RELEASE_NOTES_V0.8.13.md

@@ -0,0 +1,62 @@
+# Release Notes - v0.8.13
+
+## 🎉 新版本亮点 / Highlights
+
+本次更新聚焦**媒体发送可靠性**和**多账号稳定性**：修复了文件发送时 mediaId 格式不一致导致静默失败的问题，修复了多账号凭据解析错误、连接错误无法传播、QPS 限流重试等多个关键 Bug，同时新增 `group:`/`user:` 前缀路由支持。
+
+This release focuses on **media sending reliability** and **multi-account stability**: fixes silent file sending failures caused by inconsistent mediaId format, resolves multi-account credential resolution errors, connection error propagation, QPS throttle retry issues, and adds `group:`/`user:` prefix routing support.
+
+## 🐛 修复 / Fixes
+
+- **修复文件发送时 mediaId 格式不一致导致静默失败 / Fix inconsistent mediaId format causing silent file send failure**  
+  `sendFileProactive` 在不同调用点传入了 `cleanMediaId`（不带 `@`）和 `mediaId`（带 `@`），经实测钉钉 API 统一要求带 `@` 前缀的 `mediaId`。同时修复了 `sendFileMessage`/`sendFileProactive` 的 catch 块吞掉异常导致外层误报成功的问题。  
+  `sendFileProactive` was called with `cleanMediaId` (without `@`) in some places and `mediaId` (with `@`) in others. Testing confirmed DingTalk API requires the `@`-prefixed `mediaId`. Also fixed catch blocks swallowing errors, causing false success reports.
+
+- **修复多账号场景下凭据未解析 / Fix unresolved credentials in multi-account mode**  
+  `sendText`/`sendMedia` 在多账号模式下 `clientId`/`clientSecret` 可能为 `SecretInput` 对象，导致 API 请求携带无效凭据。现已用 `resolveDingtalkAccount` 返回的已解析值覆盖。  
+  In multi-account mode, credentials could be `SecretInput` objects; now resolved values are used.
+
+- **修复连接错误在 async 回调中无法传播 / Fix connection errors not propagating**  
+  `connection.ts` 错误处理使用 `throw` 抛出，但在 async 回调内无法被外层 Promise 捕获。改为 `reject(new Error(...))` 确保 400/401 等错误正确传播。  
+  Changed `throw` to `reject()` inside async error handlers for proper error propagation.
+
+- **修复 QPS 限流后立即重试 / Fix QPS rate limit immediate retry**  
+  收到 403 QpsLimit 后未更新 `lastUpdateTime`，导致节流检查立即放行。现已同步更新。  
+  `lastUpdateTime` is now synced when skipping a QPS-limited update.
+
+- **修复 `resolveAllowFrom` 全局过滤误拦截群消息 / Fix resolveAllowFrom blocking group messages**  
+  `allowFrom` 仅用于私聊白名单，群消息由 `groupAllowFrom` 在内部处理。将 `resolveAllowFrom` 改为返回空列表，禁用框架层全局过滤。  
+  Returns `[]` to disable framework-level filtering; internal policy checks handle DM and group separately.
+
+## ✨ 功能改进 / Improvements
+
+- **消息路由支持 `group:`/`user:` 前缀 / Message routing supports `group:`/`user:` prefix targets**  
+  `sendTextToDingTalk` 和 `sendMediaToDingTalk` 新增 `group:<id>` 和 `user:<id>` 格式解析，兼容旧版裸 `cid` 前缀。  
+  Now supports `group:<id>` and `user:<id>` prefixed targets, backward compatible with bare `cid` prefix.
+
+- **兼容 pdf-parse v1/v2 API、共享配置字段扩展 / pdf-parse v1/v2 compatibility & shared config fields**  
+  `parsePdfFile` 自动检测 pdf-parse 导出格式；`enableMediaUpload`/`systemPrompt` 移至共享配置，支持多账号独立配置。  
+  Auto-detects pdf-parse export format; `enableMediaUpload`/`systemPrompt` now configurable per-account.
+
+- **新增出站路由测试 / Add outbound routing tests**  
+  新增 `outbound-routing.test.ts`，覆盖 `group:`/`user:` 前缀解析和消息路由场景。  
+  Added `outbound-routing.test.ts` covering prefix parsing and message routing scenarios.
+
+## 📥 安装升级 / Installation & Upgrade
+
+```bash
+openclaw plugins install @dingtalk-real-ai/dingtalk-connector
+openclaw plugins update dingtalk-connector
+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-04-08  
+**版本号 / Version**：v0.8.13  
+**兼容性 / Compatibility**：OpenClaw Gateway 0.4.0+

package/docs/RELEASE_NOTES_V0.8.14.md

@@ -0,0 +1,86 @@
+# Release Notes - v0.8.15
+
+## 🎉 新版本亮点 / Highlights
+
+本次更新带来**一键扫码安装**体验：用户只需执行一条 `npx` 命令，通过钉钉扫码即可自动完成机器人创建、凭证获取、插件安装和配置写入，实现零手动配置。同时全面重写了 README 文档，新增手动配置指南和故障排查文档。
+
+This release introduces a **one-click QR install** experience: users run a single `npx` command, scan with DingTalk to automatically create a bot, obtain credentials, install the plugin, and write config — zero manual configuration. Also includes a complete README overhaul and new manual setup and troubleshooting guides.
+
+## ✨ 新功能 / New Features
+
+- **一键扫码安装 / One-click QR install**  
+  新增 `npx -y @dingtalk-real-ai/dingtalk-connector install` 命令，通过钉钉扫码一键完成：机器人创建 → 凭证获取 → 插件安装 → 配置写入 → 重启提示。  
+  Added `npx` CLI command for one-click DingTalk bot setup via QR scan: bot creation → credential acquisition → plugin install → config write → restart guidance.
+
+- **Device Authorization Flow**  
+  新增 `device-auth.ts` 模块，实现钉钉 Device Flow 授权（init → begin → poll），支持 QR 码终端渲染（`qrcode-terminal`）、2 分钟瞬时错误重试窗口。  
+  New `device-auth.ts` module implementing DingTalk Device Flow (init → begin → poll) with terminal QR rendering and 2-minute transient error retry window.
+
+- **Onboarding 扫码授权集成 / Onboarding QR auth integration**  
+  `onboarding.ts` 配置向导首选一键扫码授权，失败时自动降级为手动输入 Client ID / Client Secret。  
+  Setup wizard now prefers one-click QR authorization, with automatic fallback to manual credential input on failure.
+
+- **CLI 凭证暂存与恢复 / Credential staging & recovery**  
+  当插件安装失败时，凭证保存到独立的 `.dingtalk-staging.json`，避免污染 `openclaw.json`；下次运行安装成功后自动恢复凭证并清理暂存文件。  
+  Credentials saved to separate staging file on plugin install failure to avoid config pollution; auto-recovered on next successful install.
+
+- **CLI 安装前自动清理 / Pre-install cleanup**  
+  安装前自动删除旧版插件目录（`~/.openclaw/extensions/dingtalk-connector`），清理 `openclaw.json` 中的过期 channel/plugin/allow 配置，避免 "unknown channel id" 等验证错误。  
+  Auto-removes old plugin directory and stale config entries before install to prevent validation errors.
+
+- **CLI 429 限流重试 / Rate limit retry**  
+  插件安装遇到 ClawHub 429 限流时，使用 `Atomics.wait` 同步等待（15s/30s）后重试，最多 3 次。  
+  Plugin install retries up to 3 times with synchronous backoff (15s/30s) on ClawHub 429 rate limiting.
+
+## ✅ 改进 / Improvements
+
+- **Prerelease 版本自动识别 / Prerelease version auto-detection**  
+  CLI `install` 命令自动检测当前 package 是否为 prerelease 版本（alpha/beta/rc/canary），若是则传递精确版本号给 `openclaw plugins install`。  
+  CLI auto-detects prerelease versions and passes exact version spec to `openclaw plugins install`.
+
+- **手动配置文档拆分 / Manual setup docs separation**  
+  手动创建机器人和手动配置流程从 README 拆分到独立的 `docs/DINGTALK_MANUAL_SETUP.md`，README 精简为快速入门。  
+  Manual bot creation and config steps extracted to `docs/DINGTALK_MANUAL_SETUP.md`.
+
+- **README 全面重写 / README overhaul**  
+  参考飞书 OpenClaw 插件风格重写中英文 README，精简结构，突出核心功能，常见问题迁移到独立文档。  
+  Rewrote Chinese and English README following Lark plugin style, streamlined structure.
+
+- **GitHub 索引优化 / GitHub index optimization**  
+  新增 `.gitattributes` 排除 `coverage/` 和 `docs/` 的语言统计；优化 `package.json` keywords、description、openclaw channel 元数据；`openclaw.plugin.json` 移除冗余字段。  
+  Added `.gitattributes` for language detection; optimized package metadata; cleaned plugin manifest.
+
+## 📝 文档 / Documentation
+
+- 新增 `docs/DINGTALK_MANUAL_SETUP.md` — 完整的手动创建机器人和配置 OpenClaw 流程
+- 新增 `docs/TROUBLESHOOTING.md` — 常见问题排查（机器人不回复、配置校验、HTTP 401/400、安装失败、国内网络等）
+- Added `docs/DINGTALK_MANUAL_SETUP.md` — Complete manual bot creation and OpenClaw config guide
+- Added `docs/TROUBLESHOOTING.md` — Troubleshooting guide for common issues
+
+## 📥 安装升级 / Installation & Upgrade
+
+```bash
+# 一键扫码安装（推荐）/ One-click QR install (recommended)
+npx -y @dingtalk-real-ai/dingtalk-connector install
+
+# 从 npm 安装 / Install from npm
+openclaw plugins install @dingtalk-real-ai/dingtalk-connector
+
+# 更新 / Update
+openclaw plugins update dingtalk-connector
+
+# 从 GitHub 安装 / Install from GitHub
+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)
+- [故障排查 / Troubleshooting](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/blob/main/docs/TROUBLESHOOTING.md)
+
+---
+
+**发布日期 / Release Date**：2026-04-15  
+**版本号 / Version**：v0.8.15  
+**兼容性 / Compatibility**：OpenClaw ≥ 2026.4.9

package/docs/RELEASE_NOTES_V0.8.16.md

@@ -0,0 +1,40 @@
+# Release Notes - v0.8.15-beta.1
+
+## 🎉 新版本亮点 / Highlights
+
+本次 beta 版本主要修复 AI Card 流式更新频繁触发钉钉 QPS 限流的问题，通过引入全局令牌桶限流器，确保多会话并发时不超过钉钉 API 速率限制。
+
+This beta release fixes frequent DingTalk QPS rate limiting during AI Card streaming updates by introducing a global token bucket rate limiter that enforces API rate limits across all concurrent sessions.
+
+## 🐛 修复 / Fixes
+
+- **AI Card 流式更新 QPS 限流 / AI Card streaming QPS rate limiting**  
+  新增全局令牌桶限流器（`cardRateLimiter`），所有会话共享同一速率限制（20 QPS），避免多会话并发时总 QPS 叠加超过钉钉 API 限制（~40 次/秒）。遇到 403 QpsLimit 错误时自动退避 2 秒后重试一次，确保 finalize 等关键更新不丢失。  
+  Added global token bucket rate limiter (`cardRateLimiter`) shared across all sessions (20 QPS cap). Automatically backs off for 2 seconds and retries once on 403 QpsLimit errors, ensuring critical updates like finalize are not lost.
+
+- **streamAICard null card 崩溃 / streamAICard null card crash**  
+  修复 `createAICardForTarget` 创建失败返回 `null` 后，调用方通过 `as any` 绕过类型检查传入 `streamAICard`，导致 `Cannot read properties of null (reading 'tokenExpireTime')` 崩溃的问题。现在 `streamAICard` 入口添加了 null 守卫，安全跳过并打印警告日志。  
+  Fixed crash when `createAICardForTarget` returns `null` and callers bypass type checking with `as any`. Added null guard at `streamAICard` entry point.
+
+## ✅ 改进 / Improvements
+
+- **单实例节流间隔优化 / Per-instance throttle interval optimization**  
+  `reply-dispatcher.ts` 中的 `updateInterval` 从 500ms 增大到 800ms，配合全局限流器降低单实例发送频率，减少不必要的 API 调用。  
+  Increased `updateInterval` from 500ms to 800ms in `reply-dispatcher.ts` to complement the global rate limiter and reduce unnecessary API calls.
+
+## 📥 安装升级 / Installation & Upgrade
+
+```bash
+openclaw plugins install @dingtalk-real-ai/dingtalk-connector@0.8.15-beta.1
+```
+
+## 🔗 相关链接 / 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-04-16  
+**版本号 / Version**：v0.8.16 
+**兼容性 / Compatibility**：OpenClaw Gateway 0.4.0+

package/docs/RELEASE_NOTES_V0.8.17.md

@@ -0,0 +1,87 @@
+# Release Notes - v0.8.17
+
+## 🎉 新版本亮点 / Highlights
+
+本次版本最大亮点是 **钉钉 DWS CLI 集成** 和 **Agent Skills 体系**，让钉钉机器人不仅能聊天，还能直接操作 AI 表格、日历、通讯录、待办、审批等钉钉产品能力。同时引入 `tsdown` 预编译构建，提升插件启动速度和兼容性。
+
+The highlight of this release is **DingTalk Workspace (DWS) CLI integration** and the **Agent Skills system**, enabling the bot to not only chat but also directly operate DingTalk products like AI Table, Calendar, Contacts, Todo, Approval, and more. Additionally, `tsdown` pre-compiled build is introduced for faster startup and better compatibility.
+
+## ✨ 新增 / Added
+
+- **钉钉 DWS CLI 集成 / DWS CLI Integration**  
+  安装插件时自动安装 `dws` CLI 工具，支持 AI 表格、日历、通讯录、群聊与机器人、待办、审批、考勤、日志等钉钉产品能力。凭证自动注入，无需手动配置。可通过 `--skip-dws` 参数跳过。  
+  Auto-installs `dws` CLI during plugin setup, enabling AI Table, Calendar, Contacts, Chat & Bot, Todo, Approval, Attendance, Report and more. Credentials injected automatically. Use `--skip-dws` to skip.
+
+- **Agent Skills 体系 / Agent Skills System**  
+  新增三组内置 Skill 文档，通过 `openclaw.plugin.json` 注册，Agent 可自动引用：  
+  - `dingtalk-channel-rules` — 频道能力路由规范，明确 Connector 与 DWS 的职责边界  
+  - `dingtalk-troubleshoot` — 常见问题排查指南  
+  - `dws-cli` — DWS CLI 使用指南与产品参考（含 AI 表格、日历、通讯录等 9 个产品文档）  
+  
+  Added three built-in Skill document sets registered via `openclaw.plugin.json`:
+  - `dingtalk-channel-rules` — Channel capability routing, Connector vs DWS responsibility boundary  
+  - `dingtalk-troubleshoot` — Troubleshooting guide  
+  - `dws-cli` — DWS CLI guide with 9 product reference docs (AI Table, Calendar, Contacts, etc.)
+
+## 🐛 修复 / Fixes
+
+- **AI Card finishAICard QPS 限流 / finishAICard QPS rate limiting**  
+  `finishAICard` 的 PUT 请求现在也经过全局令牌桶限流器 `waitForToken()`，避免多会话并发结束时触发 403 QpsLimit。  
+  `finishAICard` PUT request now goes through global token bucket to prevent 403 QpsLimit on concurrent finishes.
+
+- **Probe 接口迁移到统一 HTTP 客户端 / Probe migrated to HTTP client**  
+  `probe.ts` 中的 token 获取和 bot 信息查询从 `fetch` 迁移到统一的 `dingtalkHttp` 客户端，修复潜在的代理和错误处理不一致问题。  
+  Token and bot info requests migrated from `fetch` to unified `dingtalkHttp` client.
+
+- **安全扫描误报规避 / Security scanner false positive avoidance**  
+  重构环境变量和 fetch 访问方式，避免 OpenClaw 安全扫描将合法凭证读取误报为 "credential harvesting"。  
+  Refactored env and fetch access to avoid OpenClaw security scanner false positives.
+
+- **DWS 凭证隔离 / DWS credential isolation**  
+  DWS clientId/clientSecret 存储在模块作用域私有 holder 中，不注入 `process.env`，防止子进程泄露凭证。  
+  DWS credentials stored in module-scoped holder instead of `process.env`, preventing leaks via child processes.
+
+## ✅ 改进 / Improvements
+
+- **预编译构建 (tsdown) / Pre-compiled build**  
+  引入 `tsdown` 构建工具，插件发布为预编译的 `dist/index.mjs`，替代 jiti 运行时 TS 加载，提升启动速度和兼容性。  
+  Plugin now ships pre-compiled via `tsdown` instead of relying on jiti runtime TS loading.
+
+- **Channel ID 常量化 / Channel ID as constant**  
+  提取 `CHANNEL_ID = "dingtalk-connector"` 为模块级常量，消除全代码库硬编码字符串。  
+  Extracted `CHANNEL_ID` as module-level constant, eliminating hardcoded strings.
+
+- **CLI 安装流程增强 / CLI install flow enhancement**  
+  新增 `--skip-dws` 参数跳过 DWS CLI 安装；安装成功后提示网关初始化需约 3 分钟。  
+  Added `--skip-dws` flag; post-install message mentions ~3 min gateway warm-up.
+
+- **依赖版本锁定 / Dependency version pinning**  
+  `form-data`、`qrcode-terminal`、`zod` 从 `^` 范围锁定为精确版本；`openclaw` peerDependency 改为 `>=2026.3.23`。  
+  Pinned `form-data`, `qrcode-terminal`, `zod` to exact versions; `openclaw` peer changed to `>=2026.3.23`.
+
+- **npm 发包优化 / npm publish optimization**  
+  新增 `prepack`/`postpack` 脚本在发包时自动剥离 `devDependencies`，减小安装体积；`files` 列表新增 `dist/` 和 `skills/`。  
+  Added `prepack`/`postpack` scripts to strip `devDependencies` during publish.
+
+## 📥 安装升级 / Installation & Upgrade
+
+```bash
+npx -y @dingtalk-real-ai/dingtalk-connector@0.8.17 install
+```
+
+或手动安装：
+```bash
+openclaw plugins install @dingtalk-real-ai/dingtalk-connector
+```
+
+## 🔗 相关链接 / 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)
+- [多 Agent 协作 / Multi-Agent Collaboration](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/blob/main/docs/MULTI_AGENT_COLLABORATION.md)
+
+---
+
+**发布日期 / Release Date**：2026-04-16  
+**版本号 / Version**：v0.8.17  
+**兼容性 / Compatibility**：OpenClaw Gateway 2026.3.23+

package/docs/RELEASE_NOTES_V0.8.18.md

@@ -0,0 +1,64 @@
+# Release Notes - v0.8.18
+
+## 🎉 新版本亮点 / Highlights
+
+本次版本聚焦 **流式中断故障恢复** 和 **多 Agent 安装保护**。新增 `fixStuckCards` Gateway Method 解决 Gateway 重启后 AI Card 卡住和表情残留问题；安装向导增加多 Agent 配置检测，防止已有路由配置被意外覆盖。
+
+This release focuses on **streaming interruption recovery** and **multi-Agent install protection**. Added `fixStuckCards` Gateway Method to fix stuck AI Cards and lingering emotion tags after gateway restart; install wizard now detects existing multi-Agent config to prevent accidental overwrite.
+
+## 🐛 修复 / Fixes
+
+- **AI Card 流式中断残留修复 (#463) / AI Card stuck state fix**
+  Gateway 重启导致流式响应中断时，AI Card 停留在"思考中"动画、用户消息上的🤔表情标签未自动撤回。新增 `dingtalk-connector.fixStuckCards` Gateway Method，支持手动修复卡住的 AI Card 和/或撤回残留表情。
+  When streaming is interrupted by gateway restart, AI Card stays in "thinking" animation and 🤔 emotion tag is not auto-recalled. Added `dingtalk-connector.fixStuckCards` Gateway Method for manual recovery.
+
+  ```typescript
+  // 修复卡住的 AI Card
+  await gateway.call('dingtalk-connector.fixStuckCards', {
+    cardInstanceId: 'card_1713600000000_abc12345',
+    content: '（回复中断，请重新提问）'
+  });
+
+  // 撤回残留的🤔表情
+  await gateway.call('dingtalk-connector.fixStuckCards', {
+    msgId: 'msgXXX',
+    conversationId: 'cidXXX'
+  });
+  ```
+
+- **多 Agent 配置覆盖保护 / Multi-Agent config overwrite protection**
+  安装向导检测到 `openclaw.json` 中已有钉钉 channels + bindings 配置（多 Agent 场景）时，**跳过自动写入**，展示本次选择的机器人凭证信息，让用户自行决定是否修改配置。避免多 Agent 路由被意外覆盖。
+  Install wizard detects existing DingTalk channels + bindings config (multi-Agent scenario), skips auto-write, and displays credentials for user to decide. Prevents accidental multi-Agent routing breakage.
+
+## ✅ 改进 / Improvements
+
+- **OpenClaw 版本兼容性 / OpenClaw version compatibility**
+  `peerDependency` 从 `>=2026.3.23` 升级到 `>=2026.4.9`，兼容 OpenClaw 2026.4.15 中的 plugin-sdk 变更。
+  `peerDependency` bumped from `>=2026.3.23` to `>=2026.4.9`, compatible with OpenClaw 2026.4.15 plugin-sdk changes.
+
+- **README 能力展示优化 / README capability display**
+  已支持的业务能力（待办任务、AI 表格、日历日程）从独立区块整合到主能力表格，Coming Soon 区域同步更新。
+  Supported business capabilities (Todo, AI Table, Calendar) consolidated into main capability table; Coming Soon section updated.
+
+## 📥 安装升级 / Installation & Upgrade
+
+```bash
+npx openclaw@latest add @dingtalk-real-ai/dingtalk-connector
+```
+
+或指定版本：
+```bash
+npx openclaw@latest add @dingtalk-real-ai/dingtalk-connector@0.8.18
+```
+
+## 🔗 相关链接 / 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)
+- [故障排查 / Troubleshooting](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/blob/main/docs/TROUBLESHOOTING.md)
+
+---
+
+**发布日期 / Release Date**：2026-04-21
+**版本号 / Version**：v0.8.18
+**兼容性 / Compatibility**：OpenClaw Gateway 2026.4.9+