@dingtalk-real-ai/dingtalk-connector 0.7.9 → 0.8.0-beta.0

package/CHANGELOG.md

@@ -1,10 +1,44 @@
 # Changelog
 
-本文档记录所有重要的变更。格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.0.0/)，
-版本号遵循 [Semantic Versioning](https://semver.org/lang/zh-CN/)。
+All notable changes to this project will be documented in this file.
 
-This document records all significant changes. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
-and version numbers follow [Semantic Versioning](https://semver.org/).
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.7.10] - 2026-03-16
+
+### 新增 / Added
+- ✨ **WebSocket 心跳重连机制优化** - 关闭 DWClient 的 `autoConnect`，采用应用层自动重连机制（修复 DWClient 重连 bug）；添加指数退避重连策略，避免雪崩效应；使用 WebSocket 原生 Ping 进行心跳检测  
+  **WebSocket heartbeat & reconnect optimization** - Disabled DWClient's `autoConnect`, implemented app-layer auto-reconnect (fixing DWClient bug); added exponential backoff to avoid avalanche; using WebSocket native Ping for heartbeat
+- ✨ **socket-manager 模块** - 新增模块统一管理 WebSocket 连接生命周期，包括心跳检测、自动重连、指数退避、事件监听等  
+  **socket-manager module** - New module for unified WebSocket connection lifecycle management, including heartbeat, auto-reconnect, exponential backoff, event listening
+- ✨ **debug 参数** - 添加 `debug` 配置项控制详细日志输出，便于问题排查  
+  **debug parameter** - Added `debug` config to control detailed log output for easier troubleshooting
+- ✨ **WebSocket 无限重连机制** - 移除最大重连次数限制，实现无限重连，确保长连接服务的高可用性  
+  **WebSocket infinite reconnection** - Removed maximum reconnection attempt limit, implemented infinite reconnection to ensure high availability for long-lived connection services
+
+### 修复 / Fixes
+- 🐛 **修复 DWClient 重连 bug** - DWClient 内置重连机制存在缺陷，通过应用层重连机制替代，确保连接稳定可靠  
+  **Fixed DWClient reconnect bug** - DWClient's built-in reconnect has defects; replaced with app-layer reconnect for stable connection
+- 🐛 **长连接静默断开** - 通过应用层心跳检测连接活性，超时后主动重连，减少因长时间无数据导致的静默断连且无法恢复  
+  **Long-lived connection silent disconnect** - App-layer heartbeat detects liveness and triggers reconnect on timeout, reducing silent disconnects when idle
+### 改进 / Improvements
+- ✅ **DWClient 配置** - 设置 `autoReconnect: false`、`keepAlive: false`，由应用层接管重连和心跳，避免与钉钉服务端策略冲突  
+  **DWClient config** - Set `autoReconnect: false`, `keepAlive: false`; app-layer takes over reconnect and heartbeat to avoid server conflicts
+- ✅ **指数退避策略** - 公式 `baseBackoffDelay * Math.pow(2, attempt) + jitter(0-1s)`，最大退避 30 秒，避免雪崩效应  
+  **Exponential backoff strategy** - Formula `baseBackoffDelay * Math.pow(2, attempt) + jitter(0-1s)`, max 30s backoff to avoid avalanche effect
+- ✅ **统一事件监听** - `pong`、`message`、`close`、`open` 四个事件统一管理和清理，提升代码可维护性  
+  **Unified event listening** - `pong`, `message`, `close`, `open` events managed and cleaned up uniformly, improving maintainability
+- ✅ **配置简化** - 从 `SocketManagerConfig` 中移除 `maxReconnectAttempts` 配置项，简化配置复杂度  
+  **Configuration simplification** - Removed `maxReconnectAttempts` from `SocketManagerConfig`, simplifying configuration
+- ✅ **日志输出优化** - 更新重连日志格式，移除最大次数显示（从 "尝试 X/5" 改为 "尝试 X"）  
+  **Log output optimization** - Updated reconnection log format, removed maximum attempt display (from "attempt X/5" to "attempt X")
+
+### 技术细节 / Technical Details
+- **退避策略**：指数退避 + 随机抖动，公式 `baseBackoffDelay * Math.pow(2, attempt) + jitter(0-1s)`  
+- **最大退避**：30 秒（由 `maxBackoffDelay` 限制）  
+- **重置条件**：重连成功后 `reconnectAttempts` 归零  
+- **立即重连**：心跳检测失败、WebSocket close、disconnect 消息触发时立即重连，不退避  
 
 ## [0.7.9] - 2026-03-13
 
@@ -243,5 +277,4 @@ and version numbers follow [Semantic Versioning](https://semver.org/).
 - 新增"多 Agent 配置"章节，提供详细的配置示例和说明  
   Added "Multi-Agent Configuration" section with detailed configuration examples and instructions
 - 补充常见问题解答  
-  Added FAQ section
-
+  Added FAQ section

package/README.en.md

@@ -0,0 +1,396 @@
+<div align="center">
+  <img alt="DingTalk" src="docs/images/dingtalk.svg" width="72" height="72" />
+  <h1>Official DingTalk OpenClaw Connector</h1>
+  <p>Connect DingTalk bots to OpenClaw Gateway with AI Card streaming and session management</p>
+  
+  <p>
+    <a href="README.md">简体中文</a> •
+    <a href="CHANGELOG.md">Changelog</a>
+  </p>
+</div>
+
+---
+
+## 📋 Table of Contents
+
+- [Prerequisites](#prerequisites)
+- [Quick Start](#quick-start)
+- [Features](#features)
+- [Configuration](#configuration)
+- [Troubleshooting](#troubleshooting)
+- [Advanced Topics](#advanced-topics)
+- [License](#license)
+
+---
+
+## Prerequisites
+
+Before you begin, ensure you have:
+
+> This connector is used as an OpenClaw Gateway plugin, and you usually don't need to install or manage Node.js runtime by yourself.
+
+### 1. OpenClaw Gateway
+
+- **Official Website**: https://openclaw.ai/
+- **Installation**: Follow the official guide to install OpenClaw
+- **Verify installation**:
+  ```bash
+  openclaw gateway status
+  ```
+  Expected output: `✓ Gateway is running on http://127.0.0.1:18789`
+
+### 2. DingTalk Enterprise Account
+
+- You need a DingTalk enterprise account to create internal applications
+- Official Website: https://www.dingtalk.com/
+
+---
+
+## Quick Start
+
+> 💡 **Goal**: Get your DingTalk bot working in ~5 minutes
+
+### Operating System Support
+
+- macOS / Linux: Use the default shell (zsh, bash, etc.).
+- Windows:
+  - Recommended: **PowerShell** or **Windows Terminal**.
+  - OpenClaw config file path (default): `C:\Users\<YourUserName>\.openclaw\openclaw.json`.
+
+Whenever you see `~/.openclaw/openclaw.json` below, it is equivalent to the above path on Windows.
+
+### Step 1: Install the Plugin
+
+```bash
+# Recommended: Install from npm
+openclaw plugins install @dingtalk-real-ai/dingtalk-connector
+
+# Alternative: Install from Git
+openclaw plugins install https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector.git
+```
+
+**Verify installation**:
+```bash
+openclaw plugins list
+```
+You should see `✓ DingTalk Channel (v0.8.0) - loaded`
+
+---
+
+### Step 2: Create a DingTalk Bot
+
+#### 2.1 Create Application
+
+1. Go to [DingTalk Open Platform](https://open-dev.dingtalk.com/)
+2. Click **"Application Development"**
+
+![Create Application](docs/images/image-1.png)
+
+#### 2.2 Add Bot Capability
+
+1. On the application details page, use the “one-click OpenClaw bot app” flow
+
+![Create OpenClaw bot app](docs/images/image-2.png)
+
+#### 2.3 Get Credentials
+
+1. Finish creation and open **"Credentials & Basic Info"**
+2. Copy your **AppKey** (Client ID)
+3. Copy your **AppSecret** (Client Secret)
+
+![Finish creation](docs/images/image-3.png)
+
+![Get credentials](docs/images/image-4.png)
+
+> ⚠️ **Important**: Client ID and Client Secret are your bot’s unique credentials. Store them safely.
+
+---
+
+### Step 3: Configure OpenClaw
+
+You have three options to configure the connector:
+
+#### Option A: Configuration Wizard (Recommended for Beginners)
+
+> You can directly copy and paste the following command into your terminal to run the configuration wizard.
+
+```bash
+openclaw channels add
+```
+
+Select **"DingTalk (钉钉)"** and follow the prompts to enter:
+- `clientId` (AppKey)
+- `clientSecret` (AppSecret)
+
+#### Option B: Edit Configuration File
+
+Edit the configuration file:
+
+- macOS / Linux: `~/.openclaw/openclaw.json`
+- Windows: `C:\Users\<YourUserName>\.openclaw\openclaw.json`
+
+```json
+{
+  "channels": {
+    "dingtalk-connector": {
+      "enabled": true,
+      "clientId": "dingxxxxxxxxx",
+      "clientSecret": "your_app_secret"
+    }
+  }
+}
+```
+
+> 💡 **Tip**: If the file already has content, add the `dingtalk-connector` section under the `channels` node.
+
+---
+
+### Step 4: Restart and Test
+
+```bash
+# Restart OpenClaw Gateway
+openclaw gateway restart
+
+# Watch logs in real-time
+openclaw logs --follow
+```
+
+**Test your bot**:
+1. Open DingTalk app
+2. Find your bot in the contact list
+3. Send a message: `Hello`
+4. You should receive a response within 10 seconds
+
+---
+
+## Features
+
+### ✅ Core Features
+
+- **AI Card Streaming** - Typewriter-like replies with real-time streaming
+- **Session Management** - Multi-turn conversations with context preservation
+- **Session Isolation** - Separate sessions for DMs, groups, and different groups
+- **Auto Session Reset** - Automatic new session after 30 minutes of inactivity
+- **Manual Session Reset** - Send `/new` or `新会话` to clear conversation history
+- **Image Auto-Upload** - Local image paths automatically uploaded to DingTalk
+- **Proactive Messaging** - Send messages to users or groups programmatically
+- **Rich Media Reception** - Receive and process JPEG/PNG images, pass to vision models
+- **File Attachment Extraction** - Parse .docx, .pdf, text files, and binary files
+- **Audio Message Support** - Send audio messages in multiple formats (mp3, wav, amr, ogg)
+- **DingTalk Docs API** - Create, append, search, and list DingTalk documents
+- **Multi-Agent Routing** - Connect multiple bots to different agents for specialized services
+- **Markdown Table Conversion** - Auto-convert Markdown tables to DingTalk-compatible format
+- **Async Mode** - Immediate acknowledgment with background processing (optional)
+
+---
+
+## Configuration
+
+### Basic Configuration
+
+| Option | Environment Variable | Description |
+|--------|---------------------|-------------|
+| `clientId` | — | DingTalk AppKey |
+| `clientSecret` | — | DingTalk AppSecret |
+
+### Session Management
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `separateSessionByConversation` | `true` | Separate sessions for DMs/groups |
+| `groupSessionScope` | `group` | Group session scope: `group` (shared) or `group_sender` (per-user) |
+| `sharedMemoryAcrossConversations` | `false` | Share memory across different conversations |
+
+### Session routing policies (`pmpolicy` / `groupPolicy`)
+
+Both session routing/message policy options (including `pmpolicy` and `groupPolicy`) are supported now, so you **do not need to remove** them from existing configurations.
+
+> Note: field names may vary across versions/upstream; on the connector side, related policies are supported and applied (for example, `dmPolicy`/`groupPolicy` default to `open`).
+
+### Async Mode
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `asyncMode` | `false` | Enable async mode for long-running tasks |
+| `ackText` | `🫡 任务已接收，处理中...` | Acknowledgment message text |
+
+---
+
+## Troubleshooting
+
+### Bot Not Responding
+
+**Symptoms**: Bot doesn't reply to messages
+
+**Solutions**:
+1. Check plugin status: `openclaw plugins list`
+2. Check gateway status: `openclaw gateway status`
+3. Check logs: `openclaw logs --follow`
+4. Verify the app is published/enabled in DingTalk Open Platform
+
+---
+
+### HTTP 401 Error
+
+**Symptoms**: Error message shows "401 Unauthorized"
+
+**Solution**: Upgrade to the latest version.
+
+---
+
+### Stream Connection 400 Error
+
+**Symptoms**: Logs show "Request failed with status code 400"
+
+**Common Causes**:
+
+| Cause | Solution |
+|-------|----------|
+| App not published | DingTalk Open Platform → Version Management → Publish |
+| Invalid credentials | Check `clientId`/`clientSecret` for typos or extra spaces |
+| Not Stream mode | Verify bot is configured for Stream mode (not Webhook) |
+| IP whitelist | Check if the app has IP whitelist restrictions |
+
+**Verification Steps**:
+1. Check app status in [DingTalk Open Platform](https://open-dev.dingtalk.com/)
+2. After any configuration change, click **Save** → **Publish**
+
+---
+
+## Advanced Topics
+
+### Multi-Agent Configuration
+
+Configure multiple bots connected to different agents:
+
+```json
+{
+  "channels": {
+    "dingtalk-connector": {
+      "enabled": true,
+      "accounts": {
+        "bot1": {
+          "enabled": true,
+          "clientId": "ding_bot1_app_key",
+          "clientSecret": "bot1_secret"
+        },
+        "bot2": {
+          "enabled": true,
+          "clientId": "ding_bot2_app_key",
+          "clientSecret": "bot2_secret"
+        }
+      }
+    }
+  },
+  "bindings": [
+    {
+      "agentId": "ding-bot1",
+      "match": {
+        "channel": "dingtalk-connector",
+        "accountId": "bot1"
+      }
+    },
+    {
+      "agentId": "ding-bot2",
+      "match": {
+        "channel": "dingtalk-connector",
+        "accountId": "bot2"
+      }
+    }
+  ]
+}
+```
+
+For more details, see [OpenClaw Multi-Agent Configuration Guide](https://gist.github.com/smallnest/c5c13482740fd179e40070e620f66a52).
+
+---
+
+### Session Commands
+
+Users can send the following commands to start a fresh session:
+
+- `/new`, `/reset`, `/clear`
+- `新会话`, `重新开始`, `清空对话`
+
+---
+
+### DingTalk Docs via MCP (`docs.*`)
+
+DingTalk Docs capabilities (`docs.*`, including `docs.create` / `docs.append` / `docs.search` / `docs.list` / `docs.read`) require MCP (Model Context Protocol) to provide the underlying tools. To enable `docs.*`, install and enable the corresponding MCP Server/Tool in the OpenClaw Gateway/Agent.
+
+- **Where to get MCP Server/Tool**: via the [DingTalk MCP Marketplace](https://mcp.dingtalk.com/) (or your team’s internal MCP marketplace). You can also use a third-party marketplace to source an equivalent “DingTalk Docs Read / DingTalk Docs Reader” capability and connect it to OpenClaw.
+- **Where to configure**: usually at the **Gateway or Agent tool configuration** level (not in this connector).
+- **How it takes effect**: restart the Gateway and ensure the tool is exposed to the target agent.
+
+References (OpenClaw configuration docs):
+- `https://docs.openclaw.ai/configuration`
+- `https://docs.openclaw.ai/gateway/configuration-reference`
+
+Create and manage DingTalk documents from your agent:
+
+```javascript
+// Create document
+dingtalk-connector.docs.create({
+  spaceId: "your-space-id",
+  title: "Test Document",
+  content: "# Test Content"
+})
+
+// Append content
+dingtalk-connector.docs.append({
+  docId: "your-doc-id",
+  markdownContent: "\n## Appended Content"
+})
+
+// Search documents
+dingtalk-connector.docs.search({
+  keyword: "search keyword"
+})
+
+// List documents
+dingtalk-connector.docs.list({
+  spaceId: "your-space-id"
+})
+```
+
+---
+
+## Project Structure
+
+```
+dingtalk-openclaw-connector/
+├── src/
+│   ├── core/           # Core connector logic
+│   ├── services/       # DingTalk API services
+│   ├── utils/          # Utility functions
+│   └── types/          # TypeScript type definitions
+├── docs/
+│   └── images/         # Documentation images
+├── openclaw.plugin.json # Plugin manifest
+├── package.json        # npm dependencies
+└── LICENSE
+```
+
+---
+
+## Dependencies
+
+| Package | Purpose |
+|---------|---------|
+| `dingtalk-stream` | DingTalk Stream protocol client |
+| `axios` | HTTP client |
+| `mammoth` | Word document (.docx) parsing |
+| `pdf-parse` | PDF document parsing |
+
+---
+
+## License
+
+[MIT](LICENSE)
+
+---
+
+## Support
+
+- **Issues**: [GitHub Issues](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/issues)
+- **Changelog**: [CHANGELOG.md](CHANGELOG.md)