back
loading skill details...
基于钉钉官方CLI工具dws,实现消息发送、日程管理、待办事项、通讯录查询及机器人消息自动化操作。
# DingTalk CLI Auto Skill
钉钉 CLI 自动化技能 - 基于钉钉官方 CLI 工具 (dws) 实现企业自动化功能。
## Description
本 Skill 封装了钉钉官方 CLI 工具 `dws` (DingTalk Workspace CLI),提供以下企业自动化能力:
- 📨 **消息管理**: 发送文本/Markdown消息给联系人或群聊
- 📅 **日程管理**: 创建日程、查询空闲时段、查看日程列表
- ✅ **待办事项**: 创建、完成、删除、查询待办
- 👥 **通讯录**: 搜索联系人、查询部门成员
- 🤖 **机器人交互**: 发送群机器人消息
## Prerequisites
### 1. 安装 dws CLI
```bash
# Linux/macOS
curl -fsSL https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-workspace-cli/main/scripts/install.sh | sh
# Windows PowerShell
irm https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-workspace-cli/main/scripts/install.ps1 | iex
```
### 2. 钉钉开放平台配置
1. 访问 [钉钉开放平台](https://open.dingtalk.com/) 创建企业内部应用
2. 获取 `AppKey` 和 `AppSecret`
3. 配置应用权限:
- 通讯录管理
- 日程管理
- 待办管理
- 群机器人消息
4. 发布应用
### 3. 环境变量配置
```bash
export DWS_CLIENT_ID="your-app-key"
export DWS_CLIENT_SECRET="your-app-secret"
```
或使用 OpenClaw 环境配置:
```bash
openclaw config set dingtalk.app_key your-app-key
openclaw config set dingtalk.app_secret your-app-secret
```
### 4. 首次认证
```bash
dws auth login
```
按提示完成 OAuth 设备流认证。
## Tools
### 发送消息
#### `send_text_message`
发送文本消息给指定用户或群聊
```bash
# 给用户发送消息
node scripts/message.js send-text --user-id "user123" --content "Hello, this is a test message"
# 给群聊发送消息
node scripts/message.js send-text --chat-id "chat123" --content "Group notification"
```
#### `send_markdown_message`
发送 Markdown 格式消息
```bash
node scripts/message.js send-md --user-id "user123" --title "通知" --content "**重要提醒**:会议即将开始"
```
### 日程管理
#### `create_schedule`
创建日程/会议
```bash
node scripts/calendar.js create \
--title "周例会" \
--start "2026-04-03T14:00:00" \
--end "2026-04-03T15:00:00" \
--attendees "user1,user2,user3" \
--location "会议室A"
```
#### `list_schedules`
查询日程列表
```bash
# 查询今天的日程
node scripts/calendar.js list --today
# 查询指定日期范围
node scripts/calendar.js list --start "2026-04-01" --end "2026-04-07"
```
#### `check_free_busy`
查询用户空闲时间
```bash
node scripts/calendar.js free-busy \
--users "user1,user2" \
--start "2026-04-03T09:00:00" \
--end "2026-04-03T18:00:00"
```
### 待办事项
#### `create_todo`
创建待办事项
```bash
node scripts/todo.js create \
--content "完成项目文档" \
--due "2026-04-05T18:00:00" \
--assignees "user1"
```
#### `list_todos`
查询待办列表
```bash
# 所有待办
node scripts/todo.js list
# 即将到期的待办
node scripts/todo.js list --due-within 3
```
#### `complete_todo`
完成待办
```bash
node scripts/todo.js complete --id "todo123"
```
#### `delete_todo`
删除待办
```bash
node scripts/todo.js delete --id "todo123"
```
### 通讯录
#### `search_contacts`
搜索联系人
```bash
# 按姓名搜索
node scripts/contact.js search --name "张三"
# 按部门搜索
node scripts/contact.js search --dept "技术部"
```
#### `get_department_members`
获取部门成员列表
```bash
node scripts/contact.js dept-members --dept-id "dept123"
```
### 机器人消息
#### `send_robot_message`
发送群机器人消息
```bash
node scripts/robot.js send \
--webhook "https://oapi.dingtalk.com/robot/send?access_token=xxx" \
--secret "SECxxx" \
--content "机器人通知消息"
```
## Usage Examples
### 场景 1: 每日待办提醒
```bash
# 获取今日待办
node scripts/todo.js list --today
# 创建今日待办
node scripts/todo.js create --content "提交日报" --due "today 18:00"
```
### 场景 2: 会议通知
```bash
# 搜索参会人员
node scripts/contact.js search --name "张三"
# 检查空闲时间
node scripts/calendar.js free-busy --users "user1,user2" --duration 60
# 创建会议
node scripts/calendar.js create \
--title "项目评审会" \
--start "2026-04-03T14:00:00" \
--duration 60 \
--attendees "user1,user2"
# 发送会议提醒
node scripts/message.js send-md \
--chat-id "chat123" \
--title "会议提醒" \
--content "**项目评审会** 将于14:00开始,请准时参加"
```
### 场景 3: 任务分派
```bash
# 查找成员
node scripts/contact.js search --name "李四"
# 创建并分派待办
node scripts/todo.js create \
--content "完成API文档编写" \
--assignees "user2" \
--due "2026-04-05"
# 发送通知
node scripts/message.js send-text \
--user-id "user2" \
--content "你有一个新的待办任务:完成API文档编写,截止2026-04-05"
```
## API Reference
### 命令行参数规范
所有脚本遵循统一的参数规范:
| 参数 | 说明 | 示例 |
|------|------|------|
| `--user-id` | 用户ID | `user123` |
| `--chat-id` | 群聊ID | `chat456` |
| `--content` | 消息/内容 | `Hello World` |
| `--title` | 标题 | `会议通知` |
| `--start` | 开始时间 | `2026-04-03T14:00:00` |
| `--end` | 结束时间 | `2026-04-03T15:00:00` |
| `--duration` | 持续时间(分钟) | `60` |
| `--attendees` | 参会人(逗号分隔) | `user1,user2` |
| `--assignees` | 负责人(逗号分隔) | `user1` |
| `--due` | 截止日期 | `2026-04-05` 或 `today` |
| `--dept-id` | 部门ID | `dept123` |
| `--name` | 姓名 | `张三` |
| `--dept` | 部门名称 | `技术部` |
| `--webhook` | 机器人Webhook | `https://...` |
| `--secret` | 机器人密钥 | `SEC...` |
### 时间格式
- ISO 8601: `2026-04-03T14:00:00`
- 相对时间: `today`, `tomorrow`, `+3d` (3天后)
- 自然语言: `今天18:00`, `明天上午9点`
## Error Handling
### 常见错误
| 错误码 | 说明 | 解决方案 |
|--------|------|----------|
| 401 | 未认证或Token过期 | 执行 `dws auth login` |
| 403 | 权限不足 | 检查应用权限配置 |
| 404 | 用户/群聊不存在 | 检查ID是否正确 |
| 400 | 参数错误 | 检查参数格式 |
| 429 | 请求过于频繁 | 稍后重试 |
### 调试模式
添加 `--debug` 参数查看详细日志:
```bash
node scripts/message.js send-text --user-id "user123" --content "test" --debug
```
## Configuration
### OpenClaw 集成配置
在 OpenClaw 配置文件中添加:
```json
{
"skills": {
"dingtalk-cli-auto": {
"app_key": "your-app-key",
"app_secret": "your-app-secret",
"default_chat_id": "your-default-chat-id"
}
}
}
```
### 环境变量
| 变量名 | 说明 | 必需 |
|--------|------|------|
| `DWS_CLIENT_ID` | 钉钉AppKey | 是 |
| `DWS_CLIENT_SECRET` | 钉钉AppSecret | 是 |
| `DINGTALK_DEFAULT_CHAT` | 默认群聊ID | 否 |
| `DINGTALK_DEBUG` | 调试模式 | 否 |
## Dependencies
- Node.js >= 18.0.0
- dws CLI >= 0.5.0
## Installation
```bash
# 克隆到技能目录
cd ~/clawd/skills
git clone <repo-url> dingtalk-cli-auto
# 安装依赖
cd dingtalk-cli-auto
npm install
# 配置认证
export DWS_CLIENT_ID="your-app-key"
export DWS_CLIENT_SECRET="your-app-secret"
dws auth login
# 测试
npm test
```
## Testing
运行测试用例:
```bash
# 全部测试
npm test
# 单模块测试
npm run test:message
npm run test:calendar
npm run test:todo
npm run test:contact
```
## Troubleshooting
### 问题:dws 命令未找到
**解决方案**:
```bash
# 确认安装路径
which dws
# 添加到 PATH
export PATH="$HOME/.local/bin:$PATH"
# 重新安装
curl -fsSL https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-workspace-cli/main/scripts/install.sh | sh
```
### 问题:认证失败
**解决方案**:
```bash
# 清除缓存重新认证
dws auth logout
dws auth login
# 检查环境变量
echo $DWS_CLIENT_ID
echo $DWS_CLIENT_SECRET
```
### 问题:权限不足
**解决方案**:
1. 检查钉钉开放平台应用权限设置
2. 确认应用已发布
3. 确认用户在企业通讯录中
## Changelog
### v1.0.0 (2026-04-02)
- 初始版本发布
- 支持消息发送、日程管理、待办事项、通讯录查询
- 支持机器人消息发送
## License
MIT
## Credits
- [DingTalk Workspace CLI](https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli) - 钉钉官方CLI工具
- [钉钉开放平台](https://open.dingtalk.com/) - 钉钉开放API
don't have the plugin yet? install it then click "run inline in claude" again.