docs(skill): align IM shortcut routing

internal/cli/schema_agent_metadata/chat.json

@@ -256,7 +256,8 @@
         "cobra-help:dws chat +at-me",
         "internal/cli/schema_command_registry.json#chat.shortcut_at_me",
         "internal/cli/schema_hints/metadata/chat.json",
-        "internal/cli/schema_hints/selection/chat.json"
+        "internal/cli/schema_hints/selection/chat.json",
+        "skills/mono/references/intent-guide.md"
       ],
       "use_when": [
         "当你想快速看回最近谁在群里或单聊里 @了你、但不想手动把起止时间换算成毫秒、也不想记 list-mentions 的一堆参数时使用；内部按本地时区算出「最近 N 天」（默认 7 天，可用 --days 调整回溯天数）的时间窗，搜索这段时间内 @我 的消息，再在本地把每条消息投影成发送人、时间、内容、所在会话四个关键字段。默认只读且不会发送、撤回或标记任何消息；传 --download-resources 时会在工作目录写文件，因此命令按本地写入操作确认。"
@@ -3871,7 +3872,8 @@
         "cobra-help:dws chat +chat-messages",
         "internal/cli/schema_command_registry.json#chat.shortcut_chat_messages",
         "internal/cli/schema_hints/metadata/chat.json",
-        "internal/cli/schema_hints/selection/chat.json"
+        "internal/cli/schema_hints/selection/chat.json",
+        "skills/mono/references/intent-guide.md"
       ],
       "use_when": [
         "当你想快速看某个会话里的消息（谁在什么时间说了什么），而不想拿到一大坨原始消息字段时使用；群聊传 --group（群会话 ID，openConversationId），单聊传 --user（对方 userId），两者互斥且必须二选一。省略 --time 时默认从当前时间向前读取最近消息；也可指定时间边界并用 --direction newer/older 控制方向。内部据此调用群聊或单聊的消息列表接口，再在本地投影出每条消息的发言人、文本和时间。默认只读且不会发送或修改任何消息；传 --download-resources 时会在工作目录写文件，因此命令按本地写入操作确认。"
@@ -9894,6 +9896,12 @@
               "precedence": "reviewed_explicit",
               "selected": true,
               "review_reason": "Reviewed against every executable identity/content/target validation branch and the real lower tool mappings; bot and webhook media are intentionally rejected because no equivalent lower capability exists."
+            },
+            {
+              "value": "not_required",
+              "source": "risk-default",
+              "precedence": "inference_or_default",
+              "selected": false
             }
           ]
         },
@@ -9910,6 +9918,12 @@
               "precedence": "reviewed_explicit",
               "selected": true,
               "review_reason": "Reviewed against every executable identity/content/target validation branch and the real lower tool mappings; bot and webhook media are intentionally rejected because no equivalent lower capability exists."
+            },
+            {
+              "value": "write",
+              "source": "command-verb",
+              "precedence": "inference_or_default",
+              "selected": false
             }
           ]
         },
@@ -9948,6 +9962,12 @@
               "precedence": "reviewed_explicit",
               "selected": true,
               "review_reason": "Reviewed against every executable identity/content/target validation branch and the real lower tool mappings; bot and webhook media are intentionally rejected because no equivalent lower capability exists."
+            },
+            {
+              "value": "unknown",
+              "source": "effect-default",
+              "precedence": "inference_or_default",
+              "selected": false
             }
           ]
         },
@@ -10035,6 +10055,12 @@
               "precedence": "reviewed_explicit",
               "selected": true,
               "review_reason": "Reviewed against every executable identity/content/target validation branch and the real lower tool mappings; bot and webhook media are intentionally rejected because no equivalent lower capability exists."
+            },
+            {
+              "value": "medium",
+              "source": "effect-default",
+              "precedence": "inference_or_default",
+              "selected": false
             }
           ]
         },
@@ -10069,7 +10095,8 @@
         "cobra-help:dws chat +messages-send",
         "internal/cli/schema_command_registry.json#chat.shortcut_messages_send",
         "internal/cli/schema_hints/metadata/chat.json",
-        "internal/cli/schema_hints/selection/chat.json"
+        "internal/cli/schema_hints/selection/chat.json",
+        "skills/mono/references/intent-guide.md"
       ],
       "use_when": [
         "当你希望用同一个入口选择 current-user、bot 或 webhook 身份发送消息时使用；命令会按身份校验目标、内容和凭据并路由到真实下层。current-user 支持文本/Markdown、已有 mediaId 图片、安全相对路径文件上传和幂等键；bot 支持群聊或批量单聊文本/Markdown；webhook 的目标由 token 所在群决定。不会把 user 文件能力伪装成 bot/webhook 等价能力。"
@@ -11368,7 +11395,8 @@
         "cobra-help:dws chat +search-msg",
         "internal/cli/schema_command_registry.json#chat.shortcut_search_msg",
         "internal/cli/schema_hints/metadata/chat.json",
-        "internal/cli/schema_hints/selection/chat.json"
+        "internal/cli/schema_hints/selection/chat.json",
+        "skills/mono/references/intent-guide.md"
       ],
       "use_when": [
         "当你要按关键词、发送者、@对象、会话、消息类型或机器人来源组合搜索 IM 消息时使用；默认查询近 7 天，也可指定精确起止时间。--page-all 会连续拉取游标页，默认再按消息 ID 分批富化详情；任何续页或富化失败都会保留已取得结果并返回逐项失败 ledger，绝不把截断结果标成完整。默认只读；传 --download-resources 时会在工作目录写文件，因此命令按本地写入操作确认。"
@@ -11887,7 +11915,8 @@
         "cobra-help:dws chat +thread-replies",
         "internal/cli/schema_command_registry.json#chat.shortcut_thread_replies",
         "internal/cli/schema_hints/metadata/chat.json",
-        "internal/cli/schema_hints/selection/chat.json"
+        "internal/cli/schema_hints/selection/chat.json",
+        "skills/mono/references/intent-guide.md"
       ],
       "use_when": [
         "当你已经拿到某个群里一条「话题消息」的 threadId/topicId、想快速看这条话题下的全部回复（谁在什么时间回复了什么），而不想拿到一大坨原始消息字段时使用；内部按 --group（群会话 ID）和 --thread-id（兼容 --topic-id）拉取该话题的回复列表，可选 --time 指定起始时间、--limit 指定每页条数，再在本地投影出每条回复的发言人、文本和回复时间。默认只读且不会发送或修改任何消息；传 --download-resources 时会在工作目录写文件，因此命令按本地写入操作确认。"
@@ -26619,6 +26648,7 @@
         "internal/cli/schema_hints/selection/chat.json",
         "internal/cli/schema_mcp_metadata.json#tools.chat.list_topic_replies",
         "skills/mono/SKILL.md",
+        "skills/mono/references/intent-guide.md",
         "skills/mono/references/products/chat.md"
       ],
       "use_when": [

internal/cli/schema_agent_metadata/index.json

@@ -1,6 +1,6 @@
 {
   "version": 1,
-  "source_hash": "sha256:179a67a3fd47e2ef1786aaec197d52429a6522bf61a883df70f83febf334387b",
+  "source_hash": "sha256:f8489e3583b99d851ccd2a133a0c565aaa658168d0c1ba8cf71034f2930c51e9",
   "surface_hash": "sha256:698ccdc961c0b745e6524e33ae13d87ef4fcac012a2e833c7a727a79d35004db",
   "coverage": {
     "surface_products": 26,

internal/cli/schema_catalog/catalog.json

@@ -1,12 +1,12 @@
 {
   "version": 1,
   "surface_hash": "sha256:698ccdc961c0b745e6524e33ae13d87ef4fcac012a2e833c7a727a79d35004db",
-  "source_hash": "sha256:2336db101f882586f78322e88d8351ed8b80c9c66c6cb6268cfb7605c04077ed",
+  "source_hash": "sha256:7a75c819e9a71d0166bffc60204e513074f9f300ade7a2e4b4e8529b273145df",
   "catalog": {
     "agent_metadata": {
       "products_with_metadata": 26,
       "source": "embedded-skill-metadata",
-      "source_hash": "sha256:179a67a3fd47e2ef1786aaec197d52429a6522bf61a883df70f83febf334387b",
+      "source_hash": "sha256:f8489e3583b99d851ccd2a133a0c565aaa658168d0c1ba8cf71034f2930c51e9",
       "surface_hash": "sha256:698ccdc961c0b745e6524e33ae13d87ef4fcac012a2e833c7a727a79d35004db",
       "surface_products": 26,
       "surface_tools": 818,

internal/cli/schema_catalog/tools/chat.json

@@ -22683,6 +22683,7 @@
         "internal/cli/schema_hints/selection/chat.json",
         "internal/cli/schema_mcp_metadata.json#tools.chat.list_topic_replies",
         "skills/mono/SKILL.md",
+        "skills/mono/references/intent-guide.md",
         "skills/mono/references/products/chat.md"
       ],
       "agent_summary": "分页读取指定话题的回复",
@@ -50902,7 +50903,8 @@
         "cobra-help:dws chat +at-me",
         "internal/cli/schema_command_registry.json#chat.shortcut_at_me",
         "internal/cli/schema_hints/metadata/chat.json",
-        "internal/cli/schema_hints/selection/chat.json"
+        "internal/cli/schema_hints/selection/chat.json",
+        "skills/mono/references/intent-guide.md"
       ],
       "agent_summary": "查最近 @我 的消息（自动算时间窗，投影发送人/时间/内容/会话）",
       "agent_summary_source": "dws-agent-selection/chat",
@@ -58193,7 +58195,8 @@
         "cobra-help:dws chat +chat-messages",
         "internal/cli/schema_command_registry.json#chat.shortcut_chat_messages",
         "internal/cli/schema_hints/metadata/chat.json",
-        "internal/cli/schema_hints/selection/chat.json"
+        "internal/cli/schema_hints/selection/chat.json",
+        "skills/mono/references/intent-guide.md"
       ],
       "agent_summary": "拉取某个会话（群聊或单聊）的消息列表并投影出发言人/文本/时间",
       "agent_summary_source": "dws-agent-selection/chat",
@@ -72214,7 +72217,8 @@
         "cobra-help:dws chat +messages-send",
         "internal/cli/schema_command_registry.json#chat.shortcut_messages_send",
         "internal/cli/schema_hints/metadata/chat.json",
-        "internal/cli/schema_hints/selection/chat.json"
+        "internal/cli/schema_hints/selection/chat.json",
+        "skills/mono/references/intent-guide.md"
       ],
       "agent_summary": "统一发送文本、Markdown、当前用户文件或已有 mediaId 图片",
       "agent_summary_source": "dws-agent-selection/chat",
@@ -72347,6 +72351,12 @@
               "selected": true,
               "source": "internal/cli/schema_hints/metadata/chat.json",
               "value": "user_required"
+            },
+            {
+              "precedence": "inference_or_default",
+              "selected": false,
+              "source": "risk-default",
+              "value": "not_required"
             }
           ],
           "precedence": "reviewed_explicit",
@@ -72377,6 +72387,12 @@
               "selected": true,
               "source": "internal/cli/schema_hints/metadata/chat.json",
               "value": "write"
+            },
+            {
+              "precedence": "inference_or_default",
+              "selected": false,
+              "source": "command-verb",
+              "value": "write"
             }
           ],
           "precedence": "reviewed_explicit",
@@ -72415,6 +72431,12 @@
               "selected": true,
               "source": "internal/cli/schema_hints/metadata/chat.json",
               "value": "unknown"
+            },
+            {
+              "precedence": "inference_or_default",
+              "selected": false,
+              "source": "effect-default",
+              "value": "unknown"
             }
           ],
           "precedence": "reviewed_explicit",
@@ -72502,6 +72524,12 @@
               "selected": true,
               "source": "internal/cli/schema_hints/metadata/chat.json",
               "value": "medium"
+            },
+            {
+              "precedence": "inference_or_default",
+              "selected": false,
+              "source": "effect-default",
+              "value": "medium"
             }
           ],
           "precedence": "reviewed_explicit",
@@ -77478,7 +77506,8 @@
         "cobra-help:dws chat +search-msg",
         "internal/cli/schema_command_registry.json#chat.shortcut_search_msg",
         "internal/cli/schema_hints/metadata/chat.json",
-        "internal/cli/schema_hints/selection/chat.json"
+        "internal/cli/schema_hints/selection/chat.json",
+        "skills/mono/references/intent-guide.md"
       ],
       "agent_summary": "多维搜索消息，可全量翻页并批量富化详情",
       "agent_summary_source": "dws-agent-selection/chat",
@@ -80882,7 +80911,8 @@
         "cobra-help:dws chat +thread-replies",
         "internal/cli/schema_command_registry.json#chat.shortcut_thread_replies",
         "internal/cli/schema_hints/metadata/chat.json",
-        "internal/cli/schema_hints/selection/chat.json"
+        "internal/cli/schema_hints/selection/chat.json",
+        "skills/mono/references/intent-guide.md"
       ],
       "agent_summary": "拉取某条话题消息的全部回复并投影出发言人/文本/时间",
       "agent_summary_source": "dws-agent-selection/chat",

skills/mono/SKILL.md

@@ -46,7 +46,7 @@ cli_version: ">=1.0.15"
 | `aitable` | 29 | `dingtalk-aitable` | `dws shortcut list --service aitable --format json` |
 | `attendance` | 19 | `dingtalk-attendance` | `dws shortcut list --service attendance --format json` |
 | `calendar` | 20 | `dingtalk-calendar` | `dws shortcut list --service calendar --format json` |
-| `chat` | 42 | `dingtalk-chat` | `dws shortcut list --service chat --format json` |
+| `chat` | 97 | `dingtalk-chat` | `dws shortcut list --service chat --format json` |
 | `contact` | 14 | `dingtalk-contact` | `dws shortcut list --service contact --format json` |
 | `devapp` | 19 | `dingtalk-dev` | `dws shortcut list --service devapp --format json` |
 | `ding` | 4 | `dingtalk-ding` | `dws shortcut list --service ding --format json` |

skills/mono/references/intent-guide.md

@@ -29,19 +29,21 @@
 | "明早 9 点提醒我提交周报" | 创建个人待办后添加提醒 | `todo task create` + `todo task add-reminder` | `calendar` | `+remind --at` 只写截止时间；提醒可写入，但上游不支持规则读回 |
 | "帮我建一个项目群" | 创建群聊 | `chat group create` | — | 群聊管理，不是日历日程 |
 | "把张三拉进群" | 添加群成员 | `chat group members add` | — | 先查 userId，再添加 |
-| "通知群里的人都来开会" | 个人身份群发 | `chat message send` | `chat message send-by-bot` | 以个人身份向群发消息 |
+| "通知群里的人都来开会" | 个人身份群发 | `chat +messages-send --as user` | `chat message send` | 统一入口校验身份、目标、内容和幂等键 |
-| "让机器人每天推送日报" | 机器人定时推送 | `chat message send-by-bot` | `chat message send` | 需要机器人身份定期发送 |
+| "让机器人每天推送日报" | 机器人定时推送 | `chat +messages-send --as bot` | `chat message send-by-bot` | 需要 robotCode；定时调度由外层工作流负责 |
-| "给张三发一条机器人单聊消息" | 机器人单聊 | `chat message send-by-bot --users` | — | 机器人批量单聊，先查 userId |
+| "给张三发一条机器人单聊消息" | 机器人单聊 | `chat +messages-send --as bot --users` | `chat message send-by-bot --users` | 机器人批量单聊，先查 userId |
-| "CPU 超过 90% 自动告警" | Webhook 告警 | `chat message send-by-webhook` | `chat message send-by-bot` | 系统告警场景，需自定义 Webhook |
+| "CPU 超过 90% 自动告警" | Webhook 告警 | `chat +messages-send --as webhook` | `chat message send-by-webhook` | 系统告警场景，需自定义 Webhook token |
 | "帮我看看收到的日报" | 收到的日志 | `report` | `doc` | 钉钉日志系统（日报/周报），不是文档 |
 | "帮我创建一个待办提醒" | 个人待办 | `todo` | `report` | 个人任务提醒，不是日志汇报 |
-| "拉取一下上周项目群的聊天记录" | 拉取会话消息 | `chat message list` | — | 拉取指定群聊的消息列表 |
+| "拉取一下上周项目群的聊天记录" | 拉取会话消息 | `chat +chat-messages` | `chat message list` | Shortcut 投影发言人/文本/时间并可处理资源 |
 | "看看张三发给我的消息" | 按发送者查询消息 | `chat message list-by-sender` | `chat message list --user` | 用户未明确说"单聊"时优先用 list-by-sender（跨单聊/群聊） |
 | "拉取和张三的单聊记录" | 拉取单聊消息 | `chat message list --user` | `chat message list-by-sender` | 用户明确说"单聊"时用 list --user |
-| "谁@了我/查看提及我的消息" | 查询@我的消息 | `chat message list-mentions` | `chat message list-all` | 都是跨会话时间范围查询，但 list-mentions 只返回@我的消息 |
+| "谁@了我/查看提及我的消息" | 查询@我的消息 | `chat +at-me` | `chat message list-mentions` | Shortcut 自动时间窗、投影和资源处理 |
 | "查看我今天的所有消息" | 全量会话消息 | `chat message list-all` | `chat message list` | 用户未指定具体会话时用 list-all（跨所有会话），指定了具体群或人时用 list |
-| "搜一下消息里的changefree链接" | 消息搜索 | `chat message search-advanced`（首选） | `chat search` | 推荐首选 search-advanced，它是 search 的严格超集（keyword 可选、支持多群、可叠加发送者/at 维度） |
+| "搜一下消息里的changefree链接" | 消息搜索 | `chat +search-msg` | `chat message search-advanced` | Shortcut 支持关键词、发送者、会话、消息类型、时间窗、全量翻页和批量富化 |
-| "按发送者搜索/指定多个群搜索/多维度搜消息" | 多维度搜索消息 | `chat message search-advanced`（首选） | `chat message search` | 推荐首选，支持关键词、发送者、@我、多个会话等维度组合 |
+| "按发送者搜索/指定多个群搜索/多维度搜消息" | 多维度搜索消息 | `chat +search-msg` | `chat message search-advanced` | 需要原子响应结构时才降级 |
+| "查看这条话题的所有回复" | 话题回复 | `chat +thread-replies` | `chat message list-topic-replies` | 已知 threadId/topicId 时自动投影回复人、正文和时间 |
+| "把这些消息里的附件下载下来" | 消息资源下载 | 查询 Shortcut 的 `--download-resources` | `resourceRefs.shortcut` 返回的下载命令 | 先用查询结果的 resourceRefs；单资源再执行返回的可运行参数 |
 | "消息发没发成功/查询消息发送状态" | 查询消息发送状态 | `chat message query-send-status` | — | 需要 send 返回的 openTaskId |
 | "撤回我发的消息/撤回消息" | 撤回个人消息 | `chat message recall` | `chat message recall-by-bot` | recall 撤回个人消息，recall-by-bot 撤回机器人消息 |
 | "未读消息会话/未读会话列表/我的未读会话" | 未读会话列表 | `chat message list-unread-conversations` | `chat message read-status` | list-unread-conversations 查哪些会话有未读；read-status 查具体消息的已读状态 |
@@ -267,7 +269,7 @@ alidocs 链接表面长得一样（`https://alidocs.dingtalk.com/i/nodes/{id}`
 
 ### 5. chat 内部 — 消息发送与撤回
 
-**用 `chat message send` 的场景**：
+**优先用 `chat +messages-send` 的场景**：
 - "帮我在群里发个消息提醒大家" — **个人身份**发群消息
 - "发个单聊消息给某人" — 个人身份发单聊：
   - 已有 userId 时直接使用 `--user`；已有 openDingTalkId 时使用 `--open-dingtalk-id`
@@ -278,18 +280,20 @@ alidocs 链接表面长得一样（`https://alidocs.dingtalk.com/i/nodes/{id}`
 - "发图片+文字说明" — 不要硬塞进一条命令；先发图片/文件消息再补一条 `--text "..."` 即可
 
 ```bash
-dws chat message send --group <openConversationId> --msg-type file --file-path ./screenshot.png --format json
+dws chat +messages-send --as user --chat-id <openConversationId> --msg-type file --file ./screenshot.png --idempotency-key <key> --format json
-dws chat message send --open-dingtalk-id <openDingTalkId> --msg-type file --file-path ./report.pdf --format json
+dws chat +messages-send --as user --open-dingtalk-id <openDingTalkId> --msg-type file --file ./report.pdf --idempotency-key <key> --format json
 ```
 
-> ❌ 反模式：先把本地文件转换成 mediaId，或先经钉盘上传再拼装聊天消息。本地图片/文件一律用 `--msg-type file --file-path` 直发；`--msg-type image --media-id` 只接受上游已经提供的有效 mediaId。
+> ❌ 反模式：先把本地文件转换成 mediaId，或先经钉盘上传再拼装聊天消息。本地图片/文件一律用 `--msg-type file --file` 直发；`--msg-type image --media-id` 只接受上游已经提供的有效 mediaId。
 > 富媒体消息单聊优先使用 `--open-dingtalk-id`；传 `--user` 时 CLI 会尝试解析为 openDingTalkId 后发送。
 
-**用 `chat message send-by-bot` 的场景**：
+`+messages-send` 的 @ 占位符按身份自动规范化并补齐：user 使用 `<@id>` / `<@all>`；bot/webhook 使用 `@id` / `@手机号` / `@all`。声明 `--at-*` / `--at-all` 即可，不要再手工拼 `@10`。
+
+**用 `chat +messages-send --as bot` 的场景**：
 - "让机器人在群里发一条通知" — **机器人身份**发消息
 - "给张三发一条机器人单聊消息" — 机器人单聊
 
-**用 `chat message send-by-webhook` 的场景**：
+**用 `chat +messages-send --as webhook` 的场景**：
 - "通过 Webhook 发告警到群里" — 自定义机器人 Webhook
 - 用户有 Webhook Token
 
@@ -302,16 +306,21 @@ dws chat message send --open-dingtalk-id <openDingTalkId> --msg-type file --file
 用 `chat message query-send-status` 的场景：
 - "消息发没发成功/查询消息发送状态" — 查询个人发送消息的状态，需要 send 返回的 openTaskId
 
-用 `chat message search-advanced` 的场景（推荐首选）：
+用 `chat +search-msg` 的场景（推荐首选）：
 - "按发送者搜索消息/指定多个群搜索/@我的消息多维度搜" — 支持关键词、发送者、@我、@指定人、多个会话等维度组合搜索
-- 替代关系：完全替代 `chat message search`（严格超集：keyword 可选 vs 必填，支持多群 vs 单群）；大部分替代 `chat message list-by-sender`（--user/--users 覆盖按 userId 搜索发送者，--sender-ids 覆盖按 openDingTalkId 搜索）和 `chat message list-mentions`（--at-me 覆盖核心功能）
+- `--page-all` 连续拉取游标页，默认按消息 ID 批量富化；续页或富化失败保留已取得结果并返回逐项失败 ledger
+- 替代关系：覆盖 `chat message search-advanced` 的常见组合过滤；需要原子接口返回结构或 Shortcut 尚未暴露的字段时再降级
 - 不能替代：`chat message list-focused`（「特别关注人」是独立维度）
-- 默认使用 search-advanced，仅在上述不适用场景才降级到具体命令
+- 默认使用 `+search-msg`，仅在上述不适用场景才降级到具体命令
+
+资源读取优先在 `+at-me`、`+chat-messages`、`+messages-mget`、`+search-msg`、`+thread-replies` 上加 `--download-resources`。引用、回复或合并转发里的资源使用结果 `resourceRefs` 自带的子消息 `messageId`；子消息没有会话 ID 时才继承父消息会话。单独下载一个资源时用 `+messages-resource-download`，输出必须是工作目录内的相对路径，默认拒绝覆盖。
+
+上述查询 Shortcut 因可选本地下载能力按命令级 Schema 发布为 `write/user_required`；执行前读取 leaf Schema，确认输出目录和覆盖策略，获得用户确认后才加 `--yes`。
 
 **不支持的场景**：
 - "撤回我刚发的消息"（但不知道消息 ID） — 需先通过消息拉取或搜索接口（如 `chat message list`、`chat message search-advanced` 等）获取 openMessageId，再调用 `chat message recall`
 
-判断关键：个人发→ `send`；机器人发→ `send-by-bot`；有 Webhook Token→ `send-by-webhook`；个人撤回→ `recall`；机器人撤回→ `recall-by-bot`；查发送状态→ `query-send-status`；消息搜索类意图优先路由到 `search-advanced`（推荐首选），仅在不适用时降级到具体命令
+判断关键：普通发送统一走 `+messages-send` 并显式选择 `--as`；个人撤回→ `recall`；机器人撤回→ `recall-by-bot`；查发送状态→ `query-send-status`；消息搜索类意图优先路由到 `+search-msg`，仅在不适用时降级到原子命令。
 
 ---
 

skills/mono/references/products/chat.md

@@ -2,6 +2,27 @@
 
 ## 命令总览
 
+## Shortcut 优先路由
+
+常见 Agent 意图优先使用公开 `+` Shortcut；下面的原子命令章节保留给需要特定原始返回结构、兼容参数或 Shortcut 未覆盖字段的场景。执行前用 `dws schema --cli-path "chat +<shortcut>" --format json` 读取最终参数、约束和确认语义。
+
+| 意图 | 首选 |
+|---|---|
+| 以 current-user / bot / webhook 身份发消息 | `dws chat +messages-send --as <identity> ...` |
+| 拉取单个群聊或单聊的消息 | `dws chat +chat-messages ...` |
+| 按关键词、发送者、@对象、会话、类型或时间组合搜索 | `dws chat +search-msg ...` |
+| 查询 @我的消息 | `dws chat +at-me ...` |
+| 根据消息 ID 批量取详情与 reaction | `dws chat +messages-mget ...` |
+| 读取已知 thread/topic 的全部回复 | `dws chat +thread-replies ...` |
+| 下载单个 mediaId/fileId | `dws chat +messages-resource-download ...` |
+
+- `+messages-send` 只暴露下层真实支持的身份能力：user 支持文本/Markdown、已有 mediaId 图片、本地文件和幂等键；bot 支持群聊或批量单聊文本/Markdown；webhook 的目标由 token 所在群决定。
+- `+messages-send` 会自动规范化并补齐 @ 占位符。user 使用 `<@id>` / `<@all>`；bot/webhook 使用 `@id` / `@手机号` / `@all`。声明 `--at-*` / `--at-all` 即可，不要为统一 Shortcut 手工拼 `@10`。
+- `+search-msg --page-all` 连续翻页并默认按消息 ID 批量富化；任何续页或富化失败都会保留已取得结果并返回逐项失败 ledger。
+- `+at-me`、`+chat-messages`、`+messages-mget`、`+search-msg`、`+thread-replies` 可用 `--download-resources` 下载资源。引用、回复、合并转发中的资源使用结果 `resourceRefs` 自带的子消息 `messageId`；仅当子消息缺会话 ID 时继承父消息 `openConversationId`。
+- 上述查询 Shortcut 因可选本地下载能力按命令级 Schema 发布为 `write/user_required`；`+messages-resource-download` 始终写本地。确认相对输出目录和覆盖策略后才加 `--yes`，默认拒绝覆盖已有文件。
+- 下载器仅接受经审查的钉钉与公网 OSS HTTPS 地址并逐跳校验重定向；跨主机时不会转发下层提供的请求头。新官方域名被拒绝时记录错误中的 host 供审查，不要放宽为任意 HTTPS。
+
 ### group (群组管理)
 
 #### 创建群 — 当前登录用户自动成为群主

skills/multi/dingtalk-chat/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: dingtalk-chat
-description: 钉钉群聊与消息。Use when 用户提到 发消息/编辑或撤回已发送消息/单聊/群聊/建群/普通群升级外部群/群昵称/会话分组/群成员管理/@消息/收藏消息/机器人群发/Webhook通知/发图片或文件到群。Distinct from dingtalk-ding(紧急DING消息/短信/电话)、dingtalk-mail(邮件)、dingtalk-edu-group(班级群)。命令前缀：dws chat。
+description: 钉钉群聊与消息。Use when 用户提到 发消息/编辑或撤回已发送消息/单聊/群聊/建群/普通群升级外部群/群昵称/会话分组/群成员管理/@消息/搜索聊天记录/话题回复/收藏消息/机器人群发/Webhook通知/发送或下载消息图片与文件。Distinct from dingtalk-ding(紧急DING消息/短信/电话)、dingtalk-mail(邮件)、dingtalk-edu-group(班级群)。命令前缀：dws chat。
 cli_version: ">=0.2.14"
 metadata:
   category: product
@@ -30,64 +30,127 @@ metadata:
 
 | Shortcut | 风险 | 适用场景 |
 |---|---|---|
-| `dws chat +at-me` | read | 查最近 @我 的消息（自动算时间窗，投影发送人/时间/内容/会话） |
+| `dws chat +at-me` | write | 查最近 @我 的消息（自动算时间窗，投影发送人/时间/内容/会话） |
 | `dws chat +bot-find` | read | 搜索全部可用机器人（含他人/官方，返回 openDingTalkId 可发单聊） |
 | `dws chat +bot-search` | read | 搜索当前用户自己创建的机器人 |
 | `dws chat +broadcast` | write | 按姓名逐一给多个人群发同一条单聊消息（自动解析 userId、逐个发送） |
+| `dws chat +category-add-conversation` | write | 将会话移动到指定的自定义分组中 |
 | `dws chat +category-create` | write | 创建用户自定义会话分组 |
 | `dws chat +category-delete` | high-risk-write | 删除用户自定义会话分组 |
 | `dws chat +category-list` | read | 获取用户自定义会话分组 |
+| `dws chat +category-list-conversations` | read | 拉取指定自定义会话分组下的会话 |
+| `dws chat +category-remove-conversation` | write | 将会话从指定的自定义分组中移出 |
 | `dws chat +category-rename` | write | 更新用户自定义会话分组的名称 |
+| `dws chat +chat-add-bot` | write | 将机器人添加到群中 |
+| `dws chat +chat-audit-join` | write | 审批入群验证（通过/拒绝/删除/忽略/拉黑） |
 | `dws chat +chat-bots` | read | 查看群内所有机器人 |
+| `dws chat +chat-create` | write | 以当前用户身份创建钉钉群聊 |
 | `dws chat +chat-dismiss` | high-risk-write | 解散群聊（不可逆，需群主权限） |
+| `dws chat +chat-get-by-id` | read | 根据群号获取群聊信息 |
 | `dws chat +chat-invite-url` | read | 获取群邀请链接 |
 | `dws chat +chat-list-all` | read | 分页拉取我加入的所有群列表 |
 | `dws chat +chat-list-join-requests` | read | 分页拉取入群验证记录 |
 | `dws chat +chat-list-mine` | read | 拉取我创建/管理的群 |
+| `dws chat +chat-members-get` | read | 根据成员 openDingTalkId 批量查询群成员详情 |
+| `dws chat +chat-members-list` | read | 列出群成员并把用户与机器人分桶（支持群名语义解析） |
+| `dws chat +chat-messages` | write | 拉取某个会话（群聊或单聊）的消息列表并投影出发言人/文本/时间 |
 | `dws chat +chat-mute` | write | 全员禁言 / 取消全员禁言 |
+| `dws chat +chat-mute-member` | write | 指定群成员禁言 / 取消禁言 |
+| `dws chat +chat-quit` | write | 退出群聊 |
+| `dws chat +chat-remove-bot` | high-risk-write | 从群内移除机器人 |
 | `dws chat +chat-role-add` | write | 添加群身份 |
 | `dws chat +chat-role-list` | read | 拉取会话的群身份列表 |
 | `dws chat +chat-role-query-user` | read | 查询群成员的群身份 |
+| `dws chat +chat-role-remove` | high-risk-write | 删除群身份 |
+| `dws chat +chat-role-remove-user` | write | 移除用户的指定群身份 |
 | `dws chat +chat-role-set-user` | write | 设置用户的群身份（覆盖该用户的全部群身份） |
 | `dws chat +chat-role-update` | write | 更新群身份名称 |
 | `dws chat +chat-search` | read | 按关键词搜索群聊 |
 | `dws chat +chat-set-admin` | write | 设置 / 取消群管理员 |
 | `dws chat +chat-set-history` | write | 设置新成员入群可查看历史消息范围 |
+| `dws chat +chat-transfer-owner` | write | 转让群主 |
+| `dws chat +chat-update` | write | 更新群名称（仅名称，不支持 description） |
 | `dws chat +chat-update-alias` | write | 设置群备注（仅自己可见） |
+| `dws chat +chat-update-icon` | write | 更新群头像 |
 | `dws chat +chat-update-nick` | write | 设置当前用户在群内的群昵称 |
+| `dws chat +chat-update-settings` | write | 更新群设置（settingKey + status） |
 | `dws chat +conversation-clear-all-red-point` | write | 清除所有会话红点（全部已读） |
+| `dws chat +conversation-clear-messages` | high-risk-write | 清空当前用户指定会话的聊天记录（仅本人视角，不可逆） |
+| `dws chat +conversation-clear-red-point` | write | 清除会话红点 |
+| `dws chat +conversation-hide` | write | 会话列表中隐藏会话（收到新消息会重新出现） |
 | `dws chat +conversation-info` | read | 获取会话信息（群聊传 --group，单聊传 --open-dingtalk-id） |
 | `dws chat +conversation-list` | read | 分页获取当前用户的全部会话列表（单聊+群聊） |
-| `dws chat +conversation-list-top` | read | 拉取置顶会话列表 |
+| `dws chat +conversation-list-top` | read | 拉取置顶会话列表，可只看群聊或单聊 |
+| `dws chat +conversation-mark-read` | write | 标记消息已读（该消息及之前的消息都标记为已读） |
+| `dws chat +conversation-mark-unread` | write | 标记会话为未读 |
+| `dws chat +conversation-mute` | write | 会话消息免打扰（支持单聊/群聊） |
+| `dws chat +conversation-set-top` | write | 批量会话置顶 / 取消置顶（最多 10 个） |
 | `dws chat +dm` | write | 按姓名直接给某人发单聊消息（自动解析 userId） |
+| `dws chat +feed-group-query-item` | read | 在会话分组结果中按会话 ID 精确查询多项 |
+| `dws chat +flag-cancel` | write | 取消收藏一条或多条消息（最多 10 条） |
+| `dws chat +flag-create` | write | 收藏一条或多条消息（最多 10 条） |
+| `dws chat +flag-list` | read | 分页查询当前用户收藏的消息 |
 | `dws chat +group-members` | read | 按群名列出群成员（自动搜群解析 openConversationId） |
+| `dws chat +messages-add-emoji` | write | 对消息添加 emoji 表情回应 |
+| `dws chat +messages-add-text-emotion` | write | 对消息添加文字表情回应 |
+| `dws chat +messages-batch-recall-by-bot` | write | 机器人撤回单聊消息 |
+| `dws chat +messages-batch-send-by-bot` | write | 机器人批量向用户发送单聊 Markdown 消息 |
+| `dws chat +messages-combine-forward` | write | 合并转发多条消息 |
+| `dws chat +messages-create-text-emotion` | write | 创建文字表情（获取 emotionId） |
+| `dws chat +messages-forward` | write | 转发单条消息 |
+| `dws chat +messages-forward-topic` | write | 转发话题消息到目标会话 |
+| `dws chat +messages-list` | read | 拉取群聊会话消息 |
 | `dws chat +messages-list-direct` | read | 拉取单聊会话消息 |
 | `dws chat +messages-list-pin` | read | 拉取会话中钉住的消息列表 |
 | `dws chat +messages-list-unread-conversations` | read | 获取有未读消息的会话列表 |
-| `dws chat +messages-mget` | read | 根据消息 ID 批量查询消息（最多 50 条） |
+| `dws chat +messages-mget` | write | 根据消息 ID 批量查询消息（最多 50 条） |
 | `dws chat +messages-query-send-status` | read | 查询消息发送状态 |
 | `dws chat +messages-read-status` | read | 查询消息的已读/未读状态 |
+| `dws chat +messages-recall` | write | 撤回当前用户发送的消息 |
+| `dws chat +messages-recall-by-bot` | write | 机器人撤回群消息 |
+| `dws chat +messages-remove-emoji` | write | 移除消息的 emoji 表情回应 |
+| `dws chat +messages-remove-text-emotion` | write | 移除消息的文字表情回应 |
+| `dws chat +messages-reply` | write | 以当前用户身份引用回复消息（自动补全原发送者） |
+| `dws chat +messages-resource-download` | write | 安全下载消息资源（图片/视频/语音/文件）到本地 |
+| `dws chat +messages-resource-url` | read | 获取消息资源（图片/视频/语音）下载链接 |
+| `dws chat +messages-send` | write | 统一发送文本、Markdown、当前用户文件或已有 mediaId 图片 |
+| `dws chat +messages-send-by-bot` | write | 机器人向群聊发送 Markdown 消息 |
 | `dws chat +messages-send-by-webhook` | write | 自定义机器人 Webhook 发送群消息 |
+| `dws chat +messages-send-card` | write | 创建流式卡片，可在同一次调用中写入内容并结束 |
+| `dws chat +messages-set-pin` | write | 钉住消息（Pin） |
+| `dws chat +messages-set-top` | write | 置顶消息 |
+| `dws chat +messages-unset-pin` | write | 取消钉住消息（Unpin） |
+| `dws chat +messages-unset-top` | write | 取消置顶消息 |
 | `dws chat +messages-update-card` | write | 流式更新卡片内容（最后一次 --flow-status 应为 3） |
 | `dws chat +my-groups` | read | 列出我加入的群，可按类型过滤并投影关键字段 |
+| `dws chat +search-msg` | write | 多维搜索消息，可全量翻页并批量富化详情 |
 | `dws chat +send-to-group` | write | 按群名直接给群发消息（自动搜群解析 openConversationId） |
+| `dws chat +thread-replies` | write | 拉取某条话题消息的全部回复并投影出发言人/文本/时间 |
 | `dws chat +unread-chats` | read | 列出我有未读消息的会话（投影会话名/未读数/会话ID） |
 <!-- VISIBLE_SHORTCUTS_END -->
 
+## IM Shortcut 优先路由
+
+- 统一发送优先用 `chat +messages-send`：通过 `--as user|bot|webhook` 选择身份，并只传该身份真实支持的目标、内容和凭据。仅在需要原子命令的特定返回结构或兼容参数时，才降级到 `chat message send` / `send-by-bot` / `send-by-webhook`。
+- 消息查询按意图选择：指定会话用 `+chat-messages`，跨维度过滤/全量翻页用 `+search-msg`，@我用 `+at-me`，已知消息 ID 批量富化用 `+messages-mget`，已知 thread/topic ID 读取回复用 `+thread-replies`。
+- 查询结果中的 `resourceRefs` 是可继续执行的资源上下文。引用、回复或合并转发中的子消息必须使用该子消息返回的 `messageId`；子消息缺会话 ID 时才继承父消息的 `openConversationId`，不要把所有资源重新绑定到父消息。
+- `+at-me`、`+chat-messages`、`+messages-mget`、`+search-msg`、`+thread-replies` 的 `--download-resources` 会写本地文件；`+messages-resource-download` 始终写本地文件。它们按 leaf Schema 发布为 `write/user_required`，先确认目标目录和覆盖策略，获得用户确认后才加 `--yes`。
+- `+messages-send` 会按身份规范化 @ 占位符：user 使用 `<@id>` / `<@all>`，bot/webhook 使用 `@id` / `@手机号` / `@all`；只需声明 `--at-*` / `--at-all`，缺失占位符会自动补齐。
+
 ## 意图表
 
 | 用户说 | 命令 |
 |--------|------|
-| "发消息给张三" | `dws chat message send --open-dingtalk-id <id> --title "<标题>" --text "<内容>"` |
+| "发消息给张三" | `dws chat +messages-send --as user --open-dingtalk-id <id> --text "<内容>"` |
-| "发到XX群" | `dws chat search --query "<群名>"` → `dws chat message send --group <openConversationId> --title "<标题>" --text "<内容>"` |
+| "发到XX群" | `dws chat +chat-search --query "<群名>"` → `dws chat +messages-send --as user --chat-id <openConversationId> --text "<内容>"` |
-| "建群" / "拉人进群" | `dws chat group create` / `dws chat group members add` |
+| "建群" / "拉人进群" | `dws chat +chat-create` / `dws chat group members add` |
 | "改群名" / "踢人" | `dws chat group rename` / `dws chat group members remove --yes`（踢人不可逆，确认目标后加 --yes；踢群主会被 CLI 拦截，需先 `transfer-owner`）|
-| "@我消息" | `dws chat message list-mentions` |
+| "@我消息" | `dws chat +at-me` |
-| "查群聊记录" | `dws chat message list` |
+| "查群聊记录" | `dws chat +chat-messages --group <openConversationId>` |
-| "收藏/取消收藏这条消息" | `dws chat message add-favorite` / `dws chat message remove-favorite`（均需 `openMessageId` 和 `openConversationId`）|
+| "收藏/取消收藏这条消息" | `dws chat +flag-create` / `dws chat +flag-cancel` |
-| "查看我收藏的消息" | `dws chat message list-favorites`（默认 `--cursor 0 --size 20`）|
+| "查看我收藏的消息" | `dws chat +flag-list` |
-| "用机器人发消息" | `dws chat message send-by-bot --robot-code <code> --group <id> --title "<标题>" --text "<内容>"` |
+| "用机器人发消息" | `dws chat +messages-send --as bot --robot-code <code> --chat-id <id> --text "<内容>"` |
-| "Webhook 推一条" | `dws chat message send-by-webhook --token <token> --title "<标题>" --text "<内容>"` |
+| "Webhook 推一条" | `dws chat +messages-send --as webhook --webhook-token <token> --text "<内容>"` |
 | "编辑 / 修改已发送消息" | `dws chat message edit --conversation-id <openConversationId> --msg-id <openMessageId> --text "<新内容>"` |
 | "撤回我发的消息" | `dws chat message recall`（撤回当前用户发送的消息）|
 | "撤回机器人消息" | `dws chat message recall-by-bot --robot-code <code> --group <openConversationId> --keys <processQueryKey>`（撤回机器人发的）|

skills/multi/dingtalk-chat/references/chat.md

@@ -2,6 +2,27 @@
 
 ## 命令总览
 
+## Shortcut 优先路由
+
+常见 Agent 意图优先使用公开 `+` Shortcut；下面的原子命令章节保留给需要特定原始返回结构、兼容参数或 Shortcut 未覆盖字段的场景。执行前用 `dws schema --cli-path "chat +<shortcut>" --format json` 读取最终参数、约束和确认语义。
+
+| 意图 | 首选 |
+|---|---|
+| 以 current-user / bot / webhook 身份发消息 | `dws chat +messages-send --as <identity> ...` |
+| 拉取单个群聊或单聊的消息 | `dws chat +chat-messages ...` |
+| 按关键词、发送者、@对象、会话、类型或时间组合搜索 | `dws chat +search-msg ...` |
+| 查询 @我的消息 | `dws chat +at-me ...` |
+| 根据消息 ID 批量取详情与 reaction | `dws chat +messages-mget ...` |
+| 读取已知 thread/topic 的全部回复 | `dws chat +thread-replies ...` |
+| 下载单个 mediaId/fileId | `dws chat +messages-resource-download ...` |
+
+- `+messages-send` 只暴露下层真实支持的身份能力：user 支持文本/Markdown、已有 mediaId 图片、本地文件和幂等键；bot 支持群聊或批量单聊文本/Markdown；webhook 的目标由 token 所在群决定。
+- `+messages-send` 会自动规范化并补齐 @ 占位符。user 使用 `<@id>` / `<@all>`；bot/webhook 使用 `@id` / `@手机号` / `@all`。声明 `--at-*` / `--at-all` 即可，不要为统一 Shortcut 手工拼 `@10`。
+- `+search-msg --page-all` 连续翻页并默认按消息 ID 批量富化；任何续页或富化失败都会保留已取得结果并返回逐项失败 ledger。
+- `+at-me`、`+chat-messages`、`+messages-mget`、`+search-msg`、`+thread-replies` 可用 `--download-resources` 下载资源。引用、回复、合并转发中的资源使用结果 `resourceRefs` 自带的子消息 `messageId`；仅当子消息缺会话 ID 时继承父消息 `openConversationId`。
+- 上述查询 Shortcut 因可选本地下载能力按命令级 Schema 发布为 `write/user_required`；`+messages-resource-download` 始终写本地。确认相对输出目录和覆盖策略后才加 `--yes`，默认拒绝覆盖已有文件。
+- 下载器仅接受经审查的钉钉与公网 OSS HTTPS 地址并逐跳校验重定向；跨主机时不会转发下层提供的请求头。新官方域名被拒绝时记录错误中的 host 供审查，不要放宽为任意 HTTPS。
+
 ### group (群组管理)
 
 #### 创建群 — 当前登录用户自动成为群主