dingtalk-chat

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

群聊/消息

Group Chats/Messages

最小 DWS 执行契约

Minimal DWS Execution Contract

只用
```
dws
```
；结构化读取加
```
--format json
```
，按真实返回判断。
已知命令直调；参数/约束/安全不明查 leaf 窄 Schema。Schema 不可用才读已知 leaf Help 一次；
```
unknown flag
```
用同 leaf Help 修正一次。
```
unknown command
```
不查 Help：优先错误中的明确 suggestion，其次已加载 Skill/reference 中的明确兼容入口；均无则报漂移并停，禁全 Catalog。低频 reference 不默认 Help，禁 root/parent/product Help。发现后必须执行或说明阻塞。
不猜命令/flag/字段/ID/账号/业务事实；ID 来自真实返回。目标零命中/多候选/类型不明先消歧；仅可选时间/展示范围用契约默认，缺必需信息即停。
解析/读/写同一 profile，ID 不跨组织。多账号只用唯一
```
isOrgCurrent=true
```
；否则用户指定，禁止选择第一项、最近登录或最近使用账号。
不输出/记录 token、refresh token、appSecret、webhook token；已注入认证时不索要。
写须符合明确意图；确认以最终 Runtime gate/Schema 为准，确认后才加
```
--yes
```
。
写后验证结果，不凭退出码宣称成功。退出须最终答复，区分完成、部分、阻塞、待确认、失败；保留已有数据及
```
complete/hasMore/stopReason/failures
```
。
时间戳按会话时区展示，必要时保留原值。
认证/权限/profile/confirmation/未知错误只读
```
dingtalk-shared
```
对应 reference，禁连续猜替代命令。

Use only
```
dws
```
; add
```
--format json
```
for structured reads and judge by the actual return.
Call known commands directly; if parameters/constraints/safety are unclear, consult the leaf's narrow Schema. Only if Schema is unavailable, read the known leaf Help once; for
```
unknown flag
```
, correct once using the same leaf Help. For
```
unknown command
```
, do not consult Help: first use the explicit suggestion in the error, then the explicit compatible entry in the loaded Skill/reference; if neither exists, report drift and stop; full Catalog is prohibited. Low-frequency references do not default to Help; root/parent/product Help is prohibited. Once found, you must execute or explain the blockage.
Do not guess commands/flags/fields/IDs/accounts/business facts; IDs come from real returns. If the target has zero hits/multiple candidates/unknown type, disambiguate first; only optional time/display scope use contract defaults; stop when required information is missing.
Resolve/read/write the same profile; IDs do not cross organizations. For multiple accounts, use only the unique
```
isOrgCurrent=true
```
; otherwise use the user-specified account, and do not select the first item, last login, or most recently used account.
Do not output/record token, refresh token, appSecret, webhook token; do not ask for credentials when authentication is already injected.
Writes must match the explicit intent; confirmation follows the final Runtime gate/Schema; add
```
--yes
```
only after confirmation.
Verify after writes; do not claim success based on the exit code alone. Final replies must distinguish completed, partial, blocked, pending confirmation, failed; preserve existing data and
```
complete/hasMore/stopReason/failures
```
.
Timestamps are displayed in the session timezone; preserve original values when necessary.
For authentication/permission/profile/confirmation/unknown errors, only read the corresponding reference in
```
dingtalk-shared
```
; do not keep guessing substitute commands.

对象与路由边界

Object and Routing Boundaries

```
openConversationId
```
是会话，
```
messageId/openMessageId
```
是消息，
```
openTaskId
```
是发送任务，不可混用。
会话分组/分类走
```
category
```
，群聊/聊天群走
```
chat group
```
；会话列表无正文，总结/统计读消息。Pin/Top/Favorite 不是分类。

```
openConversationId
```
is a conversation,
```
messageId/openMessageId
```
is a message,
```
openTaskId
```
is a send task; do not mix them.
Conversation grouping/categorization uses
```
category
```
; group chats/chat groups use
```
chat group
```
; the conversation list has no body, so read messages for summaries/statistics. Pin/Top/Favorite are not categories.

Shortcut 发现（Shortcut-first）

Shortcut Discovery (Shortcut-first)

按 Golden Route/reference 选 Shortcut；仅缺底层字段用 atomic，低频走 reference/Catalog。

参数查

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

；仅需且已发布

result

时查 outcomes/pagination，字段级再查

data_schema

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

unknown flag

用同 leaf Help 修正一次。

unknown command

禁 Help：错误 suggestion → 已加载 Skill/reference 明确入口；均无则报漂移。禁全 Catalog/root/parent/product Help；低频 reference 不默认 Help。

Choose Shortcuts per the Golden Route/reference; use atomic only when underlying fields are missing; low-frequency operations go to reference/Catalog.

Check parameters via

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

; when only

result

is needed and already published, check outcomes/pagination; for field-level details, check

data_schema

; missing fields must not be inferred from Help/examples. Only if Schema is unavailable, read the known leaf Help once;

unknown flag

is corrected once with the same leaf Help. For

unknown command

, Help is prohibited: error suggestion -> explicit entry in loaded Skill/reference; if none, report drift. Full Catalog/root/parent/product Help is prohibited; low-frequency references do not default to Help.

Golden Route

用户终点	唯一推荐入口	关键边界
<!-- dws-intent: chat.read.conversation -->读取指定群聊/单聊	`dws chat +chat-messages --no-reactions`	全部时加 `--page-all`
<!-- dws-intent: chat.search.filtered --><!-- dws-intent: chat.read.reactions -->按关键词/发送者/@/类型/reaction 过滤	`dws chat +search-msg` （reaction 加 `--has-reactions` ）	默认 7 天；范围用 `--start/--end`
跨会话读取/总结/统计	`dws chat message list-all --start <开始> --end <结束> --page-all --no-reactions`	不先列会话逐群循环
<!-- dws-intent: chat.conversation.active-since -->时间后活跃会话	`dws chat +recent-conversations --start <时间>`	摘要；查 `complete` ； `+active-conversations` 仅兼容
查看 @我的消息	`dws chat +at-me [--group <群名或ID>] --page-all --no-reactions`	未指定群则跨会话；默认 7 天
查看未读消息	`dws chat +unread-chats`	需正文时沿 CID 读消息
已知消息 ID 批量取详情	`dws chat +messages-mget`	看 leaf Schema；保留会话上下文
<!-- dws-intent: chat.send.dm -->按姓名发文本/Markdown	`dws chat +dm --to <姓名> --content <内容>`	唯一解析；多候选停止
<!-- dws-intent: chat.send.group -->按群名/ID 发文本/Markdown	`dws chat +send-to-group --group <群名或ID> --content <内容>`	多候选停止
<!-- dws-intent: chat.send.advanced -->文件/Bot/Webhook/复杂 @	`dws chat +messages-send`	Bot 多群检查逐项 ledger
全部会话	`dws chat +conversation-list --page-all`	含群聊/单聊，非正文
查加入/管理的群	`+my-groups --page-all` / `+chat-list-mine`	后者无 `--page-all` ；flag 不跨 leaf
搜群或查看全部成员	`+chat-search --query <词>` / `+chat-members-list --group <群名或ID>`	多候选停止；检查 buckets/完整性
查群资料/Bot/邀请链接	`+conversation-info` / `+chat-bots` / `+chat-invite-url`	只读
<!-- dws-intent: chat.create.group -->创建/清理临时群	`dws chat +chat-create --name <名称> --member-query <姓名列表>` → 保存 CID → `+chat-dismiss --group <cid>`	已知 ID 用 `--users` ；清理须确认、验证
改群资料/设置/禁言/管理员	`+chat-update` / `+chat-update-settings` / `+chat-mute` / `+chat-mute-member` / `+chat-set-admin`	用真实群/用户 ID；写后读回
管理群身份	读 group-admin 角色 family	角色 CRUD、成员绑定/解绑/查询；不切 atomic，写后回读
<!-- dws-intent: chat.category.list-conversations -->列分类内会话	`dws chat +category-list-conversations --category-id <ID>`	分类≠群；先取 ID
<!-- dws-intent: chat.reply.quote -->引用回复	`dws chat +messages-reply`	用真实消息/CID；未知投递状态非成功
撤回/转发	`+messages-recall` ； `+messages-forward` / `+messages-combine-forward` / `+messages-forward-topic`	不复制正文冒充原生转发
Pin/消息 Top/Favorite	`+messages-set-pin` / `+messages-unset-pin` ； `+messages-set-top` / `+messages-unset-top` ； `+flag-create` / `+flag-cancel`	对象互不替代；用对应查询验证
添加/移除 reaction	`+messages-add-emoji` / `+messages-remove-emoji`	扩展动作读 `message-actions`
会话置顶/免打扰/隐藏	chat-conversation	用真实 CID；会话 Top 非消息 Top
已读/未读/清红点/清空	`+conversation-mark-read` / `+conversation-mark-unread` / `+conversation-clear-red-point` / `+conversation-clear-all-red-point` / `+conversation-clear-messages`	已读需消息 ID；清空按 Runtime 确认
下载消息资源	查询加 `--download-resources --output-dir <目录>` ；已有引用用 `+messages-resource-download`	不猜 ID；保留 ledger；临时 URL 不交付

次级：Thread

+thread-replies

；置顶

dws chat +conversation-list-top

；上传

conversation-file upload

；IM 事件走

dingtalk-event

。

User endpoint	Only recommended entry	Key boundaries
<!-- dws-intent: chat.read.conversation -->Read a specific group chat/direct chat	`dws chat +chat-messages --no-reactions`	Add `--page-all` for all
<!-- dws-intent: chat.search.filtered --><!-- dws-intent: chat.read.reactions -->Filter by keyword/sender/@/type/reaction	`dws chat +search-msg` (add `--has-reactions` for reactions)	Default 7 days; use `--start/--end` for range
Cross-conversation read/summary/statistics	`dws chat message list-all --start <start> --end <end> --page-all --no-reactions`	Do not list conversations first and loop group by group
<!-- dws-intent: chat.conversation.active-since -->Conversations active since a time	`dws chat +recent-conversations --start <time>`	Summary; check `complete` ; `+active-conversations` is compatibility-only
View messages @ me	`dws chat +at-me [--group <group name or ID>] --page-all --no-reactions`	Cross-conversation if no group is specified; default 7 days
View unread chats	`dws chat +unread-chats`	When body is needed, read messages via CID
Batch fetch details by known message ID	`dws chat +messages-mget`	See leaf Schema; preserve conversation context
<!-- dws-intent: chat.send.dm -->Send text/Markdown by name	`dws chat +dm --to <name> --content <content>`	Unique resolution; stop on multiple candidates
<!-- dws-intent: chat.send.group -->Send text/Markdown by group name/ID	`dws chat +send-to-group --group <group name or ID> --content <content>`	Stop on multiple candidates
<!-- dws-intent: chat.send.advanced -->Files/Bot/Webhook/complex @	`dws chat +messages-send`	Bot multi-group check item by item with ledger
All conversations	`dws chat +conversation-list --page-all`	Includes group/direct, not body
View joined/managed groups	`+my-groups --page-all` / `+chat-list-mine`	The latter has no `--page-all` ; flags do not cross leaf
Search group or view all members	`+chat-search --query <term>` / `+chat-members-list --group <group name or ID>`	Stop on multiple candidates; check buckets/completeness
View group profile/Bot/invite link	`+conversation-info` / `+chat-bots` / `+chat-invite-url`	Read-only
<!-- dws-intent: chat.create.group -->Create/cleanup temporary group	`dws chat +chat-create --name <name> --member-query <name list>` → save CID → `+chat-dismiss --group <cid>`	Use `--users` for known IDs; cleanup requires confirmation and verification
Modify group profile/settings/mute/admin	`+chat-update` / `+chat-update-settings` / `+chat-mute` / `+chat-mute-member` / `+chat-set-admin`	Use real group/user IDs; read back after writes
Manage group roles	Read the group-admin role family	Role CRUD, member bind/unbind/query; do not switch to atomic, read back after writes
<!-- dws-intent: chat.category.list-conversations -->List conversations in a category	`dws chat +category-list-conversations --category-id <ID>`	Category ≠ group; get the ID first
<!-- dws-intent: chat.reply.quote -->Reply with quote	`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 and pretend it is a 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 the corresponding query
Add/remove reactions	`+messages-add-emoji` / `+messages-remove-emoji`	Extension actions read `message-actions`
Conversation pin/DND/hide	chat-conversation	Use real CID; conversation Top is not message Top
Mark read/unread/clear red dot/clear messages	`+conversation-mark-read` / `+conversation-mark-unread` / `+conversation-clear-red-point` / `+conversation-clear-all-red-point` / `+conversation-clear-messages`	Read requires message ID; clear follows Runtime confirmation
Download message resources	Add `--download-resources --output-dir <directory>` to query; use `+messages-resource-download` for existing references	Do not guess IDs; keep ledger; do not deliver temporary URLs

Secondary: Thread

+thread-replies

; pinned

dws chat +conversation-list-top

; upload

conversation-file upload

; IM events go through

dingtalk-event

关键结果语义

Key Result Semantics

查询保留范围、数量、完整性、停止原因、失败/下载 ledger；不完整不得称成功。消息仅
```
--page-all
```
翻页，达预算返回有界 partial。
本地图片仅已有
```
mediaId
```
才发内联 image，否则发 file；只上传不发送用
```
conversation-file upload
```
。
子消息用自身 messageId；缺 CID 才继承父 conversationId。写操作沿真实结果传 ID。

Queries preserve scope, count, completeness, stop reason, failure/download ledger; incomplete results must not be called successful. Messages paginate only with
```
--page-all
```
; reaching the budget returns a bounded partial.
Local images are sent as inline image only when a
```
mediaId
```
already exists; otherwise send as file; use
```
conversation-file upload
```
to only upload without sending.
Child messages use their own messageId; inherit the parent conversationId only when CID is missing. Write operations pass IDs from real results.

写生命周期

Write Lifecycle

多步骤写先校验目标、限制、内容、确认，再沿稳定 ID 串行执行并验证；不截断或换目标。临时资源保留 ID/阶段，失败仅做已授权清理。

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

上下文预算

Context Budget

Skill/Reference/leaf Schema/Help 各读一次；Schema 已给参数禁 Help。总结/统计/检索默认
```
--no-reactions
```
，资源下载仅显式 opt-in。
用
```
--fields
```
/
```
--jq
```
/limit/compact 预览，禁
```
head
```
截 JSON；大正文落文件，保留 ID、正文证据、下步字段、完整性和失败项。

Read Skill/Reference/leaf Schema/Help once each; if Schema already provides parameters, Help is prohibited. Summary/statistics/search default to
```
--no-reactions
```
; resource downloads are explicit opt-in only.
Use
```
--fields
```
/
```
--jq
```
/limit/compact for preview; do not use
```
head
```
to truncate JSON; large bodies go to files, keeping IDs, body evidence, next-step fields, completeness, and failure items.

按需加载

On-Demand Loading

任务≤1个

场景	Reference
消息	查询 / 动作 / 资源
群	读取 / 治理
会话/Bot	会话 / Bot
组合/话题/表情/卡片	组合 / 话题 / 表情 / 卡片/A2UI
结果/其他原子能力	contracts / chat

Task ≤ 1

Scenario	Reference
Messages	Query / Actions / Media
Groups	Discovery / Admin
Conversations/Bot	Conversation / Bot
Combined/Thread/Emoji/Card	Combined / Thread / Emoji / Card/A2UI
Outcomes/other atomic capabilities	contracts / chat

错误最短路径

Shortest Error Path

零命中/多候选：停止写并消歧，禁默认第一项。
参数/确认不明查 leaf Schema；Schema 不可用才查已知 leaf Help。
```
unknown flag
```
用同 leaf Help 修正一次；
```
unknown command
```
不查 Help：先用错误的明确 suggestion，再用已加载 Skill/reference 的明确兼容入口；无则报漂移并停，禁全 Catalog。
仅
```
retryable=true
```
按原命令重试一次；API/internal/MCP、写后不一致或无重试性即停，不换 Shortcut/atomic。保留 Trace ID、已完成/待清理项并最终答复；
```
confirmation_required
```
等用户确认，不补
```
--yes
```
。

Zero hits/multiple candidates: stop and disambiguate; do not default to the first item.
If parameters/confirmation are unclear, check the leaf Schema; only if Schema is unavailable, check the known leaf Help.
```
unknown flag
```
is corrected once with the same leaf Help;
```
unknown command
```
does not check Help: first use the explicit suggestion in the error, then the explicit compatible entry in the loaded Skill/reference; if none, report drift and stop; full Catalog is prohibited.
Only retry once with the original command when
```
retryable=true
```
; API/internal/MCP, post-write inconsistency, or non-retryable means stop, do not switch Shortcut/atomic. Keep Trace ID, completed/pending-cleanup items and give a final reply;
```
confirmation_required
```
waits for user confirmation, do not add
```
--yes
```
.