DingTalk Workspace CLI (dws)

一个 CLI 搞定钉钉工作台所有功能 — 为人类和 AI Agent 而生。
覆盖通讯录、日历、待办、考勤、智能表格等核心能力，无需样板代码即可调用，所有响应均为结构化 JSON 输出，并内置 Agent Skills 让 AI 开箱即用。

[!IMPORTANT] 共创阶段：本项目涉及钉钉企业数据访问，需企业管理员授权后方可使用。当前为灰度共创阶段，请加入钉钉 DWS 共创群，提供以下材料给官方人员完成白名单配置：① 钉钉应用的 Client ID；② 企业主管理员确认开通的凭证。后续将支持企业管理员自助审批开通。

目录

• 为什么选择 dws？
• 核心服务
• 安装
• 开始使用
• 快速开始
• AI Agent Skills
• 高级用法
• 环境变量
• 退出码
• 架构设计
• 开发指南
• 测试
• 更新日志
• 安全策略
• 贡献指南

为什么选择 dws？

为人类而设计 — 告别手写 API 调用。dws 为每个资源提供 --help，用 --dry-run 预览请求，支持表格/JSON/原始格式的结构化输出。

为 AI Agent 而设计 — 每个响应都是结构化 JSON。配合内置的 agent skills，您的 LLM 无需自定义工具即可管理钉钉工作台。

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

# 创建待办事项
dws todo task create --title "准备季度汇报材料" --executors "<userId>"

# 预览操作但不执行
dws todo task list --dry-run

# JSON 输出供 agent 使用
dws contact user search --keyword "悟空" -f json

核心服务

dws 通过统一的命令界面覆盖钉钉产品：

运行 dws --help 查看完整列表，或 dws <service> --help 查看特定服务的命令。

安装

一键安装（推荐）

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

自动检测操作系统和架构，从 GitHub Releases 下载预编译二进制文件，并安装 Agent Skills 到 ~/.agents/skills/dws — 无需 Go、Node.js 或其他依赖。大多数 AI Agent（Claude Code、Cursor、Windsurf 等）可自动发现 .agents/skills/ 目录下的技能。

[!TIP] 二进制文件默认安装到 ~/.local/bin。如果安装后找不到 dws 命令，请将其添加到 PATH：

export PATH="$HOME/.local/bin:$PATH"

将此行添加到 ~/.bashrc 或 ~/.zshrc 以永久生效。

预编译二进制文件（手动）

从 GitHub Releases 下载适合您平台的最新二进制文件。

从源码构建

git clone https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli.git
cd dingtalk-workspace-cli
make build
./dws version

这只会构建二进制文件。如需同时将 agent skills 安装到主目录：

sh scripts/install.sh

这会检测本地源码目录，无需从 GitHub 下载即可安装二进制文件和 skills。

开始使用

步骤 1：创建钉钉应用

进入 开放平台应用开发后台，在「企业内部应用 - 钉钉应用」点击右上角的创建应用，新建一个应用。

步骤 2：配置重定向 URL

创建应用后，进入应用内，点击安全设置。在「重定向 URL（回调设置）」里，输入 http://127.0.0.1 并保存。

步骤 3：发布应用

点击「应用发布 - 版本管理与发布」，发布版本，使应用变成上线状态。

步骤 4：申请白名单

参照页面顶部的 共创阶段说明，加入钉钉 DWS 共创群完成白名单配置。

步骤 5：使用凭证登录

获取 Client ID（AppKey）和 Client Secret（AppSecret）后，可通过 CLI 参数指定：

dws auth login --client-id <your-app-key> --client-secret <your-app-secret>

或者通过环境变量设置：

export DWS_CLIENT_ID=<your-app-key>
export DWS_CLIENT_SECRET=<your-app-secret>
dws auth login

[!NOTE] CLI 参数优先级高于环境变量。这些凭证用于钉钉的 OAuth 设备流认证。

Token 加密

Token 使用 PBKDF2（600,000 次迭代）+ AES-256-GCM 加密存储，密钥由您的设备 MAC 地址生成。

快速开始

dws auth login                                    # 钉钉身份认证
dws contact user search --keyword "悟空"           # 搜索联系人
dws calendar event list                            # 列出日历事件
dws todo task create --title "准备季度汇报材料" --executors "<userId>"   # 创建待办

AI Agent Skills

仓库为每个支持的钉钉产品提供 agent skills（SKILL.md 文件）。

Skills 由安装脚本自动安装。如需单独将 skills 安装到现有项目：

# macOS / Linux — 仅将 skills 安装到当前项目
curl -fsSL https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-workspace-cli/main/scripts/install-skills.sh | sh

一键安装器（install.sh）将 skills 安装到 ~/.agents/skills/dws（主目录）。 当您想要为特定项目仓库添加 skills 时，请使用 install-skills.sh，它会安装到 ./.agents/skills/dws（当前工作目录）。

[!NOTE] 主目录 vs. 项目 skills：install.sh 将 skills 放在 $HOME/.agents/skills/dws。install-skills.sh 安装到当前工作目录（./.agents/skills/dws），适用于为特定项目仓库添加 skills。

高级用法

输出格式

所有命令支持多种输出格式：

# 表格（默认，适合人类阅读）
dws contact user search --keyword "悟空" -f table

# JSON（适合 agent 和管道处理）
dws contact user search --keyword "悟空" -f json

# 原始 API 响应
dws contact user search --keyword "悟空" -f raw

试运行

预览 MCP 工具调用但不执行：

dws todo task list --dry-run

输出到文件

dws contact user search --keyword "李明" -o result.json

Shell 自动补全

# Bash
dws completion bash > /etc/bash_completion.d/dws

# Zsh
dws completion zsh > "${fpath[1]}/_dws"

# Fish
dws completion fish > ~/.config/fish/completions/dws.fish

环境变量

常用的运行时和开发覆盖项：

退出码

使用 -f json 时，错误响应包含结构化信息（category、reason、hint、actions 字段），便于机器消费。

架构设计

dws 使用 发现驱动的管道 — 不硬编码任何产品命令：

Market Registry ──► Discovery ──► IR (规范化目录) ──► CLI (Cobra) ──► Transport (MCP JSON-RPC)
      │                 │
      ▼                 ▼
  mcp.dingtalk.com   缓存（TTL + 过期降级）

1. Market — 从 mcp.dingtalk.com 获取 MCP 服务注册表
2. Discovery — 解析服务运行时能力，支持磁盘缓存和过期降级保证离线可用
3. IR — 将服务规范化为统一的产品/工具目录
4. CLI — 将目录挂载到 Cobra 命令树，映射 flag 到 MCP 输入参数
5. Transport — 执行 MCP JSON-RPC 调用，支持重试、认证注入和响应大小限制

使用 -f json 时，所有输出 — 成功、错误和元数据 — 都是结构化 JSON。

开发指南

make build                        # 开发构建
make test                         # 单元测试
make lint                         # 格式化 + lint 检查
make package                      # 本地构建所有发布产物（goreleaser snapshot）
make release                      # 通过 goreleaser 构建和发布
make publish-homebrew-formula     # 将 dist/homebrew/dingtalk-workspace-cli.rb 推送到 tap 仓库

包管理器产物

构建并验证本地包管理器产物：

make package                                       # 生成所有平台归档、npm 资源、Homebrew formula
./scripts/release/verify-package-managers.sh        # 验证 dws 二进制文件和 skills 包含在内

测试

CLI 测试

运行完整的 CLI 测试套件（单元测试、golden 测试和集成测试）：

bash test/scripts/run_all_tests.sh --jobs 8

打包测试

运行打包契约测试和本地包管理器验证：

go test ./test/scripts/... -count=1
make package
./scripts/release/verify-package-managers.sh

Skills 测试

安装 skills 后，使用 test/skill_tests.md 进行验证。将该文件中的测试提示输入您的 AI agent 并确认预期输出。

更新日志

参见 CHANGELOG.md 了解版本历史和迁移说明。

安全策略

报告安全漏洞请参见 SECURITY.md。

贡献指南

参见 CONTRIBUTING.md 了解开发工作流和本地验证步骤。

许可证

Apache-2.0