github/dingtalk-workspace-cli

Fork 0

Files

T

audanye-sudo 94deafbaa9 docs: update release badge version to v1.0.3

2026-03-29 23:37:31 +08:00

17 KiB

Raw Blame History

DingTalk Workspace CLI (dws)

dws — 钉钉工作台命令行工具，为人类和 AI Agent 而生。

中文版 · English · 参考手册 · 更新日志

Important

共创阶段：本项目涉及钉钉企业数据访问，需企业管理员授权后方可使用。当前为灰度共创阶段，请加入钉钉 DWS 共创群完成白名单配置。详见下方开始使用。

为什么选择 dws？
安装
开始使用
快速开始
在 Agent 中使用
功能特性
核心服务
安全设计
参考与文档
贡献指南

为什么选择 dws？

为人类而设计 — --help 查看用法，--dry-run 预览请求，-f table/json/raw 切换格式。
为 AI Agent 而设计 — 结构化 JSON 响应 + 内置 Agent Skills，开箱即用。
为企业管理员而设计 — 零信任架构：OAuth 设备流认证 + 域名白名单 + 权限最小化。没有一个字节能绕过安全鉴权和审计。

安装

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 下载。

从源码构建：

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/         # 安装到 PATH

需要 Go 1.25+。也可以用 make package 构建所有平台产物（macOS / Linux / Windows × amd64 / arm64）。

开始使用

步骤 1：创建钉钉应用

进入开放平台应用开发后台，在「企业内部应用 - 钉钉应用」点击创建应用。

查看截图

步骤 2：配置重定向 URL

进入应用 → 安全设置，在「重定向 URL」中添加以下地址并保存：

http://127.0.0.1
https://login.dingtalk.com

http://127.0.0.1 用于本地浏览器登录；https://login.dingtalk.com 用于 --device 设备流登录（Docker 容器、远程服务器等无浏览器环境）。建议两个都配置。

查看截图

步骤 3：发布应用

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

查看截图

步骤 4：申请白名单

加入钉钉 DWS 共创群，提供 Client ID 和管理员确认凭证完成白名单配置。

步骤 5：登录认证

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

CLI 参数优先于环境变量。凭证用于钉钉 OAuth 设备流认证。

快速开始

dws contact user search --keyword "悟空"           # 搜索联系人
dws calendar event list                            # 查看日历日程
dws todo task create --title "季度汇报" --executors "<your-userId>"   # 创建待办（请替换为真实 userId）
dws todo task list --dry-run                       # 预览操作但不执行

在 Agent 中使用

dws 是为 AI Agent 设计的 CLI 工具。请先完成安装和开始使用，然后配置 Agent 环境：

# 通过环境变量配置认证（Agent 推荐方式，无需交互式登录）
export DWS_CLIENT_ID=<your-app-key>
export DWS_CLIENT_SECRET=<your-app-secret>
dws auth login

Agent 调用模式

# 使用 --yes 跳过确认提示（Agent 必须）
dws todo task create --title "Review PR" --executors "<your-userId>" --yes

# 使用 --dry-run 预览操作（安全执行）
dws contact user search --keyword "张三" --dry-run

# 使用 --jq 精确提取（节省 token）
dws contact user get-self --jq '.result[0].orgEmployeeModel | {name: .orgUserName, dept: .depts[0].deptName, userId}'

Schema 发现

Agent 无需预置所有命令知识，通过 dws schema 动态发现可用能力：

# 第一步：发现所有可用产品
dws schema --jq '.products[] | {id, tool_count: (.tools | length)}'

# 第二步：查看目标工具的参数结构
dws schema aitable.query_records --jq '.tool.parameters'

# 第三步：构造正确的调用
dws aitable record query --base-id BASE_ID --table-id TABLE_ID --limit 10

Agent Skills

仓库内置完整的 Agent Skill 体系（skills/），安装后 Claude Code / Cursor 等 AI 工具可通过自然语言直接操作钉钉：

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

install.sh 安装到 $HOME/.agents/skills/dws（全局）；install-skills.sh 安装到 ./.agents/skills/dws（当前项目）。

包含内容：

组件	路径	说明
主 Skill	`SKILL.md`	意图路由、决策树、安全规则、错误处理
产品参考	`references/products/*.md`	各产品命令详细参考（aitable、chat、calendar 等）
意图指南	`references/intent-guide.md`	易混淆场景消歧（如 report vs todo）
全局参考	`references/global-reference.md`	认证、输出格式、全局 flag
错误码	`references/error-codes.md`	错误码 + 调试流程
Recovery 指南	`references/recovery-guide.md`	`RECOVERY_EVENT_ID` 处理
现成脚本	`scripts/*.py`	13 个批量操作脚本（见下方）

现成脚本 — 13 个 Python 脚本，覆盖常见多步工作流

脚本	说明
`calendar_schedule_meeting.py`	一键创建日程 + 添加参与者 + 搜索并预定空闲会议室
`calendar_free_slot_finder.py`	查询多人共同空闲时段，推荐最佳会议时间
`calendar_today_agenda.py`	查看今天/明天/本周的日程安排
`import_records.py`	从 CSV/JSON 批量导入记录到 AI 表格
`bulk_add_fields.py`	批量添加字段到 AI 表格数据表
`upload_attachment.py`	上传附件到 AI 表格 attachment 字段
`todo_batch_create.py`	从 JSON 文件批量创建待办（含优先级、截止时间、执行者）
`todo_daily_summary.py`	汇总今天/本周未完成的待办
`todo_overdue_check.py`	扫描已过截止时间但未完成的待办，输出逾期清单
`contact_dept_members.py`	按部门名称搜索并列出所有成员
`attendance_my_record.py`	查看我今天/本周/指定日期的考勤记录
`attendance_team_shift.py`	查询团队成员本周排班和出勤统计
`report_inbox_today.py`	查看今天收到的日志列表及详情

ISV 集成：编写您自己的 Agent Skill，与 dws 内置 Skill 搭配构建跨产品工作流：ISV Skill → dws Skill → 钉钉开放平台 API（强制鉴权 + 全链路审计）。

功能特性

智能输入纠错 — 自动修正 AI 模型常见的参数错误 v1.0.1

内置 Pipeline 纠错引擎，支持命名风格转换、粘连参数拆分、拼写模糊匹配：

# 命名风格自动转换 (camelCase / snake_case / UPPER → kebab-case)
dws aitable record query --baseId BASE_ID --tableId TABLE_ID         # 自动纠正为 --base-id --table-id

# 粘连参数自动拆分
dws contact user search --keyword "张三" --timeout30                  # 自动拆分为 --timeout 30

# 拼写错误模糊匹配
dws aitable record query --base-id BASE_ID --tabel-id TABLE_ID       # --tabel-id → --table-id

# 参数值归一化 (布尔 / 数字 / 日期 / 枚举)
# "yes" → true, "1,000" → 1000, "2024/03/29" → "2024-03-29", "ACTIVE" → "active"

Agent 输出	dws 自动纠正为
`--userId`	`--user-id`
`--limit100`	`--limit 100`
`--tabel-id`	`--table-id`
`--USER-ID`	`--user-id`
`--user_name`	`--user-name`

jq 过滤 & 字段筛选 — 精确控制输出，减少 token 消耗 v1.0.1

# 内置 jq 表达式
dws aitable record query --base-id BASE_ID --table-id TABLE_ID --jq '.invocation.params'
dws schema --jq '.products[] | {id, tools: (.tools | length)}'

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

Schema 自省 — 调用前查询任意工具的参数结构 v1.0.1

dws schema                                              # 列出所有产品和工具
dws schema aitable.query_records                        # 查看参数 Schema
dws schema aitable.query_records --jq '.tool.required'   # 查看必填字段
dws schema --jq '.products[].id'                        # 提取所有产品 ID

管道 & 文件输入 — 从文件或 stdin 读取 flag 值 v1.0.1

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

# 通过管道传入内容
cat report.md | dws chat message send-by-bot --robot-code BOT_CODE --group GROUP_ID \
  --title "周报"

# 显式从 stdin 读取
dws chat message send-by-bot --robot-code BOT_CODE --group GROUP_ID \
  --title "周报" --text @-

核心服务

服务	命令	工具数	子命令	描述
通讯录	`contact`	8	`user` `dept`	按姓名/手机号搜索、批量查询、部门树、当前用户信息
群聊	`chat`	14	`message` `group` `bot` `search`	群增删改查、成员管理、消息拉取、话题回复、以用户身份发消息
机器人	`chat bot`	9	—	机器人创建、群聊/单聊消息、Webhook、消息撤回
日历	`calendar`	13	`event` `room` `participant` `busy`	日程增删改查、会议室预订、闲忙查询、参与者管理
待办	`todo`	6	`task`	创建、列表、修改、完成、详情、删除
审批	`oa`	9	`approval`	同意/拒绝/撤销、待我审批、我发起的、流程列表
考勤	`attendance`	4	`record` `shift` `summary` `rules`	打卡记录、排班查询、考勤摘要、考勤组规则
DING	`ding`	3	`message`	发送/撤回 DING 消息
日志	`report`	7	`create` `list` `detail` `template` `stats` `sent`	创建日志、收发列表、模版、统计
智能表格	`aitable`	27	`base` `table` `record` `field` `attachment` `template`	多维表/数据表/记录/字段全量 CRUD、视图、导入导出、模板
工作台	`workbench`	2	`app`	批量查询应用详情
开发者文档	`devdoc`	2	`article`	搜索开放平台文档与错误码

12 个产品，104 个工具。运行 dws --help 查看完整列表，或 dws <service> --help 查看子命令。

即将推出

doc（文档）· mail（邮箱）· minutes（AI 听记）· drive（钉盘）· conference（视频会议）· tb（Teambition）· aiapp（AI 应用）· live（直播）· skill（技能市场）

安全设计

dws 从架构层面将安全作为一等公民，而非事后补丁。凭证不落盘、Token 不出域、权限不越界、操作不脱审 — 每一次 API 调用都必须经过钉钉开放平台的鉴权和审计链路，无例外。

开发者安全机制

机制	说明
Token 加密存储	PBKDF2（600,000 次迭代 + SHA-256）+ AES-256-GCM 加密，密钥绑定设备物理 MAC 地址；macOS 集成系统 Keychain、Windows 集成 DPAPI 提供额外保护，跨设备无法解密
输入安全防护	路径遍历防护（符号链接解析 + 工作目录约束）、CRLF 注入拦截、Unicode 视觉欺骗字符过滤，防止 AI Agent 被恶意指令诱导
域名白名单	`DWS_TRUSTED_DOMAINS` 默认仅信任 `*.dingtalk.com`，Bearer Token 不会发送到非白名单域
并发安全	双层锁机制（进程内 + 跨进程文件锁）保障 Token 刷新原子性，适配高并发 MCP Server 场景
数据完整性	所有配置写入采用原子操作（temp + fsync + rename），确保进程中断时数据不损坏
HTTPS 强制	除 loopback 开发调试外，所有请求强制 TLS
Dry-run 预览	`--dry-run` 展示调用参数但不执行，防止误操作生产数据
凭证零落盘	Client ID / Secret 仅在内存中使用，不写入配置文件或日志

企业管理员安全机制

机制	说明
OAuth 设备流认证	用户必须通过管理员授权的钉钉应用认证，未授权应用无法获取 Token
权限最小化	CLI 仅能调用管理员授予该应用的 API 权限范围，无法越权
白名单准入	共创阶段需管理员主动确认开通，后续支持自助审批
操作全链路审计	每一次数据读写都经过钉钉开放平台 API，企业管理员可在管理后台实时追溯完整调用日志，任何异常操作无处隐藏

ISV / 企业服务商安全机制

机制	说明
租户数据隔离	以已授权应用身份调用 API，不同租户数据严格隔离
Skill 沙箱	Agent Skills 是 Markdown 文档（`SKILL.md`），仅提供 prompt 描述，不执行任意代码
集成链路零盲区	ISV Skill 与 dws Skill 联调时，每一次 API 调用都强制经过钉钉开放平台鉴权，完整调用链路可追溯，不存在绕过审计的旁路

发现安全漏洞？请通过 GitHub Security Advisories 报告，详见 SECURITY.md。

参考与文档

参考手册 — 环境变量、退出码、输出格式、Shell 补全
架构设计 — 发现驱动管道、IR、Transport 层
更新日志 — 版本历史与迁移说明

贡献指南

参见 CONTRIBUTING.md 了解构建、测试和开发工作流。

许可证

Apache-2.0

17 KiB Raw Blame History Unescape Escape

DingTalk Workspace CLI (dws)

为什么选择 dws？

安装

开始使用

步骤 1：创建钉钉应用

步骤 2：配置重定向 URL

步骤 3：发布应用

步骤 4：申请白名单

步骤 5：登录认证

快速开始

在 Agent 中使用

Agent 调用模式

Schema 发现

Agent Skills

功能特性

核心服务

安全设计

参考与文档

贡献指南

许可证

17 KiB

Raw Blame History