gabrielmoreira 钉钉 Workspace CLI (dws)
钉钉官方开源的跨平台 CLI 工具，Go 语言开发。为人类用户和 AI Agent 场景同时设计，统一钉钉全套产品能力。
官方 GitHub: https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli 1500+ Stars | Apache-2.0 许可
安装
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
其他方式
# npm（需 Node.js）
npm install -g dingtalk-workspace-cli
# 预编译二进制：从 GitHub Releases 下载
# https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases
认证
dws auth login # 浏览器自动打开授权
dws auth login --device # 无头环境（Docker、SSH、CI）
选择组织并授权即可。凭证使用 PBKDF2 + AES-256-GCM 加密存储。
自定义应用模式（CI/CD、ISV 集成）
dws auth login --client-id <your-app-key> --client-secret <your-app-secret>
产品覆盖（86 条命令，12 个产品）
| 产品 | 命令 | 子命令 | 说明 |
|---|---|---|---|
| 通讯录 contact | 6 | user dept | 按姓名/手机号搜索、批量查询、部门、当前用户 |
| 聊天 chat | 10 | message group search | 群管理、成员管理、机器人消息、webhook |
| 机器人 bot | 6 | bot group message search | 机器人创建/搜索、群/单聊消息、webhook、消息撤回 |
| 日历 calendar | 13 | event room participant busy | 日程 CRUD、会议室预订、忙闲查询、参会人管理 |
| 待办 todo | 6 | task | 创建、列表、更新、完成、详情、删除 |
| 审批 approval | 9 | approval | 同意/拒绝/撤回、待办任务、发起实例、流程列表 |
| 考勤 attendance | 4 | record shift summary rules | 打卡记录、排班、考勤汇总、组规则 |
| 钉 ding | 2 | message | 发送/撤回 DING 消息 |
| 报表 report | 7 | create list detail template stats sent | 创建报表、收发列表、模板、统计 |
| AI 表格 aitable | 20 | base table record field attachment template | 完整增删改查 |
| 工作台 workbench | 2 | app | 批量查询应用详情 |
| 开发文档 devdoc | 1 | article | 搜索平台文档和错误码 |
AI Agent 特性
智能输入纠正
内置管道引擎自动修正 AI 模型常见的参数错误：
| Agent 输出 | dws 自动修正为 |
|---|---|
| --userId | --user-id |
| --limit100 | --limit 100 |
| --tabel-id | --table-id |
| --USER-ID | --user-id |
Schema 自省
Agent 无需预置知识，可动态发现能力：
# 发现所有可用产品
dws schema --jq '.products[] | {id, tool_count: (.tools | length)}'
# 查看目标工具的参数 Schema
dws schema aitable.query_records --jq '.tool.parameters'
jq 过滤与字段选择
# 精确过滤输出，减少 token 消耗
dws aitable record query --base-id BASE_ID --table-id TABLE_ID --jq '.invocation.params'
管道与文件输入
# 从文件读取消息体
dws chat message send-by-bot --robot-code BOT_CODE --group GROUP_ID \
--title "周报" --text @report.md
# 从 stdin 读取
cat report.md | dws chat message send-by-bot --robot-code BOT_CODE --group GROUP_ID \
--title "周报"
Agent Skills 系统
仓库自带完整 Agent Skill 系统（skills/ 目录）：
# 安装 skills 到当前项目
curl -fsSL https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-workspace-cli/main/scripts/install-skills.sh | sh
包含内容
| 组件 | 路径 | 说明 |
|---|---|---|
| Master Skill | SKILL.md | 意图路由、决策树、安全规则、错误处理 |
| 产品参考 | references/products/*.md | 各产品命令参考 |
| 意图指南 | references/intent-guide.md | 易混淆场景消歧 |
| 全局参考 | references/global-reference.md | 认证、输出格式、全局 flags |
| 错误码 | references/error-codes.md | 错误码 + 调试流程 |
| 恢复指南 | references/recovery-guide.md | RECOVERY_EVENT_ID 处理 |
| 预置脚本 | scripts/*.py | 13 个批量操作 Python 脚本 |
预置 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 表格字段 |
| 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 | 查看今日收到的报表详情 |
安全设计
零信任架构：凭证不落盘、Token 不离开可信域、权限不超越授权、操作不逃过审计。
| 机制 | 详情 |
|---|---|
| 加密令牌存储 | PBKDF2 + AES-256-GCM，基于设备物理 MAC 地址加密 |
| 输入安全 | 路径遍历保护、CRLF 注入拦截、Unicode 视觉欺骗过滤 |
| 域名白名单 | DWS_TRUSTED_DOMAINS 默认 *.dingtalk.com，bearer token 不发往非白名单域 |
| HTTPS 强制 | 所有请求要求 TLS |
| Dry-run 预览 | --dry-run 展示调用参数但不执行，防止误操作 |
| 零凭证持久化 | Client ID / Secret 仅在内存中使用 |
升级
dws upgrade # 交互式升级到最新版
dws upgrade --check # 检查新版本
dws upgrade --rollback # 回滚到上一版本
快速开始
dws contact user search --keyword "engineering" # 搜索联系人
dws calendar event list # 列出日历事件
dws todo task create --title "季度报告" --executors "<userId>" # 创建待办
dws todo task list --dry-run # 预览（不执行）
预置脚本
scripts/dws_setup.py
钉钉 CLI 安装和认证脚本。
python3 scripts/dws_setup.py install
python3 scripts/dws_setup.py auth
python3 scripts/dws_setup.py status
scripts/dws_quick.py
钉钉常用操作快捷脚本（dws 薄封装；命令路径以 dws schema 输出为唯一事实源）。
# 通过机器人发消息到群（--text 支持 @file 引用，与 dws CLI 一致）
python3 scripts/dws_quick.py send --robot-code <BOT> --group <GID> --text "你好" --title "通知"
# 搜索联系人
python3 scripts/dws_quick.py contacts --keyword "engineering"
# 列日程
python3 scripts/dws_quick.py calendar
# 创建待办（executors 多个用英文逗号分隔）
python3 scripts/dws_quick.py todo --title "季度报告" --executors "userId1,userId2"
# 透传任意 dws 子命令（attendance/approval 等命名空间快速发现）
python3 scripts/dws_quick.py raw -- attendance --help
python3 scripts/dws_quick.py raw -- approval instance list --help