dws

钉钉全产品 Skill

通过 dws 命令管理钉钉产品能力。

⚠️ 命令与 flag 以当前 dws 二进制为准:dws <cmd> --help 是 Cobra flags 事实源,Agent 选命令/参数约束/安全确认以 leaf Schema(--compact)为准,与本文档冲突时以二者为准。

严格禁止 (NEVER DO)

• 不要使用 dws 命令以外的方式操作（禁止 curl、HTTP API、浏览器）。唯一例外：aitable 导入/导出链路返回的预签名 uploadUrl/downloadUrl（import upload 申请的上传凭证、export data 返回的下载地址）允许用 curl 直传/直下（见 aitable-export-import.md）；除此之外禁止
• 不要编造 UUID、ID 等标识符，必须从命令返回中提取
• 不要猜测字段名/参数值，操作前必须先查询确认

严格要求 (MUST DO)

• 所有命令必须加 --format json 以获取可解析输出
• 危险操作必须先向用户确认，用户同意后才加 --yes 执行
• 直接调用 dws 批量接口（如 record update）时单次批量不超过 30 条记录；使用 scripts/import_records.py 批量导入时按脚本默认 50 条/批（其 DEFAULT_BATCH_SIZE=50，上限 100）
• 所有命令必须严格遵循对应产品参考文档里面规定的参数格式（参数与参数值之间用空格隔开）
• 脚本只用于明确覆盖的复合任务：scripts/ 下的脚本可封装 AI 表格批量导入导出、钉盘目录树等流程；当公开 + Shortcut 已提供目标唯一解析、分页/部分失败 ledger 和确认语义时，优先 Shortcut。Chat 历史导出与机器人广播已完全下沉 Runtime，不再发布兼容脚本
• 脚本调用约定：统一用 python3 调用（多数 macOS/Linux 环境没有裸 python 命令）；文档中的 scripts/... 是相对本 Skill 根目录（SKILL.md 所在目录）的路径，实际执行时应拼成完整路径（如 python3 <Skill根目录>/scripts/attendance_report_monthly.py ...），不要假设当前工作目录（CWD）已在 Skill 根目录
• 实时个人事件例外：普通 IM 消息、reaction、已读和撤回默认走 dws event +listen-im ...；OA 审批、群生命周期、明确的原始 EventKey、Filter DSL、subscribe_id 或原始 envelope 使用 dws event consume ... --flatten。不要写脚本轮询消息历史或审批列表

Shortcut 与原子命令的使用原则

shortcut 是对常用操作的高层封装，适合优先承担用户意图；产品参考文档和本 skill 负责判断意图、风险、跨产品流程和复杂参数，CLI 帮助负责声明当前版本真正可调用的命令。

• 先按产品参考、意图表和 recipe 路由。用户意图可由可见 Shortcut 满足时，优先使用 dws <service> +<verb> ... --format json，不要手写等价的多步原子命令。只有脚本明确补足 Shortcut 未覆盖的复合交付物且其安全/完整性契约仍适用时才选择脚本。
• 公开内建 shortcut 同时进入 Runtime Schema。用 dws schema --cli-path "<service> +<verb>" --compact --format json 读取 Agent 选择、参数、跨参数约束和 risk/confirmation；只有参数映射、接口绑定或 provenance 审计才通过 --jq 精确读取 full leaf；dws shortcut list --service <service> --format json 只作为轻量批量发现入口。
• 真正组装参数前用叶子帮助 dws <service> +<verb> --help 核对当前 Cobra 接受的 flags。父级 dws <service> --help 只能发现子命令，不能替代叶子参数帮助。
• shortcut catalog 中 confirmation=user_required 时，必须先获得用户确认，确认后才加 --yes；not_required 不额外确认。
• 如果 shortcut 不在 help / list 中，改用产品参考里的原子命令、脚本或标准流程；不要猜测未展示的 + 命令。
• shortcut 失败时按“错误处理”流程先加 --verbose 复查；若仍失败，应记录具体输入、输出、trace / endpoint / tool 信息。