@dingtalk-real-ai/dingtalk-connector 0.8.12 → 0.8.13

package/docs/RELEASE_NOTES_V0.7.6.md

@@ -0,0 +1,219 @@
+# Release Notes - v0.7.6
+
+## 🔧 修复版本 / Bug Fix Release
+
+本次更新修复了 Gateway 端口连接和新会话命令的问题，确保配置中的 Gateway 端口能够正确生效，并修复了新会话命令未真正清理会话的 bug。
+
+This update fixes Gateway port connection and new session command issues, ensuring that the Gateway port configured in settings takes effect correctly, and fixes the bug where new session commands did not actually clear sessions.
+
+## 🐛 修复 / Fixes
+
+### Gateway 端口连接修复 / Gateway Port Connection Fix
+
+**问题描述 / Issue Description**：  
+当用户在配置中指定了 Gateway 端口（`gateway.port`）后，连接器仍然使用运行时检测到的端口，导致无法连接到正确配置的 Gateway 端口。  
+When users specify Gateway port (`gateway.port`) in configuration, the connector still uses the runtime-detected port, causing connection failures to the correctly configured Gateway port.
+
+**修复内容 / Fix**：
+- 在 `streamFromGateway` 函数中添加 `gatewayPort` 参数支持  
+  Added `gatewayPort` parameter support in `streamFromGateway` function
+- 优先使用配置中的 `gateway.port`，其次使用运行时检测的端口，最后使用默认端口 18789  
+  Prioritize `gateway.port` from configuration, then use runtime-detected port, finally fallback to default port 18789
+- 在所有调用 `streamFromGateway` 的地方传递配置的端口信息  
+  Pass configured port information in all `streamFromGateway` calls
+
+**技术实现 / Technical Implementation**：
+```typescript
+// 修复前 / Before
+const gatewayUrl = `http://127.0.0.1:${rt.gateway?.port || 18789}/v1/chat/completions`;
+
+// 修复后 / After
+const port = gatewayPort || rt.gateway?.port || 18789;
+const gatewayUrl = `http://127.0.0.1:${port}/v1/chat/completions`;
+```
+
+**影响范围 / Impact**：  
+影响所有在配置中指定了 `gateway.port` 的用户。修复后，配置的 Gateway 端口将正确生效，连接器能够连接到正确配置的 Gateway 实例。  
+Affects all users who specified `gateway.port` in configuration. After the fix, the configured Gateway port will take effect correctly, and the connector can connect to the correctly configured Gateway instance.
+
+### 2. 新会话命令修复 / New Session Command Fix
+
+**问题描述 / Issue Description**：  
+钉钉 Connector 之前在本地通过 `isNewSessionCommand` 拦截 `/new`、`/reset`、`/clear`、`新会话` 等指令，命中后由插件直接回复固定文案「✨ 已开启新会话，之前的对话已清空。」并提前 return，不再往 Gateway 发送消息。实际上 Connector 本身并没有真正清理会话上下文，也没有触发 Gateway 的 `session.reset`，导致用户以为会话已清空，但后续对话仍然带着旧上下文继续。  
+Previously, DingTalk Connector intercepted commands like `/new`, `/reset`, `/clear`, `新会话` locally via `isNewSessionCommand`. When matched, the plugin directly replied with a fixed message "✨ 已开启新会话，之前的对话已清空。" and returned early without sending messages to Gateway. In reality, the Connector did not actually clear session context or trigger Gateway's `session.reset`, causing users to think the session was cleared while subsequent conversations still carried old context.
+
+**修复内容 / Fix**：
+- 新增 `normalizeSlashCommand` 工具方法，将 `/new`、`/reset`、`/clear`、`新会话`、`重新开始`、`清空对话` 等别名统一归一为标准指令 `/new`  
+  Added `normalizeSlashCommand` utility method to normalize aliases like `/new`, `/reset`, `/clear`, `新会话`, `重新开始`, `清空对话` to standard command `/new`
+- 在构造 `userContent` 时，先对文本部分调用 `normalizeSlashCommand`，再将结果连同图片、本地文件内容一并发送给 Gateway  
+  When constructing `userContent`, first call `normalizeSlashCommand` on text, then send the result along with images and local file content to Gateway
+- 删除 `handleDingTalkMessage` 中原有的"本地拦截 + 假提示"逻辑（`forceNewSession` 判断 + 直接回复「已开启新会话」并提前 return），不再在 Connector 层吞掉命令  
+  Removed the original "local interception + fake prompt" logic in `handleDingTalkMessage` (`forceNewSession` check + direct reply "已开启新会话" and early return), commands are no longer swallowed at Connector layer
+
+**行为变化 / Behavior Changes**：
+- **修复前**：用户发送新会话类命令时，Connector 直接回复固定文案并提前 return，会话实际上未被清理  
+  **Before**: When users sent new session commands, Connector directly replied with fixed message and returned early, session was not actually cleared
+- **修复后**：用户发送新会话类命令时，消息会以 `/new` 的形式完整透传到 Gateway，由 Gateway 统一决定是否重置会话以及返回何种提示文案，从而真正清理会话  
+  **After**: When users send new session commands, messages are forwarded to Gateway in `/new` format, Gateway decides whether to reset session and what prompt to return, truly clearing the session
+
+**影响范围 / Impact**：  
+影响所有使用新会话命令的用户。修复后，新会话命令将真正清理会话上下文，确保后续对话从全新状态开始。  
+Affects all users who use new session commands. After the fix, new session commands will truly clear session context, ensuring subsequent conversations start from a fresh state.
+
+## 📋 技术细节 / Technical Details
+
+### 内部实现变更 / Internal Implementation Changes
+
+#### Gateway 端口连接修复 / Gateway Port Connection Fix
+
+**变更前 / Before**：
+- `streamFromGateway` 函数仅使用运行时检测的端口 `rt.gateway?.port`
+- 配置中的 `gateway.port` 被忽略
+- 修改 Gateway 端口后需要重启才能生效
+
+**变更后 / After**：
+- `GatewayOptions` 接口新增 `gatewayPort?: number` 可选参数
+- `streamFromGateway` 函数优先使用传入的 `gatewayPort` 参数
+- 端口优先级：`gatewayPort` > `rt.gateway?.port` > `18789`（默认）
+- 所有调用 `streamFromGateway` 的地方传递 `cfg.gateway?.port`
+
+#### 新会话命令修复 / New Session Command Fix
+
+**变更前 / Before**：
+- `isNewSessionCommand` 函数检查消息是否为新会话命令
+- `handleDingTalkMessage` 中拦截新会话命令，直接回复固定文案并提前 return
+- 新会话命令不会发送到 Gateway，会话实际上未被清理
+
+**变更后 / After**：
+- `normalizeSlashCommand` 函数将所有新会话命令别名统一归一为 `/new`
+- 删除 `handleDingTalkMessage` 中的本地拦截逻辑
+- 新会话命令完整透传到 Gateway，由 Gateway 统一处理会话重置
+- 在构造 `userContent` 时调用 `normalizeSlashCommand` 处理文本
+
+**代码变更示例 / Code Change Example**：
+```typescript
+// 修复前 / Before
+function isNewSessionCommand(text: string): boolean {
+  const trimmed = text.trim().toLowerCase();
+  return NEW_SESSION_COMMANDS.some(cmd => trimmed === cmd.toLowerCase());
+}
+
+// 在 handleDingTalkMessage 中
+const forceNewSession = isNewSessionCommand(content.text);
+if (forceNewSession) {
+  await sendMessage(..., '✨ 已开启新会话，之前的对话已清空。', ...);
+  return;  // 提前返回，不发送到 Gateway
+}
+
+// 修复后 / After
+function normalizeSlashCommand(text: string): string {
+  const trimmed = text.trim();
+  const lower = trimmed.toLowerCase();
+  if (NEW_SESSION_COMMANDS.some(cmd => lower === cmd.toLowerCase())) {
+    return '/new';  // 统一归一为标准命令
+  }
+  return text;
+}
+
+// 在 handleDingTalkMessage 中
+const rawText = content.text || '';
+let userContent = normalizeSlashCommand(rawText) || ...;
+// 发送到 Gateway，由 Gateway 处理会话重置
+```
+
+### 相关代码位置 / Related Code Locations
+
+主要修改文件：
+- `plugin.ts` - Gateway 连接逻辑和新会话命令处理逻辑修改
+
+关键变更点：
+- `GatewayOptions` 接口定义（新增 `gatewayPort` 参数）
+- `streamFromGateway` 函数中的端口选择逻辑
+- `handleDingTalkMessage` 函数中所有 `streamFromGateway` 调用点（同步模式、异步模式、流式模式）
+- `normalizeSlashCommand` 函数实现（替换 `isNewSessionCommand`）
+- `handleDingTalkMessage` 函数中删除本地拦截逻辑，改为透传命令到 Gateway
+
+## 📥 安装升级 / 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
+- **推荐升级**：在配置中指定了 `gateway.port` 的用户强烈建议升级到此版本，以确保端口配置正确生效  
+  **Recommended Upgrade**: Users who specified `gateway.port` in configuration are strongly recommended to upgrade to this version to ensure port configuration takes effect correctly
+- **新会话命令行为变更**：新会话命令现在会真正清理会话，由 Gateway 统一处理，提示文案可能有所不同  
+  **New Session Command Behavior Change**: New session commands now truly clear sessions, handled by Gateway, prompt messages may differ
+- **无需配置变更**：现有配置无需修改，修复会自动生效  
+  **No Configuration Changes Required**: Existing configurations work without modification, fix will automatically take effect
+
+### 验证步骤 / Verification Steps
+
+升级到此版本后：
+After upgrading to this version:
+
+1. **Gateway 端口验证**（如果配置了 `gateway.port`）：  
+   **Gateway Port Verification** (if `gateway.port` is configured):
+   - 检查配置：确认 `gateway.port` 配置正确  
+     Check Configuration: Verify that `gateway.port` is correctly configured
+   - 测试连接：发送一条消息，确认能够正常连接到 Gateway  
+     Test Connection: Send a message to verify normal connection to Gateway
+   - 验证端口：确认连接使用的是配置的端口，而不是默认端口  
+     Verify Port: Confirm that the connection uses the configured port, not the default port
+
+2. **新会话命令验证**：  
+   **New Session Command Verification**:
+   - 发送新会话命令（如 `/new`、`/reset`、`新会话` 等）  
+     Send new session command (e.g., `/new`, `/reset`, `新会话`, etc.)
+   - 确认收到 Gateway 返回的会话重置提示（提示文案可能有所不同）  
+     Confirm receipt of Gateway's session reset prompt (prompt message may differ)
+   - 发送后续消息，确认会话已真正清空，不包含之前的对话上下文  
+     Send follow-up message, confirm session is truly cleared, no previous conversation context included
+
+### 配置示例 / Configuration Example
+
+```json5
+{
+  "channels": {
+    "dingtalk-connector": {
+      "enabled": true,
+      "clientId": "dingxxxxxxxxx",
+      "clientSecret": "your_secret_here",
+      "gateway": {
+        "port": 18888  // 自定义 Gateway 端口
+      }
+    }
+  }
+}
+```
+
+## 🔗 相关链接 / 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 #139](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/pull/139) - Gateway 端口连接修复
+- [Pull Request #170](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/pull/170) - 新会话命令修复
+
+## 🙏 致谢 / Acknowledgments
+
+感谢所有贡献者和用户的支持与反馈！
+Thanks to all contributors and users for their support and feedback!
+
+---
+
+**发布日期 / Release Date**：2026-03-12  
+**版本号 / Version**：v0.7.6  
+**兼容性 / Compatibility**：OpenClaw Gateway 0.4.0+

package/docs/RELEASE_NOTES_V0.7.7.md

@@ -0,0 +1,122 @@
+# Release Notes - v0.7.7
+
+## ✨ 功能与体验改进 / Features & Improvements
+
+- **自定义 Gateway URL 支持 / Custom Gateway URL Support**  
+  通过新增 `gatewayBaseUrl` 配置项，支持将请求发送到自定义的 Gateway 地址，例如通过 Nginx 反向代理到启用 TLS/HTTPS 的 Gateway。  
+  With the new `gatewayBaseUrl` option, requests can be sent to a custom Gateway URL, such as an Nginx reverse proxy in front of a TLS/HTTPS-enabled Gateway.
+
+- **钉钉「思考中」表情反馈 / DingTalk “Thinking” Emotion Feedback**  
+  在处理用户消息期间，Connector 会在原消息上贴上「🤔思考中」表情，处理结束后自动撤回，以更直观地展示处理进度。  
+  While processing a user message, the connector attaches a “🤔 Thinking” emotion to the original message and automatically recalls it after completion to clearly indicate processing progress.
+
+- **测试基础设施完善 / Testing Infrastructure Enhancement**  
+  引入 Vitest 测试框架与多种测试脚本（单次运行、watch、覆盖率、UI、集成测试），为后续质量保障和回归测试打下基础。  
+  Introduced the Vitest testing framework and multiple test scripts (run, watch, coverage, UI, integration) to improve quality assurance and regression testing.
+
+- **文档与示例优化 / Documentation & Examples Improvements**  
+  更新 README，补充了 OpenClaw 官方连接器定位、Gateway TLS/HTTPS 配置示例、钉钉机器人创建引导图、以及在 OpenClaw 中配置 MCP 触发规则的截图说明。  
+  Updated README with official connector positioning, Gateway TLS/HTTPS configuration example, DingTalk bot creation walkthrough images, and screenshots for configuring MCP trigger rules in OpenClaw.
+
+## 🐛 修复 / Fixes
+
+- **媒体元数据与缩略图提取健壮性提升 / More Robust Media Metadata & Thumbnail Extraction**  
+  当 ffprobe 或缩略图生成失败（例如环境缺少依赖、视频流缺失）时，不再抛出异常中断主流程，而是安全返回默认元数据或空缩略图，确保消息处理不中断。  
+  When ffprobe or thumbnail generation fails (e.g., missing dependencies or video stream), the connector no longer throws and aborts the main flow, but safely returns default metadata or a null thumbnail so message handling continues.
+
+- **音频时长提取兼容性改进 / Audio Duration Extraction Compatibility**  
+  使用动态 `import('child_process')` 替代 `require('child_process')`，提升在不同打包/运行环境下的兼容性。  
+  Switched from `require('child_process')` to dynamic `import('child_process')` to improve compatibility across different bundling and runtime environments.
+
+- **主动消息用户列表校验 / Proactive Message User List Validation**  
+  在向多个用户发送主动消息时，对 `userIds` 列表进行空值过滤，避免因无效用户 ID 导致的请求失败。  
+  Filters out empty values from the `userIds` list when sending proactive messages to multiple users, preventing request failures caused by invalid user IDs.
+
+## 📋 技术细节 / Technical Details
+
+### Gateway URL 配置 / Gateway URL Configuration
+
+- `GatewayOptions` 接口新增 `gatewayBaseUrl?: string` 字段，用于指定自定义 Gateway URL（例如 `http://127.0.0.1:18788`）。  
+- `streamFromGateway` 中优先使用 `gatewayBaseUrl` 构造请求地址，否则回退到本地端口逻辑：  
+  `gatewayBaseUrl ? \`\${gatewayBaseUrl}/v1/chat/completions\` : \`http://127.0.0.1:\${port}/v1/chat/completions\``。  
+- 插件配置新增 `gatewayBaseUrl` 字段说明，帮助用户在 TLS/HTTPS 或 Nginx 代理场景下正确配置。
+
+### 钉钉表情反馈逻辑 / DingTalk Emotion Feedback Logic
+
+- 新增 `addEmotionReply`：在处理用户消息前，为该消息贴上「🤔思考中」表情，使用机器人凭证调用 `robot/emotion/reply` 接口。  
+- 新增 `recallEmotionReply`：在消息处理完成后的 `finally` 块内调用，撤回之前贴上的表情，通过 `robot/emotion/recall` 接口实现。  
+- 以上调用均带有完善的错误日志，失败不会中断主消息处理流程，仅记录警告日志。
+
+### 媒体处理健壮性 / Media Handling Robustness
+
+- `extractVideoMetadata`：  
+  - 将 Promise 回调中的错误处理改为返回 `{ duration: 0, width: 0, height: 0 }`，而非直接 reject。  
+  - 当未找到视频流时，同样返回默认元数据结构。  
+  - 外层 `catch` 中也返回默认元数据，确保调用方不需要对 `null` 做额外分支判断。  
+- `extractVideoThumbnail`：  
+  - 截图失败时不再 reject，而是 resolve `null`，由上层逻辑决定是否展示缩略图。  
+- `extractAudioDuration`：  
+  - 使用 `await import('child_process')` 获取 `execFile`，提高 ESM/打包场景下的兼容性。
+
+### 测试与依赖 / Testing & Dependencies
+
+- 在 `package.json` 中：  
+  - 将 `test` 脚本更新为 `vitest run`，并新增 `test:watch`、`test:coverage`、`test:ui`、`test:integration` 等脚本。  
+  - 新增开发依赖：`@types/node`、`typescript`、`vitest`。  
+- 这些变更为后续补充单元测试、集成测试以及 CI 集成提供基础设施支持。
+
+### CI 工作流 / CI Workflow
+
+- 新增 `.github/workflows/issue-to-AI-table.yml`：  
+  - 监听 Issue 的创建、重开、关闭、编辑、打标签/去标签等事件。  
+  - 将 Issue 的关键信息（编号、标题、内容、状态、链接等）以统一格式推送到配置的 Webhook（`ISSUE_WEBHOOK_URL`）。  
+  - 可用于接入内部 AI 分析、需求盘点或看板同步等自动化流程。
+
+## 📥 安装升级 / 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**：本次更新为小版本改进，保留了 v0.7.x 既有行为，对现有配置完全兼容。  
+- **推荐使用 `gatewayBaseUrl` 配置 TLS 场景 / Recommended for TLS via `gatewayBaseUrl`**：  
+  在通过 Nginx 或其他代理为 Gateway 启用 TLS/HTTPS 的场景下，建议配置 `gatewayBaseUrl`，以确保 Connector 能够直接访问代理层地址。  
+- **媒体处理更安全 / Safer Media Handling**：即便视频/音频元数据提取失败，也不会影响消息主流程，仅在日志中记录错误。
+
+### 验证步骤 / Verification Steps
+
+升级到此版本后，建议进行以下验证：
+
+1. **Gateway URL 验证 / Gateway URL Verification**  
+   - 配置 `gatewayBaseUrl` 指向你的 Nginx/Gateway 代理地址。  
+   - 发送一条消息，确认能够正常与 Gateway 通信。  
+2. **钉钉表情反馈验证 / DingTalk Emotion Feedback Verification**  
+   - 在钉钉中向机器人发送一条消息。  
+   - 确认消息上出现「🤔思考中」表情。  
+   - 等待 AI 回复结束后，确认该表情被自动撤回。  
+3. **媒体消息兼容性验证 / Media Message Compatibility Verification**  
+   - 发送包含视频或音频的消息，在缺少部分 ffmpeg 依赖的环境下确认不会导致整个会话失败，仅记录错误日志。
+
+## 🔗 相关链接 / 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)
+
+---
+
+**发布日期 / Release Date**：2026-03-13  
+**版本号 / Version**：v0.7.7  
+**兼容性 / Compatibility**：OpenClaw Gateway 0.4.0+
+

package/docs/RELEASE_NOTES_V0.7.8.md

@@ -0,0 +1,101 @@
+# Release Notes - v0.7.8
+
+## ✨ 功能与体验改进 / Features & Improvements
+
+- **AI 卡片模版更新与展示效果优化 / AI Card Template & Rendering Improvements**  
+  升级钉钉 AI 卡片模版 ID，使卡片样式与最新官方规范保持一致，并优化多终端的展示效果与兼容性。  
+  Updated the DingTalk AI card template ID to align with the latest official template standard, improving visual consistency and compatibility across different clients.
+
+- **Markdown 表格渲染修复与自动优化 / Markdown Table Rendering Fix & Auto-Adjustment**  
+  新增 Markdown 预处理逻辑，在发送到钉钉前自动为表格头部补充必要的空行，避免因缺少空行导致的表格无法正确渲染问题；支持缩进表格场景。  
+  Added a Markdown preprocessing step that automatically inserts a blank line before table headers when needed, ensuring DingTalk renders tables correctly, including indented table cases.
+
+- **统一的 Markdown 修正管道 / Unified Markdown Normalization Pipeline**  
+  对 AI 卡片流式更新、AI 卡片最终内容提交、普通 Markdown 消息发送以及卡片 `sampleMarkdown` 内容，统一通过同一套 Markdown 修正函数进行处理，确保所有下发到钉钉的文本在表格渲染等细节上行为一致。  
+  Unified the Markdown normalization logic used for streaming AI card updates, final AI card content, regular Markdown messages, and `sampleMarkdown` card payloads, ensuring consistent behavior of table rendering and formatting in DingTalk.
+
+- **AI 卡片状态信息更准确 / More Accurate AI Card Status Content**  
+  在完成 AI 卡片时，对用于展示的内容与写入 `cardParamMap` 中的 `msgContent` 同步应用 Markdown 修正逻辑，保证用户看到的内容与卡片内部状态字段保持完全一致。  
+  When finalizing AI cards, the same Markdown fixes are now applied both to the displayed content and the `msgContent` stored in `cardParamMap`, keeping the visible card and its internal state in sync.
+
+## 🐛 修复 / Fixes
+
+- **Markdown 表格无法正确显示的问题 / Incorrect Markdown Table Rendering**  
+  修复了部分场景下 Markdown 表格前缺少空行，导致钉钉不将其识别为表格而当作普通文本渲染的问题；现在会自动检测表头与分隔行模式并在需要时插入空行。  
+  Fixed an issue where missing blank lines before Markdown tables caused DingTalk to render them as plain text; the connector now detects table headers and divider lines and inserts a blank line when necessary.
+
+- **消息去重维度优化 / Message De-duplication Scope Optimization**  
+  优化消息去重逻辑，从「按账号+消息 ID」改为仅基于「消息 ID」维度标记与判断，避免在多账号场景中出现某些重复消息未被正确拦截或误判的情况。  
+  Improved the message de-duplication mechanism by switching from an account-scoped `(accountId, messageId)` key to a global `messageId` key, preventing edge cases where duplicate messages across accounts might not be handled correctly.
+
+## 📋 技术细节 / Technical Details
+
+### AI 卡片模版 & 内容处理 / AI Card Template & Content Handling
+
+- 更新 `AI_CARD_TEMPLATE_ID` 为新的模版 ID，以匹配最新的钉钉 AI 卡片样式规范。  
+- 新增 `ensureTableBlankLines(text: string)` 工具函数：  
+  - 将文本按行拆分，识别包含竖线的表格行与 `---` 分隔行。  
+  - 当前行看起来像表头、下一行是分隔行、且前一行既不是空行也不是表格行时，会在表头前插入一个空行。  
+  - 支持带缩进的表格写法，保持原有内容顺序与缩进风格不变。  
+- 在以下路径中统一使用 `ensureTableBlankLines`：  
+  - AI 卡片流式内容更新（`streamAICard`）中的 `content` 字段。  
+  - AI 卡片结束时（`finishAICard`）的最终内容与日志长度统计。  
+  - 普通 Markdown 消息发送（`sendMarkdownMessage`），在追加 `@user` 之前先做表格修正。  
+  - `buildMsgPayload` 中 `sampleMarkdown` 类型的 `text` 字段。  
+- 为单元测试导出 `__testables.ensureTableBlankLines`，便于在不依赖具体业务逻辑的情况下验证 Markdown 修正规则。
+
+### 消息去重逻辑 / Message De-duplication Logic
+
+- 去重检查由 `isMessageProcessed(accountId, messageId)` 简化为 `isMessageProcessed(messageId)`，对同一消息 ID 统一判重。  
+- 标记逻辑由 `markMessageProcessed(accountId, messageId)` 更新为 `markMessageProcessed(messageId)`，减少多账号场景下可能出现的重复处理路径。  
+- 保持原有日志信息与跳过处理分支不变，仅调整内部去重键值结构。
+
+## 📥 安装升级 / 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**：本次为小版本修复和体验优化更新，在保留 v0.7.x 既有行为的前提下增强了 Markdown 表格渲染与消息去重逻辑，对现有配置完全兼容。  
+- **Markdown 表格渲染更稳定 / More Robust Markdown Tables**：即便原始内容中未严格遵守表格前空行的写法，Connector 也会自动做最小化修正，以提高在钉钉中的可读性。  
+- **消息去重语义更清晰 / Clearer De-duplication Semantics**：以 `messageId` 为唯一维度进行去重，更贴合钉钉消息唯一标识的语义。
+
+### 验证步骤 / Verification Steps
+
+升级到此版本后，建议进行以下验证：
+
+1. **AI 卡片模版与渲染验证 / AI Card Template & Rendering Verification**  
+   - 触发一次典型的 AI 卡片对话，观察新模版下的卡片布局与字段展示是否符合预期。  
+   - 在含有多段文字与表格的回复中，确认卡片内 Markdown 表格渲染正常。  
+
+2. **Markdown 表格兼容性验证 / Markdown Table Compatibility Verification**  
+   - 通过机器人发送包含 Markdown 表格的消息（包含表头、分隔行与多列数据），且故意在表格前省略空行。  
+   - 在移动端及 PC 端查看，确认钉钉能够正确以表格形式渲染内容。  
+
+3. **消息去重行为验证 / Message De-duplication Behavior Verification**  
+   - 在相同会话中模拟重复推送同一个 `messageId` 的回调（或快速重复发送同一条消息）。  
+   - 确认日志中出现去重命中提示，并且业务处理逻辑只执行一次。
+
+## 🔗 相关链接 / 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)
+
+---
+
+**发布日期 / Release Date**：2026-03-13  
+**版本号 / Version**：v0.7.8  
+**兼容性 / Compatibility**：OpenClaw Gateway 0.4.0+
+

package/docs/RELEASE_NOTES_V0.7.9.md

@@ -0,0 +1,65 @@
+# Release Notes - v0.7.9
+
+## ✨ 功能与体验改进 / Features & Improvements
+
+- **钉钉 Stream 客户端心跳与重连机制优化 / DingTalk Stream Client Heartbeat & Reconnect**  
+  关闭 DWClient SDK 内置的激进 keepAlive（避免 8 秒超时强制断连），启用应用层自定义心跳：基于 WebSocket ping/pong，30 秒间隔、90 秒超时，超时后主动断开并重连，重连失败时 5 秒后重试，提升长连稳定性。  
+  Disabled the SDK's aggressive keepAlive (which could force disconnect after 8s), and added an application-layer heartbeat: WebSocket ping/pong with 30s interval and 90s timeout; on timeout the client disconnects and reconnects, with a 5s retry on failure, improving long-lived connection stability.
+
+- **DWClient 配置调整 / DWClient Configuration**  
+  启用 `autoReconnect: true` 以在连接断开时自动重连；设置 `keepAlive: false`，由应用层心跳替代 SDK 心跳，避免与钉钉服务端策略冲突。  
+  Enabled `autoReconnect: true` for automatic reconnection on disconnect; set `keepAlive: false` and rely on application-layer heartbeat to avoid conflicts with DingTalk server behavior.
+
+- **统一停止与清理逻辑 / Unified Stop & Cleanup**  
+  停止 Stream 客户端时统一通过 `doStop` 清理心跳定时器并调用 `client.disconnect()`，确保资源释放与连接正确关闭。  
+  When stopping the Stream client, a unified `doStop` now clears the heartbeat timer and calls `client.disconnect()` for consistent resource cleanup and connection closure.
+
+## 🐛 修复 / Fixes
+
+- **长连接被服务端或中间网络提前断开 / Long-lived Connection Premature Disconnect**  
+  通过应用层心跳检测连接活性，超时后主动重连，减少因长时间无数据导致的静默断连且无法恢复的问题。  
+  Application-layer heartbeat detects connection liveness and triggers reconnect on timeout, reducing silent disconnects when the link is idle.
+
+## 📋 技术细节 / Technical Details
+
+### 应用层心跳机制 / Application-Layer Heartbeat
+
+- **参数**：心跳间隔 30 秒（`HEARTBEAT_INTERVAL`），超时 90 秒（`HEARTBEAT_TIMEOUT`），允许约 3 次 ping 无响应后再判定超时。  
+- **流程**：定时器每 30 秒通过 `client.socket?.ping()` 发送 ping；监听 `socket.on('pong')` 更新 `lastPongTime`；若当前时间与 `lastPongTime` 差值超过 90 秒则触发重连。  
+- **重连**：先 `await client.disconnect()`，再 `await client.connect()`，成功后重置 `lastPongTime`；若重连失败则 5 秒后再次尝试 `client.connect()`。  
+- **停止**：`doStop(reason)` 中设置 `stopped = true`、清除心跳定时器、调用 `client.disconnect()`，并记录停止原因与活动。
+
+### DWClient 配置说明 / DWClient Config
+
+- `autoReconnect: true` — 连接断开时由 SDK 参与自动重连。  
+- `keepAlive: false` — 关闭 SDK 内置的激进心跳，避免 8 秒无活动即强制断连，由应用层 30s/90s 心跳替代。
+
+## 📥 安装升级 / 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
+
+- **向下兼容 / Backward Compatible**：仅调整 Stream 客户端的心跳与重连策略，对现有配置与 API 无破坏性变更。  
+- **长连场景建议**：若依赖钉钉 Stream 长连接，升级后将自动使用新的心跳与重连逻辑，无需额外配置。
+
+## 🔗 相关链接 / 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)
+
+---
+
+**发布日期 / Release Date**：2026-03-13  
+**版本号 / Version**：v0.7.9  
+**兼容性 / Compatibility**：OpenClaw Gateway 0.4.0+

package/docs/RELEASE_NOTES_V0.8.0.md

@@ -0,0 +1,53 @@
+# Release Notes - v0.8.0
+
+## 🎉 新版本亮点 / Highlights
+
+本次更新聚焦于“架构升级 + 体验优化 + 稳定性增强”：项目完成业务逻辑分层重构，并将 OpenClaw 对接方式从 HTTP 迁移到 SDK；同时优化了 IM 交互体验，重写并简化了 README 配置教程；此外针对 dingtalk-stream 场景下的断连问题进行了修复，整体提升了接入效率与线上运行稳定性。
+
+This release focuses on architecture upgrade, experience optimization, and stability enhancement. The project has been refactored into a layered business-logic architecture and migrated from OpenClaw HTTP integration to OpenClaw SDK. It also improves IM interactions, rewrites and simplifies the README setup guide, and fixes disconnection issues in dingtalk-stream scenarios, resulting in faster onboarding and more stable production behavior.
+
+## ✨ 功能与体验改进 / Features & Improvements
+
+- **业务逻辑分层重构 / Layered Architecture Refactor**  
+  本版本对项目进行业务逻辑分层重构，按职责拆分模块与流程，提升代码可维护性、可扩展性与后续迭代效率。  
+  This release refactors the project into a layered business-logic architecture, splitting modules and flows by responsibility for better maintainability, scalability, and iteration efficiency.
+
+- **OpenClaw SDK 对接 / OpenClaw SDK Integration**  
+  对接方式由 OpenClaw HTTP 调用迁移至 OpenClaw SDK，统一接口调用路径，提升集成稳定性并减少维护成本。  
+  Integration has been migrated from OpenClaw HTTP calls to OpenClaw SDK, unifying invocation paths and improving integration stability with lower maintenance overhead.
+
+- **IM 交互体验优化 / IM Interaction Optimization**  
+  优化 IM 场景中的部分交互体验，提升消息反馈的流畅性与可用性。  
+  Improved interaction details in IM scenarios for smoother feedback and better usability.
+
+- **README 重写与教程简化 / README Rewrite & Setup Simplification**  
+  根据社区用户反馈，重写使用文档并简化配置步骤，减少接入复杂度，帮助开发者更快完成部署与验证。  
+  Rewrote documentation and simplified setup steps to reduce onboarding complexity and help developers deploy and verify faster.
+
+- **dingtalk-stream 断连修复 / dingtalk-stream Disconnect Fixes**  
+  修复 dingtalk-stream 带来的部分断连问题，增强连接稳定性及异常恢复能力。  
+  Fixed several dingtalk-stream related disconnection issues, improving connection stability and recovery behavior.
+
+## 📥 安装升级 / 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-20  
+**版本号 / Version**：v0.8.0  
+**兼容性 / Compatibility**：OpenClaw Gateway 0.4.0+

package/docs/RELEASE_NOTES_V0.8.1.md

@@ -0,0 +1,47 @@
+# Release Notes - v0.8.1
+
+## 🎉 新版本亮点 / Highlights
+
+本次更新专注于修复文件下载功能的关键问题。解决了用户发送文件到钉钉后无法下载到本地的 OSS 签名验证失败问题，确保文件和图片下载功能的稳定性。
+
+This release focuses on fixing a critical file download issue. It resolves the OSS signature verification failure that prevented files sent to DingTalk from being downloaded locally, ensuring stable file and image download functionality.
+
+## 🐛 修复 / Fixes
+
+- **文件和图片下载 OSS 签名验证失败 / File and Image Download OSS Signature Verification Failure**  
+  修复了 `dingtalkHttp` 实例默认携带的 `Content-Type: application/json` 请求头导致 OSS 预签名 URL 签名验证失败的问题。通过在下载请求中显式删除 `Content-Type` 请求头，确保文件和图片能够正常下载到 `media/inbound/` 目录。同时添加了异常堆栈日志，便于后续问题排查。  
+  Fixed an issue where the default `Content-Type: application/json` header in the `dingtalkHttp` instance caused OSS pre-signed URL signature verification to fail. By explicitly removing the `Content-Type` header in download requests, files and images can now be downloaded successfully to the `media/inbound/` directory. Also added exception stack trace logging for easier troubleshooting.
+
+  **影响范围 / Impact**:
+  - 文件下载功能 / File download functionality
+  - 图片下载功能 / Image download functionality
+
+  **技术细节 / Technical Details**:
+  - 问题根源：OSS 签名基于所有请求参数（包括请求头）计算，额外的请求头导致签名不匹配
+  - 解决方案：设置 `headers: { 'Content-Type': undefined }` 覆盖默认配置
+  - 修改文件：`src/core/message-handler.ts` 中的 `downloadFileToLocal` 和 `downloadImageToFile` 函数
+
+## 📥 安装升级 / 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)
+- [Pull Request #300](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/pull/300)
+
+---
+
+**发布日期 / Release Date**：2026-03-20  
+**版本号 / Version**：v0.8.1  
+**兼容性 / Compatibility**：OpenClaw Gateway 0.4.0+