@huo15/dingtalk-connector-pro 1.0.0

package/README.en.md

@@ -0,0 +1,479 @@
+<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)
+- [DingTalk DEAP Agent Integration](docs/DEAP_AGENT_GUIDE.en.md)
+- [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
+
+#### Method A: Install via npm (Recommended)
+
+```bash
+openclaw plugins install @dingtalk-real-ai/dingtalk-connector
+```
+
+#### Method B: Install from Local Source
+
+If you want to develop or modify the plugin, clone the repository first:
+
+```bash
+# 1. Clone the plugin repository
+git clone https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector.git
+cd dingtalk-openclaw-connector
+
+# 2. Install dependencies (required)
+npm install
+
+# 3. Install in link mode (changes take effect immediately)
+openclaw plugins install -l .
+```
+
+#### Method C: Manual Installation
+
+1. Download or copy this repository to `~/.openclaw/extensions/dingtalk-connector`.
+2. Make sure it contains `index.ts`, `openclaw.plugin.json`, and `package.json`.
+3. Run `npm install` in that directory to install dependencies.
+
+#### Method D: China Mainland Installation (npm Mirror)
+
+If `openclaw plugins install` gets stuck at `Installing plugin dependencies...` or fails with `npm install failed` due to network issues in China, you can specify a mirror registry for that install:
+
+```bash
+NPM_CONFIG_REGISTRY=https://registry.npmmirror.com openclaw plugins install @dingtalk-real-ai/dingtalk-connector
+```
+
+If the plugin is in a partially installed state (e.g., the extension directory exists but dependencies are incomplete), you can manually reinstall dependencies:
+
+```bash
+cd ~/.openclaw/extensions/dingtalk-connector
+rm -rf node_modules package-lock.json
+NPM_CONFIG_REGISTRY=https://registry.npmmirror.com npm install
+```
+
+To make the mirror permanent, set the default npm registry:
+
+```bash
+npm config set registry https://registry.npmmirror.com
+```
+
+Or add to `~/.npmrc`:
+
+```
+registry=https://registry.npmmirror.com
+```
+
+**Verify installation**:
+```bash
+openclaw plugins list
+```
+You should see `✓ DingTalk Channel (v0.8.6) - 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:
+
+```json5
+{
+  "agents": {
+    "list": [
+      {
+        "id": "ding-bot1",
+        "name": "Customer Service Bot",
+        "model": "your-model-config",
+        "workspace": "~/.openclaw/workspace-bot1",
+        "identity": {
+          "name": "Service Assistant",
+          "theme": "customer service",
+          "emoji": "🤝"
+        }
+        // Other agent configurations...
+      },
+      {
+        "id": "ding-bot2",
+        "name": "Technical Support Bot",
+        "model": "your-model-config",
+        "workspace": "~/.openclaw/workspace-bot2",
+        "identity": {
+          "name": "Tech Expert",
+          "theme": "technical support",
+          "emoji": "🔧"
+        }
+        // Other agent configurations...
+      }
+    ]
+  },
+  "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 |
+
+---
+
+## DingTalk DEAP Agent Integration
+
+Connect DingTalk DEAP Agent with OpenClaw Gateway to enable natural language-driven local device operations. See **[DingTalk DEAP Agent Integration Guide](docs/DEAP_AGENT_GUIDE.en.md)** for details.
+
+---
+
+## License
+
+[MIT](LICENSE)
+
+---
+
+## Support
+
+- **Issues**: [GitHub Issues](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/issues)
+- **Changelog**: [CHANGELOG.md](CHANGELOG.md)

package/README.md

@@ -0,0 +1,209 @@
+<div align="center">
+
+<img src="https://tools.huo15.com/uploads/images/system/logo-colours.png" alt="火一五Logo" style="width: 120px; height: auto; display: inline; margin: 0;" />
+
+</div>
+
+<div align="center">
+
+**打破信息孤岛，用一套系统驱动企业增长**
+**加速企业用户向全场景人工智能机器人转变**
+
+</div>
+
+<div align="center">
+
+| 🏫 教学机构 | 👨‍🏫 讲师 | 📧 联系方式         | 💬 QQ群      | 📺 配套视频                         |
+|:-----------:|:--------:|:------------------:|:-----------:|:-----------------------------------:|
+| 逸寻智库 | Job | support@huo15.com | 1093992108  | [📺 B站视频](https://space.bilibili.com/400418085) |
+
+</div>
+
+---
+
+# 🔔 huo15-dingtalk-connector-pro
+
+> **作者**: 火一五信息科技有限公司
+> **版本**: v1.0.0
+> **参考**: [dingtalk-openclaw-connector](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector) v0.8.12
+> **触发词**: 钉钉、钉钉连接器、dingtalk
+
+---
+
+## 一、简介
+
+火一五定制版钉钉 OpenClaw 连接器，基于官方 dingtalk-openclaw-connector v0.8.12 定制，支持 huo15-memory-evolution 记忆系统集成和 Claude Code 能力增强。
+
+---
+
+## 二、核心特性
+
+| 特性 | 说明 |
+|------|------|
+| 🤖 **记忆系统集成** | 支持 huo15-memory-evolution 记忆系统 |
+| 💬 **AI Card 流式响应** | 打字机效果，实时流式显示回复 |
+| 🔒 **会话持久化** | 同一用户的多轮对话共享上下文 |
+| 🎯 **会话隔离** | 按单聊/群聊/群区分 session |
+| ⏰ **超时自动新会话** | 默认 30 分钟无活动自动开启新对话 |
+| 📁 **富媒体接收** | 支持 JPEG/PNG 图片、文件附件 |
+| 🎵 **音频消息** | 支持发送多种格式音频 |
+| 📄 **钉钉文档 API** | 支持创建、追加、搜索钉钉文档 |
+| 🔗 **多 Agent 路由** | 支持一个连接器实例连接多个 Agent |
+
+---
+
+## 三、快速开始
+
+### 3.1 前置要求
+
+- OpenClaw 已安装并运行
+- 钉钉企业账号
+
+### 3.2 安装
+
+```bash
+# 克隆仓库
+git clone https://github.com/huo15/huo15-dingtalk-connector-pro.git
+cd huo15-dingtalk-connector-pro
+
+# 安装依赖
+npm install
+
+# 以链接模式安装
+openclaw plugins install -l .
+```
+
+### 3.3 配置
+
+1. 获取钉钉凭证
+   - 访问 [钉钉开放平台](https://open-dev.dingtalk.com/)
+   - 创建企业内部应用
+   - 获取 AppKey 和 AppSecret
+
+2. 配置连接器
+
+```bash
+# 方式一：使用配置向导
+openclaw channels add
+
+# 方式二：直接编辑配置文件
+# macOS: ~/.openclaw/openclaw.json
+```
+
+```json
+{
+  "channels": {
+    "dingtalk-connector": {
+      "enabled": true,
+      "clientId": "你的AppKey",
+      "clientSecret": "你的AppSecret"
+    }
+  }
+}
+```
+
+### 3.4 重启验证
+
+```bash
+# 重启 Gateway
+openclaw gateway restart
+
+# 检查插件状态
+openclaw plugins list
+
+# 查看日志
+openclaw logs --follow
+```
+
+---
+
+## 四、完整功能列表
+
+### 4.1 基础功能
+
+- **AI Card 流式响应** - 打字机效果，实时显示 AI 回复
+- **会话管理** - 多轮对话共享上下文
+- **会话隔离** - 按单聊/群聊/群区分 session
+- **手动/自动会话重置** - 发送 /new 或 30分钟无活动自动新会话
+- **图片自动上传** - 自动上传到钉钉
+- **富媒体接收** - JPEG/PNG 图片，支持视觉模型
+- **文件附件** - 解析 .docx, .pdf, 文本, 二进制文件
+- **音频消息** - 支持 mp3, wav, amr, ogg 格式
+- **钉钉文档 API** - 创建、追加、搜索、列出文档
+- **多 Agent 路由** - 多个 bot 连接不同 agent
+- **Markdown 表格转换** - 自动转换为钉钉兼容格式
+
+---
+
+## 五、开发计划
+
+### 5.1 融合火一五记忆进化系统
+
+- [ ] 将 huo15-memory-evolution 集成到钉钉连接器
+- [ ] 实现会话记忆持久化
+- [ ] 支持 user/feedback/project/reference 四类记忆
+- [ ] 实现 Auto Capture 自动捕获高光时刻
+- [ ] 实现 Dream Agent 每日日志提炼
+
+### 5.2 融合 Claude Code 能力
+
+- [ ] 实现 findRelevantMemories 智能记忆检索
+- [ ] 实现 CLAUDE.md 项目级指令注入
+- [ ] 实现 Manifest pre-inject
+- [ ] 实现 Forked extraction 后台提取
+- [ ] 实现 Before recommending 规范
+
+---
+
+## 六、与官方版区别
+
+| 功能 | 官方版 | 定制版 |
+|------|--------|--------|
+| 基础功能 | ✅ | ✅ |
+| 记忆系统集成 | ❌ | ✅ huo15-memory-evolution |
+| Claude Code 能力 | ❌ | ✅ 进行中 |
+| AI Card 流式响应 | ✅ | ✅ |
+| 多 Agent 路由 | ✅ | ✅ |
+
+---
+
+## 七、项目结构
+
+```
+huo15-dingtalk-connector-pro/
+├── src/
+│   ├── core/           # 核心连接器逻辑
+│   ├── services/       # 钉钉 API 服务
+│   ├── utils/         # 工具函数
+│   └── types/          # TypeScript 类型定义
+├── docs/
+│   └── images/        # 文档图片
+├── openclaw.plugin.json # 插件清单
+├── package.json        # npm 依赖
+└── LICENSE
+```
+
+---
+
+## 八、相关链接
+
+- **官方版**: https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector
+- **OpenClaw**: https://openclaw.ai
+- **火一五记忆系统**: https://clawhub.ai/jobzhao15/huo15-memory-evolution
+- **钉钉开放平台**: https://open-dev.dingtalk.com/
+
+---
+
+<div align="center">
+
+**公司名称：** 青岛火一五信息科技有限公司
+
+**联系邮箱：** postmaster@huo15.com | **QQ群：** 1093992108
+
+---
+
+**关注逸寻智库公众号，获取更多资讯**
+
+<img src="https://tools.huo15.com/uploads/images/system/qrcode_yxzk.jpg" alt="逸寻智库公众号二维码" style="width: 200px; height: auto; margin: 10px 0;" />
+
+</div>