DingTalk Workspace Skill

Use the dws CLI to interact with DingTalk enterprise workspace. This skill covers all 12 products: contact, chat, bot, calendar, todo, oa (approval), attendance, ding, report, aitable, workbench, and devdoc.

⚠️ Security & Safety Notes

Read before installing:

1. Credentials Required: This skill requires OAuth credentials (DWSCLIENTID, DWSCLIENTSECRET) from a DingTalk Open Platform app. Enterprise admin approval may be needed.

2. Install Safely: The dws CLI installer fetches from GitHub. Review the installer script before running:

- Installer: https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/blob/main/scripts/install.sh - Releases: https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases

3. Autonomous Execution Risk: This skill can perform destructive actions (approve workflows, send messages, delete records). Always use --dry-run first and restrict autonomous invocation unless you trust the agent.

4. Least Privilege: Use scoped OAuth credentials with minimum permissions. Test in a sandbox enterprise first.

Prerequisites

Installation

Option 1: Install from release (recommended)

Download pre-built binary from https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases

Option 2: Build from source (safer)

CODEBLOCK0

Option 3: Install script (review first!)

CODEBLOCK1

Authentication

CODEBLOCK2

Safe Execution Guidelines

For Agents

- --dry-run: ALWAYS use first for mutations to preview API calls
--yes: Skip confirmation prompts (use only after verifying with --dry-run)
--jq: Extract specific fields to reduce token consumption
--fields: Return only needed fields

Recommended Workflow

CODEBLOCK3

Auto-Correction

INLINECODE7 automatically corrects common AI mistakes:

- --baseId → --base-id (camelCase to kebab-case)
INLINECODE10 → --timeout 30 (sticky argument splitting)
INLINECODE12 → --table-id (fuzzy matching)
INLINECODE14 → true, "2024/03/29" → "2024-03-29" (value normalization)

Discovery & Introspection

Before making calls, discover available capabilities:

CODEBLOCK4

Quick Reference by Product

Contact

CODEBLOCK5

Chat

CODEBLOCK6

Calendar

CODEBLOCK7

Todo

CODEBLOCK8

Approval (OA)

CODEBLOCK9

Attendance

CODEBLOCK10

Report

CODEBLOCK11

AITable

CODEBLOCK12

Output Control

jq Filtering

CODEBLOCK13

Field Selection

CODEBLOCK14

File Input

CODEBLOCK15

Common Workflows

See bundled scripts in scripts/ for batch operations:

Script	Description
INLINECODE19	Create event + add participants + book meeting room
INLINECODE20

Error Handling

Common Error Codes

- INVALID_TOKEN: Re-authenticate with INLINECODE25
INLINECODE26: Check app permissions in DingTalk Open Platform
INLINECODE27: Verify IDs with dws schema introspection

Recovery

When encountering RECOVERY_EVENT_ID, use:
CODEBLOCK16

Security Notes

- Credentials are stored encrypted in system Keychain (never in config files)
All requests use HTTPS to *.dingtalk.com only
Use --dry-run before any mutation to preview the API call
Token refresh is automatic; no manual intervention needed

Reference Files

- Product commands: See references/products/*.md for detailed command reference per product
Intent guide: See references/intent-guide.md for disambiguation (e.g., report vs todo)
Error codes: See references/error-codes.md for debugging workflows
Global reference: See references/global-reference.md for auth, output formats, global flags

DingTalk 工作台技能

使用 dws 命令行工具与钉钉企业工作台进行交互。本技能涵盖全部 12 个产品：通讯录、聊天、机器人、日历、待办、OA（审批）、考勤、DING、日志、多维表、工作台和开发文档。

⚠️ 安全与注意事项

安装前请阅读：

1. 需要凭证：本技能需要来自钉钉开放平台应用的 OAuth 凭证（DWSCLIENTID、DWSCLIENTSECRET）。可能需要企业管理员审批。

2. 安全安装：dws 命令行安装程序从 GitHub 获取。运行前请检查安装脚本：

- 安装程序：https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/blob/main/scripts/install.sh - 发布版本：https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases

3. 自主执行风险：本技能可执行破坏性操作（审批工作流、发送消息、删除记录）。始终先使用 --dry-run，除非您信任该代理，否则限制自主调用。

4. 最小权限原则：使用具有最小权限的范围化 OAuth 凭证。先在沙箱企业中测试。

前提条件

安装

选项 1：从发布版本安装（推荐）

从 https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases 下载预构建二进制文件

选项 2：从源码构建（更安全）

bash
git clone https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli.git
cd dingtalk-workspace-cli
go build -o dws ./cmd
cp dws ~/.local/bin/

选项 3：安装脚本（请先检查！）

bash

macOS / Linux - 运行前请检查脚本

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

身份认证

bash

首次登录（凭证保存到系统钥匙串）

dws auth login --client-id <您的应用密钥> --client-secret <您的应用密钥>

或通过环境变量

export DWSCLIENTID=<您的应用密钥> export DWSCLIENTSECRET=<您的应用密钥> dws auth login

安全执行指南

针对代理

- --dry-run：始终先使用进行变更操作以预览 API 调用
--yes：跳过确认提示（仅在通过 --dry-run 验证后使用）
--jq：提取特定字段以减少令牌消耗
--fields：仅返回所需字段

1. 预览操作

dws todo task create --title 测试 --executors user123 --dry-run

2. 验证输出是否正确

3. 执行（仅在预览正确时）

dws todo task create --title 测试 --executors user123 --yes

自动纠错

dws 自动纠正常见的 AI 错误：

- --baseId → --base-id（驼峰式转短横线式）
--timeout30 → --timeout 30（粘性参数拆分）
--tabel-id → --table-id（模糊匹配）
yes → true，2024/03/29 → 2024-03-29（值规范化）

发现与自省

在发起调用前，发现可用能力：

bash

列出所有产品和工具数量

dws schema --jq .products[] | {id, tool_count: (.tools | length)}

检查特定工具的参数模式

dws schema aitable.query_records --jq .tool.parameters

查看必填字段

dws schema aitable.query_records --jq .tool.required

列出所有产品 ID

dws schema --jq .products[].id

按产品快速参考

通讯录

bash

按关键词搜索用户

dws contact user search --keyword 工程

获取当前用户资料

dws contact user get-self --jq .result[0].orgEmployeeModel | {name: .orgUserName, dept: .depts[0].deptName}

按名称搜索部门

dws contact dept search --keyword 工程

列出部门成员

dws contact dept members --dept-id <部门ID>

聊天

bash

以机器人身份发送消息

dws chat message send-by-bot --robot-code <机器人编码> --group <群组ID> --title 周报 --text @report.md

列出群组

dws chat group list

获取群组信息

dws chat group get --group-id <群组ID>

日历

bash

列出日历事件

dws calendar event list

创建事件

dws calendar event create --title 团队会议 --start 2024-03-29T14:00:00Z --end 2024-03-29T15:00:00Z

查找空闲时段

dws calendar participant busy --user-ids <用户ID1>,<用户ID2> --start 2024-03-29 --end 2024-03-30

搜索会议室

dws calendar room search --keyword 会议室

待办

bash

创建待办

dws todo task create --title 审查 PR --executors <您的用户ID> --yes

列出待办

dws todo task list

标记为完成

dws todo task done --task-id <任务ID>

审批（OA）

bash

列出待审批事项

dws oa approval list --status pending

审批实例

dws oa approval approve --instance-id <实例ID> --comment 已批准

拒绝实例

dws oa approval reject --instance-id <实例ID> --comment 需要修改

考勤

bash

查看我的考勤记录

dws attendance record list --user-id <您的用户ID>

查看团队排班表

dws attendance shift list --dept-id <部门ID>

日志

bash

查看今日收到的日志

dws report list --type received --start-date 2024-03-29 --end-date 2024-03-29

创建日志

dws report create --template-id <模板ID> --content @report.md

多维表

bash

查询记录

dws aitable record query --base-id ID> --table-id ID> --limit 10

创建记录

dws aitable record create --base-id ID> --table-id ID> --fields {name: 任务1, status: open}

列出多维表

dws aitable base list

列出多维表中的表格

dws aitable table list --base-id

输出控制

jq 过滤

bash

提取特定字段

dws contact user search --keyword 工程 --jq .result[] | {name: .orgUserName, userId: .userId}

统计结果数量

dws todo task list --jq .result | length

字段选择

bash

仅返回特定字段

dws aitable record query --base-id ID> --table-id ID> --fields invocation,response

文件输入

bash

从文件读取

dws chat message send-by-bot --robot-code <机器人编码> --group <群组ID> --text @message.md

从标准输入管道

cat message.md | dws chat message send-by-bot --robot-code <机器人编码> --group <群组ID>

常见工作流程

参见 scripts/ 中的捆绑脚本以进行批量操作：

脚本	描述
calendarschedulemeeting.py	创建事件 + 添加参与者 + 预订会议室
calendarfreeslot_finder.py

dingtalk-workspace钉钉工作台