first commit

2026-09-02 11:44:52 +08:00
commit 0c8fa2653e
309 changed files with 57278 additions and 0 deletions
@@ -0,0 +1,126 @@
+---
+name: dingtalk-chat
+description: 钉钉群聊与消息。Use when 用户提到 发消息/编辑或撤回消息/单聊/群聊/建群/普通群升级外部群/群昵称/会话分组/群成员管理/@消息/搜索聊天记录/话题回复/收藏消息/机器人群发/Webhook通知/发送或下载消息图片与文件。不做紧急 DING/短信/电话（走 dingtalk-misc）、邮件（走 dingtalk-mail）、班级群（走 dingtalk-misc）。命令前缀：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 发现（按需）
+
+`chat` 当前有 98 条公开 shortcut，完整清单保留在 Runtime Catalog 与 Schema，不在高频产品根 Skill 中重复展开。已知意图直接使用下方的优先路由、意图表或任务 reference；命令已选中时直接执行，只在参数/安全语义不确定时读取 leaf Schema，在当前 Cobra flags 不确定时读取 leaf Help。
+
+仅当现有路由和 reference 都无法定位低频能力时，才执行 `dws shortcut list --service chat --format json` 做最后回退；不要为已知高频意图加载完整 Shortcut Catalog 或产品级 Schema。
+<!-- 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 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 group rename --id <openConversationId> --name <新名称>` | 只知群名时先用 `+chat-search --query <群名>` 唯一解析 ID；不猜 `+chat-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` |
+
+以下次级入口在意图明确时直接使用，不需要先加载完整 Catalog：
+
+| 用户意图 | 入口 |
+|---|---|
+| 已知消息 ID 批量读取详情 | `dws chat +messages-mget` |
+| 已知资源引用单独下载 | `dws chat +messages-resource-download` |
+| 按关键词搜索群 | `dws chat +chat-search` |
+| 查看消息收藏 | `dws chat +flag-list` |
+| <!-- dws-intent: chat.reply.quote -->引用回复 | 人：`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` |
+| <!-- dws-intent: chat.create.group -->按成员 ID 或姓名创建群聊 | `dws chat +chat-create`；成员/群主均可自然解析，任一歧义都会在创建前整体停止 |
+| 跨全部会话查看 @我的消息 | `dws chat +at-me --page-all` |
+
+### 发送入口边界
+
+- `+dm`：姓名目标的简单文本/Markdown，参数空间最小。
+- `+send-to-group`：群名或稳定 ID 目标的简单文本/Markdown，避免暴露无关身份矩阵。
+- Markdown 中的公网图片必须写成 `![图片标题](https://example.com/image.png)` 才会内联展示；
+  省略开头的 `!` 时只会显示为链接。
+- `+messages-send`：文件、Bot、Webhook、复杂 @ 或幂等控制。user 已知 ID 可直接传，也可用 `--user-query` / `--chat-query` 运行同一只读解析链；Bot 多群使用 `--groups/--groups-file`，返回 `im.batch-write.v1`；bot/webhook 只使用下层真实支持的文本/Markdown 能力。
+- 文件直接传 `+messages-send --file <相对路径>`；不要先独立上传并提取 mediaId。
+- Webhook 使用 `+messages-send --as webhook --webhook-token <token>`；不要退回原子 Webhook 命令。
+- 流式卡片用 `+messages-send-card`；群聊@传 ID/`--at-all`，Runtime 把 create 返回前缀加到 `--content`；禁写占位符；仅 text。
+
+## 关键结果语义
+
+- `openTaskId` 是发送任务 ID，不是回复或撤回所需的消息 ID；消息 ID 必须来自真实查询结果。
+- 消息查询默认保留稳定 ID、会话/thread、发送者、文本、时间、reaction、引用、转发和 `resourceRefs`；`--no-reactions` 可关闭 reaction。
+- 查询结果必须检查 `complete`、`hasMore`、`failures` 和资源下载 ledger；partial result 不得表述为完整成功。
+- 子消息使用自己的 `messageId`；仅缺会话 ID 时继承父消息的 `conversationId`。
+- 下载只允许工作目录内安全相对路径，默认不覆盖并原子落盘；覆盖必须由用户显式传 `--overwrite`。读取和下载不需要 `--yes`。
+- Favorite、消息 Pin、消息 Top、会话 Top 是不同对象层级，不能互换。
+
+## 按需加载
+
+只在任务命中时读取一个精确 reference：
+
+[话题与话题圈](references/chat/thread.md)
+
+| 场景 | 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) |
+| 低频意图之间仍需消歧 | [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。Shortcut Catalog 只在根路由和精确 reference 都无法定位低频能力时使用。
+
+## 错误最短路径
+
+1. resolution 返回零命中或多候选：停止写操作，展示候选并让用户消歧；禁止默认第一项。
+2. `unknown command` / `unknown flag`：读取精确 leaf Help，修正后最多重试一次。
+3. 参数约束或 confirmation 不清楚：读取精确 leaf Schema，以 Runtime gate 为准。
+4. 认证、权限、profile 或 confirmation 错误：读取 `dingtalk-shared` 的对应 reference；正常 IM 不读取完整 shared Skill。
+5. `backend_dependency_unavailable`：保持原参数，对只读命令最多重试一次；不要改 flag、猜认证命令或切换同义原子命令，持续失败时保留 Trace ID。
+6. 其他错误：保留真实错误和已完成/失败项；不要连续尝试同义原子命令。
@@ -0,0 +1,103 @@
+# 消息任务级流程
+
+只在单个 Golden Route 不能完成任务、需要跨步骤传递真实结果时读取本文件。简单姓名/群名文本发送、单会话读取和跨会话搜索直接按根 Skill 执行。
+
+## 选择路线
+
+1. 先选择任务语义最窄的 Shortcut。
+2. 只有 Shortcut 暂不接受自然目标或目标类型时，才用一个只读 leaf/Shortcut 解析 ID。
+3. 解析全部完成并消歧后再写入；不要边解析边产生部分副作用。
+4. 后续步骤只使用真实返回字段，不从名称、URL 或上下文猜 ID。
+
+## 群聊消息
+
+<!-- dws-intent: chat.read.conversation -->读取或导出指定群聊/单聊的消息记录时使用 `dws chat +chat-messages`。可附带非必填的 `--sender-query <姓名>`：唯一解析成功后按稳定 `senderId` 筛选同一次读取结果并返回 `resolvedFilters`；解析失败、不完整或存在歧义时抑制未过滤消息并返回 `sender_resolution_failed`，不要补跑 `+search-msg`。混合姓名/ID 入口 `--sender` 无法经通讯录确认类型时可按原值 userId 精确过滤，但必须保留 `identity_unverified`。
+
+用户以发送者、关键词、@对象或消息类型为主要条件直接检索时优先使用 `+search-msg`；范围可以是单个、多个或全部会话。
+
+指定会话按时间读取时，`+chat-messages` 使用公开可选的 `--start/--end/--order`，范围固定为
+`[start,end)`；仅开始时间表示到本次执行当前时间，仅结束时间只支持 `desc`，升序必须有开始时间。
+兼容别名为 `--start-time/--end-time/--sort`。旧 `--time/--direction` 只用于单边界兼容模式，不能混用。
+
+已知群 ID 时直接读取：
+
+```bash
+dws chat +chat-messages --group <openConversationId> --format json
+```
+
+要求全量或导出时直接使用 Runtime 能力：
+
+```bash
+dws chat +chat-messages --group <openConversationId> \
+  --page-all --page-limit 50 \
+  --output ./exports/messages.json \
+  --format json
+```
+
+```bash
+dws chat +chat-messages --group <openConversationId> \
+  --start "2026-08-01T00:00:00+08:00" --end "2026-08-02T00:00:00+08:00" \
+  --order asc --page-all --format json
+```
+
+必须检查 `complete/hasMore/nextPage/stopReason/failures`；达到页数或结果上限不是来源完整。
+
+只有群名时，读取历史直接用 `+chat-messages --group <群名>`，普通文本发送直接用 `+send-to-group`。其它尚不接受群名的高级动作才先用 `+chat-search --query <群名>`；只有唯一候选才把 `openConversationId` 传给下一步。查询结果需要资源时在读取命令上加 `--download-resources`，不要让 Agent 手工遍历资源引用。按姓名读取单聊时先解析唯一用户 ID，再传给 `+chat-messages --user`。
+
+## 发送消息
+
+- <!-- dws-intent: chat.send.dm -->姓名 + 简单文本：`dws chat +dm`。
+- <!-- dws-intent: chat.send.group -->群名 + 简单文本：`dws chat +send-to-group`。
+- <!-- dws-intent: chat.send.advanced -->已知 ID、文件、Bot、Webhook、复杂 @ 或幂等：`dws chat +messages-send`。
+- 姓名 + 文件/高级控制：`+messages-send --as user --user-query <姓名> --file <相对路径>`。
+- 群名 + 文件/高级控制：`+messages-send --as user --chat-query <群名> --file <相对路径>`。
+- Bot 多群文本/Markdown：`+messages-send --as bot --robot-code <code> --groups <cid1,cid2>`；
+  Runtime 去重并返回 `im.batch-write.v1` 逐目标 ledger，最多 100 个稳定群 ID。
+
+`--user-query` 和 `--chat-query` 会在 CLI 内运行真实只读解析；零命中或多候选时在上传或发送前停止。Bot/Webhook 不接受这两个自然目标参数。
+
+文件直接交给 `+messages-send --file`。不要恢复“独立上传 → 提取 mediaId → 发送”的旧默认链路。
+
+## 创建群聊
+
+<!-- dws-intent: chat.create.group -->基础建群默认使用 `dws chat +chat-create`；它同时接受 `--users` 稳定 ID 和 `--member-query` 姓名/花名。群主默认当前用户，也可用 `--owner-open-dingtalk-id` 或 `--owner-query` 明确指定。自然身份解析、候选消歧、稳定 ID 去重和创建前预检都由 CLI 完成：
+
+```text
+传入全部姓名
+→ 对零命中和多候选统一消歧
+→ 按稳定 ID 去重
+→ 全部成功后执行一次 +chat-create
+```
+
+任一成员或群主未唯一解析时不会创建群；显式群主会加入初始成员且不再读取当前用户，省略群主时才以当前用户兜底。`--dry-run` 也走同一解析链。不要用群名预搜索伪装幂等，因为业务上允许同名群。
+
+## 机器人消息
+
+已知 `robotCode` 时使用 `+messages-send --as bot`；单群用 `--group`，多群用 `--groups` 或工作目录内安全的 `--groups-file`。未知机器人、机器人入群或撤回读取 [chat-bot.md](chat/chat-bot.md)。Bot 不继承 user 的文件/图片能力；只使用 leaf Schema 明确发布的文本/Markdown 能力。
+
+## 引用与转发
+
+- <!-- dws-intent: chat.reply.quote -->引用回复：`dws chat +messages-reply`；优先继续使用结果中的 `messageId`、`conversationId`、`deliveryStatus` 和 `referencedMessage`，未知投递状态不得写成成功送达。
+- 单条转发：`+messages-forward`。
+- 合并转发：`+messages-combine-forward`。
+- 话题转发：`+messages-forward-topic`。
+
+先用 `+chat-messages`、`+search-msg` 或 `+messages-mget` 取得真实 `messageId` 和 conversation/thread 上下文。引用或合并消息中的子消息优先使用自己的 `messageId`，不要拿父消息 ID 代替。
+
+## 上下文传递表
+
+| 上一步 | 真实返回 | 下一步用途 |
+|---|---|---|
+| `+chat-search` | `openConversationId` | 高级发送、读取、群管理 |
+| `dingtalk-contact` 唯一用户解析 | `userId` / `openDingTalkId` | 单聊、建群、@、按发送者搜索 |
+| `+messages-send` | `openTaskId` / 投递结果 | 查询投递状态；不是回复/撤回消息 ID |
+| `+chat-messages` / `+search-msg` / `+messages-mget` | `messageId`、conversation/thread、`resourceRefs` | 回复、转发、撤回、资源下载 |
+| `+chat-create` | `openConversationId` | 新群后续消息与群管理 |
+| 分页查询 | `hasMore` / `nextCursor` / `complete` | 继续翻页和完整性判断 |
+
+## 完成判断
+
+- 写操作检查任务级结果或可查询状态，不只看退出码。
+- 读取检查 `complete`、`hasMore` 和 `failures`。
+- 下载检查每项 ledger；单项失败不抹掉已取得消息。
+- 投递状态未知时报告 unknown 并保留幂等键，不自动换目标重发。
@@ -0,0 +1,10 @@
+# 卡片回调边界
+
+当前 DWS lower interface 没有卡片按钮/action callback 的订阅、验签或回复能力，
+`callback_supported=false`。因此：
+
+- 不生成 callback URL、签名密钥或虚构的监听命令；
+- 不把 `dws event consume` 当作卡片 callback 的替代；
+- 用户必须使用按钮交互时，停止并说明当前不支持，等待平台接口和 Runtime 正式发布。
+
+卡片的 create/update 能力不代表 callback 可用。
@@ -0,0 +1,27 @@
+# 创建流式卡片
+
+使用 `dws chat +messages-send-card`。群目标传 `--group`；单聊 userId 传 `--receiver`，
+Runtime 会唯一解析为 openDingTalkId；已有 openDingTalkId 时传
+`--receiver-open-dingtalk-id`。三种目标严格三选一。
+
+- 只传目标：创建卡片并从真实结果取得 `bizId`，供后续更新。
+- 同时传 `--content`：Runtime 串行执行 create → 从返回提取 `bizId` → update；默认
+  `--flow-status 3`。
+- 群聊可传 `--at-open-dingtalk-ids` 或 `--at-all`；艾特对象只进入初始
+  `create_and_send_card`。同一次调用带 `--content` 时，Runtime 将 create 返回的
+  `atTag` 自动加在正文前，再调用 `update_streaming_card`；调用方不要拼 ID
+  或艾特占位符。
+- `--dry-run` 仍执行只读 userId 解析，只输出两步计划，不执行写入。
+
+创建成功后保留真实 `bizId`。自动更新返回 `verified=true` 时已有明确生效证据；返回
+`accepted=true, verified=false` 时仅表示服务端已接受请求但未提供独立更新证据，应如实说明，
+不要重复创建或重复执行相同更新。只有错误明确标记 `retryable=true` 时，才使用原 `bizId`
+重试；明确未应用或 `bizId` 不一致时停止并保留真实错误。若结果中已经包含 `openTaskId`，
+可以按用户需要查询一次投递状态；该查询只确认消息投递，不代表卡片正文已经更新成功。
+
+当前内容仅为 streaming text，不接受 Lark Card JSON、组件树或按钮 callback。
+
+```bash
+dws chat +messages-send-card --group <openConversationId> --at-open-dingtalk-ids <mentionedOpenDingTalkId> --content "请确认"
+dws chat +messages-send-card --group <openConversationId> --at-all --content "请大家确认"
+```
@@ -0,0 +1,14 @@
+# 流式卡片 Schema
+
+DWS 当前公开的是 `im.streaming-card.v1` 工作流契约，不是任意组件 Schema：
+
+- target：group、direct user、direct openDingTalkId；
+- content：streaming text；
+- lifecycle：create 可选串联 update，后续按 `bizId` update；
+- flowStatus：1–5；
+- callback：不支持。
+
+参数、required 和 confirmation 读取
+`dws schema --cli-path "chat +messages-send-card" --compact -f json` 或
+`dws schema --cli-path "chat +messages-update-card" --compact -f json`。不要把 Lark card JSON 字段翻译成
+未发布的 DWS flags。
@@ -0,0 +1,13 @@
+# 更新流式卡片
+
+使用 `dws chat +messages-update-card --biz-id <bizId> --content <文本> --flow-status <1..5>`。
+
+状态为：1 processing、2 typing、3 completed、4 executing、5 error。Runtime 拒绝范围外的
+状态；正常完成的最后一次更新应为 3。`bizId` 必须来自真实创建结果，不能用消息 ID 代替。
+
+更新是写操作，confirmation 以精确 leaf Schema 与 Runtime gate 为准。失败后保留原
+`bizId` 和状态，不创建新卡片来掩盖更新失败。
+
+结果中 `verified=true` 表示已有明确更新证据；`accepted=true, verified=false` 仅表示服务端
+接受了请求但未提供独立生效证据，应如实说明且不得重复执行相同更新。只有错误明确标记
+`retryable=true` 时才重试；明确未应用或 `bizId` 不一致时停止。
@@ -0,0 +1,216 @@
+# 钉钉默认表情列表（emoji 回应可用）
+
+> 本文件列出钉钉支持的所有用户可见默认表情（showType=1），共 199 个。
+>
+> **来源与维护合同（reviewed snapshot）**：表格来自钉钉默认表情 catalog 的 showType=1
+> 人工复核快照；当前 lower interface 没有可靠的“列出默认 emoji”命令，因此本文件不是从
+> Runtime 或旧 Catalog 反向生成。更新时必须取得新的官方/真实客户端 catalog，核对
+> emotionId、中文 name、en_US、showType 和总数，说明来源与复核日期，再整体替换表格；禁止
+> 根据用户输入或单次 reaction 响应增补。生成策略为 **non-generated reviewed reference**，
+> Schema/Skill 生成器不得机械重写它。最后复核：2026-08-03。
+>
+> 使用规则：
+> - 用户描述的表情命中下表中的 `name` → 使用 `chat message add-emoji --emoji <name>` 贴 emoji 回应
+> - 用户描述的表情未命中下表 → 先 `chat message create-text-emotion` 创建文字表情获取 emotionId，再 `chat message add-text-emotion` 贴文字表情回应
+
+| # | emotionId | name | en_US |
+|---|-----------|------|-------|
+| 1 | emotion_001 | 微笑 | Smile |
+| 2 | emotion_099 | 可爱 | Lovely |
+| 3 | emotion_002 | 憨笑 | Wow |
+| 4 | emotion_003 | 色 | Yum |
+| 5 | emotion_004 | 发呆 | Dazed |
+| 6 | emotion_005 | 老板 | Boss |
+| 7 | emotion_036 | 傻笑 | Oops |
+| 8 | emotion_006 | 流泪 | Sob |
+| 9 | emotion_007 | 害羞 | Shy |
+| 10 | emotion_008 | 闭嘴 | Silence |
+| 11 | emotion_009 | 睡 | Sleepy |
+| 12 | emotion_010 | 大哭 | Cry |
+| 13 | emotion_011 | 尴尬 | Awkward |
+| 14 | emotion_080 | 感谢 | Thanks |
+| 15 | emotion_204 | 拒绝 | SayNo |
+| 16 | emotion_078 | 赞 | Like |
+| 17 | emotion_024 | 鼓掌 | Clap |
+| 18 | emotion_105 | 打招呼 | Hi |
+| 19 | emotion_159 | 666 | 666 |
+| 20 | emotion_079 | 抱拳 | Salute |
+| 21 | emotion_025 | 握手 | Shake |
+| 22 | emotion_023 | OK | OK |
+| 23 | emotion_033 | 胜利 | Peace |
+| 24 | emotion_142 | 向左 | Left |
+| 25 | emotion_143 | 向右 | Right |
+| 26 | emotion_144 | 向上 | Up |
+| 27 | emotion_145 | 向下 | Down |
+| 28 | emotion_185 | 来呀 | Come |
+| 29 | emotion_155 | 一点点 | ALittle |
+| 30 | emotion_179 | 捏住 | Pinch |
+| 31 | emotion_140 | 比心 | FingerHeart |
+| 32 | emotion_106 | 送花花 | Flower |
+| 33 | emotion_178 | 加油干 | MakeEffort |
+| 34 | emotion_013 | 调皮 | Tongueout |
+| 35 | emotion_014 | 大笑 | Laugh |
+| 36 | emotion_015 | 惊讶 | Scowl |
+| 37 | emotion_016 | 流汗 | Sweat |
+| 38 | emotion_017 | 奋斗 | Fight |
+| 39 | emotion_018 | 口罩 | Mask |
+| 40 | emotion_019 | 生病 | Sick |
+| 41 | emotion_020 | 吐 | Barf |
+| 42 | emotion_021 | 难过 | Bummed |
+| 43 | emotion_022 | 抓狂 | Crazy |
+| 44 | emotion_026 | 右哼哼 | Humph |
+| 45 | emotion_027 | 太阳 | Sunny |
+| 46 | emotion_028 | 月亮 | Moon |
+| 47 | emotion_029 | 强 | Thumbsup |
+| 48 | emotion_030 | 弱 | Thumbsdown |
+| 49 | emotion_031 | 彩带 | Tada |
+| 50 | emotion_032 | 蛋糕 | Cake |
+| 51 | emotion_034 | 骷髅 | Skull |
+| 52 | emotion_035 | 撇嘴 | Pout |
+| 53 | emotion_037 | 鄙视 | Dislike |
+| 54 | emotion_038 | 嘘 | Shhh |
+| 55 | emotion_040 | 思考 | Hmm… |
+| 56 | emotion_041 | 亲亲 | Kiss |
+| 57 | emotion_042 | 无奈 | Disappointed |
+| 58 | emotion_043 | 感冒 | Pollution |
+| 59 | emotion_044 | 对不起 | Sorry |
+| 60 | emotion_045 | 再见 | Wave |
+| 61 | emotion_046 | 投降 | GiveUp |
+| 62 | emotion_047 | 哼 | Grumpy |
+| 63 | emotion_048 | 欠扁 | FaceSlap |
+| 64 | emotion_049 | 拜托 | Please |
+| 65 | emotion_050 | 可怜 | Aww… |
+| 66 | emotion_051 | 舒服 | Relax |
+| 67 | emotion_052 | 爱意 | Romantic |
+| 68 | emotion_054 | 财迷 | MoneyMoney |
+| 69 | emotion_055 | 迷惑 | Puzzled |
+| 70 | emotion_056 | 委屈 | Worried |
+| 71 | emotion_057 | 灵感 | Idea |
+| 72 | emotion_058 | 天使 | Angel |
+| 73 | emotion_059 | 鬼脸 | SillyFace |
+| 74 | emotion_060 | 凄凉 | Phew |
+| 75 | emotion_061 | 郁闷 | Tired |
+| 76 | emotion_063 | 坏笑 | Trick |
+| 77 | emotion_064 | 算账 | SoMuch |
+| 78 | emotion_206 | PK | PK |
+| 79 | emotion_066 | 忍者 | Sneaky |
+| 80 | emotion_039 | 衰 | Grr |
+| 81 | emotion_067 | 炸弹 | Uh-Oh |
+| 82 | emotion_081 | 笑哭 | LaughAndCry |
+| 83 | emotion_082 | 嘿嘿 | Smirk |
+| 84 | emotion_083 | 捂脸哭 | Facepalm |
+| 85 | emotion_084 | 抠鼻 | NosePick |
+| 86 | emotion_085 | 流鼻血 | BloodyNose |
+| 87 | emotion_090 | 呲牙 | Grin |
+| 88 | emotion_091 | 吃瓜 | EatingMelon |
+| 89 | emotion_092 | 彩虹 | Rainbow |
+| 90 | emotion_098 | 耶 | Yeah |
+| 91 | emotion_012 | 发怒 | Steamed |
+| 92 | emotion_100 | 捂眼睛 | CannotLook |
+| 93 | emotion_101 | 推眼镜 | PushGlasses |
+| 94 | emotion_102 | 暗中观察 | Peep |
+| 95 | emotion_103 | 脑暴 | Brainstorming |
+| 96 | emotion_112 | 冷笑 | Distressed |
+| 97 | emotion_208 | 热 | HotFace |
+| 98 | emotion_113 | 开心 | Happy |
+| 99 | emotion_114 | 惊喜 | Surprised |
+| 100 | emotion_115 | 回头 | LookBack |
+| 101 | emotion_116 | 白眼 | RollEyes |
+| 102 | emotion_117 | 一团乱麻 | Overwhelmed |
+| 103 | emotion_149 | 黑眼圈 | DarkCircle |
+| 104 | emotion_225 | 裂开 | Broken |
+| 105 | emotion_156 | 恭喜 | Congrats |
+| 106 | emotion_160 | 费解 | Confuse |
+| 107 | emotion_167 | 收到 | RogerThat |
+| 108 | emotion_186 | 快来 | ComeOn |
+| 109 | emotion_086 | 敲打 | Hammer |
+| 110 | emotion_176 | 捧脸 | HoldFace |
+| 111 | emotion_194 | Get | Get |
+| 112 | emotion_207 | 客服 | CustomerService |
+| 113 | emotion_210 | AR | AR |
+| 114 | emotion_221 | 小蜜蜂 | Bee |
+| 115 | emotion_211 | 虎虎生威 | MajesticTiger |
+| 116 | emotion_222 | 兔飞猛进 | Rabbit |
+| 117 | emotion_226 | 龙头老大 | Dragon Face |
+| 118 | emotion_236 | 蛇来运转 | Good luck |
+| 119 | emotion_238 | 马上来财 | Wealth is coming |
+| 120 | emotion_093 | 专注 | Concentrate |
+| 121 | emotion_166 | 忙疯了 | CrazyBusy |
+| 122 | emotion_187 | 等一等 | Wait |
+| 123 | emotion_227 | 一脸苦笑 | Wry Smile |
+| 124 | emotion_228 | 王之蔑视 | Unamused |
+| 125 | emotion_229 | 洪荒之力 | Amazing |
+| 126 | emotion_234 | 向左看 | Thinking |
+| 127 | emotion_235 | 向右看 | Pondering |
+| 128 | emotion_230 | YYDS | YYDS |
+| 129 | emotion_231 | 这边请 | ThisWayPlease |
+| 130 | emotion_232 | 弹射下班 | OffDuty |
+| 131 | emotion_233 | 退退退 | Back |
+| 132 | emotion_188 | 在吗 | Hello? |
+| 133 | emotion_189 | 让人头大 | Hard |
+| 134 | emotion_089 | 摊手 | Smugshrug |
+| 135 | emotion_088 | 抱抱 | Hug |
+| 136 | emotion_158 | 举手 | RaiseHand |
+| 137 | emotion_177 | 开车 | Driving |
+| 138 | emotion_191 | 抱大腿 | Follow |
+| 139 | emotion_087 | 跪了 | YouWin |
+| 140 | emotion_162 | 鞠躬 | Bow |
+| 141 | emotion_180 | 选我 | PickMe |
+| 142 | emotion_209 | 元气满满 | FullOfVitality |
+| 143 | emotion_168 | 会议 | Meeting |
+| 144 | emotion_095 | 猫咪 | Kitty |
+| 145 | emotion_094 | 二哈 | Doggy |
+| 146 | emotion_097 | 狗子 | Puppy |
+| 147 | emotion_111 | 三多 | SanDuo |
+| 148 | emotion_153 | 承让 | LetMeWin |
+| 149 | emotion_154 | 撒花 | Celebration |
+| 150 | emotion_070 | 礼物 | Present |
+| 151 | emotion_104 | 生日快乐 | Birthday |
+| 152 | emotion_071 | 爱心 | Love |
+| 153 | emotion_072 | 心碎 | BrokenHeart |
+| 154 | emotion_073 | 嘴唇 | Lips |
+| 155 | emotion_074 | 鲜花 | Rose |
+| 156 | emotion_075 | 残花 | Wilted |
+| 157 | emotion_077 | 干杯 | Cheers |
+| 158 | emotion_151 | 咖啡 | Coffee |
+| 159 | emotion_152 | 奶茶 | MilkTea |
+| 160 | emotion_202 | 茶 | Tea |
+| 161 | emotion_218 | OKR | OKR |
+| 162 | emotion_109 | KPI | KPI |
+| 163 | emotion_108 | 100分 | 100 |
+| 164 | emotion_110 | 对勾 | Check |
+| 165 | emotion_192 | 打叉 | Wrong |
+| 166 | emotion_174 | 气泡 | Bubble |
+| 167 | emotion_157 | 加一 | PlusOne |
+| 168 | emotion_193 | Done | Done |
+| 169 | emotion_146 | 钉子 | Staple |
+| 170 | emotion_076 | 出差 | BusinessTrip |
+| 171 | emotion_181 | 高铁 | HighSpeedTrain |
+| 172 | emotion_184 | 火箭 | Rocket |
+| 173 | emotion_068 | 邮件 | Mail |
+| 174 | emotion_163 | 文档 | Document |
+| 175 | emotion_164 | 演示 | Presentation |
+| 176 | emotion_165 | 表格 | Sheet |
+| 177 | emotion_213 | 废纸篓 | Wastebasket |
+| 178 | emotion_237 | 手机 | MobilePhone |
+| 179 | emotion_203 | 时间 | Time |
+| 180 | emotion_217 | 静音 | mute |
+| 181 | emotion_201 | 公文包 | Briefcase |
+| 182 | emotion_214 | 地球 | Earth |
+| 183 | emotion_215 | 碳减排 | CarbonReduction |
+| 184 | emotion_216 | 回收标志 | RecyclingSymbol |
+| 185 | emotion_205 | 幼苗 | Seedling |
+| 186 | emotion_096 | 红包 | RedPacket |
+| 187 | emotion_150 | 锦鲤 | LuckyDog |
+| 188 | emotion_148 | 福 | Luck |
+| 189 | emotion_198 | 灯笼 | Lantern |
+| 190 | emotion_199 | 爆竹 | Firecrackers |
+| 191 | emotion_197 | 烟花 | Fireworks |
+| 192 | emotion_195 | 恭喜发财 | Prosperity |
+| 193 | emotion_161 | 月饼 | MoonCake |
+| 194 | emotion_173 | 鸡腿 | ChickenLeg |
+| 195 | emotion_169 | 休假 | Vacation |
+| 196 | emotion_175 | 火 | Hot |
+| 197 | emotion_223 | 点赞 | LikeHeartAndTripleSix |
+| 198 | emotion_196 | 平安健康 | Peace&Health |
+| 199 | emotion_200 | 定胜 | Victory |
@@ -0,0 +1,140 @@
+# Chat 低频原子能力索引
+
+> 返回入口：[DingTalk Chat Skill](../SKILL.md)
+
+本文件只用于根 Skill 和精确 task reference 都未覆盖的低频底层能力。普通发送、读取、搜索、
+建群、引用回复和查看置顶会话必须回到根 Skill 的 Golden Route，不在这里重新选路。
+
+## 使用边界
+
+1. 先确认任务确实需要 Shortcut 未发布的底层字段、原始响应或运维控制；
+2. 读取精确原子 leaf Schema/Help，不加载产品级 Catalog 猜参数；
+3. 自然目标仍必须唯一解析，禁止选择搜索结果第一项；
+4. 原子写 leaf 的 confirmation 若与对应 Golden Shortcut 不一致，停止并报告交付漂移；
+5. 后续 ID 只使用当前 profile 的真实返回，不跨组织复用；
+6. 完成后保留原始结果、partial failure 和可继续编排的稳定 ID。
+
+## 高频任务返回表
+
+| 用户终点 | 返回入口 |
+|---|---|
+| 姓名/群名简单发送、文件、Bot、Webhook、复杂 @ | 根 Skill Golden Route |
+| 消息读取、条件搜索、@我、Favorite/reaction 查询和批量详情 | [message-query](chat/message-query.md) |
+| 编辑、撤回、引用、转发、reaction/Pin/Top/Favorite 写入 | [message-actions](chat/message-actions.md) |
+| 位置、名片、资源下载和特殊媒体 fallback | [message-media](chat/message-media.md) |
+| 群列表、群搜索、成员读取、Bot 列表和邀请链接 | [group-discovery](chat/group-discovery.md) |
+| 建群、改群、成员写入、管理员、禁言、公告和群设置 | [group-admin](chat/group-admin.md) |
+| 跨步骤消息/群组合流程 | [消息任务级流程](01-messaging.md) |
+| Bot 搜索、进群和撤回 | [chat-bot](chat/chat-bot.md) |
+| 会话置顶、状态和分组 | [chat-conversation](chat/chat-conversation.md) |
+| 话题与话题圈的创建、发布、浏览、回复、互动和整条转发 | [thread](chat/thread.md) |
+| 相邻低频意图仍需消歧 | [intent-guide](intent-guide.md) |
+
+## 消息底层能力
+
+| 原子命令 | 仅用于 |
+|---|---|
+| `chat message send` | `+messages-send` 尚未发布的位置、名片等真实底层消息类型 |
+| `chat message list` | 需要原始响应或显式手工 continuation；普通浏览使用 `+chat-messages` |
+| `chat message list-all` | 指定时间范围的原始全会话分页接口 |
+| `chat message list-by-sender` | 需要原始按发送者响应；普通组合搜索使用 `+search-msg` |
+| `chat message list-mentions` / `list-focused` | 精确的 @我或特别关注原始列表 |
+| `chat message search` / `search-advanced` | `+search-msg` 未发布的底层过滤字段或原始响应 |
+| `chat message query-send-status` | 使用真实 `openTaskId` 查询用户消息投递任务 |
+| `chat message recall` / `edit` | 撤回或编辑已知消息 |
+| `chat message read-status` | 查询已知消息的已读/未读状态 |
+| `chat message reply` | `+messages-reply` 未发布的底层引用字段，且安全门禁已对齐 |
+| `chat message forward` / `combine-forward` | Shortcut 未覆盖的精确转发字段 |
+| `chat message download-media` | Shortcut 无法消费的已知底层 mediaId/fileId 引用 |
+
+消息对象管理：
+
+| 原子命令 | 对象 |
+|---|---|
+| `message set-pin-msg` / `unset-pin-msg` / `list-pin-msg` | 消息 Pin |
+| `message set-top-msg` / `unset-top-msg` | 会话内消息 Top |
+| `message add-favorite` / `remove-favorite` / `list-favorites` | 当前用户 Favorite |
+| `message add-emoji` / `remove-emoji` | 默认 emoji reaction |
+| `message create-text-emotion` / `add-text-emotion` / `update-text-emotion` / `remove-text-emotion` | 文字表情 |
+| `message list-emotion-replies` | 批量 reaction/文字回应 |
+| `emotion list` / `send` / `favorite` | 当前用户个人收藏表情列表、发送和新增 |
+
+Favorite、消息 Pin、消息 Top 与会话 Top 是四种对象，不能互换。
+个人收藏表情与消息 reaction/文字回应不同；发送收藏表情使用 `chat emotion send`，给已有消息贴表情使用 `chat message add-emoji` 或 `chat message add-text-emotion`。
+
+## 群与成员底层能力
+
+| 原子命令 | 用途 |
+|---|---|
+| `chat search` / `search-common` | 群管理前解析唯一群、查询共同群 |
+| `chat group get-by-group-id` | 数字群号转 `openConversationId` |
+| `chat group create` | `+chat-create` 尚未发布的真实底层创建字段；显式群主已由 Shortcut 覆盖 |
+| `chat group members` / `members list-by-ids` | 群成员分页和精确详情 |
+| `chat group members add` / `remove` | 添加/移除已知成员 ID |
+| `chat group members add-bot` / `remove-bot` / `group bots` | 机器人进群、移除和列表 |
+| `chat group rename` / `update-icon` | 群名和群头像 |
+| `chat group transfer-owner` / `set-admin` | 群主和管理员 |
+| `chat group upgrade-to-external` | 普通群升级外部群；不可逆 |
+| `chat group invite-url` / `share-invite` | 群邀请链接及分享 |
+| `chat group update-settings` / `user-settings query|set` | 管理员群开关或当前用户群偏好 |
+| `chat group update-nick` / `update-alias` | 当前用户群昵称和群备注 |
+| `chat group set-history` | 新成员历史消息可见范围 |
+| `chat group-mute` / `group-mute-member` | 全员或指定成员禁言 |
+| `chat group notice create|edit|get|list` | 群公告 |
+| `chat group list-my-groups` / `list-all` | 当前用户相关群列表 |
+| `chat group list-join-validations` / `audit-join-validation` | 入群审批 |
+| `chat group-role *` | 群身份定义与成员分配 |
+
+退出、解散群、踢人、转让群主、升级外部群、禁言、管理员和公告写入都属于高影响操作；
+必须以最终 Runtime gate/Schema 为准确认对象与影响。
+
+## Bot 与 Webhook 底层能力
+
+| 原子命令 | 用途 |
+|---|---|
+| `chat bot search` | 搜索当前用户创建的机器人并取得 `robotCode` |
+| `chat bot find` | 搜索可用机器人并取得机器人 `openDingTalkId` |
+| `chat message send-by-bot` | `+messages-send --as bot` 未发布的真实底层字段，包括机器人群聊引用回复的 `--reply` / `--ref-sender` |
+| `chat message recall-by-bot` | 使用 `processQueryKey` 撤回机器人消息 |
+| `chat message send-by-webhook` | `+messages-send --as webhook` 未发布的真实底层字段 |
+
+新发送流程统一使用 `+messages-send`。不得因看见 bot/webhook 原子命令就绕开统一身份能力矩阵。
+
+## 会话状态与分组
+
+| 原子命令 | 用途 |
+|---|---|
+| `chat conversation-info` | 已知稳定用户/群 ID 的会话详情 |
+| `chat list-all-conversations` | 全部会话原始分页列表 |
+| `chat list-top-conversations` | 需要原始响应时的置顶会话 fallback；普通查看使用 `+conversation-list-top` |
+| `chat set-top` | 设置/取消整个会话置顶 |
+| `chat mute` / `hide` / `mute-at-all` / `mute-red-envelope` | 会话通知与可见状态 |
+| `chat mark-unread` / `mark-read` | 会话未读或消息已读状态 |
+| `chat clear-red-point` / `clear-all-red-point` | 清除会话红点 |
+| `chat clear-messages` | 清空当前用户视角的会话记录 |
+| `chat category *` | 自定义/智能会话分组 |
+
+消息 Top 使用 `message set-top-msg`，整个会话 Top 使用 `chat set-top`，查看置顶会话使用
+`+conversation-list-top`。
+
+## 稳定 ID 传递
+
+| 来源 | 只可用于 |
+|---|---|
+| 唯一群解析 / `+chat-create` | 当前 profile 下的 `openConversationId` |
+| 唯一人员解析 | 当前 profile 下的 `userId` / `openDingTalkId` |
+| `+messages-send` | `openTaskId` 查询投递状态；它不是消息 ID |
+| `+chat-messages` / `+search-msg` / `+messages-mget` | 回复、转发、撤回、资源操作使用的真实消息/会话/thread ID |
+| `chat bot search` | `robotCode`；不能当机器人 `openDingTalkId` |
+| `chat message send-by-bot` | `processQueryKey` 用于机器人撤回；群聊引用回复还需消息查询返回的 `openMessageId` 与原发送者 `openDingTalkId` |
+
+显式稳定 ID 当前不携带可验证的 profile provenance；调用方必须保证来源，不得宣称所有
+跨 profile 误用都会在本地写入前被拦截。
+
+## 故障处理
+
+- `unknown command` / `unknown flag`：读取精确 leaf Help，最多修正一次；
+- confirmation 或参数约束不清：读取精确 leaf Schema，以最终 Runtime gate 为准；
+- 自然目标零命中/多候选：停止并展示候选，不选择第一项；
+- 权限、认证或 profile：按 `dingtalk-shared` 对应 reference 分流；
+- partial result：保留已完成项、失败 ledger、continuation 和真实错误，不换同义原子命令重试。
@@ -0,0 +1,187 @@
+# chat-bot：机器人与 Webhook
+
+> 返回入口：[chat.md](../chat.md)
+
+## 适用场景
+
+用于搜索机器人、机器人发送/撤回消息、Webhook 告警、机器人加入/移出群，以及给机器人发单聊消息。
+
+<!-- dws-intent: chat.send.advanced -->Bot/Webhook 默认统一使用 `dws chat +messages-send`，通过
+`--as bot|webhook` 选择身份；原子发送命令只保留 Shortcut 未发布字段的底层 fallback。
+
+## 必读约束
+
+- 用户明确要求“用机器人/机器人身份/robot”发送时，使用
+  `dws chat +messages-send --as bot --robot-code <robotCode>`；不得改成当前用户身份。
+- `chat bot search` 只返回我创建的机器人，没有 `openDingTalkId`；给机器人发单聊必须用 `chat bot find`。
+- 机器人发群消息前需确认机器人已在群中；报“机器人不存在”时先 `group members add-bot`。
+- `send-by-bot` 支持 Markdown、图片 URL 和文件，具体参数见下方消息类型路由。
+- 机器人在群聊中引用回复已有消息时，使用原子命令 `send-by-bot --reply --ref-sender`；该能力仅支持 Markdown，不走 `+messages-reply` 的当前用户身份。
+- 公网图片 URL 使用 `--msg-type image --image-url`，按图片消息发送。
+- 本地图片和其他本地文件一样使用 `--msg-type file --file-path`，由 CLI 上传并按文件附件发送。
+- 群聊传 `--group`；单聊可传 `--users`、`--open-dingtalk-ids` 或两者组合。
+- Markdown 必须同时传 `--title` 和 `--text`；需要稳定换行时用空行分隔段落。若以转义形式组织文本，写 `\n\n`，不要只写 `\n`。
+- `recall-by-bot` 使用 `processQueryKey`，不是 `openMessageId`。
+- Bot 多群文本/Markdown 直接使用 `+messages-send --groups <cid...>` 或
+  `--groups-file <工作目录内相对文件>`；最多 100 个稳定 ID，Runtime 去重并返回
+  `im.batch-write.v1` 逐目标 ledger。
+- `+messages-send` 的 Bot 路由和 Webhook 没有与 current-user 等价的文件、图片、音视频发送接口；
+  机器人富媒体必须使用原子 `chat message send-by-bot`，不得转成文本或换身份静默发送。
+
+## 命令明细
+
+### 机器人搜索
+
+| 命令 | 范围 | 返回 openDingTalkId | 典型触发词 |
+|------|------|---------------------|------------|
+| `chat bot search` | 仅当前用户自己创建的机器人 | 否 | “我的机器人”“我创建的机器人” |
+| `chat bot find` | 当前用户可用的全部机器人（含他人/官方） | 是 | “找机器人”“搜索机器人”“给机器人发单聊” |
+
+```bash
+dws chat bot search --page 1 --size 10 --name "日报"
+dws chat bot find --query "日报" --limit 20
+dws chat bot find --query "日报" --limit 20 --cursor <nextCursor>
+```
+
+`bot find` 翻页时 `cursor` 必须使用上次返回的 `nextCursor` 字符串原值，不要传 `"0"` 或数字字面量。
+
+### 机器人发送与撤回
+
+多群正式入口：
+
+```bash
+dws chat +messages-send --as bot --robot-code <robot-code> \
+  --groups <openConversationId1>,<openConversationId2> \
+  --markdown "## 通知\n\n请提交周报" --format json
+```
+
+读取 `requestedCount/succeededCount/failedCount/results/failures`；unknown 或失败目标不自动重发。
+
+#### `dws chat message send-by-bot`（底层 fallback）
+
+普通文本/Markdown、群聊/批量单聊和 @ 已由 `+messages-send --as bot` 覆盖。只有 Shortcut
+缺失真实必需字段且精确 leaf Schema 允许时才使用以下原子命令。
+
+```bash
+# 群聊
+dws chat message send-by-bot --robot-code <robot-code> --conversation-id <openConversationId> --title "日报" --text "## 今日完成\n\n- 事项 A\n\n- 事项 B"
+dws chat message send-by-bot --robot-code <robot-code> --conversation-id <openConversationId> --reply <openMessageId> --ref-sender <senderOpenDingTalkId> --text "收到"
+dws chat message send-by-bot --robot-code <robot-code> --conversation-id <openConversationId> --msg-type image --image-url "https://example.com/image.png"
+dws chat message send-by-bot --robot-code <robot-code> --conversation-id <openConversationId> --msg-type file --file-path ./report.pdf
+
+# 单聊 userId
+dws chat message send-by-bot --robot-code <robot-code> --users userId1,userId2 --title "提醒" --text "请提交周报"
+
+# 单聊 openDingTalkId
+dws chat message send-by-bot --robot-code <robot-code> --open-dingtalk-ids openDingTalkId1,openDingTalkId2 --title "提醒" --text "请提交周报"
+
+# 群聊 @ 人
+dws chat message send-by-bot --robot-code <robot-code> --group <openConversationId> --at-user-ids userId1,userId2 --title "提醒" --text "@userId1 @userId2 请查收"
+dws chat message send-by-bot --robot-code <robot-code> --group <openConversationId> --at-open-dingtalk-ids openDingTalkId1,openDingTalkId2 --title "提醒" --text "@openDingTalkId1 @openDingTalkId2 请查收"
+dws chat message send-by-bot --robot-code <robot-code> --group <openConversationId> --at-all --title "通知" --text "请所有人注意"
+```
+
+关键 flags：
+
+| Flag | 说明 |
+|------|------|
+| `--robot-code` | 机器人 Code，必填 |
+| `--conversation-id` | 群聊 openConversationId；`--group` 为兼容别名 |
+| `--users` | 单聊 userId 列表，逗号分隔，最多 20 个 |
+| `--open-dingtalk-ids` | 单聊 openDingTalkId 列表 |
+| `--msg-type` | `markdown`、`image` 或 `file`；省略时为 Markdown；公网图片使用 `image --image-url`，本地图片和文件使用 `file --file-path` |
+| `--text` | Markdown 消息内容，Markdown 模式必填；换行用空行，转义表示为 `\n\n` |
+| `--title` | 普通 Markdown 消息标题；引用回复省略时由 CLI 从正文生成 |
+| `--image-url` | 公网图片 URL，`--msg-type image` 时必填 |
+| `--file-path` | 本地图片或文件路径，`--msg-type file` 时由 CLI 上传并按文件附件发送 |
+| `--at-user-ids` / `--at-open-dingtalk-ids` | 群聊 @ 指定成员，正文需含对应 `@id` 文本 |
+| `--at-all` | 群聊 @所有人 |
+| `--reply` | 被引用消息的 `openMessageId`；仅群聊 Markdown，必须与 `--ref-sender` 同时使用 |
+| `--ref-sender` | 被引用消息发送者的 `openDingTalkId`；仅群聊 Markdown，必须与 `--reply` 同时使用 |
+
+引用回复不会设置 `msgType=reply`；CLI 在普通群消息参数顶层透传 `referenceOpenMessageId` 和 `srcMsgSendOpenDingTalkId`。只传其中一个参数、用于单聊或用于图片/文件消息都会在本地失败。
+
+#### `dws chat message recall-by-bot`
+
+```bash
+dws chat message recall-by-bot --robot-code <robot-code> --group <openConversationId> --keys <processQueryKey>
+dws chat message recall-by-bot --robot-code <robot-code> --keys key1,key2
+```
+
+群聊撤回传 `--group`；单聊撤回不传 `--group`。`--keys` 来自 `send-by-bot` 返回的 `processQueryKey`。
+
+### Webhook
+
+默认使用：
+
+```bash
+dws chat +messages-send --as webhook --webhook-token <webhook-token> --title "告警" --text "CPU 超 90% @10" --at-all
+```
+
+以下是底层 fallback，不作为默认选路：
+
+```bash
+dws chat message send-by-webhook --token <webhook-token> --title "告警" --content "CPU 超 90% @10" --at-all
+dws chat message send-by-webhook --token <webhook-token> --title "test" --content "hi @118785" --at-users 118785
+```
+
+关键规则：
+
+- `--token`、`--title`、`--content` 必填。
+- `--at-all` 时 `--content` 中需包含 `@10`。
+- `--at-users` 或 `--at-mobiles` 时，`--content` 中需包含对应 `@userId` 或 `@手机号`，否则 @ 不生效。
+
+### 机器人进群
+
+| 命令 | 用途 | 必填参数 |
+|------|------|----------|
+| `group members add-bot` | 将自定义机器人加入群 | `--id` `--robot-code` |
+| `group members remove-bot` | 从群移除机器人 | `--id` `--bot-id` |
+| `+chat-bots` | 查看群内机器人列表 | `--group <群名或openConversationId>`；自然群名内部唯一解析 |
+
+```bash
+dws chat group members add-bot --id <openConversationId> --robot-code <robot-code>
+dws chat +chat-bots --group "项目群"
+dws chat group members remove-bot --id <openConversationId> --bot-id <openBotId>
+```
+
+## 常见工作流
+
+### 机器人发消息后撤回
+
+```bash
+dws chat bot search --name "日报" --format json
+dws chat +messages-send --as bot --robot-code <robot-code> --group <openConversationId> --title "日报" --markdown "## 今日完成\n\n- 事项 A\n\n- 事项 B" --format json
+dws chat message recall-by-bot --robot-code <robot-code> --group <openConversationId> --keys <processQueryKey> --format json
+```
+
+### 机器人不在群内时先邀请再发送
+
+```bash
+dws chat bot search --name "日报" --format json
+dws chat group members add-bot --id <openConversationId> --robot-code <robot-code> --format json
+dws chat +messages-send --as bot --robot-code <robot-code> --group <openConversationId> --title "通知" --text "内容" --format json
+```
+
+### 给机器人发单聊
+
+```bash
+dws chat bot find --query "玉澜" --format json
+dws chat message send --open-dingtalk-id <openDingTalkId> --content "你好" --format json
+```
+
+### 机器人 @ 指定人
+
+```bash
+dws aisearch person --query "张三" --dimension name --format json
+dws chat +messages-send --as bot --robot-code <robot-code> --group <openConversationId> --at-user-ids userId1 --title "提醒" --text "@userId1 请查收" --format json
+```
+
+## 常见错误与回退
+
+- 机器人单聊没有 openDingTalkId：改用 `chat bot find`，不要用 `bot search`。
+- 机器人发群消息报“机器人不存在”：先 `group members add-bot`。
+- 撤回失败：确认使用 `processQueryKey`，不是 `openMessageId`。
+- 机器人引用回复失败：确认目标是群聊 Markdown，且 `--reply` 来自被引用消息的 `openMessageId`、`--ref-sender` 来自同一消息的发送者 `openDingTalkId`。
+- @ 不生效：检查正文是否包含 `@userId` / `@openDingTalkId` / `@10`。
+- 需要 Bot 图片/文件/音视频：停止并说明当前身份矩阵不支持；只有用户明确同意改为当前用户身份时，才重新确认目标和内容。
@@ -0,0 +1,154 @@
+# chat-conversation：会话状态、红点、置顶与分组
+
+> 返回入口：[chat.md](../chat.md)
+
+## 适用场景
+
+用于获取会话基础信息、全部会话/置顶会话列表、会话置顶、免打扰、隐藏、红点、已读未读、清空聊天记录、自定义会话分组和智能会话分组。
+
+- <!-- dws-intent: chat.conversation.list-top -->查看置顶会话默认使用 `dws chat +conversation-list-top`；
+  原子 `list-top-conversations` 只在需要原始响应时作为 fallback。
+- <!-- dws-intent: chat.read.conversation -->取得目标会话后读取或导出消息记录，默认使用 `dws chat +chat-messages`；
+  可附带非必填的 `--sender-query` 解析姓名：唯一解析成功后按 `senderId` 筛选同一次读取结果；
+  解析失败、不完整或存在歧义时抑制未过滤消息并返回 `sender_resolution_failed`。不要回到原子
+  `message list`，也不要补跑 `+search-msg`。直接条件检索优先使用 `+search-msg`。
+
+## 必读约束
+
+- 会话状态类命令通常需要 `openConversationId`。群聊只用 `+chat-search --query` 获取唯一候选，单聊可由 `chat conversation-info --user/--open-dingtalk-id` 获取。
+- `set-top` 是会话置顶；`message set-top-msg` 是会话内消息置顶，二者不能混用。
+- `clear-messages` 只清空当前用户视角的消息，不影响其他成员。
+- 智能分组规则中的成员使用 openDingTalkId；如果用户只给姓名，先用 `aisearch person --dimension name` 获取。
+
+## 命令明细
+
+### 会话基础信息
+
+```bash
+dws chat conversation-info --group <openConversationId> --format json
+dws chat conversation-info --user <userId> --format json
+dws chat conversation-info --open-dingtalk-id <openDingTalkId> --format json
+```
+
+`--group`、`--user`、`--open-dingtalk-id` 互斥且必须指定一个。文件/音视频发送不再依赖调用方读取 spaceId；直接用 `message send --msg-type file|audio|video --file`。
+
+### 会话列表与红点
+
+| 命令 | 用途 | 参数 |
+|------|------|------|
+| `+conversation-list` | 获取当前用户会话 | 要求“全部”时加 `--page-all`；检查 `complete` / `failures` |
+| `+chat-list` | 列出当前用户会话（默认群聊，可选单聊） | 默认只返回群聊；`--types group,p2p` 可包含单聊；要求全部时加 `--page-all`，合并去重后再过滤类型 |
+| `+chat-list-all` | 获取当前用户加入的全部群 | 要求全部时加 `--page-all`；沿数字 `nextCursor` 去重聚合 |
+| `+my-groups` | 获取并投影当前用户加入的群 | 要求全部时加 `--page-all`；读完后再应用 `--type` 本地过滤 |
+| `+conversation-list-top` | 获取置顶会话列表 | 可选 `--limit` `--cursor` `--exclude-muted`；使用稳定 `conversations[]` |
+| `message list-unread-conversations` | 获取未读会话列表 | 可选 `--count` `--exclude-muted` |
+| `clear-red-point` | 清除指定会话红点 | `--conversation-id`，别名 `--id` / `--chat` |
+| `clear-all-red-point` | 清除所有会话红点，一键全部已读 | 无参数 |
+
+翻页时，`hasMore=true` 用返回的 `nextCursor` 作为下次 `--cursor`。Shortcut 全量读取应检查
+`complete`、`stopReason` 和 `failures`；达到 `--page-limit` 时会保留可继续的 `nextCursor`。
+
+### 会话置顶与通知
+
+| 命令 | 用途 | 必填参数 |
+|------|------|----------|
+| `set-top` | 设置/取消会话置顶 | `--conversation-id`；默认置顶，`--off` 取消 |
+| `mute` | 开启/关闭会话免打扰 | `--conversation-id`；默认开启，`--off` 关闭 |
+| `hide` | 隐藏会话 | `--conversation-id` |
+| `mute-at-all` | 关闭/恢复 @所有人通知 | `--conversation-id`；默认关闭，`--off` 恢复；必须先开启会话总免打扰 |
+| `mute-red-envelope` | 关闭/恢复红包通知 | `--conversation-id`；默认关闭，`--off` 恢复；必须先开启会话总免打扰 |
+
+若连续操作两个子开关，优先操作红包通知；恢复 @所有人通知后，平台可能清除子开关所需的
+总免打扰状态，此时要先重新开启总免打扰，再操作红包通知。
+
+```bash
+dws chat set-top --conversation-id <openConversationId>
+dws chat set-top --conversation-id <openConversationId> --off
+dws chat mute --conversation-id <openConversationId>
+dws chat mute --conversation-id <openConversationId> --off
+dws chat hide --conversation-id <openConversationId>
+```
+
+### 已读未读与清理
+
+| 命令 | 用途 | 必填参数 |
+|------|------|----------|
+| `mark-unread` | 标记指定会话为未读 | `--conversation-id` |
+| `mark-read` | 将指定消息及之前消息标记为已读 | `--conversation-id` `--message-id` |
+| `clear-messages` | 清空当前用户指定会话的消息 | `--conversation-id` |
+
+```bash
+dws chat mark-unread --conversation-id <openConversationId>
+dws chat mark-read --conversation-id <openConversationId> --message-id <openMessageId>
+dws chat clear-messages --conversation-id <openConversationId>
+```
+
+### 会话分组
+
+| 命令 | 用途 | 必填参数 |
+|------|------|----------|
+| `category list` | 获取用户自定义会话分组 | 无 |
+| `category list-conversations` | 拉取指定分组下会话 | `--category-id`，可选 `--exclude-muted` |
+| `category list-by-conv` | 拉取指定会话所属的用户自定义会话分组 | `--group` |
+| `category batch-info` | 批量拉取用户自定义会话分组信息 | `--category-ids` |
+| `category create` | 创建会话分组 | `--title` |
+| `category create-smart` | 创建智能会话分组，可按群名称关键词和群内成员匹配 | `--name`，可选 `--keywords` `--members` |
+| `category delete` | 删除会话分组 | `--category-id` |
+| `category rename` | 修改分组名称 | `--category-id` `--title` |
+| `category add-conv` | 将会话加入分组 | `--group` `--category-ids` |
+| `category remove-conv` | 将会话移出分组 | `--group` `--category-ids` |
+
+```bash
+dws chat category list
+dws chat category list-by-conv --group <openConversationId>
+dws chat category batch-info --category-ids 123,456
+dws chat category create --title "工作群"
+dws chat category create-smart --name "重点群" --keywords "重点,项目" --members openDingTalkId1,openDingTalkId2
+dws chat category add-conv --group <openConversationId> --category-ids 123,456
+```
+
+`create-smart` 中 `--keywords` 是群名称关键词列表，`--members` 是群内成员 openDingTalkId 列表；两者可单独使用，也可组合使用。
+
+## 常见工作流
+
+### 获取单聊会话 ID 后置顶
+
+```bash
+dws aisearch person --query "张三" --dimension name --format json
+dws chat conversation-info --user <userId> --format json
+dws chat set-top --conversation-id <openConversationId> --format json
+```
+
+### 查看置顶会话并拉消息
+
+```bash
+dws chat +conversation-list-top --limit 100 --format json
+dws chat +chat-messages --group <openConversationId> --time "2026-03-10 00:00:00" --direction older --format json
+```
+
+### 会话分组
+
+```bash
+dws chat category create --title "重点项目" --format json
+dws chat category add-conv --group <openConversationId> --category-ids <categoryId> --format json
+dws chat category list-by-conv --group <openConversationId> --format json
+dws chat category batch-info --category-ids <categoryId> --format json
+dws chat category list-conversations --category-id <categoryId> --format json
+```
+
+### 智能会话分组
+
+```bash
+dws aisearch person --query "张三" --dimension name --format json
+dws chat category create-smart --name "项目组" --keywords "项目,开发" --format json
+dws chat category create-smart --name "团队群" --members openDingTalkId1,openDingTalkId2 --format json
+dws chat category create-smart --name "重点群" --keywords "重点" --members openDingTalkId1 --format json
+```
+
+## 常见错误与回退
+
+- 用户说“置顶消息”：用 `message set-top-msg`，不是 `chat set-top`。
+- 用户说“置顶会话”：设置/取消用 `chat set-top`，查看列表用 `+conversation-list-top`。
+- 单聊没有会话 ID：先 `conversation-info --user` 或 `--open-dingtalk-id`。
+- 清空聊天记录前必须确认目标会话；该操作只影响当前用户视角。
+- 智能分组没有匹配条件：至少确认分组名称；关键词和成员规则不明确时先向用户确认，不要自行猜成员。
@@ -0,0 +1,144 @@
+# group-admin：群创建、成员写入与管理
+
+> 返回入口：[DingTalk Chat Skill](../../SKILL.md)
+
+用于建群、修改群资料、成员增删、邀请卡片分享、群主和管理员、禁言、公告、群设置、
+入群审批、群身份、退出、解散和升级外部群。只读群发现、成员读取和邀请链接使用
+[group-discovery.md](group-discovery.md)。
+
+## 安全与目标
+
+- 群目标统一使用当前 profile 下真实 `openConversationId`；支持自然群名的 Shortcut 由 CLI
+  唯一解析，多候选时停止。
+- 解散群、踢人、转让群主、禁言、管理员和外部群升级都是高影响操作；以最终 Runtime gate
+  和精确 leaf Schema 为准确认对象、动作与影响。
+- 所有自然成员和群主必须先完成唯一解析并按稳定 ID 去重，再开始任何写入；不得边解析边
+  产生部分副作用。
+- 群公告会触达成员；`notice edit` 是整体替换，必须有完整新正文。
+
+## 建群与基础资料
+
+<!-- dws-intent: chat.create.group -->基础建群使用 `dws chat +chat-create`。已知成员 ID 传 `--users`，
+姓名/花名传 `--member-query`；群主默认当前用户，也可传 `--owner-open-dingtalk-id` 或
+`--owner-query`。任一自然身份未唯一解析时，创建前整体停止。
+
+```bash
+dws chat +chat-create --name "项目冲刺群" --member-query "测试用户甲,测试用户乙" --format json
+dws chat +chat-create --name "合作群" --member-query "测试用户甲" \
+  --owner-query "测试用户乙" --type EXTERNAL --format json
+```
+
+修改群名称优先使用接受群名或稳定 ID 的 `+chat-update`：
+
+```bash
+dws chat +chat-update --group <群名或openConversationId> --name "新群名" --format json
+```
+
+群头像和管理员级群开关使用 `+chat-update-icon`、`+chat-update-settings`；只有 Shortcut
+尚未发布真实必需字段时才评估原子 `group rename/update-icon/update-settings`。
+
+原子 `chat group create` 只用于 `+chat-create` 未发布的真实底层字段，并先读取精确 leaf
+Schema。普通内部/外部群、话题群和显式群主已经由 `+chat-create` 覆盖，不回流到手工
+`aisearch → group create` 链路。
+
+## 成员与机器人写入
+
+| 动作 | 入口与关键参数 |
+|---|---|
+| 添加成员 | `group members add --id <cid> --users <userIds>` |
+| 移除成员 | `group members remove --id <cid> --users <userIds>` |
+| 添加已知机器人 | `+chat-add-bot` 或精确原子 `group members add-bot` |
+| 查看群内机器人 | `+chat-bots --group <群名或cid>` |
+| 移除群内机器人 | `+chat-remove-bot` 或精确原子 `group members remove-bot` |
+
+普通成员增删的 `--users` 只接受组织 `userId`，必须来自真实人员解析结果；不得把
+`+chat-members-list` / `+chat-members-get` 返回的 `openDingTalkId` 直接传入。添加已知机器人
+使用 `robotCode`；移除机器人使用当前群 `+chat-bots` 返回的真实 `openBotId`，两者不能互换。
+缺少 `openBotId` 时在同一流程中先执行 `+chat-bots`，不必额外读取群发现 reference。只有需要
+搜索未知机器人、区分 `bot search` / `bot find`、机器人发送或撤回、Webhook 时，才读取
+[chat-bot.md](chat-bot.md)。
+
+## 邀请卡片、群主、管理员与禁言
+
+邀请链接只读走 `+chat-invite-url`。实际分享邀请卡片使用 `group share-invite`：`--source`
+是被分享群，接收端在 `--target` 会话和 `--receiver` 单聊用户之间二选一。
+
+```bash
+dws chat group share-invite --source <sourceCid> --target <targetCid> --format json
+dws chat group share-invite --source <sourceCid> --receiver <openDingTalkId> --format json
+```
+
+| 动作 | 入口与关键参数 |
+|---|---|
+| 转让群主 | `+chat-transfer-owner --group <cid> --new-owner <稳定ID>` |
+| 设置/取消管理员 | `group set-admin --group <cid> --users <ids> [--off]` |
+| 全员禁言/解除 | `group-mute --group <cid> [--off]` |
+| 成员禁言/解除 | `+chat-mute-member` 或 `group-mute-member` |
+| 查询禁言配置 | `group get-mute-config --group <cid>` |
+
+原子 `group-mute-member --mute-time` 单位为毫秒。不要用展示名称代替稳定用户 ID，也不要
+在未确认影响时执行转让、踢人或禁言。
+
+## 群设置与当前用户偏好
+
+管理员级群开关使用 `+chat-update-settings` 或原子 `group update-settings`。常见 settingKey
+包括 `authority`、`joinValidation`、`onlyAdminCanAtAll`、`searchable`、
+`addFriendForbidden`、`onlyAdminCanDING`、`onlyAdminCanPinMsg` 和
+`onlyAdminCanSendFile`、`groupEmailDisabled`、`groupLiveAuthority`、
+`groupBillAuthority`；只修改用户明确要求的字段。
+
+新成员历史消息可见范围使用 `group set-history --group <cid> --option <值>`；`option` 只取
+精确 leaf Schema 发布值，不按自然语言猜枚举。
+
+当前登录用户自己的置顶、免打扰、群昵称和群备注使用 `group user-settings query/set`，
+不是管理员群开关。单个群昵称/备注优先 `group update-nick/update-alias`。
+
+```bash
+dws chat group user-settings query --groups <cid1>,<cid2> --format json
+dws chat group user-settings set \
+  --items '[{"openConversationId":"cid1","top":true,"mute":false}]' --format json
+```
+
+批量设置只传本次要改的字段；空字符串清除昵称或备注，不补用户未要求的值。
+
+## 群公告
+
+| 动作 | 原子入口 |
+|---|---|
+| 发布公告 | `group notice create --group <cid> --content <完整Markdown>` |
+| 修改公告 | `group notice edit --group <cid> --notice-id <id> --content <完整Markdown>` |
+| 查询公告 | `group notice get/list` |
+
+定时公告 `--run-at` 使用带时区时间；`notice list --scheduled` 查询待发布公告。分页时沿真实
+`nextPageCursor` 继续。修改前必须取得完整替换正文，不把增量片段当整篇公告。
+
+## 入群审批与群身份
+
+先用 `group list-join-validations` 取得真实 `record-id/applicant/inviter`，再执行
+`group audit-join-validation` 或 `+chat-audit-join`。审批状态只使用精确 leaf Schema 发布值。
+
+群身份使用 `group-role` / `+chat-role-*`：
+
+- `list/add/update/remove` 管理身份定义；
+- `set-user/remove-user/query-user` 管理成员身份；
+- `openRoleId` 必须来自真实身份列表。
+
+覆盖或清除成员身份前确认用户、群和完整角色集合，不能用展示名称猜 `openRoleId`。
+
+## 退出、解散与外部群升级
+
+- 当前用户退出群：`+chat-quit` 或精确原子 `group quit`。
+- 解散群：`group dismiss`，不可逆。
+- 普通群升级外部群：`group upgrade-to-external`，不可逆。
+
+这些动作必须以最终 Runtime gate 为准，不把示例中的确认参数当固定事实。
+
+## 完成与错误
+
+- 创建或更新后保留真实 `openConversationId` 和任务结果；只对查询结果真实返回的字段执行读回验证。
+- 写接口成功但现有查询未返回目标设置时，报告真实写入回执和不可独立读回的边界；不用群名、
+  成员数等其他字段代替验证，也不猜未发布的读回命令。
+- 任一自然目标零命中或多候选时，在写入前整体停止。
+- 逐项写入保留 succeeded/failed/unknown ledger，不用重试抹掉失败项。
+- 分享邀请时 `--target` 与 `--receiver` 只能二选一；接收对象不明确时先确认。
+- 机器人进群失败时确认机器人身份和当前用户管理权限，不连续切换同义原子命令。
@@ -0,0 +1,121 @@
+# group-discovery：群发现、列表与成员读取
+
+> 返回入口：[DingTalk Chat Skill](../../SKILL.md)
+
+用于只读的群列表、群搜索、共同群、群成员、群机器人和邀请链接。建群、改群、成员增删、
+邀请卡片分享、公告、禁言和其他群管理写操作读取 [group-admin.md](group-admin.md)。
+
+## 入口选择
+
+| 用户终点 | 唯一推荐入口 |
+|---|---|
+| 我加入的全部群 | `dws chat +my-groups --page-all` |
+| 我创建或管理的群 | `dws chat +chat-list-mine` |
+| 只看群主群或管理员群 | `+chat-list-mine --role OWNER|ADMIN` |
+| 按关键词搜索群 | `dws chat +chat-search --query <关键词>` |
+| 查看指定群全部成员 | `dws chat +chat-members-list --group <群名或ID>` |
+| 已知成员 openDingTalkId 批量查群内详情 | `dws chat +chat-members-get --id <cid> --users <ids>` |
+| 获取群邀请链接 | `dws chat +chat-invite-url --group <群名或ID>` |
+| 查看群机器人 | `dws chat +chat-bots --group <群名或ID>` |
+
+“全部群”与“全部会话”不同：`+my-groups` 只列当前用户加入的群；
+`+conversation-list --page-all` 可能同时包含单聊和群聊，不能替代群成员关系。
+
+## 群列表、分页与角色
+
+`+my-groups` 返回当前用户加入的群，包括作为群主、管理员和普通成员加入的群：
+
+- 要求完整列表时使用 `--page-all`；Runtime 沿真实 `nextCursor` 读取后续页，并按
+  `openConversationId` 合并去重，读完后再应用可选 `--type` 本地过滤。
+- `--limit` 是每页数量，不是最终结果上限；`--cursor` 只用于从已有 `nextCursor` 手工续读。
+- `--page-limit` 只与 `--page-all` 一起使用，用于限制最多读取页数。达到上限后仍有下一页时，
+  结果不完整。
+- 只有 `complete=true` 且 `hasMore=false` 才能声称已经读取全部；否则保留 `nextCursor`、
+  `stopReason` 和 `failures` 并说明结果不完整。
+
+```bash
+dws chat +my-groups --page-all --page-limit 50 --format json
+```
+
+`+chat-list-mine` 只返回当前用户作为群主或管理员的群。只要群集合时不传 `--role`，
+一次取得 OWNER 和 ADMIN。要求逐项标明身份时，直接分别查询 `--role OWNER` 和
+`--role ADMIN`，不先执行无角色查询或读取 Help；按 `openConversationId` 合并去重后，
+再应用一次全局数量上限，不得把两个分支直接拼接。
+
+```bash
+dws chat +chat-list-mine --limit 20 --format json
+dws chat +chat-list-mine --role OWNER --format json
+dws chat +chat-list-mine --role ADMIN --exclude-muted --format json
+```
+
+`+my-groups` 不提供当前用户角色。用户明确要求普通成员群时，使用
+`chat group list-all --limit 200`；返回 `hasMore=true` 时，必须把真实 `nextCursor`
+传给下一次调用并继续读取，直到 `hasMore=false`，不得把继续翻页交给用户。读完后按
+`openConversationId` 去重，仅筛选真实返回的 `myRole=普通成员`；不得给 `+my-groups`
+编造 `--role MEMBER`，也不得用“全部群减去 OWNER/ADMIN 群”推断。
+
+## 群搜索与稳定 ID
+
+群搜索默认使用 `+chat-search`。要求全部候选时加 `--page-all`；可用
+`--page-size/--page-token` 或兼容 `--limit/--cursor`。零命中或多候选时停止并展示候选，
+不要选择第一项。
+
+```bash
+dws chat +chat-search --query "项目冲刺" --page-all --format json
+```
+
+只有数字群号时，使用 `chat group get-by-group-id --group-id <数字>` 转换为
+`openConversationId`。需要搜索共同群时使用原子 `chat search-common`；`AND` 表示所有人
+都在群里，`OR` 表示任一人在群里。自然人员必须先解析为当前 profile 的真实身份。
+
+```bash
+dws chat search-common --nicks "测试用户甲,测试用户乙" --match-mode AND --limit 20 --cursor 0
+```
+
+## 群成员
+
+`+chat-members-list` 接受群名或 `openConversationId`，唯一解析后全量读取，并把用户与机器人
+分桶。结果必须检查 `buckets/complete/failures`。
+
+```bash
+dws chat +chat-members-list --group "项目群" --format json
+dws chat +chat-members-list --conversation-id <openConversationId> --format json
+```
+
+先检查 `+chat-members-list` 的稳定结果。只有结果未包含用户要求的群昵称、角色或其他群内字段时，
+才使用其中的真实 `openDingTalkId` 批量调用：
+
+```bash
+dws chat +chat-members-get --id <openConversationId> \
+  --users <openDingTalkId1>,<openDingTalkId2> --format json
+```
+
+不要为了群内详情默认切换到企业通讯录；只有用户明确要求部门、岗位、直属主管等企业资料时，
+才把真实 userId 交给 `dingtalk-contact`。
+
+## 邀请链接与机器人
+
+`+chat-invite-url` 是只读获取链接，可选 `--expires-seconds`；`group share-invite` 会实际把
+邀请卡片发送给另一个会话或用户，属于 [group-admin.md](group-admin.md)。
+
+`+chat-bots` 返回稳定 `bots[]` 和 `openBotId`，供后续移除。搜索可用机器人、机器人发送和
+撤回读取 [chat-bot.md](chat-bot.md)。
+
+## 原子 fallback
+
+| 原子命令 | 仅用于 |
+|---|---|
+| `chat search` / `search-common` | Shortcut 未发布的搜索字段或共同群 |
+| `chat group get-by-group-id` | 数字群号转换 |
+| `chat group members` | 需要原始成员分页响应 |
+| `chat group members list-by-ids` | 需要原始批量成员详情 |
+| `chat group list-all` / `list-my-groups` | 需要 Shortcut 未投影的真实底层字段 |
+
+使用原子 fallback 前读取精确 leaf Schema；不得把 fallback 写成与 Shortcut 并列的默认路线。
+
+## 完成与错误
+
+- 分页完成只以真实 `complete/hasMore/nextCursor/failures` 判断，不看过滤后的 `count` 猜测。
+- 所有稳定 ID 必须来自同一 profile 的真实返回。
+- 找不到群或出现多候选时停止，不臆测 `openConversationId`。
+- 任务从只读发现转为写操作时，使用 [group-admin.md](group-admin.md) 的目标和安全规则。
@@ -0,0 +1,132 @@
+# message-actions：消息编辑、撤回、回复与对象操作
+
+> 返回入口：[DingTalk Chat Skill](../../SKILL.md)
+
+用于对真实消息执行编辑、撤回、引用回复、转发、Pin、Top、Favorite 和表情回应写操作，
+并包含必要的紧邻验证。需要跨多个阶段传递真实结果的组合流程由
+[01-messaging.md](../01-messaging.md) 说明；本文件不重复完整工作流。
+
+## 入口选择
+
+| 用户终点 | 推荐入口 |
+|---|---|
+| 撤回当前用户消息 | `dws chat +messages-recall --msg-id <openMessageId>` |
+| <!-- dws-intent: chat.reply.quote -->引用回复 | `dws chat +messages-reply` |
+| 编辑已发送消息 | `dws chat message edit` |
+| 单条/合并/话题转发 | `+messages-forward` / `+messages-combine-forward` / `+messages-forward-topic` |
+| Pin / Unpin | `+messages-set-pin` / `+messages-unset-pin` |
+| 消息 Top / 取消 Top | `+messages-set-top` / `+messages-unset-top` |
+| Favorite / 取消 Favorite | `+flag-create` / `+flag-cancel` |
+| 默认 emoji 回应 | `+messages-add-emoji` / `+messages-remove-emoji` |
+
+所有写操作以最终 Runtime gate 和精确 leaf Schema 为准。确认对象、消息和影响后再执行；
+不要因为文档示例自行制造或省略 confirmation。
+
+## 稳定 ID 规则
+
+- `openTaskId` 是发送任务 ID，不是消息 ID。
+- 撤回、编辑、回复、转发、Pin、Top 和 reaction 使用真实查询结果中的 `messageId`。
+- 同时保留消息的 `conversationId`、thread、发送者和引用上下文。
+- 子消息使用自己的 `messageId`；只在缺会话 ID 时继承父消息 `conversationId`。
+- Bot 撤回使用 `processQueryKey`，不使用本文件的 `openMessageId` 路线。
+
+刚由用户身份发送的消息如果只得到 `openTaskId`，先查询发送状态：
+
+```text
+messages-send 或 message send
+→ openTaskId
+→ message query-send-status
+→ openMessageId + openConversationId
+→ 编辑或撤回
+```
+
+## 撤回与编辑
+
+`+messages-recall` 可只传 `--msg-id`；省略会话 ID 时 CLI 会通过只读消息详情补齐。
+兼容单值 `--message-ids`，但不要把 `processQueryKey` 当消息 ID。
+
+```bash
+dws chat +messages-recall --msg-id <openMessageId> --format json
+dws chat +messages-recall --conversation-id <openConversationId> --msg-id <openMessageId> --format json
+```
+
+编辑使用 `message edit --conversation-id <cid> --msg-id <id>`，并在 `--text` 与 `--content`
+中二选一。`--text` 由 CLI 生成 Markdown content；`--content` 必须是完整 content JSON。
+
+```bash
+dws chat message edit --conversation-id <openConversationId> --msg-id <openMessageId> --text "更新后的内容"
+dws chat message edit --conversation-id <openConversationId> --msg-id <openMessageId> --content '{"title":"标题","text":"更新后的内容"}'
+```
+
+群聊 @所有人使用 `--at-all`；指定人员使用 `--at-open-dingtalk-ids`。正文中的占位符以
+Runtime 规范化结果为准，不把裸展示名当稳定身份。
+
+## 引用回复与转发
+
+引用回复默认使用 `+messages-reply`。`--group` 和消息 ID 来自真实查询；
+`--ref-sender` 可省略时让 CLI 只读补齐，不手工猜发送者身份。
+
+```bash
+dws chat +messages-reply --group <openConversationId> \
+  --message-id <openMessageId> --content "收到" --format json
+```
+
+| 动作 | 入口 | 关键上下文 |
+|---|---|---|
+| 单条转发 | `+messages-forward` | 源消息 ID、源会话、目标会话 |
+| 合并转发 | `+messages-combine-forward` | 多个真实消息 ID、源/目标会话 |
+| 话题转发 | `+messages-forward-topic` | 源消息、源会话、源 thread、目标会话 |
+
+只有 Shortcut 尚未发布真实必需字段时，才评估原子 `message reply`、`forward`、
+`combine-forward` 或 `forward-topic`，并先读取精确 leaf Schema。不要复制正文伪装原生转发。
+
+## Pin、Top 与 Favorite
+
+| 对象 | 写入入口 | 说明 |
+|---|---|---|
+| 消息 Pin | `+messages-set-pin` / `+messages-unset-pin` | 作用于一条消息 |
+| 消息 Top | `+messages-set-top` / `+messages-unset-top` | 作用于会话内一条消息 |
+| Favorite | `+flag-create` / `+flag-cancel` | 当前用户收藏 |
+| 会话 Top | `+conversation-set-top` | 作用于整个会话，不属于本文件 |
+
+用户要求确认 Pin 已生效时，使用 `+messages-list-pin` 检查真实结果中的 `messageId`；取消 Pin
+后仅在用户要求确认取消结果时再次查询。典型短链为：`+messages-set-pin` →
+`+messages-list-pin` → `+messages-unset-pin`。
+
+需要原子 fallback 时，消息 Pin 对应 `message set-pin-msg/unset-pin-msg`，消息 Top 对应
+`message set-top-msg/unset-top-msg`，Favorite 对应 `message add-favorite/remove-favorite`。
+四种对象不能互换，即使用户都使用“收藏、钉住、置顶”等自然语言。
+
+## 表情回应
+
+优先在 [chat-emoji-list.md](../chat-emoji-list.md) 按表情名称查默认 emoji，不必全文理解表格。
+
+| 场景 | 入口 |
+|---|---|
+| 添加/移除默认 emoji | `+messages-add-emoji` / `+messages-remove-emoji` |
+| 默认表情无合适项时创建文字表情 | `+messages-create-text-emotion` |
+| 添加/移除文字表情 | `+messages-add-text-emotion` / `+messages-remove-text-emotion` |
+| 替换文字表情 | `message update-text-emotion` |
+
+reaction 查询属于 [message-query.md](message-query.md)，不要为了查看回应执行写命令。
+
+## 流式卡片与文本工具
+
+流式卡片使用根 Skill 直接链接的 [card/create.md](../card/create.md)、
+[card/update.md](../card/update.md) 和 [card/schema.md](../card/schema.md)；本文件不复制卡片参数。
+
+纯文本翻译使用：
+
+```bash
+dws chat text translate --query "你好世界" --to en_US
+```
+
+用户只要求翻译文本时不要误走消息发送。
+
+## 完成与错误
+
+- 写操作检查任务级结果、投递状态和失败项，不只看退出码。
+- 投递状态 unknown 时保留幂等键，不自动换目标重发。
+- `unknown flag` 时读取精确 leaf Help，最多修正一次。
+- 目标消息不存在、会话不匹配或发送者上下文缺失时停止，不猜 ID。
+- 已知稳定消息 ID 的单一动作及其紧邻验证均在本文件完成。
@@ -0,0 +1,76 @@
+# message-media：特殊消息与资源下载
+
+> 返回入口：[DingTalk Chat Skill](../../SKILL.md)
+
+只用于位置、联系人名片、底层 mediaId/fileId 和消息资源下载。普通文本、Markdown、文件、
+图片、音频和视频发送继续按根 Skill 使用 `+dm`、`+send-to-group` 或 `+messages-send --file`，
+不读取本文件。
+
+## 默认边界
+
+- 用户身份普通文件/音视频：`dws chat +messages-send --as user --file <相对路径>`。
+- 已知资源引用单独下载：`dws chat +messages-resource-download`。
+- 从消息中定位并下载资源：在定位消息的 `+chat-messages`、`+search-msg` 或
+  `+messages-mget` 同一次调用中加 `--download-resources`。
+- 只有 Shortcut 尚未发布的位置、联系人名片或真实底层媒体字段，才使用原子 fallback。
+
+<!-- dws-intent: chat.send.advanced -->`dws chat +messages-send` 的 user 文件能力不能外推给 Bot/Webhook；
+机器人富媒体边界读取 [chat-bot.md](chat-bot.md)，不得静默改成当前用户身份。
+
+## 位置与联系人名片
+
+位置消息必须确认纬度、经度、地址名称和地图缩略图 mediaId：
+
+```bash
+dws chat message send --conversation-id <openConversationId> --msg-type location \
+  --latitude <纬度> --longitude <经度> --location-name <地址名称> \
+  --map-thumbnail-url "@mediaId"
+```
+
+联系人名片的 `--contact-id` 必须是联系人 `openDingTalkId`，不能把 userId 直接代入：
+
+```bash
+dws chat message send --conversation-id <openConversationId> \
+  --msg-type profile --contact-id <openDingTalkId>
+```
+
+用户要求真实发送结果时，保留发送返回的 `openTaskId`，再执行：
+
+```bash
+dws chat message query-send-status --open-task-id <openTaskId> --format json
+```
+
+检查真实 `sendStatus`、`openMessageId` 和 `openConversationId`。
+
+原子 `message send` 只在 Shortcut 缺少真实必需字段时使用。群聊目标用 `--conversation-id`；单聊目标
+用 `--user` 或 `--open-dingtalk-id`，三者通常互斥。发送前核对接收对象、消息类型和资源来源。
+
+## 资源下载
+
+公开 `+messages-resource-download` 使用工作目录内安全相对路径，默认不覆盖；完整文件先写入
+临时落盘再原子发布。覆盖必须由用户显式传 `--overwrite`，读取和下载不需要 `--yes`。
+
+任务要求从某条消息中定位并下载资源时，优先在限定会话、消息或时间范围的查询中加
+`--download-resources --output-dir <目录>`，并检查下载 ledger。`+messages-resource-download`
+只用于已经持有完整、真实且属于当前组织/profile 的独立资源引用、无需再定位消息的场景。
+若 `fileId` 返回 `RESOURCE_NOT_FOUND`，不得把同一个 ID 改称 `mediaId` 重试，也不得原样
+重复调用；应回到消息查询并使用 `--download-resources`。
+
+底层 fallback：
+
+```bash
+dws chat message download-media --type mediaId --resource-id <mediaId> \
+  --message-id <openMessageId> --open-conversation-id <openConversationId> \
+  --output ./downloads/
+```
+
+`resource-id`、`message-id` 和会话 ID 必须来自同一 profile 下的真实消息查询结果。
+当前没有 Range/断点续传；失败时保留 ledger 或错误，显式重试整个文件，不拼接残片。
+
+## 完成与错误
+
+- 查询并下载时同时检查消息完整性和每项下载 ledger；单项失败不抹掉已取得消息。
+- 文件/音视频发送失败先确认工作目录内相对路径可读，不恢复独立上传再提取 mediaId 的旧默认链路。
+- 位置参数不完整时先向用户确认，不猜经纬度或缩略图。
+- 名片发送失败时确认 `--contact-id` 是 openDingTalkId。
+- 下载目标存在时默认停止；只有用户明确允许覆盖时才传 `--overwrite`。
@@ -0,0 +1,135 @@
+# message-query：消息读取、搜索与查询
+
+> 返回入口：[DingTalk Chat Skill](../../SKILL.md)
+
+用于浏览或导出指定会话、按条件搜索消息、按消息 ID 读取详情、查看 @我、话题回复、
+Favorite、Pin 和 reaction。只读任务优先使用 Shortcut；只有 Shortcut 未发布所需底层字段、
+原始响应或手工 continuation 时才读取精确原子 leaf Schema。
+
+## 入口选择
+
+| 用户终点 | 唯一推荐入口 |
+|---|---|
+| <!-- dws-intent: chat.read.conversation -->浏览或导出一个指定群聊/单聊 | `dws chat +chat-messages` |
+| <!-- dws-intent: chat.search.filtered -->发送者、关键词、@对象或消息类型是主要条件 | `dws chat +search-msg` |
+| 已知消息 IDs 读取详情 | `dws chat +messages-mget` |
+| 查看 @我的消息 | `dws chat +at-me` |
+| 查看 Favorite | `dws chat +flag-list` |
+| 已知话题主消息或 thread/topic ID 读取回复 | `dws chat +thread-replies` |
+
+`+chat-messages` 是指定会话的粗粒度读取；`+search-msg` 是目标条件明确的单/跨会话检索。
+不要先读完整会话再补跑搜索，也不要把群名或姓名直接填入只接受稳定 ID 的参数。
+
+## 指定会话读取
+
+群聊 `--group` 可传群名或 `openConversationId`；也可用 `--chat-query` 显式解析群名、
+用 `--conversation-id` 显式传稳定 ID。单聊使用 `--user` 或 `--open-dingtalk-id`。
+
+```bash
+dws chat +chat-messages --group <群名或openConversationId> --format json
+dws chat +chat-messages --group <openConversationId> --page-all --page-limit 50 --format json
+```
+
+可附带非必填的 `--sender-query <姓名>`：未传时返回全部消息；唯一解析出
+userId/openDingTalkId 后，按消息 `senderId` 筛选同一次读取结果，覆盖最终
+`messages/count` 并返回 `resolvedFilters`。解析失败、不完整或存在歧义时抑制未过滤消息，
+返回 `sender_resolution_failed`，不得把全量消息当作发送者筛选结果。
+
+`--sender` 是姓名、userId 或 openDingTalkId 的混合入口。通讯录无法确认输入类型时，可按
+原值 userId 精确过滤并交付命中消息，但结果必须保留 `identity_unverified`，不得把字符串命中
+升级为已验证身份，也不得据此作完整否定结论。
+
+```bash
+dws chat +chat-messages --group "项目群" --sender-query "测试用户甲" --page-all --format json
+```
+
+时间范围使用公开可选的 `--start`、`--end`、`--order asc|desc`，兼容别名为
+`--start-time/--end-time/--sort`。范围为 `[start,end)`；仅开始时间表示到本次执行当前时间；
+仅结束时间只支持 `desc`，`asc` 必须提供开始时间。旧 `--time/--direction` 只用于兼容的
+单边界模式，不能与范围模式混用。
+
+```bash
+dws chat +chat-messages --group <openConversationId> \
+  --start "2026-08-01T00:00:00+08:00" --end "2026-08-02T00:00:00+08:00" \
+  --order asc --page-all --format json
+```
+
+完整读取后只需消息字段可判断的子集时，在同一次调用中使用全局 `--jq`，保留根信封并
+同步改写 `messages/count`；不得丢失 `complete`、`hasMore`、`failures` 等 ledger。
+发送者姓名仍使用 `--sender-query` 解析稳定身份，不用 `--jq` 比较展示名。
+
+```bash
+dws chat +chat-messages --group "项目群" --page-all --format json \
+  --jq '. as $root | [.messages[] | select((.reactions // []) | length > 0)] as $matched | $root | .messages = $matched | .count = ($matched | length)'
+```
+
+要求导出时用 `--output <工作目录内相对.json>` 原子写入；需要资源时在读取命令上加
+`--download-resources`，不要让 Agent 先输出全量 JSON 再手工遍历资源引用。
+
+## 多维度搜索
+
+- 关键词使用公开 `--query`。
+- 已知稳定会话 ID 使用 `--group` / `--groups`；稳定发送者 ID 使用 `--senders`。
+- 只有群名时使用 `--chat-query`，由 CLI 唯一解析会话。
+- 只有发送者姓名时使用 `--sender-query`，由 CLI 唯一解析人员。
+- 不传会话过滤时搜索全部会话；默认时间范围为最近 7 天。
+- `--page-all` 只翻完当前时间范围内的游标页；精确范围使用成对的 `--start/--end`。
+- `--order` 只稳定排列已经取得的结果；未全量或 `complete=false` 时不得称为完整范围全局排序。
+
+```bash
+dws chat +search-msg --chat-query "项目群" --sender-query "测试用户甲" --page-all --format json
+dws chat +search-msg --chat-query "项目群" --query "发布计划" --page-all --format json
+dws chat +search-msg --sender-query "测试用户甲" --page-all --format json
+```
+
+需要 Shortcut 未发布的原始过滤字段或响应时，才评估 `message search-advanced`。它支持
+发送者、@对象、多个会话、消息类型、会话类型、机器人消息和时间范围，但不是默认入口。
+至少提供一种真实过滤条件，完整遍历只有 `--page-all` 会触发。
+
+## 其他查询
+
+### 已知消息、@我与话题回复
+
+- `+messages-mget --msg-ids <id...>`：最多 50 条；结果可直接用于回复、转发、撤回和资源下载。
+- `+at-me [--group <群名或ID>] --page-all`：群内或跨全部会话查看 @我的消息。
+- `+thread-replies --message-id <rootMessageId>`：自动只读解析 conversation/thread。
+- `+thread-replies --group <cid> --thread-id <threadId>`：显式稳定上下文。
+
+话题回复默认 `desc`；`asc` 必须与 `--page-all` 一起使用。自动续页使用下层毫秒级
+`nextCursor`，不得使用只有秒精度的展示时间手工拼 continuation。检查 `complete`、
+`hasMore`、`stopReason` 和 `failures`。
+
+### Favorite、Pin 与 reaction 查询
+
+| 任务 | 入口 |
+|---|---|
+| Favorite 列表 | `+flag-list`；要求全部时加 `--page-all`，页大小 1–30 |
+| 消息 Pin 列表 | `message list-pin-msg --open-conversation-id <cid>` |
+| 批量 reaction/文字回应 | `message list-emotion-replies --msg-ids <id...>` |
+| 已读/未读状态 | `message read-status --group <cid> --message-id <id>` |
+
+Favorite、消息 Pin、消息 Top 和会话 Top 是不同对象。写入或取消这些状态读取
+[message-actions.md](message-actions.md)，这里只负责查询。
+
+## 原子 fallback
+
+| 原子命令 | 仅用于 |
+|---|---|
+| `message list` | 指定会话原始响应或显式手工 continuation |
+| `message list-all` | 时间范围内全部会话的原始分页响应 |
+| `message list-by-sender` | 已有稳定发送者 ID 且需要底层原始响应 |
+| `message list-mentions` / `list-focused` | @我或特别关注的原始列表 |
+| `message search` / `search-advanced` | Shortcut 未发布的真实过滤字段 |
+| `message list-by-ids` | 已知消息 ID 的原始详情响应 |
+
+Typed `chat message` 自动翻页只由 `--page-all` 触发；只传 `--page-limit`、`--max-items`
+或 `--page-delay` 仍是单页。非第一页失败时保留 partial 结果、失败页和 continuation，不能
+把 partial result 表述成完整成功。
+
+## 完成与错误
+
+- 查询必须检查 `complete`、`hasMore`、`stopReason`、`failures` 和下载 ledger。
+- 发送者/群名零命中或多候选时停止，不选择第一项。
+- `unknown flag` 时读取精确 leaf Help，修正后最多重试一次。
+- 子消息优先使用自己的 `messageId`；只在缺会话 ID 时继承父消息的 `conversationId`。
+- 查到真实消息后需要写操作时，使用 [message-actions.md](message-actions.md) 中的稳定 ID 规则。
@@ -0,0 +1,43 @@
+# 话题与话题圈
+
+> 返回入口：[DingTalk Chat Skill](../../SKILL.md)
+
+话题（Thread）是一条主消息及其回复线，可以位于普通群或话题圈中，使用 `openConvThreadId` 标识；承载话题的父群使用 `openConversationId`。命令沿用拆分前 `chat group` / `chat message` 的参数名称。只有需要新建话题圈时才使用 `create-group`，已有群中的话题可直接使用其余 `chat thread` 命令。
+
+## 入口选择
+
+| 用户终点 | 推荐入口 |
+|---|---|
+| 已有稳定成员 ID 创建话题圈 | `dws chat thread create-group --name <名称> --users <userId,...>` |
+| 发布新话题 | `dws chat thread send --conversation-id <openConversationId>` |
+| 浏览话题主消息 | `dws chat thread list --conversation-id <openConversationId>` |
+| 向具体话题直接追加回复 | `dws chat thread reply --conversation-id <openConvThreadId>` |
+| 分页读取一个话题的回复 | `dws chat thread list-replies --conversation-id <openConversationId> --topic-id <openConvThreadId>` |
+| 转发整条话题 | `dws chat thread forward --src-msg-id <openMessageId> --src-conversation-id <openConversationId> --src-thread-id <openConvThreadId> --dest-conversation-id <openConversationId>` |
+| 撤回话题中的一条消息 | `dws chat thread recall-message --conversation-id <openConversationId> --message-id <openMessageId>` |
+| 添加或移除 emoji | `dws chat thread add-emoji` / `remove-emoji` |
+| 查询 Thread 消息的表情回复 | `dws chat thread list-emotion-replies --msg-ids <openMessageId,...>` |
+| 添加、移除或更新文字表情 | `dws chat thread add-text-emotion` / `remove-text-emotion` / `update-text-emotion` |
+
+## 发布、回复与读取
+
+`thread send` 的 `--conversation-id` 是承载话题的会话 `openConversationId`，用于发布新的顶层话题。
+
+`thread reply` 沿用原发送命令的 `--conversation-id`，但这里传 Thread 子会话的 `openConvThreadId`。它直接追加回复，不使用消息引用回复，也不创建新的顶层 Thread。
+
+已有父会话 `openConversationId` 和 Thread `openConvThreadId` 且只需读取一页时，使用 `thread list-replies --conversation-id ... --topic-id ...`。需要按主消息自动解析、全量翻页、排序或下载资源时，使用 `+thread-replies` Shortcut。
+
+用户需要逐条查看、列出或概括具体回复内容时，使用 `thread list-replies`；只浏览话题主消息时使用 `thread list`。需要自动读取全部页面、排序或下载资源时，使用 `+thread-replies` Shortcut。
+
+整条 Thread 可转发到普通群；当前不支持从话题圈向另一个话题圈转发整条 Thread。
+
+## 消息操作
+
+撤回、emoji 和文字表情命令沿用对应 `chat message` 命令的主参数。Runtime 会先读取消息并校验其属于 Thread，再执行操作；批量查询会逐条校验 `--msg-ids`。文字表情的 `emotionId`、`backgroundId`、名称和文字使用 `chat message create-text-emotion` 返回的实际值；移除时使用已添加的值，更新时用 `--old-emotion-id` 传当前值、其余表情参数传新值。
+
+## 完成与错误
+
+- 创建话题圈返回真实群会话结果，不额外制造 `openTopicId` 字段。
+- 发布和回复沿用异步发送结果；`openTaskId` 是任务 ID，后续消息操作需要从发送状态或消息查询中取得真实消息 ID。
+- Thread 主消息和回复均保留 `openConvThreadId`，父容器继续使用 `openConversationId`。
+- 标识缺失、类型不明或消息不属于 Thread 时停止，不猜 ID。
@@ -0,0 +1,70 @@
+# IM 稳定契约与能力边界
+
+本页只记录需要跨命令复用的 Runtime 契约。下面四个 marker 区块由
+`check-multi-im-skill-chain.sh` 对照 Go typed descriptor 逐字校验；修改能力时先改 Runtime、
+测试与 descriptor，再同步本页。命令参数仍以精确 leaf Schema 为准。
+
+## 消息结果 `im.message-list.v1`
+
+`+chat-messages`、`+search-msg`、`+messages-mget` 及相关消息读取使用同一兼容版本。
+字段可能为空，但不能换名猜测；全量任务必须结合完整性 ledger 判断。
+
+<!-- DWS_MESSAGE_RESULT_CONTRACT_START -->
+- `version`: `im.message-list.v1`
+- `message_fields`: `messageId`, `conversationId`, `threadId`, `sender`, `senderId`, `senderType`, `messageType`, `text`, `createTime`, `updateTime`, `reactions`, `quotedMessage`, `forwarded`, `resourceRefs`
+- `envelope_fields`: `contractVersion`, `messages`, `count`, `resolvedFilters`, `queryRange`, `pagesFetched`, `paginationKnown`, `complete`, `hasMore`, `nextPage`, `stopReason`, `truncated`, `truncatedByPageLimit`, `truncatedByResultLimit`, `failedCount`, `failures`, `partial`, `scope`, `resourceDownloads`
+<!-- DWS_MESSAGE_RESULT_CONTRACT_END -->
+
+当 `complete=false` 时不能称为全量成功。`nextPage` 只能来自真实 lower boundary；
+`failedCount/failures`、`partial`、总 `truncated` 和两个原因字段必须原样保留。
+当 Runtime 解析并应用自然发送者条件时，`resolvedFilters.senders[]` 保留原查询及选中的
+`userId/openDingTalkId`。消息展示名可以与通讯录姓名不同；只能用稳定 `senderId` 与解析结果关联，
+不得重新做姓名字符串比较。
+
+当查询声明时间范围或顺序时，`queryRange` 保留规范化的 `startTime`、`endTime`、`order` 与
+`semantics=[start,end)`。排序只覆盖本次实际取得的 `messages`；`complete=false` 时不得把它描述为完整范围的全局排序。
+
+## `+messages-send` 身份矩阵
+
+<!-- DWS_IDENTITY_CAPABILITY_CONTRACT_START -->
+| identity | targets | content types | natural targets | mention targets | idempotency keys | batch ledger |
+|---|---|---|---|---|---:|---:|
+| `user` | `group`<br>`direct-user`<br>`direct-open-dingtalk-id` | `text`<br>`markdown`<br>`image-media-id`<br>`file`<br>`audio-as-file`<br>`video-as-file` | `chat-query`<br>`user-query` | `open-dingtalk-id`<br>`all` | `true` | `false` |
+| `bot` | `group`<br>`groups`<br>`direct-users`<br>`direct-open-dingtalk-ids` | `text`<br>`markdown` | — | `user-id`<br>`open-dingtalk-id`<br>`all` | `false` | `true` |
+| `webhook` | `token-owned-group` | `text`<br>`markdown` | — | `user-id`<br>`mobile`<br>`all` | `false` | `false` |
+<!-- DWS_IDENTITY_CAPABILITY_CONTRACT_END -->
+
+Bot 多群用 `--groups` 或 `--groups-file`，Runtime 去重后输出
+`im.batch-write.v1` 逐目标 ledger。Bot/Webhook 不支持的内容类型会在写前失败，不能降级为
+另一身份或偷偷改成纯文本。
+
+## 流式卡片
+
+<!-- DWS_CARD_WORKFLOW_CONTRACT_START -->
+- `version`: `im.streaming-card.v1`
+- `targets`: `group`, `direct-user`, `direct-open-dingtalk-id`
+- `content_types`: `streaming-text`
+- `flow_statuses`: `1=processing`, `2=typing`, `3=completed`, `4=executing`, `5=error`
+- `callback_supported`: `false`
+<!-- DWS_CARD_WORKFLOW_CONTRACT_END -->
+
+发送目标与状态范围由 Runtime 校验。当前不是 Lark Card JSON 编译器，也不消费按钮 callback；
+具体创建和更新流程见 `card/` 下的精确 reference。
+
+## 正向能力与负向边界
+
+<!-- DWS_CAPABILITY_BOUNDARY_CONTRACT_START -->
+| capability | supported | current route / boundary |
+|---|---:|---|
+| `thread-write` | `false` | quote reply with +messages-reply; thread reading with +thread-replies |
+| `bot-rich-media` | `false` | bot text/markdown, or current-user file/image send |
+| `card-action-callback` | `false` | streaming text card create/update only |
+| `resource-resume` | `false` | atomic whole-file download with explicit retry |
+| `group-member-full-pagination` | `true` | +chat-members-list or +group-members |
+| `group-owner-selection` | `true` | +chat-create owner flags |
+<!-- DWS_CAPABILITY_BOUNDARY_CONTRACT_END -->
+
+`supported=false` 是执行门禁，不是待猜测字段。只有 lower interface、Runtime、测试、Schema 和
+此页同时升级后，才能改变对外承诺。
+
+话题圈会话仍禁止引用消息回复；向 Thread 追加回复使用 `chat thread reply --conversation-id <openConvThreadId>`。
@@ -0,0 +1,56 @@
+# Chat 低频意图消歧
+
+只在根 Skill 的 Golden Route 无法区分相邻能力时读取。命令 flags 和安全语义以精确 leaf Schema/Runtime 为准。
+
+## 消息选择
+
+| 用户终点 | 选择 | 不要混用 |
+|---|---|---|
+| 给姓名发简单文本 | `+dm` | 先查人再原子发送 |
+| 给群名发简单文本 | `+send-to-group` | 先搜群再原子发送 |
+| 文件、Bot、Webhook、复杂 @、幂等 | `+messages-send` | 为不同身份各走一套原子入口 |
+| 读取或导出指定会话，可附带发送者姓名 | `+chat-messages`；姓名用非必填 `--sender-query` | 解析成功后读后筛选；解析失败抑制未过滤消息并返回错误；不补跑搜索 |
+| 直接按发送者、关键词、@对象或消息类型搜索 | `+search-msg` | 条件检索优先，可限定单个或跨多个会话 |
+| 已知消息 IDs 取详情 | `+messages-mget` | 重新搜索关键词 |
+| @我的消息 | `+at-me` | 全量消息后本地猜测 @ |
+| 已知 thread/topic ID 的回复 | `+thread-replies` | 普通消息列表 |
+| 引用回复一条消息 | `+messages-reply` | 普通发送 |
+| 单条/合并/话题转发 | `+messages-forward` / `+messages-combine-forward` / `+messages-forward-topic` | 复制正文重新发送 |
+| 流式卡片创建或更新 | `+messages-send-card` / `+messages-update-card` | 普通 text/Markdown 发送 |
+
+## Topic 选择
+
+话题与话题圈的创建、发布、浏览、回复、互动和整条转发统一读取 [thread.md](chat/thread.md)，不从普通消息入口选路。
+
+## 对象层级
+
+| 用户终点 | 对象 | Reference |
+|---|---|---|
+| 收藏或取消收藏 | 当前用户的 Favorite | [message-actions.md](chat/message-actions.md) |
+| Pin/Unpin 一条消息 | 消息 Pin | [message-actions.md](chat/message-actions.md) |
+| 置顶/取消置顶一条消息 | 消息 Top | [message-actions.md](chat/message-actions.md) |
+| 置顶/取消置顶整个会话 | 会话 Top | [chat-conversation.md](chat/chat-conversation.md) |
+| 查看置顶会话 | 会话列表 | `+conversation-list-top` |
+| 标记消息已读 | 消息读取状态 | [message-actions.md](chat/message-actions.md) |
+| 清红点、标记会话未读 | 会话状态 | [chat-conversation.md](chat/chat-conversation.md) |
+
+Favorite、消息 Pin、消息 Top 和会话 Top 不能互换，即使用户都说“收藏/钉住/置顶”。
+
+## 群与机器人
+
+| 用户终点 | 选择 |
+|---|---|
+| 已有成员 IDs 创建群 | `+chat-create` |
+| 查群、查看成员、邀请链接 | [group-discovery.md](chat/group-discovery.md) |
+| 加人、踢人、管理员、群公告、群设置 | [group-admin.md](chat/group-admin.md) |
+| 找可用机器人并取得单聊 ID | `chat bot find`，不是只查自己创建机器人的 `bot search` |
+| 已知 robotCode 发送 | `+messages-send --as bot` |
+| 机器人入群、移除、批量群发或撤回 | [chat-bot.md](chat/chat-bot.md) |
+
+## 跨产品边界
+
+- 紧急 DING、短信或电话：切 `dingtalk-misc`，不要当普通 Chat 消息。
+- 邮件：切 `dingtalk-mail`。
+- 只查询人员资料或把姓名解析成 ID：切 `dingtalk-contact`；若终点只是简单发消息，直接留在 Chat 使用 `+dm`。
+- 企业知识跨文档、消息、邮件搜索：切 `dingtalk-aisearch`；明确只搜聊天消息时使用 `+search-msg`。
+- 文档翻译先由文档产品读取正文；`chat text translate` 只处理纯文本。