dingtalk-workspace-cli

• Why dws?
• Installation
• Upgrade
• Getting Started
• Quick Start
• Using with Agents
• Features
• Key Services
• Security by Design
• Reference & Docs
• OpenHarmony build
• Contributing

The installer ships skills in one of two layouts. CLI commands (dws aitable ..., dws calendar ...) are identical in both modes — only the agent-side skill layout differs.

Installs and upgrades default to multi. mono remains available via DWS_SKILL_MODE=mono or dws skill setup --mode mono. File issues if you hit problems.

How to pick:

• Quick install (one-liner above): non-interactive, installs multi.
• TTY install (download then run): curl -O .../install.sh && bash install.sh — prompts 1) multi 2) mono (default 1).
• Override via env: curl -fsSL ... | DWS_SKILL_MODE=mono sh.
• Switch later: dws skill setup --mode mono (or --mode multi) — review the listed paths and confirm interactively.

npm (requires Node.js (npm/npx)):

npm install -g dingtalk-workspace-cli

Install only the CLI binary and skip all bundled Skill validation, extraction, Agent-directory updates, state writes, and user-cache refreshes:

DWS_NO_SKILLS=1 npm install -g dingtalk-workspace-cli

$env:DWS_NO_SKILLS = "1"
npm install -g dingtalk-workspace-cli

Without DWS_NO_SKILLS=1, npm keeps installing Skills as before. A failure while refreshing the optional ~/.dws/skills cache is reported as a warning after the CLI and Agent Skills are installed; run dws skill setup to refresh Skills later.

Install the latest 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

The Formula lives in this repository, so the first tap command must include the explicit repository URL. Afterwards, use brew upgrade dingtalk-workspace-cli normally.

Install the keg-only Homebrew beta without replacing the stable Formula:

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

To make the beta dws the default for the current shell, prepend $(brew --prefix dingtalk-workspace-cli-beta)/bin to PATH.

Pre-built binary: download from GitHub Releases.

macOS users: If you see "cannot be opened because Apple cannot check it for malicious software", run:

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

Build from source:

git clone https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli.git
cd dingtalk-workspace-cli
go build -o dws ./cmd       # build to current directory
cp dws ~/.local/bin/         # install to PATH

Static endpoint data is generated from the Wukong baseline and committed in this repository under internal/syncdata, so source builds do not require a sibling data checkout.

Requires Go 1.26+. On supported macOS, Linux, and Windows amd64/arm64 hosts, the default CGO build includes the SafeChat backend without a build tag and therefore requires a working C compiler. Set CGO_ENABLED=0 only when a stub build is intentional. Use make package with Docker to build all six release targets through the repository's pinned cross-compilation toolchain.

独立二进制的升级分为准备和替换两阶段：

1. 准备 — 官方开源版下载同版本的当前平台归档和技能包，强制验证大小、SHA256 及新二进制版本。自定义 Registry 保留完整 npm 包及完整性校验。验证失败时不替换现有安装。
2. Apply — only after all preparations succeed, the binary is replaced and skills are flattened into the canonical ~/.agents/skills root. Agents classified by the pinned compatibility registry as supporting the universal root read it directly; other detected Agents receive links to the canonical copy, with a direct-copy fallback when links are unavailable. Older DWS-managed agent-specific copies are backed up and retired so the same Skill is not discovered twice.

独立二进制升级保留自动备份和 dws upgrade --rollback。包管理器安装的回退由对应管理器处理；npm/pnpm 没有 --skip-skills 参数，但可设置 DWS_NO_SKILLS=1 仅安装 CLI 二进制。Homebrew 捆绑技能，使用 dws skill setup 安装到 Agent 目录。

1. After selecting your organization, click "Apply Now" to notify the admin
2. The admin receives a request card and can approve with one click
3. Once approved, re-run dws auth login

Go to Developer Platform → "CLI Access Management" → Enable.

For enterprise-managed scenarios, create your own DingTalk app:

1. Open Platform Console → Create App
2. Security Settings → Add redirect URLs: http://127.0.0.1,https://login.dingtalk.com
3. Publish the app
4. Login:

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

Credentials are securely persisted after first login (Keychain). Subsequent runs auto-refresh tokens.

dws can stay logged in to several DingTalk accounts at once, including multiple accounts in the same organization. A profile is uniquely identified by corpId:userId; the current profile decides which identity a command runs as.

Business commands automatically check and refresh local OAuth credentials as needed; there is no need to run auth status before each request. auth status retains refresh, migration and repair behavior and may wait for the authentication lock. For concurrent polling, use dws auth status --readonly --format json (optionally with --profile): it reads a local snapshot without the authentication lock, network validation, refresh, migration or credential writes. System Keychain reads can still wait. Both modes use the same output fields. A read-only result with a non-empty reason is inconclusive and must not be treated as a confirmed logout; local_state_requires_repair signals migration/repair and local_state_unreadable signals a failed local read. Use auth status without --readonly with the same profile for refresh or repair. Read-only mode never reports a refresh and may report an expired access token that normal mode would refresh. Concurrent updates may yield an older snapshot or an inconclusive result. In both modes, authenticated is true when either the access or refresh credential is valid; token_valid separately describes access-token usability.

dws auth login                              # add or refresh one account
dws profile list                            # list every logged-in account
dws profile switch <corpId:userId>          # persistently switch; use - to toggle back
dws profile switch "<corpName>:<userName>"  # friendly input; names must be unique
dws --profile <corpId> contact user search --query "..."        # use that org's explicitly recorded current account
dws --profile <corpId:userId> contact user search --query "..." # use one exact account without changing the default

Selectors support corpId:userId, corpId:userName, corpName:userId, and corpName:userName. Friendly names are input aliases only; use the stable profile value returned by profile list for automation. Duplicate organization or account names fail with explicit corpId:userId candidates. If an organization has multiple accounts but no recorded current account, --profile <corpId> fails instead of choosing the first or most recently used account.

currentProfile, previousProfile, and per-organization defaults are stored as exact identities. primaryProfile remains in JSON only for compatibility and is not used for selection. profile list reads status and expiry from each real identity Token without refreshing it. auth logout --profile <corpId> removes all local accounts in that organization; an exact selector or local profile name removes one account.

Cross-org reads are orchestrated by the agent rather than a built-in --all-orgs: list profiles, group by corpId, and use the unique isOrgCurrent=true account for each organization. If a multi-account organization has no default, ask the user to choose an account first. Writes default to the current account — confirm both organization and account before cross-org writes.

On macOS, transient or unclassified Keychain read failures block a new OAuth login rather than risking a mixed Keychain/file-DEK state. A confirmed missing DEK or ciphertext/DEK mismatch is preserved through authorization and replaced only for the slots targeted by the fresh login. If normal terminal commands can still read the login while a sandbox using DWS_DISABLE_KEYCHAIN=1 cannot, migrate the legacy and profile auth entries without exposing tokens:

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

The migration validates every selected auth ciphertext before writing, ignores unrelated application secrets, and can be rerun after an interrupted commit. If validation identifies genuinely damaged ciphertext, remove only the affected account with dws auth logout --profile <corpId:userId>, or all accounts in one organization with --profile <corpId>, then log in again. Use dws auth reset only when you intend to discard every local profile.

Copying only ~/.dws/app.json does not carry the refresh token; access tokens expire after ~2 hours. Use the official export/import flow:

# Sandbox A (already logged in)
dws auth export -o /tmp/dws-auth.tar.gz
# Or for copy/paste: dws auth export --base64 -o /tmp/dws-auth.b64

# Sandbox B
dws auth import -i /tmp/dws-auth.tar.gz
# Or: dws auth import -i /tmp/dws-auth.b64 --base64
dws auth status   # confirm "Refresh Token: valid"

The bundle includes the encrypted keychain under ~/.local/share/dws-cli (with auth-token.enc and dek) plus required ~/.dws config files. Windows export and import are intentionally rejected before credentials or bundles are read: Windows stores credentials as DPAPI-protected HKCU Registry values, and the current file-DEK bundle has no safe DPAPI-to-portable conversion.

dws event consume subscribes as the currently logged-in user over a managed Stream WebSocket and emits each event as one NDJSON line on stdout. The 28-event public catalog covers scoped and all one-to-one/group messages, specified senders, read/recall/reaction events, group lifecycle events, seven OA approval task/instance events, one VoIP invitation event, three Todo task lifecycle events, and the interactive-card callback event.

The default ndjson, json, and pretty output preserves the transport envelope (type, event_type, string data, and headers) for existing scripts; compact retains its existing processor. Add --flatten to emit the stable top-level business fields used by Agent workflows. --format controls JSON serialization; --flatten controls the data structure and cannot be combined with -f raw or --debug-raw-events.

Prerequisite: run dws auth login. Personal identity is resolved from the OAuth token and cannot be supplied through command-line identity flags.

For an event-focused installation, use the official convenience installer:

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

# Or install the standalone multi skill from an existing dws installation
dws skill setup --mode multi -s event

# Inspect the public personal event catalog and 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 card
dws event schema user_card_action_triggered --flatten
dws event list --category todo
dws event schema user_todo_task_create --flatten

# Listen for messages that mention the current user
dws event +listen-im --kind at-me -f ndjson

# Listen for messages from a specified sender
dws event +listen-im --kind sender --user <userId> -f ndjson

# Listen by openDingtalkId (external contact, bot, or cross-organization identity)
dws event +listen-im --kind sender --open-dingtalk-id <openDingtalkId> -f ndjson

# Listen for messages in a specified group
dws event +listen-im --kind group --chat-id <openConversationId> -f ndjson

# Listen for all one-to-one or all group messages
dws event +listen-im --kind all-direct -f ndjson
dws event +listen-im --kind all-group -f ndjson

# Listen for a specified group's title changes, member changes, or disband event
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

# Listen for messages, reads, and recalls from the same sender in one process
dws event +listen-im --kind sender --user <userId> \
  --events message,read,recall -f ndjson

# Listen for all seven public OA approval events in one process
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

# Listen for Todo create/update/delete events where the current user is an executor
dws event consume \
  user_todo_task_create \
  user_todo_task_update \
  user_todo_task_delete \
  --role-types executor \
  --flatten -f ndjson

# Listen for interactive-card callbacks; the schema documents reviewed fields while preserving extensions
dws event consume user_card_action_triggered --flatten -f ndjson

# Inspect local consumers and cancel a subscription
dws event status
dws event stop <subscribe_id>

The structured interactive-card context is at payload.body.actionData.context. Join questions[].id to answers[question_id], then resolve IDs in selected through the same question's options[].id; an empty selected is a valid no-selection state. JSON strings in body.context are compatibility fallbacks, and every payload level continues to preserve unknown fields.

For one-to-one and specified-sender events, use exactly one target identity: --user for an internal userId, or --open-dingtalk-id for an openDingtalkId. The CLI does not infer or convert between these identity types.

See skills/multi/dingtalk-event/SKILL.md for the Agent workflow and supported event parameters.

dws api lets you call server-side DingTalk OpenAPIs that support an internal-app App Token, without an SDK. Tokens are automatically acquired and refreshed.

Prerequisite: Provide one complete custom-app Client ID/Client Secret pair through one-shot flags, environment variables, or app config saved by a successful login (see Custom App mode). MCP default-credential login alone does not support Raw API calls.

Client ID and Client Secret are resolved only as one complete pair, in this order: complete --client-id/--client-secret > complete DWS_CLIENT_ID/DWS_CLIENT_SECRET > complete app config. A half-configured source fails explicitly and is never combined with another source. Flags/env used directly by dws api are one-shot and do not persist the App Secret; flags/env used by a successful dws auth login are persisted as that exact pair for OAuth refresh and later Raw API calls. The acquired App Token is cached under app-token:<clientID>; the hidden --token accepts a temporary caller-supplied App Token and neither persists nor refreshes it.

Client Secrets use the canonical Keychain slot appsecret:<clientID>, distinct from OAuth User Tokens and App Tokens. Existing plaintext app config and historical client-secret:<clientID> entries are migrated automatically. If the old and new slots disagree, DWS fails closed and asks for a new login instead of guessing.

# Login (first time only)
dws auth login --client-id <APP_KEY> --client-secret <APP_SECRET>

# Or use one environment pair; a complete env pair overrides app config atomically
export DWS_CLIENT_ID=<APP_KEY>
export DWS_CLIENT_SECRET=<APP_SECRET>

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

# List all enterprise apps
dws api GET /v1.0/microApp/allApps

# Search users (POST + JSON body)
dws api POST /v1.0/contact/users/search \
  --data '{"queryWord":"engineering","offset":0,"size":10}'

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

# Get user details (use --base-url to specify domain)
dws api POST /topapi/v2/user/get \
  --base-url https://oapi.dingtalk.com \
  --data '{"userid":"<USER_ID>"}'

# Or use the full URL directly
dws api POST https://oapi.dingtalk.com/topapi/v2/user/get \
  --data '{"userid":"<USER_ID>"}'

# === General ===
dws api GET /v1.0/microApp/allApps --dry-run             # preview request
dws api GET /v1.0/microApp/allApps --jq '.appList | length'  # jq filtering

# Read a JSON body from a file (--params also accepts @file; use - for stdin)
dws api POST https://oapi.dingtalk.com/topapi/v2/department/listsubid \
  --data @department-request.json --dry-run

# Stream one multipart file; top-level --data fields become text form fields; review a dry-run first
dws api POST https://oapi.dingtalk.com/media/upload \
  --data '{"type":"image"}' --file media=./demo.png --dry-run

dws api automatically uses only an internal-app App Token. It does not read OAuth User Tokens and does not expose --as user / --user. Prefer an existing DWS product command; use this escape hatch only for an uncovered internal-app server OpenAPI. Review a dry-run and confirm before create, update, delete, revoke, or send operations.

Built-in pipeline engine that normalizes flag names, splits sticky arguments, and fuzzy-matches typos:

# Naming convention auto-conversion (camelCase / snake_case / UPPER -> kebab-case)
dws aitable record query --baseId BASE_ID --tableId TABLE_ID         # auto-corrected to --base-id --table-id

# Sticky argument splitting
dws contact user search --query "engineering" --timeout30           # auto-split to --timeout 30

# Fuzzy flag name matching
dws aitable record query --base-id BASE_ID --tabel-id TABLE_ID       # --tabel-id -> --table-id

# Value normalization (boolean / number / date / enum)
# "yes" -> true, "1,000" -> 1000, "2024/03/29" -> "2024-03-29", "ACTIVE" -> "active"

# Built-in jq expressions
dws aitable record query --base-id BASE_ID --table-id TABLE_ID --jq '.invocation.params'
dws schema "dev app create" --jq '.parameters'

# Return only specific fields
dws aitable record query --base-id BASE_ID --table-id TABLE_ID --fields invocation,response

dws schema aitable --compact                            # discover product commands
dws schema "aitable record query" --compact             # view the selected Agent leaf contract
dws schema "aitable record query" --jq '[.parameters | to_entries[] | select(.value.required)]' # view required fields
dws schema --all                                        # full export for CI/audit/baselines

# Read message body from a file
dws chat message send-by-bot --robot-code BOT_CODE --group GROUP_ID \
  --title "Weekly Report" --text @report.md

# Pipe content via stdin
cat report.md | dws chat message send-by-bot --robot-code BOT_CODE --group GROUP_ID \
  --title "Weekly Report"

# Read from stdin explicitly
dws chat message send-by-bot --robot-code BOT_CODE --group GROUP_ID \
  --title "Weekly Report" --text @-

Note: @ is treated as the @<path> file-injection prefix only when the next character is an ASCII path-shaped character (A-Z / a-z / 0-9 / . / / / ~ / _ / -), or @- for stdin. Chat-bot payloads like --text "@所有人 周报" or --text "@张三 看一下" pass through unchanged, so literal mentions reach the API as-is.

• conference (video meetings)
• Multi-skill mode (default) — per-product skills under skills/multi/; installs and upgrades default to it, dws skill setup --mode mono switches back after interactive confirmation

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

安装时可以选择两种 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）。
• 环境变量覆盖：curl -fsSL ... | DWS_SKILL_MODE=mono 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.26+。在支持的 macOS、Linux、Windows amd64/arm64 平台上，默认 CGO 构建无需 build tag 即包含 SafeChat 后端，因此本机构建需要可用的 C 编译器。 只有明确需要 stub 时才设置 CGO_ENABLED=0。使用 make package 和 Docker 可通过仓库固定的交叉编译工具链构建全部六个平台产物。 静态端点数据由悟空基线生成并提交在本仓库 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 唯一确定。

业务命令会检查本地 OAuth token 并按需自动刷新，无需先执行认证状态查询。 dws auth status 保留刷新、迁移和修复能力，可能等待认证锁。 并发轮询请使用 dws auth status --readonly --format json（支持 --profile）：只读本地快照，不获取认证锁、不刷新、不迁移或写入凭证；系统 Keychain 读取仍可能等待。 两种模式返回相同字段，但只读模式不会报告刷新成功，可能返回普通模式会刷新掉的过期 token 状态。 只读结果的 reason 非空时表示无法判断，不能仅凭 authenticated: false 当作已确认未登录；local_state_requires_repair 表示需要迁移或修复，local_state_unreadable 表示读取失败。 需要刷新或修复时使用相同 profile 运行 auth status（不加 --readonly）。 两种模式的 authenticated 判断一致：access token 或 refresh token 任一个有效即为已认证；token_valid 单独表示 access token 是否可用。 本地快照不验证服务端状态，并发更新时可能读到旧值或无法确定的结果。

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 下，瞬态或未分类的 Keychain 读取失败仍会拒绝新的 OAuth 登录，避免把系统 Keychain 和 file-DEK 写成混合状态。已确认的 DEK 缺失或密文/DEK 不匹配会保留到授权完成，并且只替换本次新登录实际写入的 token slot。如果普通终端仍能读取登录态、只有设置 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。当前 28 个公开事件覆盖指定范围和全量单聊/群消息、指定发送人、已读/撤回/表情回应、群生命周期、七个 OA 审批任务/实例事件、一个 VoIP 通话邀请事件、三个待办生命周期事件，以及互动卡片回调事件。

默认 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 card
dws event schema user_card_action_triggered --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

# 监听互动卡片回调；Schema 描述已评审字段并保留未知扩展
dws event consume user_card_action_triggered --flatten -f ndjson

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

互动卡片的结构化操作上下文位于 payload.body.actionData.context。通过 questions[].id 关联 answers[question_id]，再按同一问题的 options[].id 解析 selected 中的选项 ID；空 selected 是合法未选择状态。body.context 中的 JSON 字符串仅作兼容回退，所有 payload 层级仍保留未知字段。

单聊和指定发送人事件必须且只能选择一种目标身份：企业内部 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