Execution Contract
- Before executing the first
dwsoperation, fully readdingtalk-shared; if the current task is already loaded, do not read it again. - First break the request into ordered steps, then choose entry points step by step. If the command is known, execute it directly without first checking Help, Schema, or Shortcut Catalog; only when the current leaf's flag or security semantics are genuinely unclear should you check the exact leaf.
- Add
--format jsonto all commands, and judge the result based on the structured business response. Subsequent IDs should only be taken from the actual response of this run; when there are zero matches, multiple matches, or the type is unclear, stop and disambiguate. - Write operations follow the final Runtime gate. When confirmation is needed, first state the object, action, and impact, and only after the user confirms append
--yes; do not write--yesinto storage examples. - Verification is mandatory after writing. When a non-idempotent write times out, lacks a stable ID, or fails to read back, query for reconciliation first; blind replay is prohibited.
Shortcuts (preferred when there is no dedicated script/recipe)
The following shortcuts enter both the public catalog and the Runtime Schema. Route according to this skill/recipe, and when matched, Shortcut takes precedence over atomic commands. For parameters, check only dws schema --cli-path "todo +<shortcut>" --compact --jq '{cli_path,parameters,constraints,confirmation}' -f json; when only and already-published result is needed, check --jq '{cli_path,outcomes:.result.outcomes,pagination}', and for field-level details check data_schema; do not infer from Help/examples when missing. Only read the known leaf Help once if Schema is unavailable;unknown flag correct once using the same leaf Help.unknown command Help is prohibited: error suggestion → entry point already specified in the loaded Skill/reference; if neither exists, report drift. All Catalog/root/parent/product Help is prohibited; omit --compactonly for mapping, interface, or provenance auditing. Only when neither existing routes nor references can locate a low-frequency capability, use dws shortcut list --service todo --format json for discovery.
| Shortcut | Risk | Applicable Scenario |
|---|---|---|
dws todo +assign |
write | Create and assign a to-do for someone by name (automatically resolve userId) |
dws todo +assign-multi |
write | Assign one to-do to multiple people by name in one go (automatically resolve each name to a userId) |
dws todo +comment |
write | Add a to-do comment and verify by reading it back |
dws todo +create |
write | Create a to-do and verify by reading it back |
dws todo +created-todos |
read | List the to-dos I created (to-dos I initiated as the creator, not those assigned to me for execution) |
dws todo +due-today |
read | List the to-dos due today |
dws todo +get |
read | Query to-do details |
dws todo +get-my-tasks |
read | Query my to-do list under the current organization |
dws todo +get-related-tasks |
read | List all to-dos related to me in one go (the union of my three roles as creator/executor/participant, deduplicated by taskId) |
dws todo +list-attachment |
read | Query the attachment list of a to-do task |
dws todo +list-comment |
read | Query the to-do comment list |
dws todo +list-sub |
read | Query the subtask to-do list |
dws todo +overdue |
read | List my overdue incomplete to-dos |
dws todo +remind |
write | Create a to-do for myself with an optional due time |
dws todo +reminder |
write | Set or clear a to-do reminder (terminal receipt only) |
dws todo +search |
read | Search all to-dos related to me |
dws todo +todo-done |
write | Mark one of my to-dos as complete by title keyword (automatically locate taskId) |
dws todo +update |
write | Update a to-do and verify by reading it back |
Routing Priority
The general Shortcut priority rule above applies only tothe case where a Shortcut fully covers the current step. Do not default to using it just because the request contains "create" +remind / +create。
- choose the creation entry point first: assign by name with
+assign/+assign-multi; to record one for yourself and only search, view details, or clean up afterward, use+remind; if there is already a realuserIdand you only need to create, read back, and clean up, use+create。 - The composite lifecycle starts from atomic creation: after creation you still need to list by status/priority/role/date/page number, or continue updating, completing/reopening, reminders, comments, attachments, members, subtasks, tags, or create multiple objects at once, use
todo task create. Do not use the creation Shortcut as a substitute for the first step. - For subsequent steps, choose the narrowest entry point: when aggregation, search, and verification are fully covered by Shortcuts, use
+get-my-tasks、+get-related-tasks、+due-today、+overdue、+search、+get、+complete、+reopen、+update、+comment、+reminderor+list-*; when you need atomic-specific parameters, dynamic sub-resource IDs, multiple objects, or intermediate states, use atomic commands. - Use scripts for deterministic batch/summary operations: for batch creation, today/tomorrow/this week summaries, and overdue scans, use the bundled script respectively.
- Across steps, pass only stable IDs: Shortcuts and atomic commands can coexist, but only pass the normalized
taskId、commentId、attachmentId、tagCode、userId; do not assume the two types of entry points return identical full response structures.
Golden Routes
| User intent | Preferred entry point | Key result / boundary |
|---|---|---|
| Create for yourself, then only search, view details, or clean up | dws todo +remind --task "<标题>" [--at "<截止ISO>"] --format json |
Automatically resolve the current user;--at is the due time, not the reminder time |
| "Create a to-do for Zhang San" | dws todo +assign --to "张三" --task "<标题>" --format json |
The name must resolve uniquely before creation |
| "Create the same to-do for Zhang San and Li Si" | dws todo +assign-multi --to "张三,李四" --task "<标题>" --format json |
If any name is not unique, zero writes |
Already has userId, only create, read back, and clean up |
dws todo +create --title "<标题>" --executors <USER_ID> [--due "<截止ISO>"] [--priority 10|20|30|40] --format json |
Return a stable taskId, and read back to verify the title |
| After creation you still need to filter, change resources, or create multiple objects | dws todo task create --title "<标题>" --executors <USER_ID> ... --format json |
Enter the composite lifecycle from result.taskId ; do not start with +remind / +create Start |
| Due today / overdue | dws todo +due-today --format json / dws todo +overdue --format json |
Both boundedly pull all pages; an empty set is also a successful result |
| My action to-dos under the current organization | dws todo +get-my-tasks --all --status false --format json |
--all reaching 40 pages without being exhausted will fail, not pretend to be complete |
| All to-dos related to me | dws todo +get-related-tasks --format json |
Union of the three roles: creator, assignee, and participant, deduplicated by taskId Deduplicate |
| Query by title keyword | dws todo +search --query "<关键词>" --format json |
Search and list are not mixed; match 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 the title, due time, or priority | dws todo +update --task-id <TASK_ID> ... --format json |
Specify at least one field to change; verify field by field after writing |
| Set an independent reminder | dws todo +reminder --task-id <TASK_ID> --base-time customTime --at "<提醒ISO>" --format json |
The upstream has no reminder query interface and can only return terminal write receipts,verified=false |
| Advance reminder based on deadline | dws todo +reminder --task-id <TASK_ID> --base-time dueTime --due-date-offset -30 --format json |
The to-do must already have a deadline; the offset unit is minutes |
| Clear all reminders | dws todo +reminder --task-id <TASK_ID> --clear --format json |
Clear 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; if the content changes, it will be rejected at zero calls |
| Today/Tomorrow/This week summary | python scripts/todo_daily_summary.py today|tomorrow|week |
Use +get-my-tasks --all, include only incomplete to-dos within the range that have deadlines |
Low-frequency atomic capabilities
Composite requests read first Composite lifecycle. The following common atomic commands have been approved; execute them directly and do not guess aliases or check Help first:
| Intent | Command skeleton |
|---|---|
| Resolve self / name | dws contact user get-self --format json / dws aisearch person --query "<姓名>" --dimension name --format json |
| Create / subtask | 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 executor / participant | task add-executor / task remove-executor / task add-participant / task remove-participant, all pass the real taskId and userId |
| Comment | comment add / comment list / comment delete; for deletion use the real commentId |
| Attachment | task add-attachment --file <绝对路径> / task list-attachment / task remove-attachment |
| Reminder | task add-reminder add a single record;task reset-reminder replace all or clear |
| Tag | tag create / tag list / tag update / tag add / tag delete; use only the real tagCode |
| Delete to-do | dws todo task delete --task-id <TASK_ID> --format json |
Deletion-type operations must be confirmed by the user; if the user has explicitly authorized "delete/clean up the objects created this time after completion" in the current request, that authorization covers only the exact IDs recorded this time. Attachment uploads actually transfer local files and cannot be used to probe permissions.
Key constraints
- Title, URL, and display number are not
taskId. Act directly on known IDs; use list/search to locate unknown IDs, and stop when there are zero or multiple matches. - Public to-do commands uniformly use
--task-id；--id/--idsis only a hidden compatibility alias; do not write it into new commands or examples. - Priority: low=10, normal=20, medium/high/important=30, urgent/highest/P0=40.
--due/+remind --atrepresents deadline; an independent reminder must use+reminder。- The atomic flag for custom-time reminders is
--reminder-time-stamp; do not apply the Shortcut's--attotask add-reminder。 task listuse--status, do not write--done; details aretask get, there is notask detail。- "To-do tag" always belongs to Todo; use
dws todo tag ...; it must never be interpreted as a Git tag, contact tag, or any other product tag. - Create and comment are non-idempotent writes. On timeout, missing stable ID, or failed read-back, retain the "possibly submitted/unverified" state, query first for reconciliation, and do not blindly replay.
- Add to all commands
--format json; write Shortcut confirms according to the Runtime security contract; before confirmation, do not append--yes。 - When post-meeting action items come from notes, first use
dingtalk-minutes; OA approval usesdingtalk-misc; time blocks and meetings usedingtalk-calendar。