dingtalk-todo

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

钉钉待办 Skill

DingTalk Todo Skill

执行契约

Execution Contract

执行第一个
```
dws
```
操作前完整读取
```
dingtalk-shared
```
；当前任务已加载则不重复读取。
先把请求拆成有序步骤，再逐步选入口。已知命令直接执行，不先查 Help、Schema 或 Shortcut Catalog；只有当前 leaf 的 flag 或安全语义确实不明时才查精确 leaf。
所有命令加
```
--format json
```
，按结构化业务返回判断结果。后续 ID 只取自本次真实返回；零匹配、多匹配或类型不明时停止并消歧。
写操作遵循最终 Runtime gate。需要确认时先说明对象、动作和影响，用户确认后才追加
```
--yes
```
；不要把
```
--yes
```
写入存储示例。
写后必须核验。非幂等写超时、缺少稳定 ID 或读回失败时先查询对账，禁止盲目重放。

Before the first
```
dws
```
operation, fully read
```
dingtalk-shared
```
; if already loaded in the current task, do not read it again.
Break the request into ordered steps first, then choose entry points step by step. For known commands, execute directly without first checking Help, Schema, or Shortcut Catalog; only check the exact leaf when its flag or security semantics are genuinely unclear.
Add
```
--format json
```
to all commands and judge results by structured business responses. Subsequent IDs come only from this actual response; stop and disambiguate on zero matches, multiple matches, or unclear types.
Writes follow the final Runtime gate. When confirmation is needed, first state the object, action, and impact; append
```
--yes
```
only after the user confirms. Do not write
```
--yes
```
into stored examples.
Verify after every write. On non-idempotent write timeout, missing stable ID, or read-back failure, query to reconcile first; blind replay is forbidden.

Shortcuts（无专用脚本/recipe 时优先）

Shortcuts (preferred when no dedicated script/recipe exists)

以下 shortcut 同时进入公开 catalog 与 Runtime Schema。按本 skill/recipe 路由，命中时 Shortcut 优先于原子命令。参数只查

dws schema --cli-path "todo +<shortcut>" --compact --jq '{cli_path,parameters,constraints,confirmation}' -f json

；仅需且已发布

result

时查

--jq '{cli_path,outcomes:.result.outcomes,pagination}'

，字段级再查

data_schema

；缺失不以 Help/样例推断。Schema 不可用才读一次已知 leaf Help；

unknown flag

用同 leaf Help 修正一次。

unknown command

禁 Help：错误 suggestion → 已加载 Skill/reference 明确入口；均无则报漂移。禁全 Catalog/root/parent/product Help；仅映射、接口或 provenance 审计省略

--compact

。现有路由和 reference 均无法定位低频能力时，才用

dws shortcut list --service todo --format json

发现。

Shortcut	风险	适用场景
`dws todo +assign`	write	按姓名给某人创建并指派一条待办（自动解析 userId）
`dws todo +assign-multi`	write	把一条待办按姓名一次性指派给多个人（自动把每个姓名解析成 userId）
`dws todo +comment`	write	添加待办评论并读回验证
`dws todo +create`	write	创建待办并读回验证
`dws todo +created-todos`	read	列出我创建的待办（我作为创建人 creator 发起的待办，而非分配给我执行的）
`dws todo +due-today`	read	列出我今天到期的待办
`dws todo +get`	read	查询待办详情
`dws todo +get-my-tasks`	read	查询当前组织下我的待办列表
`dws todo +get-related-tasks`	read	一次性列出与我相关的全部待办（我作为创建人/执行人/参与人三种角色的并集，按 taskId 去重）
`dws todo +list-attachment`	read	查询待办任务的附件列表
`dws todo +list-comment`	read	查询待办评论列表
`dws todo +list-sub`	read	查询子待办列表
`dws todo +overdue`	read	列出我已过期未完成的待办
`dws todo +remind`	write	给自己创建一条带可选截止时间的待办
`dws todo +reminder`	write	设置或清除待办提醒（仅终端回执）
`dws todo +search`	read	搜索与我相关的全部待办
`dws todo +todo-done`	write	按标题关键词把我的某条待办标记完成（自动定位 taskId）
`dws todo +update`	write	更新待办并读回验证

The following shortcuts also enter the public catalog and Runtime Schema. Route by this skill/recipe; on a hit, Shortcut takes priority over atomic commands. For parameters, only query

dws schema --cli-path "todo +<shortcut>" --compact --jq '{cli_path,parameters,constraints,confirmation}' -f json

; when only the published

result

is needed, query with

--jq '{cli_path,outcomes:.result.outcomes,pagination}'

; for field-level details, query

data_schema

; do not infer missing information from Help/examples. Only when the Schema is unavailable, read the known leaf Help once; an

unknown flag

can be corrected once with the same leaf Help.

unknown command

forbids Help: a wrong suggestion → use the loaded Skill/reference to determine the entry; if both are absent, report drift. Full Catalog/root/parent/product Help is forbidden; omit

--compact

only for mapping, interface, or provenance audits. Only when existing routes and references cannot locate a low-frequency capability, use

dws shortcut list --service todo --format json

to discover.

Shortcut	Risk	Applicable scenarios
`dws todo +assign`	write	Create and assign a todo to someone by name (automatically resolves userId)
`dws todo +assign-multi`	write	Assign one todo to multiple people by name at once (automatically resolves each name into a userId)
`dws todo +comment`	write	Add a todo comment and read back to verify
`dws todo +create`	write	Create a todo and read back to verify
`dws todo +created-todos`	read	List todos I created (as creator, not assigned to me for execution)
`dws todo +due-today`	read	List todos due today
`dws todo +get`	read	Query todo details
`dws todo +get-my-tasks`	read	List my todos under the current organization
`dws todo +get-related-tasks`	read	List all todos related to me at once (union of creator/executor/participant roles, deduplicated by taskId)
`dws todo +list-attachment`	read	Query the attachment list of a todo task
`dws todo +list-comment`	read	Query the comment list of a todo
`dws todo +list-sub`	read	Query the subtask list
`dws todo +overdue`	read	List my overdue incomplete todos
`dws todo +remind`	write	Create a todo for myself with an optional due time
`dws todo +reminder`	write	Set or clear todo reminders (terminal receipt only)
`dws todo +search`	read	Search all todos related to me
`dws todo +todo-done`	write	Mark one of my todos as done by title keyword (automatically locates taskId)
`dws todo +update`	write	Update a todo and read back to verify

路由优先级

Routing Priority

上面的通用 Shortcut 优先规则只适用于一个 Shortcut 完整覆盖当前步骤的情况。不要因为请求里出现“创建”就默认使用

+remind

+create

。

先选创建入口：按姓名指派用
```
+assign
```
/
```
+assign-multi
```
；给自己记一条且后续只有搜索、详情或清理时用
```
+remind
```
；已有真实
```
userId
```
且只需创建、回读和清理时用
```
+create
```
。
组合生命周期从原子创建开始：创建后还要按状态/优先级/角色/日期/页码列举，或继续更新、完成/重开、提醒、评论、附件、成员、子待办、标签，或一次创建多个对象时，使用
```
todo task create
```
。不要用创建 Shortcut 代替第一步。
后续按步骤选最窄入口：聚合、搜索和核验完整由 Shortcut 覆盖时使用
```
+get-my-tasks
```
、
```
+get-related-tasks
```
、
```
+due-today
```
、
```
+overdue
```
、
```
+search
```
、
```
+get
```
、
```
+complete
```
、
```
+reopen
```
、
```
+update
```
、
```
+comment
```
、
```
+reminder
```
或
```
+list-*
```
；需要原子特有参数、动态子资源 ID、多对象或中间状态时用原子命令。
确定性批量/汇总使用脚本：批量创建、今天/明天/本周汇总、逾期扫描分别使用 bundled script。
跨步骤只传稳定 ID：Shortcut 与原子命令可以共存，但只传递规范化后的
```
taskId
```
、
```
commentId
```
、
```
attachmentId
```
、
```
tagCode
```
、
```
userId
```
；不要假设两类入口的完整返回结构相同。

The generic Shortcut priority rule above applies only when one Shortcut fully covers the current step. Do not default to

+remind

+create

just because the request contains 'create'.

Choose the creation entry first: use
```
+assign
```
/
```
+assign-multi
```
for assigning by name; use
```
+remind
```
for recording one for yourself that will only be searched, viewed, or cleaned up later; use
```
+create
```
when you already have a real
```
userId
```
and only need create, read-back, and cleanup.
Compose a lifecycle starting from atomic creation: use
```
todo task create
```
when after creation you need to list by status/priority/role/date/page, or continue updating, completing/reopening, reminding, commenting, attachments, members, subtasks, tags, or creating multiple objects at once. Do not use a creation Shortcut in place of the first step.
Then choose the narrowest entry per step: use
```
+get-my-tasks
```
,
```
+get-related-tasks
```
,
```
+due-today
```
,
```
+overdue
```
,
```
+search
```
,
```
+get
```
,
```
+complete
```
,
```
+reopen
```
,
```
+update
```
,
```
+comment
```
,
```
+reminder
```
, or
```
+list-*
```
when a Shortcut fully covers aggregation, search, and verification; use atomic commands when atomic-specific parameters, dynamic sub-resource IDs, multiple objects, or intermediate states are needed.
Use scripts for deterministic batch/aggregation: batch creation, today/tomorrow/week summaries, and overdue scans use the bundled scripts.
Only pass stable IDs across steps: Shortcuts and atomic commands can coexist, but only pass normalized
```
taskId
```
,
```
commentId
```
,
```
attachmentId
```
,
```
tagCode
```
, and
```
userId
```
; do not assume the two entry types have identical complete return structures.

Golden Routes

用户意图	首选入口	关键结果 / 边界
给自己创建，随后只搜索、看详情或清理	`dws todo +remind --task "<标题>" [--at "<截止ISO>"] --format json`	自动解析当前用户； `--at` 是截止时间，不是提醒时间
“给张三建待办”	`dws todo +assign --to "张三" --task "<标题>" --format json`	姓名必须唯一解析后才创建
“给张三、李四建同一条待办”	`dws todo +assign-multi --to "张三,李四" --task "<标题>" --format json`	任一姓名不唯一则零写入
已有 `userId` ，只创建、回读和清理	`dws todo +create --title "<标题>" --executors <USER_ID> [--due "<截止ISO>"] [--priority 10\|20\|30\|40] --format json`	返回稳定 `taskId` ，并读回核验标题
创建后还要筛选、变更资源或创建多个对象	`dws todo task create --title "<标题>" --executors <USER_ID> ... --format json`	从 `result.taskId` 进入组合生命周期；不要以 `+remind` / `+create` 起步
今天到期 / 已逾期	`dws todo +due-today --format json` / `dws todo +overdue --format json`	均有界拉全分页；空集合也是成功结果
当前组织下我的执行待办	`dws todo +get-my-tasks --all --status false --format json`	`--all` 达到 40 页仍未耗尽会失败，不伪装完整
与我相关的全部待办	`dws todo +get-related-tasks --format json`	创建人、执行人、参与人三种角色并集，按 `taskId` 去重
按标题关键词查询	`dws todo +search --query "<关键词>" --format json`	搜索与 list 不混用；跨全部分页匹配
已知 `taskId` 查详情	`dws todo +get --task-id <TASK_ID> --format json`	详情必须回传同一个稳定 `taskId`
已知 `taskId` 完成 / 重开	`dws todo +complete --task-id <TASK_ID> --format json` / `dws todo +reopen ...`	先读当前状态，避免重复写，再读回核验
只记得标题，标记完成	`dws todo +todo-done --task "<关键词>" --format json`	仅唯一命中时写；零个或多个候选均停止
修改标题、截止时间或优先级	`dws todo +update --task-id <TASK_ID> ... --format json`	至少指定一个待改字段；写后逐字段核验
设置独立提醒	`dws todo +reminder --task-id <TASK_ID> --base-time customTime --at "<提醒ISO>" --format json`	上游无提醒查询接口，只能返回终端写回执， `verified=false`
基于截止时间提前提醒	`dws todo +reminder --task-id <TASK_ID> --base-time dueTime --due-date-offset -30 --format json`	待办必须已有截止时间；偏移单位为分钟
清除全部提醒	`dws todo +reminder --task-id <TASK_ID> --clear --format json`	清除写操作；不能与提醒参数混用
批量创建	`python scripts/todo_batch_create.py <todos.json> --dry-run`	预览返回稳定 `planDigest` ；执行必须提交用户确认的同一摘要，内容变化会在零调用时拒绝
今天/明天/本周汇总	`python scripts/todo_daily_summary.py today\|tomorrow\|week`	走 `+get-my-tasks --all` ，只纳入范围内且有截止时间的未完成待办

User intent	Preferred entry	Key results / boundaries
Create for yourself, then only search, view details, or clean up	`dws todo +remind --task "<标题>" [--at "<截止ISO>"] --format json`	Automatically resolves the current user; `--at` is the due time, not the reminder time
Assign a todo to Zhang San	`dws todo +assign --to "张三" --task "<标题>" --format json`	Create only after the name resolves uniquely
Create the same todo for Zhang San and Li Si	`dws todo +assign-multi --to "张三,李四" --task "<标题>" --format json`	If any name is not unique, zero writes are performed
Already have `userId` , only create, read back, and clean up	`dws todo +create --title "<标题>" --executors <USER_ID> [--due "<截止ISO>"] [--priority 10\|20\|30\|40] --format json`	Returns a stable `taskId` and reads back to verify the title
After creation, also filter, change resources, or create multiple objects	`dws todo task create --title "<标题>" --executors <USER_ID> ... --format json`	Enter the combined lifecycle from `result.taskId` ; do not start with `+remind` / `+create`
Due today / overdue	`dws todo +due-today --format json` / `dws todo +overdue --format json`	Both fetch all pages within bounds; an empty result is also a successful result
My execution todos under the current organization	`dws todo +get-my-tasks --all --status false --format json`	`--all` fails if not exhausted after 40 pages; do not pretend it is complete
All todos related to me	`dws todo +get-related-tasks --format json`	Union of creator/executor/participant roles, deduplicated by `taskId`
Query by title keyword	`dws todo +search --query "<关键词>" --format json`	Search and list are not mixed; matches across all pages
Known `taskId` , query details	`dws todo +get --task-id <TASK_ID> --format json`	Details must return the same stable `taskId`
Known `taskId` , complete / reopen	`dws todo +complete --task-id <TASK_ID> --format json` / `dws todo +reopen ...`	Read the current state first to avoid duplicate writes, then read back to verify
Only remember the title, mark as complete	`dws todo +todo-done --task "<关键词>" --format json`	Write only on a unique match; stop on zero or multiple candidates
Modify title, due time, or priority	`dws todo +update --task-id <TASK_ID> ... --format json`	Specify at least one field to change; verify each field after writing
Set a standalone reminder	`dws todo +reminder --task-id <TASK_ID> --base-time customTime --at "<提醒ISO>" --format json`	Upstream has no reminder query interface; only the terminal write receipt can be returned, `verified=false`
Remind in advance based on due time	`dws todo +reminder --task-id <TASK_ID> --base-time dueTime --due-date-offset -30 --format json`	The todo must already have a due time; offset unit is minutes
Clear all reminders	`dws todo +reminder --task-id <TASK_ID> --clear --format json`	Clear is a write operation; cannot be mixed with reminder parameters
Batch create	`python scripts/todo_batch_create.py <todos.json> --dry-run`	Preview returns a stable `planDigest` ; execution must submit the same digest confirmed by the user; content changes are rejected before any call is made
Today / tomorrow / week summary	`python scripts/todo_daily_summary.py today\|tomorrow\|week`	Uses `+get-my-tasks --all` ; only includes unfinished todos within the range and with a due time

低频原子能力

Low-Frequency Atomic Capabilities

组合请求先读组合生命周期。以下常用原子命令已审定，直接执行，不要先猜别名或查 Help：

意图	命令骨架
解析自己 / 姓名	`dws contact user get-self --format json` / `dws aisearch person --query "<姓名>" --dimension name --format json`
创建 / 子待办	`dws todo task create ...` / `dws todo task create-sub --parent-id <PARENT_ID> --title "<标题>" --executors <USER_ID> ...`
列表 / 详情	`dws todo task list [--status true\|false] [--priority ...] [--role-types ...] [--page N --size N] ...` / `dws todo task get --task-id <TASK_ID>`
更新 / 完成或重开	`dws todo task update --task-id <TASK_ID> ...` / `dws todo task done --task-id <TASK_ID> --status true\|false`
增删执行人 / 参与人	`task add-executor` / `task remove-executor` / `task add-participant` / `task remove-participant` ，均传真实 `taskId` 与 `userId`
评论	`comment add` / `comment list` / `comment delete` ；删除使用列表返回的真实 `commentId`
附件	`task add-attachment --file <绝对路径>` / `task list-attachment` / `task remove-attachment`
提醒	`task add-reminder` 添加单条； `task reset-reminder` 替换全部或清空
标签	`tag create` / `tag list` / `tag update` / `tag add` / `tag delete` ；只使用真实 `tagCode`
删除待办	`dws todo task delete --task-id <TASK_ID> --format json`

删除类操作必须由用户确认；若用户在当前请求中已明确授权“办完后删除/清理本次创建对象”，该授权只覆盖本次记录的精确 ID。附件上传会真实传输本地文件，不能用来试探权限。

For combined requests, read Combined Lifecycle first. The following commonly used atomic commands are approved; execute them directly without guessing aliases or checking Help:

Intent	Command skeleton
Resolve self / name	`dws contact user get-self --format json` / `dws aisearch person --query "<姓名>" --dimension name --format json`
Create / subtasks	`dws todo task create ...` / `dws todo task create-sub --parent-id <PARENT_ID> --title "<标题>" --executors <USER_ID> ...`
List / details	`dws todo task list [--status true\|false] [--priority ...] [--role-types ...] [--page N --size N] ...` / `dws todo task get --task-id <TASK_ID>`
Update / complete or reopen	`dws todo task update --task-id <TASK_ID> ...` / `dws todo task done --task-id <TASK_ID> --status true\|false`
Add/remove executors / participants	`task add-executor` / `task remove-executor` / `task add-participant` / `task remove-participant` , all use the real `taskId` and `userId`
Comments	`comment add` / `comment list` / `comment delete` ; deletion uses the real `commentId` returned by the list
Attachments	`task add-attachment --file <绝对路径>` / `task list-attachment` / `task remove-attachment`
Reminders	`task add-reminder` adds one; `task reset-reminder` replaces all or clears them
Tags	`tag create` / `tag list` / `tag update` / `tag add` / `tag delete` ; only use real `tagCode`
Delete todo	`dws todo task delete --task-id <TASK_ID> --format json`

Delete-type operations must be confirmed by the user; if the user has explicitly authorized in the current request to 'delete/clean up the object created this time after completion', the authorization only covers the exact IDs recorded in this session. Attachment uploads actually transfer local files and must not be used to probe permissions.

关键约束

Key Constraints

标题、URL、展示序号都不是
```
taskId
```
。已知 ID 直接行动；未知 ID 用列表/搜索定位，零匹配或多匹配时停止。
待办公开命令统一使用
```
--task-id
```
；
```
--id
```
/
```
--ids
```
只是隐藏兼容别名，不要写入新命令或示例。
优先级：低=10、普通=20、较高/高/重要=30、紧急/最高/P0=40。
```
--due
```
/
```
+remind --at
```
表示 deadline；独立 reminder 必须走
```
+reminder
```
。
自定义时间提醒的原子 flag 是
```
--reminder-time-stamp
```
；不要把 Shortcut 的
```
--at
```
套到
```
task add-reminder
```
。
```
task list
```
使用
```
--status
```
，不要写
```
--done
```
；详情是
```
task get
```
，不存在
```
task detail
```
。
“待办标签”始终属于 Todo，使用
```
dws todo tag ...
```
；绝不能解释成 Git tag、通讯录标签或其他产品标签。
创建和评论是非幂等写。超时、缺少稳定 ID 或读回失败时保留“可能已提交/未核验”状态，先查询对账，禁止盲目重放。
所有命令加
```
--format json
```
；写 Shortcut 按 Runtime 安全契约确认，确认前不得自行附加
```
--yes
```
。
会后行动项来自听记时先走
```
dingtalk-minutes
```
；OA 审批走
```
dingtalk-misc
```
；时间块和会议走
```
dingtalk-calendar
```
。

Title, URL, and display sequence number are not
```
taskId
```
. Act directly on known IDs; for unknown IDs, locate via list/search, and stop on zero or multiple matches.
Todo public commands uniformly use
```
--task-id
```
;
```
--id
```
/
```
--ids
```
are only hidden compatibility aliases. Do not write them into new commands or examples.
Priority: low=10, normal=20, above normal/high/important=30, urgent/highest/P0=40.
```
--due
```
/
```
+remind --at
```
means the deadline; standalone reminders must use
```
+reminder
```
.
The atomic flag for a custom-time reminder is
```
--reminder-time-stamp
```
; do not apply the Shortcut's
```
--at
```
to
```
task add-reminder
```
.
```
task list
```
uses
```
--status
```
; do not write
```
--done
```
; details are
```
task get
```
;
```
task detail
```
does not exist.
'Todo tags' always belong to Todo; use
```
dws todo tag ...
```
; never interpret them as Git tags, contact tags, or other product tags.
Creation and comments are non-idempotent writes. On timeout, missing stable ID, or read-back failure, keep a 'possibly submitted/unverified' state and query to reconcile first; blind replay is forbidden.
All commands add
```
--format json
```
; write Shortcuts follow the Runtime security contract; do not attach
```
--yes
```
on your own before confirmation.
Post-meeting action items from minutes should go through
```
dingtalk-minutes
```
first; OA approvals use
```
dingtalk-misc
```
; time blocks and meetings use
```
dingtalk-calendar
```
.

按需参考

On-Demand References

局部意图消歧
轻量流程
组合流程
完整命令参考

Local Intent Disambiguation
Lightweight Flows
Combined Flows
Complete Command Reference