@dingtalk-real-ai/dingtalk-connector 0.8.7 → 0.8.8

package/CHANGELOG.md

@@ -5,6 +5,31 @@ All notable changes to this project will be documented in this file.
 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.8.8] - 2026-03-29
+
+### 修复 / Fixes
+- 🐛 **多 block 流式响应产生多条独立气泡** ([#369](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/issues/369)) - 重构 `startStreaming` 并发控制逻辑，从 `isCreatingCard` 布尔标志改为 `cardCreationPromise`，彻底消除多 block 响应场景下每个 block 新建独立 AI Card 气泡的问题  
+  **Multi-block streaming response creates multiple bubbles** - Refactored `startStreaming` concurrency control from boolean flag to `cardCreationPromise`, eliminating independent AI Card bubbles per block in multi-block responses
+
+- 🐛 **Web UI Connected / Last inbound 显示 n/a** - 新增 `onStatusChange` 回调在连接建立/断开/收到消息时上报状态字段；补全 `buildSessionContext` 中 `conversationId` 和 `groupSubject` 字段透传  
+  **Web UI shows n/a for Connected and Last inbound** - Added `onStatusChange` callback to report status fields on connection events; fixed `buildSessionContext` field passthrough
+
+- 🐛 **AI Card 函数调用参数错误** - 修复 `reply-dispatcher.ts` 中 `createAICardForTarget`、`streamAICard`、`finishAICard` 参数从 `params.runtime` 改为 `account.config/log`  
+  **AI Card function call parameter error** - Fixed parameters in `reply-dispatcher.ts` from `params.runtime` to `account.config/log`
+
+- 🐛 **sendFileProactive 参数错误导致文件发送失败** - 修复 `processFileMarkers` 和 `processRawMediaPaths` 错误传入 `downloadUrl`，改为正确的 `cleanMediaId`  
+  **File sending failure due to wrong sendFileProactive parameter** - Fixed incorrect `downloadUrl` parameter, now correctly uses `cleanMediaId`
+
+- 🐛 **纯多账号配置下 probe 被跳过** ([#381](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/issues/381)) - `getStatus()` 改用 `resolveDingtalkAccount()` 统一获取账号信息，修复纯多账号配置下状态显示不准确的问题  
+  **Probe skipped in pure multi-account config** - `getStatus()` now uses `resolveDingtalkAccount()` for unified account resolution
+
+### 改进 / Improvements
+- ✅ **音频时长提取安全性改进** ([#134](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/issues/134)) - `extractAudioDuration` 改用 `fluent-ffmpeg` 的 `ffprobe` API，消除安全扫描误报  
+  **Audio duration extraction security improvement** - Changed to `fluent-ffmpeg` `ffprobe` API, eliminating security scan false positives
+
+- ✅ **SDK 接口迁移** - `onboarding.ts` 类型引用迁移到新版 `ChannelSetupWizardAdapter`，导入路径更新为 `openclaw/plugin-sdk/setup`  
+  **SDK interface migration** - Migrated to `ChannelSetupWizardAdapter` and updated import path to `openclaw/plugin-sdk/setup`
+
 ## [0.8.7] - 2026-03-26
 
 ### 修复 / Fixes

package/README.en.md

@@ -19,6 +19,7 @@
 - [Configuration](#configuration)
 - [Troubleshooting](#troubleshooting)
 - [Advanced Topics](#advanced-topics)
+- [DingTalk DEAP Agent Integration](docs/DEAP_AGENT_GUIDE.en.md)
 - [License](#license)
 
 ---
@@ -61,19 +62,67 @@ Whenever you see `~/.openclaw/openclaw.json` below, it is equivalent to the abov
 
 ### Step 1: Install the Plugin
 
+#### Method A: Install via npm (Recommended)
+
 ```bash
-# Recommended: Install from npm
 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:
 
-# Alternative: Install from Git
-openclaw plugins install https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector.git
+```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.0) - loaded`
+You should see `✓ DingTalk Channel (v0.8.6) - loaded`
 
 ---
 
@@ -412,6 +461,12 @@ dingtalk-openclaw-connector/
 
 ---
 
+## 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)

package/README.md

@@ -19,6 +19,7 @@
 - [配置说明](#配置说明)
 - [常见问题](#常见问题)
 - [进阶主题](#进阶主题)
+- [钉钉 DEAP Agent 集成](docs/DEAP_AGENT_GUIDE.md)
 - [许可证](#许可证)
 
 ---
@@ -93,19 +94,67 @@ yarn global add openclaw@latest
 
 ### 步骤 1：安装插件
 
+#### 方法 A：通过 npm 包安装（推荐）
+
 ```bash
-# 推荐：从 npm 安装
 openclaw plugins install @dingtalk-real-ai/dingtalk-connector
+```
+
+#### 方法 B：通过本地源码安装
+
+如果你想对插件进行二次开发，可以先克隆仓库：
+
+```bash
+# 1. 克隆插件仓库
+git clone https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector.git
+cd dingtalk-openclaw-connector
+
+# 2. 安装依赖（必需）
+npm install
+
+# 3. 以链接模式安装（方便修改代码后实时生效）
+openclaw plugins install -l .
+```
+
+#### 方法 C：手动安装
+
+1. 将本仓库下载或复制到 `~/.openclaw/extensions/dingtalk-connector`。
+2. 确保包含 `index.ts`、`openclaw.plugin.json` 和 `package.json`。
+3. 在该目录下运行 `npm install` 安装依赖。
+
+#### 方法 D：国内网络环境安装（npm 镜像源）
+
+如果你在国内网络环境下执行 `openclaw plugins install` 时卡在 `Installing plugin dependencies...` 或出现 `npm install failed`，可临时为该次安装指定镜像源：
+
+```bash
+NPM_CONFIG_REGISTRY=https://registry.npmmirror.com openclaw plugins install @dingtalk-real-ai/dingtalk-connector
+```
+
+如果插件已处于半安装状态（例如扩展目录存在但依赖未装全），可进入插件目录手动补装依赖：
+
+```bash
+cd ~/.openclaw/extensions/dingtalk-connector
+rm -rf node_modules package-lock.json
+NPM_CONFIG_REGISTRY=https://registry.npmmirror.com npm install
+```
+
+如果希望长期生效，可设置 npm 默认镜像：
 
-# 或者：从 Git 安装
-openclaw plugins install https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector.git
+```bash
+npm config set registry https://registry.npmmirror.com
+```
+
+或写入 `~/.npmrc`：
+
+```
+registry=https://registry.npmmirror.com
 ```
 
 **验证安装**：
 ```bash
 openclaw plugins list
 ```
-你应该看到 `✓ DingTalk Channel (v0.8.0) - loaded`
+你应该看到 `✓ DingTalk Channel (v0.8.6) - loaded`
 
 ---
 
@@ -455,6 +504,12 @@ dingtalk-openclaw-connector/
 
 ---
 
+## 钉钉 DEAP Agent 集成
+
+通过钉钉 DEAP Agent 与 OpenClaw Gateway 连接，实现自然语言驱动的本地设备操作能力。详见 **[钉钉 DEAP Agent 集成指南](docs/DEAP_AGENT_GUIDE.md)**。
+
+---
+
 ## 许可证
 
 [MIT](LICENSE)

package/docs/DEAP_AGENT_GUIDE.en.md

@@ -0,0 +1,115 @@
+# DingTalk DEAP Agent Integration
+
+> [中文版](DEAP_AGENT_GUIDE.md)
+
+Connect DingTalk [DEAP](https://deap.dingtalk.com) Agent with [OpenClaw](https://openclaw.ai) Gateway to enable natural language-driven local device operations.
+
+## Key Features
+
+- ✅ **Natural Language Interaction** - Users type natural language commands in the DingTalk chat (e.g., "Find PDF files on my desktop"), and the Agent automatically parses and executes the corresponding operations
+- ✅ **NAT Traversal** - Designed for local devices without public IPs, establishing a stable communication tunnel between local and cloud environments via the Connector client
+- ✅ **Cross-Platform Support** - Provides native binaries for Windows, macOS, and Linux, ensuring smooth operation across all platforms
+
+## System Architecture
+
+This solution uses a layered architecture with three core components:
+
+1. **OpenClaw Gateway** - Deployed on the local device, provides a standardized HTTP interface for receiving and processing operation commands from the cloud, leveraging the OpenClaw engine to execute tasks
+2. **DingTalk OpenClaw Connector** - Runs locally, building a communication tunnel between local and cloud environments to solve the problem of local devices without public IPs
+3. **DingTalk DEAP MCP** - An extension module for the DEAP Agent, responsible for forwarding user natural language requests to the OpenClaw Gateway via the cloud tunnel
+
+```mermaid
+graph LR
+    subgraph "DingTalk App"
+        A["User chats with Agent"] --> B["DEAP Agent"]
+    end
+
+    subgraph "Local Environment"
+        D["DingTalk OpenClaw Connector"] --> C["OpenClaw Gateway"]
+        C --> E["PC Operation Execution"]
+    end
+
+    B -.-> D
+```
+
+## Implementation Guide
+
+### Step 1: Set Up the Local Environment
+
+Ensure the OpenClaw Gateway is installed and running on your local device. The default address is `127.0.0.1:18789`:
+
+```bash
+openclaw gateway start
+```
+
+#### Configure Gateway Parameters
+
+1. Visit the [Configuration Page](http://127.0.0.1:18789/config)
+2. In the **Overview**, set the Gateway Token and save it securely:
+   ![alt text](images/image-5.png)
+3. Switch to **Infrastructure** and enable the `OpenAI Chat Completions Endpoint`:
+   ![alt text](images/image-6.png)
+
+4. Click the `Save` button in the top-right corner to save your configuration
+
+### Step 2: Obtain Required Parameters
+
+#### Get corpId
+
+Log in to the [DingTalk Developer Platform](https://open-dev.dingtalk.com) to find your enterprise CorpId:
+
+<img width="864" height="450" alt="Get corpId from DingTalk Developer Platform" src="https://github.com/user-attachments/assets/18ec9830-2d43-489a-a73f-530972685225" />
+
+#### Get apiKey
+
+Log in to the [DingTalk DEAP Platform](https://deap.dingtalk.com), navigate to **Security & Permissions** → **API-Key Management** to create a new API Key:
+
+<img width="1222" height="545" alt="DingTalk DEAP Platform API-Key Management" src="https://github.com/user-attachments/assets/dfe29984-4432-49c1-8226-0f9b60fbb5bc" />
+
+### Step 3: Start the Connector Client
+
+1. Download the installer for your operating system from the [Releases](https://github.com/hoskii/dingtalk-openclaw-connector/releases/tag/v0.0.1) page
+2. Extract and run the Connector in the corresponding directory (macOS example):
+
+   ```bash
+   unzip connector-mac.zip
+   ./connector-darwin -deapCorpId YOUR_CORP_ID -deapApiKey YOUR_API_KEY
+   ```
+   ![alt text](images/image-7.png)
+
+### Step 4: Configure the DEAP Agent
+
+1. Log in to the [DingTalk DEAP Platform](https://deap.dingtalk.com) and create a new agent:
+
+   <img width="2444" height="1486" alt="Create New Agent" src="https://github.com/user-attachments/assets/0b7f0855-f991-4aeb-b6e6-7576346b4477" />
+
+2. In the skill management page, search for and integrate the OpenClaw skill:
+
+   <img width="3430" height="1732" alt="Add OpenClaw Skill" src="https://github.com/user-attachments/assets/d44f0038-f863-4c1f-afa7-b774d875e4ba" />
+
+3. Configure skill parameters:
+
+   | Parameter    | Source     | Description                                                                            |
+   | ------------ | ---------- | -------------------------------------------------------------------------------------- |
+   | apikey       | From Step 2 | DEAP Platform API Key                                                                  |
+   | apihost      | Default     | Typically `127.0.0.1:18789`. On Windows, you may need to use `localhost:18789` instead |
+   | gatewayToken | From Step 1 | Gateway authentication token                                                           |
+
+   <img width="3426" height="1752" alt="Configure OpenClaw Skill Parameters" src="https://github.com/user-attachments/assets/bc725789-382f-41b5-bbdb-ba8f29923d5c" />
+
+Note that OpenClaw is an MCP, so you also need to configure its trigger rules. The MCP will only be invoked when the rules are satisfied:
+<img width="1088" height="526" alt="image" src="https://github.com/user-attachments/assets/8b0b6f6d-70ff-4edc-b674-7a24126aadfa" />
+
+4. Publish the Agent:
+
+   <img width="3416" height="1762" alt="Publish Agent" src="https://github.com/user-attachments/assets/3f8c3fdb-5f2b-4a4b-8896-35202e713bf3" />
+
+### Step 5: Start Using
+
+1. Search for and find your Agent in the DingTalk App:
+
+   <img width="1260" height="436" alt="Search for Agent" src="https://github.com/user-attachments/assets/30feff80-1b28-4274-830b-7045aed14980" />
+
+2. Start your natural language conversation:
+
+   <img width="1896" height="1240" alt="Chat with Agent" src="https://github.com/user-attachments/assets/2a80aab8-3fbf-4d18-beea-770577cb1a40" />

package/docs/DEAP_AGENT_GUIDE.md

@@ -0,0 +1,115 @@
+# 钉钉 DEAP Agent 集成
+
+> [English Version](DEAP_AGENT_GUIDE.en.md)
+
+通过将钉钉 [DEAP](https://deap.dingtalk.com) Agent 与 [OpenClaw](https://openclaw.ai) Gateway 连接，实现自然语言驱动的本地设备操作能力。
+
+## 核心功能
+
+- ✅ **自然语言交互** - 用户在钉钉对话框中输入自然语言指令（如"帮我查找桌面上的 PDF 文件"），Agent 将自动解析并执行相应操作
+- ✅ **内网穿透机制** - 专为本地设备无公网 IP 场景设计，通过 Connector 客户端建立稳定的内外网通信隧道
+- ✅ **跨平台兼容** - 提供 Windows、macOS 和 Linux 系统的原生二进制执行文件，确保各平台下的顺畅运行
+
+## 系统架构
+
+该方案采用分层架构模式，包含三个核心组件：
+
+1. **OpenClaw Gateway** - 部署于本地设备，提供标准化 HTTP 接口，负责接收并处理来自云端的操作指令，调动 OpenClaw 引擎执行具体任务
+2. **DingTalk OpenClaw Connector** - 运行于本地环境，构建本地与云端的通信隧道，解决内网设备无公网 IP 的问题
+3. **DingTalk DEAP MCP** - 作为 DEAP Agent 的扩展能力模块，负责将用户自然语言请求经由云端隧道转发至 OpenClaw Gateway
+
+```mermaid
+graph LR
+    subgraph "钉钉 App"
+        A["用户与 Agent 对话"] --> B["DEAP Agent"]
+    end
+
+    subgraph "本地环境"
+        D["DingTalk OpenClaw Connector"] --> C["OpenClaw Gateway"]
+        C --> E["PC 操作执行"]
+    end
+
+    B -.-> D
+```
+
+## 实施指南
+
+### 第一步：部署本地环境
+
+确认本地设备已成功安装并启动 OpenClaw Gateway，默认监听地址为 `127.0.0.1:18789`：
+
+```bash
+openclaw gateway start
+```
+
+#### 配置 Gateway 参数
+
+1. 访问 [配置页面](http://127.0.0.1:18789/config)
+2. 在 **概览** 中设置 Gateway Token 并妥善保存：
+   ![alt text](images/image-5.png)
+3. 切换至 **基础设施**，启用 `OpenAI Chat Completions Endpoint` 功能：
+   ![alt text](images/image-6.png)
+
+4. 点击右上角 `Save` 按钮完成配置保存
+
+### 第二步：获取必要参数
+
+#### 获取 corpId
+
+登录 [钉钉开发者平台](https://open-dev.dingtalk.com) 查看企业 CorpId：
+
+<img width="864" height="450" alt="钉钉开发者平台获取 corpId" src="https://github.com/user-attachments/assets/18ec9830-2d43-489a-a73f-530972685225" />
+
+#### 获取 apiKey
+
+登录 [钉钉 DEAP 平台](https://deap.dingtalk.com)，在 **安全与权限** → **API-Key 管理** 页面创建新的 API Key：
+
+<img width="1222" height="545" alt="钉钉 DEAP 平台 API-Key 管理" src="https://github.com/user-attachments/assets/dfe29984-4432-49c1-8226-0f9b60fbb5bc" />
+
+### 第三步：启动 Connector 客户端
+
+1. 从 [Releases](https://github.com/hoskii/dingtalk-openclaw-connector/releases/tag/v0.0.1) 页面下载适配您操作系统的安装包
+2. 解压后在对应目录运行 Connector（以 macOS 为例）：
+
+   ```bash
+   unzip connector-mac.zip
+   ./connector-darwin -deapCorpId YOUR_CORP_ID -deapApiKey YOUR_API_KEY
+   ```
+   ![alt text](images/image-7.png)
+
+### 第四步：配置 DEAP Agent
+
+1. 登录 [钉钉 DEAP 平台](https://deap.dingtalk.com)，创建新的智能体：
+
+   <img width="2444" height="1486" alt="新建智能体界面" src="https://github.com/user-attachments/assets/0b7f0855-f991-4aeb-b6e6-7576346b4477" />
+
+2. 在技能管理页面，搜索并集成 OpenClaw 技能：
+
+   <img width="3430" height="1732" alt="添加 OpenClaw 技能" src="https://github.com/user-attachments/assets/d44f0038-f863-4c1f-afa7-b774d875e4ba" />
+
+3. 配置技能参数：
+
+   | 参数         | 来源       | 说明                                                                                   |
+   | ------------ | ---------- | -------------------------------------------------------------------------------------- |
+   | apikey       | 第二步获取 | DEAP 平台 API Key                                                                      |
+   | apihost      | 默认值     | 通常为 `127.0.0.1:18789`，在Windows环境下可能需要配置为 `localhost:18789` 才能正常工作 |
+   | gatewayToken | 第一步获取 | Gateway 配置的认证令牌                                                                 |
+
+   <img width="3426" height="1752" alt="配置 OpenClaw 技能参数" src="https://github.com/user-attachments/assets/bc725789-382f-41b5-bbdb-ba8f29923d5c" />
+
+注意 OpenClaw 属于一个MCP，还需要配置他的触发规则，满足规则的情况下才会使用这个MCP:
+<img width="1088" height="526" alt="image" src="https://github.com/user-attachments/assets/8b0b6f6d-70ff-4edc-b674-7a24126aadfa" />
+
+4. 发布 Agent：
+
+   <img width="3416" height="1762" alt="发布 Agent" src="https://github.com/user-attachments/assets/3f8c3fdb-5f2b-4a4b-8896-35202e713bf3" />
+
+### 第五步：开始使用
+
+1. 在钉钉 App 中搜索并找到您创建的 Agent：
+
+   <img width="1260" height="436" alt="搜索 Agent" src="https://github.com/user-attachments/assets/30feff80-1b28-4274-830b-7045aed14980" />
+
+2. 开始自然语言对话体验：
+
+   <img width="1896" height="1240" alt="与 Agent 对话" src="https://github.com/user-attachments/assets/2a80aab8-3fbf-4d18-beea-770577cb1a40" />

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "dingtalk-connector",
   "name": "DingTalk Channel",
-  "version": "0.8.7",
+  "version": "0.8.8",
   "description": "DingTalk (钉钉) messaging channel via Stream mode with AI Card streaming",
   "author": "DingTalk Real Team",
   "main": "index.ts",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dingtalk-real-ai/dingtalk-connector",
-  "version": "0.8.7",
+  "version": "0.8.8",
   "description": "DingTalk (钉钉) channel connector — Stream mode with AI Card streaming",
   "main": "index.ts",
   "type": "module",
@@ -44,18 +44,22 @@
     "access": "public"
   },
   "dependencies": {
-    "@ffmpeg-installer/ffmpeg": "^1.1.0",
-    "@ffprobe-installer/ffprobe": "^2.1.2",
     "axios": "^1.6.0",
     "dingtalk-stream": "2.1.4",
     "fluent-ffmpeg": "^2.1.3",
     "form-data": "^4.0.0",
     "mammoth": "^1.8.0",
-    "openclaw": "^2026.3.23-2",
     "pako": "^2.1.0",
     "pdf-parse": "^1.1.1",
     "zod": "^3.22.0"
   },
+  "peerDependencies": {
+    "openclaw": "^2026.3.23-2"
+  },
+  "optionalDependencies": {
+    "@ffmpeg-installer/ffmpeg": "^1.1.0",
+    "@ffprobe-installer/ffprobe": "^2.1.2"
+  },
   "devDependencies": {
     "@types/node": "^20.19.37",
     "@vitest/coverage-v8": "^2.0.0",

package/skills/dws/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: dws
+description: 管理钉钉产品能力(AI表格/日历/通讯录/文档/机器人/待办/邮箱/听记/AI应用/审批/日志/钉盘等)。当用户需要操作表格数据、管理日程会议、查询通讯录、发送消息通知、处理审批流程、查看听记摘要、创建应用/系统/管理后台/业务工具、查看或提交日报周报（钉钉日志模版）、管理钉盘文件时使用、钉钉技能市场搜索及下载。
+cli_version: ">=0.2.14"
+---
+
+# 钉钉全产品 Skill
+
+通过 `dws` 命令管理钉钉产品能力。
+
+## 严格禁止 (NEVER DO)
+- 不要使用 dws 命令以外的方式操作（禁止 curl、HTTP API、浏览器）
+- 不要编造 UUID、ID 等标识符，必须从命令返回中提取
+- 不要编造 URL、Email、手机号等结构化信息，禁止猜测
+- 不要猜测字段名/参数值，操作前必须先查询确认
+
+## 严格要求 (MUST DO)
+- 所有命令必须加 `--format json` 以获取可解析输出
+- 危险操作必须先向用户确认，用户同意后才加 `--yes` 执行
+- 单次批量操作不超过 30 条记录
+- 所有命令必须**严格遵循**对应产品参考文档里面规定的参数格式（如：如果有参数值，则参数和参数值之间至少用一个空格隔开）
+- URL 必须从产品参考文件或 [链接规范](./references/url-patterns.md) 中查找模板，或使用命令返回的完整链接，无法获取时告知用户无法提供
+- Email/手机号必须从命令返回中提取或由用户明确提供，无法获取时主动询问用户
+
+
+## 产品总览
+
+| 产品                | 用途                                                   | 参考文件                                                           |
+|-------------------|------------------------------------------------------|----------------------------------------------------------------|
+| `aitable`         | AI表格：表格/数据表/字段/记录增删改查/模板搜索                           | [aitable.md](./references/products/aitable.md)                 |
+| `calendar`        | 日历：日程/参与者/会议室/闲忙查询                                   | [calendar.md](./references/products/calendar.md)               |
+| `contact`         | 通讯录：用户查询(当前用户/搜索/详情)/部门查询(搜索/子部门/成员列表)               | [contact.md](./references/products/contact.md)                 |
+| `doc`             | 文档：搜索/浏览/读取/创建/更新文档/文件夹管理/块级编辑                       | [doc.md](./references/products/doc.md)                         |
+| `chat`            | 群聊：群管理(建群/搜索/成员增删/改群名)/消息(拉取/发送/机器人群发/Webhook)/机器人搜索 | [chat.md](./references/products/chat.md)                       |
+| `todo`            | 待办：创建(含优先级/截止时间)/查询/修改/标记完成/删除                       | [todo.md](./references/products/todo.md)                       |
+| `mail`            | 邮箱：查询邮箱/搜索/查看/发送邮件                                   | [mail.md](./references/products/mail.md)                       |
+| `minutes`         | AI听记：列表/摘要/转写/关键字/标题修改                               | [minutes.md](./references/products/minutes.md)                 |
+| `report`          | 日志：按模版创建/收件箱/已发送/模版查看/详情/已读统计                         | [report.md](./references/products/report.md)                   |
+| `drive`           | 钉盘：浏览文件/元数据/下载/创建文件夹/上传文件                            | [drive.md](./references/products/drive.md)                     |
+| `ding`            | DING消息：发送/撤回（应用内/短信/电话）                              | [ding.md](./references/products/ding.md)                       |
+| `devdoc`          | 开放平台文档：搜索开发文档                                        | [simple.md](./references/products/simple.md)                   |
+| `conference`      | 视频会议：预约会议                                            | [simple.md](./references/products/simple.md)                   |
+| `aiapp`           | AI应用：创建/查询/修改AI应用                                    | [aiapp.md](./references/products/aiapp.md)                     |
+| `live`            | 直播：查看直播列表                                            | [simple.md](./references/products/simple.md)                   |
+| `oa`              | OA审批：待处理/详情/同意/拒绝/撤销/记录/已发起/任务                       | [oa.md](./references/products/oa.md)                           |
+| `attendance`      | 考勤：打卡记录/排班查询                                         | [attendance.md](./references/products/attendance.md)           |
+| `skill`           | 技能市场：搜索/下载                                         | [simple.md](./references/products/simple.md)           |
+
+## 意图判断决策树
+
+用户提到"表格/多维表/AI表格/记录/数据" → `aitable`
+用户提到"日程/日历/会议室/约会" → `calendar`
+用户提到"通讯录/同事/部门/组织架构" → `contact`
+用户提到"文档/知识库/写文档"以及用户传入文档URL（如 `https://alidocs.dingtalk.com/*`） → `doc`
+用户提到"待办/TODO/任务提醒" → `todo`
+用户提到"邮件/邮箱" → `mail`
+用户提到"听记/会议录音/转写/AI摘要"以及用户传入听记URL（如 `https://shanji.dingtalk.com/*`） → `minutes`
+用户提到"帮我做/建/生成/生成系统/AI应用/创建应用/智能应用" → `aiapp`
+用户提到"DING/紧急消息/电话提醒" → `ding`
+用户提到"考勤/打卡/排班" → `attendance`
+用户提到"群聊/群消息/群成员/聊天记录/建群/机器人发消息/Webhook/通知" → `chat`
+用户提到"审批/OA" → `oa`
+用户提到"开发/API/调用错误 文档" → `devdoc`
+用户提到"视频会议/预约会议" → `conference`
+用户提到"直播" → `live`
+用户提到"日志/日报/周报/日志统计/写日报/提交周报/发日志/填日志" → `report`
+用户提到"钉盘/文件/网盘/下载文件/上传文件" → `drive`
+用户提到"技能市场/查找技能" → `skill`
+
+关键区分: aitable(数据表格) vs doc(文档编辑)
+关键区分: report(钉钉日志/日报周报) vs doc(文档编辑) vs todo(待办任务)
+关键区分: drive(钉盘文件存储/上传/下载) vs doc(钉钉文档内容读写/知识库空间)
+关键区分: conference(视频会议预约) vs calendar event(日历日程管理)
+关键区分: chat message send(个人身份群发) vs send-by-bot(机器人发消息) vs send-by-webhook(Webhook告警)
+
+
+> 更多易混淆场景及用户表达示例，见 [intent-guide.md](./references/intent-guide.md)
+
+## 危险操作确认
+
+以下操作为不可逆或高影响操作，执行前**必须先向用户展示操作摘要并获得明确同意**，同意后才加 `--yes` 执行。
+
+| 产品 | 命令 | 说明 |
+|------|------|------|
+| `aitable` | `base delete` | 删除整个 AI 表格，含全部数据表和记录 |
+| `aitable` | `table delete` | 删除数据表，含全部记录 |
+| `aitable` | `field delete` | 删除字段，该列数据不可恢复 |
+| `aitable` | `record delete` | 删除记录（支持批量） |
+| `calendar` | `event delete` | 删除日程，所有参与者同步取消 |
+| `calendar` | `participant delete` | 移除日程参与者 |
+| `calendar` | `room delete` | 取消会议室预定 |
+| `todo` | `task delete` | 删除待办 |
+| `doc` | `block delete` | 删除文档块元素 |
+| `oa` | `approval approve/reject` | 同意或拒绝审批（审批决策不可撤回） |
+
+### 确认流程
+```
+Step 1 → 展示操作摘要（操作类型 + 目标对象 + 影响范围）
+Step 2 → 用户明确回复确认（如 "确认" / "好的"）
+Step 3 → 加 --yes 执行命令
+```
+
+## 核心流程
+作为一个智能助手，你的首要任务是**理解用户的真实、完整的意图**，而不是简单地执行命令。在选择 `dws` 的产品命令前，必须严格遵循以下四步流程：
+
+1. 意图分类：首先，判断用户指令的核心 动词/动作 属于哪一类。这比关注名词更重要。
+2. 歧义处理与信息追问：如果用户指令模糊或包含多个产品的关键字，严禁猜测。必须主动向用户追问以澄清意图。这是你作为智能助手而非命令执行器的核心价值。
+3. 精准产品映射：在完成前两步，意图已经清晰后，参考产品总览和意图判断决策树 来选择产品。
+4. 充分阅读产品参考文件，通过编写代码或直接调用指令实现用户意图。
+
+## 错误处理
+1. 遇到错误，加 `--verbose` 重试一次
+2. 仍然失败，报告完整错误信息给用户，禁止自行尝试替代方案
+3. 认证失败时，参考 [global-reference.md](./references/global-reference.md) 中的认证章节处理
+4. 各产品高频错误及排查流程见 [error-codes.md](./references/error-codes.md)
+
+## 详细参考 (按需读取)
+
+- [references/products/](./references/products/) — 各产品命令详细参考
+- [references/intent-guide.md](./references/intent-guide.md) — 意图路由指南（易混淆场景对照）
+- [references/global-reference.md](./references/global-reference.md) — 全局标志、认证、输出格式
+- [references/field-rules.md](./references/field-rules.md) — AI表格字段类型规则
+- [references/error-codes.md](./references/error-codes.md) — 错误码 + 调试流程
+- [scripts/](./scripts/) — 各产品批量操作脚本（AI表格/日历/群聊/通讯录/文档/钉盘/邮箱/听记/审批/日志/待办等）