DingTalk Workspace CLI (dws)：钉钉官方开源的跨平台 AI 工作流 CLI 工具

一、痛点切入：从"在钉钉里反复点鼠标"说起

每个企业运营者都熟悉这样的场景：每天要在钉钉里手动发日报、查考勤、批审批、翻文档，一个流程要切三四个后台；若想把这些重复操作自动化，又面临没有现成接口、SDK 文档分散、认证流程复杂的困境。更棘手的是，当大模型（LLM）开始介入办公自动化时，如何让 AI Agent 可靠地操控钉钉数据——而非每次都靠截图+ OCR 的不稳定方案——成为摆在开发者面前的一道现实难题。

DingTalk Workspace CLI（简称 dws） 正是为解决这些问题而生。它是阿里巴巴钉钉团队官方开源的跨平台命令行工具，将钉钉全产品线的 OpenAPI 能力统一封装为一组结构化的 CLI 命令，同时面向人类用户和 AI Agent 两大使用场景，让钉钉自动化从"手动点鼠标"升级为"可编程、可组合、可审计"的工作流引擎。

二、项目背景与起源

dws 由钉钉 Real AI 团队（DingTalk-Real-AI）开发和维护，采用 Apache-2.0 开源许可证，代码仓库托管于 GitHub。项目于 2026 年初正式开源，迅速获得 2170+ GitHub Stars，136 次 Fork，社区活跃。

从设计目标看，dws 不仅仅是一个 SDK 的 CLI 包装，而是从零重新思考了 CLI 与企业 API 的交互范式：

面向人类：提供 --help、 --dry-run 预览、-f table/json/raw 多格式输出，学习成本低。
面向 AI Agent：提供结构化 JSON 响应、内置 Agent Skills（兼容 MCP 协议），让 LLM 能够可靠地解析和组合 API 调用结果。
面向企业管理员：零信任架构（OAuth device-flow 认证 + 域名白名单 + 最小权限），每一字节数据都经过认证和审计。

这种"三端合一"的设计思路，在同类开源工具中较为少见，也是 dws 与市面上大多数钉钉 SDK 的本质区别。

三、核心功能：从通讯录到 AI 表格全覆盖

dws 的命令体系覆盖钉钉几乎所有核心产品，按子命令数量排序如下：

3.1 通讯录与人员管理（contact）

提供 15 个子命令，覆盖用户搜索（按姓名/手机号/工号）、部门查询、标签与角色管理、人员关系图谱、在职人员/离职人员档案等场景。支持批量查询，适合 HR 系统的自动化对接。

3.2 即时通讯与群管理（chat/im，65 个子命令）

dws 对 IM 能力的封装最为全面，是整个工具链中使用频次最高的模块：

消息：发送/回复/撤回/转发，支持文本、卡片、表情、话题帖；支持按发送者、提及、未读、已读等多维度检索。
群聊：完整的群 CRUD（创建/删除/获取/更新），成员增删改、角色分配（群主转让、设置管理员）、邀请链接生成。
机器人：支持以 bot 身份发送消息（send-by-bot/recall-by-bot），也支持 webhook 方式推送，适合值班通知、监控系统告警等场景。
会话管理：置顶、免打扰、分类、会话搜索（普通搜索/高级搜索）。

3.3 日历与会议室（calendar）

17 个子命令覆盖日程 CRUD、会议室预约空闲查询（free-busy query）、参会人管理、会议附件上传。

3.4 待办任务（todo）

16 个子命令，支持任务创建/列表/更新/完成/删除，附加评论（task comment），适合与项目管理工具集成。

3.5 审批流（oa）

15 个子命令，封装钉钉 OA 审批能力：审批/驳回/撤回/转交，待审批/我发起的/我已审批实例列表，表单解析，操作日志查询。

3.6 考勤（attendance）

4 个子命令：打卡记录查询、排班表、考勤汇总、考勤规则读取。

3.7 日志与汇报（report/ding）

日报/周报/月报全流程：创建/提交/列表/详情/模板/统计，接收箱/发送箱检索；DING 消息发送与撤回。

3.8 智能表格 AI Tables（aitable，52 个子命令）

dws 对多维表格的封装最为深入，也是其与 AI 结合最紧密的部分：

基础对象：Base（工作空间）、Table（多维表格）、Record（记录）、Field（字段）、View（视图）的完整 CRUD。
图表与仪表盘：支持图表和仪表盘的创建与公开分享配置。
导入导出：支持 CSV/Excel 格式的数据批量导入导出。
附件：两阶段上传（prepare-only upload + one-shot upload-file）。
表单：多维表格表单创建与收集。

3.9 文档与知识库（doc/wiki）

28 个子命令，涵盖文档搜索/读取/创建/更新，块级编辑，评论协作；知识库文档检索与读取。

3.10 网盘（drive）

9 个子命令，覆盖钉钉网盘空间列表、文件信息/下载、文件夹创建、单次上传（upload，三步组合）或两阶段上传（upload-info + commit）。

3.11 会议纪要（minutes）

19 个子命令，支持 AI 会议纪要的列表/详情/摘要/关键词/全文转录/待办事项提取，思维导图生成，发言人替换，热词上传。

3.12 邮件（mail）

18 个子命令，支持邮箱列表、KQL 消息搜索、邮件读写、草稿管理、文件夹/标签/线程/附件操作。

3.13 在线表格（sheet）

23 个子命令，封装钉钉在线表格（contentType=ALIDOC）操作：工作表 CRUD、范围读写/追加、行列增删改、单元格合并/拆分、查找替换、命名筛选视图。

四、核心技术亮点

4.1 零信任安全架构

dws 采用三重安全机制：OAuth device-flow 认证（设备码登录，企业管理员授权）、API 域名白名单（仅限 api.dingtalk.com 和 oapi.dingtalk.com，防止 token 泄漏）、最小权限范围控制。README 强调："Not a single byte can bypass authentication and audit"（每一字节数据都无法绕过认证和审计）。

4.2 面向 AI Agent 的增强能力

这是 dws 与普通 CLI 工具最核心的差异点：

智能输入纠错（Smart Input Correction）：内置管道引擎，自动规范化 flag 名称、拆分粘滞参数、模糊匹配拼写错误。典型场景：LLM 输出 --userId 自动转为 --user-id；--timeout30 自动拆分为 --timeout 30；--tabel-id 模糊匹配为 --table-id。这解决了 AI Agent 在生成 CLI 命令时最常见的参数格式错误问题。

结构化 JSON 输出 + jq 过滤：--jq 参数支持内置 jq 表达式，精确提取响应字段，减少 LLM 的 token 消耗。--fields 参数可直接指定返回字段。

Schema 自省（Schema Introspection）：dws schema 命令可在调用前查询任意产品的参数 schema 和授权元数据，让 Agent 具备"先查规范再调用"的能力，而非盲目尝试。

Agent Skills 集成：dws 安装后提供与 MCP 协议兼容的 Skill 文件（mono 模式：一个统一 Skill；multi 模式：18 个按产品拆分的独立 Skill），可直接被 AI Agent 消费，调用逻辑完全结构化。

4.3 双重 API 域名自动适配

钉钉同时维护 api.dingtalk.com（新版 header 认证）和 oapi.dingtalk.com（旧版 query 参数认证）两套接口体系。dws 自动检测 URL 属于哪个域名，并自动应用对应的认证方式，降低使用门槛。

4.4 自动化 Token 管理

AccessToken 自动获取、自动缓存（在有效期内复用）、自动刷新（过期前智能刷新），无需使用者手动管理 Token 生命周期。

五、部署方式

dws 是纯 CLI 工具，无 Web 界面，无 Docker 支持，但安装方式极为灵活：

安装方式	命令	适用场景
一键脚本（Linux/macOS）	`curl -fsSL .../install.sh \| sh`	最简方式，2 分钟上手
PowerShell（Windows）	`irm .../install.ps1 \| iex`	Windows 用户
npm 全局安装	`npm install -g dingtalk-workspace-cli`	已有 Node.js 环境
预编译二进制	GitHub Releases 下载	无网络环境
源码编译	`go build -o dws ./cmd`	开发者定制/贡献

依赖：Go 1.25+（源码编译）、Git、curl；无需 GPU，无需 Docker，资源占用极低（RAM ~512MB，磁盘 ~50MB）。

六、技术架构

语言：Go 1.25+，编译为单一静态二进制，跨平台（macOS/Linux/Windows x86_64/arm64）。
核心依赖：spf13/cobra（CLI 框架）、charmbracelet/huh（TUI 表单）、zalando/go-keyring（安全密钥存储）、fatih/color（彩色输出）、itchyny/gojq（JSON 查询）、golang.org/x/crypto（加密）。
代码组织：cmd/（入口）、internal/（内部实现：apiclient/auth/cli/cobracmd/cache/discovery 等）、pkg/（可复用工具：asynctask/config/convert/edition 等）、skills/（Agent Skill 定义文件）、test/（测试套件）、docs/（架构文档/自动化/命令索引/参考手册）。
质量保障：GitHub Actions CI（lint + build + test）、.goreleaser.yaml 跨平台发布配置、完整测试套件、贡献者指南。
AI 集成：无特定 AI framework 依赖，通过结构化 JSON + Skill 文件与任意 LLM/MCP 生态对接。

七、局限与注意事项

企业认证门槛：dws 访问企业数据需要企业管理员授权，不支持个人用户直接使用。这是合规要求，但也限制了个人开发者的快速体验。
非容器化：纯 CLI 工具，无 Dockerfile，不支持 Docker Compose 部署，在大规模服务器端自动化场景中不如容器化方案灵活。
多 Skill 模式不稳定：multi 模式（18 个独立 Skill）仍为实验阶段（EXPERIMENTAL），接口和命名可能在未来版本中变化，生产环境建议使用 mono 模式。
部分服务依赖钉钉内部 API：部分产品（如 Wiki 多行子命令列表在 README 中被截断）可能存在文档与实际实现的同步问题。
Go 1.25+ 版本要求：若需源码编译，需要 Go 1.25 及以上版本，部分老系统可能需要手动升级 Go 工具链。

八、行业意义

dws 的出现代表着企业办公工具领域的一个重要趋势：从"提供 SDK 让开发者编程"到"提供 Agent-Ready CLI 让 AI 编程"。传统的钉钉集成方案要求开发者深入理解 API 文档、认证流程和错误处理；dws 通过自省式 schema、输入纠错和 Skill 封装，把这个门槛显著降低，使 AI Agent 能够以接近人类的方式与钉钉 API 交互。

从数据看，项目自开源以来保持高频更新（最新提交 2026-06-11），社区 issue 活跃度较高（90 个 open issues），体现了钉钉团队对开源的认真投入。随着多模态 AI Agent 逐步进入企业办公场景，类似 dws 这样专为 Agent 设计的企业 API CLI 有望成为标配。

九、快速上手

# 方式1：一键安装（Linux/macOS）
curl -fsSL https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-workspace-cli/main/scripts/install.sh | sh

# 方式2：npm 安装
npm install -g dingtalk-workspace-cli

# 认证（需要企业管理员提供 App 凭证）
dws auth login --client-id <APP_KEY> --client-secret <APP_SECRET>

# 查询 schema（了解可用命令）
dws schema

# 发送一条群消息
dws chat message send-by-bot --robot-code BOT_CODE --group GROUP_ID --title "Hello" --text "DWS test"

# 预览请求（不实际执行）
dws api GET /v1.0/microApp/allApps --dry-run

DingTalk Workspace CLI (dws)：钉钉官方开源的跨平台 AI 工作流 CLI 工具

一、痛点切入：从"在钉钉里反复点鼠标"说起

二、项目背景与起源

从设计目标看，dws 不仅仅是一个 SDK 的 CLI 包装，而是从零重新思考了 CLI 与企业 API 的交互范式：

面向人类：提供 --help、 --dry-run 预览、-f table/json/raw 多格式输出，学习成本低。
面向 AI Agent：提供结构化 JSON 响应、内置 Agent Skills（兼容 MCP 协议），让 LLM 能够可靠地解析和组合 API 调用结果。
面向企业管理员：零信任架构（OAuth device-flow 认证 + 域名白名单 + 最小权限），每一字节数据都经过认证和审计。

这种"三端合一"的设计思路，在同类开源工具中较为少见，也是 dws 与市面上大多数钉钉 SDK 的本质区别。

三、核心功能：从通讯录到 AI 表格全覆盖

dws 的命令体系覆盖钉钉几乎所有核心产品，按子命令数量排序如下：

3.1 通讯录与人员管理（contact）

3.2 即时通讯与群管理（chat/im，65 个子命令）

dws 对 IM 能力的封装最为全面，是整个工具链中使用频次最高的模块：

消息：发送/回复/撤回/转发，支持文本、卡片、表情、话题帖；支持按发送者、提及、未读、已读等多维度检索。
群聊：完整的群 CRUD（创建/删除/获取/更新），成员增删改、角色分配（群主转让、设置管理员）、邀请链接生成。
机器人：支持以 bot 身份发送消息（send-by-bot/recall-by-bot），也支持 webhook 方式推送，适合值班通知、监控系统告警等场景。
会话管理：置顶、免打扰、分类、会话搜索（普通搜索/高级搜索）。

3.3 日历与会议室（calendar）

17 个子命令覆盖日程 CRUD、会议室预约空闲查询（free-busy query）、参会人管理、会议附件上传。

3.4 待办任务（todo）

16 个子命令，支持任务创建/列表/更新/完成/删除，附加评论（task comment），适合与项目管理工具集成。

3.5 审批流（oa）

15 个子命令，封装钉钉 OA 审批能力：审批/驳回/撤回/转交，待审批/我发起的/我已审批实例列表，表单解析，操作日志查询。

3.6 考勤（attendance）

4 个子命令：打卡记录查询、排班表、考勤汇总、考勤规则读取。

3.7 日志与汇报（report/ding）

日报/周报/月报全流程：创建/提交/列表/详情/模板/统计，接收箱/发送箱检索；DING 消息发送与撤回。

3.8 智能表格 AI Tables（aitable，52 个子命令）

dws 对多维表格的封装最为深入，也是其与 AI 结合最紧密的部分：

基础对象：Base（工作空间）、Table（多维表格）、Record（记录）、Field（字段）、View（视图）的完整 CRUD。
图表与仪表盘：支持图表和仪表盘的创建与公开分享配置。
导入导出：支持 CSV/Excel 格式的数据批量导入导出。
附件：两阶段上传（prepare-only upload + one-shot upload-file）。
表单：多维表格表单创建与收集。

3.9 文档与知识库（doc/wiki）

28 个子命令，涵盖文档搜索/读取/创建/更新，块级编辑，评论协作；知识库文档检索与读取。

3.10 网盘（drive）

9 个子命令，覆盖钉钉网盘空间列表、文件信息/下载、文件夹创建、单次上传（upload，三步组合）或两阶段上传（upload-info + commit）。

3.11 会议纪要（minutes）

19 个子命令，支持 AI 会议纪要的列表/详情/摘要/关键词/全文转录/待办事项提取，思维导图生成，发言人替换，热词上传。

3.12 邮件（mail）

18 个子命令，支持邮箱列表、KQL 消息搜索、邮件读写、草稿管理、文件夹/标签/线程/附件操作。

3.13 在线表格（sheet）

23 个子命令，封装钉钉在线表格（contentType=ALIDOC）操作：工作表 CRUD、范围读写/追加、行列增删改、单元格合并/拆分、查找替换、命名筛选视图。

四、核心技术亮点

4.1 零信任安全架构

4.2 面向 AI Agent 的增强能力

这是 dws 与普通 CLI 工具最核心的差异点：

结构化 JSON 输出 + jq 过滤：--jq 参数支持内置 jq 表达式，精确提取响应字段，减少 LLM 的 token 消耗。--fields 参数可直接指定返回字段。

4.3 双重 API 域名自动适配

4.4 自动化 Token 管理

AccessToken 自动获取、自动缓存（在有效期内复用）、自动刷新（过期前智能刷新），无需使用者手动管理 Token 生命周期。

五、部署方式

dws 是纯 CLI 工具，无 Web 界面，无 Docker 支持，但安装方式极为灵活：

安装方式	命令	适用场景
一键脚本（Linux/macOS）	`curl -fsSL .../install.sh \| sh`	最简方式，2 分钟上手
PowerShell（Windows）	`irm .../install.ps1 \| iex`	Windows 用户
npm 全局安装	`npm install -g dingtalk-workspace-cli`	已有 Node.js 环境
预编译二进制	GitHub Releases 下载	无网络环境
源码编译	`go build -o dws ./cmd`	开发者定制/贡献

依赖：Go 1.25+（源码编译）、Git、curl；无需 GPU，无需 Docker，资源占用极低（RAM ~512MB，磁盘 ~50MB）。

六、技术架构

语言：Go 1.25+，编译为单一静态二进制，跨平台（macOS/Linux/Windows x86_64/arm64）。
核心依赖：spf13/cobra（CLI 框架）、charmbracelet/huh（TUI 表单）、zalando/go-keyring（安全密钥存储）、fatih/color（彩色输出）、itchyny/gojq（JSON 查询）、golang.org/x/crypto（加密）。
代码组织：cmd/（入口）、internal/（内部实现：apiclient/auth/cli/cobracmd/cache/discovery 等）、pkg/（可复用工具：asynctask/config/convert/edition 等）、skills/（Agent Skill 定义文件）、test/（测试套件）、docs/（架构文档/自动化/命令索引/参考手册）。
质量保障：GitHub Actions CI（lint + build + test）、.goreleaser.yaml 跨平台发布配置、完整测试套件、贡献者指南。
AI 集成：无特定 AI framework 依赖，通过结构化 JSON + Skill 文件与任意 LLM/MCP 生态对接。

七、局限与注意事项

企业认证门槛：dws 访问企业数据需要企业管理员授权，不支持个人用户直接使用。这是合规要求，但也限制了个人开发者的快速体验。
非容器化：纯 CLI 工具，无 Dockerfile，不支持 Docker Compose 部署，在大规模服务器端自动化场景中不如容器化方案灵活。
多 Skill 模式不稳定：multi 模式（18 个独立 Skill）仍为实验阶段（EXPERIMENTAL），接口和命名可能在未来版本中变化，生产环境建议使用 mono 模式。
部分服务依赖钉钉内部 API：部分产品（如 Wiki 多行子命令列表在 README 中被截断）可能存在文档与实际实现的同步问题。
Go 1.25+ 版本要求：若需源码编译，需要 Go 1.25 及以上版本，部分老系统可能需要手动升级 Go 工具链。

八、行业意义

九、快速上手

# 方式1：一键安装（Linux/macOS）
curl -fsSL https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-workspace-cli/main/scripts/install.sh | sh

# 方式2：npm 安装
npm install -g dingtalk-workspace-cli

# 认证（需要企业管理员提供 App 凭证）
dws auth login --client-id <APP_KEY> --client-secret <APP_SECRET>

# 查询 schema（了解可用命令）
dws schema

# 发送一条群消息
dws chat message send-by-bot --robot-code BOT_CODE --group GROUP_ID --title "Hello" --text "DWS test"

# 预览请求（不实际执行）
dws api GET /v1.0/microApp/allApps --dry-run