dws

钉钉全产品 Skill

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

命令可用性以当前 dws 二进制为准。本文档随内置 skill 发布，可能滞后于二进制；如果 dws <cmd> --help 不存在，说明当前版本未暴露该命令。--help 决定 Cobra 实际接受的 flags；公开基础命令和内建 + shortcut 的 leaf Schema（常规用 --compact）决定 Agent 选择、参数/约束和安全确认语义。实际调用前可用 dws <cmd> --help 或 --dry-run 验证。

严格禁止 (NEVER DO)

• 不要使用 dws 命令以外的方式操作钉钉业务数据（禁止 curl 或自行拼 HTTP）；唯一例外是按 openapi-explorer.md 读取官方 open.dingtalk.com/llms.txt 文档并生成受限的 dws api 调用
• 不要编造 UUID、ID 等标识符，必须从命令返回中提取
• 不要猜测字段名/参数值，操作前必须先查询确认

严格要求 (MUST DO)

• 所有命令必须加 --format json 以获取可解析输出
• 用户明确要登录钉钉国际版、海外版或 .io 区域时，必须执行 dws auth login --intl（无头环境再加 --device），不得回退到国内 .com；--intl 只用于登录，后续业务命令按所选 profile 自动路由
• 危险操作必须先向用户确认，用户同意后才加 --yes 执行
• 单次批量操作不超过 30 条记录
• 所有命令必须严格遵循对应产品参考文档里面规定的参数格式（如：如果有参数值，则参数和参数值之间至少用一个空格隔开）
• 脚本只用于明确覆盖的复合任务：scripts/ 下的脚本可封装 AI 表格批量导入导出、AI 应用创建轮询、文档创建后写内容、钉盘目录树等流程；当公开 + Shortcut 已提供目标唯一解析、分页/部分失败 ledger 和确认语义时，优先 Shortcut。Chat 历史导出与机器人广播已完全下沉 Runtime，不再发布兼容脚本
• 实时个人事件例外：普通 IM 消息、reaction、已读和撤回默认走 dws event +listen-im ...；OA 审批、VoIP 通话邀请、Todo、互动卡片回调、群生命周期、明确的原始 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 信息。