DingTalk Workspace 技能

使用 dws CLI 与 DingTalk 企业工作区（workspace）交互。该技能覆盖全部 12 类产品：contact（通讯录）、chat（聊天）、bot（机器人）、calendar（日历）、todo（待办）、oa（审批）、attendance（考勤）、ding（钉钉）、report（汇报）、aitable（智能表格）、workbench（工作台）和 devdoc（开发文档）。

⚠️ 安全与安全注意事项

安装前请务必阅读：

1. 需提供凭据：本技能需要来自 DingTalk 开放平台应用的 OAuth 凭据（DWS_CLIENT_ID、DWS_CLIENT_SECRET）。可能需企业管理员审批授权。

2. 安全安装：dws CLI 安装器从 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 预览 API 调用，且仅在充分信任对应 agent 的前提下才启用自主调用能力。

4. 最小权限原则：请使用作用域受限（scoped）的 OAuth 凭据，并授予最低必要权限；建议先在 sandbox 企业环境中进行测试。

前置条件

安装

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

从以下地址下载预编译二进制文件：https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases

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

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：使用安装脚本（请先审阅！）

# 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

认证

推荐方式：交互式登录（使用系统密钥链安全存储）

dws auth login --client-id  --client-secret 
# Token 将加密存储于系统 Keychain（macOS/Windows）或 libsecret（Linux）

备选方式：环境变量（慎用）

export DWS_CLIENT_ID=
export DWS_CLIENT_SECRET=
dws auth login

⚠️ 安全提示：环境变量可能在进程列表和日志中暴露。生产环境请优先选用交互式登录方式。

安全执行指南

面向 Agent 的使用规范

• --dry-run：对所有变更类操作必须首先使用，用于预览将触发的 API 请求
• --yes：跳过确认提示（仅在通过 --dry-run 验证后使用）
• --jq：提取特定字段，降低 token 消耗
• --fields：仅返回所需字段

推荐工作流

# 1. 预览操作效果
dws todo task create --title "Test" --executors "user123" --dry-run

# 2. 核查输出是否符合预期

# 3. 执行操作（仅当预览结果正确时）
dws todo task create --title "Test" --executors "user123" --yes

自动纠错机制

dws 可自动修正常见 AI 生成错误：

• --baseId → --base-id（驼峰命名转短横线分隔）
• --timeout30 → --timeout 30（粘连参数自动拆分）
• --tabel-id → --table-id（模糊匹配纠偏）
• "yes" → true，"2024/03/29" → "2024-03-29"（值标准化）

能力发现与自省

发起调用前，请先探查可用能力：

# 列出所有产品及其工具数量
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'

按产品快速参考

Contact（通讯录）

# 按关键词搜索用户
dws contact user search --keyword "engineering"

# 获取当前用户资料
dws contact user get-self --jq '.result[0].orgEmployeeModel | {name: .orgUserName, dept: .depts[0].deptName}'

# 按名称搜索部门
dws contact dept search --keyword "Engineering"

# 列出部门成员
dws contact dept members --dept-id 

Chat（聊天）

# 以机器人身份发送消息
dws chat message send-by-bot --robot-code  --group  --title "Weekly Report" --text @report.md

# 列出群组
dws chat group list

# 获取群组详情
dws chat group get --group-id 

Calendar（日历）

# 列出日历事件
dws calendar event list

# 创建日历事件
dws calendar event create --title "Team Meeting" --start "2024-03-29T14:00:00Z" --end "2024-03-29T15:00:00Z"

# 查询空闲时间段（多人共同空闲时段）
dws calendar participant busy --user-ids , --start "2024-03-29" --end "2024-03-30"

# 搜索会议室
dws calendar room search --keyword "Meeting Room"

Todo（待办）

# 创建待办事项
dws todo task create --title "Review PR" --executors "" --yes

# 列出待办事项
dws todo task list

# 标记为已完成
dws todo task done --task-id 

Approval（OA 审批）

# 列出待审批实例
dws oa approval list --status pending

# 审批通过
dws oa approval approve --instance-id  --comment "Approved"

# 驳回审批
dws oa approval reject --instance-id  --comment "Needs revision"

Attendance（考勤）

# 查看本人考勤记录
dws attendance record list --user-id 

# 查看团队排班计划
dws attendance shift list --dept-id 

Report（汇报）

# 查看今日已接收的汇报
dws report list --type received --start-date "2024-03-29" --end-date "2024-03-29"

# 创建汇报
dws report create --template-id  --content @report.md

AITable（智能表格）

# 查询记录
dws aitable record query --base-id  --table-id  --limit 10

# 创建记录
dws aitable record create --base-id  --table-id  --fields '{"name": "Task 1", "status": "open"}'

# 列出所有 base（工作空间）
dws aitable base list

# 列出某 base 下的所有表
dws aitable table list --base-id 

输出控制

jq 过滤

# 提取特定字段
dws contact user search --keyword "engineering" --jq '.result[] | {name: .orgUserName, userId: .userId}'

# 统计结果数量
dws todo task list --jq '.result | length'

字段选择

# 仅返回指定字段
dws aitable record query --base-id  --table-id  --fields invocation,response

文件输入

# 从文件读取内容
dws chat message send-by-bot --robot-code  --group  --text @message.md

# 从标准输入管道传入
cat message.md | dws chat message send-by-bot --robot-code  --group 

常用工作流

参见 scripts/ 目录中附带的批量操作脚本：

安全第一：所有变更类脚本默认以 --dry-run 模式运行。如需实际执行修改操作，必须显式传入 --execute 参数。

示例：

# 首先预览（默认行为）
python scripts/todo_batch_create.py tasks.json

# 预览确认无误后执行
python scripts/todo_batch_create.py tasks.json --execute

错误处理

常见错误码

• INVALID_TOKEN：使用 dws auth login 重新认证
• PERMISSION_DENIED：前往 DingTalk 开放平台检查应用权限配置
• RESOURCE_NOT_FOUND：使用 dws schema 自省功能验证 ID 是否有效

恢复操作

遇到 RECOVERY_EVENT_ID 错误时，请使用：

dws --recovery 

安全说明

• 凭据经加密后存储于系统 Keychain 中（绝不会写入配置文件）
• 所有请求均通过 HTTPS 发送至 *.dingtalk.com 域名
• 任何变更类操作前请务必使用 --dry-run 预览 API 调用
• Token 刷新全自动完成，无需人工干预

参考文档

• 各产品命令参考：详见 references/products/*.md，含各产品完整命令说明
• 意图指南：详见 references/intent-guide.md，用于消歧义（例如区分 report 与 todo）
• 错误码参考：详见 references/error-codes.md，辅助调试工作流
• 全局参考：详见 references/global-reference.md，涵盖认证、输出格式及全局标志位等通用信息