dsh-crwu-workbench 0.0.10

package/skills/dws/dingtalk-chat/SKILL.md

@@ -0,0 +1,127 @@
+---
+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 发现（按需）
+
+`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 conversation-file upload --conversation-id <cid> --file <路径>`；返回文件 ID，仅本地路径 |
+| 按关键词搜索群 | `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 <路径>`；只存会话空间、不发消息才用 `chat conversation-file upload`，返回 `dentryId`/`spaceId`。
+- 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. 其他错误：保留真实错误和已完成/失败项；不要连续尝试同义原子命令。

package/skills/dws/dingtalk-chat/references/01-messaging.md

@@ -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 并保留幂等键，不自动换目标重发。

package/skills/dws/dingtalk-chat/references/card/callback.md

@@ -0,0 +1,10 @@
+# 卡片回调边界
+
+当前 DWS lower interface 没有卡片按钮/action callback 的订阅、验签或回复能力，
+`callback_supported=false`。因此：
+
+- 不生成 callback URL、签名密钥或虚构的监听命令；
+- 不把 `dws event consume` 当作卡片 callback 的替代；
+- 用户必须使用按钮交互时，停止并说明当前不支持，等待平台接口和 Runtime 正式发布。
+
+卡片的 create/update 能力不代表 callback 可用。

package/skills/dws/dingtalk-chat/references/card/create.md

@@ -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 "请大家确认"
+```

package/skills/dws/dingtalk-chat/references/card/schema.md

@@ -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。

package/skills/dws/dingtalk-chat/references/card/update.md

@@ -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` 不一致时停止。

package/skills/dws/dingtalk-chat/references/chat/chat-bot.md

@@ -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 图片/文件/音视频：停止并说明当前身份矩阵不支持；只有用户明确同意改为当前用户身份时，才重新确认目标和内容。