SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场dingtalk-workspace-cli

dingtalk-workspace-cli

办公与效率

查看项目

更新于 10-13 20:10

技能介绍

钉钉 Workspace CLI（命令名 dws）是钉钉官方开源的跨平台命令行工具，将钉钉的完整产品套件统一到一个二进制文件中，面向人类用户和 AI 智能体工作流两类使用者设计。每个响应都是结构化 JSON，内置的 Agent Skills 让大语言模型可以开箱即用地使用钉钉能力。

一、用途 通过 dws 可以在命令行或 AI 智能体工作流中管理钉钉联系人、日历、待办、考勤、审批等业务内容，并可用于脚本自动化、CI/CD 状态推送等场景。

二、主要能力

  1. 认证：登录、登出、查看认证状态。
  2. 联系人：搜索用户、列出部门、获取用户详情。
  3. 日历：列出事件、创建事件（含标题、起止时间、参与人）、查看会议室可用性。
  4. 待办：列出任务、创建任务（指定标题与执行人）、完成任务。
  5. 会话：列出群组、通过 Webhook 发送消息、发送机器人消息。
  6. 考勤：查询考勤记录、列出班次排班。
  7. 审批：列出审批模板、提交审批实例、查询审批实例。
  8. DING 消息：发送与撤回 DING 消息。
  9. AI 表格（aitable）：列出表格、查询记录。
  10. 开发者文档：搜索钉钉开放平台文档。
  11. 工作台：列出工作台应用。

三、使用方式

  1. 安装 推荐一行命令安装。 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

安装程序会自动检测操作系统与架构，下载预编译二进制到 ~/.local/bin，并把 Agent Skills 安装到 ~/.agents/skills/dws。必要时加入 PATH： export PATH="$HOME/.local/bin:$PATH" （可写入 ~/.bashrc 或 ~/.zshrc 以持久生效）

从源码构建： git clone https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli.git cd dingtalk-workspace-cli make build ./dws version

  1. 前置条件与设置 （1）创建钉钉应用：前往钉钉开放平台，创建企业内部应用，记下 Client ID（AppKey）与 Client Secret（AppSecret）。 （2）配置重定向 URL：在应用的安全设置中添加 http://127.0.0.1 作为重定向 URL。 （3）发布应用：前往应用发布 → 版本管理，发布应用使其生效。 （4）白名单（beta）：共创阶段需加入钉钉 DWS 群并提供 Client ID 与企业管理员确认以加入白名单。 （5）认证： 使用 CLI 参数： dws auth login --client-id $DWS_CLIENT_ID --client-secret $DWS_CLIENT_SECRET 或先设置环境变量再登录： export DWS_CLIENT_ID=your-app-key export DWS_CLIENT_SECRET=your-app-secret dws auth login 令牌使用 PBKDF2（600,000 次迭代）加 AES-256-GCM 加密存储，并绑定设备 MAC 地址。

  2. 环境变量 DWS_CLIENT_ID：OAuth Client ID（钉钉 AppKey） DWS_CLIENT_SECRET：OAuth Client Secret（钉钉 AppSecret） DWS_CONFIG_DIR：覆盖默认配置目录 DWS_SERVERS_URL：自定义服务注册端点 DWS_TRUSTED_DOMAINS：用于 bearer token 的逗号分隔域名（默认 *.dingtalk.com） DWS_ALLOW_HTTP_ENDPOINTS：设为 1 以允许回环地址上的 HTTP（仅开发用）

  3. 输出格式 所有命令支持 -f / --format： table：人类可读表格（默认） json：结构化 JSON（供智能体与管道使用） raw：原始 API 响应 保存输出到文件： dws contact user search --keyword "Alice" -f json -o results.json

  4. 干跑（Dry Run） 预览 MCP 工具调用而不实际执行： dws todo task list --dry-run dws calendar event create --title "Test" --dry-run

  5. 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

  6. 退出码 0 成功；1 API（MCP 工具调用或上游 API 失败）；2 认证（认证或授权失败）；3 校验（输入参数错误或模式不匹配）；4 发现（服务发现或缓存失败）；5 内部（意外内部错误）。使用 -f json 时错误包含结构化字段：category、reason、hint、actions。

四、适用场景

  1. 脚本化：例如先搜索用户再为其创建待办，或发送每日站会提醒。
  2. CI/CD：把构建状态推送到钉钉群。
  3. 在 Go 项目中调用 dws（通过 os/exec 调用并解析 JSON）。
  4. AI 智能体集成：dws 会自动安装 Agent Skills，多数 AI 编程智能体（Claude Code、Cursor、Windsurf 等）会自动发现 .agents/skills/ 中的技能。可为特定项目安装技能： curl -fsSL https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-workspace-cli/main/scripts/install-skills.sh | sh 技能位于 ./.agents/skills/dws/，可提交到仓库，让所有协作者与智能体自动获得钉钉能力。典型触发提示如查找某用户的钉钉 ID、为某人创建待办、列出明天的日历事件、向团队负责人发送 DING 消息、查询某用户本月考勤记录。

五、架构概览 dws 使用发现驱动的流水线，不硬编码任何产品命令： Market Registry → Discovery → IR（规范化目录）→ CLI（Cobra）→ Transport（MCP JSON-RPC） Market：从 mcp.dingtalk.com 获取 MCP 服务注册表。 Discovery：解析服务能力，带 TTL 缓存到磁盘并支持过期回退以供离线使用。 IR：将服务规范化为统一的产品/工具目录。 CLI：把目录挂载到 Cobra 命令树，将标志映射为 MCP 输入参数。 Transport：执行 MCP JSON-RPC 调用，带重试、认证注入和响应大小限制。

六、开发 make build：构建二进制 make test：运行单元测试 make lint：格式化与检查 make package：本地构建全部发布产物（goreleaser snapshot） make release：通过 goreleaser 构建并发布

七、限制与故障排查

  1. dws: command not found：执行 export PATH="$HOME/.local/bin:$PATH"。
  2. 认证错误（退出码 2）：检查 DWS_CLIENT_ID 与 DWS_CLIENT_SECRET 是否正确；确认应用已发布且配置了重定向 URL http://127.0.0.1；确认企业已加入白名单（测试阶段必需）。
  3. 发现失败（退出码 4）：dws 会缓存服务发现，缓存过期时可删除： rm -rf "${DWS_CONFIG_DIR:-$HOME/.config/dws}/cache" 若使用自定义注册表，设置 DWS_SERVERS_URL。
  4. API 错误（退出码 1）：用 dws todo task list -f json 获取结构化错误详情（包含 category、reason、hint、actions）。
  5. 检查原始请求：dws contact user search --keyword "Alice" -f raw。
  6. 本地开发/测试允许 HTTP：export DWS_ALLOW_HTTP_ENDPOINTS=1。

其他如收费、价格、平台支持范围等细节暂未提供。