Dingtalk Unified

钉钉套件（DingTalk Unified）

通过官方 dws（DingTalk Workspace CLI）调用钉钉产品能力。dws 的产品域和命令数随版本动态更新，本 Skill 不把静态命令表当作唯一真相；执行时以 dws --help、dws <domain> --help 和 dws schema 为准，并提供意图路由、安全策略、授权策略、命令发现策略和错误恢复策略。

使用前置流程

Step 1：确认 dws 可用

优先使用系统 PATH 中的 dws：

dws version --format json

如果命令不存在，先安装官方 npm 包：

npm install -g dingtalk-workspace-cli

安装后再次执行：

dws version --format json

要求版本满足 >=1.0.26。低版本可能缺少 ndjson/csv 输出格式、--content/--content-file flag、群消息 --title 必填、auth 凭证按版本分区、schema sticky flag splitting 等能力和修复。

Step 2：检查登录状态

dws auth status --format json

• 已登录：继续执行用户请求。
• 未登录 / token 失效：进入授权流程。

权限三层模型：

1. OAuth 登录：解决“当前用户是谁”。
2. 组织 CLI 访问：解决“企业/组织是否允许 CLI 访问数据”。
3. 业务 PAT scope：解决"某个具体动作是否被允许"，例如读取钉钉文档需要 doc:read。

不要把"已登录"误判为"所有业务权限都已授权"。

凭证存储说明（v1.0.29+）：dws 按 CLI 版本分区存储 OAuth 凭证（app.json 按版本隔离），多版本共存时不会互相覆盖。升级后首次使用可能需要重新登录。

授权触发规则：

• 用户只是问“登录状态 / 是否已登录”时，只汇报状态，不主动发起登录。
• 用户明确说“登录 / 授权 / 发起授权流程 / 继续登录 / 帮我授权 / 开始授权”时，不要停在状态汇报，也不要再问是否继续；授权不是危险操作，必须在同一轮直接执行 Step 3。
• 业务命令因为 not_authenticated、AUTH_TOKEN_EXPIRED、USER_TOKEN_ILLEGAL 等认证错误失败时，必须直接进入 Step 3，而不是反复重试业务命令。

Step 2.5：中文 / CJK 参数安全

当前 WorkBuddy shell 环境可能是 LC_CTYPE=C / LANG=""，直接在 Bash 参数里传中文可能导致 dws 输出看起来乱码，甚至把错误编码写入用户可见字段（如待办标题、文件名、文档名、消息内容）。涉及中文 / CJK 内容时先检查：

locale

如果不是 UTF-8 locale，避免直接写 dws ... --title "中文"。改用 Python 以 Unicode 字符串和 subprocess.run([...]) 参数列表调用 dws，并设置 UTF-8 环境：

PYTHONUTF8=1 /Library/Frameworks/Python.framework/Versions/3.12/bin/python3 -c 'import subprocess, os, sys; title="\u8bc4\u5ba1\u7ed3\u8bba"; r=subprocess.run(["dws","todo","task","update","--task-id","<taskId>","--title",title,"--format","json"], env={**os.environ,"LC_ALL":"en_US.UTF-8","LANG":"en_US.UTF-8"}, capture_output=True); sys.stdout.buffer.write(r.stdout); sys.stderr.buffer.write(r.stderr); raise SystemExit(r.returncode)'

验证中文字段时，不要只看终端渲染；可读取 JSON 后用 unicode_escape 比对真实内容。

Step 3：完成授权（Skill 自闭环方案）

本 Skill 不依赖 WorkBuddy Runtime 改造即可完成授权。按以下顺序执行：

A. 默认方案：浏览器跳转登录

优先执行官方 loopback 登录，让 dws 自动打开浏览器完成钉钉 OAuth：

dws auth login

执行要求：

1. 保持命令运行，等待用户在浏览器/钉钉页面完成授权。
2. 授权完成后执行 dws auth status --format json 验证状态。
3. 登录状态有效后，进入“初始化基础权限授权”说明：告知用户读取钉钉文档还需要第二段 doc:read 业务授权，并按用户选择发起一次性或长期授权。
4. 如果浏览器未自动打开、loopback 失败、远程环境不可用或命令长时间无结果，立即切到 B 方案，不要反复重试。

B. 兜底方案：设备流授权链接 + 授权码

执行：

dws auth login --device

从输出中提取并清晰展示给用户：

• 授权页：https://login.dingtalk.com/oauth2/device/verify.htm
• 授权码：例如 ABCD-EFGH
• 带授权码的完整链接：https://login.dingtalk.com/oauth2/device/verify.htm?user_code=ABCD-EFGH

推荐操作方式：

1. 如果输出了完整链接，直接告诉用户点击该链接完成授权；在 macOS 本地环境也可以执行 open "<complete_url>" 自动打开浏览器。
2. 如果完整链接不可用，则让用户打开授权页并输入授权码。
3. 保持 dws auth login --device 命令轮询，直到授权成功、失败或过期。
4. 授权完成后执行：

dws auth status --format json

5. 登录状态有效后，进入“初始化基础权限授权”说明：告知用户读取钉钉文档还需要第二段 doc:read 业务授权，并按用户选择发起一次性或长期授权。

C. 初始化基础权限授权

首次 OAuth 登录成功后，读取钉钉文档通常还需要第二段业务授权 doc:read。初始化流程必须把这个预期说清楚：

钉钉初始化需要完成两步：
1. 登录钉钉账号
2. 授予 WorkBuddy 读取钉钉文档权限 doc:read

初始化阶段可请求长期授权，避免每次读文档都被中断；但必须明确告诉用户这可能是第二次授权确认，不是并入同一次 OAuth：

export DINGTALK_DWS_AGENTCODE="workbuddy"
export DWS_CHANNEL="workbuddy"
dws pat chmod doc:read --agentCode workbuddy --grant-type permanent --format json

如果用户明确只想临时授权，改用一次性授权：

dws pat chmod doc:read --agentCode workbuddy --grant-type once --format json

执行规则：

1. 不要把 doc:read 说成并入同一次 OAuth；它可能触发第二次授权确认。
2. doc:read 属于低风险只读 PAT，初始化时可以请求 permanent，但要先说明用途：用于后续读取钉钉文档正文，减少重复授权打断。
3. 如果组织策略不允许授权或命令返回权限错误，记录失败原因，不阻断非文档类任务；但在执行 doc read、doc search、读取文档内容等文档读取任务前必须再次补授权。
4. doc:read 只覆盖读取钉钉文档；写文档、删除块、移动/重命名等写操作仍按需单独授权，并遵守危险操作确认规则。

D. 可选方案：二维码

若用户明确要求二维码，或链接无法点击，可把 B 方案的完整链接转换成二维码图片/终端二维码。仅在本机已有二维码工具时执行，例如 qrencode；不要为了生成二维码额外安装依赖。没有二维码工具时，直接使用 B 方案的完整链接和授权码。

E. 已登录后的权限授权：host-owned PAT

host-owned PAT 不是首次登录方案，只用于已登录后遇到业务权限/行为授权拦截时处理。执行业务命令前可注入：

export DINGTALK_DWS_AGENTCODE="workbuddy"
export DWS_CHANNEL="workbuddy"

如果业务命令返回 exit code 4，或 stderr/stdout 中出现 PAT_MEDIUM_RISK_NO_PERMISSION、requiredScopes、grantOptions 等字段：

1. 同时检查 stdout 和 stderr，优先解析 JSON key，不要依赖可能乱码的中文 message。
2. 提取 requiredScopes[].scope 和 grantOptions。
3. 向用户说明缺少哪些权限、一次性授权和长期授权的区别。
4. 低风险只读 scope 可建议 once；中高风险或写权限必须先解释数据范围和风险。
5. 用户确认后执行：

dws pat chmod <scope>... --agentCode workbuddy --grant-type once --format json

6. --grant-type session 只有在已知 --session-id 时才能使用；不要执行缺少 --session-id 的旧命令。格式为：

dws pat chmod <scope>... --agentCode workbuddy --grant-type session --session-id <id> --format json

7. 同一工作流已知会连续触发多个 scope 时，可在用户确认后一次性合并授权，减少反复中断。例如钉盘上传通常需要：

dws pat chmod drive:upload-info drive:commit --agentCode workbuddy --grant-type once --format json

8. 只有用户明确要求长期授权时，才改用 --grant-type permanent。
9. 授权完成后 replay 原始业务命令。

F. 常用操作 PAT 预判基线（2026-05-14 测试企业探针）

说明：dws schema 能给出命令结构和敏感操作标记，但不总是静态暴露 host-owned PAT scope。最可靠信号仍是运行时返回 PAT_MEDIUM_RISK_NO_PERMISSION.requiredScopes。对固定工作流，可提前合并申请已知 scope。

首次安装不建议“一次性申请所有常用权限”。推荐最小 OAuth 登录 + 按场景延迟授权；可为高频工作流做授权包（如“钉盘上传包：drive:upload-info、drive:commit”），由用户首次使用该场景时一键确认。

严格禁止

• 不要绕过 dws 直接用 curl、HTTP API 或浏览器自动化操作钉钉业务数据。
• 不要把 AppKey、AppSecret、access token、refresh token 写入 SKILL.md、references 或日志。
• 不要编造 userId、openConversationId、baseId、tableId、processInstanceId、taskId、fileId 等标识符；必须从 dws 命令返回中提取。
• 不要猜测字段名、枚举值或参数格式；不确定时先运行 dws <command> --help 或 dws schema <path>。
• 不要在未获得用户确认时执行删除、撤回、拒绝、移除成员、批量修改等高影响操作。

严格要求

• 所有业务命令默认加 --format json，以便解析结构化输出。--format 支持 json|table|raw|pretty|ndjson|csv（v1.0.26+）；对大列表建议用 ndjson 流式输出。
• 写操作优先使用 --dry-run 预览；需要真正执行时再加 --yes。
• 危险操作必须先展示操作摘要（操作类型、目标对象、影响范围），用户明确确认后才执行。
• 单次批量写入/删除/修改不超过 30 条记录；超过时拆批并逐批确认。
• 参考文档与实际 CLI 输出冲突时，以 dws <command> --help 和 dws schema <path> 为准。
• 认证或权限错误出现后，停止反复尝试业务 API，先完成授权诊断。

执行策略

• 简单状态类命令可直接执行，例如 dws auth status --format json、dws version --format json。
• 复杂命令、写操作、上传/下载、审批、日历、群聊、文档块级编辑、AI 表格字段/记录操作，执行前先查 dws <domain> --help 或 dws <domain> <group> --help；必要时再查 dws schema <path>。
• 写操作采用 --dry-run（如命令支持）→ 操作摘要 → 用户确认 → --yes 执行。
• 基于 help/schema 修正参数最多 1 次；加 --verbose 诊断最多 1 次；仍失败则汇报错误和下一步，不绕过 dws。
• 输出解析同时检查 stdout 和 stderr。auth login、doctor、pat 类命令可能不是纯 JSON；遇到非 JSON 输出时提取 URL、user code、error code、requiredScopes 等结构化线索。
• 默认分页、字段裁剪和摘要化；不要大段回显邮件、聊天、文档正文等敏感内容，除非用户明确要求。

产品总览

dws 的产品域会随版本动态变化。下表是核心路由参考，不是完整命令契约；实际可用产品和参数以 dws --help、dws <domain> --help、dws schema 为准。