dingtalk-chat git:20260903.02713baA

Immutable. This exact content is served forever at /api/v1/blob/4b2d09ee698929ee.

---
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_RUNTIME_CONTRACT_START -->
## 最小 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；不要连续猜测替代命令。
<!-- DWS_RUNTIME_CONTRACT_END -->

<!-- VISIBLE_SHORTCUTS_START -->
## 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。
<!-- VISIBLE_SHORTCUTS_END -->

## Golden Route

按用户任务选择最小充分入口。公开层按意图分流；Resolver、发送执行、消息投影和错误契约在 Runtime 内复用，不把所有能力塞进一个万能命令。

| 用户意图 | 唯一推荐入口 | 关键边界 |
|---|---|---|
| <!-- dws-intent: chat.send.dm -->按姓名发简单文本或 Markdown | `dws chat +dm --to <姓名> --content <内容>` | CLI 解析唯一用户；多候选时停止，不先手工查 ID |
| <!-- dws-intent: chat.send.group -->按群名或 ID 发简单文本或 Markdown | `dws chat +send-to-group --group <群名或ID> --content <内容>` | 稳定 ID 直接使用；群名多候选时停止 |
| <!-- dws-intent: chat.send.advanced -->文件、Bot、Webhook、复杂 @ 或高级发送 | `dws chat +messages-send` | Bot 多群用 `--groups/--groups-file` 并检查逐项 ledger |
| <!-- dws-intent: chat.read.conversation -->读取指定会话、返回较多消息 | `dws chat +chat-messages` | 粗粒度读取；目标条件明确时优先 `+search-msg` |
| <!-- dws-intent: chat.search.filtered -->多维度条件搜索（发送者/关键词/@/类型，单/跨会话） | `dws chat +search-msg` | 目标条件明确时使用 |
| <!-- dws-intent: chat.create.group -->按成员 ID 或姓名创建群聊 | `dws chat +chat-create` | 姓名用 `--member-query` 由 CLI 唯一解析，不先手工搜索 |
| 查看指定群成员（用户/机器人） | `dws chat +chat-members-list --group <群名或ID>` | 唯一解析并全量读取 |
| 获取群邀请链接 | `dws chat +chat-invite-url --group <群名或ID>` | 多候选时停止 |
| 查看群机器人 | `dws chat +chat-bots --group <群名或ID>` | 返回稳定 `bots[]` |
| 管理群身份 | 按动作使用 `+chat-role-list` / `+chat-role-add` / `+chat-role-update` / `+chat-role-remove` / `+chat-role-set-user` / `+chat-role-remove-user` / `+chat-role-query-user` | `--group` 接受群名或 ID；定义删除用单数 `--role-id`，成员设置/移除用复数 `--role-ids` |
| 管理个人会话分类 | `+category-create` → `+category-add-conversation` → `+category-list-conversations` → `+category-delete`；读取全部用 `+category-list` | 分类不是聊天群；高频生命周期直接走 shortcut，详情读 `chat-conversation.md` |
| 个人收藏表情列表/发送/收藏 | `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-intent: chat.conversation.list-top -->查看置顶会话 | `dws chat +conversation-list-top` | 会话 Top 与消息 Pin、消息 Top、Favorite 不同 |
| 监听未来 IM 事件 | [`dingtalk-event`](../dingtalk-event/SKILL.md) | 常规监听走 `+listen-im`；生命周期/高级控制走 `consume` |

## 关键结果语义

- `openTaskId` 是发送任务 ID，不是消息 ID；后续 ID 必须来自真实结果。
- 查询检查 `complete/hasMore/failures` 和下载 ledger；partial 不得表述为完整成功，也不得丢失已取得业务数据。
- Favorite、消息 Pin、消息 Top、会话 Top 是不同对象，不能互换；详细字段、子消息和下载规则只在对应 reference 中加载。

## 按需加载

只在根路由不足且任务命中时读取一个精确 reference：

| 场景 | Reference |
|---|---|
| 需要跨步骤传递真实结果的消息/群组合流程 | [01-messaging.md](references/01-messaging.md) |
| 消息读取与查询 | [message-query](references/chat/message-query.md) |
| 编辑、撤回、回复、转发、Pin、Top、Favorite 或 reaction 写入 | [message-actions](references/chat/message-actions.md) |
| 位置、联系人名片、底层媒体与资源下载 | [message-media](references/chat/message-media.md) |
| 群列表、群搜索、共同群、成员与群内机器人读取 | [group-discovery](references/chat/group-discovery.md) |
| 建群、成员或已知机器人增删、管理员、公告与群设置 | [group-admin](references/chat/group-admin.md) |
| 搜索未知机器人、机器人消息发送/撤回与 Webhook | [chat-bot.md](references/chat/chat-bot.md) |
| 会话置顶、分类、红点、免打扰和隐藏 | [chat-conversation.md](references/chat/chat-conversation.md) |
| 话题与话题圈 | [thread.md](references/chat/thread.md) |
| 低频意图之间仍需消歧 | [intent-guide.md](references/intent-guide.md) |
| 表情名称与 ID | [chat-emoji-list.md](references/chat-emoji-list.md) |
| 稳定结果、身份矩阵与能力边界 | [contracts.md](references/contracts.md) |
| 流式卡片创建 | [card/create.md](references/card/create.md) |
| 流式卡片更新 | [card/update.md](references/card/update.md) |
| 卡片 callback 是否可用 | [card/callback.md](references/card/callback.md) |
| 卡片公开 Schema 边界 | [card/schema.md](references/card/schema.md) |
| 只有上述 reference 仍无法定位的原子能力 | [chat.md](references/chat.md) 的对应章节 |

不要预加载 reference；根路由参数充分时不读取。Catalog 只在根路由和精确 reference 都无法定位低频能力时使用。

## 错误最短路径

1. resolution 返回零命中或多候选：停止写操作，展示候选并让用户消歧；禁止默认第一项。
2. `unknown command` / `unknown flag`：读取精确 leaf Help，修正后最多重试一次。
3. 参数约束或 confirmation 不清楚：首次业务调用前读取精确 leaf Schema；`confirmation_required` 后停止，不自动补 `--yes` 重试。
4. 认证、权限或 profile 错误：只读取 `dingtalk-shared` 的对应 reference。
5. `backend_dependency_unavailable`：保持原参数，对只读命令最多重试一次；不要改 flag、猜认证命令或切换同义原子命令，持续失败时保留 Trace ID。
6. 其他错误：保留真实错误和已完成/失败项；不要连续尝试同义原子命令。