Minimal DWS Execution Contract
- Use only
dws; for structured reads add--format json, and judge by the actual return. - Directly invoke known commands; when parameters/constraints/security are unclear, check the narrow leaf Schema. Only when the Schema is unavailable, read the known leaf Help once;
unknown flaguse the same leaf Help to correct once.unknown commandDo not check Help: prioritize explicit suggestions in the error, then explicit compatible entries in loaded Skills/references; if neither exists, report drift and stop; no full Catalog. Low-frequency references do not default to Help; root/parent/product Help is forbidden. After discovery, it must be executed or the blockage explained. - Do not guess commands/flags/fields/IDs/accounts/business facts; IDs come from actual returns. Zero hits/multiple candidates/unclear type for the target must be disambiguated first; only optional time/display scope use contract defaults; if required information is missing, stop.
- Parse/read/write the same profile; IDs do not cross organizations. For multiple accounts use only the unique
isOrgCurrent=true; otherwise the user specifies, and choosing the first item, most recent login, or most recently used account is forbidden. - Do not output/record tokens, refresh tokens, appSecret, webhook tokens; do not request them when authentication is already injected.
- Writes must conform to explicit intent; confirmation is subject to the final Runtime gate/Schema, and only after confirmation add
--yes。 - verify results after writing, and do not claim success based on exit codes. Exit must be the final reply, distinguishing complete, partial, blocked, pending confirmation, and failed; preserve existing data and
complete/hasMore/stopReason/failures。 - display timestamps according to the session time zone, and preserve the original values when necessary.
- For authentication/permission/profile/confirmation/unknown errors, only read
dingtalk-sharedthe corresponding reference; guessing alternative commands in succession is forbidden.
Shortcut Discovery (as needed)
minutes currently has 29 public shortcuts; the complete list is kept in the Runtime Catalog and Schema and is not repetitively expanded in the high-frequency product root Skill. For known intent, directly invoke according to the routing/reference below; when parameters/constraints/security are unclear, read the narrow leaf Schema once. Only when needed and already published result check outcomes/pagination, and for field-level check data_schema; do not infer from Help/samples when missing. Only when the Schema is unavailable, read the known leaf Help once;unknown flag use the same leaf Help to correct once.unknown command Help is forbidden: error suggestion → explicit entry in loaded Skill/reference; if neither exists, report drift. Full Catalog/root/parent/product Help is forbidden; low-frequency references do not default to Help.
Only when existing routing and references cannot locate a low-frequency capability, execute dws shortcut list --service minutes --format json as the last fallback; do not load the complete Shortcut Catalog or product-level Schema for known high-frequency intents.
Golden Route
The following are the core paths currently supported by the Minutes Case, used to reduce Agent routing forks; they are not equivalent to production usage frequency statistics. An existing taskUuid must be passed through as-is; decoding or re-encoding is forbidden; for a complete minutes URL, first extract the taskUuid, then use it as-is. When only a title or time clue is available, search first; stop on zero hits; when there are multiple candidates or the candidates differ greatly, have the user disambiguate, and do not default to taking the first item.
| User intent | Sole recommended entry | Key boundaries |
|---|---|---|
| Find minutes by title or time | dws minutes +search --scope all --query "<关键词>" --page-all |
scope optional mine/shared/all; provide at least one of query/start/end.all --page-all After exhaustively paging through mine/shared respectively, deduplicate; do not treat a single noLimit endpoint as the complete full set |
| Browse minutes I created, that are shared with me, or all accessible minutes | +list-mine / +list-shared / +list-all |
The default is a resumable preview; to claim completeness you must add --page-all and check complete=true. When the user only says "my minutes" it does not equal an explicit mine; when the scope is unclear use all |
| Find minutes by real tags | dws minutes tag list --format json, then tag query --tag-id <真实tagId> |
Tags are not equal to keywords; an empty tag means the end. For pagination details of finding by tags see the local intent |
| See my latest created one | dws minutes +latest [--keyword <关键词>] |
Only use when the user explicitly says "latest"; do not use it to replace a named-target search, and do not use latest after a recording start to guess the new recording ID |
| Read basic info, summary, or keywords | dws minutes +detail --id <taskUuid> --artifacts basic,summary,keywords |
When a taskUuid already exists and only existing artifacts are being read, use it directly; do not enter the upload workflow; any artifact failure is handled as partial/non-zero, and do not describe missing items as empty content |
| Read the verbatim transcript | dws minutes +transcript --id <taskUuid> [--direction 1] [--single-page] |
When a taskUuid already exists and only the verbatim transcript is being read, use it directly; do not use +upload-and-analyze --resume-id to read on its behalf. Default to ascending order and page through to the end; for descending order you must pass --direction 1, and when the user explicitly wants only the first page pass --single-page, and must not then automatically continue paging. Before delivery check data.direction/data.complete/data.pages and meta.pagination |
| Read action items | Single +action-items --id <taskUuid>; batch +detail --ids <uuid1,uuid2> --artifacts todos |
Only when state=known_empty say "no to-dos";ready only then can you read items。unsupported_shape/failed must be non-zero and retain desensitized shape evidence; do not translate it into an empty result. When a DingTalk to-do needs to be created, then switch to dingtalk-todo |
| Archive the summary, keywords, full verbatim transcript, and action items locally | dws minutes +export-pack --id <taskUuid> --output <新相对目录> |
When media is needed add --include-media; it must be proven by published/path/manifest/files that it was written to disk; only creating a directory, a plan, or a filename cannot be called generated |
| Modify or preview the title | dws minutes +update --id <taskUuid> --title "<新标题>" |
For a real modification, execute per Runtime confirmation and read back; when the user only wants a preview, first read basic, then add --dry-run, show "current value → target value" and then stop; do not additionally --yes |
| Overwrite the minutes body | dws minutes +summary --id <taskUuid> --content @<相对文件> |
content is the complete target body, not a partial patch; execute per Runtime confirmation, and protect image references and read back the full text |
| Upload audio/video to generate minutes | dws minutes +upload --file <相对路径> |
A real execution will upload files and create remote minutes, and must follow Runtime confirmation; when the user explicitly wants a flash minutes card, instead use +upload-and-notify, and when an analysis artifact needs to be waited for after upload use +upload-and-analyze |
| Really start, pause, resume, or stop recording | +record-start / +record-pause / +record-resume / +record-stop |
This set of entry points will really execute. When start returns accepted=true, bound=false or controlReady=false , report "accepted but not bound" and stop: do not retry start, and do not use +latest, the first item in the list, or the most recent item by time to guess the ID. To end and wait for artifacts use +record-wrap-up |
| Only preview the recording request, do not actually execute | dws minutes record start --dry-run --format json |
Use the corresponding atomic `minutes record start |
| Generate or continue a mind map | dws minutes +mindmap --id <taskUuid> |
After creation, poll with a bound; on timeout or unknown status retain recovery information, use --resume to continue, and do not create again |
| Generate or continue speaker insights | dws minutes +speaker-insights --id <taskUuid> |
Only state=ready/complete=true completes; pending retains taskId and same account --resume [--task-id <ID>], do not create duplicates; pass the user-specified wait duration to --timeout |
| Current user requests view/download/edit permissions | `dws minutes +apply-permission --id --permission view | download |
| Owner grants or revokes permissions for members | dws minutes +share ... / dws minutes +unshare ... |
First use the address book to resolve names to stable UIDs within the same organization; revocation is a destructive operation. Batch results must retain a per-member ledger and failed items |
Search and list execution capsule
When the user requests "all, every, complete, summarize the entire range", use --page-all：
dws minutes +search --query "<关键词>" --scope all --page-all --format json
dws minutes +search --start "<RFC3339>" --end "<RFC3339>" --scope mine --page-all --format json
dws minutes +list-mine --page-all --format json
dws minutes +list-shared --page-all --format json
dws minutes +list-all --page-all --format json
Only omit --page-allwhen the user explicitly wants the first page, a preview, a sample, or a limited number of pages; faithfully retain completeness and continuation evidence. For N items per page, pass --limit Nin both the first round and continuation pages; do not take the default count and then show only N items as a substitute; for a limited number of pages, use the same leaf's --cursor <真实 next_token> to continue pulling, without expanding to the full set.+list-all of --cursor and --page-all are mutually exclusive. If there is a time window, use +search, because +list-* does not accept --start/--end。
Target and completeness
- Time display and filtering: dates, timezone offsets, weekdays, and boundaries such as "this week" must be calculated by date tools, not mentally or inferred from title dates. Timestamps use the local script format_timestamp.py：
python3 <本Skill目录>/scripts/format_timestamp.py --unit ms --timezone Asia/Shanghai <时间戳1> [时间戳2 ...]; example units/timezones must be replaced with confirmed values (prefer the user-specified timezone, otherwise the known session timezone). The final output should be reused directly, without recalculating weekdays or performing secondary conversions; readable returns with an explicit timezone may be cited directly, and when the unit/timezone is unclear, retain the original value. Relative-week boundaries are calculated separately with a date library; this script only converts timestamps.durationand similar durations are not passed to this script; convert only by local calculation using confirmed units, retain the original value when the unit is unknown, and do not judge content as invalid or recording status based on duration. - Target locking priority:
taskUuid/URL > exact title > title-containing or semantically related candidates. Similar candidates may be shown, but if candidate differences are obvious or multiple candidates are all reasonable, you must stop for disambiguation; incomplete pagination itself is not target ambiguity. - When the user says "first confirm/verify the target", the default requirement is to complete evidence verification using real basic information fields, and it does not automatically become a conversational gate waiting for user reply. When the target is unique, pagination is complete, and all subsequent operations are read-only, complete the required delivery in the same round after showing verification evidence such as title, time, and ownership; pause only when the user explicitly requests "wait for my confirmation before continuing" or there are still multiple reasonable candidates.
- For pure capability, rule, or error explanations with no unique real target, explain directly and do not guess the object; when the user explicitly requests verification and the target is unique, you must actually read it, not merely display a command.
minemeans only those I created,sharedmeans only those shared with me;allmeans the accessible aggregate target. Do not claim that a single backend noLimit endpoint is naturally equal tomine + shared。- A list or transcript can be called "all/complete" only if
data.complete=true. A full request encounteringmeta.pagination.next_tokencontinues; stop only when the token is missing, the cursor stalls/loops, reachespage-limit, or a subsequent page fails, and retain the failure envelope or incomplete evidence. - When the user requests verification or summarization of "these/each/all" hit items, the complete hit set must be covered; usable
dws minutes +detail --ids <uuid1,uuid2> --artifacts basic --format jsonBatch verify, and retain failures item by item. Checking only the first item cannot represent the whole; when the response has no per-item attribution or organization field, state truthfully that it is unavailable, and do not substitute the current profile's organization name for the attribution of each meeting note. - For multiple meeting notes, multiple sources, or cross-product aggregation, preserve per each
taskUuid/source IDrequested/resolved/missing/artifacts/status; when input or required artifacts are missing, treat the whole as partial, still deliver independent results supported by successful content and list missing items; do not reduce the original request or present a subset as the whole, and do not generate conclusions that depend on missing sources for now. - Content summarization must come from each real
summary/transcript/keywords; when there is onlytitle/basic, list metadata only; for other content evidence that does not satisfy user requirements, also list metadata only, and for classification tasks list "to be classified/insufficient evidence", without judging invalidity based on title or duration. The number classified after deduplication by taskUuid plus the number to be classified must equal the target total. partial_success, asynchronouspending, timeout, and unknown write results are not success. Continue according to the recovery handle in the result, and do not replay steps that already succeeded.
Security boundaries
+export-packrecursively cleans recognized signed links/credentials from all text artifacts, replacing signed targets with[signed-url-removed]; if scanning fails, do not publish. At delivery, explainsanitized/redactionCount/sanitizationScope, and do not interpretcomplete=trueas meaning summary images have been saved offline; currentlyofflineImagesComplete=false. Binary media content is outside the scope of text scanning.- Confirm whether the leaf Schema and Runtime gate are authoritative, and do not infer on your own based on "looks like a write operation". The currently required confirmations include
+update、+summary、+record-*、+share/+unshare/+apply-permission、+speaker-replace、+replace-batchin the recommended Golden Route. - For compatibility with the existing public Contract, the corresponding underlying atomic commands retain the historical
not_required; they are only used for explicit low-level control that Shortcut cannot express, and must not be called as a downgrade to bypass the Golden Route's confirmation gate. +uploadand+upload-and-analyze, even if no message is sent, still upload local media and create remote meeting notes, so real execution must follow Runtime confirmation;--dry-runcan still be previewed with zero remote calls. Entries with greater side effects, such as uploading and sending flash note cards, precisely syncing and deleting hotwords, and revoking permissions, continue to be handled separately.+mindmap、+speaker-insightsand+prepare-asrcurrently require confirmation;--resumestill follows the command-level gate of the Shortcut it belongs to. The old+upload --enable-message-cardand+upload-and-analyze --enable-message-cardcontinue as executable compatibility entries and follow the confirmation gate of their respective Shortcut; new calls still recommend+upload-and-notify. The atomicminutes upload create --enable-message-cardand the old--syncare retained only as public migration hints and must not be treated as an executable Golden Route.--dry-runmust return explicit dry-run/request evidence and must not call the remote; recording preview is executed according to the atomic entry above. If any entry refuses dry-run, it must report "preview not supported", and interception or ordinary execution must not be called a successful rehearsal.- When the user explicitly requests "preview only/no actual writing", the task ends after real current-state reading, dry-run planning, and difference delivery; do not continue to request write confirmation, and do not perform a real write and then revert in order to verify the preview.
- Sharing/revoking uses stable member UID; names, phone numbers, or cross-organization IDs must not be used directly as UID; the same target resolution, reading, writing, and verification must use the same profile.
Load on demand
When Golden Route parameters are sufficient, execute directly without pre-reading Reference. For each Case, read at most one most precise file first; for parameter facts, prioritize reading the compact leaf Schema, not the product-level full Catalog.
| Trigger Conditions | Reference |
|---|---|
| ASR hotwords, upload session recovery, complex asynchronous polling, batch permission workflow | Complex Workflows |
| Low-frequency intents such as speaker replacement, batch text replacement, media download, offline export | Local Intents |
| Must resolve to atomic commands, or requires URL/parameter/confirmation facts | Atomic Commands |
Shortest Error Path
- Zero hits, multiple candidates, or unclear ID type: stop and return candidate evidence. If a full request pagination is incomplete but has a valid continuation, continue; stop and return only when the token is missing/stalled/looping, the page limit is reached, or a later page fails, with
data.complete、meta.paginationor failure envelope and other evidence. - Authentication, permission, profile, or confirmation errors: handle according to the corresponding error Reference in
dingtalk-shared; do not change scope, account, or write commands and hope for the best. - Asynchronous timeout or partial success: retain
taskUuid/taskId/sessionId/checkpoint, resume only the incomplete stage; for unknown writes, read back first, and do not automatically retry.
Cross-product boundaries
- Write a minutes summary or verbatim transcript as a document → after reading the real content, switch to
dingtalk-doc。 - Create a minutes action item as a task → after reading the action item, switch to
dingtalk-todo, and handle the assignee according to its identity resolution rules. - Send a summary to a colleague → switch to
dingtalk-chat；+shareonly manages minutes permissions and does not send summary messages. - Create or modify a schedule or meeting room →
dingtalk-calendar; Minutes only handles minutes artifacts and recording control.