dingtalk-chat

Group chat/messages

Minimal DWS execution contract

• Use only dws; for structured reading add --format json, judge by the actual return.
• Call known commands directly; when parameters/constraints/security are unclear, check the leaf narrow Schema. Only when Schema is unavailable, read a known leaf Help once;unknown flag correct once using the same leaf Help.unknown command Do not check Help: prefer explicit suggestions in the error, then explicit compatible entry points in already loaded Skill/reference; if neither exists, report drift and stop, all-Catalog is forbidden. Low-frequency reference does not default to Help, root/parent/product Help is forbidden. After discovery, must execute or explain the blockage.
• Do not guess commands/flags/fields/IDs/accounts/business facts; IDs come from real returns. For zero hits/multiple candidates/unclear type in the target, disambiguate first; use contract defaults only for optional time/display scope, stop when required information is missing.
• Parse/read/write the same profile, IDs do not cross organizations. For multiple accounts use only the unique isOrgCurrent=true; otherwise user-specified, choosing the first item, most recent login, or most recently used account is forbidden.
• Do not output/record token, refresh token, appSecret, webhook token; do not request them when authentication is already injected.
• Writes must match explicit intent; confirmation is subject to the final Runtime gate/Schema, only after confirmation add --yes。
• After writing, verify the result, do not claim success based on exit code. Exit must be the final reply, distinguishing completed, partial, blocked, pending confirmation, failed; preserve existing data and complete/hasMore/stopReason/failures。
• Timestamps are displayed in the session time zone, preserve the original value when necessary.
• For authentication/permission/profile/confirmation/unknown errors, only read dingtalk-shared the corresponding reference, consecutively guessing alternative commands is forbidden.

Object and routing boundaries

• openConversationId is a conversation,messageId/openMessageId is a message,openTaskId is a send task, they must not be mixed up.
• Conversation grouping/classification uses category, group chat/chat group uses chat group; the conversation list has no body text, for summaries/statistics read messages. Pin/Top/Favorite are not classification.

Shortcut discovery (Shortcut-first)

Select Shortcut by Golden Route/reference; only when underlying fields are missing use atomic, low-frequency goes through reference/Catalog.

For parameters check dws schema --cli-path "chat <leaf>" --compact --jq '{cli_path,parameters,constraints,confirmation}' -f json; only when needed and already published result check outcomes/pagination, for field level check again data_schema; do not infer from Help/examples when missing. Only when Schema is unavailable, read a known leaf Help once;unknown flag correct once using the same leaf Help.unknown command Help is forbidden: error suggestion → explicit entry point in already loaded Skill/reference; if neither exists, report drift. All-Catalog/root/parent/product Help is forbidden; low-frequency reference does not default to Help.

Golden Route

User endpoint	Only recommended entry	Key boundary
Read specified group chat/single chat	dws chat +chat-messages --no-reactions	Add for all --page-all
Filter by keyword/sender/@/type/reaction	dws chat +search-msg(for reaction add --has-reactions）	default 7 days; for scope use --start/--end
Cross-conversation reading/summarizing/statistics	dws chat message list-all --start <开始> --end <结束> --page-all --no-reactions	Do not list conversations first and loop group by group
Active conversations after time	dws chat +recent-conversations --start <时间>	Summary; check complete；+active-conversations only compatible
View @my messages	dws chat +at-me [--group <群名或ID>] --page-all --no-reactions	If no group is specified, cross-conversation; default 7 days
View unread messages	dws chat +unread-chats	When body is needed, read messages along CID
Batch-fetch details for known message IDs	dws chat +messages-mget	See leaf Schema; preserve conversation context
Send text/Markdown by name	dws chat +dm --to <姓名> --content <内容>	Unique resolution; stop on multiple candidates
Send text/Markdown by group name/ID	dws chat +send-to-group --group <群名或ID> --content <内容>	Stop on multiple candidates
File/Bot/Webhook/complex @	dws chat +messages-send	Bot multi-group check item-by-item ledger
All conversations	dws chat +conversation-list --page-all	Includes group chats/one-on-one chats, not body
Check groups joined/managed	+my-groups --page-all / +chat-list-mine	The latter has no --page-all; flag does not cross leaf
Search groups or view all members	+chat-search --query <词> / +chat-members-list --group <群名或ID>	Stop on multiple candidates; check buckets/completeness
Check group profile/Bot/invite link	+conversation-info / +chat-bots / +chat-invite-url	Read-only
Create/clean up temporary group	dws chat +chat-create --name <名称> --member-query <姓名列表> → save CID → +chat-dismiss --group <cid>	For known ID use --users; cleanup must be confirmed and verified
Modify group profile/settings/mute/admins	+chat-update / +chat-update-settings / +chat-mute / +chat-mute-member / +chat-set-admin	Use real group/user ID; read back after writing
Manage group identity	Read group-admin role family	Role CRUD, member bind/unbind/query; do not switch atomic, read back after writing
List conversations in category	dws chat +category-list-conversations --category-id <ID>	Category ≠ group; get ID first
Quote reply	dws chat +messages-reply	Use real message/CID; unknown delivery status is not success
Recall/forward	+messages-recall；+messages-forward / +messages-combine-forward / +messages-forward-topic	Do not copy body to impersonate native forward
Pin/Message Top/Favorite	+messages-set-pin / +messages-unset-pin；+messages-set-top / +messages-unset-top；+flag-create / +flag-cancel	Objects are not interchangeable; verify with corresponding query
Add/remove reaction	+messages-add-emoji / +messages-remove-emoji	Extended action read message-actions
Conversation pin/mute/hide	chat-conversation	Use real CID; conversation Top is not message Top
Read/unread/clear red dot/clear	+conversation-mark-read / +conversation-mark-unread / +conversation-clear-red-point / +conversation-clear-all-red-point / +conversation-clear-messages	Read requires message ID; clear per Runtime confirmation
Download message resource	Query add --download-resources --output-dir <目录>; if reference exists use +messages-resource-download	Do not guess ID; keep ledger; do not deliver temporary URL

Secondary: Thread +thread-replies; pin dws chat +conversation-list-top; upload conversation-file upload; IM events go through dingtalk-event。

Key result semantics

• Query retains scope, count, completeness, stop reason, failure/download ledger; incomplete must not be called success. Messages only --page-all paginate, return bounded partial when budget reached.
• Local image only sends inline image if it already has mediaId , otherwise sends file; upload only without sending use conversation-file upload。
• Sub-message uses its own messageId; only inherit parent conversationId when CID is missing. Write operations pass ID along real result.

Write lifecycle

• Multi-step writes first validate target, limits, content, confirmation, then execute serially along stable ID and verify; do not truncate or switch target. Temporary resources retain ID/stage, on failure only perform authorized cleanup.

Context budget

• Read Skill/Reference/leaf Schema/Help once each; if Schema already provides parameters, Help is forbidden. Summary/statistics/retrieval default --no-reactionsResource download is explicitly opt-in only.
• Use --fields/--jq/limit/compact to preview; head is prohibited from truncating JSON; large bodies go to files, retaining ID, body evidence, next-step fields, integrity, and failure items.

Load on demand

Tasks ≤ 1

Scenario	Reference
Message	Query / Action / Resource
Group	Read / Governance
Session/Bot	Session / Bot
Combination/Topic/Emoji/Card	Combination / Topic / Emoji / Card/A2UI
Result/Other Atomic Capabilities	contracts / chat

Shortest Error Path

1. Zero matches/multiple candidates: stop writing and disambiguate; defaulting to the first item is prohibited.
2. If parameters/confirmation are unclear, check the leaf Schema; only if the Schema is unavailable, check the known leaf Help.unknown flag Use the same leaf Help to correct once;unknown command Do not check Help: first use the explicit suggestion from the error, then use the explicit compatible entry point from the already loaded Skill/reference; if none exists, report drift and stop; the full Catalog is prohibited.
3. Only retryable=true retry once with the original command; stop on API/internal/MCP, post-write inconsistency, or non-retryability, and do not switch Shortcut/atomic. Retain the Trace ID, completed/to-be-cleaned-up items, and provide a final reply;confirmation_required wait for user confirmation, do not supplement --yes。