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

安装时可以选择两种 skill 组织方式。两种模式下 CLI 命令完全一样（dws aitable ... / dws calendar ...），区别只在 Agent 那边读到的 skill 文档结构。

安装与升级默认均为 multi。mono 仍可通过 DWS_SKILL_MODE=mono 或 dws skill setup --mode mono 使用。问题请提 issue 反馈。

怎么选：

• 快速安装（上方一行 curl）：非交互，默认装 multi。
• TTY 安装（先下载再执行）：curl -O .../install.sh && bash install.sh，会弹出 1) multi 2) mono 选项（默认 1）。
• 环境变量覆盖：DWS_SKILL_MODE=mono curl -fsSL ... | sh。
• 装完之后再切换：dws skill setup --mode mono（或 --mode multi），核对列出的路径后交互确认。

npm（需要 Node.js（npm/npx））：

npm install -g dingtalk-workspace-cli

安装最新 beta：

npm install -g dingtalk-workspace-cli@beta

Homebrew（macOS / Linux）：

brew tap DingTalk-Real-AI/dingtalk-workspace-cli https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli.git
brew install dingtalk-workspace-cli

Formula 与代码位于同一个仓库，因此首次 tap 需要显式指定仓库 URL。后续可直接使用 brew upgrade dingtalk-workspace-cli。

安装 Homebrew beta（keg-only，不覆盖稳定版）：

brew install dingtalk-workspace-cli-beta
$(brew --prefix dingtalk-workspace-cli-beta)/bin/dws version

如需让 beta 的 dws 成为当前 shell 默认版本，将 $(brew --prefix dingtalk-workspace-cli-beta)/bin 放到 PATH 最前面。

预编译二进制文件：从 GitHub Releases 下载。

macOS 用户注意：如果提示“无法打开，因为 Apple 无法检查其是否包含恶意软件”，请执行：

xattr -d com.apple.quarantine /path/to/dws

从源码构建：

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$ 构建所有平台产物（\text{macOS} / \text{Linux} / \text{Windows} \times \text{amd64} / \text{arm64}）。 静态端点数据由悟空基线生成并提交在本仓库 $internal/syncdata，源码构建不需要额外 checkout 数据仓库。

升级过程采用两阶段原子流程，确保一致性：

1. 准备阶段 — 将平台对应的二进制文件和技能包下载到临时目录，校验 SHA256 校验和，解压并验证所有文件。任何步骤失败则立即中止，不会修改现有安装。
2. 执行阶段 — 仅在所有准备工作成功后，替换二进制文件并将技能包平铺到已检测到的具体 Agent 目录（例如 ~/.codex/skills/dingtalk-chat、~/.claude/skills/dingtalk-chat）。只有未检测到具体 Agent 时才使用 ~/.agents/skills；检测到具体 Agent 后会备份迁走旧的 DWS 通用副本，避免同一 Skill 被重复发现。

每次升级前自动备份当前版本，可通过 dws upgrade --rollback 随时回滚。

1. 选择组织后，点击「立即申请」通知管理员
2. 管理员收到申请卡片，一键审批
3. 审批通过后，重新执行 dws auth login

进入 开发者平台 →「CLI 访问管理」→ 开启。

企业自主管控场景，可创建自有钉钉应用：

1. 开放平台应用开发后台 → 创建应用
2. 安全设置 → 添加重定向 URL：http://127.0.0.1,https://login.dingtalk.com
3. 发布应用
4. 登录：

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

首次登录后凭证安全存储（Keychain），后续自动刷新 Token。

dws 可以同时登录多个钉钉账号，同一组织也能保留多个账号。一个 profile 由 corpId + userId 唯一确定。

dws auth login                              # 新增或刷新一个账号
dws profile list                            # 列出全部账号，profile 字段是稳定的 corpId:userId
dws profile switch <corpId:userId>          # 持久切换账号；用 - 切回上一个
dws profile switch "组织名:用户名"          # 名称输入要求唯一
dws --profile <corpId> contact user search --query "..."        # 使用该组织明确记录的当前账号
dws --profile <corpId:userId> contact user search --query "..." # 单次精确指定账号，不改默认账号

支持 corpId:userId、corpId:userName、corpName:userId、corpName:userName。名称只用于输入，自动化应使用 profile list 返回的稳定 profile。组织名或用户名重名时会列出候选并报错；同组织多账号但没有明确当前账号时，只传组织也会报错，不会选择第一项或最近使用账号。

currentProfile、previousProfile 和组织默认账号都保存精确身份。primaryProfile 只为 JSON 兼容保留，不再参与选择。profile list 直接读取各身份 Token 计算状态和到期时间，不触发刷新。auth logout --profile <corpId> 退出该组织全部账号；精确选择器或本地 profile 名只退出一个账号。

跨组织读取由 agent 编排，而非内置 --all-orgs：先 dws profile list，每个组织使用唯一的 isOrgCurrent=true 账号；若多账号组织没有默认账号，先让用户指定账号。写操作默认只在当前账号执行——跨组织写之前先确认目标组织和账号。

macOS 下，如果已登记的 token slot 无法解密，为避免把系统 Keychain 和 file-DEK 写成混合状态，新的 OAuth 登录会直接拒绝。如果普通终端仍能读取登录态、只有设置 DWS_DISABLE_KEYCHAIN=1 的沙箱读不到，可在不暴露 token 的情况下迁移 legacy 与各 profile 的认证条目：

env -u DWS_DISABLE_KEYCHAIN dws auth migrate-keychain --to file-dek --dry-run --format json
env -u DWS_DISABLE_KEYCHAIN dws auth migrate-keychain --to file-dek --yes --format json
DWS_DISABLE_KEYCHAIN=1 dws auth status --format json

迁移会先验证全部认证密文再写入、忽略无关的应用密钥；提交中断后可安全重跑。如果预检确认是密文本身损坏，优先使用 dws auth logout --profile <corpId:userId> 只清理受影响账号；只有确认要丢弃全部本地 profile 时才用 dws auth reset。

仅拷贝 ~/.dws/app.json 无法带走 refresh token；access token 约 2 小时后会失效。请使用官方导出/导入：

# A 沙箱（已登录）
dws auth export -o /tmp/dws-auth.tar.gz
# 或便于分片复制：dws auth export --base64 -o /tmp/dws-auth.b64

# B 沙箱
dws auth import -i /tmp/dws-auth.tar.gz
# 或：dws auth import -i /tmp/dws-auth.b64 --base64
dws auth status   # 确认 Refresh Token: 有效

包内包含 ~/.local/share/dws-cli 加密 keychain（含 auth-token.enc 与 dek）及 ~/.dws 必要配置。

dws event consume 使用当前 OAuth 登录用户建立托管的 Stream WebSocket 长连接，并把每条事件以 NDJSON 一行输出到 stdout。当前公开目录覆盖指定范围和全量单聊/群消息、指定发送人、已读/撤回/表情回应、群生命周期、七个 OA 审批任务/实例事件，以及三个待办生命周期事件。

默认 ndjson、json、pretty 输出保留兼容 transport envelope（type、event_type、字符串 data、headers），compact 继续沿用原 processor。Agent 或新脚本显式加 --flatten 后，输出稳定的顶层业务字段。--format 控制 JSON 序列化，--flatten 控制数据结构，且不能与 -f raw 或 --debug-raw-events 同时使用。

前置条件：先运行 dws auth login。个人身份从 OAuth token 解析，不允许通过命令行伪造。

只需要 event 能力时，可以使用官方便捷安装脚本：

curl -fsSL https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-workspace-cli/main/scripts/install-event.sh | sh

# 或在已有 dws 环境中安装独立的 multi skill
dws skill setup --mode multi -s event

# 查看公开个人事件目录和 schema
dws event list
dws event schema user_im_message_receive_o2o --flatten
dws event list --category oa
dws event schema user_oa_approval_task_created --flatten
dws event list --category todo
dws event schema user_todo_task_create --flatten

# 监听当前用户被 @ 的消息
dws event +listen-im --kind at-me -f ndjson

# 监听指定发送人的消息
dws event +listen-im --kind sender --user <userId> -f ndjson

# 使用 openDingtalkId 监听外部联系人、机器人或跨组织身份
dws event +listen-im --kind sender --open-dingtalk-id <openDingtalkId> -f ndjson

# 监听指定群的消息
dws event +listen-im --kind group --chat-id <openConversationId> -f ndjson

# 监听所有单聊或所有群消息
dws event +listen-im --kind all-direct -f ndjson
dws event +listen-im --kind all-group -f ndjson

# 监听指定群标题变更、成员进退群或群解散
dws event consume user_im_group_updated --group <openConversationId> --flatten -f ndjson
dws event consume user_im_group_member_added --group <openConversationId> --flatten -f ndjson
dws event consume user_im_group_member_exited --group <openConversationId> --flatten -f ndjson
dws event consume user_im_group_disbanded --group <openConversationId> --flatten -f ndjson

# 一个进程监听同一发送人的消息、已读和撤回
dws event +listen-im --kind sender --user <userId> \
  --events message,read,recall -f ndjson

# 一个进程监听全部七个公开 OA 审批事件
dws event consume \
  user_oa_approval_task_created \
  user_oa_approval_task_finished \
  user_oa_approval_task_redirected \
  user_oa_approval_instance_started \
  user_oa_approval_instance_cc \
  user_oa_approval_instance_terminated \
  user_oa_approval_instance_finished \
  --flatten -f ndjson

# 监听当前用户作为执行者的待办创建、更新和删除事件
dws event consume \
  user_todo_task_create \
  user_todo_task_update \
  user_todo_task_delete \
  --role-types executor \
  --flatten -f ndjson

# 查看本地 consume，并取消指定订阅
dws event status
dws event stop <subscribe_id>

单聊和指定发送人事件必须且只能选择一种目标身份：企业内部 userId 使用 --user，openDingtalkId 使用 --open-dingtalk-id。CLI 不会自动猜测或转换身份类型。

Agent 工作流和事件参数详见 skills/multi/dingtalk-event/SKILL.md。

dws api 让你直接调用支持企业内部应用 App Token 的钉钉服务端 OpenAPI，无需 SDK，Token 自动获取和刷新。

前置条件：必须提供一对完整的自有应用 Client ID/Client Secret，可来自本次 flags、环境变量或成功登录后保存的 app config（见自建应用模式）。仅通过 MCP 默认凭证登录不支持 Raw API 调用。

Client ID/Client Secret 必须来自同一完整凭证对，优先级为：完整 --client-id/--client-secret > 完整 DWS_CLIENT_ID/DWS_CLIENT_SECRET > 完整 app config。任一来源只提供一项都会明确失败，不会与其他来源拼接。直接用于 dws api 的 flags/env 仅对本次调用生效，不持久化 AppSecret；成功执行 dws auth login 时使用的 flags/env 则会按实际使用的完整 pair 持久化，供 OAuth 刷新和后续 Raw API 使用。获取到的 App Token 会按 app-token:<clientID> 缓存；隐藏 --token 仅临时使用调用方提供的 App Token，不持久化、不自动刷新。

Client Secret 统一使用 Keychain 槽位 appsecret:<clientID>，与 OAuth User Token、App Token 完全隔离。历史明文 app config 和 client-secret:<clientID> 会自动迁移；新旧槽位值不一致时 fail closed，要求重新登录，不猜测正确值。

# 登录（仅首次）
dws auth login --client-id <APP_KEY> --client-secret <APP_SECRET>

# 或使用一对环境变量，完整 env pair 会整体覆盖 app config
export DWS_CLIENT_ID=<APP_KEY>
export DWS_CLIENT_SECRET=<APP_SECRET>

# === api.dingtalk.com ===

# 获取企业所有应用列表
dws api GET /v1.0/microApp/allApps

# 搜索用户 (POST + JSON body)
dws api POST /v1.0/contact/users/search \
  --data '{"queryWord":"张三","offset":0,"size":10}'

# === oapi.dingtalk.com ===

# 获取用户详情（使用 --base-url 指定域名）
dws api POST /topapi/v2/user/get \
  --base-url https://oapi.dingtalk.com \
  --data '{"userid":"<USER_ID>"}'

# 也可以直接使用完整 URL
dws api POST https://oapi.dingtalk.com/topapi/v2/user/get \
  --data '{"userid":"<USER_ID>"}'

# === 通用功能 ===
dws api GET /v1.0/microApp/allApps --dry-run             # 预览请求
dws api GET /v1.0/microApp/allApps --jq '.appList | length'  # jq 过滤

# 从文件读取 JSON body（--params 也支持 @file；也可用 - 从 stdin 读取）
dws api POST https://oapi.dingtalk.com/topapi/v2/department/listsubid \
  --data @department-request.json --dry-run

# 单文件流式 multipart 上传；--data 顶层字段转为文本 form field；先 dry-run 核对
dws api POST https://oapi.dingtalk.com/media/upload \
  --data '{"type":"image"}' --file media=./demo.png --dry-run

dws api 只自动使用企业内部应用的 App Token，不读取 OAuth User Token，也不提供 --as user / --user。优先使用已有 DWS 产品命令；只有未封装的企业内部应用服务端 OpenAPI 才使用 Raw 逃生舱。写、删、撤销等操作须在 dry-run 核对并确认后执行。

内置 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 --query "张三" --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"

# 内置 jq 表达式
dws aitable record query --base-id BASE_ID --table-id TABLE_ID --jq '.invocation.params'
dws schema "dev app create" --jq '.parameters'

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

dws schema aitable --compact                            # 发现产品命令
dws schema "aitable record query" --compact             # 查看 Agent leaf 契约
dws schema "aitable record query" --jq '[.parameters | to_entries[] | select(.value.required)]' # 定向查看必填字段
dws schema --all                                        # CI/审计/基线的全量导出

# 从文件读取消息内容
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 @-

说明：@ 仅在其后是 ASCII 路径前缀字符（A-Z / a-z / 0-9 / . / / / ~ / _ / -）或 @-（stdin）时，才会被识别为 @<path> 文件注入语法。--text "@所有人 周报" / --text "@张三 看一下" 这类机器人消息中的字面 @ 提及会原样透传到 API。

• conference（视频会议）
• 多 skill 模式（默认）— 每产品一个独立 skill，位于 skills/multi/，安装与升级默认启用；dws skill setup --mode mono 交互确认后可切回单 skill