dws

# 钉钉全产品 Skill 通过 `dws` 命令管理钉钉产品能力。 > ⚠️ **命令可用性以当前 dws 二进制为准**。服务发现已下线，本文档随内置 skill 发布；如果 `dws <cmd> --help` 不存在，说明当前版本未暴露该命令。`--help` 决定 Cobra 实际接受的 flags；公开基础命令和内建 `+` shortcut 的 leaf Schema 决定 Agent 选择、参数映射/约束和安全确认语义。若命令存在但调用失败，请按错误中的 endpoint 或 tool 提示确认静态端点目录和后端工具注册。实际调用前可用 `dws <cmd> --help` 或 `--dry-run` 验证。 ## 严格禁止 (NEVER DO) - 不要使用 dws 命令以外的方式操作（禁止 curl、HTTP API、浏览器） - 不要编造 UUID、ID 等标识符，必须从命令返回中提取 - 不要猜测字段名/参数值，操作前必须先查询确认 ## 严格要求 (MUST DO) - 所有命令必须加 `--format json` 以获取可解析输出 - 危险操作必须先向用户确认，用户同意后才加 `--yes` 执行 - 单次批量操作不超过 30 条记录 - 所有命令必须**严格遵循**对应产品参考文档里面规定的参数格式（如：如果有参数值，则参数和参数值之间至少用一个空格隔开） - **脚本优先**：[scripts/](./scripts/) 下的 `python scripts/<name>.py` 已封装翻页/轮询/批量逻辑，遇到对应场景（如 AI 表格批量导入导出、AI 应用创建轮询、文档创建后写内容、钉盘目录树等）**优先调用脚本**而非手写多步命令。脚本均支持 `--dry-run` 预览、`--format json` 输出，失败时回退到手动步骤 - **实时个人消息事件例外**：用户要监听消息、订阅事件、自动回复消息或事件驱动 Agent 时，必须走 `dws event consume ... --flatten` 长连接，不要写脚本轮询消息历史 ## Shortcut 与原子命令的使用原则 `shortcut` 是对常用操作的高层封装，适合优先承担用户意图；产品参考文档和本 skill 负责判断意图、风险、跨产品流程和复杂参数，CLI 帮助负责声明当前版本真正可调用的命令。 - 先按产品参考、意图表和 recipe 路由。存在精确覆盖场景的专用脚本/recipe 时继续遵循“脚本优先”；否则用户意图可由可见 shortcut 满足时，优先使用 `dws <service> +<verb> ... --format json`，不要手写等价的多步原子命令。 - 公开内建 shortcut 同时进入 Runtime Schema。用 `dws schema --cli-path "<service> +<verb>" --format json` 读取 Agent 选择、参数、跨参数约束、risk/confirmation 与接口语义；`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 信息。 <!-- VISIBLE_SHORTCUTS_OVERVIEW_START --> ## Shortcut 总览 下面统计当前公开 catalog 中的 shortcut。mono 模式不展开 200+ 行明细，避免 skill 过重；需要执行时先按产品路由，再用 `dws shortcut list --service <service> --format json` 读取参数、约束、风险和示例，最后用 `dws <service> +<shortcut> --help` 核对当前 Cobra flags。multi 模式的各产品 skill 会展开该产品的 shortcut 表。 | 服务 | shortcut 数 | multi skill | 发现命令 | |---|---:|---|---| | `aitable` | 29 | `dingtalk-aitable` | `dws shortcut list --service aitable --format json` | | `attendance` | 19 | `dingtalk-misc` | `dws shortcut list --service attendance --format json` | | `calendar` | 20 | `dingtalk-calendar` | `dws shortcut list --service calendar --format json` | | `chat` | 42 | `dingtalk-chat` | `dws shortcut list --service chat --format json` | | `contact` | 14 | `dingtalk-contact` | `dws shortcut list --service contact --format json` | | `devapp` | 19 | `dingtalk-dev` | `dws shortcut list --service devapp --format json` | | `ding` | 4 | `dingtalk-misc` | `dws shortcut list --service ding --format json` | | `doc` | 17 | `dingtalk-doc` | `dws shortcut list --service doc --format json` | | `drive` | 7 | `dingtalk-drive` | `dws shortcut list --service drive --format json` | | `mail` | 10 | `dingtalk-mail` | `dws shortcut list --service mail --format json` | | `minutes` | 6 | `dingtalk-minutes` | `dws shortcut list --service minutes --format json` | | `oa` | 7 | `dingtalk-misc` | `dws shortcut list --service oa --format json` | | `report` | 2 | `dingtalk-misc` | `dws shortcut list --service report --format json` | | `sheet` | 2 | `dingtalk-misc` | `dws shortcut list --service sheet --format json` | | `todo` | 11 | `dingtalk-todo` | `dws shortcut list --service todo --format json` | | `wiki` | 1 | `dingtalk-wiki` | `dws shortcut list --service wiki --format json` | <!-- VISIBLE_SHORTCUTS_OVERVIEW_END --> ## 多组织 / 多账号 - `dws profile list --format json` 默认返回全部账号。自动化只使用每项稳定的 `profile=corpId:userId`；`status/expiresAt/refreshExpAt` 来自真实身份 Token，列表不触发刷新。 - 输入支持 `corpId:userId`、`corpId:userName`、`corpName:userId`、`corpName:userName`，也兼容单独的 corpId、唯一 corpName 和本地 profile 名。名称只用于输入；重名时必须按报错候选改用 `corpId:userId`。 - 只传组织时使用该组织明确记录的 `isOrgCurrent=true` 账号。多账号组织没有默认账号时必须让用户指定账号；禁止选择第一项、最近登录或最近使用账号。 - 不传 `--profile` 使用全局 `isCurrent=true` 账号。`primaryProfile/isPrimary` 仅兼容输出，不参与选择；`previousProfile` 只用于 `profile switch -`。 - 跨组织读 / 搜：按 `corpId` 去重；每个组织使用唯一 `isOrgCurrent=true` 的 `profile`。组织存在多个账号且没有默认账号时先询问用户。写 / 发 / 删 / 撤回及持久切换前先确认目标组织和账号。 ## 产品总览 | 产品 | 用途 | 参考文件 | |-------------------|------------------------------------------------------|----------------------------------------------------------------| | `aiapp` | AI应用：创建/查询/修改AI应用 | [aiapp.md](./references/products/aiapp.md) | | `aisearch` | AI搜问（通用找人首选）：按姓名/部门/职位/职责/上级/下级/手机号/工号维度找人，"谁负责 XX/XX 的负责人/某事项/某项目的人"统一走本产品；不含人才池/绩效/职业历程等专项 HR 场景（那些去 `hrbrain`） | [aisearch.md](./references/products/aisearch.md) | | `aitable` | AI表格：Base/数据表/字段/记录/视图/附件/图表/仪表盘/导入导出/模板搜索 | [aitable.md](./references/products/aitable.md) | | `attendance` | 考勤：打卡结果/打卡流水/考勤组查询/考勤规则/汇总统计/假期类型/假期余额（P0 已落地，部分管理类命令仍属 P1） | [attendance.md](./references/products/attendance.md) | | `calendar` | 日历：日历列表/日程/参与者/附件/响应/会议室/闲忙查询/时间建议 | [calendar.md](./references/products/calendar.md) | | `chat` | 群聊与机器人：搜索群/建群/群成员管理/改群名/消息发送(文本/Markdown/图片/文件)/拉取消息/消息收藏/@我/特别关注/机器人群发/单聊/撤回/转发/引用回复/Webhook/机器人搜索 | [chat.md](./references/products/chat.md) | | `contact` | 通讯录：用户查询/部门/角色/花名册（学历/家庭/银行卡/紧急联系人/合同等基础字段）/离职员工/特别关注，以及创建企业、企业账号和邀请员工；不含职业历程/绩效/人才池（那些去 `hrbrain`） | [contact.md](./references/products/contact.md) | | `devdoc` | 开放平台文档：搜索开发文档 | [devdoc.md](./references/products/devdoc.md) | | `ding` | DING消息：发送/撤回（应用内/短信/电话） | [ding.md](./references/products/ding.md) | | `doc` | 钉钉文档：搜索/浏览/读写/块级编辑/评论/文件创建/复制/移动/重命名/**删除/导出 docx/权限管理/媒体上传下载** | [doc.md](./references/products/doc.md) | | `drive` | 钉钉云盘：文件列表/元数据/文件夹/上传(两步)/下载 | [drive.md](./references/products/drive.md) | | `hrbrain` | 组织大脑：人才池管理/员工档案专项模块查询（元数据/批量数据/标签/职业历程/绩效）/结构化高级人才搜索（原始条件表达式）；区别于 `contact` 的基础通讯录档案与 `aisearch` 的通用语义找人 | [hrbrain.md](./references/products/hrbrain.md) | | `markdown` | 原生 Markdown 文件：读取/创建/全量覆盖/字面量或 RE2 局部替换 | [markdown.md](./references/products/markdown.md) | | `minutes` | AI听记：听记列表/摘要/关键词/转写/待办/思维导图/发言人/发言人段落总结/热词/录音控制/成员权限/上传 | [minutes.md](./references/products/minutes.md) | | `oa` | OA审批：待处理/详情/同意/拒绝/撤销/记录/已发起/任务/转交/评论/抄送 | [oa.md](./references/products/oa.md) | | `pat` | PAT 行为授权：浏览器策略/scope 预览/一次性、会话或永久授权 | [pat.md](./references/products/pat.md) | | `report` | 日志：按模版创建/收件箱/已发送/模版查看/详情/已读统计 | [report.md](./references/products/report.md) | | `mail` | 邮箱：邮箱地址查询/邮件搜索(KQL)/邮件详情/发送邮件 | [mail.md](./references/products/mail.md) | | `sheet` | 在线电子表格(axls)：工作表 CRUD/区域读写/CSV 批量写入/行列增删/合并/查找替换/筛选视图/全局筛选/排序/下拉列表/条件格式/浮动图片/浮动图表/模板/导出 xlsx(单命令一站式) | [sheet.md](./references/products/sheet.md) | | `todo` | 待办：创建(含优先级/截止时间/循环)/查询/修改/标记完成/删除 | [todo.md](./references/products/todo.md) | | `wiki` | 知识库：空间创建/详情/列表/搜索 + 成员管理 | [wiki.md](./references/products/wiki.md) | | `event` | 个人 IM 事件：监听消息接收、指定发送人、已读、撤回、表情回应，NDJSON 输出（实时驱动 Agent）| [event.md](./references/products/event.md) | ## 意图判断决策树 用户提到"AI应用/创建应用/生成系统/做工具/管理后台/低代码" → `aiapp` 用户提到"目标管理/Agoal/战略解码/经营合约/计分卡/目标模板/周月报提交统计" → `agoal` 用户提到"找人/搜人/谁负责 XX/某事项的负责人/某项目的人/团队成员/上级/下级/按工号找人/按手机号找人" → `aisearch`（通用语义找人；若明确涉及人才池/绩效/职业历程/结构化高级条件，去 `hrbrain`） 用户提到"表格/多维表/AI表格/记录/数据/视图/图表/仪表盘" → `aitable` 用户提到"考勤/打卡/排班" → `attendance` 用户提到"日程/日历/会议室/约会/时间建议" → `calendar` 用户提到"群聊/建群/群成员/群管理/发消息/发图片消息/发文件消息/发 Markdown 消息/截图发钉钉/转发消息/引用回复/@我/特别关注消息/机器人发消息/Webhook/机器人群发/机器人单聊/通知" → `chat` 用户提到"通讯录/同事/部门/组织架构/子部门/部门多少人/离职员工/离职名单/离职花名册/花名册/基础员工档案(学历/家庭/银行卡/紧急联系人/合同)/角色/主管角色/管理员角色/财务/HR/特别关注/星标联系人/创建企业/企业账号/邀请员工/新员工入职" → `contact`（不含职业历程/绩效/人才池；那些去 `hrbrain`） 用户提到"开发/API/调用错误 文档" → `devdoc` 用户提到"DING/紧急消息/电话提醒" → `ding` 用户提到"钉钉文档/云文档/知识库/读写文档/块级编辑/文档评论/文档复制移动" → `doc` 用户提到"云盘/文件存储/文件上传下载/文件夹" → `drive` 用户提到"人才池/储备干部池/员工档案元数据或批量模块数据/职业历程/绩效记录/员工标签/组织大脑/结构化人才搜索(高级条件表达式)" → `hrbrain`（区别于 `aisearch` 的通用语义找人与 `contact` 的基础通讯录档案） 用户提到"原生 Markdown 文件/.md 文件/读取 Markdown 原文/覆盖 Markdown/局部替换 Markdown" → `markdown` 用户提到"听记/AI听记/会议纪要/转写/摘要/思维导图/发言人/热词" → `minutes` 用户提到"邮箱/邮件/发邮件/收邮件/搜邮件/查邮件/邮件草稿/转发邮件/回复邮件/邮件附件/抄送" → `mail` 用户提到"审批/请假/报销/出差/加班/同意/拒绝/撤销审批" → `oa` 用户提到"PAT 授权/行为权限/scope 授权/批量授权/一次性授权/会话授权/永久授权/授权浏览器策略" → `pat` 用户提到"日志/日报/周报/日志统计/写日报/提交周报/发日志/填日志" → `report` 用户提到"在线电子表格/钉钉表格/axls/工作表/单元格读写/合并单元格/筛选视图/导出 xlsx" → `sheet` 用户提到"待办/TODO/任务提醒/循环待办" → `todo` 用户提到"创建知识库/知识库列表/搜索知识库空间/wiki/团队空间/知识库成员管理/我的文档个人空间" → `wiki` 用户提到"监听有人@我/监听单聊或群消息/监听所有单聊或群消息/监听某人发送的消息/监听消息已读/监听消息撤回/监听消息贴表情或表情回应/监听群成员加入/监听群成员退出/监听群改名或群解散/订阅个人 IM 事件/实时接收钉钉事件/个人事件流/event consume user_im_message_*/监听并自动回复消息/驱动 Agent 处理消息" → `event` 事件监听中，同一目标、同一过滤条件的多个兼容事件优先生成一个 `dws event consume <event_key> [event_key...] --flatten`；不同用户、不同群或不同过滤条件拆成多个 consume 进程。 关键区分: aitable(数据表格) vs todo(待办任务) 关键区分: report(钉钉日志/日报周报) vs todo(待办任务) 关键区分: chat send-by-bot(机器人身份发消息) vs send-by-webhook(自定义机器人Webhook告警) 关键区分: doc(在线富文本文档/adoc) vs markdown(原生 .md 纯文本文件) vs drive(通用文件存储与传输) 关键区分: contact(基础通讯录档案：学历/家庭/银行卡/紧急联系人/合同/部门角色) vs aisearch person(通用语义找人：谁负责/上级/下级/多维度模糊搜索) vs hrbrain(人才池/员工档案专项模块数据/职业历程/绩效/结构化高级人才搜索) 关键区分: oa tasks(审批 taskId，审批/拒绝用) vs oa list-pending(收件箱 processInstanceId，查看用) > 更多易混淆场景见 [intent-guide.md](./references/intent-guide.md) ## 危险操作确认 以下操作为不可逆或高影响操作，执行前**必须先向用户展示操作摘要并获得明确同意**，同意后才加 `--yes` 执行。 | 产品 | 命令 | 说明 | |------|------|------| | `aitable` | `base delete` | 删除整个 AI 表格，含全部数据表和记录 | | `aitable` | `table delete` | 删除数据表（含全部字段/视图/记录） | | `aitable` | `field delete` | 删除字段（该列所有值同步清空） | | `aitable` | `view delete` | 删除视图 | | `aitable` | `record delete` | 删除记录（支持批量） | | `aitable` | `chart delete` / `dashboard delete` | 删除图表/仪表盘 | | `calendar` | `event delete` | 删除日程，所有参与者同步取消 | | `calendar` | `participant delete` | 移除日程参与者 | | `calendar` | `room delete` | 取消会议室预定 | | `chat` | `group members remove` | 移除群成员 | | `chat` | `message recall-by-bot` | 撤回机器人已发消息 | | `doc` | `delete` | **删除整篇文档/文件**到回收站（与 `block delete` 不同，本命令删除整个 node） | | `doc` | `block delete` | 删除文档单个块（不可恢复） | | `doc` | `permission update` | 修改协作者权限（降权可能影响他人访问） | | `ding` | `message recall` | 撤回已发 DING 消息 | | `oa` | `approval revoke` | 撤销自己发起的审批实例 | | `oa` | `approval reject` | 拒绝待审批（需加明确理由） | | `todo` | `task delete` | 删除待办 | | `minutes` | `replace-text` | 全文批量替换转写与摘要 | ### 确认流程 ``` Step 1 → 展示操作摘要（操作类型 + 目标对象 + 影响范围） Step 2 → 用户明确回复确认（如 "确认" / "好的"） Step 3 → 加 --yes 执行命令 ``` ## 核心流程