| name | dingtalk-chat |
| description | 钉钉群聊与消息。Use when 发消息、单聊/群聊、建群、群设置/成员、搜索/回复、机器人/Webhook、消息文件。DING 和班级群走 dingtalk-misc；邮件走 dingtalk-mail。前缀 dws chat。 |
| metadata | {"cli_version":">=0.2.14","category":"product","requires":{"bins":["dws"]}} |
钉钉群聊 / 消息 Skill
最小 DWS 执行契约
- 只通过
dws CLI 操作钉钉；结构化读取使用 --format json，按真实返回判断结果。
- 已知命令直接执行。只有 leaf 参数或安全语义不确定时读取精确 Schema，只有 Cobra flag 不确定时读取精确 leaf Help；不要加载产品级 Catalog 代替选路。
- 不猜命令、flag、字段、ID、账号或时间。后续 ID 必须来自真实返回；零命中、多候选或类型不明时停止并消歧。
- 解析目标、读取上下文和最终执行必须使用同一 profile；不得跨组织复用 userId、openDingTalkId 或 openConversationId。多账号组织只使用明确的
isOrgCurrent=true 默认账号；没有默认账号时要求用户指定，禁止选择第一项、最近登录或最近使用账号。
- 不输出或记录 token、refresh token、appSecret、webhook token 等凭据；宿主已注入认证时不要索要凭据。
- 写操作必须符合用户明确意图。是否需要确认以最终 Runtime gate 和 Schema 为准；需要确认时先说明对象、动作与影响，再追加
--yes。
- 写后按任务结果契约验证；不能仅凭退出码宣称成功。部分结果、未知投递状态和失败项必须如实保留。
- 时间戳面向用户展示时转换为带时区的可读时间；默认使用当前会话时区，必要时同时保留原值。
- 遇到认证、权限、profile、confirmation 或未知错误时，只加载
dingtalk-shared 中对应 reference；不要连续猜测替代命令。
Shortcut 发现（Shortcut-first）
chat 有 93 条 canonical Shortcut：根 Help 展示 26 条 Featured，另 67 条在 Catalog、Schema 和精确 Help；5 条 public 兼容入口从根 Help 省略，2 条 unavailable 不参与默认选路。
优先按 Golden Route、意图表或 reference 选 Shortcut；仅在所需底层参数或原始响应未覆盖时使用 atomic。低频发现用 dws shortcut list --service chat --format json；参数/安全查 compact leaf Schema，flags 查所选 Shortcut 的精确 Help。
Golden Route
按用户任务选择最小充分入口。公开层按意图分流；Resolver、发送执行、消息投影和错误契约在 Runtime 内复用，不把所有能力塞进一个万能命令。
| 用户意图 | 唯一推荐入口 | 关键边界 |
|---|
| 按姓名发简单文本或 Markdown | dws chat +dm --to <姓名> --content <内容> | CLI 解析唯一用户；多候选时停止，不先手工查 ID |
| 按群名或 ID 发简单文本或 Markdown | dws chat +send-to-group --group <群名或ID> --content <内容> | 稳定 ID 直接使用；群名多候选时停止 |
| 文件、Bot、Webhook、复杂 @ 或高级发送 | dws chat +messages-send | Bot 多群用 --groups/--groups-file 并检查逐项 ledger |
| 读取指定会话、返回较多消息 | dws chat +chat-messages | 粗粒度读取；目标条件明确时优先 +search-msg |
| 多维度条件搜索（发送者/关键词/@/类型，单/跨会话） | dws chat +search-msg | 目标条件明确时使用 |
| 查看指定群成员（用户/机器人） | dws chat +chat-members-list --group <群名或ID> | 唯一解析并全量读取 |
| 获取群邀请链接 | dws chat +chat-invite-url --group <群名或ID> | 多候选时停止 |
| 查看群机器人 | dws chat +chat-bots --group <群名或ID> | 返回稳定 bots[] |
| 个人收藏表情列表/发送/收藏 | dws chat emotion list/send/favorite | 约束见 leaf Schema |
| 修改群名称 | dws chat +chat-update --group <群名或openConversationId> --name <新名称> | Shortcut 内统一解析群名或稳定 ID；多候选时停止，不直接调用 atomic group rename |
| 查看指定群内 @我的消息 | dws chat +at-me --group <群名> --page-all | 检查 complete；空结果仍返回数组 |
| 查看全部会话 | dws chat +conversation-list --page-all | 检查 complete / failures |
| 读取并下载消息资源 | 查询命令加 --download-resources | 不另起手工下载循环；下载失败项保留在结果中 |
| 查看置顶会话 | dws chat +conversation-list-top | 会话 Top 与消息 Pin、消息 Top、Favorite 不同 |
| 监听未来 IM 事件 | dingtalk-event | 常规监听走 +listen-im；生命周期/高级控制走 |
以下次级入口在意图明确时直接使用，不需要先加载完整 Catalog：
| 用户意图 | 入口 |
|---|
| 已知消息 ID 批量读取详情 | dws chat +messages-mget |
| 已知资源引用单独下载 | dws chat +messages-resource-download |
| 只上传会话文件，不发消息 | dws chat conversation-file upload --conversation-id <cid> --file <路径>；返回文件 ID，仅本地路径 |
| 按关键词搜索群 | dws chat +chat-search |
| 查看消息收藏 | dws chat +flag-list |
| 引用回复 | 人：dws chat +messages-reply；成功结果保留新消息/会话/投递与原消息来源上下文。Bot 群：dws chat message send-by-bot --conversation-id <cid> --reply <mid> --ref-sender <sid> |
| 撤回当前用户消息 | dws chat +messages-recall --msg-id <openMessageId>；可省略会话 ID，由 CLI 只读补齐；兼容单值 --message-ids |
| 已知话题主消息 ID 或 thread/topic ID 读取回复 | dws chat +thread-replies |
| 按成员 ID 或姓名创建群聊 | dws chat +chat-create；成员/群主均可自然解析，任一歧义都会在创建前整体停止 |
| 跨全部会话查看 @我的消息 | dws chat +at-me --page-all |
发送入口边界
+dm：姓名目标的简单文本/Markdown，参数空间最小。+send-to-group：群名或稳定 ID 目标的简单文本/Markdown，避免暴露无关身份矩阵。- Markdown 中的公网图片必须写成
 才会内联展示；
省略开头的 ! 时只会显示为链接。
+messages-send：文件、Bot、Webhook、复杂 @ 或幂等控制。user 已知 ID 可直接传，也可用 --user-query / --chat-query 运行同一只读解析链；Bot 多群使用 --groups/--groups-file，返回 im.batch-write.v1；bot/webhook 只使用下层真实支持的文本/Markdown 能力。- 发文件消息用
+messages-send --file <路径>；只存会话空间、不发消息才用 chat conversation-file upload，返回 dentryId/spaceId。
- Webhook 使用
+messages-send --as webhook --webhook-token <token>；不要退回原子 Webhook 命令。
- 流式卡片用
+messages-send-card；群聊 @ 传 ID/--at-all，Runtime 拼接 create 前缀；禁占位符，仅 text。
关键结果语义
openTaskId 是发送任务 ID，不是回复或撤回所需的消息 ID；消息 ID 必须来自真实查询结果。- 消息查询默认保留稳定 ID、会话/thread、发送者、文本、时间、
messageAiSendFlag、reaction、引用、转发和 resourceRefs；--no-reactions 可关闭 reaction。
- 查询结果必须检查
complete、hasMore、failures 和资源下载 ledger；partial result 不得表述为完整成功。
- 子消息使用自己的
messageId；仅缺会话 ID 时继承父消息的 conversationId。
- 下载只允许工作目录内安全相对路径，默认不覆盖并原子落盘；覆盖必须由用户显式传
--overwrite。读取和下载不需要 --yes。
- Favorite、消息 Pin、消息 Top、会话 Top 是不同对象层级，不能互换。
按需加载
只在任务命中时读取一个精确 reference：
话题与话题圈
不要预加载 reference。Shortcut Catalog 只在根路由和精确 reference 都无法定位低频能力时使用。
错误最短路径
- resolution 返回零命中或多候选：停止写操作，展示候选并让用户消歧；禁止默认第一项。
unknown command / unknown flag：读取精确 leaf Help，修正后最多重试一次。- 参数约束或 confirmation 不清楚：读取精确 leaf Schema，以 Runtime gate 为准。
- 认证、权限、profile 或 confirmation 错误：读取
dingtalk-shared 的对应 reference；正常 IM 不读取完整 shared Skill。
backend_dependency_unavailable：保持原参数，对只读命令最多重试一次；不要改 flag、猜认证命令或切换同义原子命令，持续失败时保留 Trace ID。- 其他错误：保留真实错误和已完成/失败项；不要连续尝试同义原子命令。
