Pinvou/pinvou-agent / pinvou3-app/src-tauri/resources/common/bundle/dingtalk-skills/dws
dws
Unverified【何时用:仅当用户明确指向钉钉/DingTalk(钉钉文档、钉钉日程等)时使用;泛指做文档/表格/待办/审批默认走本地工具,不要误用钉钉】用 dws CLI 管理钉钉:AI表格/AI搜问(找人首选)/目标管理(Agoal)/组织大脑/日历/通讯录/群聊与机器人消息/待办/审批/智能合同/考勤/日志(日报周报)/DING消息/钉钉文档/云盘/Markdown文件/HTML文件/AI听记/邮箱/在线电子表格(axls)/知识库/白板/开放平台文档/个人IM与OA事件订阅。用户要求操作上述钉钉产品时使用。
钉钉全产品 Skill
通过 dws 命令管理钉钉产品能力。
⚠️ 命令与 flag 以当前 dws 二进制为准:
dws <cmd> --help是 Cobra flags 事实源,Agent 选命令/参数约束/安全确认以 leaf Schema(--compact)为准,与本文档冲突时以二者为准。
🔑 首次使用先认证:命令报
AUTH_TOKEN_EXPIRED/ 未登录时,不要在会话内直接跑dws auth login——它是阻塞式扫码设备流,会一直等待授权直至超时,用户看不到扫码链接。把命令交给用户在其终端自行执行(流程见 global-reference.md 认证章节),完成后再继续;不要因未登录直接断定技能不可用。
严格禁止 (NEVER DO)
- 不要使用 dws 命令以外的方式操作钉钉业务数据(禁止 curl、HTTP API、浏览器)。例外:① aitable 导入/导出/附件上传链路返回的预签名
uploadUrl/downloadUrl(import upload申请的上传凭证、export data返回的下载地址、attachment upload返回的上传地址)允许用 curl 直传/直下(见 aitable-export-import.md 与 aitable-attachment.md);② 按 openapi-explorer.md 读取官方open.dingtalk.com/llms.txt文档并生成受限的dws api调用。除此之外禁止 - 不要编造 UUID、ID 等标识符,必须从命令返回中提取
- 不要猜测字段名/参数值,操作前必须先查询确认
严格要求 (MUST DO)
- 所有命令必须加
--format json(默认输出即 json,显式携带以防默认值变化,确保可解析) - 用户明确要登录钉钉国际版、海外版或
.io区域时,必须执行dws auth login --intl(无头环境再加--device),不得回退到国内.com;--intl只用于登录,后续业务命令按所选 profile 自动路由 - 危险操作必须先向用户确认,用户同意后才加
--yes执行 - 直接调用 dws 批量接口(如
record update)时单次硬上限 100 条(各 record 分册同);Agent 直连建议每批 ≤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 审批、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 信息。
Shortcut 总览
下面只统计当前公开 catalog 中的 shortcut,不展开完整明细。已知意图先按产品 Skill、意图表或任务 reference 选唯一命令;参数/约束/安全不明时读一次 leaf 窄 Schema。Schema 不可用时才读一次已知 leaf Help;unknown flag 用同 leaf Help 修正一次;unknown command 不查 Help,先用错误的明确 suggestion,否则用已加载 Skill/reference 的明确兼容入口,仍无则报告漂移,不枚举全 Catalog。仅当现有路由和 reference 都无法定位低频能力时,才用 dws shortcut list --service <service> --format json 做最后回退;不要为已知意图加载完整产品 Catalog 或 root/parent Help。
| 服务 | shortcut 数 |
|---|---|
agoal | 5 |
aisearch | 1 |
aitable | 127 |
attendance | 11 |
calendar | 27 |
chat | 102 |
contact | 19 |
devapp | 25 |
ding | 1 |
doc | 49 |
drive | 28 |
mail | 8 |
minutes | 29 |
oa | 1 |
pat | 1 |
report | 4 |
sheet | 2 |
todo | 20 |
whiteboard | 3 |
wiki | 20 |
多组织 / 多账号
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。组织存在多个账号且没有默认账号时先询问用户。写 / 发 / 删 / 撤回及持久切换前先确认目标组织和账号。
产品总览
| 产品 | 用途 | 参考文件 |
|---|---|---|
agoal | 目标管理:战略解码、经营合约、计分卡、目标规则周期、个人目标、目标模板、周月报规则提交统计与跟催 | agoal.md |
aisearch | AI搜问(通用找人首选):按姓名/部门/职位/职责/上级/下级/手机号/工号维度找人,"谁负责 XX/XX 的负责人/某事项/某项目的人"统一走本产品;不含人才池/绩效/职业历程等专项 HR 场景(那些去 hrbrain) | aisearch.md |
aitable | AI表格:Base/数据表/字段/记录/视图/附件/图表/仪表盘/导入导出/模板搜索/PostgreSQL 只读查询与 JOIN | aitable.md |
api | OpenAPI 逃生舱:官方 llms.txt 分层发现,仅执行企业内部应用 App Token 服务端 API | openapi-explorer.md |
attendance | 考勤:打卡结果/打卡流水/考勤组查询/考勤规则/汇总统计/假期类型/假期余额(全部命令已注册可用,见 attendance.md「命令可用性提示」) | attendance.md |
calendar | 日历:日历列表/日程/参与者/附件/响应/会议室/闲忙查询/时间建议 | calendar.md |
chat | 群聊与机器人:搜索群/建群/群成员管理/改群名/消息发送(文本/Markdown/图片/文件)/拉取消息/消息收藏/@我/特别关注/机器人群发/单聊/撤回/转发/引用回复/Webhook/机器人搜索 | chat.md |
contact | 通讯录:用户查询/部门/角色/花名册(学历/家庭/银行卡/紧急联系人/合同等基础字段)/离职员工/特别关注,以及创建企业、企业账号和邀请员工;不含职业历程/绩效/人才池(那些去 hrbrain) | contact.md |
contract | 法务智能合同:台账、批量导入、听记起草、归档、项目、相对方与账款管理 | contract.md |
dev | 开放平台开发者:应用生命周期/机器人建号与配置/凭证/权限/事件订阅/版本发布审批/本地建联(dev connect);创建或建联机器人一律走 dev,不走 chat | dev.md |
devdoc | 开放平台文档:搜索开发文档 | devdoc.md |
ding | DING消息:发送/撤回(应用内/短信/电话) | ding.md |
dingtalk-tag | DingTalk Tag 数字员工:管理生命周期、Skill/MCP、执行状态与 trace,以及员工 Profile、普通本地 Agent 或 DSH 接入与运行管理 | dingtalk-tag-index.md |
doc | 钉钉文档:搜索/浏览/读写/块级编辑/评论/文件创建/复制/移动/重命名/删除/导出 docx/权限管理/媒体上传下载 | doc.md |
drive | 钉钉云盘:文件列表/元数据/文件夹/上传(两步)/下载/本地与钉盘文件夹差异比较(status)/拉取到本地(pull)/推送到钉盘(push)/双向同步(sync)/互联网公开发布(publish)/分享链接密码与有效期/节点分享范围(set-share-scope) | drive.md |
hrbrain | 组织大脑:人才池管理/员工档案专项模块查询(元数据/批量数据/标签/职业历程/绩效)/结构化高级人才搜索(原始条件表达式);区别于 contact 的基础通讯录档案与 aisearch 的通用语义找人 | hrbrain.md |
html | 原生 HTML 文件:读取/创建/全量覆盖/局部替换(.html/.htm,钉盘或文档空间) | html.md |
markdown | 原生 Markdown 文件:读取/创建/对比/全量覆盖/局部替换/评论列表 | markdown.md |
minutes | AI听记:听记列表/摘要/关键词/转写/待办/思维导图/发言人/发言人段落总结/热词/录音控制/成员权限/上传 | minutes.md |
oa | OA审批:待处理/详情/同意/拒绝/撤销/记录/已发起/任务/转交/评论/抄送 | oa.md |
pat | PAT 行为授权:浏览器策略/scope 预览/一次性、会话或永久授权 | pat.md |
report | 日志:按模版创建/收件箱/已发送/模版查看/详情/已读统计 | report.md |
mail | 邮箱:邮箱地址查询/邮件搜索(KQL)/邮件详情/发送邮件 | mail.md |
sheet | 在线电子表格(axls):工作表 CRUD/区域读写/CSV 批量写入/行列增删/合并/查找替换/筛选视图/全局筛选/排序/下拉列表/条件格式/浮动图片/浮动图表/模板/导出 xlsx(单命令一站式) | sheet.md |
todo | 待办:创建(含优先级/截止时间/循环)/查询/修改/标记完成/删除 | todo.md |
wiki | 知识库:空间创建/详情/列表/搜索 + 成员管理 + 知识库动态查询 + 空间分享范围(permission set-share-scope) | wiki.md |
whiteboard | 独立白板(白板文件)的内容操作;或在已有承载文档 nodeId 和 partId 后读写文档内嵌白板 part 的图形内容,两类目标互不转换 | whiteboard.md |
event | 个人 IM/OA/VoIP/Todo/互动卡片事件:监听消息、群生命周期、审批任务/实例、通话邀请、待办变化与卡片回调,NDJSON 输出(实时驱动 Agent) | event.md |
意图判断决策树
用户提到"AI应用/创建应用/生成系统/做工具/管理后台/低代码/宜搭" → 产品参考以 dev.md 为准(勿猜 aiapp 等未在 dev.md 列出的命令,命令以 dws dev --help 实测为准);应用创建/机器人建号与建联流程见该文「典型工作流」
用户提到"目标管理/Agoal/战略解码/经营合约或字段配置/计分卡/目标规则周期/个人目标/目标模板/周月报规则提交统计/按时/迟交/未提交/跟催" → agoal;只填写、提交或查询日报周报月报正文时才走 report
用户提到"法务/智能合同/合同台账/合同归档/合同项目/相对方/合同账款/按听记起草合同" → contract(合同审批实例的查询或处理走 oa;合同文件存储操作走 drive)
用户提到"找人/搜人/谁负责 XX/某事项的负责人/某项目的人/团队成员/上级/下级/按工号找人/按手机号找人" → aisearch(通用语义找人;若明确涉及人才池/绩效/职业历程/结构化高级条件,去 hrbrain)
用户提到"表格/多维表/AI表格/记录/数据/视图/图表/仪表盘/SQL/PostgreSQL/SELECT/JOIN/跨表关联查询" → aitable
用户提到"考勤/打卡/排班" → attendance
用户提到"日程/日历/会议室/约会/时间建议" → calendar
用户提到"群聊/建群/群成员/群管理/发消息/发图片消息/发文件消息/发 Markdown 消息/截图发钉钉/转发消息/引用回复/@我/特别关注消息/机器人发消息/Webhook/机器人群发/机器人单聊/通知" → chat
用户提到"通讯录/同事/部门/组织架构/子部门/部门多少人/离职员工/离职名单/离职花名册/花名册/基础员工档案(学历/家庭/银行卡/紧急联系人/合同)/角色/主管角色/管理员角色/财务/HR/特别关注/星标联系人/创建企业/企业账号/邀请员工/新员工入职" → contact(不含职业历程/绩效/人才池;那些去 hrbrain)
用户提到"开发/API/调用错误 文档" → devdoc
用户提到"未封装 OpenAPI/llms.txt/dws api/Raw API/API 逃生舱" → dws api(先查现有产品命令,再读官方 llms.txt)
用户提到"DING/紧急消息/电话提醒" → ding
用户提到"DingTalk Tag/DEAP 数字员工/创建发布数字员工/修改数字员工人设/响应模式/为 A2A 等场景安全登录数字员工 DWS/给数字员工挂 Skill 或 MCP/数字员工运行状态或 trace/落盘本地 Profile/接入 DSH" → dingtalk-tag,先读 dingtalk-tag-index.md
用户提到"钉钉文档/云文档/知识库/读写文档/块级编辑/文档评论/文档复制移动" → doc
用户提到"云盘/文件存储/文件上传下载/文件夹/互联网公开/分享链接密码/公开有效期" → drive
用户提到"人才池/储备干部池/员工档案元数据或批量模块数据/职业历程/绩效记录/员工标签/组织大脑/结构化人才搜索(高级条件表达式)" → hrbrain(区别于 aisearch 的通用语义找人与 contact 的基础通讯录档案)
用户提到"原生 HTML 文件/.html 文件/新建 HTML 页面/创建 HTML 文件/读取 HTML 原文/覆盖 HTML/局部替换 HTML" → html
用户提到"原生 Markdown 文件/.md 文件/读取 Markdown 原文/覆盖 Markdown/局部替换 Markdown/Markdown 评论" → markdown
用户提到"听记/AI听记/会议纪要/转写/摘要/思维导图/发言人/热词" → minutes
用户提到"邮箱/邮件/发邮件/收邮件/搜邮件/查邮件/邮件草稿/转发邮件/回复邮件/邮件附件/抄送" → mail
用户提到"审批/请假/报销/出差/加班/同意/拒绝/撤销审批" → oa
用户提到"PAT 授权/行为权限/scope 授权/批量授权/一次性授权/会话授权/永久授权/授权浏览器策略" → pat
用户提到"日志/日报/周报/日志统计/写日报/提交周报/发日志/填日志" → report
用户提到"在线电子表格/钉钉表格/axls/工作表/单元格读写/合并单元格/筛选视图/导出 xlsx" → sheet
用户提到"待办/TODO/任务提醒/循环待办" → todo
用户提到"创建知识库/知识库列表/搜索知识库空间/wiki/团队空间/知识库成员管理/我的文档个人空间" → wiki
用户提到"白板文件/独立白板/保存到白板/画布/OpenNodes/白板节点/连接线/整页重建白板" → whiteboard。用户要在文档中插入、定位或删除白板卡片 → doc whiteboard;只有已有承载文档 nodeId 和 partId 的内嵌白板图形内容读写才走 whiteboard。内嵌目标身份缺失时停止并补齐,禁止转成独立白板
用户提到"监听有人@我/监听单聊或群消息/监听所有单聊或群消息/监听某人发送的消息/监听消息已读/监听消息撤回/监听消息贴表情或表情回应/订阅个人 IM 事件/实时接收钉钉事件/监听并自动回复消息/驱动 Agent 处理消息" → event +listen-im;群成员加入/退出、群改名/解散或明确原始 EventKey/Filter DSL → event consume
用户提到"监听待我审批的任务/监听审批任务创建、完成或转交/监听审批单发起或终止/监听我发起的审批完成/监听审批实例完成/订阅 OA 事件/event consume user_oa_approval_" → event consume
用户提到"收到语音通话邀请时通知我/监听 VoIP 来电/订阅 user_voip_call_receive_invite" → event consume
用户提到"监听待办创建/更新/删除/监听指派给我的待办/订阅 Todo 事件/event consume user_todo_task_" → event consume,按角色使用 --role-types
用户提到"互动卡片回调/监听卡片操作/订阅 user_card_action_triggered" → event consume user_card_action_triggered --flatten -f ndjson
普通消息、reaction、已读、撤回监听优先由一个 dws event +listen-im 进程表达目标;不同用户、不同群或不同过滤条件拆成独立进程。只有高级事件控制才生成 dws event consume <event_key> [event_key...] --flatten。
关键区分: aitable(数据表格) vs todo(待办任务) 关键区分: report(钉钉日志/日报周报) vs todo(待办任务) 关键区分: chat send-by-bot(机器人身份发消息) vs send-by-webhook(自定义机器人Webhook告警) 关键区分: doc(在线富文本文档/adoc) vs markdown(原生 .md 纯文本文件) vs html(原生 .html 文件读写) vs drive(通用文件存储与传输) 关键区分: contact(基础通讯录档案:学历/家庭/银行卡/紧急联系人/合同/部门角色) vs aisearch person(通用语义找人:谁负责/上级/下级/多维度模糊搜索) vs hrbrain(人才池/员工档案专项模块数据/职业历程/绩效/结构化高级人才搜索) 关键区分: oa tasks(审批 taskId,审批/拒绝用) vs oa list-pending(收件箱 processInstanceId,查看用) 关键区分: oa(查询或操作审批) vs event user_oa_approval_(当前用户审批事件长连接监听) 关键区分: todo(查询或操作待办) vs event user_todo_task_(当前用户待办事件长连接监听)
更多易混淆场景见 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 | 删除图表/仪表盘 |
aitable | workflow disable | 停用自动化工作流(影响业务自动化) |
aitable | advperm disable | 停用高级权限总开关(关闭后全员回退默认权限) |
aitable | advperm role-delete | 删除自定义角色(不可逆,系统角色禁删) |
calendar | event delete | 删除日程,所有参与者同步取消 |
calendar | attendee delete | 移除日程参与者 |
calendar | room delete | 取消会议室预定 |
chat | group members remove | 移除群成员 |
chat | group dismiss | 解散群聊(不可恢复) |
chat | group upgrade-to-external | 升级为外部群(组织外可见,影响成员与信息安全边界) |
chat | clear-messages | 清空会话聊天记录 |
chat | message recall-by-bot | 撤回机器人已发消息 |
doc | delete | 删除整篇文档/文件到回收站(与 block delete 不同,本命令删除整个 node) |
doc | block delete | 删除文档块(不可恢复);--block-id 支持逗号分隔一次删多个 |
doc | permission update | 修改协作者权限(降权可能影响他人访问) |
ding | message recall | 撤回已发 DING 消息 |
dingtalk-tag | manage save-draft / manage publish / manage delete / capability skill create / capability mcp create | 覆写或发布数字员工、删除数字员工、创建能力资源;以 leaf Schema 的 confirmation 为准 |
oa | approval revoke | 撤销自己发起的审批实例 |
oa | approval reject | 拒绝待审批(需加明确理由) |
todo | task delete | 删除待办 |
minutes | replace-text | 全文批量替换转写与摘要 |
确认门禁的识别与重试协议
非交互环境(Agent/CI,stdin 非 TTY)下,写命令不带 --yes 时 CLI 不打印交互提示语,直接失败并输出结构化错误。识别方式:
--format json输出(或 stderr)中error.reason == "confirmation_required",错误信息含「当前环境无法交互确认」
遇到 confirmation_required 时按以下协议处理:
- 不要当普通错误放弃:把命令、风险等级(
write/high-risk-write)和关键参数展示给用户,明确告知这是写/高风险操作 - 用户显式同意 → 在原始命令末尾追加
--yes重试(不改动任何业务参数) - 用户拒绝 → 终止,不得改写参数绕过门禁
- 想先让用户 review 具体请求:加
--dry-run重试——它不触发确认门禁,会输出完整调用预览(invocation.params),用户确认预览后再换--yes执行
禁止:
- 看到
confirmation_required就未经用户同意自动追加--yes静默重试(等于禁用门禁) - 把
confirmation_required当网络/权限错误处理或重试 - 用
echo yes | dws ...等管道方式喂答案代替--yes(管道答案技术上会被接受,但违背了让用户显式知悉的设计意图)
核心流程
在选择 dws 的产品命令前,遵循以下流程:
- URL 预检:输入含
alidocs.dingtalk.comURL 时,该域名下存在多种路径格式(/i/nodes/...、/i/p/...、/spreadsheetv2/...、/document/edit|preview?dentryKey=...等),每种的处理流程不同。必须先读取 url-patterns.md 中的「alidocs URL 分流决策」,按其中规则识别 URL 类型后再选择对应产品。含shanji.dingtalk.comURL 时直接路由到minutes。URL 已识别后直接进入对应产品流程,无需后续步骤。 - 意图分类:判断用户指令的核心动词/动作属于哪一类。
- 歧义追问:指令模糊或包含多个产品的关键字时,严禁猜测,主动向用户追问澄清意图。
- 选定产品:参考产品总览和意图判断决策树选定产品,按任务最小化读取对应产品参考文件后执行(已知高频意图直接用已给出的唯一命令,不预加载完整产品参考)。
命令发现(Schema 渐进查询 + --help 互为补充)
Schema 渐进查询(Agent 选命令首选)
dws schema 内嵌当前二进制公开命令面的结构化契约。Agent 选择命令、读取参数映射/约束和安全语义时必须优先渐进查询 leaf Schema;真正组装执行参数前,用 --help 确认当前 Cobra 接受的 flags:
本节同时适用于基础/原子命令与公开内建 + shortcut。用户自定义或未公开 shortcut 不进入发布 Schema;其是否可执行仍以当前 Cobra help 为准。
已知命令路径例外:当本 Skill、产品意图表或任务 reference 已经给出精确 CLI path 时,不要再查询产品级/分组级 Schema,也不要调用完整 Shortcut Catalog;可直接执行。只有参数、约束或安全语义不确定时才读取该命令的 leaf Schema,只有当前 Cobra flags 不确定时才补读 leaf Help。
稳定 command identity、主 CLI path 和 alias 由 leaf ContractFinal.Identity 与真实 Cobra tree 精确绑定。Agent 不应读取 Catalog 文件、native annotation 或其他生成 JSON 来重新推断命令;所有运行时查询都以当前二进制交付的 Schema 投影为准。
# 第 1 层:产品概览(~4.5KB,列出全部产品 + 工具数 + 用途摘要)
dws schema
# 第 2 层:产品级(列出该产品下全部工具的 cli_path + description + effect/risk)
dws schema calendar --compact
# 第 3 层:分组级(按命令分组列出工具摘要)
dws schema "calendar event" --compact
# 第 4 层:Agent leaf(参数契约:type/required/description/constraints/examples)
dws schema "calendar event create" --compact
# --all:导出所有工具的完整 leaf Schema,仅用于 CI / 审计 / 参数 baseline
dws schema --all --format json
--all 使用边界(强制):--all 会返回每个工具的完整参数、约束和安全语义,输出体积很大。仅在用户明确要求全量导出,或执行 CI、Catalog 审计、参数防丢 baseline 时使用。普通业务任务严禁使用 --all 做命令发现,也不要把全量结果直接注入 Agent 上下文;必须按“产品概览 → 产品/分组 → leaf”渐进查询。完整兼容性 baseline 必须使用未裁剪的 schema --all;schema --all --compact 会移除 provenance 和接口映射字段,不得作为完整 baseline。
同一个工具省略 --compact 的 full leaf 与 --all 条目是同一份 ToolSpec 契约;compact leaf 只做展示投影,不重新解析语义。Alias 查询不得根据 alias 重写或补猜参数。若同一视图观察到内容差异,应作为契约漂移报告,而不是选择其中一份继续执行。
--compact Agent 模式采用正向字段白名单。保留 cli_path、canonical_path、description、effect、risk、confirmation、interface_mode、availability、interface_reason、parameters(含 type/required/description/default/enum)、constraints、examples、use_when、avoid_when;新增 full/audit 字段不会自动泄漏进 Agent 上下文。它有意不返回 interface_ref、参数 property/interface_type 和 provenance;检查这些映射事实时,用 full leaf 配合 --jq 精确投影。
--compact 是 Schema 展示能力。当前版本支持;若兼容旧二进制时收到 unknown_flag: --compact,仅去掉 --compact 重跑同一个 Schema 查询。不要因此判定 leaf 不存在,也不要改用 Schema 查询业务数据。
Schema 字段速查
// leaf 级输出(dws schema "calendar event create" --compact)
{
"cli_path": "calendar event create",
"canonical_path": "calendar.create_calendar_event",
"description": "创建新的日程...",
"effect": "write", // read | write | destructive
"risk": "medium", // low | medium | high
"confirmation": "not_required", // not_required | user_required
"interface_mode": "mcp", // mcp | local | composite
"availability": "available", // available | unavailable
"interface_reason": "",
"parameters": {
"title": { "type": "string", "required": true, "description": "..." },
"start": { "type": "string", "required": true, "format": "date-time" }
// ...
},
"constraints": { "require_together": [["recurrence-type", "recurrence-interval", "recurrence-range-type"]] },
"examples": ["dws calendar event create --title ..."]
}
confirmation=user_required→ 必须先向用户确认再加--yes;不要根据effect或risk的值自行重写最终 confirmation winneravailability=unavailable→ 不执行该工具;向用户说明interface_reason。interface_mode只描述实现机制,不能覆盖 availabilityparameters.<flag>.required=true→ Agent 应提供该参数;Cobra 是否硬拒绝以--help/实际命令契约为准parameters.<flag>.cli_required=true→ Cobra 将该 flag 标记为硬必填constraints.require_together→ 列出的 flag 必须同时提供
Schema、Help 与业务数据的边界
| 信息 | 事实源 |
|---|---|
| 命令是否存在、当前 Cobra 接受哪些 flags | dws <cli_path> --help |
| Agent 选择、CLI 参数/required/组合约束、risk/confirmation(原子/基础命令) | dws schema "<cli_path>" --compact |
| CLI↔RPC 参数映射、接口绑定或 provenance 审计 | full leaf 配合 --jq / --fields 精确投影;不要把整个 full leaf 注入 Agent 上下文 |
| shortcut 的参数、组合约束、risk/confirmation、示例 | 已知路径优先 dws schema --cli-path "<service> +<shortcut>" --compact --format json;完整 shortcut list 仅用于无法定位低频能力时的最后回退 |
| 人类可读用法 | dws <cli_path> --help |
| 钉钉中的文档、文件、日程、消息等实际数据 | 真正执行对应的 read / search / list 命令 |
Schema 与 Help 冲突是契约漂移,不得静默猜测或把两边字段随意拼接:
- 执行参数只使用 Cobra/Help 接受的 flags,并把漂移报告出来。
- 安全语义冲突时不能选择更宽松行为;先采用更保守的确认方式,无法确认安全执行方式时停止并报告。
- leaf Schema 是已经按来源 precedence 解析后的契约;不要根据值的“严格程度”自行改写 winner。只有发现它与 Help/实际执行契约冲突时,才进入上述安全降级。
dws schema 只查询命令契约,不搜索钉钉文档或业务数据。完成命令发现后,必须继续执行真实命令,例如 dws doc read、dws drive search;不要把 Schema 查询结果当成业务查询结果。
Helper-only 与本地 Cobra 命令
dev.* 包含 helper-only 执行面,其中远端 helper 未进入 pinned metadata 时标记为 composite,不能伪装成 local。event list / event schema 读取内置目录和 payload 定义,属于 local;event consume / event status / event stop 同时编排远端个人订阅控制面与本地 bus/consume,属于 composite。实现来源不同,不改变统一查询边界:进入全局 dws schema 的命令须由 leaf ContractFinal.Identity 声明收集,并由同一 ToolSpec 投影到 leaf、产品/分组、--all 与 Catalog。不得把 Cobra 临时合成结果作为第二条 Schema 数据路径。
事件需要区分两种 Schema:dws event schema <event_key> --flatten 查询 Agent 要消费的顶层业务字段;dws schema "event consume" --compact 查询 CLI 命令参数。前者是真实业务命令,后者只读取最终内嵌 SchemaRegistry;不能相互替代。
source 表示最终命令 identity 的来源,不表示运行时 backing;helper/local/MCP 实现机制读取 interface_mode、availability 和 provenance,不要假定 dev.* 必然是 source=mcp:<server>,也不要假定本地命令必然是 source=cobra。
错误处理
- 先读取 JSON 错误的
retryable、retry_after_seconds、next_retry_at、hint和actions;只有明确retryable=true时才按服务端节奏做一次有界重试。缺少重试语义时加--verbose收集诊断后停止 - 仍然失败,报告完整错误信息给用户,禁止自行尝试替代方案
- 认证失败时,参考 global-reference.md 中的认证章节处理
- 各产品高频错误及排查流程见 error-codes.md
- 遇到 capability-limits.md 中列出的「已知不支持操作」时,直接告知用户不支持并建议在钉钉客户端操作,不要重试或变通
详细参考 (按需读取)
- references/products/ — 各产品命令详细参考(Cobra 接受的 flag 以叶子
--help为准;公开基础命令与内建 shortcut 的 Agent 映射/约束/安全语义以 leaf Schema 为准) - references/products/dingtalk-tag/ — DingTalk Tag 数字员工生命周期、能力资源与执行查询
- references/intent-guide.md — 意图路由指南(易混淆场景对照)
- references/url-patterns.md — URL 格式规范 + alidocs URL 分流决策与类型探测流程(含钉盘
document/edit|preview?dentryKey=链接) - references/global-reference.md — 全局标志、认证、输出格式
- references/field-rules.md — AI表格字段类型规则
- references/error-codes.md — 错误码 + 调试流程
- scripts/ — 各产品批量/复合操作脚本(AI表格批量导入导出、日历、通讯录、考勤、日志、待办、钉盘目录树等)
- references/products/aitable/ — AI表格细分章节(单元格值/字段/公式/筛选/导入导出/记录增删改查/错误恢复/最佳实践);记录操作另见 aitable-record-ops.md
- references/products/pat.md — PAT 浏览器策略、行为 scope 预览与授权安全要求
- references/capability-limits.md — 已知能力限制(doc/aitable/chat/minutes,遇到时直接告知用户不支持)
- references/best_practices/ — 11 个编号场景 recipe(01 消息/02 任务/03 会议/04 文档/05 汇报/06 数据分析/07 听记/08 通讯录/09 邮件/10-11 听记发言人)+ lite-recipes.md 速查;通用规范在
_common/
Agent 使用 OpenNodes 带内容创建白板时,必须先执行 whiteboard render,展示 SVG 和渲染提示后停止,等待用户明确确认当前版本才能创建;修改后重新渲染和确认。不得跳过预览直接创建,最初的创建请求及创建后回读不能替代预览确认。详见白板入口的创建流程;空白创建、直接套用模板和已有白板更新不由此规则扩展。
Agent 更新已有白板内容(追加、修改、删除、清空)必须先执行 whiteboard +diff,展示差异和风险后停止,等待用户明确确认当前差异,再用同一 sourceDigest 执行 +update;diff 失败或有 blocker 时不得写入。不得换原子 update 绕过,render、dry-run 和写后回读不能替代 diff。详见白板入口的更新流程。更新只设一个用户确认点:先完成所需的 render 和必需的 +diff,再把视觉预览(如有)、差异与覆盖影响一起展示并一次确认;不要在 render 后先索要确认、获准后才补做 diff 再次询问。同一目标、revision、source 和模式已获确认后,直接提交;只有这些内容变化或出现未披露的实质风险才重新确认。
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 195k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 192k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 192k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 192k | Updated | Claude CodeCodex | Verified | Install |