---
name: dws-shared
description: dws 多 skill 模式的公共参考——认证、全局参数、Schema 命令发现、多组织 / --profile 规则、安全底线。所有 dingtalk-* 子 skill 执行前先读本 skill。命令前缀：dws。
cli_version: ">=1.0.40"
metadata:
category: productivity
stability: experimental
requires:
bins:
- dws
---
# DWS 公共参考（dws-shared）
> 🧪 **EXPERIMENTAL · 试验版 / Preview** — multi 模式当前未达 stable 标准；生产 / 共享环境请优先使用 mono 模式（`dws skill setup --mode mono`）。
每个 dingtalk-* 子 skill 都把本 skill 列为 PREREQUISITE：执行任何产品命令前先读这里的认证、全局参数、Schema 命令发现与多组织规则。`dws` 必须在 PATH 上。
## 认证
- `dws auth login`（新账号新增 profile，同一 `corpId + userId` 重登只刷新该账号）；`--device` 无头 / SSH 登录
- `dws auth status [--profile <selector>]` 查看组织当前账号或指定账号；会尝试刷新，失败时保留真实错误
- macOS 出现 `ciphertext_key_mismatch` 且普通终端仍可登录时：先运行 `env -u DWS_DISABLE_KEYCHAIN dws auth migrate-keychain --to file-dek --dry-run --format json`，通过后加 `--yes` 迁移；不要直接 `auth reset`
## 全局参数
- 所有命令加 `--format json` 取可解析输出
- 全局 `--profile <selector>`：支持 `corpId:userId`、`corpId:userName`、`corpName:userId`、`corpName:userName`，也兼容单独的 corpId、唯一 corpName 和本地 profile 名；均不改默认 profile
- 以 leaf Schema 的 `confirmation` 为准：`user_required` 才先确认并在同意后加 `--yes`；`not_required` 不得仅因 `effect=write` 自行升级确认要求
## 命令发现：Schema + --help
选择命令、读取参数映射/组合约束与安全语义时，优先渐进查询当前二进制内嵌的 leaf Schema；真正组装参数前，用 `--help` 确认 Cobra 当前接受的 flags：
本节适用于进入 Runtime Schema 的基础/原子命令。`+` shortcut 是明确例外，使用下方独立 shortcut catalog 契约。
```bash
dws schema # 产品概览
dws schema calendar # 产品工具列表
dws schema "calendar event" # 命令分组
dws schema "calendar event create" --compact # 完整 leaf 契约
```
`--all` 会导出全部工具的完整 leaf，输出很大。仅在用户明确要求全量导出，或执行 CI、Catalog 审计、参数防丢 baseline 时使用 `dws schema --all --format json`；普通业务任务必须渐进查询，不得把全量结果注入上下文。完整 baseline 不得使用会裁剪 provenance 的 `--all --compact`。
| 要确认的信息 | 事实源 |
|-------------|--------|
| 命令是否存在、Cobra 接受哪些 flags | `dws <cli_path> --help` |
| Agent 选命令、参数映射/约束、risk/confirmation（原子/基础命令） | `dws schema "<cli_path>"` |
| shortcut 的参数、约束、risk/confirmation、示例 | `dws shortcut list --service <service> --format json` |
| 钉钉中的文档、日程、消息等业务数据 | 真正执行对应的 `read` / `search` / `list` 命令 |
Schema 与 Help 冲突属于契约漂移：参数只用 Help 接受的 flags，并报告漂移；安全语义冲突时采用更保守的确认方式。Schema 只描述命令契约，不能替代业务查询。
## Shortcut 可用性
- `shortcut` 是对常用操作的高层封装。先按产品 skill 的意图表、脚本和 recipe 路由：存在精确覆盖场景的专用脚本/recipe 时按其执行；否则可见 shortcut 优先于手写等价原子流程。
- shortcut 有独立 catalog，按设计不进入 Runtime Schema。用 `dws shortcut list --service <service> --format json` 读取 flags、required/enum、跨参数 constraints、risk/confirmation 和 examples；不要对 `+` 路径调用 `dws schema`。
- 真正组装参数前用叶子帮助 `dws <service> +<verb> --help` 核对 Cobra 接受的 flags；父级 `dws <service> --help` 只能用于发现子命令。
- shortcut catalog 中 `confirmation=user_required` 时先获得用户确认，确认后才加 `--yes`；`not_required` 不额外确认。
- 如果 shortcut 不在 help / list 中，改用产品参考里的原子命令、脚本或标准流程；不要猜测未展示的 `+` 命令。
## 多组织 / --profile（关键规则）
dws 可同时登录多个钉钉账号，同一组织也可保留多个账号。一个 profile 由 `corpId + userId` 唯一确定；`dws profile list --format json` 默认显示全部账号，稳定选择器读取每项 `profile`。
- **选择规则**：名称只用于输入，自动化使用 `profile=corpId:userId`。名称重名时按报错候选改用稳定选择器，不得猜测。
- **组织默认账号**：只传组织时使用唯一 `isOrgCurrent=true` 的账号。多账号组织没有默认账号时先让用户指定账号；禁止选择第一项、最近登录或最近使用账号。
- **跨组织铁律**：任何读 / 搜在当前组织没命中、且按 `corpId` 去重后有 ≥2 个组织时，每个组织使用唯一组织默认账号的 `profile` 各搜一遍。禁止把同组织多个账号重复执行。
- **单组织**：只有 1 个组织时按当前账号处理；用户明确指定账号时使用该账号的稳定 `profile`。
- **安全护栏**：自动跨组织只对「读 / 搜」；写 / 发 / 删 / 撤回等操作默认只在当前组织做，确需带 `--profile` 跨组织写时先与用户确认目标组织；持久切换 `dws profile switch`（改默认组织）属写操作，未经用户明确要求不得执行。
- 完整命令与跨组织聚合见 `dingtalk-profile` skill。
## 错误处理
- `unknown command` / `unknown flag`：先跑 `dws <path> --help` 查证再修正一次，别把自然语言当命令 / flag
- 服务端 token 过期：提示用户 `dws auth login` 重新登录；本地密钥不匹配按上面的 macOS 迁移流程处理，不要混为 token 过期
- 业务错误码 / 接口语义：用 `dws devdoc article search --query "<关键词>" --format json` 查官方文档，不编造原因