dws

DingTalk full-product Skill

Manage DingTalk product capabilities via the dws command.

Command availability is subject to the current dws binary. This document is released with the built-in skill and may lag behind the binary; if dws <cmd> --help does not exist, it means the current version does not expose that command.--help determines the flags actually accepted by Cobra; public base commands and the leaf Schema of the built-in + shortcut (usually using --compact) determine Agent selection, parameter/constraint, and safety-confirmation semantics. Before actual invocation, you can verify with dws <cmd> --help or --dry-run .

Strictly Prohibited (NEVER DO)

• Do not operate DingTalk business data by any means other than the dws command (curl or manually assembling HTTP is prohibited); the only exception is reading the official open.dingtalk.com/llms.txt documentation and generating restricted dws api calls as specified in openapi-explorer.md
• Do not fabricate identifiers such as UUIDs or IDs; they must be extracted from command returns
• Do not guess field names/parameter values; you must query and confirm before operating

Strict Requirements (MUST DO)

• All commands must include --format json to obtain parseable output
• When the user explicitly wants to log in to DingTalk International, Overseas, or the .io region, you must execute dws auth login --intl(for headless environments, also add --device), and must not fall back to the domestic .com；--intl . It is only used for login; subsequent business commands are automatically routed according to the selected profile
• Dangerous operations must first be confirmed with the user, and only after the user agrees add --yes to execute
• A single batch operation must not exceed 30 records
• All commands must strictly follow the parameter format specified in the corresponding product reference documentation (for example: if there is a parameter value, at least one space must separate the parameter and the parameter value)
• Scripts are only for explicitly covered composite tasks: scripts under scripts/ can encapsulate workflows such as AI table bulk import/export, AI application creation polling, writing content after document creation, and DingTalk Drive directory trees; when public + When Shortcut already provides unique target resolution, pagination/partial-failure ledger, and confirmation semantics, prefer Shortcut. Chat history export and bot broadcast have been fully moved down to Runtime and no longer publish compatibility scripts
• Real-time personal event exceptions: ordinary IM messages, reactions, read receipts, and recalls go by default through dws event +listen-im ...; OA approvals, VoIP call invitations, Todos, interactive card callbacks, group lifecycle, explicit raw EventKey, Filter DSL, subscribe_id, or raw envelope use dws event consume ... --flatten. Do not write scripts to poll message history, approval lists, call records, or to-do lists

Principles for using Shortcuts and atomic commands

shortcut is a high-level wrapper for common operations and is suitable for taking priority in carrying user intent; product reference documentation and this skill are responsible for judging intent, risk, cross-product flows, and complex parameters, while CLI help is responsible for declaring the commands actually callable in the current version.

• First route by product reference, intent table, and recipe. When the user intent can be satisfied by a visible Shortcut, prefer to use dws <service> +<verb> ... --format json, and do not hand-write equivalent multi-step atomic commands. Choose a script only when the script explicitly supplements a composite deliverable not covered by Shortcut and its security/integrity contract still applies.
• Public built-in shortcuts also enter the Runtime Schema. Use dws schema --cli-path "<service> +<verb>" --compact --format json to read Agent selection, parameters, cross-parameter constraints, and risk/confirmation; only parameter mapping, interface binding, or provenance auditing should precisely read the full leaf through --jq ;dws shortcut list --service <service> --format json serves only as a lightweight bulk discovery entry.
• Before actually assembling parameters, use leaf help dws <service> +<verb> --help to verify the flags currently accepted by Cobra. Parent-level dws <service> --help can only discover subcommands and cannot replace leaf parameter help.
• When in the shortcut catalog confirmation=user_required , user confirmation must first be obtained, and only after confirmation add --yes；not_required without additional confirmation.
• If a shortcut is not in help / list, switch to the atomic commands, scripts, or standard flows in the product reference; do not guess at + commands that are not shown.
• When a shortcut fails, follow the "error handling" flow by first adding --verbose to recheck; if it still fails, record the specific input, output, trace / endpoint / tool information.

<!-- VISIBLE_SHORTCUTS_OVERVIEW_START -->

Shortcut Overview

The following only counts shortcuts in the current public catalog, without expanding the full details. For a known intent, first choose a unique command by product Skill, intent table, or task reference; when parameters/constraints/security are unclear, read the leaf narrow Schema once. Only when the Schema is unavailable, read the known leaf Help once;unknown flag use the same leaf Help to correct once;unknown command do not check Help; first use the explicit suggestion from the error, otherwise use the explicit compatible entry from the loaded Skill/reference, and if there is still none, report drift and do not enumerate the entire Catalog. Only when existing routing and reference both cannot locate a low-frequency capability, use dws shortcut list --service <service> --format json as the last fallback; do not load the full product Catalog or root/parent Help for a known intent.

Service	shortcut count	multi skill
agoal	5	—
aisearch	1	—
aitable	127	dingtalk-aitable
attendance	11	dingtalk-misc
calendar	27	dingtalk-calendar
chat	102	dingtalk-chat
contact	19	dingtalk-contact
devapp	25	dingtalk-misc
ding	1	dingtalk-misc
doc	49	dingtalk-doc
drive	28	dingtalk-drive
mail	8	dingtalk-mail
minutes	29	dingtalk-minutes
oa	1	dingtalk-misc
pat	1	dingtalk-misc
report	4	dingtalk-misc
sheet	2	dingtalk-misc
todo	21	dingtalk-todo
whiteboard	3	dingtalk-misc
wiki	20	dingtalk-wiki
<!-- VISIBLE_SHORTCUTS_OVERVIEW_END -->

Multi-organization / Multi-account

• dws profile list --format json returns all accounts by default. Automation uses only each item's stable profile=corpId:userId；status/expiresAt/refreshExpAt from the real identity Token; the list does not trigger refresh.
• Input supports corpId:userId、corpId:userName、corpName:userId、corpName:userName, and is also compatible with an individual corpId, unique corpName, and local profile name. Names are used only for input; when names are duplicated, you must switch by the reported error candidates to corpId:userId.
• When only an organization is provided, use the account explicitly recorded by that organization as the isOrgCurrent=true account. For multi-account organizations without a default account, the user must specify the account; it is forbidden to select the first item, most recently logged-in, or most recently used account.
• When --profile is not provided, use the global isCurrent=true account.primaryProfile/isPrimary For compatibility output only, does not participate in selection;previousProfile is only used for profile switch -.
• Cross-organization read/search: deduplicate by corpId ; each organization uses the isOrgCurrent=true of the unique profile. When an organization has multiple accounts and no default account, ask the user first. Before write/send/delete/recall and persistent switching, confirm the target organization and account first.

Product Overview

Product	Purpose	Reference File
agoal	Goal management: strategy decoding, business contracts, scorecards, goal rule cycles, personal goals, goal templates, weekly/monthly report rule submission statistics and follow-ups	agoal.md
aisearch	AI Search & Ask (the preferred general choice for finding people): find people by name/department/position/responsibility/superior/subordinate/mobile number/employee ID dimensions; "who is responsible for XX/the person in charge of XX/a certain matter/a certain project" uniformly goes through this product; does not include specialized HR scenarios such as talent pools/performance/career history (those go to hrbrain）	aisearch.md
aitable	AI Tables: Base/data tables/fields/records/views/attachments/charts/dashboards/import-export/template search/PostgreSQL read-only queries and JOIN	aitable.md
api	OpenAPI escape hatch: official llms.txt hierarchical discovery, only executes enterprise internal application App Token server-side APIs	openapi-explorer.md
attendance	Attendance: clock-in results/clock-in records/attendance group queries/attendance rules/summary statistics/leave types/leave balances (P0 implemented, some management commands are still P1)	attendance.md
calendar	Calendar: calendar list/events/participants/attachments/responses/meeting rooms/free-busy queries/time suggestions	calendar.md
chat	Group chat and bots: search groups/create groups/group member management/change group name/send messages (text/Markdown/images/files)/pull messages/message favorites/@me/special attention/bot mass messaging/one-on-one chat/recall/forward/quote reply/Webhook/bot search	chat.md
contact	Contacts: user queries/departments/roles/rosters (basic fields such as education/family/bank cards/emergency contacts/contracts)/departed employees/special attention, as well as creating enterprises, enterprise accounts, and inviting employees; does not include career history/performance/talent pools (those go to hrbrain）	contact.md
contract	Legal intelligent contracts: ledgers, batch import, listening-note drafting, archiving, projects, counterparties and accounts receivable/payable management	contract.md
devdoc	Open Platform Documentation: Search developer documentation	devdoc.md
ding	DING message: send/recall (in-app/SMS/phone)	ding.md
dingtalk-tag	DingTalk Tag Digital Employee: manage lifecycle, Skill/MCP, execution status and trace, as well as employee Profile, regular local Agent or DSH integration and operation management	dingtalk-tag-index.md
doc	DingTalk Docs: search/browse/read-write/block-level editing/comments/file creation/copy/move/rename/delete/export docx/permission management/media upload and download	doc.md
drive	DingTalk Drive: file list/metadata/folders/upload (two-step)/download/local vs DingTalk Drive folder difference comparison (status)/pull to local (pull)/push to DingTalk Drive (push)/two-way sync (sync)/public internet publishing (publish)/share link password and validity period/node share scope (set-share-scope)	drive.md
hrbrain	Organization Brain: talent pool management/employee profile specialized module queries (metadata/batch data/tags/career history/performance)/structured advanced talent search (raw condition expressions); differs from contact 's basic contacts profile and aisearch 's general semantic people search	hrbrain.md
html	Native HTML files: read/create/full overwrite/partial replace (.html/.htm, DingTalk Drive or document space)	html.md
markdown	Native Markdown files: read/create/compare/full overwrite/partial replace/comment list	markdown.md
minutes	AI Minutes: minutes list/summary/keywords/transcript/to-dos/mind map/speakers/speaker segment summary/hot words/recording control/member permissions/upload	minutes.md
oa	OA Approval: pending/details/approve/reject/cancel/records/initiated/tasks/transfer/comments/cc	oa.md
pat	PAT Behavior Authorization: browser policy/scope preview/one-time, session or permanent authorization	pat.md
report	Reports: create by template/inbox/sent/template view/details/read statistics	report.md
mail	Mail: email address lookup/email search (KQL)/email details/send email	mail.md
sheet	Online spreadsheet (axls): worksheet CRUD/range read-write/CSV batch write/row-column insert-delete/merge/find and replace/filter view/global filter/sort/dropdown list/conditional formatting/floating image/floating chart/template/export xlsx (single-command one-stop)	sheet.md
todo	To-do: create (including priority/due time/recurrence)/query/modify/mark complete/delete	todo.md
wiki	Knowledge base: space creation/details/list/search + member management + knowledge base activity query + space sharing scope (permission set-share-scope)	wiki.md
whiteboard	Content operations for a standalone whiteboard (whiteboard file); or, after having the carrying document nodeId and partId, read and write the graphical content of a whiteboard part embedded in a document; the two types of targets are not converted into each other	whiteboard.md
event	Personal IM/OA/VoIP/Todo/interactive card events: listen to messages, group lifecycle, approval tasks/instances, call invitations, to-do changes and card callbacks, NDJSON output (real-time driven Agent)	event.md

Intent determination decision tree

When the user mentions "AI application/create application/generate system/make tool/management backend/low-code/Yida" → currently no stable product reference (do not guess aiapp commands); explain to the user that the capability has not been released as product documentation, for the multi layout see dingtalk-misc of unsupported-scripts.md When the user mentions "goal management/Agoal/strategic decoding/business contract or field configuration/scorecard/goal rule cycle/personal goals/goal templates/weekly and monthly report rule submission statistics/on time/late/not submitted/follow-up" → agoal; only when filling in, submitting, or querying the body of daily, weekly, or monthly reports does it go through report When the user mentions "legal/intelligent contract/contract ledger/contract archiving/contract project/counterparty/contract payment/draft contract from meeting notes" → contract(querying or processing contract approval instances goes through oa; contract file storage operations go through drive) When the user mentions "find person/search person/who is responsible for XX/the person responsible for a matter/the people on a project/team members/superior/subordinate/find person by employee ID/find person by mobile number" → aisearch(general semantic person finding; if it clearly involves talent pool/performance/career history/structured advanced conditions, go to hrbrain) When the user mentions "sheet/multi-dimensional table/AI table/record/data/view/chart/dashboard/SQL/PostgreSQL/SELECT/JOIN/cross-table associated query" → aitable When the user mentions "attendance/check-in/shift scheduling" → attendance When the user mentions "schedule/calendar/meeting room/appointment/time suggestion" → calendar When the user mentions "group chat/create group/group members/group management/send message/send image message/send file message/send Markdown message/screenshot to DingTalk/forward message/quote reply/@me/specially followed messages/bot send message/Webhook/bot group broadcast/bot one-on-one chat/notification" → chat When the user mentions "contacts/colleague/department/organizational structure/sub-department/how many people in a department/resigned employee/resignation list/resignation roster/roster/basic employee profile (education/family/bank card/emergency contact/contract)/role/supervisor role/administrator role/finance/HR/special follow/starred contact/create enterprise/enterprise account/invite employee/new employee onboarding" → contact(excluding career history/performance/talent pool; those go to hrbrain) User mentions "development/API/invocation error docs" → devdoc User mentions "unwrapped OpenAPI/llms.txt/dws api/Raw API/API escape hatch" → dws api(first check existing product commands, then read the official llms.txt) User mentions "DING/urgent message/phone reminder" → ding User mentions "DingTalk Tag/DEAP digital employee/create and publish digital employee/modify digital employee persona/response mode/securely log in digital employee DWS for A2A and other scenarios/attach Skill or MCP to digital employee/digital employee running status or trace/save local Profile/connect to DSH" → dingtalk-tag, first read dingtalk-tag-index.md User mentions "DingTalk Docs/Cloud Docs/knowledge base/read and write documents/block-level editing/document comments/document copy and move" → doc User mentions "cloud drive/file storage/file upload and download/folder/public internet access/share link password/public validity period" → drive User mentions "talent pool/reserve cadre pool/employee profile metadata or batch module data/career history/performance records/employee tags/organizational brain/structured talent search (advanced condition expression)" → hrbrain(different from aisearch general semantic people search and contact basic contacts profile) User mentions "native HTML file/.html file/create new HTML page/create HTML file/read raw HTML/overwrite HTML/partial replace HTML" → html User mentions "native Markdown file/.md file/read raw Markdown/overwrite Markdown/partial replace Markdown/Markdown comments" → markdown User mentions "Minutes/AI Minutes/meeting minutes/transcription/summary/mind map/speaker/hot words" → minutes User mentions "mailbox/email/send email/receive email/search email/check email/email draft/forward email/reply email/email attachment/cc" → mail User mentions "approval/leave/reimbursement/business trip/overtime/approve/reject/cancel approval" → oa User mentions "PAT authorization/behavior permission/scope authorization/batch authorization/one-time authorization/session authorization/permanent authorization/authorization browser policy" → pat User mentions "log/daily report/weekly report/log statistics/write daily report/submit weekly report/send log/fill in log" → report User mentions "online spreadsheet/DingTalk Sheets/axls/worksheet/cell read and write/merge cells/filter view/export xlsx" → sheet User mentions "to-do/TODO/task reminder/recurring to-do" → todo User mentions "create knowledge base/knowledge base list/search knowledge base space/wiki/team space/knowledge base member management/my documents personal space" → wiki User mentions "whiteboard file/standalone whiteboard/save to whiteboard/canvas/OpenNodes/whiteboard node/connector/full-page whiteboard rebuild" → whiteboard. User wants to insert, locate, or delete a whiteboard card in a document → doc whiteboard; only reading and writing the embedded whiteboard graphic content of an existing host document nodeId and partId goes through whiteboard. When the embedded target identity is missing, stop and complete it; do not convert it into an independent whiteboard. When the user mentions "listen for someone @-ing me / listen to single chats or group messages / listen to all single chats or group messages / listen to messages sent by a specific person / listen for message read receipts / listen for message recalls / listen for message sticker reactions or emoji reactions / subscribe to personal IM events / receive DingTalk events in real time / listen and auto-reply to messages / drive an Agent to process messages" → event +listen-im; group member join/leave, group rename/disband, or explicit original EventKey/Filter DSL → event consume When the user mentions "listen for tasks awaiting my approval / listen for approval task creation, completion, or transfer / listen for approval form initiation or termination / listen for completion of approvals I initiated / listen for approval instance completion / subscribe to OA events / event consume user_oa_approval_" → event consume When the user mentions "notify me when I receive a voice call invitation / listen for VoIP incoming calls / subscribe to user_voip_call_receive_invite" → event consume When the user mentions "listen for to-do creation/update/deletion / listen for to-dos assigned to me / subscribe to Todo events / event consume user_todo_task_" → event consume, use by role --role-types When the user mentions "interactive card callback / listen for card actions / subscribe to user_card_action_triggered" → event consume user_card_action_triggered --flatten -f ndjson

For ordinary messages, reactions, read receipts, and recall listening, prefer expressing the target with a single dws event +listen-im process; split different users, different groups, or different filter conditions into independent processes. Only advanced event control generates dws event consume <event_key> [event_key...] --flatten.

Key distinction: aitable (data table) vs todo (to-do task) Key distinction: report (DingTalk log/daily and weekly reports) vs todo (to-do task) Key distinction: chat send-by-bot (send messages as a bot identity) vs send-by-webhook (custom bot Webhook alert) Key distinction: doc (online rich-text document/adoc) vs markdown (native .md plain text file) vs html (native .html file read/write) vs drive (general-purpose file storage and transfer) Key distinction: contact (basic address book profile: education/family/bank card/emergency contact/contract/department role) vs aisearch person (general semantic people search: who is responsible/superior/subordinate/multi-dimensional fuzzy search) vs hrbrain (talent pool/employee profile specialized module data/career history/performance/structured advanced talent search) Key distinction: oa tasks (approval taskId, used for approve/reject) vs oa list-pending (inbox processInstanceId, used for viewing) Key distinction: oa (query or operate on approvals) vs event user_oa_approval_* (persistent connection listening for the current user's approval events) Key distinction: todo (query or operate on to-dos) vs event user_todo_task_* (persistent connection listening for the current user's to-do events)

For more easily confused scenarios, see intent-guide.md

Dangerous Operation Confirmation

The following operations are irreversible or high-impact. Before executing them, you must first show the user an operation summary and obtain explicit consent; only after consent add --yes to execute.

Product	Command	Description
aitable	base delete	Delete an entire AI table, including all data tables and records
aitable	table delete	Delete a data table (including all fields/views/records)
aitable	field delete	Delete a field (all values in that column are cleared simultaneously)
aitable	view delete	Delete a view
aitable	record delete	Delete records (batch supported)
aitable	chart delete / dashboard delete	Delete a chart/dashboard
calendar	event delete	Delete a schedule; all participants are canceled simultaneously
calendar	participant delete	Remove a schedule participant
calendar	room delete	Cancel a meeting room reservation
chat	group members remove	Remove group member
chat	message recall-by-bot	Recall messages already sent by the bot
doc	delete	Delete an entire document/file to the recycle bin (unlike block delete , this command deletes the entire node)
doc	block delete	Delete a document block (irrecoverable);--block-id supports deleting multiple at once, separated by commas
doc	permission update	Modify collaborator permissions (downgrading may affect others' access)
ding	message recall	Recall a DING message already sent
dingtalk-tag	manage save-draft / manage publish / manage delete / capability skill create / capability mcp create	Overwrite or publish a digital employee, delete a digital employee, create a capability resource; subject to the confirmation of the leaf Schema
oa	approval revoke	Revoke an approval instance you initiated
oa	approval reject	Reject a pending approval (an explicit reason is required)
todo	task delete	Delete a to-do
minutes	replace-text	Batch replace transcriptions and summaries across the full text

Confirmation process

Step 1 → 展示操作摘要（操作类型 + 目标对象 + 影响范围）
Step 2 → 用户明确回复确认（如 "确认" / "好的"）
Step 3 → 加 --yes 执行命令

Recognition and retry protocol for the confirmation gate

In a non-interactive environment (Agent/CI, stdin is not a TTY), when a write command does not include --yes , the CLI does not print an interactive prompt and instead fails directly with a structured error. How to recognize it:

• In the --format json output (or stderr), error.reason == "confirmation_required", and the error message contains "the current environment cannot confirm interactively"

When encountering confirmation_required , handle it according to the following protocol:

1. Do not give up as if it were an ordinary error: show the command, risk level (write / high-risk-write) and key parameters to the user, and clearly state that this is a write/high-risk operation.
2. The user explicitly agrees → append --yes to the end of the original command and retry (without changing any business parameters).
3. The user rejects → terminate; do not rewrite parameters to bypass the gate.
4. If you want the user to review the specific request first: add --dry-run and retry—it does not trigger the confirmation gate and will output a complete call preview (invocation.params). After the user confirms the preview, switch to --yes to execute.

Prohibited:

• Upon seeing confirmation_required , automatically appending --yes and silently retrying without the user's consent (equivalent to disabling the gate).
• Treating confirmation_required as a network/permission error and handling or retrying it.
• Using echo yes | dws ... or other pipe methods to feed answers instead of --yes(pipe answers will technically be accepted, but this violates the design intent of making the user explicitly aware).

Core process

As an intelligent assistant, your primary task is to understand the user's true and complete intent, rather than simply executing commands. Before choosing dws 's product commands, you must strictly follow the four-step process below:

1. URL pre-check: when the input contains alidocs.dingtalk.com URL, multiple path formats exist under that domain (/i/nodes/...、/i/p/...、/spreadsheetv2/...、/document/edit|preview?dentryKey=... , etc.), and each has a different handling process. You must first read the "alidocs URL triage decision" in url-patterns.md, identify the URL type according to the rules therein, and then choose the corresponding product. When it contains shanji.dingtalk.com URL, route directly to minutes. Once the URL is recognized, proceed directly to the corresponding product workflow; no subsequent steps are required.
2. Intent classification: First, determine which category the core verb/action of the user instruction belongs to. This is more important than focusing on nouns.
3. Ambiguity handling and information follow-up: If the user instruction is vague or contains keywords for multiple products, guessing is strictly prohibited. You must proactively ask the user follow-up questions to clarify the intent. This is your core value as an intelligent assistant rather than a command executor.
4. Precise product mapping: After completing the first two steps, once the intent is clear, refer to the product overview and the intent judgment decision tree to select the product.
5. Task-minimized reading: For known high-frequency intents, directly use the unique command already provided in this Skill or the product reference, without preloading the complete product reference file; only when routing, parameters, or exception recovery genuinely require it, read the corresponding product or task reference.

Command Discovery (Progressive Schema Query + --help as Complements)

Progressive Schema Query (First Choice for Agents Selecting Commands)

dws schema embeds the structured contract of the current binary's public command surface. When an Agent selects commands and reads parameter mappings/constraints and security semantics, it must prioritize progressive querying of the leaf Schema; before actually assembling execution parameters, use --help to confirm the flags currently accepted by Cobra:

This section applies both to basic/atomic commands and to public built-in + shortcuts. User-defined or non-public shortcuts do not enter the release Schema; whether they are executable is still subject to the current Cobra help.

Exception for known command paths: When this Skill, the product intent table, or the task reference has already provided the exact CLI path, do not query the product-level/group-level Schema again, and do not call the complete Shortcut Catalog; execute directly. Only when parameters, constraints, or security semantics are uncertain should the leaf Schema of that command be read, and only when the current Cobra flags are uncertain should the leaf Help be read as a supplement.

Stable command identity, the main CLI path, and aliases are precisely bound by the leaf ContractFinal.Identity to the real Cobra tree. Agents should not read Catalog files, native annotations, or other generated JSON to re-infer commands; all runtime queries are based on the Schema projection delivered by the current binary.

# 第 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 usage boundary (mandatory):--all will return the complete parameters, constraints, and security semantics of each tool, and the output volume is very large. Use it only when the user explicitly requests a full export, or when performing CI, Catalog audits, or a parameter-loss-prevention baseline. For ordinary business tasks, it is strictly prohibited to use --all for command discovery, and do not inject the full results directly into the Agent context; you must query progressively as "product overview → product/group → leaf". A complete compatibility baseline must use the untrimmed schema --all；schema --all --compact will remove provenance and interface mapping fields, and must not be used as a complete baseline.

For the same tool, omitting --compact the full leaf and the --all entry are the same ToolSpec contract; the compact leaf only performs a display projection and does not re-parse semantics. Alias queries must not rewrite or guess parameters based on the alias. If content differences are observed in the same view, they should be reported as contract drift, rather than choosing one of them to continue execution.

--compact Agent mode uses a positive field allowlist. Retains cli_path、canonical_path、description、effect、risk、confirmation、interface_mode、availability、interface_reason、parameters(including type/required/description/default/enum）、constraints、examples、use_when、avoid_when; newly added full/audit fields will not automatically leak into the Agent context. It intentionally does not return interface_ref, the parameter property/interface_type , and provenance; when checking these mapping facts, use the full leaf together with --jq for precise projection.

--compact is the Schema display capability. The current version supports it; when receiving it while remaining compatible with older binaries, unknown_flag: --compact, just remove --compact and rerun the same Schema query. Do not conclude from this that the leaf does not exist, and do not switch to using Schema to query business data.

Schema field quick reference

// 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 → must first confirm with the user before adding --yes; do not rewrite the final confirmation winner on your own based on the value of effect or risk - availability=unavailable → do not execute this tool; explain to the user that interface_reason。interface_mode only describes the implementation mechanism and cannot override availability
• parameters.<flag>.required=true → the Agent should provide this parameter; whether Cobra hard-rejects it is governed by --help/the actual command contract
• parameters.<flag>.cli_required=true → Cobra marks this flag as hard-required
• constraints.require_together → the listed flags must be provided together

Boundaries between Schema, Help, and business data

Information	Source of truth
Whether a command exists and which flags the current Cobra accepts	dws <cli_path> --help
Agent selection, CLI parameters/required/combination constraints, risk/confirmation (atomic/basic commands)	dws schema "<cli_path>" --compact
CLI↔RPC parameter mapping, interface binding, or provenance auditing	full leaf together with --jq / --fields for exact projection; do not inject the entire full leaf into the Agent context
shortcut parameters, combination constraints, risk/confirmation, examples	prefer the known path dws schema --cli-path "<service> +<shortcut>" --compact --format json; use the complete shortcut list only as a last fallback when low-frequency capabilities cannot be located
Human-readable usage	dws <cli_path> --help
Actual data such as documents, files, schedules, and messages in DingTalk	actually execute the corresponding read / search / list command

A conflict between Schema and Help is contract drift; do not silently guess or arbitrarily splice fields from both sides:

• For execution parameters, use only the flags accepted by Cobra/Help, and report the drift.
• In case of a security-semantics conflict, do not choose the more permissive behavior; first adopt the more conservative confirmation method, and if a safe execution method cannot be confirmed, stop and report.
• The leaf Schema is the contract already resolved according to source precedence; do not rewrite the winner on your own based on how "strict" a value is. Only when it is found to conflict with Help/the actual execution contract should you enter the above security degradation.

dws schema only queries the command contract and does not search DingTalk documents or business data. After completing command discovery, you must continue to execute the real command, for example dws doc read、dws drive search; do not treat Schema query results as business query results.

Helper-only and local Cobra commands

dev.* includes a helper-only execution surface, in which remote helpers not included in pinned metadata are marked as compositeand cannot be disguised as local。event list / event schema reads built-in directory and payload definitions, and belongs to local；event consume / event status / event stop while orchestrating the remote personal subscription control plane and local bus/consume, and belongs to composite. The implementation sources differ, but this does not change the unified query boundary: commands entering the global dws schema must be declared and collected by the leaf ContractFinal.Identity , and projected by the same ToolSpec to the leaf, product/group,--all and Catalog. Do not use Cobra temporary composite results as a second Schema data path.

Events need to distinguish between two kinds of Schema:dws event schema <event_key> --flatten queries the top-level business fields that the Agent needs to consume;dws schema "event consume" --compact Query CLI command parameters. The former is the real business command, while the latter only reads the final embedded SchemaRegistry; they cannot substitute for each other.

source indicates the source of the final command identity, not the runtime backing; the helper/local/MCP implementation mechanism reads interface_mode、availability and provenance, do not assume dev.* must be source=mcp:<server>, and do not assume that a local command must be source=cobra.

Error handling

1. First read the JSON error's retryable、retry_after_seconds、next_retry_at、hint and actions; only when it is explicitly retryable=true should you perform one bounded retry according to the server's pacing. When retry semantics are missing, add --verbose to collect diagnostics and then stop
2. If it still fails, report the complete error information to the user; do not attempt alternative solutions on your own
3. For authentication failures, refer to the authentication section in global-reference.md for handling
4. For high-frequency errors for each product and troubleshooting processes, see error-codes.md
5. When encountering "known unsupported operations" listed in capability-limits.md, directly tell the user it is not supported and suggest performing the operation in the DingTalk client; do not retry or work around it

Detailed references (read as needed)

• references/products/ — Detailed reference for each product's commands (the flags accepted by Cobra are based on the leaf --help ; the Agent mapping/constraints/security semantics of public base commands and built-in shortcuts are based on the leaf Schema)
• references/products/dingtalk-tag/ — DingTalk Tag digital employee lifecycle, capability resources, and execution queries
• references/intent-guide.md — Intent routing guide (comparison of easily confused scenarios)
• references/url-patterns.md — URL format specification + alidocs URL routing decision and type detection process (including DingTalk Drive document/edit|preview?dentryKey= links)
• references/global-reference.md — Global flags, authentication, output formats
• references/field-rules.md — AI Table field type rules
• references/error-codes.md — Error codes + debugging process
• scripts/ — Batch/composite operation scripts for each product (AI Table batch import/export, calendar, bot messages, contacts, attendance, logs, to-dos, document creation and writing, DingTalk Drive directory tree, etc.)
• references/products/aitable/ — AI Table detailed chapters (cell values/field properties/formulas/filtering and sorting/import and export/dashboards/record CRUD/error recovery/best practices)
• references/products/aitable-record-ops.md — Specialized explanation of AI Table record operations
• references/products/pat.md — PAT browser policy, behavior scope preview, and authorization security requirements
• references/capability-limits.md — Known capability limits (doc/aitable/chat/minutes; when encountered, directly tell the user it is not supported)
• references/best_practices/ — Action guide for recipes across all scenarios (11 numbered scenarios + lite quick reference)
  • 01-messaging.md — Messaging
  • 02-task.md — Task management (todo)
  • 03-meeting.md — Meeting scheduling (calendar + meeting rooms)
  • 04-document.md — Document scenarios (write-doc / search-docs / migrate-doc / update-doc-section / doc-to-message / delete-old-doc / export-doc-as-docx / grant-doc-access / insert-image-to-doc / template-based-generation, etc.)
  • 05-reporting.md — Work reporting (DingTalk logs / document weekly report routing)
  • 06-data-analytics.md — AI table data analysis (read-aitable / generate-data-report / create-aitable-record / update-aitable-record / export-aitable-to-xlsx / primary-doc-from-record, etc.)
  • 07-minutes.md — Minutes and post-meeting
  • 08-directory.md — Contacts (organizational structure)
  • 09-mail.md — Mail
  • 10-minutes-speaker-match.md — Intelligent speaker matching for minutes
  • 11-minutes-speaker-correct.md — Speaker recognition and labeling for minutes
  • lite-recipes.md — Lite Recipe quick reference (execute directly once the core flow is determined to be lite)
  • _common/conventions.md — General conventions such as batch queries, multi-source parallel collection, and field terminology
  • _common/recipe-conventions.md — Recipe meta-conventions

When an Agent uses OpenNodes to create a whiteboard with content, it must first execute whiteboard render, display the SVG and rendering prompt, then stop and wait for the user to explicitly confirm the current version before creating; after modification, re-render and confirm again. It must not skip the preview and create directly; the initial creation request and the post-creation read-back cannot replace preview confirmation. See the creation flow at the whiteboard entry point for details; blank creation, direct template application, and updates to existing whiteboards are not extended by this rule.

When an Agent updates existing whiteboard content (append, modify, delete, clear), it must first execute whiteboard +diff, display the differences and risks, then stop and wait for the user to explicitly confirm the current differences, then use the same sourceDigest to execute +update; when diff fails or there is a blocker, it must not write. It must not switch to atomic update to bypass this; render, dry-run, and read-back after writing cannot replace diff. See the update flow at the whiteboard entry point for details. Updates set only one user confirmation point: first complete the required render and the necessary +diff, then display the visual preview (if any), differences, and coverage impact together and confirm once; do not ask for confirmation after render first, and then ask again after performing diff once approved. Once the same target, revision, source, and mode have been confirmed, submit directly; re-confirm only when these contents change or undisclosed material risks appear.