DingTalk Workspace CLI (dws)

DingTalk Workspace CLI (dws) 是全球首款专为 AI Agent 和 企业安全 双重标准设计的钉钉命令行工具。它打破了传统 CLI 仅面向开发者的局限，通过结构化 JSON 输出、智能纠错引擎和内置的 Agent Skills 体系，让 AI 能够像人类一样精准、安全地操作钉钉生态中的通讯录、日历、待办、审批、智能表格等核心业务。

无论是个人用户希望通过终端高效管理日程，还是企业希望构建自动化的 AI 办公助理，dws 都提供了零信任架构下的坚实底座。

核心亮点

1. 为 AI Agent 原生设计

• 结构化输出：默认支持 JSON 格式，配合 --jq 参数可精确提取字段，大幅减少 Token 消耗，让 AI 更容易解析结果。
• Schema 自省：AI 无需预置所有命令知识，通过 dws schema 即可动态发现可用产品、工具及参数结构，实现“边学边用”。
• 智能纠错引擎：内置强大的 Pipeline 纠错机制，自动修复 AI 常犯的命名风格错误（camelCase → kebab-case）、参数粘连、拼写模糊等问题，极大提升调用成功率。
• 内置 Skills：提供完整的 SKILL.md 及参考文档，安装后 Claude Code、Cursor 等工具即可通过自然语言直接操作钉钉。

2. 企业级零信任安全

• 凭证零落盘：Client ID/Secret 仅在内存中使用，Token 采用 PBDF2 + AES-256-GCM 加密存储，并绑定设备物理特征，跨设备无法解密。
• 全链路审计：每一次 API 调用都必须经过钉钉开放平台的鉴权，管理员可在后台实时追溯完整日志，无旁路可逃。
• 权限最小化：CLI 仅能调用管理员授予该应用的 API 权限，严格遵循 OAuth 设备流认证。
• 输入安全防护：内置路径遍历防护、CRLF 注入拦截及 Unicode 视觉欺骗过滤，防止 AI 被恶意指令诱导。

3. 为人类开发者友好

• 直观交互：--help 查看用法，--dry-run 预览请求而不执行，-f 切换输出格式（table/json/raw）。
• 管道与文件支持：支持从 stdin 读取内容或从文件加载参数（如 @report.md），完美融入 Shell 脚本工作流。
• 跨平台：单一二进制文件，支持 macOS (Intel/ARM), Linux, Windows，无需安装运行时环境。

快速安装

一键安装脚本

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-workspace-cli/main/scripts/install.sh | sh

注意：macOS 用户若遇“无法打开”提示，请执行 xattr -d com.apple.quarantine $(which dws)。

Windows (PowerShell):

irm https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-workspace-cli/main/scripts/install.ps1 | iex

源码构建

需要 Go 1.25+：

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/

开始使用

1. 认证登录

# 自动唤起浏览器登录
dws auth login

# 无浏览器环境（Docker/SSH/CI）使用设备码登录
dws auth login --device

若组织未开启 CLI 权限，系统会引导你向管理员发送申请，审批通过后即可使用。

2. 基础命令示例

# 搜索联系人
dws contact user search --keyword "悟空"

# 查看日历日程
dws calendar event list

# 创建待办（--yes 跳过确认，适合 Agent）
dws todo task create --title "季度汇报" --executors "<userId>" --yes

# 预览操作（不实际执行）
dws todo task list --dry-run

3. AI 集成最佳实践

• 精确提取：使用 --jq 减少输出噪音。

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

• 动态发现：让 AI 先查询 Schema 再构造命令。

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

• 安装 Skills：

  curl -fsSL https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-workspace-cli/main/scripts/install-skills.sh | sh
  

  安装后，AI 即可理解“帮我预定一个明天下午的会议室”这类自然语言指令，并自动转化为复杂的 calendar 和 contact 组合命令。

核心功能全景

dws 覆盖 12 大产品线，拥有 86+ 个命令：

即将支持：文档 (doc)、邮箱 (mail)、AI 听记 (minutes)、钉盘 (drive)、视频会议 (conference) 等。

高级特性：让 AI 更聪明

1. 智能输入纠错

AI 生成的命令往往不符合 CLI 规范，dws 能自动修复：

• 风格转换：--userId → --user-id
• 参数拆分：--limit100 → --limit 100
• 拼写容错：--tabel-id → --table-id
• 值归一化："yes" → true, "2024/03/29" → "2024-03-29"

2. 现成脚本库

内置 13 个 Python 脚本，覆盖复杂多步工作流，AI 可直接调用：

• calendar_schedule_meeting.py: 一键搜人 + 查闲忙 + 订会议室 + 发日程。
• todo_batch_create.py: 从 JSON 批量创建带优先级和截止时间的待办。
• attendance_team_shift.py: 统计团队排班与出勤情况。
• import_records.py: 从 CSV/JSON 批量导入数据到智能表格。

3. 管道与文件输入

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

# 管道传输
cat report.md | dws chat message send-by-bot --robot-code BOT_CODE --group GROUP_ID

安全架构详解

dws 将安全视为一等公民，构建了多层防御体系：

1. 开发者侧：
   • 加密存储：Token 加密密钥绑定设备 MAC 地址，利用系统 Keychain/DPAPI 保护。
   • 原子操作：配置写入采用 temp + fsync + rename 模式，防止进程中断导致数据损坏。
   • 域名白名单：默认仅信任 *.dingtalk.com，杜绝 Token 泄露给恶意服务器。
2. 企业管理侧：
   • 准入控制：管理员需在后台主动开启 CLI 访问权限，并可审批具体用户的申请。
   • 全链路审计：所有操作均通过钉钉开放平台 API，天然具备完整的审计日志，任何异常操作无处遁形。
   • 租户隔离：ISV 集成时，严格基于授权应用身份调用，确保不同租户数据绝对隔离。

应用场景

• 🤖 AI 办公助理：结合 Claude Code/Cursor，实现“自然语言订票、查考勤、写周报、开会议”。
• ⚙️ CI/CD 自动化：在流水线中自动发送部署通知 DING、创建发布审批单、同步项目进度到智能表格。
• 📊 数据运营：定时导出考勤统计、分析日志提交情况、批量更新组织架构信息。
• 🔗 ISV 集成：第三方 SaaS 通过 dws 无缝连接钉钉生态，构建跨平台工作流。