Merge branch 'main' into codex/im-shortcut-gap-fill

chore: update formula for v1.0.55 [skip ci]
Merge pull request #833 from DingTalk-Real-AI/codex/changelog-v1.0.55-promote-beta.8
2026-07-30 11:31:19 +08:00 · 2026-07-30 03:11:41 +00:00 · 2026-07-30 11:00:51 +08:00 · 2026-07-30 10:32:58 +08:00 · 2026-07-30 10:32:20 +08:00 · 2026-07-30 10:29:39 +08:00
50 changed files with 14464 additions and 1127 deletions
@@ -6,6 +6,70 @@ The format is inspired by [Keep a Changelog](https://keepachangelog.com/) and th

 ## [Unreleased]

+## [1.0.55-beta.8] - 2026-07-30
+
+This beta revalidates the `v1.0.55-beta.7` product baseline through a complete
+guarded release delivery. It carries no new product-facing command behavior;
+the new version is required because the published beta.7 artifacts succeeded
+on GitHub, npm, and Homebrew, but its enabled optional Gitee mirror failed and
+left that Release run ineligible for stable promotion.
+
+### Changed
+
+- **Complete promotion evidence** — republishes the validated v1.0.55 command, Runtime Schema, Skill, authentication, and projection changes with the optional Gitee upload fallback disabled, so the release can produce one successful auditable delivery proof before stable promotion.
+
+## [1.0.55] - 2026-07-30
+
+This release promotes the validated `v1.0.55-beta.8` baseline to stable. It
+expands the public Workspace command surface and personal event consumption,
+makes the full built-in shortcut catalog available to Agents, and hardens
+multi-account routing, authentication compatibility, command safety, and
+response projection across the CLI.
+
+### Added
+
+- **Broader Workspace command surface** (#621, #676) — adds roughly 30 reviewed Drive, Doc, Sheet, and Chat leaf commands synchronized from Wukong, including Drive version and permission operations, document styling, Sheet comment/version/formula verification, and in-place text-emotion updates. A reusable declarative `LeafSpec` framework now delivers command identity, safety, selection, and guarded Help metadata consistently.
+- **Complete Agent-visible shortcut delivery** (#802, #815) — publishes all 210 built-in shortcuts as reviewed Runtime Schema leaves across 16 products, including 88 validated Chat shortcuts, with executable paths, parameters, constraints, selection guidance, dry-run capabilities, and runtime-aligned confirmation semantics.
+- **Expanded enterprise and event capabilities** (#790) — adds the HR Brain talent-pool, employee-profile, and structured-search command families; `dws mcp url get` resolves MCP Market endpoints; personal event consumption supports eight additional IM event keys, multi-key consumers, and targeted shutdown.
+- **Agent integration identity** (#804, #816) — adds validated `DWS_AGENT_HOST` and `DWS_AGENT_PRODUCT` labels for observability and product attribution while keeping them separate from authentication and authorization.
+
+### Changed
+
+- **Progressive multi-Skill guidance and account safety** (#621, #821) — reorganizes bundled product guidance for progressive discovery and restores the mandatory rule that Agents must not guess an account when a multi-account organization has no unique current default.
+- **Supported Chat file delivery** — retires the legacy AppKey/AppSecret-backed `chat media upload` command from discovery and routes local files through `chat message send --msg-type file --file-path`, while callers with an existing media ID can continue sending images directly.
+- **Guarded release delivery** (#791) — strengthens immutable GitHub, npm, Homebrew, optional mirror, recovery, and version-allocation checks while keeping beta and stable publication role-gated and auditable.
+
+### Fixed
+
+- **Shortcut and message projection correctness** (#706, #783, #795) — prevents successful read shortcuts from silently projecting non-empty backend responses to empty results, renders rich, forwarded, and encrypted message forms safely, and fixes group-bot, bot-search, mail-thread, media-ID alias, and Todo paging response handling.
+- **Command contract edge cases** (#803) — makes approval revocation and document rollback honor dry-run before confirmation or preflight, fixes Drive and Doc rename semantics, restores Drive-specific metadata, and validates Todo reminder rules.
+- **Authentication and external-contact compatibility** (#756, #757) — migrates legacy global and organization-scoped credentials without cross-account token borrowing, preserves contacts that expose only `openDingTalkId`, and aligns message-resource flags with message-list output fields.
+
+## [1.0.55-beta.7] - 2026-07-29
+
+This beta supersedes the unpublished `v1.0.55-beta.6` candidate and packages
+PRs #621, #676, #757, #815, #816, and #821. It restores the mandatory
+multi-account safety rule caught by the sealed-release E2E gate while retaining
+the reviewed Wukong capability and multi-Skill synchronization, declarative
+command and Schema delivery, hardened Chat shortcuts, external contact
+resolution, and Agent product identity on top of the `v1.0.55-beta.5` baseline.
+
+### Added
+
+- **Wukong capability and multi-Skill synchronization** (#621) — ports roughly 30 reviewed leaf commands into the open-source CLI across Drive, Doc, Sheet, and Chat, including in-place text-emotion updates, Drive version and permission operations, document styling, and Sheet comment/version/formula verification. The bundled multi-Skill framework is reorganized into progressive product references and routing guidance while retaining current open-source command, response, safety, and Runtime Schema contracts.
+- **Declarative leaf commands and unified metadata delivery** (#676) — adds the reusable `LeafSpec` command framework and migrates 27 DevApp commands without changing their paths or flags. Runtime consumers now resolve identity, safety, and selection through one embedded Catalog-backed API, and guarded Help output publishes the command's safety/confirmation annotation.
+- **Agent product identity** (#816) — adds the optional `DWS_AGENT_PRODUCT` override for the existing HTTP `claw-type` header while preserving each edition's default when unset. Product and runtime labels are caller-declared signals, not authentication credentials; services must validate supported values and must not grant access solely from them. The override does not change the separate IM message-display `clawType` parameter controlled by the edition and `--ai-tag`.
+
+### Changed
+
+- **Reviewed Chat shortcut delivery** (#815) — publishes 88 currently available Chat shortcuts after real-business validation, keeps three confirmed lower-service failures unavailable, strengthens semantic availability and dry-run contracts, and adds safe message-resource download plus group-member listing. Conversation filtering, IM routing/reporting, and member mute resolution are aligned with the validated backend identities.
+- **Agent identity label hardening** (#816) — limits `DWS_AGENT_PRODUCT` and `DWS_AGENT_HOST` to 64 ASCII bytes, trims only surrounding ASCII spaces and tabs, and rejects other control or Unicode whitespace. QwenWork integrations should report the two dimensions separately as `DWS_AGENT_PRODUCT=qwenwork` plus `DWS_AGENT_HOST=cloud` or `desktop`; previously used combined Host labels such as `qwenwork_cloud` remain syntactically valid for compatibility.
+
+### Fixed
+
+- **External-contact and message-resource chaining** (#757) — the shared name-to-ID resolver keeps external or cross-organization contacts that expose only `openDingTalkId`, applies reviewed display-name fallbacks, and preserves organization-only filtering for commands that require `userId`. `chat +messages-resource-url` now accepts `--msg-id` and `--open-message-id` as aliases for `--message-id`, matching message-list response fields.
+- **Multi-account Skill safety contract** (#821) — restores the mandatory rule that an Agent must never choose the first, most recently logged-in, or most recently used account when an organization has multiple accounts without one unique `isOrgCurrent=true` default. A PR-level embedded-Skill regression test now catches removal before the full sealed-release E2E gate.
+
 ## [1.0.55-beta.6] - 2026-07-29

 This beta packages PRs #621, #676, #757, #815, and #816, validating the Wukong
@@ -1,33 +1,33 @@
 class DingtalkWorkspaceCliBeta < Formula
  desc "Automate DingTalk workspace tasks from the terminal (beta channel)"
  homepage "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli"
-  version "1.0.55-beta.5"
+  version "1.0.55-beta.8"
  license "Apache-2.0"
  keg_only "it is the beta channel and conflicts with dingtalk-workspace-cli"

  on_macos do
    if Hardware::CPU.arm?
-      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.55-beta.5/dws-darwin-arm64.tar.gz"
-      sha256 "ac826a88062c6b839808eb28312dc026cc76bfc298cdedec34c468b87d5c22d6"
+      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.55-beta.8/dws-darwin-arm64.tar.gz"
+      sha256 "07fabf720fa98f82c56027df703a3ad3f0aec16c957ea684047928f9f74fa00f"
    else
-      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.55-beta.5/dws-darwin-amd64.tar.gz"
-      sha256 "361faab5cae2299fa2d8d305fd12dde7a992d408cfd5b1ad54ecd99073cd0a45"
+      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.55-beta.8/dws-darwin-amd64.tar.gz"
+      sha256 "fbec64dc5c3463a04de9720ffb1fd247196e619ea81b976b47ecbf751a17fb72"
    end
  end

  on_linux do
    if Hardware::CPU.arm?
-      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.55-beta.5/dws-linux-arm64.tar.gz"
-      sha256 "a8d0d39f037d6cb73aae3e4f7432fc58d3430971ce25d74c3c78580377d4dade"
+      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.55-beta.8/dws-linux-arm64.tar.gz"
+      sha256 "f111cdffef0188ddf954d2174fa0d318069bcec80104775483f13f645aa8089b"
    else
-      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.55-beta.5/dws-linux-amd64.tar.gz"
-      sha256 "4a0fc75b9b81f2d8670b9f71bace510515963c4285e9ec62c21aacb3c645c939"
+      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.55-beta.8/dws-linux-amd64.tar.gz"
+      sha256 "d69475b7f3cec4bad4c051834df22fbfadfa7075b82347e6ca7490f67d71d0b1"
    end
  end

  resource "skills" do
-    url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.55-beta.5/dws-skills.zip"
-    sha256 "7120a49c8bac90ea4c77668115b11edeca843e7fef0cc0ff2de538635a9884e1"
+    url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.55-beta.8/dws-skills.zip"
+    sha256 "be8c9267704cfef1319fc9cd2fcba5aebe45b670b4dc37d3dae15f65523356f8"
  end

  def install
@@ -1,33 +1,33 @@
 class DingtalkWorkspaceCli < Formula
  desc "Automate DingTalk workspace tasks from the terminal"
  homepage "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli"
-  version "1.0.54"
+  version "1.0.55"
  license "Apache-2.0"


  on_macos do
    if Hardware::CPU.arm?
-      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.54/dws-darwin-arm64.tar.gz"
-      sha256 "8ae0e52cf973f6fb3df61c67a41fd11e2df417a0c815762b6060cbcb5e600c08"
+      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.55/dws-darwin-arm64.tar.gz"
+      sha256 "dd753bbd051e5dd007cf433b8aa211c4a221dd73dfcb0b3783fa924d09f12351"
    else
-      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.54/dws-darwin-amd64.tar.gz"
-      sha256 "11b711b9d70dea62304bf5f8206c56b4e7ea91148dafe97fb7c0f844a2a61da3"
+      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.55/dws-darwin-amd64.tar.gz"
+      sha256 "f465eb7ac38a8a84eac4eb821fd15424bfc6f6245a60fa695ba97a639970dd77"
    end
  end

  on_linux do
    if Hardware::CPU.arm?
-      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.54/dws-linux-arm64.tar.gz"
-      sha256 "9c7ecb4c8cd55644b2faa73f6ce7843c0279b23793e23deb5061692ea71a0cf1"
+      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.55/dws-linux-arm64.tar.gz"
+      sha256 "5961be0fd551ec8e69b6fff2b1609f73486f7e6c3ffe8eb4bb99fa1ed691b401"
    else
-      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.54/dws-linux-amd64.tar.gz"
-      sha256 "8a0bc245747fc3facf98c8103c06da46852a30bff31ac93b0aa874e8c7e46db7"
+      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.55/dws-linux-amd64.tar.gz"
+      sha256 "051ba404a5f6a8fb15def0e0f5d9d273cf9d63f881df2fffe159f2c4ea3366e7"
    end
  end

  resource "skills" do
-    url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.54/dws-skills.zip"
-    sha256 "7450fd0115c75bfe6820c7099f348973d9353cca9d8d647c9cddcd70978a7ec0"
+    url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.55/dws-skills.zip"
+    sha256 "bd35f674f184001f5a03c7b5fa6029ebcda54f0054e15cd608b5b5e213ce2d05"
  end

  def install
@@ -0,0 +1,30 @@
+package app
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// TestMultiSkillSharedContractKeepsAccountSafetyRule pins the multi-account
+// safety rule that release run 30437390088 found missing: the MultiSkill e2e
+// contract asserts the exact phrase below inside the installed
+// dws-shared/SKILL.md, so removing it from the embedded skill source must
+// fail at PR time instead of at release time.
+func TestMultiSkillSharedContractKeepsAccountSafetyRule(t *testing.T) {
+	dir, cleanup, err := materializeEmbeddedSkillSource(skillSetupModeMulti)
+	if err != nil {
+		t.Fatalf("materialize embedded multi skill source: %v", err)
+	}
+	t.Cleanup(cleanup)
+
+	data, err := os.ReadFile(filepath.Join(dir, "dws-shared", "SKILL.md"))
+	if err != nil {
+		t.Fatalf("read embedded dws-shared/SKILL.md: %v", err)
+	}
+	const rule = "禁止选择第一项、最近登录或最近使用账号"
+	if !strings.Contains(string(data), rule) {
+		t.Fatalf("embedded dws-shared/SKILL.md lost the mandatory account safety rule %q", rule)
+	}
+}
@@ -17,7 +17,7 @@ import (

 const (
 	publicShortcutCount          = 265
-	schemaPublishedShortcutCount = 210
+	schemaPublishedShortcutCount = 215
 )

 func TestEmbeddedSchemaCoversOrExactlyExcludesEveryPublicShortcutContract(t *testing.T) {
@@ -106,7 +106,7 @@ func TestEmbeddedShortcutProgressiveQueriesReturnCompleteContracts(t *testing.T)

 	product := executeShortcutSchemaQuery(t, "chat")
 	productPayload, _ := product["product"].(map[string]any)
-	if got, want := int(product["count"].(float64)), 124; got != want {
+	if got, want := int(product["count"].(float64)), 129; got != want {
 		t.Fatalf("schema chat count = %d, want %d", got, want)
 	}
 	summaries := schemaContractObjectSlice(productPayload["tools"])
@@ -116,8 +116,8 @@ func TestEmbeddedShortcutProgressiveQueriesReturnCompleteContracts(t *testing.T)
 			shortcutCount++
 		}
 	}
-	if shortcutCount != 42 {
-		t.Fatalf("schema chat shortcut summaries = %d, want 42", shortcutCount)
+	if shortcutCount != 47 {
+		t.Fatalf("schema chat shortcut summaries = %d, want 47", shortcutCount)
 	}
 }

@@ -388,6 +388,7 @@ func shortcutCustomConstraintEvidence(description string) []string {
 		"绝对路径",
 		"..",
 		"最多 15 个字符",
+		"能力矩阵",
 	}
 	evidence := make([]string, 0, len(probes))
 	for _, probe := range probes {
@@ -1,17 +1,17 @@
 {
  "version": 1,
-  "source_hash": "sha256:eb6e44775a6e85f92ca31c90c876f67543ab928d8a8bda04f07a33dc802f7028",
-  "surface_hash": "sha256:29d4f5f43688cc01bc2277a4528b597de4fbab89a7b2f13fe2e56df85d1c66c4",
+  "source_hash": "sha256:f8cb29bdbeaceae6f04cbac8a93ea77f2a84f93f8304d25878c827b959bc0ba0",
+  "surface_hash": "sha256:60eee8e2f37d6d9d60689efce85082798eb9ad38b7ba7c0b471c3de676a85a16",
  "coverage": {
    "surface_products": 26,
    "products_with_metadata": 26,
-    "surface_tools": 840,
-    "tools_with_metadata": 840,
-    "tools_with_agent_summary": 840,
-    "tools_with_use_when": 840,
-    "tools_with_avoid_when": 840,
-    "tools_with_examples": 840,
-    "tools_with_interface_mode": 840,
+    "surface_tools": 845,
+    "tools_with_metadata": 845,
+    "tools_with_agent_summary": 845,
+    "tools_with_use_when": 845,
+    "tools_with_avoid_when": 845,
+    "tools_with_examples": 845,
+    "tools_with_interface_mode": 845,
    "unmatched_skill_tools": 122,
    "unreviewed_skill_tools": 11
  },
@@ -1,17 +1,17 @@
 {
  "version": 1,
-  "surface_hash": "sha256:29d4f5f43688cc01bc2277a4528b597de4fbab89a7b2f13fe2e56df85d1c66c4",
-  "source_hash": "sha256:c71b9bacfe2d73f5ad45151fada6fdc18bac69b266058a8b05647b6847c99835",
+  "surface_hash": "sha256:60eee8e2f37d6d9d60689efce85082798eb9ad38b7ba7c0b471c3de676a85a16",
+  "source_hash": "sha256:735bbf8e04cfc44db741e9b14ffe1698f80aac5d2662d2c1c41b0aadcee9098d",
  "catalog": {
    "agent_metadata": {
      "products_with_metadata": 26,
      "source": "embedded-skill-metadata",
-      "source_hash": "sha256:eb6e44775a6e85f92ca31c90c876f67543ab928d8a8bda04f07a33dc802f7028",
-      "surface_hash": "sha256:29d4f5f43688cc01bc2277a4528b597de4fbab89a7b2f13fe2e56df85d1c66c4",
+      "source_hash": "sha256:f8cb29bdbeaceae6f04cbac8a93ea77f2a84f93f8304d25878c827b959bc0ba0",
+      "surface_hash": "sha256:60eee8e2f37d6d9d60689efce85082798eb9ad38b7ba7c0b471c3de676a85a16",
      "surface_products": 26,
-      "surface_tools": 840,
-      "tools_with_agent_summary": 840,
-      "tools_with_metadata": 840,
+      "surface_tools": 845,
+      "tools_with_agent_summary": 845,
+      "tools_with_metadata": 845,
      "unmatched_skill_tools": 122,
      "version": 1
    },
@@ -7722,7 +7722,7 @@
        "id": "chat",
        "name": "群聊 / 消息 / 机器人",
        "runtime": true,
-        "tool_count": 124,
+        "tool_count": 129,
        "tools": [
          {
            "agent_metadata_source": "embedded-skill-metadata",
@@ -9800,7 +9800,7 @@
            "cli_name": "+at-me",
            "cli_path": "chat +at-me",
            "confirmation": "not_required",
-            "description": "当你想快速看回最近谁在群里或单聊里 @了你、但不想手动把起止时间换算成毫秒、也不想记 list-mentions 的一堆参数时使用；内部按本地时区算出「最近 N 天」（默认 7 天，可用 --days 调整回溯天数）的时间窗，搜索这段时间内 @我 的消息，再在本地把每条消息投影成发送人、时间、内容、所在会话四个关键字段。这是纯只读操作，只做搜索与本地投影，不会发送、撤回或标记任何消息。",
+            "description": "当你想快速看回最近谁在群里或单聊里 @了你、但不想手动把起止时间换算成毫秒、也不想记 list-mentions 的一堆参数时使用；内部按本地时区算出「最近 N 天」（默认 7 天，可用 --days 调整回溯天数）的时间窗，搜索这段时间内 @我 的消息，再在本地把每条消息投影成发送人、时间、内容、所在会话四个关键字段。默认只读且不会发送、撤回或标记任何消息；--download-resources 使用工作目录内安全路径、默认不覆盖和原子落盘，按既有安全下载约定无需交互确认。\n\n参数约束：\n  - --output-dir 必须是工作目录内的相对路径，不允许绝对路径或 .. 逃逸",
            "effect": "read",
            "idempotency": "idempotent",
            "interface_mode": "composite",
@@ -9811,7 +9811,7 @@
            "risk": "low",
            "title": "查最近 @我 的消息（自动算时间窗，投影发送人/时间/内容/会话）",
            "use_when": [
-              "当你想快速看回最近谁在群里或单聊里 @了你、但不想手动把起止时间换算成毫秒、也不想记 list-mentions 的一堆参数时使用；内部按本地时区算出「最近 N 天」（默认 7 天，可用 --days 调整回溯天数）的时间窗，搜索这段时间内 @我 的消息，再在本地把每条消息投影成发送人、时间、内容、所在会话四个关键字段。这是纯只读操作，只做搜索与本地投影，不会发送、撤回或标记任何消息。"
+              "当你想快速看回最近谁在群里或单聊里 @了你、但不想手动把起止时间换算成毫秒、也不想记 list-mentions 的一堆参数时使用；内部按本地时区算出「最近 N 天」（默认 7 天，可用 --days 调整回溯天数）的时间窗，搜索这段时间内 @我 的消息，再在本地把每条消息投影成发送人、时间、内容、所在会话四个关键字段。默认只读且不会发送、撤回或标记任何消息；--download-resources 使用工作目录内安全路径、默认不覆盖和原子落盘，按既有安全下载约定无需交互确认。"
            ]
          },
          {
@@ -10152,6 +10152,32 @@
              "当你想查看自己作为群主或管理员在管理哪些群时使用；只读分页返回，可用 --role OWNER/ADMIN 按角色过滤。"
            ]
          },
+          {
+            "agent_metadata_source": "embedded-skill-metadata",
+            "agent_summary": "拉取某个会话（群聊或单聊）的消息列表并投影出发言人/文本/时间",
+            "agent_summary_source": "dws-agent-selection/chat",
+            "availability": "available",
+            "avoid_when": [
+              "要跨多个会话按关键词、发送者或消息类型检索时使用 +search-msg；已有一批精确消息 ID 时使用 +messages-mget"
+            ],
+            "canonical_path": "chat.shortcut_chat_messages",
+            "cli_name": "+chat-messages",
+            "cli_path": "chat +chat-messages",
+            "confirmation": "not_required",
+            "description": "当你想快速看某个会话里的消息（谁在什么时间说了什么），而不想拿到一大坨原始消息字段时使用；群聊传 --group（群会话 ID，openConversationId），单聊传 --user（对方 userId），两者互斥且必须二选一。省略 --time 时默认从当前时间向前读取最近消息；也可指定时间边界并用 --direction newer/older 控制方向。内部据此调用群聊或单聊的消息列表接口，再在本地投影出每条消息的发言人、文本和时间。默认只读且不会发送或修改任何消息；--download-resources 使用工作目录内安全路径、默认不覆盖和原子落盘，按既有安全下载约定无需交互确认。\n\n参数约束：\n  - --group、--conversation-id、--id、--user、--open-dingtalk-id 必须且只能指定一个\n  - --output-dir 必须是工作目录内的相对路径，不允许绝对路径或 .. 逃逸",
+            "effect": "read",
+            "idempotency": "idempotent",
+            "interface_mode": "composite",
+            "interface_reason": "Reviewed built-in Shortcut adapter: it routes group or direct-message history reads, projects a stable message shape, and optionally orchestrates safe resource downloads with a failure ledger.",
+            "name": "shortcut_chat_messages",
+            "primary_cli_path": "chat +chat-messages",
+            "reviewed": true,
+            "risk": "low",
+            "title": "拉取某个会话（群聊或单聊）的消息列表并投影出发言人/文本/时间",
+            "use_when": [
+              "当你想快速看某个会话里的消息（谁在什么时间说了什么），而不想拿到一大坨原始消息字段时使用；群聊传 --group（群会话 ID，openConversationId），单聊传 --user（对方 userId），两者互斥且必须二选一。省略 --time 时默认从当前时间向前读取最近消息；也可指定时间边界并用 --direction newer/older 控制方向。内部据此调用群聊或单聊的消息列表接口，再在本地投影出每条消息的发言人、文本和时间。默认只读且不会发送或修改任何消息；--download-resources 使用工作目录内安全路径、默认不覆盖和原子落盘，按既有安全下载约定无需交互确认。"
+            ]
+          },
          {
            "agent_metadata_source": "embedded-skill-metadata",
            "agent_summary": "全员禁言 / 取消全员禁言",
@@ -10684,7 +10710,7 @@
            "cli_name": "+messages-mget",
            "cli_path": "chat +messages-mget",
            "confirmation": "not_required",
-            "description": "当你已有一批消息 openMsgId、需要批量取回完整详情、reaction 和可执行资源引用时使用；一次最多 50 条。--download-resources 可把所有可识别 mediaId 安全下载到工作目录内，并逐资源返回成功/失败 ledger。\n\n参数约束：\n  - --msg-ids 去重后必须包含 1-50 条消息 ID\n  - --output-dir 必须是工作目录内的相对路径，不允许绝对路径或 .. 逃逸",
+            "description": "当你已有一批消息 openMsgId、需要批量取回完整详情、reaction 和可执行资源引用时使用；一次最多 50 条。--download-resources 可把所有可识别 mediaId/fileId 安全下载到工作目录内，并逐资源返回成功/失败 ledger；本地下载路径受限于工作目录、默认不覆盖同名文件，按既有安全下载约定无需交互确认。\n\n参数约束：\n  - --msg-ids 去重后必须包含 1-50 条消息 ID\n  - --output-dir 必须是工作目录内的相对路径，不允许绝对路径或 .. 逃逸",
            "effect": "read",
            "idempotency": "idempotent",
            "interface_mode": "composite",
@@ -10695,7 +10721,7 @@
            "risk": "low",
            "title": "根据消息 ID 批量查询消息（最多 50 条）",
            "use_when": [
-              "当你已有一批消息 openMsgId、需要批量取回完整详情、reaction 和可执行资源引用时使用；一次最多 50 条。--download-resources 可把所有可识别 mediaId 安全下载到工作目录内，并逐资源返回成功/失败 ledger。"
+              "当你已有一批消息 openMsgId、需要批量取回完整详情、reaction 和可执行资源引用时使用；一次最多 50 条。--download-resources 可把所有可识别 mediaId/fileId 安全下载到工作目录内，并逐资源返回成功/失败 ledger；本地下载路径受限于工作目录、默认不覆盖同名文件，按既有安全下载约定无需交互确认。"
            ]
          },
          {
@@ -10750,6 +10776,32 @@
              "当你想知道自己发出的某条消息有哪些人已读/未读时使用；只读，需传会话 openConversationId 和该消息 openMessageId，可指定目标成员列表。"
            ]
          },
+          {
+            "agent_metadata_source": "embedded-skill-metadata",
+            "agent_summary": "统一发送文本、Markdown、当前用户文件或已有 mediaId 图片",
+            "agent_summary_source": "dws-agent-selection/chat",
+            "availability": "available",
+            "avoid_when": [
+              "需要 bot/webhook 发送媒体、卡片或 thread 回复时不要假设等价支持；改用真实存在的专用下层命令，缺少下层能力时停止"
+            ],
+            "canonical_path": "chat.shortcut_messages_send",
+            "cli_name": "+messages-send",
+            "cli_path": "chat +messages-send",
+            "confirmation": "user_required",
+            "description": "当你希望用同一个入口选择 current-user、bot 或 webhook 身份发送消息时使用；命令会按身份校验目标、内容和凭据并路由到真实下层。current-user 支持文本/Markdown、已有 mediaId 图片、安全相对路径文件上传和幂等键；--user 传 userId 时包括在 --dry-run 中也会先通过通讯录关键词搜索并按 userId 精确匹配 openDingTalkId。bot 支持群聊或批量单聊文本/Markdown；webhook 的目标由 token 所在群决定。不会把 user 文件能力伪装成 bot/webhook 等价能力。\n\n参数约束：\n  - --text、--markdown、--media-id、--file、--file-path 至少指定一个\n  - --text、--markdown、--media-id、--file、--file-path 互斥，最多指定一个\n  - --identity、--as 互斥，最多指定一个\n  - --group、--chat-id 互斥，最多指定一个\n  - --user、--open-dingtalk-id 互斥，最多指定一个\n  - --uuid、--idempotency-key 互斥，最多指定一个\n  - 目标、凭据和幂等参数受发送身份能力矩阵约束：user 必须指定一个群聊或单聊目标；bot 必须指定 robot-code 和一类目标；webhook 必须指定 webhook-token；幂等键仅 user 支持",
+            "effect": "write",
+            "idempotency": "unknown",
+            "interface_mode": "composite",
+            "interface_reason": "Reviewed composite send adapter: it selects current-user, bot, or webhook transport; current-user additionally supports live-compatible contact search with exact userId matching, mediaId images, and the native init/upload/commit local-file flow.",
+            "name": "shortcut_messages_send",
+            "primary_cli_path": "chat +messages-send",
+            "reviewed": true,
+            "risk": "medium",
+            "title": "统一发送文本、Markdown、当前用户文件或已有 mediaId 图片",
+            "use_when": [
+              "当你希望用同一个入口选择 current-user、bot 或 webhook 身份发送消息时使用；命令会按身份校验目标、内容和凭据并路由到真实下层。current-user 支持文本/Markdown、已有 mediaId 图片、安全相对路径文件上传和幂等键；--user 传 userId 时包括在 --dry-run 中也会先通过通讯录关键词搜索并按 userId 精确匹配 openDingTalkId。bot 支持群聊或批量单聊文本/Markdown；webhook 的目标由 token 所在群决定。不会把 user 文件能力伪装成 bot/webhook 等价能力。"
+            ]
+          },
          {
            "agent_metadata_source": "embedded-skill-metadata",
            "agent_summary": "自定义机器人 Webhook 发送群消息",
@@ -10776,6 +10828,32 @@
              "当你只有自定义机器人的 Webhook token、想往其所在群推送消息时使用；会实际通过 Webhook 发群消息，需传 token、标题、正文，可 @手机号/userId 或 @所有人。"
            ]
          },
+          {
+            "agent_metadata_source": "embedded-skill-metadata",
+            "agent_summary": "创建流式卡片，可在同一次调用中写入内容并结束",
+            "agent_summary_source": "dws-agent-selection/chat",
+            "availability": "available",
+            "avoid_when": [
+              "已有 bizId、只需要追加或更新现有卡片内容时使用 +messages-update-card"
+            ],
+            "canonical_path": "chat.shortcut_messages_send_card",
+            "cli_name": "+messages-send-card",
+            "cli_path": "chat +messages-send-card",
+            "confirmation": "user_required",
+            "description": "当你要发送一张流式卡片消息时使用；群 openConversationId、单聊 userId、单聊 openDingTalkId 严格三选一，分别使用 --group、--receiver、--receiver-open-dingtalk-id。--receiver 始终按 userId 通过通讯录关键词搜索做精确匹配，即使值以 D/d 开头也不会猜成 openDingTalkId；已有 openDingTalkId 时必须用显式参数直传。userId 包括在 --dry-run 时也会先解析。只传目标时创建卡片并返回 bizId，供后续 messages-update-card 流式更新；同时传 --content 时会自动串联创建和更新，默认以 flowStatus=3 完成，避免卡片停留在加载中。\n\n参数约束：\n  - --group、--receiver、--receiver-open-dingtalk-id 必须且只能指定一个\n  - --flow-status 必须在 1-5 之间，且显式指定时必须同时提供 --content",
+            "effect": "write",
+            "idempotency": "unknown",
+            "interface_mode": "composite",
+            "interface_reason": "Reviewed card lifecycle adapter: it can resolve a userId through contact search with exact matching, call create_and_send_card alone, or compose creation with update_streaming_card after extracting the returned bizId.",
+            "name": "shortcut_messages_send_card",
+            "primary_cli_path": "chat +messages-send-card",
+            "reviewed": true,
+            "risk": "medium",
+            "title": "创建流式卡片，可在同一次调用中写入内容并结束",
+            "use_when": [
+              "当你要发送一张流式卡片消息时使用；群 openConversationId、单聊 userId、单聊 openDingTalkId 严格三选一，分别使用 --group、--receiver、--receiver-open-dingtalk-id。--receiver 始终按 userId 通过通讯录关键词搜索做精确匹配，即使值以 D/d 开头也不会猜成 openDingTalkId；已有 openDingTalkId 时必须用显式参数直传。userId 包括在 --dry-run 时也会先解析。只传目标时创建卡片并返回 bizId，供后续 messages-update-card 流式更新；同时传 --content 时会自动串联创建和更新，默认以 flowStatus=3 完成，避免卡片停留在加载中。"
+            ]
+          },
          {
            "agent_metadata_source": "embedded-skill-metadata",
            "agent_summary": "流式更新卡片内容（最后一次 --flow-status 应为 3）",
@@ -10828,6 +10906,32 @@
              "当你想快速看一眼自己都加入了哪些群、以及每个群的会话ID、名称、群主和人数，而不想翻分页或盯着原始返回时使用；内部分页拉取你加入的群列表，把每个群防御式地投影成 会话id / 名称 / 群主 / 人数 / 类型 等关键字段，输出成干净的结果。可选 --type 在本地按群类型过滤（底层接口本身不带类型参数，故为客户端过滤）。这是只读操作，不会改动任何群或成员关系。"
            ]
          },
+          {
+            "agent_metadata_source": "embedded-skill-metadata",
+            "agent_summary": "多维搜索消息，可全量翻页并批量富化详情",
+            "agent_summary_source": "dws-agent-selection/chat",
+            "availability": "available",
+            "avoid_when": [
+              "只想读取一个已知会话的连续历史时使用 +chat-messages；已有精确消息 ID 时使用 +messages-mget"
+            ],
+            "canonical_path": "chat.shortcut_search_msg",
+            "cli_name": "+search-msg",
+            "cli_path": "chat +search-msg",
+            "confirmation": "not_required",
+            "description": "当你要按关键词、发送者、@对象、会话、消息类型或机器人来源组合搜索 IM 消息时使用；默认查询近 7 天，也可指定精确起止时间。--page-all 会连续拉取游标页，默认再按消息 ID 分批富化详情；任何续页或富化失败都会保留已取得结果并返回逐项失败 ledger，绝不把截断结果标成完整。--download-resources 使用工作目录内安全路径、默认不覆盖和原子落盘，按既有安全下载约定无需交互确认。\n\n参数约束：\n  - 至少指定一个内容、身份、会话或消息类型过滤条件\n  - 需与 --end 一起传\n  - 需与 --start 一起传\n  - --groups、--chat-id 互斥，最多指定一个\n  - --senders、--sender 互斥，最多指定一个\n  - --at-me、--is-at-me 互斥，最多指定一个\n  - --conversation-type、--chat-type 互斥，最多指定一个\n  - --limit、--page-size 互斥，最多指定一个\n  - --cursor、--page-token 互斥，最多指定一个\n  - --output-dir 必须是工作目录内的相对路径，不允许绝对路径或 .. 逃逸",
+            "effect": "read",
+            "idempotency": "idempotent",
+            "interface_mode": "composite",
+            "interface_reason": "Reviewed search adapter: it combines filters, cursor pagination, batched mget enrichment, stable projection, completeness accounting, and optional safe resource downloads.",
+            "name": "shortcut_search_msg",
+            "primary_cli_path": "chat +search-msg",
+            "reviewed": true,
+            "risk": "low",
+            "title": "多维搜索消息，可全量翻页并批量富化详情",
+            "use_when": [
+              "当你要按关键词、发送者、@对象、会话、消息类型或机器人来源组合搜索 IM 消息时使用；默认查询近 7 天，也可指定精确起止时间。--page-all 会连续拉取游标页，默认再按消息 ID 分批富化详情；任何续页或富化失败都会保留已取得结果并返回逐项失败 ledger，绝不把截断结果标成完整。--download-resources 使用工作目录内安全路径、默认不覆盖和原子落盘，按既有安全下载约定无需交互确认。"
+            ]
+          },
          {
            "agent_metadata_source": "embedded-skill-metadata",
            "agent_summary": "按群名直接给群发消息（自动搜群解析 openConversationId）",
@@ -10854,6 +10958,32 @@
              "当你只知道群的名字、想直接往这个群里发一条消息而不想先手动查群 ID 时使用；内部先按群名搜索群聊解析出唯一 openConversationId 再发送，群名匹配到多个群时会列出候选让你区分、绝不自行假定。会真实发出群消息。"
            ]
          },
+          {
+            "agent_metadata_source": "embedded-skill-metadata",
+            "agent_summary": "拉取某条话题消息的全部回复并投影出发言人/文本/时间",
+            "agent_summary_source": "dws-agent-selection/chat",
+            "availability": "available",
+            "avoid_when": [
+              "要回复 Thread 或发送新回复时不要使用此读取入口；当前没有经过验证的 thread writer Shortcut"
+            ],
+            "canonical_path": "chat.shortcut_thread_replies",
+            "cli_name": "+thread-replies",
+            "cli_path": "chat +thread-replies",
+            "confirmation": "not_required",
+            "description": "当你已经拿到某个群里一条「话题消息」的 threadId/topicId、想快速看这条话题下的全部回复（谁在什么时间回复了什么），而不想拿到一大坨原始消息字段时使用；内部按 --group（群会话 ID）和 --thread-id（兼容 --topic-id）拉取该话题的回复列表，可选 --time 指定起始时间、--limit 指定每页条数，再在本地投影出每条回复的发言人、文本和回复时间。默认只读且不会发送或修改任何消息；--download-resources 使用工作目录内安全路径、默认不覆盖和原子落盘，按既有安全下载约定无需交互确认。\n\n参数约束：\n  - --thread-id 与兼容参数 --topic-id 必须且只能指定一个\n  - --output-dir 必须是工作目录内的相对路径，不允许绝对路径或 .. 逃逸",
+            "effect": "read",
+            "idempotency": "idempotent",
+            "interface_mode": "composite",
+            "interface_reason": "Reviewed thread reader adapter: it accepts threadId/topicId, reads lower topic replies, projects stable message fields, and optionally downloads reply resources safely.",
+            "name": "shortcut_thread_replies",
+            "primary_cli_path": "chat +thread-replies",
+            "reviewed": true,
+            "risk": "low",
+            "title": "拉取某条话题消息的全部回复并投影出发言人/文本/时间",
+            "use_when": [
+              "当你已经拿到某个群里一条「话题消息」的 threadId/topicId、想快速看这条话题下的全部回复（谁在什么时间回复了什么），而不想拿到一大坨原始消息字段时使用；内部按 --group（群会话 ID）和 --thread-id（兼容 --topic-id）拉取该话题的回复列表，可选 --time 指定起始时间、--limit 指定每页条数，再在本地投影出每条回复的发言人、文本和回复时间。默认只读且不会发送或修改任何消息；--download-resources 使用工作目录内安全路径、默认不覆盖和原子落盘，按既有安全下载约定无需交互确认。"
+            ]
+          },
          {
            "agent_metadata_source": "embedded-skill-metadata",
            "agent_summary": "列出我有未读消息的会话（投影会话名/未读数/会话ID）",
@@ -26514,6 +26644,6 @@
      }
    ],
    "source": "embedded-command-catalog",
-    "tool_count": 840
+    "tool_count": 845
  }
 }
@@ -168,7 +168,6 @@
        "chat +chat-get-by-id",
        "chat +chat-members-get",
        "chat +chat-members-list",
-        "chat +chat-messages",
        "chat +chat-mute-member",
        "chat +chat-quit",
        "chat +chat-remove-bot",
@@ -205,15 +204,11 @@
        "chat +messages-reply",
        "chat +messages-resource-download",
        "chat +messages-resource-url",
-        "chat +messages-send",
        "chat +messages-send-by-bot",
-        "chat +messages-send-card",
        "chat +messages-set-pin",
        "chat +messages-set-top",
        "chat +messages-unset-pin",
-        "chat +messages-unset-top",
-        "chat +search-msg",
-        "chat +thread-replies"
+        "chat +messages-unset-top"
      ]
    }
  ]
@@ -496,6 +496,26 @@
    {
      "canonical_path": "chat.set_top_conversation",
      "cli_path": "chat set-top"
+    },
+    {
+      "canonical_path": "chat.shortcut_chat_messages",
+      "cli_path": "chat +chat-messages"
+    },
+    {
+      "canonical_path": "chat.shortcut_messages_send",
+      "cli_path": "chat +messages-send"
+    },
+    {
+      "canonical_path": "chat.shortcut_messages_send_card",
+      "cli_path": "chat +messages-send-card"
+    },
+    {
+      "canonical_path": "chat.shortcut_search_msg",
+      "cli_path": "chat +search-msg"
+    },
+    {
+      "canonical_path": "chat.shortcut_thread_replies",
+      "cli_path": "chat +thread-replies"
    }
  ]
 }
@@ -1152,6 +1152,32 @@
      "cli_path": "chat +chat-role-query-user",
      "runtime_gate": "none"
    },
+    "chat.shortcut_chat_messages": {
+      "effect": "read",
+      "risk": "low",
+      "confirmation": "not_required",
+      "idempotency": "idempotent",
+      "interface_mode": "composite",
+      "availability": "available",
+      "interface_reason": "Reviewed built-in Shortcut adapter: it routes group or direct-message history reads, projects a stable message shape, and optionally orchestrates safe resource downloads with a failure ledger.",
+      "reviewed": true,
+      "review_reason": "Reviewed against the executable Shortcut and group/direct lower read tools. Optional downloads stay read/not_required under the existing safe local-download convention: workspace-relative paths, no overwrite by default, and atomic publication.",
+      "cli_path": "chat +chat-messages",
+      "runtime_gate": "none"
+    },
+    "chat.shortcut_messages_send": {
+      "effect": "write",
+      "risk": "medium",
+      "confirmation": "user_required",
+      "idempotency": "unknown",
+      "interface_mode": "composite",
+      "availability": "available",
+      "interface_reason": "Reviewed composite send adapter: it selects current-user, bot, or webhook transport; current-user additionally supports live-compatible contact search with exact userId matching, mediaId images, and the native init/upload/commit local-file flow.",
+      "reviewed": true,
+      "review_reason": "Reviewed against every executable identity/content/target validation branch, authenticated contact-search response shape, and the real lower tool mappings; bot and webhook media are intentionally rejected because no equivalent lower capability exists.",
+      "cli_path": "chat +messages-send",
+      "runtime_gate": "typed_yes"
+    },
    "chat.shortcut_messages_send_by_webhook": {
      "effect": "write",
      "risk": "medium",
@@ -1165,6 +1191,25 @@
      "cli_path": "chat +messages-send-by-webhook",
      "runtime_gate": "typed_yes"
    },
+    "chat.shortcut_messages_send_card": {
+      "effect": "write",
+      "risk": "medium",
+      "confirmation": "user_required",
+      "idempotency": "unknown",
+      "interface_mode": "composite",
+      "availability": "available",
+      "interface_reason": "Reviewed card lifecycle adapter: it can resolve a userId through contact search with exact matching, call create_and_send_card alone, or compose creation with update_streaming_card after extracting the returned bizId.",
+      "parameters": {
+        "receiver-open-dingtalk-id": {
+          "property": "receiverOpenDingTalkId",
+          "required": false
+        }
+      },
+      "reviewed": true,
+      "review_reason": "Reviewed against authenticated contact-search resolution, create-only, two-action dry-run, create/update success, missing bizId, and partial-failure behavior that preserves the created bizId; the explicit openDingTalkId flag is bound to the lower interface's exact receiverOpenDingTalkId property.",
+      "cli_path": "chat +messages-send-card",
+      "runtime_gate": "typed_yes"
+    },
    "chat.shortcut_messages_list_direct": {
      "effect": "read",
      "risk": "low",
@@ -1200,7 +1245,7 @@
      "availability": "available",
      "interface_reason": "Reviewed built-in shortcut adapter: the executable CLI owns validation, optional multi-step orchestration, output projection, and confirmation; the complete command contract is not represented by one pinned MCP interface_ref.",
      "reviewed": true,
-      "review_reason": "Reviewed against the built-in Shortcut registry and mounted Cobra command: publishes the executable risk gate and composite interface without inventing a direct MCP identity.",
+      "review_reason": "Reviewed against the built-in Shortcut registry and mounted Cobra command. Optional downloads stay read/not_required under the existing safe local-download convention and therefore do not create a non-interactive confirmation no-op.",
      "cli_path": "chat +messages-mget",
      "runtime_gate": "none"
    },
@@ -1265,7 +1310,7 @@
      "availability": "available",
      "interface_reason": "Reviewed built-in shortcut adapter: the executable CLI owns validation, optional multi-step orchestration, output projection, and confirmation; the complete command contract is not represented by one pinned MCP interface_ref.",
      "reviewed": true,
-      "review_reason": "Reviewed against the built-in Shortcut registry and mounted Cobra command: publishes the executable risk gate and composite interface without inventing a direct MCP identity.",
+      "review_reason": "Reviewed against the built-in Shortcut registry and mounted Cobra command. Optional downloads stay read/not_required under the existing safe local-download convention and therefore do not create a non-interactive confirmation no-op.",
      "cli_path": "chat +at-me",
      "runtime_gate": "none"
    },
@@ -1321,6 +1366,19 @@
      "cli_path": "chat +my-groups",
      "runtime_gate": "none"
    },
+    "chat.shortcut_search_msg": {
+      "effect": "read",
+      "risk": "low",
+      "confirmation": "not_required",
+      "idempotency": "idempotent",
+      "interface_mode": "composite",
+      "availability": "available",
+      "interface_reason": "Reviewed search adapter: it combines filters, cursor pagination, batched mget enrichment, stable projection, completeness accounting, and optional safe resource downloads.",
+      "reviewed": true,
+      "review_reason": "Reviewed against the executable advanced-search flags plus page and enrichment ledgers. Optional downloads stay read/not_required under the existing safe local-download convention and therefore do not create a non-interactive confirmation no-op.",
+      "cli_path": "chat +search-msg",
+      "runtime_gate": "none"
+    },
    "chat.shortcut_send_to_group": {
      "effect": "write",
      "risk": "medium",
@@ -1334,6 +1392,19 @@
      "cli_path": "chat +send-to-group",
      "runtime_gate": "typed_yes"
    },
+    "chat.shortcut_thread_replies": {
+      "effect": "read",
+      "risk": "low",
+      "confirmation": "not_required",
+      "idempotency": "idempotent",
+      "interface_mode": "composite",
+      "availability": "available",
+      "interface_reason": "Reviewed thread reader adapter: it accepts threadId/topicId, reads lower topic replies, projects stable message fields, and optionally downloads reply resources safely.",
+      "reviewed": true,
+      "review_reason": "Reviewed against the executable thread/topic alias contract and real list_topic_replies mapping. Optional downloads stay read/not_required under the existing safe local-download convention and therefore do not create a non-interactive confirmation no-op.",
+      "cli_path": "chat +thread-replies",
+      "runtime_gate": "none"
+    },
    "chat.shortcut_unread_chats": {
      "effect": "read",
      "risk": "low",
@@ -7,7 +7,7 @@
    "channel": "open-source"
  },
  "coverage": {
-    "source_tools": 840,
+    "source_tools": 845,
    "matched_tools": 71
  },
  "tools": {
@@ -2110,6 +2110,46 @@
        "ShortcutRegistry:chat +chat-role-query-user"
      ]
    },
+    "chat.shortcut_chat_messages": {
+      "agent_summary": "拉取某个会话（群聊或单聊）的消息列表并投影出发言人/文本/时间",
+      "use_when": [
+        "当你想快速看某个会话里的消息（谁在什么时间说了什么），而不想拿到一大坨原始消息字段时使用；群聊传 --group（群会话 ID，openConversationId），单聊传 --user（对方 userId），两者互斥且必须二选一。省略 --time 时默认从当前时间向前读取最近消息；也可指定时间边界并用 --direction newer/older 控制方向。内部据此调用群聊或单聊的消息列表接口，再在本地投影出每条消息的发言人、文本和时间。默认只读且不会发送或修改任何消息；--download-resources 使用工作目录内安全路径、默认不覆盖和原子落盘，按既有安全下载约定无需交互确认。"
+      ],
+      "avoid_when": [
+        "要跨多个会话按关键词、发送者或消息类型检索时使用 +search-msg；已有一批精确消息 ID 时使用 +messages-mget"
+      ],
+      "examples": [
+        "dws chat +chat-messages --group <openConversationId> --direction older",
+        "dws chat +chat-messages --open-dingtalk-id <openDingTalkId> --download-resources --output-dir ./downloads"
+      ],
+      "reviewed": true,
+      "review_reason": "Agent-authored from the verified group/direct routing, stable projection, pagination, and optional safe resource workflow; it distinguishes conversation history from cross-conversation search and exact-ID mget.",
+      "source_refs": [
+        "internal/cli/schema_command_registry.json#chat.shortcut_chat_messages",
+        "cobra-help:dws chat +chat-messages",
+        "ShortcutRegistry:chat +chat-messages"
+      ]
+    },
+    "chat.shortcut_messages_send": {
+      "agent_summary": "统一发送文本、Markdown、当前用户文件或已有 mediaId 图片",
+      "use_when": [
+        "当你希望用同一个入口选择 current-user、bot 或 webhook 身份发送消息时使用；命令会按身份校验目标、内容和凭据并路由到真实下层。current-user 支持文本/Markdown、已有 mediaId 图片、安全相对路径文件上传和幂等键；--user 传 userId 时包括在 --dry-run 中也会先通过通讯录关键词搜索并按 userId 精确匹配 openDingTalkId。bot 支持群聊或批量单聊文本/Markdown；webhook 的目标由 token 所在群决定。不会把 user 文件能力伪装成 bot/webhook 等价能力。"
+      ],
+      "avoid_when": [
+        "需要 bot/webhook 发送媒体、卡片或 thread 回复时不要假设等价支持；改用真实存在的专用下层命令，缺少下层能力时停止"
+      ],
+      "examples": [
+        "dws chat +messages-send --as user --chat-id <openConversationId> --markdown \"## 周报\" --idempotency-key <key>",
+        "dws chat +messages-send --as user --user <userId> --msg-type file --file ./report.pdf"
+      ],
+      "reviewed": true,
+      "review_reason": "Agent-authored from the verified identity/content capability matrix, live-compatible contact search with exact userId matching, native local-file upload flow, and fail-closed rejection of unsupported bot/webhook media.",
+      "source_refs": [
+        "internal/cli/schema_command_registry.json#chat.shortcut_messages_send",
+        "cobra-help:dws chat +messages-send",
+        "ShortcutRegistry:chat +messages-send"
+      ]
+    },
    "chat.shortcut_messages_send_by_webhook": {
      "agent_summary": "自定义机器人 Webhook 发送群消息",
      "use_when": [
@@ -2129,6 +2169,26 @@
        "ShortcutRegistry:chat +messages-send-by-webhook"
      ]
    },
+    "chat.shortcut_messages_send_card": {
+      "agent_summary": "创建流式卡片，可在同一次调用中写入内容并结束",
+      "use_when": [
+        "当你要发送一张流式卡片消息时使用；群 openConversationId、单聊 userId、单聊 openDingTalkId 严格三选一，分别使用 --group、--receiver、--receiver-open-dingtalk-id。--receiver 始终按 userId 通过通讯录关键词搜索做精确匹配，即使值以 D/d 开头也不会猜成 openDingTalkId；已有 openDingTalkId 时必须用显式参数直传。userId 包括在 --dry-run 时也会先解析。只传目标时创建卡片并返回 bizId，供后续 messages-update-card 流式更新；同时传 --content 时会自动串联创建和更新，默认以 flowStatus=3 完成，避免卡片停留在加载中。"
+      ],
+      "avoid_when": [
+        "已有 bizId、只需要追加或更新现有卡片内容时使用 +messages-update-card"
+      ],
+      "examples": [
+        "dws chat +messages-send-card --group <openConversationId> --content \"任务已完成\"",
+        "dws chat +messages-send-card --receiver <userId>"
+      ],
+      "reviewed": true,
+      "review_reason": "Agent-authored from the verified create-only and create-then-update lifecycle, live-compatible contact search with exact userId matching, explicit userId/openDingTalkId routing, two-action dry-run, bizId extraction, and partial-failure reporting.",
+      "source_refs": [
+        "internal/cli/schema_command_registry.json#chat.shortcut_messages_send_card",
+        "cobra-help:dws chat +messages-send-card",
+        "ShortcutRegistry:chat +messages-send-card"
+      ]
+    },
    "chat.shortcut_messages_list_direct": {
      "agent_summary": "拉取单聊会话消息",
      "use_when": [
@@ -2170,7 +2230,7 @@
    "chat.shortcut_messages_mget": {
      "agent_summary": "根据消息 ID 批量查询消息（最多 50 条）",
      "use_when": [
-        "当你已有一批消息 openMsgId、需要批量取回完整详情、reaction 和可执行资源引用时使用；一次最多 50 条。--download-resources 可把所有可识别 mediaId 安全下载到工作目录内，并逐资源返回成功/失败 ledger。"
+        "当你已有一批消息 openMsgId、需要批量取回完整详情、reaction 和可执行资源引用时使用；一次最多 50 条。--download-resources 可把所有可识别 mediaId/fileId 安全下载到工作目录内，并逐资源返回成功/失败 ledger；本地下载路径受限于工作目录、默认不覆盖同名文件，按既有安全下载约定无需交互确认。"
      ],
      "avoid_when": [
        "需要该 Shortcut 未公开的底层参数、原始响应或不同执行语义时，改用对应原子命令"
@@ -2265,7 +2325,7 @@
    "chat.shortcut_at_me": {
      "agent_summary": "查最近 @我 的消息（自动算时间窗，投影发送人/时间/内容/会话）",
      "use_when": [
-        "当你想快速看回最近谁在群里或单聊里 @了你、但不想手动把起止时间换算成毫秒、也不想记 list-mentions 的一堆参数时使用；内部按本地时区算出「最近 N 天」（默认 7 天，可用 --days 调整回溯天数）的时间窗，搜索这段时间内 @我 的消息，再在本地把每条消息投影成发送人、时间、内容、所在会话四个关键字段。这是纯只读操作，只做搜索与本地投影，不会发送、撤回或标记任何消息。"
+        "当你想快速看回最近谁在群里或单聊里 @了你、但不想手动把起止时间换算成毫秒、也不想记 list-mentions 的一堆参数时使用；内部按本地时区算出「最近 N 天」（默认 7 天，可用 --days 调整回溯天数）的时间窗，搜索这段时间内 @我 的消息，再在本地把每条消息投影成发送人、时间、内容、所在会话四个关键字段。默认只读且不会发送、撤回或标记任何消息；--download-resources 使用工作目录内安全路径、默认不覆盖和原子落盘，按既有安全下载约定无需交互确认。"
      ],
      "avoid_when": [
        "需要该 Shortcut 未公开的底层参数、原始响应或不同执行语义时，改用对应原子命令"
@@ -2359,6 +2419,26 @@
        "ShortcutRegistry:chat +my-groups"
      ]
    },
+    "chat.shortcut_search_msg": {
+      "agent_summary": "多维搜索消息，可全量翻页并批量富化详情",
+      "use_when": [
+        "当你要按关键词、发送者、@对象、会话、消息类型或机器人来源组合搜索 IM 消息时使用；默认查询近 7 天，也可指定精确起止时间。--page-all 会连续拉取游标页，默认再按消息 ID 分批富化详情；任何续页或富化失败都会保留已取得结果并返回逐项失败 ledger，绝不把截断结果标成完整。--download-resources 使用工作目录内安全路径、默认不覆盖和原子落盘，按既有安全下载约定无需交互确认。"
+      ],
+      "avoid_when": [
+        "只想读取一个已知会话的连续历史时使用 +chat-messages；已有精确消息 ID 时使用 +messages-mget"
+      ],
+      "examples": [
+        "dws chat +search-msg --query \"周报\" --senders <openDingTalkId> --days 3 --page-all",
+        "dws chat +search-msg --group <openConversationId> --message-type file --download-resources --output-dir ./downloads"
+      ],
+      "reviewed": true,
+      "review_reason": "Agent-authored from the verified filter mapping, cursor pagination, batched mget enrichment, completeness ledger, and shared safe resource workflow.",
+      "source_refs": [
+        "internal/cli/schema_command_registry.json#chat.shortcut_search_msg",
+        "cobra-help:dws chat +search-msg",
+        "ShortcutRegistry:chat +search-msg"
+      ]
+    },
    "chat.shortcut_send_to_group": {
      "agent_summary": "按群名直接给群发消息（自动搜群解析 openConversationId）",
      "use_when": [
@@ -2378,6 +2458,26 @@
        "ShortcutRegistry:chat +send-to-group"
      ]
    },
+    "chat.shortcut_thread_replies": {
+      "agent_summary": "拉取某条话题消息的全部回复并投影出发言人/文本/时间",
+      "use_when": [
+        "当你已经拿到某个群里一条「话题消息」的 threadId/topicId、想快速看这条话题下的全部回复（谁在什么时间回复了什么），而不想拿到一大坨原始消息字段时使用；内部按 --group（群会话 ID）和 --thread-id（兼容 --topic-id）拉取该话题的回复列表，可选 --time 指定起始时间、--limit 指定每页条数，再在本地投影出每条回复的发言人、文本和回复时间。默认只读且不会发送或修改任何消息；--download-resources 使用工作目录内安全路径、默认不覆盖和原子落盘，按既有安全下载约定无需交互确认。"
+      ],
+      "avoid_when": [
+        "要回复 Thread 或发送新回复时不要使用此读取入口；当前没有经过验证的 thread writer Shortcut"
+      ],
+      "examples": [
+        "dws chat +thread-replies --group <openConversationId> --thread-id <threadId>",
+        "dws chat +thread-replies --group <openConversationId> --topic-id <topicId> --download-resources --output-dir ./downloads"
+      ],
+      "reviewed": true,
+      "review_reason": "Agent-authored from the verified thread/topic alias, lower list_topic_replies mapping, stable projection, group-context fallback, and optional safe resource workflow.",
+      "source_refs": [
+        "internal/cli/schema_command_registry.json#chat.shortcut_thread_replies",
+        "cobra-help:dws chat +thread-replies",
+        "ShortcutRegistry:chat +thread-replies"
+      ]
+    },
    "chat.shortcut_unread_chats": {
      "agent_summary": "列出我有未读消息的会话（投影会话名/未读数/会话ID）",
      "use_when": [
@@ -13,6 +13,7 @@ import (
 	"strconv"
 	"strings"
 	"time"
+	"unicode"
 	"unicode/utf8"

 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/cli"
@@ -289,6 +290,47 @@ func normalizeAtPlaceholders(text string, ids []string, wrapAngle bool) string {
 	return text
 }

+// NormalizeMessageMentions applies the placeholder convention required by the
+// selected sender identity and ensures a declared @all is present in the body.
+// Current-user messages use <@id>/<@all>; bot and webhook messages use
+// @id/@mobile/@all.
+func NormalizeMessageMentions(text string, ids []string, atAll, wrapAngle bool) string {
+	text = normalizeAtPlaceholders(text, ids, wrapAngle)
+	allPlaceholder := "@all"
+	if wrapAngle {
+		text = normalizeAtPlaceholders(text, []string{"all"}, true)
+		allPlaceholder = "<@all>"
+	} else {
+		text = strings.ReplaceAll(text, "<@all>", "@all")
+	}
+	if atAll && !containsMessageMention(text, allPlaceholder) {
+		text = allPlaceholder + " " + text
+	}
+	return text
+}
+
+func containsMessageMention(text, placeholder string) bool {
+	if strings.HasPrefix(placeholder, "<") {
+		return strings.Contains(text, placeholder)
+	}
+	for searchFrom := 0; ; {
+		offset := strings.Index(text[searchFrom:], placeholder)
+		if offset < 0 {
+			return false
+		}
+		end := searchFrom + offset + len(placeholder)
+		if end == len(text) {
+			return true
+		}
+		next, _ := utf8.DecodeRuneInString(text[end:])
+		if !unicode.IsLetter(next) && !unicode.IsDigit(next) &&
+			next != '_' && next != '-' {
+			return true
+		}
+		searchFrom = end
+	}
+}
+
 func resolveOpenDingTalkID(ctx context.Context, value string) (string, error) {
 	ids, err := resolveOpenDingTalkIDs(ctx, []string{value})
 	if err != nil {
@@ -114,6 +114,18 @@ func TestCrossPlatformCoverageChatDirectionAndScalarCoverage(t *testing.T) {
 	for _, wrap := range []bool{true, false} {
 		_ = normalizeAtPlaceholders("hello @u1 <@u2>", []string{"", "u1", "u2"}, wrap)
 	}
+	if got := NormalizeMessageMentions("hello @u1", []string{"u1"}, true, true); got != "<@all> hello <@u1>" {
+		t.Fatalf("current-user mention normalization = %q", got)
+	}
+	if got := NormalizeMessageMentions("<@all> <@u1>", []string{"u1"}, true, false); got != "@all @u1" {
+		t.Fatalf("bot mention normalization = %q", got)
+	}
+	if got := NormalizeMessageMentions("@alliance hello", nil, true, false); got != "@all @alliance hello" {
+		t.Fatalf("bot @all token detection = %q", got)
+	}
+	if got := NormalizeMessageMentions("hello @all", nil, true, false); got != "hello @all" {
+		t.Fatalf("trailing bot @all detection = %q", got)
+	}
 }

 func TestCrossPlatformCoverageChatContactMappingCoverage(t *testing.T) {
@@ -0,0 +1,43 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+
+package helpers
+
+import "context"
+
+// ConversationLocalFileMeta exposes the already-reviewed native chat upload
+// metadata to built-in semantic Shortcuts. It remains an alias so the native
+// Cobra leaf and Shortcut use exactly the same upload implementation.
+type ConversationLocalFileMeta = conversationLocalFileMeta
+
+// BuildConversationLocalFileMeta validates a local file and computes the
+// metadata required by DingTalk's conversation-file upload flow.
+func BuildConversationLocalFileMeta(filePath, fileName, md5Value string) (ConversationLocalFileMeta, error) {
+	return buildConversationLocalFileMeta(filePath, fileName, md5Value)
+}
+
+// UploadConversationLocalFile executes the existing init -> HTTP upload ->
+// commit flow and returns the commit response for message-content assembly.
+func UploadConversationLocalFile(
+	ctx context.Context,
+	targetArgs map[string]any,
+	meta ConversationLocalFileMeta,
+	uuid string,
+) (string, error) {
+	return uploadConversationLocalFile(ctx, targetArgs, meta, uuid)
+}
+
+// ParseConversationFileSendIDs extracts the committed dentry and space IDs.
+func ParseConversationFileSendIDs(text string) (int64, int64, error) {
+	return parseConversationFileSendIDs(text)
+}
+
+// BuildConversationFileContent renders the exact file-message content accepted
+// by send_personal_message.
+func BuildConversationFileContent(
+	dentryID, spaceID int64,
+	meta ConversationLocalFileMeta,
+) (string, error) {
+	return buildConversationFileContent(dentryID, spaceID, meta)
+}
@@ -0,0 +1,87 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+
+package helpers
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestCrossPlatformCoverageConversationFileShortcutWrappersReuseNativeFlow(t *testing.T) {
+	file := filepath.Join(t.TempDir(), "report.txt")
+	if err := os.WriteFile(file, []byte("content"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	meta, err := BuildConversationLocalFileMeta(file, "", "")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if meta.FileName != "report.txt" || meta.FileSize != 7 {
+		t.Fatalf("meta = %#v", meta)
+	}
+	content, err := BuildConversationFileContent(11, 22, meta)
+	if err != nil || !strings.Contains(content, `"dentryId":11`) {
+		t.Fatalf("content = %q, %v", content, err)
+	}
+	dentryID, spaceID, err := ParseConversationFileSendIDs(`{"result":{"dentryId":11,"spaceId":22}}`)
+	if err != nil || dentryID != 11 || spaceID != 22 {
+		t.Fatalf("ids = %d/%d, %v", dentryID, spaceID, err)
+	}
+
+	oldPut := httpPutFile
+	t.Cleanup(func() { httpPutFile = oldPut })
+	var putPath string
+	httpPutFile = func(_ context.Context, _ string, _ map[string]string, localPath string, size int64) error {
+		putPath = localPath
+		if size != 7 {
+			t.Errorf("upload size = %d", size)
+		}
+		return nil
+	}
+	caller := &scriptedToolCaller{steps: []scriptedToolStep{
+		{text: `{"resourceUrl":"https://upload.example.test/file","uploadKey":"key"}`},
+		{text: `{"result":{"dentryId":11,"spaceId":22}}`},
+	}}
+	installScriptedCaller(t, caller)
+	commit, err := UploadConversationLocalFile(
+		context.Background(),
+		map[string]any{"openConversationId": "cid"},
+		meta,
+		"uuid",
+	)
+	if err != nil || !strings.Contains(commit, `"dentryId":11`) || putPath != file || caller.calls != 2 {
+		t.Fatalf("upload = %q, path=%q calls=%d err=%v", commit, putPath, caller.calls, err)
+	}
+}
+
+func TestCrossPlatformCoverageReadToolNameContractAndHelperBoundary(t *testing.T) {
+	for tool, want := range map[string]bool{
+		" get_conversation ":               true,
+		"LIST_MESSAGES":                    true,
+		"query_send_status":                true,
+		"search_messages":                  true,
+		"unread_message_conversation_list": true,
+		"send_personal_message":            false,
+		"":                                 false,
+	} {
+		if got := IsReadToolName(tool); got != want {
+			t.Errorf("IsReadToolName(%q) = %v, want %v", tool, got, want)
+		}
+	}
+
+	caller := &helpersReadCaller{
+		helpersCoreCaller: &helpersCoreCaller{format: "json", dry: true},
+		readResult:        textToolResult(`{"success":true}`),
+	}
+	installHelpersCoreDeps(t, caller)
+	if _, err := CallMCPReadToolTextOnServer("chat", "send_personal_message", nil); err == nil {
+		t.Fatal("write tool was accepted by the read helper boundary")
+	}
+	if caller.readCalls != 0 || caller.calls != 0 {
+		t.Fatalf("rejected write reached caller: read=%d regular=%d", caller.readCalls, caller.calls)
+	}
+}
@@ -156,6 +156,12 @@ func callMCPToolReturnTextOnServer(ctx context.Context, serverID, toolName strin
 // returning a synthetic dry-run envelope that looks like business data.
 func CallMCPReadToolTextOnServer(serverID, toolName string, args map[string]any) (string, error) {
 	ctx := context.Background()
+	if !IsReadToolName(toolName) {
+		return "", &CLIError{
+			Code:    CodeMCPToolError,
+			Message: fmt.Sprintf("tool %q is not allowed on the dry-run read channel", toolName),
+		}
+	}
 	if deps == nil || deps.Caller == nil {
 		return "", &CLIError{
 			Code:    CodeMCPToolError,
@@ -176,6 +182,22 @@ func CallMCPReadToolTextOnServer(serverID, toolName string, args map[string]any)
 	return parseMCPToolTextResult(serverID, toolName, result, err)
 }

+// IsReadToolName is the fail-closed naming contract for the dry-run read
+// channel. Both the Shortcut runtime and the helper boundary enforce it so a
+// future direct helper caller cannot accidentally route a write tool through
+// ReadToolCaller.
+func IsReadToolName(toolName string) bool {
+	toolName = strings.TrimSpace(strings.ToLower(toolName))
+	for _, prefix := range []string{
+		"get_", "list_", "query_", "search_", "unread_",
+	} {
+		if strings.HasPrefix(toolName, prefix) {
+			return true
+		}
+	}
+	return false
+}
+
 func parseMCPToolTextResult(serverID, toolName string, result *edition.ToolResult, err error) (string, error) {
 	if err != nil {
 		if patErr := reclassifyPATFromError(err); patErr != nil {
@@ -14,9 +14,10 @@
 package chat

 import (
+	"encoding/json"
 	"fmt"
-	"os"
 	"path/filepath"
+	"sort"
 	"strings"

 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut"
@@ -318,7 +319,7 @@ func listMessageProjectOneWithReactions(m map[string]any, includeReactions bool)
 	if quoted := chatmsg.QuotedMessage(m); len(quoted) > 0 {
 		row["quotedMessage"] = quoted
 	}
-	if resources := chatmsg.Resources(m); len(resources) > 0 {
+	if resources := chatmsg.ResourcesDeep(m); len(resources) > 0 {
 		row["resourceRefs"] = resources
 	}
 	projectForwarded := func(item map[string]any) map[string]any {
@@ -525,39 +526,26 @@ var MessagesMget = shortcut.Shortcut{
 	Command:     "+messages-mget",
 	Product:     "im",
 	Description: "根据消息 ID 批量查询消息（最多 50 条）",
-	Intent:      "当你已有一批消息 openMsgId、需要批量取回完整详情、reaction 和可执行资源引用时使用；一次最多 50 条。--download-resources 可把所有可识别 mediaId 安全下载到工作目录内，并逐资源返回成功/失败 ledger。",
+	Intent:      "当你已有一批消息 openMsgId、需要批量取回完整详情、reaction 和可执行资源引用时使用；一次最多 50 条。--download-resources 可把所有可识别 mediaId/fileId 安全下载到工作目录内，并逐资源返回成功/失败 ledger；本地下载路径受限于工作目录、默认不覆盖同名文件，按既有安全下载约定无需交互确认。",
 	Risk:        shortcut.RiskRead,
-	Flags: []shortcut.Flag{
+	Flags: append([]shortcut.Flag{
 		{Name: "msg-ids", Type: shortcut.FlagStringSlice, Desc: "消息 openMsgId 列表；--msg-ids 去重后必须包含 1-50 条消息 ID", Required: true},
 		{Name: "no-reactions", Type: shortcut.FlagBool, Desc: "不输出消息 reaction（默认输出）"},
-		{Name: "download-resources", Type: shortcut.FlagBool, Desc: "自动下载消息中的全部可识别 mediaId 资源"},
-		{Name: "output-dir", Type: shortcut.FlagString, Default: "./downloads", Desc: "资源输出目录；--output-dir 必须是工作目录内的相对路径，不允许绝对路径或 .. 逃逸"},
-		{Name: "overwrite", Type: shortcut.FlagBool, Desc: "允许覆盖同名资源文件（默认拒绝）"},
-	},
-	Constraints: []shortcut.Constraint{
+	}, MessageResourceDownloadFlags()...),
+	Constraints: append([]shortcut.Constraint{
 		{
 			Kind:        shortcut.ConstraintCustom,
 			Flags:       []string{"msg-ids"},
 			Description: "--msg-ids 去重后必须包含 1-50 条消息 ID",
 		},
-		{
-			Kind:        shortcut.ConstraintCustom,
-			Flags:       []string{"output-dir"},
-			Description: "--output-dir 必须是工作目录内的相对路径，不允许绝对路径或 .. 逃逸",
-		},
-	},
+	}, MessageResourceDownloadConstraints()...),
 	Tips: []string{`dws chat +messages-mget --msg-ids msgId1,msgId2`},
 	Validate: func(rt *shortcut.RuntimeContext) error {
 		ids := uniqueShortcutStrings(rt.StrSlice("msg-ids"))
 		if len(ids) < 1 || len(ids) > 50 {
 			return fmt.Errorf("--msg-ids 去重后必须包含 1-50 条消息 ID，当前 %d 条", len(ids))
 		}
-		if rt.Bool("download-resources") {
-			if err := validateResourceDownloadOutputFlag(rt.Str("output-dir"), "--output-dir"); err != nil {
-				return err
-			}
-		}
-		return nil
+		return ValidateMessageResourceDownload(rt)
 	},
 	Execute: func(rt *shortcut.RuntimeContext) error {
 		ids := uniqueShortcutStrings(rt.StrSlice("msg-ids"))
@@ -587,81 +575,194 @@ var MessagesMget = shortcut.Shortcut{
 			"messages":           messages,
 		}
 		if rt.Bool("download-resources") {
-			ledger, err := downloadMgetResources(rt, rawMessages)
-			if err != nil {
-				return err
-			}
-			payload["resourceDownloads"] = ledger
+			payload["resourceDownloads"] = DownloadMessageResources(rt, rawMessages, "")
 		}
 		return rt.Output(payload)
 	},
 }

-func downloadMgetResources(rt *shortcut.RuntimeContext, messages []map[string]any) (map[string]any, error) {
+// MessageResourceDownloadFlags returns the common opt-in resource workflow used
+// by message list, search, mget, @me and thread-reading Shortcuts.
+func MessageResourceDownloadFlags() []shortcut.Flag {
+	return []shortcut.Flag{
+		{Name: "download-resources", Type: shortcut.FlagBool, Desc: "自动下载消息中的全部可识别 mediaId/fileId 资源"},
+		{Name: "output-dir", Type: shortcut.FlagString, Default: "./downloads", Desc: "资源输出目录；必须是工作目录内的相对路径，禁止绝对路径和 .. 逃逸"},
+		{Name: "overwrite", Type: shortcut.FlagBool, Desc: "允许覆盖同名资源文件（默认拒绝）"},
+	}
+}
+
+// MessageResourceDownloadConstraints publishes the shared safe-output rule.
+func MessageResourceDownloadConstraints() []shortcut.Constraint {
+	return []shortcut.Constraint{{
+		Kind:        shortcut.ConstraintCustom,
+		Flags:       []string{"output-dir"},
+		Description: "--output-dir 必须是工作目录内的相对路径，不允许绝对路径或 .. 逃逸",
+	}}
+}
+
+// ValidateMessageResourceDownload validates the output path only when the
+// caller opts into local writes.
+func ValidateMessageResourceDownload(rt *shortcut.RuntimeContext) error {
+	if !rt.Bool("download-resources") {
+		return nil
+	}
+	return validateResourceDownloadOutputFlag(rt.Str("output-dir"), "--output-dir")
+}
+
+// DownloadMessageResources downloads every unique message resource reference
+// and returns a per-resource success/failure ledger. A fallback conversation
+// ID lets group/thread list commands supply context when a mediaId item's lower
+// response omits it; fileId resources route through the existing drive leaf.
+func DownloadMessageResources(
+	rt *shortcut.RuntimeContext,
+	messages []map[string]any,
+	fallbackConversationID string,
+) map[string]any {
 	resources := make([]map[string]any, 0)
 	for _, message := range messages {
-		resources = append(resources, chatmsg.Resources(message)...)
+		resources = append(resources, chatmsg.ResourcesDeep(message)...)
 	}
+	discoveredCount := len(resources)
+	uniqueResources := make([]map[string]any, 0, len(resources))
+	seen := map[string]bool{}
+	for _, resource := range resources {
+		resourceType := strings.TrimSpace(fmt.Sprint(resource["type"]))
+		if canonicalType, ok := canonicalMessageResourceType(resourceType); ok {
+			resourceType = canonicalType
+		}
+		resourceID := strings.TrimSpace(fmt.Sprint(resource["resourceId"]))
+		download, _ := resource["download"].(map[string]any)
+		arguments, _ := download["arguments"].(map[string]any)
+		messageID := strings.TrimSpace(fmt.Sprint(arguments["message-id"]))
+		if messageID == "<nil>" {
+			messageID = ""
+		}
+		key := strings.ToLower(resourceType) + "\x00" + resourceID
+		if strings.EqualFold(resourceType, "mediaId") {
+			conversationID := strings.TrimSpace(fmt.Sprint(arguments["open-conversation-id"]))
+			key += "\x00" + messageID + "\x00" + conversationID
+		}
+		if resourceID != "" && resourceID != "<nil>" {
+			if seen[key] {
+				continue
+			}
+			seen[key] = true
+		}
+		uniqueResources = append(uniqueResources, resource)
+	}
+	resources = uniqueResources
 	if rt.DryRun() {
 		return map[string]any{
-			"dryRun":         true,
-			"requestedCount": len(resources),
-			"resources":      resources,
-		}, nil
+			"dryRun":            true,
+			"discoveredCount":   discoveredCount,
+			"requestedCount":    len(resources),
+			"deduplicatedCount": discoveredCount - len(resources),
+			"resources":         resources,
+		}
+	}
+	if len(resources) == 0 {
+		return map[string]any{
+			"ok":                true,
+			"partial":           false,
+			"discoveredCount":   discoveredCount,
+			"requestedCount":    0,
+			"deduplicatedCount": discoveredCount,
+			"downloadedCount":   0,
+			"failedCount":       0,
+			"downloads":         []map[string]any{},
+			"failures":          []map[string]any{},
+		}
 	}

 	cwd, err := resourceGetwd()
 	if err != nil {
-		return nil, fmt.Errorf("读取工作目录失败: %w", err)
+		return map[string]any{
+			"ok":                false,
+			"partial":           false,
+			"discoveredCount":   discoveredCount,
+			"requestedCount":    len(resources),
+			"deduplicatedCount": discoveredCount - len(resources),
+			"downloadedCount":   0,
+			"failedCount":       len(resources),
+			"downloads":         []map[string]any{},
+			"failures": []map[string]any{{
+				"stage":         "output-directory",
+				"affectedCount": len(resources),
+				"error":         fmt.Sprintf("读取工作目录失败: %v", err),
+			}},
+		}
 	}
-	outputDir := strings.TrimRight(rt.Str("output-dir"), `/\`) + string(os.PathSeparator)
+	outputDir := strings.TrimRight(rt.Str("output-dir"), `/\`)
 	downloads := make([]map[string]any, 0, len(resources))
 	failures := make([]map[string]any, 0)
+	downloadedNames := map[string]bool{}
 	for _, resource := range resources {
+		resourceType := strings.TrimSpace(fmt.Sprint(resource["type"]))
+		if canonicalType, ok := canonicalMessageResourceType(resourceType); ok {
+			resourceType = canonicalType
+		}
 		resourceID := strings.TrimSpace(fmt.Sprint(resource["resourceId"]))
 		download, _ := resource["download"].(map[string]any)
 		arguments, _ := download["arguments"].(map[string]any)
 		messageID := strings.TrimSpace(fmt.Sprint(arguments["message-id"]))
 		conversationID := strings.TrimSpace(fmt.Sprint(arguments["open-conversation-id"]))
-		if download["ready"] != true || resourceID == "" || messageID == "" || conversationID == "" {
+		if messageID == "<nil>" {
+			messageID = ""
+		}
+		if conversationID == "" || conversationID == "<nil>" {
+			conversationID = strings.TrimSpace(fallbackConversationID)
+		}
+		missingMediaContext := resourceType == "mediaId" &&
+			(messageID == "" || messageID == "<nil>" ||
+				conversationID == "" || conversationID == "<nil>")
+		if resourceID == "" || resourceID == "<nil>" || missingMediaContext {
 			failures = append(failures, map[string]any{
-				"resourceId": resourceID,
-				"messageId":  messageID,
-				"error":      "资源引用缺少 message-id 或 open-conversation-id",
+				"resourceType": resourceType,
+				"resourceId":   resourceID,
+				"messageId":    messageID,
+				"error":        "资源引用缺少 resource-id，或 mediaId 缺少 message-id/open-conversation-id",
 			})
 			continue
 		}

-		data, callErr := rt.CallMCPData("im", "get_resource_download_url", map[string]any{
-			"resourceType":       "mediaId",
-			"resourceId":         resourceID,
-			"openMessageId":      messageID,
-			"openConversationId": conversationID,
-		})
+		data, callErr := resolveMessageResourceDownloadData(
+			rt, resourceType, resourceID, messageID, conversationID)
 		if callErr != nil {
 			failures = append(failures, map[string]any{
-				"resourceId": resourceID,
-				"messageId":  messageID,
-				"error":      callErr.Error(),
+				"resourceType": resourceType,
+				"resourceId":   resourceID,
+				"messageId":    messageID,
+				"error":        callErr.Error(),
 			})
 			continue
 		}
 		resourceURL, headers, infoErr := resourceDownloadInfo(data)
 		if infoErr != nil {
 			failures = append(failures, map[string]any{
-				"resourceId": resourceID,
-				"messageId":  messageID,
-				"error":      infoErr.Error(),
+				"resourceType": resourceType,
+				"resourceId":   resourceID,
+				"messageId":    messageID,
+				"error":        infoErr.Error(),
 			})
 			continue
 		}
+		preferredName := resourceDownloadPreferredName(data)
+		filename := resourceDownloadFilename(resourceURL, preferredName)
+		filename = disambiguateResourceDownloadFilename(filename, downloadedNames)
+		output := filepath.Join(outputDir, filename)
 		destPath, relativePath, pathErr := resolveResourceDownloadPath(
-			cwd, outputDir, resourceURL, rt.Bool("overwrite"))
+			cwd,
+			output,
+			resourceURL,
+			rt.Bool("overwrite"),
+			preferredName,
+		)
 		if pathErr != nil {
 			failures = append(failures, map[string]any{
-				"resourceId": resourceID,
-				"messageId":  messageID,
-				"error":      pathErr.Error(),
+				"resourceType": resourceType,
+				"resourceId":   resourceID,
+				"messageId":    messageID,
+				"error":        pathErr.Error(),
 			})
 			continue
 		}
@@ -669,28 +770,47 @@ func downloadMgetResources(rt *shortcut.RuntimeContext, messages []map[string]an
 			rt.Command().Context(), nil, resourceURL, headers, destPath, rt.Bool("overwrite"))
 		if downloadErr != nil {
 			failures = append(failures, map[string]any{
-				"resourceId": resourceID,
-				"messageId":  messageID,
-				"error":      downloadErr.Error(),
+				"resourceType": resourceType,
+				"resourceId":   resourceID,
+				"messageId":    messageID,
+				"error":        downloadErr.Error(),
 			})
 			continue
 		}
+		downloadedNames[strings.ToLower(filepath.Base(relativePath))] = true
 		downloads = append(downloads, map[string]any{
-			"resourceId": resourceID,
-			"messageId":  messageID,
-			"localPath":  filepath.ToSlash(relativePath),
-			"sizeBytes":  size,
+			"resourceType": resourceType,
+			"resourceId":   resourceID,
+			"messageId":    messageID,
+			"localPath":    filepath.ToSlash(relativePath),
+			"sizeBytes":    size,
 		})
 	}
 	return map[string]any{
-		"ok":              len(failures) == 0,
-		"partial":         len(downloads) > 0 && len(failures) > 0,
-		"requestedCount":  len(resources),
-		"downloadedCount": len(downloads),
-		"failedCount":     len(failures),
-		"downloads":       downloads,
-		"failures":        failures,
-	}, nil
+		"ok":                len(failures) == 0,
+		"partial":           len(downloads) > 0 && len(failures) > 0,
+		"discoveredCount":   discoveredCount,
+		"requestedCount":    len(resources),
+		"deduplicatedCount": discoveredCount - len(resources),
+		"downloadedCount":   len(downloads),
+		"failedCount":       len(failures),
+		"downloads":         downloads,
+		"failures":          failures,
+	}
+}
+
+func disambiguateResourceDownloadFilename(filename string, used map[string]bool) string {
+	if !used[strings.ToLower(filename)] {
+		return filename
+	}
+	extension := filepath.Ext(filename)
+	stem := strings.TrimSuffix(filename, extension)
+	for sequence := 2; ; sequence++ {
+		candidate := fmt.Sprintf("%s (%d)%s", stem, sequence, extension)
+		if !used[strings.ToLower(candidate)] {
+			return candidate
+		}
+	}
 }

 func uniqueShortcutStrings(values []string) []string {
@@ -888,41 +1008,170 @@ var MessagesCreateTextEmotion = shortcut.Shortcut{
 	},
 }

-// MessagesSendCard creates and pushes a streaming card (create_and_send_card, im).
+// MessagesSendCard creates and optionally completes a streaming card by
+// composing create_and_send_card with update_streaming_card.
 var MessagesSendCard = shortcut.Shortcut{
 	Service:     "chat",
 	Command:     "+messages-send-card",
 	Product:     "im",
-	Description: "创建并推送流式卡片（需配合 messages-update-card）",
-	Intent:      "当你要发送一张可后续流式更新的卡片消息（如 AI 逐字输出）时使用；会实际推送卡片并返回 bizId，群 openConversationId 或单聊接收者 userId 二选一，配合 messages-update-card 更新。",
+	Description: "创建流式卡片，可在同一次调用中写入内容并结束",
+	Intent:      "当你要发送一张流式卡片消息时使用；群 openConversationId、单聊 userId、单聊 openDingTalkId 严格三选一，分别使用 --group、--receiver、--receiver-open-dingtalk-id。--receiver 始终按 userId 通过通讯录关键词搜索做精确匹配，即使值以 D/d 开头也不会猜成 openDingTalkId；已有 openDingTalkId 时必须用显式参数直传。userId 包括在 --dry-run 时也会先解析。只传目标时创建卡片并返回 bizId，供后续 messages-update-card 流式更新；同时传 --content 时会自动串联创建和更新，默认以 flowStatus=3 完成，避免卡片停留在加载中。",
 	Risk:        shortcut.RiskWrite,
 	Flags: []shortcut.Flag{
-		{Name: "group", Type: shortcut.FlagString, Desc: "群 openConversationId（与 --receiver 互斥）"},
-		{Name: "receiver", Type: shortcut.FlagString, Desc: "单聊接收者 userId（与 --group 互斥）"},
+		{Name: "group", Type: shortcut.FlagString, Desc: "群 openConversationId（与两个单聊接收者参数互斥）"},
+		{Name: "receiver", Type: shortcut.FlagString, Desc: "单聊接收者 userId（与 --group/--receiver-open-dingtalk-id 互斥）；始终通过通讯录搜索精确匹配 openDingTalkId，包括 --dry-run 和 D/d 开头的 userId"},
+		{Name: "receiver-open-dingtalk-id", Type: shortcut.FlagString, Desc: "单聊接收者 openDingTalkId（与 --group/--receiver 互斥）；显式直传且不做通讯录解析"},
+		{Name: "content", Type: shortcut.FlagString, Desc: "创建后立即写入的卡片内容；省略时仅创建并返回 bizId"},
+		{Name: "flow-status", Type: shortcut.FlagInt, Default: "3", Desc: "自动更新状态：1处理中/2输入中/3完成/4执行中/5错误；--flow-status 必须在 1-5 之间，且显式指定时必须同时提供 --content"},
 	},
 	Constraints: []shortcut.Constraint{
-		{Kind: shortcut.ConstraintExactlyOne, Flags: []string{"group", "receiver"}},
+		{Kind: shortcut.ConstraintExactlyOne, Flags: []string{"group", "receiver", "receiver-open-dingtalk-id"}},
+		{
+			Kind:        shortcut.ConstraintCustom,
+			Flags:       []string{"flow-status"},
+			Description: "--flow-status 必须在 1-5 之间，且显式指定时必须同时提供 --content",
+		},
+	},
+	Tips: []string{
+		`dws chat +messages-send-card --group <openConversationId>`,
+		`dws chat +messages-send-card --group <openConversationId> --content "任务已完成"`,
+	},
+	Validate: func(rt *shortcut.RuntimeContext) error {
+		if status := rt.Int("flow-status"); status < 1 || status > 5 {
+			return fmt.Errorf("--flow-status 必须在 1-5 之间")
+		}
+		if rt.Changed("flow-status") && rt.Str("content") == "" {
+			return fmt.Errorf("--flow-status 只有与 --content 一起使用才有意义")
+		}
+		return nil
 	},
-	Tips: []string{`dws chat +messages-send-card --group <openConversationId>`},
 	Execute: func(rt *shortcut.RuntimeContext) error {
 		group := rt.Str("group")
 		receiver := rt.Str("receiver")
-		if group == "" && receiver == "" {
-			return fmt.Errorf("--group 或 --receiver 必填其一")
-		}
-		if group != "" && receiver != "" {
-			return fmt.Errorf("--group 与 --receiver 互斥")
-		}
+		receiverOpenID := rt.Str("receiver-open-dingtalk-id")
 		params := map[string]any{}
-		if group != "" {
+		switch {
+		case group != "":
 			params["openConversationId"] = group
-		} else {
-			params["receiverUid"] = receiver
+		case receiver != "":
+			openID, err := resolveUserOpenDingTalkID(rt, receiver)
+			if err != nil {
+				return err
+			}
+			params["receiverOpenDingTalkId"] = openID
+		default:
+			params["receiverOpenDingTalkId"] = receiverOpenID
 		}
-		return rt.CallMCP("create_and_send_card", params)
+		content := rt.Str("content")
+		if content == "" {
+			return rt.CallMCP("create_and_send_card", params)
+		}
+		status := rt.Int("flow-status")
+		if rt.DryRun() {
+			return rt.Output(map[string]any{
+				"dry_run":      true,
+				"executed":     false,
+				"preview_kind": "plan",
+				"actionCount":  2,
+				"failedCount":  0,
+				"actions": []map[string]any{
+					{
+						"tool":      "create_and_send_card",
+						"arguments": params,
+					},
+					{
+						"tool": "update_streaming_card",
+						"arguments": map[string]any{
+							"bizId":      "<from create_and_send_card>",
+							"msgContent": content,
+							"flowStatus": status,
+						},
+					},
+				},
+			})
+		}
+		created, err := rt.CallMCPWriteData("im", "create_and_send_card", params)
+		if err != nil {
+			return err
+		}
+		bizID := findCardBizID(created)
+		if bizID == "" {
+			return fmt.Errorf("卡片已创建但下层未返回 bizId，无法自动更新；请检查 create_and_send_card 响应")
+		}
+		updated, err := rt.CallMCPWriteData("im", "update_streaming_card", map[string]any{
+			"bizId":      bizID,
+			"msgContent": content,
+			"flowStatus": status,
+		})
+		if err != nil {
+			return fmt.Errorf("卡片已创建（bizId=%s），但自动更新失败: %w", bizID, err)
+		}
+		return rt.Output(map[string]any{
+			"ok":         true,
+			"bizId":      bizID,
+			"flowStatus": status,
+			"created":    created,
+			"updated":    updated,
+		})
 	},
 }

+func findCardBizID(value any) string {
+	switch typed := value.(type) {
+	case map[string]any:
+		directKeys := []string{"bizId", "bizID", "biz_id"}
+		for _, key := range directKeys {
+			if candidate, ok := typed[key].(string); ok && strings.TrimSpace(candidate) != "" {
+				candidate = strings.TrimSpace(candidate)
+				return candidate
+			}
+		}
+
+		// Prefer documented response envelopes before scanning extension fields.
+		// Map iteration order is deliberately randomized by Go, so an unordered
+		// recursive walk could select a stale metadata bizId.
+		envelopeKeys := []string{"result", "data", "card", "response"}
+		visited := make(map[string]struct{}, len(directKeys)+len(envelopeKeys))
+		for _, key := range directKeys {
+			visited[key] = struct{}{}
+		}
+		for _, key := range envelopeKeys {
+			visited[key] = struct{}{}
+			if candidate := findCardBizID(typed[key]); candidate != "" {
+				return candidate
+			}
+		}
+
+		remainingKeys := make([]string, 0, len(typed))
+		for key := range typed {
+			if _, ok := visited[key]; !ok {
+				remainingKeys = append(remainingKeys, key)
+			}
+		}
+		sort.Strings(remainingKeys)
+		for _, key := range remainingKeys {
+			if candidate := findCardBizID(typed[key]); candidate != "" {
+				return candidate
+			}
+		}
+	case []any:
+		for _, child := range typed {
+			if candidate := findCardBizID(child); candidate != "" {
+				return candidate
+			}
+		}
+	case string:
+		trimmed := strings.TrimSpace(typed)
+		if strings.HasPrefix(trimmed, "{") || strings.HasPrefix(trimmed, "[") {
+			var nested any
+			if json.Unmarshal([]byte(trimmed), &nested) == nil {
+				return findCardBizID(nested)
+			}
+		}
+	}
+	return ""
+}
+
 // MessagesUpdateCard streams updated card content (update_streaming_card, im).
 var MessagesUpdateCard = shortcut.Shortcut{
 	Service:     "chat",
@@ -4,10 +4,11 @@
 package chat

 import (
+	"bytes"
 	"context"
+	"encoding/json"
 	"errors"
 	"net/http"
-	"strings"
 	"testing"

 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/helpers"
@@ -25,7 +26,7 @@ func TestCrossPlatformCoverageListMessageRichProjection(t *testing.T) {
 			"content":            `{"mediaId":"@image"}`,
 			"quotedMessage": map[string]any{
 				"openMessageId": "quoted",
-				"content":       "quoted",
+				"content":       `{"mediaId":"@quoted-image"}`,
 			},
 		},
 	}}})
@@ -37,13 +38,23 @@ func TestCrossPlatformCoverageListMessageRichProjection(t *testing.T) {
 			t.Errorf("projection missing %s: %#v", key, rows[0])
 		}
 	}
+	resources := rows[0]["resourceRefs"].([]map[string]any)
+	if len(resources) != 2 {
+		t.Fatalf("projected resources = %#v", resources)
+	}
+	quotedArgs := resources[1]["download"].(map[string]any)["arguments"].(map[string]any)
+	if resources[1]["resourceId"] != "@quoted-image" ||
+		quotedArgs["message-id"] != "quoted" ||
+		quotedArgs["open-conversation-id"] != "cid" {
+		t.Fatalf("quoted resource context = %#v", resources[1])
+	}
 }

 func TestCrossPlatformCoverageMgetResourceDownloadOutcomes(t *testing.T) {
-	baseArgs := []string{"chat", "+messages-mget", "--msg-ids", "msg", "--download-resources"}
+	baseArgs := []string{"chat", "+messages-mget", "--msg-ids", "msg", "--download-resources", "--yes"}
 	readyMget := `{"result":[{"openMessageId":"msg","openConversationId":"cid","content":"{\"mediaId\":\"@file\"}"}]}`
 	missingContextMget := `{"result":[{"content":"{\"mediaId\":\"@file\"}"}]}`
-	validInfo := `{"result":{"resourceUrl":"https://example.test/resource.bin"}}`
+	validInfo := `{"result":{"resourceUrl":"https://download.dingtalk.com/resource.bin"}}`

 	t.Run("dry run", func(t *testing.T) {
 		helpers.InitDeps(&larkAlignmentCaller{responses: map[string]string{
@@ -62,9 +73,53 @@ func TestCrossPlatformCoverageMgetResourceDownloadOutcomes(t *testing.T) {
 			"im/list_messages_by_ids": readyMget,
 		}})
 		root := newPlatformCoverageRoot()
+		var output bytes.Buffer
+		root.SetOut(&output)
 		root.SetArgs(baseArgs)
-		if err := root.Execute(); err == nil || !strings.Contains(err.Error(), "工作目录") {
-			t.Fatalf("getwd error = %v", err)
+		if err := root.Execute(); err != nil {
+			t.Fatalf("getwd ledger error = %v", err)
+		}
+		var payload map[string]any
+		if err := json.Unmarshal(output.Bytes(), &payload); err != nil {
+			t.Fatal(err)
+		}
+		ledger, _ := payload["resourceDownloads"].(map[string]any)
+		if ledger["requestedCount"] != float64(1) ||
+			ledger["failedCount"] != ledger["requestedCount"] {
+			t.Fatalf("getwd ledger = %#v", ledger)
+		}
+	})
+	t.Run("zero resources skip getwd", func(t *testing.T) {
+		resetResourceDownloadHooks(t)
+		getwdCalled := false
+		resourceGetwd = func() (string, error) {
+			getwdCalled = true
+			return "", errors.New("getwd")
+		}
+		helpers.InitDeps(&larkAlignmentCaller{responses: map[string]string{
+			"im/list_messages_by_ids": `{"result":[{"openMessageId":"msg","openConversationId":"cid","content":"plain text"}]}`,
+		}})
+		root := newPlatformCoverageRoot()
+		var output bytes.Buffer
+		root.SetOut(&output)
+		root.SetArgs(baseArgs)
+		if err := root.Execute(); err != nil {
+			t.Fatalf("zero-resource download error = %v", err)
+		}
+		if getwdCalled {
+			t.Fatal("zero-resource download unnecessarily read the working directory")
+		}
+		var payload map[string]any
+		if err := json.Unmarshal(output.Bytes(), &payload); err != nil {
+			t.Fatal(err)
+		}
+		ledger, _ := payload["resourceDownloads"].(map[string]any)
+		failures, _ := ledger["failures"].([]any)
+		if ledger["ok"] != true ||
+			ledger["requestedCount"] != float64(0) ||
+			ledger["failedCount"] != float64(0) ||
+			len(failures) != 0 {
+			t.Fatalf("zero-resource ledger = %#v", ledger)
 		}
 	})

@@ -120,3 +175,48 @@ func TestCrossPlatformCoverageMgetResourceDownloadOutcomes(t *testing.T) {
 		})
 	}
 }
+
+func TestCrossPlatformCoverageMgetDownloadRunsWithoutConfirmation(t *testing.T) {
+	resetResourceDownloadHooks(t)
+	t.Chdir(t.TempDir())
+	resourceDownload = func(
+		_ context.Context,
+		_ *http.Client,
+		_ string,
+		_ map[string]string,
+		dest string,
+		_ bool,
+	) (int64, error) {
+		return 7, nil
+	}
+	fake := &larkAlignmentCaller{responses: map[string]string{
+		"im/list_messages_by_ids":      `{"result":[{"openMessageId":"msg","openConversationId":"cid","content":"{\"mediaId\":\"@file\"}"}]}`,
+		"im/get_resource_download_url": `{"result":{"resourceUrl":"https://download.dingtalk.com/resource.bin"}}`,
+	}}
+	helpers.InitDeps(fake)
+	root := newPlatformCoverageRoot()
+	var output bytes.Buffer
+	root.SetOut(&output)
+	root.SetIn(bytes.NewBuffer(nil))
+	root.SetArgs([]string{
+		"chat", "+messages-mget",
+		"--msg-ids", "msg",
+		"--download-resources",
+	})
+	if err := root.Execute(); err != nil {
+		t.Fatal(err)
+	}
+	if len(fake.calls) != 2 ||
+		fake.calls[0].tool != "list_messages_by_ids" ||
+		fake.calls[1].tool != "get_resource_download_url" {
+		t.Fatalf("download calls = %#v", fake.calls)
+	}
+	var payload map[string]any
+	if err := json.Unmarshal(output.Bytes(), &payload); err != nil {
+		t.Fatal(err)
+	}
+	ledger, _ := payload["resourceDownloads"].(map[string]any)
+	if ledger["downloadedCount"] != float64(1) || ledger["failedCount"] != float64(0) {
+		t.Fatalf("download ledger = %#v", ledger)
+	}
+}
@@ -120,17 +120,17 @@ func TestCrossPlatformCoverageChatCreateAndReplyFailures(t *testing.T) {
 		},
 		{
 			name:      "explicit sender lookup",
-			caller:    &larkAlignmentCaller{failProductTool: "contact/get_user_info_by_user_ids"},
+			caller:    &larkAlignmentCaller{failProductTool: "contact/search_contact_by_key_word"},
 			args:      []string{"chat", "+messages-reply", "--conversation-id", "cid", "--message-id", "msg", "--ref-sender", "user-id", "--text", "收到", "--yes"},
 			wantError: "解析为 openDingTalkId",
 		},
 		{
 			name: "explicit sender unresolved",
 			caller: &larkAlignmentCaller{responses: map[string]string{
-				"contact/get_user_info_by_user_ids": `{"result":[]}`,
+				"contact/search_contact_by_key_word": `{"result":[]}`,
 			}},
 			args:      []string{"chat", "+messages-reply", "--conversation-id", "cid", "--message-id", "msg", "--ref-sender", "user-id", "--text", "收到", "--yes"},
-			wantError: "无法把 --ref-sender",
+			wantError: "没有精确匹配",
 		},
 		{
 			name:      "referenced message lookup",
@@ -234,7 +234,7 @@ func TestCrossPlatformCoverageFlagAndMgetValidation(t *testing.T) {
 	fake := &larkAlignmentCaller{failProductTool: "im/list_messages_by_ids"}
 	helpers.InitDeps(fake)
 	root := newPlatformCoverageRoot()
-	root.SetArgs([]string{"chat", "+messages-mget", "--msg-ids", "msg"})
+	root.SetArgs([]string{"chat", "+messages-mget", "--msg-ids", "msg", "--yes"})
 	if err := root.Execute(); err == nil {
 		t.Fatal("mget lower error was swallowed")
 	}
@@ -0,0 +1,887 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+
+package chat
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"reflect"
+	"strings"
+	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/helpers"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut"
+)
+
+func TestMessagesSendPublishesCompleteIdentityConstraintInputs(t *testing.T) {
+	want := []string{
+		"identity", "as", "group", "chat-id", "user", "open-dingtalk-id",
+		"users", "open-dingtalk-ids", "robot-code", "webhook-token",
+		"uuid", "idempotency-key",
+	}
+	var got []string
+	for _, constraint := range MessagesSend.Constraints {
+		if constraint.Kind == shortcut.ConstraintCustom {
+			got = constraint.Flags
+			break
+		}
+	}
+	if !reflect.DeepEqual(got, want) {
+		t.Fatalf("identity constraint flags = %#v, want %#v", got, want)
+	}
+	wantSet := make(map[string]bool, len(want))
+	for _, name := range want {
+		wantSet[name] = true
+	}
+	for _, flag := range MessagesSend.Flags {
+		if !wantSet[flag.Name] {
+			continue
+		}
+		if !strings.Contains(flag.Desc, "能力矩阵") {
+			t.Errorf("--%s does not publish identity matrix semantics: %q", flag.Name, flag.Desc)
+		}
+		if flag.Name == "user" && !strings.Contains(flag.Desc, "--dry-run") {
+			t.Errorf("--user does not publish dry-run contact resolution: %q", flag.Desc)
+		}
+	}
+}
+
+func TestCrossPlatformCoverageSafeResourceDownloadsStayReadOnly(t *testing.T) {
+	for _, command := range []shortcut.Shortcut{MessagesMget, MessagesResourceDownload} {
+		if command.Risk != shortcut.RiskRead {
+			t.Errorf("%s risk contract = %q", command.Command, command.Risk)
+		}
+	}
+}
+
+func TestCrossPlatformCoverageMessagesSendCurrentUserImageAndUserResolution(t *testing.T) {
+	fake := &larkAlignmentCaller{}
+	helpers.InitDeps(fake)
+	root := newPlatformCoverageRoot()
+	root.SetArgs([]string{
+		"chat", "+messages-send",
+		"--user", "user-id",
+		"--msg-type", "image",
+		"--media-id", "@image",
+		"--idempotency-key", "image-key",
+		"--yes",
+	})
+	if err := root.Execute(); err != nil {
+		t.Fatal(err)
+	}
+	if len(fake.calls) != 2 {
+		t.Fatalf("calls = %#v, want contact resolution + send", fake.calls)
+	}
+	if fake.calls[0].product != "contact" || fake.calls[0].tool != "search_contact_by_key_word" {
+		t.Fatalf("resolution call = %#v", fake.calls[0])
+	}
+	if got := fake.calls[0].args["keyword"]; got != "user-id" {
+		t.Fatalf("resolution keyword = %#v, want user-id", got)
+	}
+	send := fake.calls[1]
+	if send.product != "chat" || send.tool != "send_personal_message" {
+		t.Fatalf("send call = %#v", send)
+	}
+	for key, want := range map[string]any{
+		"receiverOpenDingTalkId": "D-resolved",
+		"msgType":                "image",
+		"uuid":                   "image-key",
+	} {
+		if !reflect.DeepEqual(send.args[key], want) {
+			t.Errorf("%s = %#v, want %#v", key, send.args[key], want)
+		}
+	}
+	var content map[string]string
+	if err := json.Unmarshal([]byte(send.args["content"].(string)), &content); err != nil {
+		t.Fatal(err)
+	}
+	if content["mediaId"] != "@image" {
+		t.Fatalf("image content = %#v", content)
+	}
+}
+
+func TestCrossPlatformCoverageMessagesSendCurrentUserLocalFileFlow(t *testing.T) {
+	t.Chdir(t.TempDir())
+	if err := os.WriteFile("report.txt", []byte("gap-fill"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	var uploaded []byte
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Method != http.MethodPut {
+			t.Errorf("upload method = %s", r.Method)
+		}
+		var err error
+		uploaded, err = io.ReadAll(r.Body)
+		if err != nil {
+			t.Error(err)
+		}
+		w.WriteHeader(http.StatusOK)
+	}))
+	t.Cleanup(server.Close)
+
+	fake := &larkAlignmentCaller{responses: map[string]string{
+		"im/init_conversation_file_upload":   `{"resourceUrl":"` + server.URL + `","uploadKey":"upload-key"}`,
+		"im/commit_conversation_file_upload": `{"result":{"dentryId":11,"spaceId":22}}`,
+		"chat/send_personal_message":         `{"result":{"openMessageId":"sent-file"}}`,
+	}}
+	helpers.InitDeps(fake)
+	root := newPlatformCoverageRoot()
+	var output bytes.Buffer
+	root.SetOut(&output)
+	root.SetArgs([]string{
+		"chat", "+messages-send",
+		"--group", "cid",
+		"--msg-type", "audio",
+		"--file-path", "./report.txt",
+		"--uuid", "file-key",
+		"--yes",
+	})
+	if err := root.Execute(); err != nil {
+		t.Fatal(err)
+	}
+	if string(uploaded) != "gap-fill" || len(fake.calls) != 3 {
+		t.Fatalf("uploaded = %q, calls = %#v", uploaded, fake.calls)
+	}
+	if fake.calls[0].tool != "init_conversation_file_upload" ||
+		fake.calls[1].tool != "commit_conversation_file_upload" ||
+		fake.calls[2].tool != "send_personal_message" {
+		t.Fatalf("file flow calls = %#v", fake.calls)
+	}
+	send := fake.calls[2]
+	if send.args["msgType"] != "file" || send.args["openConversationId"] != "cid" ||
+		send.args["uuid"] != "file-key" {
+		t.Fatalf("file send args = %#v", send.args)
+	}
+	var content map[string]any
+	if err := json.Unmarshal([]byte(send.args["content"].(string)), &content); err != nil {
+		t.Fatal(err)
+	}
+	if content["dentryId"] != float64(11) || content["spaceId"] != float64(22) ||
+		content["fileName"] != "report.txt" {
+		t.Fatalf("file content = %#v", content)
+	}
+	var payload map[string]any
+	if err := json.Unmarshal(output.Bytes(), &payload); err != nil {
+		t.Fatal(err)
+	}
+	if payload["requestedMessageType"] != "audio" || payload["effectiveMessageType"] != "file" {
+		t.Fatalf("file output = %#v", payload)
+	}
+}
+
+func TestCrossPlatformCoverageMessagesSendCurrentUserLocalFileDryRunAndFailures(t *testing.T) {
+	t.Chdir(t.TempDir())
+	if err := os.WriteFile("fixture.bin", []byte("x"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	uploadServer := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.WriteHeader(http.StatusOK)
+	}))
+	t.Cleanup(uploadServer.Close)
+	fake := &larkAlignmentCaller{}
+	helpers.InitDeps(fake)
+	root := newPlatformCoverageRoot()
+	var output bytes.Buffer
+	root.SetOut(&output)
+	root.SetArgs([]string{
+		"chat", "+messages-send",
+		"--open-dingtalk-id", "D-target",
+		"--file", "./fixture.bin",
+		"--dry-run",
+		"--yes",
+	})
+	if err := root.Execute(); err != nil {
+		t.Fatal(err)
+	}
+	if len(fake.calls) != 0 {
+		t.Fatalf("file dry-run made lower calls: %#v", fake.calls)
+	}
+	var payload map[string]any
+	if err := json.Unmarshal(output.Bytes(), &payload); err != nil {
+		t.Fatal(err)
+	}
+	if payload["actionCount"] != float64(2) || payload["preview_kind"] != "plan" {
+		t.Fatalf("dry-run payload = %#v", payload)
+	}
+
+	for _, tc := range []struct {
+		name string
+		args []string
+	}{
+		{"unsafe path", []string{"--group", "cid", "--file", "../outside"}},
+		{"missing file", []string{"--group", "cid", "--file", "./missing"}},
+		{"media mismatch", []string{"--group", "cid", "--media-id", "@image", "--msg-type", "file"}},
+		{"file mismatch", []string{"--group", "cid", "--file", "./fixture.bin", "--msg-type", "image"}},
+		{"missing media", []string{"--group", "cid", "--text", "x", "--msg-type", "image"}},
+		{"bot media", []string{"--identity", "bot", "--robot-code", "robot", "--group", "cid", "--media-id", "@image"}},
+		{"webhook media", []string{"--identity", "webhook", "--webhook-token", "token", "--media-id", "@image"}},
+		{"user target conflict", []string{"--group", "cid", "--user", "u1", "--text", "x"}},
+		{"user media at", []string{"--group", "cid", "--media-id", "@image", "--at-all"}},
+		{"text flag with markdown type", []string{"--group", "cid", "--text", "x", "--msg-type", "markdown"}},
+		{"markdown flag with text type", []string{"--group", "cid", "--markdown", "x", "--msg-type", "text"}},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			helpers.InitDeps(&larkAlignmentCaller{})
+			command := newPlatformCoverageRoot()
+			args := append([]string{"chat", "+messages-send"}, tc.args...)
+			args = append(args, "--yes")
+			command.SetArgs(args)
+			if err := command.Execute(); err == nil {
+				t.Fatalf("invalid args succeeded: %v", tc.args)
+			}
+		})
+	}
+
+	for _, tc := range []struct {
+		name string
+		fake *larkAlignmentCaller
+	}{
+		{
+			name: "upload init error",
+			fake: &larkAlignmentCaller{failProductTool: "im/init_conversation_file_upload"},
+		},
+		{
+			name: "commit response missing IDs",
+			fake: &larkAlignmentCaller{responses: map[string]string{
+				"im/init_conversation_file_upload":   `{"resourceUrl":"` + uploadServer.URL + `","uploadKey":"key"}`,
+				"im/commit_conversation_file_upload": `{}`,
+			}},
+		},
+		{
+			name: "message send error",
+			fake: &larkAlignmentCaller{
+				failProductTool: "chat/send_personal_message",
+				responses: map[string]string{
+					"im/init_conversation_file_upload":   `{"resourceUrl":"` + uploadServer.URL + `","uploadKey":"key"}`,
+					"im/commit_conversation_file_upload": `{"dentryId":1,"spaceId":2}`,
+				},
+			},
+		},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			helpers.InitDeps(tc.fake)
+			command := newPlatformCoverageRoot()
+			command.SetArgs([]string{
+				"chat", "+messages-send",
+				"--group", "cid",
+				"--file", "./fixture.bin",
+				"--yes",
+			})
+			if err := command.Execute(); err == nil {
+				t.Fatal("file failure scenario unexpectedly succeeded")
+			}
+		})
+	}
+}
+
+func TestCrossPlatformCoverageMessagesSendUserResolutionFailures(t *testing.T) {
+	for _, tc := range []struct {
+		name string
+		fake *larkAlignmentCaller
+	}{
+		{"lookup error", &larkAlignmentCaller{failProductTool: "contact/search_contact_by_key_word"}},
+		{"no exact user id", &larkAlignmentCaller{responses: map[string]string{
+			"contact/search_contact_by_key_word": `{"result":[{"userId":"other-user","openDingTalkId":"D-other"}]}`,
+		}}},
+		{"missing open id", &larkAlignmentCaller{responses: map[string]string{
+			"contact/search_contact_by_key_word": `{"result":[{"userId":"user-id","name":"Resolved User"}]}`,
+		}}},
+		{"ambiguous open id", &larkAlignmentCaller{responses: map[string]string{
+			"contact/search_contact_by_key_word": `{"result":[{"userId":"user-id","openDingTalkId":"D-one"},{"userId":"user-id","openDingTalkId":"D-two"}]}`,
+		}}},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			helpers.InitDeps(tc.fake)
+			root := newPlatformCoverageRoot()
+			root.SetArgs([]string{
+				"chat", "+messages-send",
+				"--user", "user-id",
+				"--text", "hello",
+				"--yes",
+			})
+			if err := root.Execute(); err == nil {
+				t.Fatal("unresolved user was accepted")
+			}
+			if len(tc.fake.calls) != 1 {
+				t.Fatalf("calls = %#v", tc.fake.calls)
+			}
+		})
+	}
+}
+
+func TestCrossPlatformCoverageMessagesSendTextModesAndExecuteGuard(t *testing.T) {
+	for _, args := range [][]string{
+		{"--group", "cid", "--markdown", "## markdown"},
+		{"--group", "cid", "--text", "plain", "--msg-type", "text"},
+	} {
+		fake := &larkAlignmentCaller{}
+		helpers.InitDeps(fake)
+		root := newPlatformCoverageRoot()
+		root.SetArgs(append(append([]string{"chat", "+messages-send"}, args...), "--yes"))
+		if err := root.Execute(); err != nil {
+			t.Fatal(err)
+		}
+		if len(fake.calls) != 1 || fake.calls[0].tool != "send_personal_message" {
+			t.Fatalf("text mode calls = %#v", fake.calls)
+		}
+	}
+
+	shortcut.Register(shortcut.Shortcut{
+		Service: "chat",
+		Command: "+gap-send-execute-guard",
+		Flags:   MessagesSend.Flags,
+		Execute: executeMessagesSend,
+	})
+	helpers.InitDeps(&larkAlignmentCaller{})
+	root := newPlatformCoverageRoot()
+	root.SetArgs([]string{
+		"chat", "+gap-send-execute-guard",
+		"--group", "cid",
+		"--media-id", "@image",
+		"--msg-type", "file",
+	})
+	if err := root.Execute(); err == nil {
+		t.Fatal("execute-time content mismatch was accepted")
+	}
+}
+
+func TestCrossPlatformCoverageMessagesSendCardOneCallLifecycle(t *testing.T) {
+	fake := &larkAlignmentCaller{responses: map[string]string{
+		"im/create_and_send_card":  `{"result":{"card":{"biz_id":"biz-1"}}}`,
+		"im/update_streaming_card": `{"result":{"updated":true}}`,
+	}}
+	helpers.InitDeps(fake)
+	root := newPlatformCoverageRoot()
+	var output bytes.Buffer
+	root.SetOut(&output)
+	root.SetArgs([]string{
+		"chat", "+messages-send-card",
+		"--group", "cid",
+		"--content", "完成",
+		"--flow-status", "3",
+		"--yes",
+	})
+	if err := root.Execute(); err != nil {
+		t.Fatal(err)
+	}
+	if len(fake.calls) != 2 || fake.calls[0].tool != "create_and_send_card" ||
+		fake.calls[1].tool != "update_streaming_card" {
+		t.Fatalf("card calls = %#v", fake.calls)
+	}
+	if fake.calls[1].args["bizId"] != "biz-1" || fake.calls[1].args["msgContent"] != "完成" ||
+		fake.calls[1].args["flowStatus"] != 3 {
+		t.Fatalf("card update args = %#v", fake.calls[1].args)
+	}
+	var payload map[string]any
+	if err := json.Unmarshal(output.Bytes(), &payload); err != nil {
+		t.Fatal(err)
+	}
+	if payload["bizId"] != "biz-1" || payload["ok"] != true {
+		t.Fatalf("card output = %#v", payload)
+	}
+}
+
+func TestCrossPlatformCoverageMessagesSendCardResolvesReceiverForLowerTool(t *testing.T) {
+	fake := &larkAlignmentCaller{}
+	helpers.InitDeps(fake)
+	root := newPlatformCoverageRoot()
+	root.SetArgs([]string{
+		"chat", "+messages-send-card",
+		"--receiver", "d-user-id",
+		"--yes",
+	})
+	if err := root.Execute(); err != nil {
+		t.Fatal(err)
+	}
+	if len(fake.calls) != 2 ||
+		fake.calls[0].product != "contact" ||
+		fake.calls[0].tool != "search_contact_by_key_word" ||
+		fake.calls[1].product != "im" ||
+		fake.calls[1].tool != "create_and_send_card" {
+		t.Fatalf("card receiver calls = %#v", fake.calls)
+	}
+	if got := fake.calls[1].args["receiverOpenDingTalkId"]; got != "D-resolved" {
+		t.Fatalf("receiverOpenDingTalkId = %#v, want D-resolved", got)
+	}
+	if got := fake.calls[0].args["keyword"]; got != "d-user-id" {
+		t.Fatalf("D/d-prefixed userId resolution args = %#v", fake.calls[0].args)
+	}
+	if _, exists := fake.calls[1].args["receiverUid"]; exists {
+		t.Fatalf("obsolete receiverUid leaked to lower tool: %#v", fake.calls[1].args)
+	}
+}
+
+func TestCrossPlatformCoverageMessagesSendCardUsesExplicitOpenReceiver(t *testing.T) {
+	fake := &larkAlignmentCaller{}
+	helpers.InitDeps(fake)
+	root := newPlatformCoverageRoot()
+	root.SetArgs([]string{
+		"chat", "+messages-send-card",
+		"--receiver-open-dingtalk-id", "D-direct",
+		"--yes",
+	})
+	if err := root.Execute(); err != nil {
+		t.Fatal(err)
+	}
+	if len(fake.calls) != 1 ||
+		fake.calls[0].product != "im" ||
+		fake.calls[0].tool != "create_and_send_card" {
+		t.Fatalf("card open receiver calls = %#v", fake.calls)
+	}
+	if got := fake.calls[0].args["receiverOpenDingTalkId"]; got != "D-direct" {
+		t.Fatalf("receiverOpenDingTalkId = %#v, want D-direct", got)
+	}
+}
+
+func TestCrossPlatformCoverageMessagesSendCardDryRunAndFailureBoundaries(t *testing.T) {
+	t.Run("create only", func(t *testing.T) {
+		fake := &larkAlignmentCaller{}
+		helpers.InitDeps(fake)
+		root := newPlatformCoverageRoot()
+		root.SetArgs([]string{
+			"chat", "+messages-send-card",
+			"--group", "cid",
+			"--yes",
+		})
+		if err := root.Execute(); err != nil {
+			t.Fatal(err)
+		}
+		if len(fake.calls) != 1 || fake.calls[0].tool != "create_and_send_card" {
+			t.Fatalf("create-only calls = %#v", fake.calls)
+		}
+	})
+
+	t.Run("dry run", func(t *testing.T) {
+		fake := &larkAlignmentCaller{}
+		helpers.InitDeps(fake)
+		root := newPlatformCoverageRoot()
+		var output bytes.Buffer
+		root.SetOut(&output)
+		root.SetArgs([]string{
+			"chat", "+messages-send-card",
+			"--receiver", "user",
+			"--content", "处理中",
+			"--flow-status", "1",
+			"--dry-run",
+			"--yes",
+		})
+		if err := root.Execute(); err != nil {
+			t.Fatal(err)
+		}
+		if len(fake.calls) != 1 ||
+			fake.calls[0].product != "contact" ||
+			fake.calls[0].tool != "search_contact_by_key_word" {
+			t.Fatalf("card dry-run receiver resolution calls = %#v", fake.calls)
+		}
+		var payload map[string]any
+		if err := json.Unmarshal(output.Bytes(), &payload); err != nil {
+			t.Fatal(err)
+		}
+		actions, _ := payload["actions"].([]any)
+		create, _ := actions[0].(map[string]any)
+		arguments, _ := create["arguments"].(map[string]any)
+		if payload["actionCount"] != float64(2) ||
+			arguments["receiverOpenDingTalkId"] != "D-resolved" {
+			t.Fatalf("card plan = %#v", payload)
+		}
+	})
+
+	t.Run("receiver resolution error", func(t *testing.T) {
+		fake := &larkAlignmentCaller{failProductTool: "contact/search_contact_by_key_word"}
+		helpers.InitDeps(fake)
+		root := newPlatformCoverageRoot()
+		root.SetArgs([]string{
+			"chat", "+messages-send-card",
+			"--receiver", "user-id",
+			"--yes",
+		})
+		err := root.Execute()
+		if err == nil || !strings.Contains(err.Error(), "解析为 openDingTalkId 失败") {
+			t.Fatalf("receiver resolution error = %v", err)
+		}
+		if len(fake.calls) != 1 || fake.calls[0].tool != "search_contact_by_key_word" {
+			t.Fatalf("receiver resolution calls = %#v", fake.calls)
+		}
+	})
+
+	for _, tc := range []struct {
+		name      string
+		fake      *larkAlignmentCaller
+		wantError string
+	}{
+		{
+			name:      "create error",
+			fake:      &larkAlignmentCaller{failProductTool: "im/create_and_send_card"},
+			wantError: "fixture lower call failed",
+		},
+		{
+			name: "missing biz id",
+			fake: &larkAlignmentCaller{responses: map[string]string{
+				"im/create_and_send_card": `{"result":{"created":true}}`,
+			}},
+			wantError: "未返回 bizId",
+		},
+		{
+			name: "update error preserves id",
+			fake: &larkAlignmentCaller{
+				failProductTool: "im/update_streaming_card",
+				responses: map[string]string{
+					"im/create_and_send_card": `{"bizId":"biz-preserved"}`,
+				},
+			},
+			wantError: "biz-preserved",
+		},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			helpers.InitDeps(tc.fake)
+			root := newPlatformCoverageRoot()
+			root.SetArgs([]string{
+				"chat", "+messages-send-card",
+				"--group", "cid",
+				"--content", "完成",
+				"--yes",
+			})
+			err := root.Execute()
+			if err == nil || !strings.Contains(err.Error(), tc.wantError) {
+				t.Fatalf("error = %v, want substring %q", err, tc.wantError)
+			}
+		})
+	}
+
+	for _, args := range [][]string{
+		{"--group", "cid", "--content", "x", "--flow-status", "6"},
+		{"--group", "cid", "--flow-status", "2"},
+		{"--group", "cid", "--receiver-open-dingtalk-id", "D-direct"},
+		{"--receiver", "user-id", "--receiver-open-dingtalk-id", "D-direct"},
+	} {
+		helpers.InitDeps(&larkAlignmentCaller{})
+		root := newPlatformCoverageRoot()
+		root.SetArgs(append([]string{"chat", "+messages-send-card"}, args...))
+		if err := root.Execute(); err == nil {
+			t.Fatalf("invalid card args succeeded: %v", args)
+		}
+	}
+}
+
+func TestCrossPlatformCoverageFindCardBizIDResponseShapes(t *testing.T) {
+	for _, tc := range []struct {
+		value any
+		want  string
+	}{
+		{map[string]any{"bizId": "direct"}, "direct"},
+		{map[string]any{"bizID": "caps"}, "caps"},
+		{map[string]any{"biz_id": "snake"}, "snake"},
+		{map[string]any{"result": []any{map[string]any{"bizId": "nested"}}}, "nested"},
+		{map[string]any{
+			"metadata": map[string]any{"bizId": "stale"},
+			"result":   map[string]any{"bizId": "current"},
+		}, "current"},
+		{map[string]any{
+			"extension": map[string]any{"bizId": "fallback"},
+		}, "fallback"},
+		{map[string]any{
+			"bizId":  map[string]any{"x": 1},
+			"result": map[string]any{"bizId": "typed"},
+		}, "typed"},
+		{map[string]any{"bizId": map[string]any{"x": 1}}, ""},
+		{`{"result":{"bizId":"json"}}`, "json"},
+		{`[{"bizId":"array-json"}]`, "array-json"},
+		{`{"bizId":`, ""},
+		{"plain", ""},
+		{42, ""},
+	} {
+		if got := findCardBizID(tc.value); got != tc.want {
+			t.Errorf("findCardBizID(%#v) = %q, want %q", tc.value, got, tc.want)
+		}
+	}
+}
+
+func TestCrossPlatformCoverageMessageResourceDownloadKeepsNestedMessageContext(t *testing.T) {
+	resetResourceDownloadHooks(t)
+	t.Chdir(t.TempDir())
+	resourceDownload = func(
+		_ context.Context,
+		_ *http.Client,
+		_ string,
+		_ map[string]string,
+		dest string,
+		_ bool,
+	) (int64, error) {
+		if err := os.MkdirAll(filepath.Dir(dest), 0o755); err != nil {
+			return 0, err
+		}
+		return 7, nil
+	}
+	fake := &larkAlignmentCaller{responses: map[string]string{
+		"im/get_resource_download_url": `{"result":{"resourceUrl":"https://download.dingtalk.com/resource.bin"}}`,
+	}}
+	helpers.InitDeps(fake)
+	message := map[string]any{
+		"openMessageId": "msg",
+		"content":       `{"mediaId":"@same","nested":{"mediaId":"@same"}}`,
+		"quotedMessage": map[string]any{
+			"openMessageId": "msg-quoted",
+			"content":       `{"mediaId":"@quoted"}`,
+		},
+	}
+	secondMessage := map[string]any{
+		"openMessageId": "msg-2",
+		"content":       `{"mediaId":"@same"}`,
+	}
+	var ledger map[string]any
+	shortcut.Register(shortcut.Shortcut{
+		Service: "chat",
+		Command: "+gap-resource-download",
+		Flags:   MessageResourceDownloadFlags(),
+		Execute: func(rt *shortcut.RuntimeContext) error {
+			ledger = DownloadMessageResources(rt, []map[string]any{message, message, secondMessage}, "cid-fallback")
+			return nil
+		},
+	})
+	root := newPlatformCoverageRoot()
+	root.SetArgs([]string{"chat", "+gap-resource-download", "--output-dir", "./downloads"})
+	if err := root.Execute(); err != nil {
+		t.Fatal(err)
+	}
+	if ledger["discoveredCount"] != 5 || ledger["requestedCount"] != 3 ||
+		ledger["deduplicatedCount"] != 2 || ledger["downloadedCount"] != 3 {
+		t.Fatalf("download ledger = %#v", ledger)
+	}
+	if len(fake.calls) != 3 {
+		t.Fatalf("resource lookup = %#v", fake.calls)
+	}
+	gotMessageIDs := map[string]bool{}
+	for _, call := range fake.calls {
+		if call.args["openConversationId"] != "cid-fallback" {
+			t.Errorf("resource conversation = %#v", call.args)
+		}
+		gotMessageIDs[call.args["openMessageId"].(string)] = true
+	}
+	for _, messageID := range []string{"msg", "msg-quoted", "msg-2"} {
+		if !gotMessageIDs[messageID] {
+			t.Errorf("missing resource lookup for %q: %#v", messageID, fake.calls)
+		}
+	}
+}
+
+func TestCrossPlatformCoverageMessageFileResourceDownloadUsesDriveAndPreservesName(t *testing.T) {
+	resetResourceDownloadHooks(t)
+	t.Chdir(t.TempDir())
+	resourceDownload = func(
+		_ context.Context,
+		_ *http.Client,
+		_ string,
+		_ map[string]string,
+		dest string,
+		_ bool,
+	) (int64, error) {
+		if err := os.WriteFile(dest, []byte("drive-file"), 0o600); err != nil {
+			return 0, err
+		}
+		return int64(len("drive-file")), nil
+	}
+	fake := &larkAlignmentCaller{responses: map[string]string{
+		"drive/download_file": `{"result":{"downloadUrl":"https://download.dingtalk.com/opaque","fileName":"fixture.txt"}}`,
+	}}
+	helpers.InitDeps(fake)
+
+	root := newPlatformCoverageRoot()
+	root.SetArgs([]string{
+		"chat", "+messages-resource-download",
+		"--type", "fileId",
+		"--resource-id", "drive-file",
+		"--output", "./downloads/",
+		"--yes",
+	})
+	if err := root.Execute(); err != nil {
+		t.Fatal(err)
+	}
+	content, err := os.ReadFile(filepath.Join("downloads", "fixture.txt"))
+	if err != nil || string(content) != "drive-file" {
+		t.Fatalf("downloaded content = %q, err = %v", content, err)
+	}
+	if len(fake.calls) != 1 ||
+		fake.calls[0].product != "drive" ||
+		fake.calls[0].tool != "download_file" ||
+		fake.calls[0].args["fileId"] != "drive-file" {
+		t.Fatalf("drive call = %#v", fake.calls)
+	}
+
+	var ledger map[string]any
+	shortcut.Register(shortcut.Shortcut{
+		Service: "chat",
+		Command: "+gap-file-resource-download",
+		Flags:   MessageResourceDownloadFlags(),
+		Execute: func(rt *shortcut.RuntimeContext) error {
+			ledger = DownloadMessageResources(rt, []map[string]any{{
+				"content": "[文件] fixture.txt fileId: drive-file",
+			}}, "")
+			return nil
+		},
+	})
+	root = newPlatformCoverageRoot()
+	root.SetArgs([]string{"chat", "+gap-file-resource-download", "--output-dir", "./batch-downloads"})
+	if err := root.Execute(); err != nil {
+		t.Fatal(err)
+	}
+	if ledger["downloadedCount"] != 1 || ledger["failedCount"] != 0 {
+		t.Fatalf("file download ledger = %#v", ledger)
+	}
+	downloads := ledger["downloads"].([]map[string]any)
+	if downloads[0]["resourceType"] != "fileId" ||
+		downloads[0]["localPath"] != "batch-downloads/fixture.txt" ||
+		downloads[0]["messageId"] != "" {
+		t.Fatalf("file download = %#v", downloads[0])
+	}
+}
+
+func TestCrossPlatformCoverageMessageResourceDownloadDisambiguatesSameNames(t *testing.T) {
+	resetResourceDownloadHooks(t)
+	t.Chdir(t.TempDir())
+	destinations := make([]string, 0, 2)
+	resourceDownload = func(
+		_ context.Context,
+		_ *http.Client,
+		_ string,
+		_ map[string]string,
+		dest string,
+		_ bool,
+	) (int64, error) {
+		destinations = append(destinations, filepath.Base(dest))
+		return 1, nil
+	}
+	helpers.InitDeps(&larkAlignmentCaller{responses: map[string]string{
+		"drive/download_file": `{"result":{"downloadUrl":"https://download.dingtalk.com/opaque","fileName":"fixture.txt"}}`,
+	}})
+
+	var ledger map[string]any
+	shortcut.Register(shortcut.Shortcut{
+		Service: "chat",
+		Command: "+gap-colliding-resource-download",
+		Flags:   MessageResourceDownloadFlags(),
+		Execute: func(rt *shortcut.RuntimeContext) error {
+			ledger = DownloadMessageResources(rt, []map[string]any{
+				{"fileId": "file-a"},
+				{"fileId": "file-b"},
+			}, "")
+			return nil
+		},
+	})
+	root := newPlatformCoverageRoot()
+	root.SetArgs([]string{"chat", "+gap-colliding-resource-download", "--output-dir", "./downloads"})
+	if err := root.Execute(); err != nil {
+		t.Fatal(err)
+	}
+	if !reflect.DeepEqual(destinations, []string{"fixture.txt", "fixture (2).txt"}) {
+		t.Fatalf("download destinations = %#v", destinations)
+	}
+	if ledger["downloadedCount"] != 2 || ledger["failedCount"] != 0 {
+		t.Fatalf("download ledger = %#v", ledger)
+	}
+}
+
+func TestCrossPlatformCoverageResourceDownloadFilenameCollisionSequence(t *testing.T) {
+	used := map[string]bool{}
+	first := disambiguateResourceDownloadFilename("a.txt", used)
+	used[strings.ToLower(first)] = true
+	second := disambiguateResourceDownloadFilename("a.txt", used)
+	used[strings.ToLower(second)] = true
+	third := disambiguateResourceDownloadFilename("a (2).txt", used)
+	if first != "a.txt" || second != "a (2).txt" || third != "a (2) (2).txt" {
+		t.Fatalf("collision sequence = %q, %q, %q", first, second, third)
+	}
+}
+
+func TestCrossPlatformCoverageFailedResourceDownloadDoesNotConsumeFilename(t *testing.T) {
+	resetResourceDownloadHooks(t)
+	t.Chdir(t.TempDir())
+	destinations := make([]string, 0, 2)
+	attempt := 0
+	resourceDownload = func(
+		_ context.Context,
+		_ *http.Client,
+		_ string,
+		_ map[string]string,
+		dest string,
+		_ bool,
+	) (int64, error) {
+		destinations = append(destinations, filepath.Base(dest))
+		attempt++
+		if attempt == 1 {
+			return 0, errors.New("fixture download failed")
+		}
+		return 1, nil
+	}
+	helpers.InitDeps(&larkAlignmentCaller{responses: map[string]string{
+		"drive/download_file": `{"result":{"downloadUrl":"https://download.dingtalk.com/opaque","fileName":"fixture.txt"}}`,
+	}})
+
+	var ledger map[string]any
+	shortcut.Register(shortcut.Shortcut{
+		Service: "chat",
+		Command: "+gap-failed-colliding-resource-download",
+		Flags:   MessageResourceDownloadFlags(),
+		Execute: func(rt *shortcut.RuntimeContext) error {
+			ledger = DownloadMessageResources(rt, []map[string]any{
+				{"fileId": "file-a"},
+				{"fileId": "file-b"},
+			}, "")
+			return nil
+		},
+	})
+	root := newPlatformCoverageRoot()
+	root.SetArgs([]string{"chat", "+gap-failed-colliding-resource-download", "--output-dir", "./downloads"})
+	if err := root.Execute(); err != nil {
+		t.Fatal(err)
+	}
+	if !reflect.DeepEqual(destinations, []string{"fixture.txt", "fixture.txt"}) {
+		t.Fatalf("failed download consumed a filename: %#v", destinations)
+	}
+	if ledger["downloadedCount"] != 1 || ledger["failedCount"] != 1 {
+		t.Fatalf("download ledger = %#v", ledger)
+	}
+}
+
+func TestCrossPlatformCoverageMessageResourceDownloadRequiresMediaContextOnly(t *testing.T) {
+	helpers.InitDeps(&larkAlignmentCaller{})
+	root := newPlatformCoverageRoot()
+	root.SetArgs([]string{
+		"chat", "+messages-resource-download",
+		"--resource-id", "@media",
+	})
+	if err := root.Execute(); err == nil ||
+		!strings.Contains(err.Error(), "--type mediaId") {
+		t.Fatalf("missing media context error = %v", err)
+	}
+
+	root = newPlatformCoverageRoot()
+	root.SetArgs([]string{
+		"chat", "+messages-resource-download",
+		"--type", "fileId",
+		"--resource-id", "drive-file",
+		"--output", "../outside",
+	})
+	if err := root.Execute(); err == nil ||
+		!strings.Contains(err.Error(), "--output") {
+		t.Fatalf("unsafe output error = %v", err)
+	}
+}
+
+func TestCrossPlatformCoverageReadHelperRejectsWriteToolDirectly(t *testing.T) {
+	fake := &larkAlignmentCaller{}
+	helpers.InitDeps(fake)
+	if _, err := helpers.CallMCPReadToolTextOnServer("chat", "send_personal_message", nil); err == nil {
+		t.Fatal("write tool was accepted by the helper read channel")
+	}
+	if len(fake.calls) != 0 {
+		t.Fatalf("rejected write reached lower caller: %#v", fake.calls)
+	}
+}
@@ -139,13 +139,13 @@ var MessagesReply = shortcut.Shortcut{
 	Command:     "+messages-reply",
 	Product:     "chat",
 	Description: "以当前用户身份引用回复消息（自动补全原发送者）",
-	Intent:      "当你要以当前用户身份对已有消息发送纯文本引用回复时使用；提供会话和被引用消息即可，默认通过 mget 自动读取原发送者，也可显式传 openDingTalkId/userId。它不支持 bot 身份、富媒体、卡片或 thread 内回复。",
+	Intent:      "当你要以当前用户身份对已有消息发送纯文本引用回复时使用；提供会话和被引用消息即可，默认通过 mget 自动读取原发送者，也可显式传 openDingTalkId/userId；userId 会通过通讯录搜索精确匹配 openDingTalkId。它不支持 bot 身份、富媒体、卡片或 thread 内回复。",
 	Risk:        shortcut.RiskWrite,
 	Flags: []shortcut.Flag{
 		{Name: "conversation-id", Type: shortcut.FlagString, Desc: "会话 openConversationId", Required: true},
 		{Name: "ref-msg-id", Type: shortcut.FlagString, Desc: "被引用消息 openMessageId"},
 		{Name: "message-id", Type: shortcut.FlagString, Desc: "--ref-msg-id 的 lark-cli 对齐别名"},
-		{Name: "ref-sender", Type: shortcut.FlagString, Desc: "原消息发送者 openDingTalkId/userId（不传则自动读取）"},
+		{Name: "ref-sender", Type: shortcut.FlagString, Desc: "原消息发送者 openDingTalkId/userId（userId 通过通讯录搜索精确匹配；不传则自动读取）"},
 		{Name: "text", Type: shortcut.FlagString, Desc: "纯文本回复内容", Required: true},
 		{Name: "uuid", Type: shortcut.FlagString, Desc: "幂等键（可选）"},
 		{Name: "idempotency-key", Type: shortcut.FlagString, Desc: "--uuid 的 lark-cli 对齐别名"},
@@ -184,16 +184,11 @@ func resolveReplySender(rt *shortcut.RuntimeContext) (string, error) {
 		if isOpenID(value) {
 			return value, nil
 		}
-		data, err := rt.CallMCPData("contact", "get_user_info_by_user_ids", map[string]any{
-			"user_id_list": []string{value},
-		})
+		openID, err := resolveUserOpenDingTalkID(rt, value)
 		if err != nil {
 			return "", fmt.Errorf("把 --ref-sender userId 解析为 openDingTalkId 失败: %w", err)
 		}
-		if openID := findOpenDingTalkID(data); openID != "" {
-			return openID, nil
-		}
-		return "", apperrors.NewValidation("无法把 --ref-sender 解析为 openDingTalkId")
+		return openID, nil
 	}

 	messageID := replyMessageID(rt)
@@ -44,7 +44,24 @@ func (f *larkAlignmentCaller) CallTool(_ context.Context, product, tool string,
 	case "contact/get_current_user_profile":
 		text = `{"result":[{"orgEmployeeModel":{"userId":"self-user"}}]}`
 	case "contact/get_user_info_by_user_ids":
-		text = `{"result":[{"userId":"user-id","openDingTalkId":"D-resolved"}]}`
+		text = `{"result":[{"orgEmployeeModel":{"orgUserId":"user-id","orgUserName":"Resolved User"}}]}`
+	case "contact/search_contact_by_key_word":
+		keyword, _ := args["keyword"].(string)
+		payload, _ := json.Marshal(map[string]any{
+			"result": []map[string]any{
+				{
+					"name":           "Fuzzy Neighbor",
+					"userId":         keyword + "-other",
+					"openDingTalkId": "D-other",
+				},
+				{
+					"name":           "Resolved User",
+					"userId":         keyword,
+					"openDingTalkId": "D-resolved",
+				},
+			},
+		})
+		text = string(payload)
 	case "im/create_group_conversation":
 		text = `{"result":{"cid":"internal-cid","openCid":"open-cid"}}`
 	case "im/list_messages_by_ids":
@@ -117,27 +134,35 @@ func TestMessagesSendRoutesIdentitySpecificTransports(t *testing.T) {
 		product string
 		tool    string
 		want    map[string]any
+		bodyKey string
+		body    string
 	}{
 		{
 			name:    "user",
-			args:    []string{"chat", "+messages-send", "--as", "user", "--chat-id", "cid", "--markdown", "hello", "--idempotency-key", "u1", "--yes"},
+			args:    []string{"chat", "+messages-send", "--as", "user", "--chat-id", "cid", "--markdown", "hello @D1", "--at-open-dingtalk-ids", "D1", "--at-all", "--idempotency-key", "u1", "--yes"},
 			product: "chat",
 			tool:    "send_personal_message",
 			want:    map[string]any{"openConversationId": "cid", "msgType": "markdown", "uuid": "u1"},
+			bodyKey: "content",
+			body:    "<@all> hello <@D1>",
 		},
 		{
 			name:    "bot",
-			args:    []string{"chat", "+messages-send", "--identity", "bot", "--robot-code", "robot", "--group", "cid", "--text", "hello", "--at-all", "--yes"},
+			args:    []string{"chat", "+messages-send", "--identity", "bot", "--robot-code", "robot", "--group", "cid", "--text", "<@u1> hello", "--at-user-ids", "u1", "--at-all", "--yes"},
 			product: "bot",
 			tool:    "send_robot_group_message",
 			want:    map[string]any{"robotCode": "robot", "openConversationId": "cid", "isAtAll": "true"},
+			bodyKey: "markdown",
+			body:    "@all @u1 hello",
 		},
 		{
 			name:    "webhook",
-			args:    []string{"chat", "+messages-send", "--identity", "webhook", "--webhook-token", "token", "--text", "hello", "--at-all", "--yes"},
+			args:    []string{"chat", "+messages-send", "--identity", "webhook", "--webhook-token", "token", "--text", "<@13800000000> hello", "--at-mobiles", "13800000000", "--at-all", "--yes"},
 			product: "bot",
 			tool:    "send_message_by_custom_robot",
 			want:    map[string]any{"robotToken": "token", "isAtAll": true},
+			bodyKey: "text",
+			body:    "@all @13800000000 hello",
 		},
 	}
 	for _, tt := range tests {
@@ -161,6 +186,17 @@ func TestMessagesSendRoutesIdentitySpecificTransports(t *testing.T) {
 					t.Errorf("%s = %#v, want %#v", key, call.args[key], want)
 				}
 			}
+			if tt.bodyKey == "content" {
+				var content map[string]string
+				if err := json.Unmarshal([]byte(call.args[tt.bodyKey].(string)), &content); err != nil {
+					t.Fatal(err)
+				}
+				if content["text"] != tt.body {
+					t.Errorf("content text = %q, want %q", content["text"], tt.body)
+				}
+			} else if call.args[tt.bodyKey] != tt.body {
+				t.Errorf("%s = %#v, want %q", tt.bodyKey, call.args[tt.bodyKey], tt.body)
+			}
 		})
 	}
 }
@@ -384,7 +420,7 @@ func TestMessagesMgetDryRunPublishesMultiResourceDownloadPlan(t *testing.T) {
 	}
 }

-func TestMessagesReplyResolvesUserIDBeforeExecution(t *testing.T) {
+func TestCrossPlatformCoverageMessagesReplyResolvesUserIDBeforeExecution(t *testing.T) {
 	fake := &larkAlignmentCaller{}
 	helpers.InitDeps(fake)
 	root := newPlatformCoverageRoot()
@@ -401,7 +437,7 @@ func TestMessagesReplyResolvesUserIDBeforeExecution(t *testing.T) {
 	}
 	if len(fake.calls) != 2 ||
 		fake.calls[0].product != "contact" ||
-		fake.calls[0].tool != "get_user_info_by_user_ids" ||
+		fake.calls[0].tool != "search_contact_by_key_word" ||
 		fake.calls[1].tool != "send_personal_message" {
 		t.Fatalf("calls = %#v", fake.calls)
 	}
@@ -18,6 +18,7 @@ import (
 	"errors"
 	"fmt"
 	"io"
+	"net"
 	"net/http"
 	"net/url"
 	"os"
@@ -54,16 +55,16 @@ var MessagesResourceDownload = shortcut.Shortcut{
 	Service:     "chat",
 	Command:     "+messages-resource-download",
 	Product:     "im",
-	Description: "安全下载消息资源（图片/视频/语音）到本地",
-	Intent: "当你需要拿到消息里的实际图片、视频或语音文件，而不只是临时 URL 时使用；" +
-		"先用消息和会话身份换取下载地址，再安全写入工作目录内的相对路径。" +
-		"默认不覆盖已有文件，只有显式传 --overwrite 才覆盖。",
+	Description: "安全下载消息资源（图片/视频/语音/文件）到本地",
+	Intent: "当你需要拿到消息里的实际图片、视频、语音或钉盘文件，而不只是资源 ID 时使用；" +
+		"mediaId 用消息和会话身份换取下载地址，fileId 复用钉盘下载能力，再安全写入工作目录内的相对路径。" +
+		"默认不覆盖已有文件，只有显式传 --overwrite 才覆盖；按既有安全本地下载约定无需交互确认。",
 	Risk: shortcut.RiskRead,
 	Flags: []shortcut.Flag{
-		{Name: "type", Type: shortcut.FlagString, Default: "mediaId", Desc: "资源类型", Enum: []string{"mediaId"}},
-		{Name: "resource-id", Type: shortcut.FlagString, Desc: "资源 ID（消息中的 mediaId）", Required: true},
-		{Name: "message-id", Type: shortcut.FlagString, Desc: "消息 openMessageId", Required: true},
-		{Name: "open-conversation-id", Type: shortcut.FlagString, Desc: "会话 openConversationId", Required: true},
+		{Name: "type", Type: shortcut.FlagString, Default: "mediaId", Desc: "资源类型", Enum: []string{"mediaId", "fileId"}},
+		{Name: "resource-id", Type: shortcut.FlagString, Desc: "消息中的 mediaId 或 fileId", Required: true},
+		{Name: "message-id", Type: shortcut.FlagString, Desc: "mediaId 所属消息的 openMessageId"},
+		{Name: "open-conversation-id", Type: shortcut.FlagString, Desc: "mediaId 所属会话的 openConversationId"},
 		{Name: "output", Type: shortcut.FlagString, Default: ".", Desc: "工作目录内的相对文件或目录路径"},
 		{Name: "overwrite", Type: shortcut.FlagBool, Desc: "允许覆盖已存在的目标文件（默认拒绝）"},
 	},
@@ -73,17 +74,34 @@ var MessagesResourceDownload = shortcut.Shortcut{
 			Flags:       []string{"output"},
 			Description: "--output 必须是工作目录内的相对路径，不允许绝对路径或 .. 逃逸",
 		},
+		{
+			Kind:        shortcut.ConstraintCustom,
+			Flags:       []string{"type", "message-id", "open-conversation-id"},
+			Description: "--type mediaId 时必须同时提供 --message-id 和 --open-conversation-id；fileId 不需要消息上下文",
+		},
 	},
 	Tips: []string{
 		`dws chat +messages-resource-download --resource-id <mediaId> --message-id <openMessageId> --open-conversation-id <openConversationId>`,
+		`dws chat +messages-resource-download --type fileId --resource-id <fileId> --output ./downloads/`,
 		`dws chat +messages-resource-download --resource-id <mediaId> --message-id <openMessageId> --open-conversation-id <openConversationId> --output ./downloads/`,
 	},
 	Validate: func(rt *shortcut.RuntimeContext) error {
-		return validateResourceDownloadOutput(rt.Str("output"))
+		if err := validateResourceDownloadOutput(rt.Str("output")); err != nil {
+			return err
+		}
+		resourceType, _ := canonicalMessageResourceType(rt.Str("type"))
+		if resourceType == "mediaId" &&
+			(strings.TrimSpace(rt.Str("message-id")) == "" ||
+				strings.TrimSpace(rt.Str("open-conversation-id")) == "") {
+			return apperrors.NewValidation(
+				"--type mediaId 时必须同时提供 --message-id 和 --open-conversation-id")
+		}
+		return nil
 	},
 	Execute: func(rt *shortcut.RuntimeContext) error {
+		resourceType, _ := canonicalMessageResourceType(rt.Str("type"))
 		plan := map[string]any{
-			"resourceType":       rt.Str("type"),
+			"resourceType":       resourceType,
 			"resourceId":         rt.Str("resource-id"),
 			"messageId":          rt.Str("message-id"),
 			"openConversationId": rt.Str("open-conversation-id"),
@@ -101,12 +119,13 @@ var MessagesResourceDownload = shortcut.Shortcut{
 			return rt.Output(plan)
 		}

-		data, err := rt.CallMCPData("im", "get_resource_download_url", map[string]any{
-			"resourceType":       rt.Str("type"),
-			"resourceId":         rt.Str("resource-id"),
-			"openMessageId":      rt.Str("message-id"),
-			"openConversationId": rt.Str("open-conversation-id"),
-		})
+		data, err := resolveMessageResourceDownloadData(
+			rt,
+			resourceType,
+			rt.Str("resource-id"),
+			rt.Str("message-id"),
+			rt.Str("open-conversation-id"),
+		)
 		if err != nil {
 			return err
 		}
@@ -119,7 +138,12 @@ var MessagesResourceDownload = shortcut.Shortcut{
 			return apperrors.NewInternal(fmt.Sprintf("读取工作目录失败: %v", err))
 		}
 		destPath, relativePath, err := resolveResourceDownloadPath(
-			cwd, rt.Str("output"), resourceURL, rt.Bool("overwrite"))
+			cwd,
+			rt.Str("output"),
+			resourceURL,
+			rt.Bool("overwrite"),
+			resourceDownloadPreferredName(data),
+		)
 		if err != nil {
 			return err
 		}
@@ -131,13 +155,46 @@ var MessagesResourceDownload = shortcut.Shortcut{
 		return rt.Output(map[string]any{
 			"messageId":    rt.Str("message-id"),
 			"resourceId":   rt.Str("resource-id"),
-			"resourceType": rt.Str("type"),
+			"resourceType": resourceType,
 			"localPath":    filepath.ToSlash(relativePath),
 			"sizeBytes":    size,
 		})
 	},
 }

+func resolveMessageResourceDownloadData(
+	rt *shortcut.RuntimeContext,
+	resourceType, resourceID, messageID, conversationID string,
+) (map[string]any, error) {
+	resourceType, ok := canonicalMessageResourceType(resourceType)
+	if !ok {
+		return nil, apperrors.NewValidation(fmt.Sprintf(
+			"不支持的消息资源类型 %q；仅支持 mediaId 或 fileId", resourceType))
+	}
+	if resourceType == "fileId" {
+		return rt.CallMCPData("drive", "download_file", map[string]any{
+			"fileId": resourceID,
+		})
+	}
+	return rt.CallMCPData("im", "get_resource_download_url", map[string]any{
+		"resourceType":       "mediaId",
+		"resourceId":         resourceID,
+		"openMessageId":      messageID,
+		"openConversationId": conversationID,
+	})
+}
+
+func canonicalMessageResourceType(resourceType string) (string, bool) {
+	switch {
+	case strings.EqualFold(strings.TrimSpace(resourceType), "mediaId"):
+		return "mediaId", true
+	case strings.EqualFold(strings.TrimSpace(resourceType), "fileId"):
+		return "fileId", true
+	default:
+		return strings.TrimSpace(resourceType), false
+	}
+}
+
 func validateResourceDownloadOutput(output string) error {
 	return validateResourceDownloadOutputFlag(output, "--output")
 }
@@ -195,10 +252,12 @@ func resourceDownloadInfo(data map[string]any) (string, map[string]string, error
 		parsed.Scheme = "https"
 		resourceURL = parsed.String()
 	}
-	if parsed.Scheme != "https" {
-		return "", nil, apperrors.NewAPI(
-			"资源下载接口未返回合法的 HTTPS 下载地址")
+	parsed, err = validateResourceDownloadURL(resourceURL)
+	if err != nil {
+		return "", nil, apperrors.NewAPI(fmt.Sprintf(
+			"资源下载接口返回了不受信任的下载地址: %v", err))
 	}
+	resourceURL = parsed.String()

 	headers := map[string]string{}
 	if values, ok := data["headers"].(map[string]any); ok {
@@ -211,14 +270,65 @@ func resourceDownloadInfo(data map[string]any) (string, map[string]string, error
 	return resourceURL, headers, nil
 }

+func resourceDownloadPreferredName(data map[string]any) string {
+	for {
+		result, ok := data["result"].(map[string]any)
+		if !ok {
+			break
+		}
+		data = result
+	}
+	name, _ := data["fileName"].(string)
+	return strings.TrimSpace(name)
+}
+
 func isAliyunOSSHost(host string) bool {
 	host = strings.ToLower(strings.TrimSuffix(strings.TrimSpace(host), "."))
-	return host == "aliyuncs.com" || strings.HasSuffix(host, ".aliyuncs.com")
+	if !strings.HasSuffix(host, ".aliyuncs.com") {
+		return false
+	}
+	for _, label := range strings.Split(strings.TrimSuffix(host, ".aliyuncs.com"), ".") {
+		if (label == "oss" || strings.HasPrefix(label, "oss-")) &&
+			!strings.Contains(label, "internal") {
+			return true
+		}
+	}
+	return false
+}
+
+func validateResourceDownloadURL(rawURL string) (*url.URL, error) {
+	parsed, err := url.Parse(strings.TrimSpace(rawURL))
+	if err != nil ||
+		parsed.Scheme != "https" ||
+		strings.TrimSpace(parsed.Host) == "" ||
+		parsed.User != nil {
+		return nil, apperrors.NewValidation("资源下载地址必须是受信任域名上的 HTTPS URL")
+	}
+	host := strings.ToLower(strings.TrimSuffix(strings.TrimSpace(parsed.Hostname()), "."))
+	if host == "" || net.ParseIP(host) != nil || !isResourceDownloadAllowedHost(host) {
+		return nil, apperrors.NewValidation(fmt.Sprintf(
+			"资源下载地址域名 %q 不属于受信任的钉钉或 OSS 域名", host))
+	}
+	if port := parsed.Port(); port != "" && port != "443" {
+		return nil, apperrors.NewValidation("资源下载地址只允许使用 HTTPS 默认端口")
+	}
+	return parsed, nil
+}
+
+func isResourceDownloadAllowedHost(host string) bool {
+	host = strings.ToLower(strings.TrimSuffix(strings.TrimSpace(host), "."))
+	// Lower tools may return signed headers with the URL. Keep those headers
+	// confined to platform-owned public download families; extend this list
+	// only after observing another official production download host.
+	return isAliyunOSSHost(host) ||
+		host == "dingtalk.com" ||
+		strings.HasSuffix(host, ".dingtalk.com")
 }

 func resolveResourceDownloadPath(
 	baseDir, output, resourceURL string,
 	overwrite bool,
+	preferredName ...string,
 ) (absolutePath, relativePath string, err error) {
 	if err := validateResourceDownloadOutput(output); err != nil {
 		return "", "", err
@@ -242,7 +352,7 @@ func resolveResourceDownloadPath(
 		directoryIntent ||
 		output == "."
 	if isDirectory {
-		candidate = filepath.Join(candidate, resourceDownloadFilename(resourceURL))
+		candidate = filepath.Join(candidate, resourceDownloadFilename(resourceURL, preferredName...))
 	}

 	parent := filepath.Dir(candidate)
@@ -321,13 +431,17 @@ func ensureResourceDownloadParent(baseDir, parent string) error {
 	return nil
 }

-func resourceDownloadFilename(resourceURL string) string {
+func resourceDownloadFilename(resourceURL string, preferredName ...string) string {
+	if len(preferredName) > 0 {
+		if name := safeResourceDownloadFilename(preferredName[0]); name != "" {
+			return name
+		}
+	}
 	parsed, err := url.Parse(resourceURL)
 	if err == nil {
 		name, unescapeErr := url.PathUnescape(filepath.Base(parsed.Path))
 		if unescapeErr == nil {
-			name = filepath.Base(strings.ReplaceAll(name, "\\", "/"))
-			if name != "" && name != "." && name != string(os.PathSeparator) {
+			if name = safeResourceDownloadFilename(name); name != "" {
 				return name
 			}
 		}
@@ -335,6 +449,43 @@ func resourceDownloadFilename(resourceURL string) string {
 	return "download"
 }

+// safeResourceDownloadFilename returns a portable basename or an empty string
+// for names that are unsafe or unusable on a supported platform. Server-provided
+// file names are untrusted input, and downloads may be prepared on one OS then
+// consumed on another.
+func safeResourceDownloadFilename(raw string) string {
+	normalized := strings.ReplaceAll(raw, "\\", "/")
+	if strings.TrimSpace(normalized) != normalized {
+		return ""
+	}
+	name := filepath.Base(normalized)
+	if name == "" || name == "." || name == ".." ||
+		strings.HasSuffix(name, ".") || strings.HasSuffix(name, " ") {
+		return ""
+	}
+	for _, char := range name {
+		if char < 0x20 || char == 0x7f || strings.ContainsRune(`<>:"/\|?*`, char) {
+			return ""
+		}
+	}
+
+	stem := name
+	if index := strings.IndexByte(stem, '.'); index >= 0 {
+		stem = stem[:index]
+	}
+	stem = strings.ToUpper(strings.TrimRight(stem, " ."))
+	switch stem {
+	case "CON", "PRN", "AUX", "NUL":
+		return ""
+	}
+	if len(stem) == 4 &&
+		(stem[:3] == "COM" || stem[:3] == "LPT") &&
+		stem[3] >= '1' && stem[3] <= '9' {
+		return ""
+	}
+	return name
+}
+
 func downloadResourceAtomically(
 	ctx context.Context,
 	client *http.Client,
@@ -346,22 +497,42 @@ func downloadResourceAtomically(
 	if client == nil {
 		client = &http.Client{Timeout: resourceDownloadTimeout}
 	}
+	parsedResourceURL, err := validateResourceDownloadURL(resourceURL)
+	if err != nil {
+		return 0, err
+	}
 	clientCopy := *client
 	client = &clientCopy
 	originalRedirect := client.CheckRedirect
+	initialHost := strings.ToLower(parsedResourceURL.Hostname())
+	headersConfinedToInitialHost := true
 	client.CheckRedirect = func(req *http.Request, via []*http.Request) error {
-		if req.URL.Scheme != "https" || strings.TrimSpace(req.URL.Host) == "" {
-			return apperrors.NewValidation("资源下载重定向必须使用 HTTPS")
+		if _, redirectErr := validateResourceDownloadURL(req.URL.String()); redirectErr != nil {
+			return apperrors.NewValidation(fmt.Sprintf(
+				"资源下载重定向指向了不受信任的地址: %v", redirectErr))
 		}
 		if len(via) >= 10 {
 			return apperrors.NewAPI("资源下载重定向次数过多")
 		}
+		if !strings.EqualFold(req.URL.Hostname(), initialHost) {
+			headersConfinedToInitialHost = false
+		}
+		// net/http rebuilds redirect headers from the initial request on every
+		// hop. Once a chain leaves the original host, strip lower-service
+		// headers on every later hop so a same-host redirect on the new origin
+		// cannot silently restore them.
+		if !headersConfinedToInitialHost {
+			for key := range headers {
+				req.Header.Del(key)
+			}
+		}
 		if originalRedirect != nil {
 			return originalRedirect(req, via)
 		}
 		return nil
 	}
-	request, err := http.NewRequestWithContext(ctx, http.MethodGet, resourceURL, nil)
+	request, err := http.NewRequestWithContext(
+		ctx, http.MethodGet, parsedResourceURL.String(), nil)
 	if err != nil {
 		return 0, apperrors.NewValidation(fmt.Sprintf("创建资源下载请求失败: %v", err))
 	}
@@ -9,7 +9,6 @@ import (
 	"errors"
 	"io"
 	"net/http"
-	"net/http/httptest"
 	"os"
 	"path/filepath"
 	"strings"
@@ -58,6 +57,7 @@ func TestCrossPlatformCoverageResourceDownloadCommandOutcomes(t *testing.T) {
 		"--resource-id", "@image",
 		"--message-id", "msg",
 		"--open-conversation-id", "cid",
+		"--yes",
 	}
 	t.Run("dry run", func(t *testing.T) {
 		helpers.InitDeps(&larkAlignmentCaller{})
@@ -89,7 +89,7 @@ func TestCrossPlatformCoverageResourceDownloadCommandOutcomes(t *testing.T) {
 		resetResourceDownloadHooks(t)
 		resourceGetwd = func() (string, error) { return "", errors.New("getwd") }
 		helpers.InitDeps(&larkAlignmentCaller{responses: map[string]string{
-			"im/get_resource_download_url": `{"result":{"resourceUrl":"https://example.test/file"}}`,
+			"im/get_resource_download_url": `{"result":{"resourceUrl":"https://download.dingtalk.com/file"}}`,
 		}})
 		root := newPlatformCoverageRoot()
 		root.SetArgs(baseArgs)
@@ -101,7 +101,7 @@ func TestCrossPlatformCoverageResourceDownloadCommandOutcomes(t *testing.T) {
 		resetResourceDownloadHooks(t)
 		resourceAbs = func(string) (string, error) { return "", errors.New("path") }
 		helpers.InitDeps(&larkAlignmentCaller{responses: map[string]string{
-			"im/get_resource_download_url": `{"result":{"resourceUrl":"https://example.test/file"}}`,
+			"im/get_resource_download_url": `{"result":{"resourceUrl":"https://download.dingtalk.com/file"}}`,
 		}})
 		root := newPlatformCoverageRoot()
 		root.SetArgs(baseArgs)
@@ -132,7 +132,7 @@ func TestCrossPlatformCoverageResourceDownloadCommandOutcomes(t *testing.T) {
 			resetResourceDownloadHooks(t)
 			resourceDownload = tc.download
 			helpers.InitDeps(&larkAlignmentCaller{responses: map[string]string{
-				"im/get_resource_download_url": `{"result":{"resourceUrl":"https://example.test/file"}}`,
+				"im/get_resource_download_url": `{"result":{"resourceUrl":"https://download.dingtalk.com/file"}}`,
 			}})
 			root := newPlatformCoverageRoot()
 			root.SetArgs(append(append([]string{}, baseArgs...), "--output", filepath.Join(t.TempDir(), "file")))
@@ -164,7 +164,7 @@ func TestCrossPlatformCoverageResourceDownloadValidationAndInfo(t *testing.T) {
 		}
 	}
 	resourceURL, headers, err := resourceDownloadInfo(map[string]any{
-		"resourceUrl": "https://example.test/file",
+		"resourceUrl": "https://download.dingtalk.com/file",
 		"headers": map[string]any{
 			"":        "ignored",
 			"X-Count": 3,
@@ -175,14 +175,29 @@ func TestCrossPlatformCoverageResourceDownloadValidationAndInfo(t *testing.T) {
 		t.Fatalf("resource info = %q %#v %v", resourceURL, headers, err)
 	}
 	for host, want := range map[string]bool{
-		"ALIYUNCS.COM.":       true,
-		"bucket.aliyuncs.com": true,
-		"example.com":         false,
+		"ALIYUNCS.COM.":                                false,
+		"bucket.aliyuncs.com":                          false,
+		"bucket.oss-cn-hangzhou.aliyuncs.com":          true,
+		"bucket.oss-internal.aliyuncs.com":             false,
+		"bucket.oss-cn-hangzhou-internal.aliyuncs.com": false,
+		"example.com":                                  false,
 	} {
 		if got := isAliyunOSSHost(host); got != want {
 			t.Errorf("isAliyunOSSHost(%q) = %v, want %v", host, got, want)
 		}
 	}
+	for host, want := range map[string]bool{
+		"DINGTALK.COM.":                       true,
+		"download.dingtalk.com":               true,
+		"bucket.oss-cn-hangzhou.aliyuncs.com": true,
+		"aliyuncs.com.evil.test":              false,
+		"evildingtalk.com":                    false,
+		"download.example.invalid":            false,
+	} {
+		if got := isResourceDownloadAllowedHost(host); got != want {
+			t.Errorf("isResourceDownloadAllowedHost(%q) = %v, want %v", host, got, want)
+		}
+	}
 }

 func TestCrossPlatformCoverageResourceDownloadPathErrors(t *testing.T) {
@@ -348,6 +363,24 @@ func TestCrossPlatformCoverageResourceDownloadFilenameFallbacks(t *testing.T) {
 	if got := resourceDownloadFilename("https://example.test/a%20b.txt"); got != "a b.txt" {
 		t.Fatalf("decoded filename = %q", got)
 	}
+	for _, unsafeName := range []string{
+		"..",
+		"CON",
+		"nul.txt",
+		"COM1.log",
+		"trailing.",
+		"trailing ",
+		"line\nbreak.txt",
+		`bad:name.txt`,
+	} {
+		got := resourceDownloadFilename(
+			"https://download.dingtalk.com/fallback.bin",
+			unsafeName,
+		)
+		if got != "fallback.bin" {
+			t.Errorf("unsafe preferred name %q produced %q", unsafeName, got)
+		}
+	}
 }

 type resourceRoundTripper func(*http.Request) (*http.Response, error)
@@ -375,63 +408,105 @@ func TestCrossPlatformCoverageDownloadResourceHTTPFailures(t *testing.T) {
 	errorClient := &http.Client{Transport: resourceRoundTripper(func(*http.Request) (*http.Response, error) {
 		return nil, errors.New("transport")
 	})}
-	if _, err := downloadResourceAtomically(context.Background(), errorClient, "https://example.test/file", nil, dest, false); err == nil {
+	if _, err := downloadResourceAtomically(context.Background(), errorClient, "https://download.dingtalk.com/file", nil, dest, false); err == nil {
 		t.Fatal("transport error was swallowed")
 	}
-	if _, err := downloadResourceAtomically(context.Background(), resourceResponseClient(500, "", 0), "https://example.test/file", nil, dest, false); err == nil {
+	if _, err := downloadResourceAtomically(context.Background(), resourceResponseClient(500, "", 0), "https://download.dingtalk.com/file", nil, dest, false); err == nil {
 		t.Fatal("HTTP 500 was accepted")
 	}
-	if _, err := downloadResourceAtomically(context.Background(), resourceResponseClient(200, "x", 2), "https://example.test/file", nil, dest, false); err == nil {
+	if _, err := downloadResourceAtomically(context.Background(), resourceResponseClient(200, "x", 2), "https://download.dingtalk.com/file", nil, dest, false); err == nil {
 		t.Fatal("content-length mismatch was accepted")
 	}
-
-	plain := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, request *http.Request) {
-		if request.Header.Get("X-Test") != "ok" {
-			t.Errorf("missing forwarded header")
-		}
-		_, _ = w.Write([]byte("body"))
-	}))
-	t.Cleanup(plain.Close)
 	nilClientDest := filepath.Join(t.TempDir(), "nil-client")
-	if _, err := downloadResourceAtomically(context.Background(), nil, plain.URL, map[string]string{"X-Test": "ok"}, nilClientDest, true); err != nil {
-		t.Fatal(err)
+	if _, err := downloadResourceAtomically(
+		context.Background(), nil, "https://evil.example/file",
+		map[string]string{"X-Test": "ok"}, nilClientDest, true,
+	); err == nil {
+		t.Fatal("nil-client path accepted an untrusted URL")
 	}
 }

 func TestCrossPlatformCoverageDownloadResourceRedirectGuards(t *testing.T) {
-	httpRedirect := httptest.NewTLSServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
-		http.Redirect(w, &http.Request{}, "http://example.test/file", http.StatusFound)
-	}))
-	t.Cleanup(httpRedirect.Close)
+	httpRedirect := &http.Client{Transport: resourceRoundTripper(func(*http.Request) (*http.Response, error) {
+		return &http.Response{
+			StatusCode: http.StatusFound,
+			Body:       io.NopCloser(strings.NewReader("")),
+			Header:     http.Header{"Location": []string{"http://evil.example/file"}},
+		}, nil
+	})}
 	if _, err := downloadResourceAtomically(
-		context.Background(), httpRedirect.Client(), httpRedirect.URL, nil,
+		context.Background(), httpRedirect, "https://download.dingtalk.com/start", nil,
 		filepath.Join(t.TempDir(), "http-redirect"), false,
 	); err == nil {
 		t.Fatal("HTTP redirect was accepted")
 	}

-	var loop *httptest.Server
-	loop = httptest.NewTLSServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
-		http.Redirect(w, &http.Request{}, loop.URL, http.StatusFound)
-	}))
-	t.Cleanup(loop.Close)
+	loop := &http.Client{Transport: resourceRoundTripper(func(*http.Request) (*http.Response, error) {
+		return &http.Response{
+			StatusCode: http.StatusFound,
+			Body:       io.NopCloser(strings.NewReader("")),
+			Header:     http.Header{"Location": []string{"https://download.dingtalk.com/loop"}},
+		}, nil
+	})}
 	if _, err := downloadResourceAtomically(
-		context.Background(), loop.Client(), loop.URL, nil,
+		context.Background(), loop, "https://download.dingtalk.com/loop", nil,
 		filepath.Join(t.TempDir(), "loop"), false,
 	); err == nil {
 		t.Fatal("redirect loop was accepted")
 	}

-	original := loop.Client()
+	original := *loop
 	original.CheckRedirect = func(*http.Request, []*http.Request) error {
 		return errors.New("original redirect policy")
 	}
 	if _, err := downloadResourceAtomically(
-		context.Background(), original, loop.URL, nil,
+		context.Background(), &original, "https://download.dingtalk.com/loop", nil,
 		filepath.Join(t.TempDir(), "original"), false,
 	); err == nil {
 		t.Fatal("original redirect rejection was swallowed")
 	}
+
+	redirectCount := 0
+	crossHost := &http.Client{Transport: resourceRoundTripper(func(request *http.Request) (*http.Response, error) {
+		redirectCount++
+		switch redirectCount {
+		case 1:
+			if request.Header.Get("X-Resource-Token") != "secret" {
+				t.Fatal("initial signed header missing")
+			}
+			return &http.Response{
+				StatusCode: http.StatusFound,
+				Body:       io.NopCloser(strings.NewReader("")),
+				Header:     http.Header{"Location": []string{"https://bucket.oss-cn-hangzhou.aliyuncs.com/intermediate"}},
+			}, nil
+		case 2:
+			if request.Header.Get("X-Resource-Token") != "" {
+				t.Fatal("server-supplied header leaked on first cross-host hop")
+			}
+			return &http.Response{
+				StatusCode: http.StatusFound,
+				Body:       io.NopCloser(strings.NewReader("")),
+				Header:     http.Header{"Location": []string{"https://bucket.oss-cn-hangzhou.aliyuncs.com/final"}},
+			}, nil
+		default:
+			if request.Header.Get("X-Resource-Token") != "" {
+				t.Fatal("server-supplied header was restored on later same-host hop")
+			}
+		}
+		return &http.Response{
+			StatusCode:    http.StatusOK,
+			Body:          io.NopCloser(strings.NewReader("ok")),
+			ContentLength: 2,
+			Header:        make(http.Header),
+		}, nil
+	})}
+	if _, err := downloadResourceAtomically(
+		context.Background(), crossHost, "https://download.dingtalk.com/start",
+		map[string]string{"X-Resource-Token": "secret"},
+		filepath.Join(t.TempDir(), "cross-host"), false,
+	); err != nil {
+		t.Fatal(err)
+	}
 }

 func TestCrossPlatformCoverageDownloadResourceFileFailures(t *testing.T) {
@@ -439,7 +514,7 @@ func TestCrossPlatformCoverageDownloadResourceFileFailures(t *testing.T) {
 	run := func(t *testing.T, overwrite bool) error {
 		t.Helper()
 		_, err := downloadResourceAtomically(
-			context.Background(), client, "https://example.test/file", nil,
+			context.Background(), client, "https://download.dingtalk.com/file", nil,
 			filepath.Join(t.TempDir(), "resource"), overwrite)
 		return err
 	}
@@ -516,7 +591,7 @@ func TestCrossPlatformCoverageDownloadResourceCopySuccessWithBuffer(t *testing.T
 	dest := filepath.Join(t.TempDir(), "resource")
 	if _, err := downloadResourceAtomically(
 		context.Background(), resourceResponseClient(200, "ok", 2),
-		"https://example.test/file", nil, dest, true,
+		"https://download.dingtalk.com/file", nil, dest, true,
 	); err != nil {
 		t.Fatal(err)
 	}
@@ -15,18 +15,41 @@ package chat

 import (
 	"context"
+	"io"
 	"net/http"
-	"net/http/httptest"
 	"os"
 	"path/filepath"
 	"strings"
 	"testing"
 )

-func TestResourceDownloadInfo(t *testing.T) {
+func TestCrossPlatformCoverageCanonicalMessageResourceType(t *testing.T) {
+	for input, want := range map[string]string{
+		"mediaId":  "mediaId",
+		"MEDIAID":  "mediaId",
+		" fileid ": "fileId",
+		"FileId":   "fileId",
+	} {
+		got, ok := canonicalMessageResourceType(input)
+		if !ok || got != want {
+			t.Errorf("canonicalMessageResourceType(%q) = %q, %v; want %q, true",
+				input, got, ok, want)
+		}
+	}
+	if got, ok := canonicalMessageResourceType("attachment"); ok || got != "attachment" {
+		t.Errorf("unsupported resource type = %q, %v", got, ok)
+	}
+	if _, err := resolveMessageResourceDownloadData(
+		nil, "attachment", "resource", "message", "conversation",
+	); err == nil || !strings.Contains(err.Error(), "不支持的消息资源类型") {
+		t.Fatalf("unsupported resolver type error = %v", err)
+	}
+}
+
+func TestCrossPlatformCoverageResourceDownloadInfo(t *testing.T) {
 	url, headers, err := resourceDownloadInfo(map[string]any{
 		"result": map[string]any{
-			"resourceUrl": []any{"https://download.example.test/path/image.png"},
+			"resourceUrl": []any{"https://download.dingtalk.com/path/image.png"},
 			"headers": map[string]any{
 				"X-Test": "value",
 			},
@@ -35,7 +58,7 @@ func TestResourceDownloadInfo(t *testing.T) {
 	if err != nil {
 		t.Fatal(err)
 	}
-	if url != "https://download.example.test/path/image.png" {
+	if url != "https://download.dingtalk.com/path/image.png" {
 		t.Fatalf("url = %q", url)
 	}
 	if headers["X-Test"] != "value" {
@@ -57,6 +80,19 @@ func TestResourceDownloadInfo(t *testing.T) {
 	}); err == nil {
 		t.Fatal("plain HTTP URL unexpectedly accepted")
 	}
+	for _, resourceURL := range []string{
+		"https://evil.example/file",
+		"https://aliyuncs.com.evil.example/file",
+		"https://127.0.0.1/file",
+		"https://user:secret@download.dingtalk.com/file",
+		"https://download.dingtalk.com:8443/file",
+	} {
+		if _, _, err := resourceDownloadInfo(
+			map[string]any{"resourceUrl": resourceURL},
+		); err == nil {
+			t.Fatalf("untrusted URL %q unexpectedly accepted", resourceURL)
+		}
+	}
 }

 func TestResolveResourceDownloadPath(t *testing.T) {
@@ -115,16 +151,23 @@ func TestResolveResourceDownloadPathRejectsSymlinkParentBeforeCreatingOutside(t
 	}
 }

-func TestDownloadResourceAtomically(t *testing.T) {
+func TestCrossPlatformCoverageDownloadResourceAtomically(t *testing.T) {
 	const body = "verified download bytes"
-	server := httptest.NewTLSServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
-		_, _ = w.Write([]byte(body))
-	}))
-	t.Cleanup(server.Close)
+	client := &http.Client{Transport: resourceRoundTripper(func(request *http.Request) (*http.Response, error) {
+		if request.URL.String() != "https://download.dingtalk.com/resource.bin" {
+			t.Fatalf("request URL = %q", request.URL)
+		}
+		return &http.Response{
+			StatusCode:    http.StatusOK,
+			Body:          io.NopCloser(strings.NewReader(body)),
+			ContentLength: int64(len(body)),
+			Header:        make(http.Header),
+		}, nil
+	})}
 	dest := filepath.Join(t.TempDir(), "resource.bin")

 	size, err := downloadResourceAtomically(
-		context.Background(), server.Client(), server.URL, nil, dest, false)
+		context.Background(), client, "https://download.dingtalk.com/resource.bin", nil, dest, false)
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -139,7 +182,7 @@ func TestDownloadResourceAtomically(t *testing.T) {
 		t.Fatalf("body = %q", got)
 	}
 	if _, err := downloadResourceAtomically(
-		context.Background(), server.Client(), server.URL, nil, dest, false,
+		context.Background(), client, "https://download.dingtalk.com/resource.bin", nil, dest, false,
 	); err == nil || !strings.Contains(err.Error(), "已存在") {
 		t.Fatalf("no-clobber error = %v", err)
 	}
@@ -5,41 +5,51 @@
 package chat

 import (
+	"context"
 	"encoding/json"
 	"fmt"
 	"strings"
+	"time"
 	"unicode/utf8"

 	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/helpers"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut"
 )

-// MessagesSend is the identity-aware common text/Markdown entry point. Media
-// upload remains on the native message send command until DWS has one shared
-// upload contract; this Shortcut does not pretend webhook/bot/current-user
-// transports support identical capabilities.
+const messagesSendFileUploadTimeout = 10 * time.Minute
+
+// MessagesSend is the identity-aware common sending entry point. The current
+// user branch reuses the native message leaf's reviewed file-upload flow and
+// existing-mediaId image path. Bot and webhook remain text/Markdown-only
+// because their lower transports do not expose equivalent media contracts.
 var MessagesSend = shortcut.Shortcut{
 	Service:     "chat",
 	Command:     "+messages-send",
 	Product:     "chat",
-	Description: "统一发送文本/Markdown（current user、bot、webhook）",
-	Intent:      "当你希望用同一个入口选择 current-user、bot 或 webhook 身份发送文本/Markdown 时使用；命令会按身份校验目标和凭据并路由到真实下层。current-user 支持幂等键，bot 支持群聊或批量单聊，webhook 的目标由 token 所在群决定。媒体上传仍使用原生命令。",
+	Description: "统一发送文本、Markdown、当前用户文件或已有 mediaId 图片",
+	Intent:      "当你希望用同一个入口选择 current-user、bot 或 webhook 身份发送消息时使用；命令会按身份校验目标、内容和凭据并路由到真实下层。current-user 支持文本/Markdown、已有 mediaId 图片、安全相对路径文件上传和幂等键；--user 传 userId 时包括在 --dry-run 中也会先通过通讯录关键词搜索并按 userId 精确匹配 openDingTalkId。bot 支持群聊或批量单聊文本/Markdown；webhook 的目标由 token 所在群决定。不会把 user 文件能力伪装成 bot/webhook 等价能力。",
 	Risk:        shortcut.RiskWrite,
 	Flags: []shortcut.Flag{
-		{Name: "identity", Type: shortcut.FlagString, Default: "user", Enum: []string{"user", "bot", "webhook"}, Desc: "发送身份"},
-		{Name: "as", Type: shortcut.FlagString, Enum: []string{"user", "bot", "webhook"}, Desc: "--identity 的 lark-cli 对齐别名"},
-		{Name: "group", Type: shortcut.FlagString, Desc: "群 openConversationId（user/bot 群聊）"},
-		{Name: "chat-id", Type: shortcut.FlagString, Desc: "--group 的 lark-cli 对齐别名"},
-		{Name: "open-dingtalk-id", Type: shortcut.FlagString, Desc: "单聊接收者 openDingTalkId（user）"},
-		{Name: "users", Type: shortcut.FlagStringSlice, Desc: "批量单聊接收者 userId（bot）"},
-		{Name: "open-dingtalk-ids", Type: shortcut.FlagStringSlice, Desc: "批量单聊接收者 openDingTalkId（bot）"},
-		{Name: "robot-code", Type: shortcut.FlagString, Desc: "机器人 Code（bot 必填）"},
-		{Name: "webhook-token", Type: shortcut.FlagString, Desc: "自定义机器人 Webhook token（webhook 必填）"},
+		{Name: "identity", Type: shortcut.FlagString, Default: "user", Enum: []string{"user", "bot", "webhook"}, Desc: "发送身份；目标、凭据和幂等参数受发送身份能力矩阵约束"},
+		{Name: "as", Type: shortcut.FlagString, Enum: []string{"user", "bot", "webhook"}, Desc: "--identity 的 lark-cli 对齐别名；受发送身份能力矩阵约束"},
+		{Name: "group", Type: shortcut.FlagString, Desc: "群 openConversationId（user/bot 群聊）；受发送身份能力矩阵约束"},
+		{Name: "chat-id", Type: shortcut.FlagString, Desc: "--group 的 lark-cli 对齐别名；受发送身份能力矩阵约束"},
+		{Name: "user", Type: shortcut.FlagString, Desc: "单聊接收者 userId（user；包括 --dry-run 也会先通过通讯录搜索精确匹配 openDingTalkId）；受发送身份能力矩阵约束"},
+		{Name: "open-dingtalk-id", Type: shortcut.FlagString, Desc: "单聊接收者 openDingTalkId（user）；受发送身份能力矩阵约束"},
+		{Name: "users", Type: shortcut.FlagStringSlice, Desc: "批量单聊接收者 userId（bot）；受发送身份能力矩阵约束"},
+		{Name: "open-dingtalk-ids", Type: shortcut.FlagStringSlice, Desc: "批量单聊接收者 openDingTalkId（bot）；受发送身份能力矩阵约束"},
+		{Name: "robot-code", Type: shortcut.FlagString, Desc: "机器人 Code（identity=bot 时使用）；受发送身份能力矩阵约束"},
+		{Name: "webhook-token", Type: shortcut.FlagString, Desc: "自定义机器人 Webhook token（identity=webhook 时使用）；受发送身份能力矩阵约束"},
 		{Name: "title", Type: shortcut.FlagString, Desc: "消息标题（不传则从正文生成）"},
 		{Name: "text", Type: shortcut.FlagString, Desc: "纯文本正文"},
 		{Name: "markdown", Type: shortcut.FlagString, Desc: "Markdown 正文"},
-		{Name: "uuid", Type: shortcut.FlagString, Desc: "幂等键（仅 user）"},
-		{Name: "idempotency-key", Type: shortcut.FlagString, Desc: "--uuid 的 lark-cli 对齐别名（仅 user）"},
+		{Name: "msg-type", Type: shortcut.FlagString, Enum: []string{"text", "markdown", "image", "file", "audio", "video"}, Desc: "内容类型；省略时根据正文、--media-id 或 --file 自动推断"},
+		{Name: "media-id", Type: shortcut.FlagString, Desc: "已有图片 mediaId（仅 user 的 image）"},
+		{Name: "file", Type: shortcut.FlagString, Desc: "工作目录内安全相对文件路径（仅 user 的 file/audio/video）"},
+		{Name: "file-path", Type: shortcut.FlagString, Desc: "--file 的兼容别名"},
+		{Name: "uuid", Type: shortcut.FlagString, Desc: "幂等键（仅 user）；受发送身份能力矩阵约束"},
+		{Name: "idempotency-key", Type: shortcut.FlagString, Desc: "--uuid 的 lark-cli 对齐别名（仅 user）；受发送身份能力矩阵约束"},
 		{Name: "at-open-dingtalk-ids", Type: shortcut.FlagStringSlice, Desc: "@ 的 openDingTalkId（user/bot 群聊）"},
 		{Name: "at-user-ids", Type: shortcut.FlagStringSlice, Desc: "@ 的 userId（bot/webhook）"},
 		{Name: "at-mobiles", Type: shortcut.FlagStringSlice, Desc: "@ 的手机号（webhook）"},
@@ -47,19 +57,21 @@ var MessagesSend = shortcut.Shortcut{
 		shortcut.AIMessageTagFlag(),
 	},
 	Constraints: []shortcut.Constraint{
-		{Kind: shortcut.ConstraintAtLeastOne, Flags: []string{"text", "markdown"}},
-		{Kind: shortcut.ConstraintMutuallyExclusive, Flags: []string{"text", "markdown"}},
+		{Kind: shortcut.ConstraintAtLeastOne, Flags: []string{"text", "markdown", "media-id", "file", "file-path"}},
+		{Kind: shortcut.ConstraintMutuallyExclusive, Flags: []string{"text", "markdown", "media-id", "file", "file-path"}},
 		{Kind: shortcut.ConstraintMutuallyExclusive, Flags: []string{"identity", "as"}},
 		{Kind: shortcut.ConstraintMutuallyExclusive, Flags: []string{"group", "chat-id"}},
+		{Kind: shortcut.ConstraintMutuallyExclusive, Flags: []string{"user", "open-dingtalk-id"}},
 		{Kind: shortcut.ConstraintMutuallyExclusive, Flags: []string{"uuid", "idempotency-key"}},
 		{
 			Kind:        shortcut.ConstraintCustom,
-			Flags:       []string{"identity", "as", "group", "chat-id", "open-dingtalk-id", "users", "open-dingtalk-ids", "robot-code", "webhook-token", "uuid", "idempotency-key"},
-			Description: "user 必须指定 group/open-dingtalk-id 之一；bot 必须指定 robot-code 和群聊/批量单聊目标之一；webhook 必须指定 webhook-token；幂等键仅 user 支持",
+			Flags:       []string{"identity", "as", "group", "chat-id", "user", "open-dingtalk-id", "users", "open-dingtalk-ids", "robot-code", "webhook-token", "uuid", "idempotency-key"},
+			Description: "目标、凭据和幂等参数受发送身份能力矩阵约束：user 必须指定一个群聊或单聊目标；bot 必须指定 robot-code 和一类目标；webhook 必须指定 webhook-token；幂等键仅 user 支持",
 		},
 	},
 	Tips: []string{
 		`dws chat +messages-send --as user --chat-id <openConversationId> --markdown "## 周报" --idempotency-key <key>`,
+		`dws chat +messages-send --as user --user <userId> --msg-type file --file ./report.pdf --idempotency-key <key>`,
 		`dws chat +messages-send --as bot --robot-code <robotCode> --users userId1,userId2 --text "请提交周报"`,
 	},
 	Validate: validateMessagesSend,
@@ -69,16 +81,28 @@ var MessagesSend = shortcut.Shortcut{
 func validateMessagesSend(rt *shortcut.RuntimeContext) error {
 	identity := messagesSendIdentity(rt)
 	group := rt.StrFirst("chat-id", "group")
+	userID := rt.Str("user")
 	openID := rt.Str("open-dingtalk-id")
 	users := uniqueShortcutStrings(rt.StrSlice("users"))
 	openIDs := uniqueShortcutStrings(rt.StrSlice("open-dingtalk-ids"))
 	atOpenIDs := uniqueShortcutStrings(rt.StrSlice("at-open-dingtalk-ids"))
 	atUserIDs := uniqueShortcutStrings(rt.StrSlice("at-user-ids"))
 	atMobiles := uniqueShortcutStrings(rt.StrSlice("at-mobiles"))
+	contentType, err := messagesSendContentType(rt)
+	if err != nil {
+		return err
+	}
+	if contentType == "text" && rt.Str("markdown") != "" {
+		return apperrors.NewValidation("--msg-type text 必须与 --text 一起使用")
+	}
+	if contentType == "markdown" && rt.Str("text") != "" {
+		return apperrors.NewValidation("--msg-type markdown 必须与 --markdown 一起使用")
+	}
 	switch identity {
 	case "user":
-		if (group == "") == (openID == "") {
-			return apperrors.NewValidation("--identity user 时 --group 与 --open-dingtalk-id 必须且只能指定一个")
+		targetCount := nonEmptyStringCount(group, userID, openID)
+		if targetCount != 1 {
+			return apperrors.NewValidation("--identity user 时 --group、--user、--open-dingtalk-id 必须且只能指定一个")
 		}
 		if len(users) > 0 || len(openIDs) > 0 || rt.Str("robot-code") != "" || rt.Str("webhook-token") != "" {
 			return apperrors.NewValidation("--identity user 不接受 bot/webhook 凭据或批量目标")
@@ -86,9 +110,12 @@ func validateMessagesSend(rt *shortcut.RuntimeContext) error {
 		if len(atUserIDs) > 0 || len(atMobiles) > 0 {
 			return apperrors.NewValidation("--identity user 只接受 --at-open-dingtalk-ids")
 		}
-		if openID != "" && (len(atOpenIDs) > 0 || rt.Bool("at-all")) {
+		if (userID != "" || openID != "") && (len(atOpenIDs) > 0 || rt.Bool("at-all")) {
 			return apperrors.NewValidation("user 单聊不接受 @ 参数；@ 只适用于群聊")
 		}
+		if contentType != "text" && contentType != "markdown" && (len(atOpenIDs) > 0 || rt.Bool("at-all")) {
+			return apperrors.NewValidation("user image/file/audio/video 当前不接受 @ 参数")
+		}
 	case "bot":
 		if rt.Str("robot-code") == "" {
 			return apperrors.NewValidation("--identity bot 必须指定 --robot-code")
@@ -97,8 +124,8 @@ func validateMessagesSend(rt *shortcut.RuntimeContext) error {
 		if (group != "") == hasDirect {
 			return apperrors.NewValidation("--identity bot 时 --group 与批量单聊目标必须且只能指定一类")
 		}
-		if openID != "" || rt.Str("webhook-token") != "" {
-			return apperrors.NewValidation("--identity bot 不接受 --open-dingtalk-id 或 --webhook-token")
+		if userID != "" || openID != "" || rt.Str("webhook-token") != "" {
+			return apperrors.NewValidation("--identity bot 不接受 --user、--open-dingtalk-id 或 --webhook-token")
 		}
 		if len(atMobiles) > 0 {
 			return apperrors.NewValidation("--identity bot 不接受 --at-mobiles")
@@ -109,11 +136,14 @@ func validateMessagesSend(rt *shortcut.RuntimeContext) error {
 		if messagesSendIdempotencyKey(rt) != "" {
 			return apperrors.NewValidation("--uuid 当前仅 user 身份的下层支持")
 		}
+		if contentType != "text" && contentType != "markdown" {
+			return apperrors.NewValidation("--identity bot 当前下层只支持 text/markdown")
+		}
 	case "webhook":
 		if rt.Str("webhook-token") == "" {
 			return apperrors.NewValidation("--identity webhook 必须指定 --webhook-token")
 		}
-		if group != "" || openID != "" || len(users) > 0 || len(openIDs) > 0 || rt.Str("robot-code") != "" {
+		if group != "" || userID != "" || openID != "" || len(users) > 0 || len(openIDs) > 0 || rt.Str("robot-code") != "" {
 			return apperrors.NewValidation("--identity webhook 的目标由 token 所在群决定，不接受其他目标或 bot Code")
 		}
 		if len(atOpenIDs) > 0 {
@@ -122,6 +152,9 @@ func validateMessagesSend(rt *shortcut.RuntimeContext) error {
 		if messagesSendIdempotencyKey(rt) != "" {
 			return apperrors.NewValidation("--uuid 当前仅 user 身份的下层支持")
 		}
+		if contentType != "text" && contentType != "markdown" {
+			return apperrors.NewValidation("--identity webhook 当前下层只支持 text/markdown")
+		}
 	}
 	return nil
 }
@@ -135,12 +168,43 @@ func executeMessagesSend(rt *shortcut.RuntimeContext) error {
 	}
 	switch identity {
 	case "user":
+		contentType, err := messagesSendContentType(rt)
+		if err != nil {
+			return err
+		}
+		group, openID, err := messagesSendUserTarget(rt)
+		if err != nil {
+			return err
+		}
+		if contentType == "image" {
+			content, _ := json.Marshal(map[string]string{"mediaId": rt.Str("media-id")})
+			params := rt.AddAIMessageTag(map[string]any{
+				"msgType": "image",
+				"content": string(content),
+			})
+			addMessagesSendUserTarget(params, group, openID)
+			if value := messagesSendIdempotencyKey(rt); value != "" {
+				params["uuid"] = value
+			}
+			return executeUnifiedMessageWrite(rt, "chat", "send_personal_message", params)
+		}
+		if contentType == "file" || contentType == "audio" || contentType == "video" {
+			return executeMessagesSendUserFile(rt, group, openID, contentType)
+		}
+		if group != "" {
+			body = helpers.NormalizeMessageMentions(
+				body,
+				uniqueShortcutStrings(rt.StrSlice("at-open-dingtalk-ids")),
+				rt.Bool("at-all"),
+				true,
+			)
+		}
 		content, _ := json.Marshal(map[string]string{"title": title, "text": body})
 		params := rt.AddAIMessageTag(map[string]any{
 			"msgType": "markdown",
 			"content": string(content),
 		})
-		if group := rt.StrFirst("chat-id", "group"); group != "" {
+		if group != "" {
 			params["openConversationId"] = group
 			if values := uniqueShortcutStrings(rt.StrSlice("at-open-dingtalk-ids")); len(values) > 0 {
 				params["atOpenDingTalkIds"] = values
@@ -149,13 +213,22 @@ func executeMessagesSend(rt *shortcut.RuntimeContext) error {
 				params["atAll"] = true
 			}
 		} else {
-			params["receiverOpenDingTalkId"] = rt.Str("open-dingtalk-id")
+			params["receiverOpenDingTalkId"] = openID
 		}
 		if value := messagesSendIdempotencyKey(rt); value != "" {
 			params["uuid"] = value
 		}
 		return executeUnifiedMessageWrite(rt, "chat", "send_personal_message", params)
 	case "bot":
+		body = helpers.NormalizeMessageMentions(
+			body,
+			append(
+				uniqueShortcutStrings(rt.StrSlice("at-user-ids")),
+				uniqueShortcutStrings(rt.StrSlice("at-open-dingtalk-ids"))...,
+			),
+			rt.Bool("at-all"),
+			false,
+		)
 		params := map[string]any{
 			"robotCode": rt.Str("robot-code"),
 			"title":     title,
@@ -185,6 +258,15 @@ func executeMessagesSend(rt *shortcut.RuntimeContext) error {
 		}
 		return executeUnifiedMessageWrite(rt, "bot", "batch_send_robot_msg_to_users", params)
 	case "webhook":
+		body = helpers.NormalizeMessageMentions(
+			body,
+			append(
+				uniqueShortcutStrings(rt.StrSlice("at-user-ids")),
+				uniqueShortcutStrings(rt.StrSlice("at-mobiles"))...,
+			),
+			rt.Bool("at-all"),
+			false,
+		)
 		params := map[string]any{
 			"robotToken": rt.Str("webhook-token"),
 			"title":      title,
@@ -241,6 +323,191 @@ func messagesSendBody(rt *shortcut.RuntimeContext) string {
 	return rt.StrFirst("markdown", "text")
 }

+func messagesSendContentType(rt *shortcut.RuntimeContext) (string, error) {
+	contentType := strings.ToLower(rt.Str("msg-type"))
+	switch {
+	case rt.Str("media-id") != "":
+		if contentType != "" && contentType != "image" {
+			return "", apperrors.NewValidation("--media-id 只支持 --msg-type image")
+		}
+		return "image", nil
+	case rt.StrFirst("file", "file-path") != "":
+		if contentType == "" {
+			return "file", nil
+		}
+		if contentType != "file" && contentType != "audio" && contentType != "video" {
+			return "", apperrors.NewValidation("--file 只支持 --msg-type file/audio/video")
+		}
+		return contentType, nil
+	default:
+		if contentType == "" {
+			if rt.Str("markdown") != "" {
+				return "markdown", nil
+			}
+			return "text", nil
+		}
+		if contentType != "text" && contentType != "markdown" {
+			return "", apperrors.NewValidation(fmt.Sprintf("--msg-type %s 需要匹配的 --media-id 或 --file", contentType))
+		}
+		return contentType, nil
+	}
+}
+
+func messagesSendUserTarget(rt *shortcut.RuntimeContext) (group, openID string, err error) {
+	group = rt.StrFirst("chat-id", "group")
+	openID = rt.Str("open-dingtalk-id")
+	if openID != "" || group != "" {
+		return group, openID, nil
+	}
+	openID, err = resolveUserOpenDingTalkID(rt, rt.Str("user"))
+	if err != nil {
+		return "", "", err
+	}
+	return "", openID, nil
+}
+
+func resolveUserOpenDingTalkID(rt *shortcut.RuntimeContext, userID string) (string, error) {
+	userID = strings.TrimSpace(userID)
+	data, err := rt.CallMCPData("contact", "search_contact_by_key_word", map[string]any{
+		"keyword": userID,
+	})
+	if err != nil {
+		return "", fmt.Errorf("通过通讯录搜索把 userId %q 解析为 openDingTalkId 失败: %w", userID, err)
+	}
+
+	exactRows := 0
+	openIDs := make([]string, 0, 1)
+	for _, user := range shortcutMapSlice(data["result"]) {
+		if shortcutString(user, "userId", "userID") != userID {
+			continue
+		}
+		exactRows++
+		if openID := shortcutString(user, "openDingTalkId", "openDingtalkId"); openID != "" {
+			openIDs = appendUniqueShortcutString(openIDs, openID)
+		}
+	}
+	switch {
+	case len(openIDs) == 1:
+		return openIDs[0], nil
+	case len(openIDs) > 1:
+		return "", apperrors.NewValidation(fmt.Sprintf(
+			"通讯录中 userId %q 精确匹配到多个不同的 openDingTalkId，无法安全选择",
+			userID,
+		))
+	case exactRows > 0:
+		return "", apperrors.NewValidation(fmt.Sprintf(
+			"通讯录已精确匹配 userId %q，但结果未返回 openDingTalkId",
+			userID,
+		))
+	default:
+		return "", apperrors.NewValidation(fmt.Sprintf(
+			"通讯录搜索结果中没有精确匹配的 userId %q",
+			userID,
+		))
+	}
+}
+
+func executeMessagesSendUserFile(
+	rt *shortcut.RuntimeContext,
+	group, openID, requestedType string,
+) error {
+	rawPath := rt.StrFirst("file", "file-path")
+	safePath, err := apperrors.SafeInputPath(rawPath)
+	if err != nil {
+		return err
+	}
+	meta, err := helpers.BuildConversationLocalFileMeta(safePath, "", "")
+	if err != nil {
+		return err
+	}
+	targetArgs := map[string]any{}
+	addMessagesSendUserTarget(targetArgs, group, openID)
+	idempotencyKey := messagesSendIdempotencyKey(rt)
+	if rt.DryRun() {
+		return rt.Output(map[string]any{
+			"dry_run":      true,
+			"executed":     false,
+			"preview_kind": "plan",
+			"actionCount":  2,
+			"failedCount":  0,
+			"actions": []map[string]any{
+				{
+					"identity": "user",
+					"tool":     "init/commit_conversation_file_upload",
+					"file": map[string]any{
+						"path":      rawPath,
+						"name":      meta.FileName,
+						"sizeBytes": meta.FileSize,
+					},
+				},
+				{
+					"identity":             "user",
+					"tool":                 "send_personal_message",
+					"requestedMessageType": requestedType,
+					"effectiveMessageType": "file",
+					"target":               targetArgs,
+				},
+			},
+		})
+	}
+	uploadContext, cancelUpload := context.WithTimeout(
+		rt.Command().Context(), messagesSendFileUploadTimeout)
+	defer cancelUpload()
+	commitText, err := helpers.UploadConversationLocalFile(
+		uploadContext, targetArgs, meta, idempotencyKey)
+	if err != nil {
+		return err
+	}
+	dentryID, spaceID, err := helpers.ParseConversationFileSendIDs(commitText)
+	if err != nil {
+		return err
+	}
+	content, _ := helpers.BuildConversationFileContent(dentryID, spaceID, meta)
+	params := rt.AddAIMessageTag(map[string]any{
+		"msgType": "file",
+		"content": content,
+	})
+	addMessagesSendUserTarget(params, group, openID)
+	if idempotencyKey != "" {
+		params["uuid"] = idempotencyKey
+	}
+	data, err := rt.CallMCPWriteData("chat", "send_personal_message", params)
+	if err != nil {
+		return err
+	}
+	return rt.Output(map[string]any{
+		"ok":                   true,
+		"identity":             "user",
+		"tool":                 "send_personal_message",
+		"requestedMessageType": requestedType,
+		"effectiveMessageType": "file",
+		"file": map[string]any{
+			"path":      rawPath,
+			"name":      meta.FileName,
+			"sizeBytes": meta.FileSize,
+		},
+		"result": data,
+	})
+}
+
+func addMessagesSendUserTarget(params map[string]any, group, openID string) {
+	if group != "" {
+		params["openConversationId"] = group
+		return
+	}
+	params["receiverOpenDingTalkId"] = openID
+}
+
+func nonEmptyStringCount(values ...string) int {
+	count := 0
+	for _, value := range values {
+		if strings.TrimSpace(value) != "" {
+			count++
+		}
+	}
+	return count
+}
+
 func messagesSendIdempotencyKey(rt *shortcut.RuntimeContext) string {
 	return rt.StrFirst("idempotency-key", "uuid")
 }
@@ -207,21 +207,25 @@ func firstMessageValue(m map[string]any, keys ...string) any {
 	return nil
 }

-// Resources extracts actionable media references from both structured message
-// fields and the textual mediaId notation returned by older DingTalk message
-// APIs. Every reference publishes the exact Shortcut arguments already known
-// from the message, plus ready=false and missing fields when a follow-up lookup
-// is still required. This shared shape is used by list, search, mget, quoted
-// messages and thread replies.
+// Resources extracts actionable media and drive-file references from both
+// structured message fields and the textual mediaId/fileId notation returned
+// by older DingTalk message APIs. Every reference publishes the exact Shortcut
+// arguments already known from the message, plus ready=false and missing fields
+// when a follow-up lookup is still required. This shared shape is used by list,
+// search, mget, quoted messages and thread replies.
 func Resources(m map[string]any) []map[string]any {
 	if m == nil {
 		return nil
 	}
-	ids := make([]string, 0)
-	collectMediaIDs(m, &ids)
-	ids = uniqueMediaIDs(ids)
-	sort.Strings(ids)
-	if len(ids) == 0 {
+	mediaIDs := make([]string, 0)
+	collectResourceIDs(m, "mediaid", mediaIDTextRE, &mediaIDs)
+	mediaIDs = uniqueResourceIDs(mediaIDs)
+	sort.Strings(mediaIDs)
+	fileIDs := make([]string, 0)
+	collectResourceIDs(m, "fileid", fileIDTextRE, &fileIDs)
+	fileIDs = uniqueResourceIDs(fileIDs)
+	sort.Strings(fileIDs)
+	if len(mediaIDs) == 0 && len(fileIDs) == 0 {
 		return nil
 	}

@@ -234,8 +238,8 @@ func Resources(m map[string]any) []map[string]any {
 		conversationID = ""
 	}

-	out := make([]map[string]any, 0, len(ids))
-	for _, id := range ids {
+	out := make([]map[string]any, 0, len(mediaIDs)+len(fileIDs))
+	for _, id := range mediaIDs {
 		arguments := map[string]any{
 			"type":        "mediaId",
 			"resource-id": id,
@@ -262,36 +266,94 @@ func Resources(m map[string]any) []map[string]any {
 			},
 		})
 	}
+	for _, id := range fileIDs {
+		out = append(out, map[string]any{
+			"type":       "fileId",
+			"resourceId": id,
+			"download": map[string]any{
+				"shortcut": "+messages-resource-download",
+				"arguments": map[string]any{
+					"type":        "fileId",
+					"resource-id": id,
+				},
+				"ready":   true,
+				"missing": []string{},
+			},
+		})
+	}
 	return out
 }

-var mediaIDTextRE = regexp.MustCompile(`(?i)media[_-]?id\s*[:=]\s*["']?([^"'\s)\]}>,]+)`)
+// ResourcesDeep returns resources from a message and each nested quoted,
+// replied-to or forwarded message. Every nested resource is projected from the
+// child message that owns it, so its download arguments never reuse the parent
+// message ID. A missing child conversation ID inherits the enclosing
+// conversation because quoted and forwarded records often omit that duplicate
+// field.
+func ResourcesDeep(m map[string]any) []map[string]any {
+	return resourcesDeep(m, "", 0)
+}

-func collectMediaIDs(value any, out *[]string) {
+const maxResourceMessageDepth = 32
+
+func resourcesDeep(m map[string]any, inheritedConversationID string, depth int) []map[string]any {
+	if m == nil || depth > maxResourceMessageDepth {
+		return nil
+	}
+	conversationID := strings.TrimSpace(fmt.Sprint(ConversationID(m)))
+	if conversationID == "" || conversationID == "<nil>" {
+		conversationID = inheritedConversationID
+	}
+	owned := m
+	if ConversationID(m) == nil && conversationID != "" {
+		owned = make(map[string]any, len(m)+1)
+		for key, value := range m {
+			owned[key] = value
+		}
+		owned["openConversationId"] = conversationID
+	}
+	out := append([]map[string]any(nil), Resources(owned)...)
+	if depth == maxResourceMessageDepth {
+		return out
+	}
+	for _, child := range nestedMessageChildren(m) {
+		out = append(out, resourcesDeep(child, conversationID, depth+1)...)
+	}
+	return out
+}
+
+var mediaIDTextRE = regexp.MustCompile(`(?i)\bmedia[_-]?id\s*[:=]\s*["']?([^"'\s)\]}>,]+)`)
+var fileIDTextRE = regexp.MustCompile(`(?i)\bfile[_-]?id\s*[:=]\s*["']?([^"'\s)\]}>,]+)`)
+
+func collectResourceIDs(value any, targetKey string, textPattern *regexp.Regexp, out *[]string) {
 	switch typed := value.(type) {
 	case map[string]any:
 		resourceType := strings.TrimSpace(fmt.Sprint(firstMessageValue(typed, "resourceType", "resource_type")))
 		for key, child := range typed {
-			normalizedKey := strings.ToLower(strings.NewReplacer("_", "", "-", "").Replace(key))
-			if normalizedKey == "mediaid" || (normalizedKey == "resourceid" && strings.EqualFold(resourceType, "mediaId")) {
-				if id := mediaIDScalar(child); id != "" {
+			normalizedKey := normalizeMessageKey(key)
+			if normalizedKey == targetKey ||
+				(normalizedKey == "resourceid" && strings.EqualFold(resourceType, targetKey)) {
+				if id := resourceIDScalar(child); id != "" {
 					*out = append(*out, id)
 				}
 			}
-			collectMediaIDs(child, out)
+			if isNestedMessageBoundaryKey(normalizedKey) {
+				continue
+			}
+			collectResourceIDs(child, targetKey, textPattern, out)
 		}
 	case []any:
 		for _, child := range typed {
-			collectMediaIDs(child, out)
+			collectResourceIDs(child, targetKey, textPattern, out)
 		}
 	case []map[string]any:
 		for _, child := range typed {
-			collectMediaIDs(child, out)
+			collectResourceIDs(child, targetKey, textPattern, out)
 		}
 	case string:
-		for _, match := range mediaIDTextRE.FindAllStringSubmatch(typed, -1) {
+		for _, match := range textPattern.FindAllStringSubmatch(typed, -1) {
 			if len(match) > 1 {
-				if id := mediaIDScalar(match[1]); id != "" {
+				if id := resourceIDScalar(match[1]); id != "" {
 					*out = append(*out, id)
 				}
 			}
@@ -300,13 +362,81 @@ func collectMediaIDs(value any, out *[]string) {
 		if strings.HasPrefix(trimmed, "{") || strings.HasPrefix(trimmed, "[") {
 			var decoded any
 			if json.Unmarshal([]byte(trimmed), &decoded) == nil {
-				collectMediaIDs(decoded, out)
+				collectResourceIDs(decoded, targetKey, textPattern, out)
 			}
 		}
 	}
 }

-func mediaIDScalar(value any) string {
+func normalizeMessageKey(key string) string {
+	return strings.ToLower(strings.NewReplacer("_", "", "-", "").Replace(key))
+}
+
+func isNestedMessageBoundaryKey(key string) bool {
+	switch key {
+	case "quotedmessage", "replymessage", "quoted", "replytomessage",
+		"forwardmessages", "forwardedmessages", "forwarded":
+		return true
+	default:
+		return false
+	}
+}
+
+func nestedMessageMaps(value any) []map[string]any {
+	switch typed := value.(type) {
+	case map[string]any:
+		return []map[string]any{typed}
+	case []map[string]any:
+		return typed
+	case []any:
+		out := make([]map[string]any, 0, len(typed))
+		for _, item := range typed {
+			if child, ok := item.(map[string]any); ok {
+				out = append(out, child)
+			}
+		}
+		return out
+	case string:
+		var decoded any
+		if json.Unmarshal([]byte(strings.TrimSpace(typed)), &decoded) == nil {
+			return nestedMessageMaps(decoded)
+		}
+	}
+	return nil
+}
+
+func nestedMessageChildren(value any) []map[string]any {
+	out := make([]map[string]any, 0)
+	switch typed := value.(type) {
+	case map[string]any:
+		for key, child := range typed {
+			if isNestedMessageBoundaryKey(normalizeMessageKey(key)) {
+				out = append(out, nestedMessageMaps(child)...)
+				continue
+			}
+			out = append(out, nestedMessageChildren(child)...)
+		}
+	case []any:
+		for _, child := range typed {
+			out = append(out, nestedMessageChildren(child)...)
+		}
+	case []map[string]any:
+		for _, child := range typed {
+			out = append(out, nestedMessageChildren(child)...)
+		}
+	case string:
+		trimmed := strings.TrimSpace(typed)
+		if strings.HasPrefix(trimmed, "{") || strings.HasPrefix(trimmed, "[") {
+			var decoded any
+			if json.Unmarshal([]byte(trimmed), &decoded) == nil {
+				out = append(out, nestedMessageChildren(decoded)...)
+			}
+		}
+	}
+	return out
+}
+
+func resourceIDScalar(value any) string {
 	text, ok := value.(string)
 	if !ok {
 		return ""
@@ -314,7 +444,7 @@ func mediaIDScalar(value any) string {
 	return strings.Trim(strings.TrimSpace(text), `"'`)
 }

-func uniqueMediaIDs(values []string) []string {
+func uniqueResourceIDs(values []string) []string {
 	out := make([]string, 0, len(values))
 	seen := map[string]bool{}
 	for _, value := range values {
@@ -189,6 +189,111 @@ func TestQuotedMessageIsBoundedAndSemantic(t *testing.T) {
 	}
 }

+func TestCrossPlatformCoverageResourcesRespectNestedMessageOwnership(t *testing.T) {
+	message := map[string]any{
+		"openMessageId":      "parent",
+		"openConversationId": "cid-parent",
+		"content":            map[string]any{"mediaId": "media-parent"},
+		"quotedMessage": map[string]any{
+			"openMessageId": "quoted",
+			"content":       map[string]any{"mediaId": "media-quoted"},
+		},
+		"forwardMessages": []any{
+			map[string]any{
+				"openMessageId":      "forwarded",
+				"openConversationId": "cid-forwarded",
+				"content":            map[string]any{"mediaId": "media-forwarded"},
+			},
+		},
+	}
+	owned := Resources(message)
+	if len(owned) != 1 || owned[0]["resourceId"] != "media-parent" {
+		t.Fatalf("parent resources crossed message boundary: %#v", owned)
+	}
+
+	deep := ResourcesDeep(message)
+	if len(deep) != 3 {
+		t.Fatalf("deep resources = %#v", deep)
+	}
+	argumentsByResource := map[string]map[string]any{}
+	for _, resource := range deep {
+		download := resource["download"].(map[string]any)
+		argumentsByResource[resource["resourceId"].(string)] = download["arguments"].(map[string]any)
+	}
+	for resourceID, want := range map[string][2]string{
+		"media-parent":    {"parent", "cid-parent"},
+		"media-quoted":    {"quoted", "cid-parent"},
+		"media-forwarded": {"forwarded", "cid-forwarded"},
+	} {
+		arguments := argumentsByResource[resourceID]
+		if arguments["message-id"] != want[0] ||
+			arguments["open-conversation-id"] != want[1] {
+			t.Errorf("%s arguments = %#v, want message=%q conversation=%q",
+				resourceID, arguments, want[0], want[1])
+		}
+	}
+}
+
+func TestCrossPlatformCoverageResourceBoundaryHelpers(t *testing.T) {
+	encoded := map[string]any{
+		"openMessageId":      "parent",
+		"openConversationId": "cid",
+		"content":            `{"quotedMessage":{"openMessageId":"encoded-child","mediaId":"nested"}}`,
+	}
+	if got := Resources(encoded); got != nil {
+		t.Fatalf("encoded nested resource bound to parent: %#v", got)
+	}
+	if got := ResourcesDeep(encoded); len(got) != 1 {
+		t.Fatalf("encoded nested resources = %#v", got)
+	} else {
+		arguments := got[0]["download"].(map[string]any)["arguments"].(map[string]any)
+		if arguments["message-id"] != "encoded-child" ||
+			arguments["open-conversation-id"] != "cid" {
+			t.Fatalf("encoded child arguments = %#v", arguments)
+		}
+	}
+	if got := resourcesDeep(map[string]any{"mediaId": "x"}, "", maxResourceMessageDepth+1); got != nil {
+		t.Fatalf("over-depth resources = %#v", got)
+	}
+	if got := resourcesDeep(
+		map[string]any{"mediaId": "x"},
+		"",
+		maxResourceMessageDepth,
+	); len(got) != 1 {
+		t.Fatalf("max-depth owned resources = %#v", got)
+	}
+	if got := nestedMessageMaps([]map[string]any{{"id": "a"}}); len(got) != 1 {
+		t.Fatalf("map slice = %#v", got)
+	}
+	if got := nestedMessageMaps(`[{"id":"a"}]`); len(got) != 1 {
+		t.Fatalf("encoded message list = %#v", got)
+	}
+	if got := nestedMessageMaps([]any{"bad", map[string]any{"id": "a"}}); len(got) != 1 {
+		t.Fatalf("mixed message list = %#v", got)
+	}
+	if got := nestedMessageMaps("{"); got != nil {
+		t.Fatalf("invalid encoded messages = %#v", got)
+	}
+	if got := nestedMessageChildren([]map[string]any{
+		{"content": "plain"},
+		{"content": `{"forwardedMessages":[{"openMessageId":"m"}]}`},
+	}); len(got) != 1 {
+		t.Fatalf("nested message children = %#v", got)
+	}
+	if got := nestedMessageChildren([]any{
+		"plain",
+		map[string]any{"quoted": map[string]any{"openMessageId": "m"}},
+	}); len(got) != 1 {
+		t.Fatalf("mixed nested message children = %#v", got)
+	}
+	if got := nestedMessageChildren("{"); len(got) != 0 {
+		t.Fatalf("invalid nested children = %#v", got)
+	}
+	if isNestedMessageBoundaryKey("content") {
+		t.Fatal("ordinary content treated as a message boundary")
+	}
+}
+
 func TestUpdateTimeOmitsUneditedEcho(t *testing.T) {
 	if got := UpdateTime(map[string]any{
 		"createTime": "2026-07-19 13:37:03",
@@ -326,6 +431,17 @@ func TestResourcesReportsMissingDownloadContext(t *testing.T) {
 	}
 }

+func TestResourcesTextMediaIDRequiresWordBoundary(t *testing.T) {
+	resources := Resources(map[string]any{
+		"openMessageId":      "msg-1",
+		"openConversationId": "cid-1",
+		"content":            `notmediaId=@false mediaId=@real`,
+	})
+	if len(resources) != 1 || resources[0]["resourceId"] != "@real" {
+		t.Fatalf("resources = %#v, want only the bounded mediaId", resources)
+	}
+}
+
 func TestForwarded(t *testing.T) {
 	var project func(m map[string]any) map[string]any
 	project = func(m map[string]any) map[string]any {
@@ -29,14 +29,27 @@ func TestCrossPlatformCoverageQuotedResourcesAndScalarVariants(t *testing.T) {
 	resources := Resources(map[string]any{
 		"attachments": []map[string]any{
 			{"resourceType": "mediaId", "resourceId": "@file-a"},
-			{"mediaId": 42},
+			{"resourceType": "fileId", "resourceId": "drive-file"},
+			{"mediaId": 42, "fileId": 42},
 		},
+		"content": `[文件] report.txt fileId: drive-file`,
 	})
-	if len(resources) != 1 || resources[0]["resourceId"] != "@file-a" {
+	if len(resources) != 2 ||
+		resources[0]["resourceId"] != "@file-a" ||
+		resources[1]["resourceId"] != "drive-file" ||
+		resources[1]["type"] != "fileId" {
 		t.Fatalf("resources = %#v", resources)
 	}
-	if got := mediaIDScalar(42); got != "" {
-		t.Fatalf("non-string media ID = %q", got)
+	fileDownload := resources[1]["download"].(map[string]any)
+	fileArguments := fileDownload["arguments"].(map[string]any)
+	if fileDownload["ready"] != true ||
+		fileDownload["shortcut"] != "+messages-resource-download" ||
+		fileArguments["type"] != "fileId" ||
+		fileArguments["resource-id"] != "drive-file" {
+		t.Fatalf("file download = %#v", fileDownload)
+	}
+	if got := resourceIDScalar(42); got != "" {
+		t.Fatalf("non-string resource ID = %q", got)
 	}
 }

@@ -172,15 +172,7 @@ func dryRunWriteError(product, tool string) error {
 }

 func looksReadTool(tool string) bool {
-	tool = strings.TrimSpace(strings.ToLower(tool))
-	for _, prefix := range []string{
-		"get_", "list_", "query_", "search_", "unread_",
-	} {
-		if strings.HasPrefix(tool, prefix) {
-			return true
-		}
-	}
-	return false
+	return helpers.IsReadToolName(tool)
 }

 func (rt *RuntimeContext) callMCPData(product, tool string, params map[string]any) (map[string]any, error) {
@@ -469,10 +461,11 @@ func validateConstraints(rt *RuntimeContext, s Shortcut) error {
 // --dry-run is set. Read-only shortcuts never prompt. Returns false when the
 // user declines.
 func confirmRisk(rt *RuntimeContext, s Shortcut) bool {
-	if s.risk() == RiskRead || rt.DryRun() || rt.Yes() {
+	risk := s.risk()
+	if risk == RiskRead || rt.DryRun() || rt.Yes() {
 		return true
 	}
-	fmt.Fprintf(rt.cmd.ErrOrStderr(), "即将执行 %s %s（%s），确认继续？(yes/no): ", s.Service, s.Command, s.risk())
+	fmt.Fprintf(rt.cmd.ErrOrStderr(), "即将执行 %s %s（%s），确认继续？(yes/no): ", s.Service, s.Command, risk)
 	reader := bufio.NewReader(os.Stdin)
 	answer, _ := reader.ReadString('\n')
 	answer = strings.TrimSpace(strings.ToLower(answer))
@@ -435,7 +435,7 @@
    },
    "+messages-send": {
      "disposition": "semantic_adapter",
-      "semantic_delta": "用统一 identity 参数路由 current-user、bot、webhook 文本/Markdown 发送；按身份校验目标与凭据，幂等键只在真实支持的 user 分支开放，媒体上传仍诚实留在 native leaf。",
+      "semantic_delta": "用统一 identity 参数路由 current-user、bot、webhook 发送；current-user 支持文本、Markdown、mediaId 图片、安全相对路径本地文件上传、userId 姓名解析与幂等键，bot/webhook 仍只暴露下层真实支持的文本/Markdown 能力。",
      "risk": "write",
      "public": true,
      "reviewed": true
@@ -487,7 +487,7 @@
    },
    "+messages-mget": {
      "disposition": "semantic_adapter",
-      "semantic_delta": "按最多 50 个消息 ID 批量读取并输出稳定消息投影、reaction 与 resourceRefs；可用 --download-resources 复用 HTTPS、相对路径、无覆盖和原子落盘防护，逐资源返回下载失败 ledger。",
+      "semantic_delta": "按最多 50 个消息 ID 批量读取并输出稳定消息投影、reaction 与 resourceRefs；可用 --download-resources 统一下载 mediaId 与 fileId，复用受信任下载域、相对路径、无覆盖和原子落盘防护，对重复资源去重并逐资源返回下载失败 ledger；安全本地下载沿用 read/not_required 契约，不产生非交互确认盲区。",
      "risk": "read",
      "public": true,
      "reviewed": true
@@ -542,8 +542,8 @@
      "reviewed": true
    },
    "+messages-send-card": {
-      "disposition": "schema_leaf",
-      "semantic_delta": "创建流式卡片是一对一写入；完整卡片生命周期需由 send/update leaf 明确编排。",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "既可只创建流式卡片，也可在一次调用中创建、提取 bizId、写入内容并设置流式状态；dry-run 输出两步执行计划，更新失败时保留已创建的 bizId。",
      "risk": "write",
      "public": true,
      "reviewed": true
@@ -564,7 +564,7 @@
    },
    "+messages-resource-download": {
      "disposition": "primary_smart",
-      "semantic_delta": "把临时资源 URL 解析、工作目录内安全路径、默认不覆盖、临时文件下载和原子发布封装为结构化单步结果。",
+      "semantic_delta": "统一承接消息 mediaId 与钉盘 fileId：分别复用 IM 临时资源 URL 和 drive.download_file，只允许钉钉/OSS HTTPS 下载域且重定向复验并隔离跨域凭据，再通过工作目录内安全路径、默认不覆盖、临时文件下载和原子发布输出结构化结果。",
      "risk": "read",
      "public": true,
      "reviewed": true
@@ -627,7 +627,7 @@
    },
    "+at-me": {
      "disposition": "primary_smart",
-      "semantic_delta": "自动构造时间窗，分页拉取跨会话 @我 消息，并保留身份、引用、reaction、resourceRefs 与完整性。",
+      "semantic_delta": "自动构造时间窗，分页拉取跨会话 @我 消息，并保留身份、引用、reaction、resourceRefs 与完整性；可选对资源去重后安全落盘并返回逐项失败 ledger。",
      "risk": "read",
      "public": true,
      "reviewed": true
@@ -641,7 +641,7 @@
    },
    "+chat-messages": {
      "disposition": "primary_smart",
-      "semantic_delta": "统一群聊与两类单聊目标，输出稳定消息身份、引用、reaction、resourceRefs、时间边界翻页和可读正文。",
+      "semantic_delta": "统一群聊与两类单聊目标；省略时间时自动以当前时间向前读取最近消息，并输出稳定消息身份、引用、reaction、resourceRefs、时间边界翻页和可读正文；可选对列表内资源去重后安全落盘并返回逐项失败 ledger。",
      "risk": "read",
      "public": true,
      "reviewed": true
@@ -677,7 +677,7 @@
    },
    "+search-msg": {
      "disposition": "primary_smart",
-      "semantic_delta": "统一关键词、发送者、@对象、会话、消息类型和机器人来源过滤；支持精确时间窗、page-all、50 条一组 mget 富化，并以 failure ledger 显式报告截断或富化失败。",
+      "semantic_delta": "统一关键词、发送者、@对象、会话、消息类型和机器人来源过滤；展开下层按会话分组的 conversationMessagesList，支持精确时间窗、page-all、50 条一组 mget 富化，可选安全下载命中消息资源，并以 failure ledger 显式报告截断、富化或下载失败。",
      "risk": "read",
      "public": true,
      "reviewed": true
@@ -691,7 +691,7 @@
    },
    "+thread-replies": {
      "disposition": "primary_smart",
-      "semantic_delta": "接受消息列表直接返回的 threadId（兼容 topicId），拉取回复并输出稳定身份、引用、reaction、resourceRefs、可读正文和时间边界分页。",
+      "semantic_delta": "接受消息列表直接返回的 threadId（兼容 topicId），拉取回复并输出稳定身份、引用、reaction、resourceRefs、可读正文和时间边界分页；可选对回复资源去重后安全落盘并返回逐项失败 ledger。",
      "risk": "read",
      "public": true,
      "reviewed": true
@@ -15,6 +15,7 @@ package shortcut

 import (
 	"bytes"
+	"os"
 	"strings"
 	"testing"

@@ -40,6 +41,42 @@ func TestCrossPlatformCoverageRiskDefaultsToRead(t *testing.T) {
 	}
 }

+func TestCrossPlatformCoverageConfirmRiskPromptsForStaticWrite(t *testing.T) {
+	cmd := &cobra.Command{}
+	var stderr bytes.Buffer
+	cmd.SetErr(&stderr)
+	rt := &RuntimeContext{cmd: cmd}
+	s := Shortcut{
+		Service: "chat",
+		Command: "+messages-send",
+		Risk:    RiskWrite,
+	}
+
+	reader, writer, err := os.Pipe()
+	if err != nil {
+		t.Fatal(err)
+	}
+	previousStdin := os.Stdin
+	os.Stdin = reader
+	t.Cleanup(func() {
+		os.Stdin = previousStdin
+		_ = reader.Close()
+		_ = writer.Close()
+	})
+	if _, err := writer.WriteString("yes\n"); err != nil {
+		t.Fatal(err)
+	}
+	if err := writer.Close(); err != nil {
+		t.Fatal(err)
+	}
+	if !confirmRisk(rt, s) {
+		t.Fatal("static write risk was not confirmed")
+	}
+	if got := stderr.String(); !strings.Contains(got, "chat +messages-send（write）") {
+		t.Fatalf("confirmation prompt = %q", got)
+	}
+}
+
 func TestCrossPlatformCoverageMountRegistersFlagsAndUse(t *testing.T) {
 	s := Shortcut{
 		Service:     "contact",
@@ -19,6 +19,7 @@ import (
 	"time"

 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut"
+	chatshortcut "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut/chat"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut/chatmsg"
 )

@@ -37,9 +38,9 @@ import (
 //     so it honours --format/--jq/--fields. When the response carries no
 //     recognisable message list we fall back to printing the raw payload.
 //
-// This replaces manually working out the millisecond time window and copying the
-// list-mentions incantation. Read-only: it only searches and reshapes, never
-// sends, recalls or marks anything.
+// This replaces manually working out the millisecond time window and copying
+// the list-mentions incantation. The default path only searches and reshapes;
+// --download-resources additionally writes resource files locally.
 //
 //	dws chat +at-me
 //	dws chat +at-me --days 3
@@ -51,18 +52,20 @@ var AtMe = shortcut.Shortcut{
 	Intent: "当你想快速看回最近谁在群里或单聊里 @了你、但不想手动把起止时间换算成毫秒、也不想记 list-mentions 的一堆参数时使用；" +
 		"内部按本地时区算出「最近 N 天」（默认 7 天，可用 --days 调整回溯天数）的时间窗，搜索这段时间内 @我 的消息，" +
 		"再在本地把每条消息投影成发送人、时间、内容、所在会话四个关键字段。" +
-		"这是纯只读操作，只做搜索与本地投影，不会发送、撤回或标记任何消息。",
+		"默认只读且不会发送、撤回或标记任何消息；--download-resources 使用工作目录内安全路径、默认不覆盖和原子落盘，按既有安全下载约定无需交互确认。",
 	Risk: shortcut.RiskRead,
-	Flags: []shortcut.Flag{
+	Flags: append([]shortcut.Flag{
 		{Name: "days", Type: shortcut.FlagInt, Desc: "回溯天数（可选，默认 7）", Default: "7", Required: false},
 		{Name: "limit", Type: shortcut.FlagInt, Desc: "每页返回数量（默认 50）", Default: "50"},
 		{Name: "cursor", Type: shortcut.FlagString, Desc: "分页游标，翻页传上次的 nextCursor", Default: "0"},
 		{Name: "no-reactions", Type: shortcut.FlagBool, Desc: "不输出消息 reaction（默认输出）"},
-	},
+	}, chatshortcut.MessageResourceDownloadFlags()...),
+	Constraints: chatshortcut.MessageResourceDownloadConstraints(),
 	Tips: []string{
 		`dws chat +at-me`,
 		`dws chat +at-me --days 3`,
 	},
+	Validate: chatshortcut.ValidateMessageResourceDownload,
 	Execute: func(rt *shortcut.RuntimeContext) error {
 		// Step 1 — look-back window [now-Nd, now] in epoch millis. days defaults
 		// to 7; guard against non-positive overrides so the window stays sane.
@@ -99,6 +102,9 @@ var AtMe = shortcut.Shortcut{
 		}
 		payload := map[string]any{"messages": results}
 		chatmsg.ApplyPagination(payload, data)
+		if rt.Bool("download-resources") {
+			payload["resourceDownloads"] = chatshortcut.DownloadMessageResources(rt, items, "")
+		}
 		return rt.Output(payload)
 	},
 }
@@ -233,7 +239,7 @@ func atMeProjectWithReactions(m map[string]any, includeReactions bool) map[strin
 	if quoted := chatmsg.QuotedMessage(m); len(quoted) > 0 {
 		row["quotedMessage"] = quoted
 	}
-	if resources := chatmsg.Resources(m); len(resources) > 0 {
+	if resources := chatmsg.ResourcesDeep(m); len(resources) > 0 {
 		row["resourceRefs"] = resources
 	}
 	projectForwarded := func(item map[string]any) map[string]any {
@@ -15,11 +15,19 @@ package smart

 import (
 	"strings"
+	"time"

 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut"
+	chatshortcut "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut/chat"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut/chatmsg"
 )

+var dingTalkMessageLocation = time.FixedZone("CST", 8*60*60)
+
+func formatDingTalkMessageBoundary(now time.Time) string {
+	return now.In(dingTalkMessageLocation).Format("2006-01-02 15:04:05")
+}
+
 // ChatMessages: fetch the message list of one conversation (group OR single
 // chat) and print a clean projected list (speaker / text / time) instead of a
 // raw dump.
@@ -35,8 +43,8 @@ import (
 //     aliases and one level of nesting;
 //  3. print via rt.Output as {messages, count} so it honours --format/--jq/--fields.
 //
-// Read-only: it only reads a conversation's messages and reshapes them locally,
-// never posts or mutates anything.
+// The default path only reads and reshapes conversation messages;
+// --download-resources additionally writes resource files locally.
 //
 //	dws chat +chat-messages --group <openconversation_id> --time "2025-03-01 00:00:00"
 //	dws chat +chat-messages --user <userId> --time "2025-03-01 00:00:00" --limit 50
@@ -47,39 +55,43 @@ var ChatMessages = shortcut.Shortcut{
 	Description: "拉取某个会话（群聊或单聊）的消息列表并投影出发言人/文本/时间",
 	Intent: "当你想快速看某个会话里的消息（谁在什么时间说了什么），而不想拿到一大坨原始消息字段时使用；" +
 		"群聊传 --group（群会话 ID，openConversationId），单聊传 --user（对方 userId），两者互斥且必须二选一。" +
-		"可选 --time 指定起始时间、--limit 指定每页条数、--direction newer/older 控制时间方向（newer 从给定时间往现在拉，older 往以前拉）。" +
+		"省略 --time 时默认从当前时间向前读取最近消息；也可指定时间边界并用 --direction newer/older 控制方向。" +
 		"内部据此调用群聊或单聊的消息列表接口，再在本地投影出每条消息的发言人、文本和时间。" +
-		"这是纯只读操作，只做拉取与本地投影，不会发送或修改任何消息。",
+		"默认只读且不会发送或修改任何消息；--download-resources 使用工作目录内安全路径、默认不覆盖和原子落盘，按既有安全下载约定无需交互确认。",
 	Risk: shortcut.RiskRead,
-	Flags: []shortcut.Flag{
+	Flags: append([]shortcut.Flag{
 		{Name: "group", Type: shortcut.FlagString, Desc: "群会话 ID（openConversationId），与 --user 互斥"},
 		{Name: "conversation-id", Type: shortcut.FlagString, Desc: "--group 的别名", Hidden: true},
 		{Name: "id", Type: shortcut.FlagString, Desc: "--group 的别名", Hidden: true},
 		{Name: "user", Type: shortcut.FlagString, Desc: "单聊对方的 userId，与 --group 互斥"},
 		{Name: "open-dingtalk-id", Type: shortcut.FlagString, Desc: "单聊对方的 openDingTalkId，与 --group/--user 互斥"},
-		{Name: "time", Type: shortcut.FlagString, Desc: "起始时间，如 \"2025-03-01 00:00:00\"（可选）"},
+		{Name: "time", Type: shortcut.FlagString, Desc: "时间边界，如 \"2025-03-01 00:00:00\"；省略时从当前时间向前读取最近消息"},
 		{Name: "limit", Type: shortcut.FlagInt, Desc: "每页拉取的消息条数（可选）"},
 		{Name: "size", Type: shortcut.FlagInt, Desc: "--limit 的旧版别名", Hidden: true},
-		{Name: "direction", Type: shortcut.FlagString, Desc: "时间方向 newer/older（可选，newer 从给定时间往现在拉，older 往以前拉）"},
+		{Name: "direction", Type: shortcut.FlagString, Enum: []string{"newer", "older"}, Desc: "时间方向 newer/older；省略时为 older，从时间边界向前读取"},
 		{Name: "no-reactions", Type: shortcut.FlagBool, Desc: "不输出消息 reaction（默认输出）"},
-	},
-	Constraints: []shortcut.Constraint{
+	}, chatshortcut.MessageResourceDownloadFlags()...),
+	Constraints: append([]shortcut.Constraint{
 		{Kind: shortcut.ConstraintExactlyOne, Flags: []string{"group", "conversation-id", "id", "user", "open-dingtalk-id"}},
-	},
+	}, chatshortcut.MessageResourceDownloadConstraints()...),
 	Tips: []string{
 		`dws chat +chat-messages --group <openconversation_id> --time "2025-03-01 00:00:00"`,
 		`dws chat +chat-messages --user <userId> --time "2025-03-01 00:00:00" --limit 50`,
 		`dws chat +chat-messages --group <openconversation_id> --direction older`,
 	},
+	Validate: chatshortcut.ValidateMessageResourceDownload,
 	Execute: func(rt *shortcut.RuntimeContext) error {
 		// Step 1 — build params and pick the right tool. Param keys
 		// (openconversation_id / userId / time / forward / limit) match the MCP server
 		// schema for group and direct message listing.
 		var tool string
 		params := map[string]any{}
+		fallbackConversationID := ""

 		if rt.Changed("time") && rt.Str("time") != "" {
 			params["time"] = rt.Str("time")
+		} else {
+			params["time"] = formatDingTalkMessageBoundary(time.Now())
 		}
 		if limit := rt.IntFirst("limit", "size"); limit > 0 {
 			params["limit"] = limit
@@ -94,11 +106,14 @@ var ChatMessages = shortcut.Shortcut{
 			case "older":
 				params["forward"] = false
 			}
+		} else {
+			params["forward"] = false
 		}

 		if group := rt.StrFirst("group", "conversation-id", "id"); group != "" {
 			tool = "list_conversation_message_v2"
 			params["openconversation_id"] = group
+			fallbackConversationID = group
 		} else if openID := strings.TrimSpace(rt.Str("open-dingtalk-id")); openID != "" {
 			tool = "list_individual_chat_message"
 			params["openDingTalkId"] = openID
@@ -126,6 +141,9 @@ var ChatMessages = shortcut.Shortcut{
 		}
 		direction := strings.TrimSpace(strings.ToLower(rt.Str("direction")))
 		chatmsg.ApplyMessagePagination(payload, data, items, direction)
+		if rt.Bool("download-resources") {
+			payload["resourceDownloads"] = chatshortcut.DownloadMessageResources(rt, items, fallbackConversationID)
+		}
 		return rt.Output(payload)
 	},
 }
@@ -198,7 +216,7 @@ func projectChatMessageWithReactions(m map[string]any, includeReactions bool) ma
 	if quoted := chatmsg.QuotedMessage(m); len(quoted) > 0 {
 		row["quotedMessage"] = quoted
 	}
-	if resources := chatmsg.Resources(m); len(resources) > 0 {
+	if resources := chatmsg.ResourcesDeep(m); len(resources) > 0 {
 		row["resourceRefs"] = resources
 	}
 	projectForwarded := func(item map[string]any) map[string]any {
@@ -67,7 +67,7 @@ func TestCrossPlatformCoverageRichMessageProjections(t *testing.T) {
 		"emotionReplyList":   []any{map[string]any{"emojiName": "赞", "replyCount": 1}},
 		"quotedMessage": map[string]any{
 			"openMessageId": "quoted",
-			"content":       "quoted body",
+			"content":       `{"mediaId":"@quoted-image"}`,
 		},
 	}
 	for name, row := range map[string]map[string]any{
@@ -80,6 +80,16 @@ func TestCrossPlatformCoverageRichMessageProjections(t *testing.T) {
 				t.Errorf("%s projection missing %s: %#v", name, key, row)
 			}
 		}
+		resources := row["resourceRefs"].([]map[string]any)
+		if len(resources) != 2 {
+			t.Fatalf("%s projected resources = %#v", name, resources)
+		}
+		quotedArgs := resources[1]["download"].(map[string]any)["arguments"].(map[string]any)
+		if resources[1]["resourceId"] != "@quoted-image" ||
+			quotedArgs["message-id"] != "quoted" ||
+			quotedArgs["open-conversation-id"] != "cid" {
+			t.Fatalf("%s quoted resource context = %#v", name, resources[1])
+		}
 	}
 }

@@ -89,7 +99,7 @@ func TestCrossPlatformCoverageChatMessagesOpenIDRoute(t *testing.T) {
 	}}
 	helpers.InitDeps(caller)
 	root := newPlatformCoverageRoot()
-	root.SetArgs([]string{"chat", "+chat-messages", "--open-dingtalk-id", "D-user", "--limit", "1"})
+	root.SetArgs([]string{"chat", "+chat-messages", "--open-dingtalk-id", "D-user", "--limit", "1", "--yes"})
 	if err := root.Execute(); err != nil {
 		t.Fatal(err)
 	}
@@ -202,7 +212,7 @@ func TestCrossPlatformCoverageSearchValidationAndTimeErrors(t *testing.T) {
 	for _, tail := range cases {
 		helpers.InitDeps(&smartCoverageCaller{})
 		root := newPlatformCoverageRoot()
-		root.SetArgs(append([]string{"chat", "+search-msg"}, tail...))
+		root.SetArgs(append([]string{"chat", "+search-msg", "--yes"}, tail...))
 		if err := root.Execute(); err == nil {
 			t.Errorf("invalid search args succeeded: %v", tail)
 		}
@@ -247,7 +257,7 @@ func TestCrossPlatformCoverageSearchPaginationFailureModes(t *testing.T) {
 			root := newPlatformCoverageRoot()
 			var output bytes.Buffer
 			root.SetOut(&output)
-			root.SetArgs(append([]string{"chat", "+search-msg"}, tc.args...))
+			root.SetArgs(append([]string{"chat", "+search-msg", "--yes"}, tc.args...))
 			err := root.Execute()
 			if (err != nil) != tc.wantError {
 				t.Fatalf("error = %v, wantError=%v", err, tc.wantError)
@@ -0,0 +1,217 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+
+package smart
+
+import (
+	"bytes"
+	"encoding/json"
+	"testing"
+	"time"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/helpers"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut"
+)
+
+func TestCrossPlatformCoverageSafeResourceQueryDownloadsStayReadOnly(t *testing.T) {
+	for _, command := range []shortcut.Shortcut{AtMe, ChatMessages, SearchMsg, ThreadReplies} {
+		if command.Risk != shortcut.RiskRead {
+			t.Errorf("%s risk contract = %q", command.Command, command.Risk)
+		}
+	}
+}
+
+func TestCrossPlatformCoverageMessageReadShortcutsPublishResourceDownloadPlans(t *testing.T) {
+	message := `{"openMessageId":"msg","openConversationId":"cid","content":"{\"mediaId\":\"@image\"}","quotedMessage":{"openMessageId":"quoted","content":"{\"fileId\":\"@quoted-file\"}"}}`
+	tests := []struct {
+		name      string
+		tool      string
+		response  string
+		args      []string
+		resultKey string
+	}{
+		{
+			name:      "chat messages",
+			tool:      "chat/list_conversation_message_v2",
+			response:  `{"result":{"messages":[` + message + `]}}`,
+			args:      []string{"chat", "+chat-messages", "--group", "cid"},
+			resultKey: "messages",
+		},
+		{
+			name:      "search",
+			tool:      "im/search_messages",
+			response:  `{"result":{"messages":[` + message + `],"hasMore":false}}`,
+			args:      []string{"chat", "+search-msg", "--query", "x", "--no-enrich"},
+			resultKey: "messages",
+		},
+		{
+			name:      "at me",
+			tool:      "chat/search_at_me_message",
+			response:  `{"result":{"conversationMessagesList":[{"openConversationId":"cid","messages":[` + message + `]}]}}`,
+			args:      []string{"chat", "+at-me"},
+			resultKey: "messages",
+		},
+		{
+			name:      "thread replies",
+			tool:      "chat/list_topic_replies",
+			response:  `{"result":{"messages":[` + message + `]}}`,
+			args:      []string{"chat", "+thread-replies", "--group", "cid", "--thread-id", "thread"},
+			resultKey: "replies",
+		},
+	}
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			caller := &smartCoverageCaller{responses: map[string][]string{
+				tc.tool: {tc.response},
+			}}
+			helpers.InitDeps(caller)
+			root := newPlatformCoverageRoot()
+			var output bytes.Buffer
+			root.SetOut(&output)
+			args := append([]string{}, tc.args...)
+			args = append(args, "--download-resources", "--output-dir", "./downloads", "--dry-run")
+			root.SetArgs(args)
+			if err := root.Execute(); err != nil {
+				t.Fatal(err)
+			}
+			if caller.counts[tc.tool] != 1 {
+				t.Fatalf("lower calls = %#v", caller.counts)
+			}
+			var payload map[string]any
+			if err := json.Unmarshal(output.Bytes(), &payload); err != nil {
+				t.Fatalf("decode output: %v\n%s", err, output.String())
+			}
+			rows, ok := payload[tc.resultKey].([]any)
+			if !ok || len(rows) != 1 {
+				t.Fatalf("payload missing %s: %#v", tc.resultKey, payload)
+			}
+			row, _ := rows[0].(map[string]any)
+			resources, _ := row["resourceRefs"].([]any)
+			if len(resources) != 2 {
+				t.Fatalf("visible resources = %#v", resources)
+			}
+			ledger, _ := payload["resourceDownloads"].(map[string]any)
+			if ledger["dryRun"] != true ||
+				ledger["discoveredCount"] != float64(2) ||
+				ledger["requestedCount"] != float64(2) {
+				t.Fatalf("resource plan = %#v", ledger)
+			}
+		})
+	}
+}
+
+func TestCrossPlatformCoverageMessageReadShortcutResourceOutputValidation(t *testing.T) {
+	for _, args := range [][]string{
+		{"chat", "+chat-messages", "--group", "cid"},
+		{"chat", "+search-msg", "--query", "x", "--no-enrich"},
+		{"chat", "+at-me"},
+		{"chat", "+thread-replies", "--group", "cid", "--thread-id", "thread"},
+	} {
+		helpers.InitDeps(&smartCoverageCaller{})
+		root := newPlatformCoverageRoot()
+		root.SetArgs(append(args, "--download-resources", "--output-dir", "../outside", "--yes"))
+		if err := root.Execute(); err == nil {
+			t.Fatalf("unsafe output accepted: %v", args)
+		}
+	}
+}
+
+func TestCrossPlatformCoverageChatMessagesDefaultsToRecentHistory(t *testing.T) {
+	caller := &platformCoverageCaller{}
+	helpers.InitDeps(caller)
+	root := newPlatformCoverageRoot()
+	before := time.Now().Add(-2 * time.Second)
+	root.SetArgs([]string{"chat", "+chat-messages", "--group", "cid", "--limit", "5"})
+	if err := root.Execute(); err != nil {
+		t.Fatal(err)
+	}
+	after := time.Now().Add(2 * time.Second)
+	if len(caller.calls) != 1 {
+		t.Fatalf("calls = %#v", caller.calls)
+	}
+	call := caller.calls[0]
+	if call.args["forward"] != false {
+		t.Fatalf("default forward = %#v, want false", call.args["forward"])
+	}
+	boundary, err := time.ParseInLocation(
+		"2006-01-02 15:04:05",
+		call.args["time"].(string),
+		dingTalkMessageLocation,
+	)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if boundary.Before(before) || boundary.After(after) {
+		t.Fatalf("default time = %s, want current boundary", boundary)
+	}
+}
+
+func TestFormatDingTalkMessageBoundaryDoesNotDependOnProcessTimezone(t *testing.T) {
+	now := time.Date(2026, time.July, 29, 1, 2, 3, 0, time.UTC)
+	if got := formatDingTalkMessageBoundary(now); got != "2026-07-29 09:02:03" {
+		t.Fatalf("UTC process boundary = %q, want DingTalk UTC+8 wall time", got)
+	}
+}
+
+func TestCrossPlatformCoverageChatMessagesPreservesExplicitTime(t *testing.T) {
+	caller := &platformCoverageCaller{}
+	helpers.InitDeps(caller)
+	root := newPlatformCoverageRoot()
+	root.SetArgs([]string{
+		"chat", "+chat-messages",
+		"--group", "cid",
+		"--time", "2026-07-01 12:34:56",
+		"--yes",
+	})
+	if err := root.Execute(); err != nil {
+		t.Fatal(err)
+	}
+	if len(caller.calls) != 1 ||
+		caller.calls[0].args["time"] != "2026-07-01 12:34:56" {
+		t.Fatalf("explicit time call = %#v", caller.calls)
+	}
+}
+
+func TestCrossPlatformCoverageSearchMsgFlattensRealGroupedResponse(t *testing.T) {
+	original := map[string]any{"openMessageId": "m1"}
+	items := searchMsgItems(map[string]any{
+		"result": map[string]any{
+			"conversationMessagesList": []any{
+				"invalid-group",
+				map[string]any{"messages": "invalid"},
+				map[string]any{
+					"openConversationId": "cid",
+					"title":              "会话",
+					"singleChat":         true,
+					"messages": []any{
+						"invalid-message",
+						original,
+						map[string]any{
+							"openMessageId":      "m2",
+							"openConversationId": "own-cid",
+							"conversationTitle":  "own-title",
+							"singleChat":         false,
+						},
+					},
+				},
+			},
+		},
+	})
+	if len(items) != 2 {
+		t.Fatalf("grouped items = %#v", items)
+	}
+	if items[0]["openConversationId"] != "cid" || items[0]["conversationTitle"] != "会话" ||
+		items[0]["singleChat"] != true {
+		t.Fatalf("injected group context = %#v", items[0])
+	}
+	if items[1]["openConversationId"] != "own-cid" || items[1]["conversationTitle"] != "own-title" ||
+		items[1]["singleChat"] != false {
+		t.Fatalf("message context was overwritten: %#v", items[1])
+	}
+	if _, mutated := original["openConversationId"]; mutated {
+		t.Fatalf("source message mutated: %#v", original)
+	}
+	if searchMsgChildMap(map[string]any{"result": "invalid"}, "result") != nil {
+		t.Fatal("non-map child was accepted")
+	}
+}
@@ -21,6 +21,7 @@ import (

 	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut"
+	chatshortcut "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut/chat"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut/chatmsg"
 )

@@ -35,9 +36,10 @@ var SearchMsg = shortcut.Shortcut{
 	Product:     "im",
 	Description: "多维搜索消息，可全量翻页并批量富化详情",
 	Intent: "当你要按关键词、发送者、@对象、会话、消息类型或机器人来源组合搜索 IM 消息时使用；默认查询近 7 天，" +
-		"也可指定精确起止时间。--page-all 会连续拉取游标页，默认再按消息 ID 分批富化详情；任何续页或富化失败都会保留已取得结果并返回逐项失败 ledger，绝不把截断结果标成完整。",
+		"也可指定精确起止时间。--page-all 会连续拉取游标页，默认再按消息 ID 分批富化详情；任何续页或富化失败都会保留已取得结果并返回逐项失败 ledger，绝不把截断结果标成完整。" +
+		"--download-resources 使用工作目录内安全路径、默认不覆盖和原子落盘，按既有安全下载约定无需交互确认。",
 	Risk: shortcut.RiskRead,
-	Flags: []shortcut.Flag{
+	Flags: append([]shortcut.Flag{
 		{Name: "query", Type: shortcut.FlagString, Desc: "搜索关键词"},
 		{Name: "keyword", Type: shortcut.FlagString, Desc: "--query 的别名", Hidden: true},
 		{Name: "group", Type: shortcut.FlagString, Desc: "单个会话 openConversationId"},
@@ -65,17 +67,22 @@ var SearchMsg = shortcut.Shortcut{
 		{Name: "page-limit", Type: shortcut.FlagInt, Desc: "--page-all 的最大页数（1-40）", Default: "20"},
 		{Name: "no-enrich", Type: shortcut.FlagBool, Desc: "不再按消息 ID 批量查询完整详情"},
 		{Name: "no-reactions", Type: shortcut.FlagBool, Desc: "不输出命中消息的 reaction（默认输出）"},
-	},
-	Constraints: []shortcut.Constraint{
+	}, chatshortcut.MessageResourceDownloadFlags()...),
+	Constraints: append([]shortcut.Constraint{
 		{
-			Kind:        shortcut.ConstraintCustom,
-			Flags:       []string{"query", "group", "groups", "chat-id", "senders", "sender", "at-me", "is-at-me", "at-ids", "message-type", "only-robot", "conversation-type", "chat-type"},
+			Kind:        shortcut.ConstraintAtLeastOne,
+			Flags:       []string{"query", "keyword", "group", "conversation-id", "id", "groups", "chat-id", "senders", "sender", "at-me", "is-at-me", "at-ids", "message-type", "only-robot", "conversation-type", "chat-type"},
 			Description: "至少指定一个内容、身份、会话或消息类型过滤条件",
 		},
 		{
 			Kind:        shortcut.ConstraintCustom,
-			Flags:       []string{"start", "end", "days"},
-			Description: "--start 与 --end 必须同时指定；否则使用 --days 时间窗",
+			Flags:       []string{"start"},
+			Description: "需与 --end 一起传",
+		},
+		{
+			Kind:        shortcut.ConstraintCustom,
+			Flags:       []string{"end"},
+			Description: "需与 --start 一起传",
 		},
 		{Kind: shortcut.ConstraintMutuallyExclusive, Flags: []string{"groups", "chat-id"}},
 		{Kind: shortcut.ConstraintMutuallyExclusive, Flags: []string{"senders", "sender"}},
@@ -83,12 +90,12 @@ var SearchMsg = shortcut.Shortcut{
 		{Kind: shortcut.ConstraintMutuallyExclusive, Flags: []string{"conversation-type", "chat-type"}},
 		{Kind: shortcut.ConstraintMutuallyExclusive, Flags: []string{"limit", "page-size"}},
 		{Kind: shortcut.ConstraintMutuallyExclusive, Flags: []string{"cursor", "page-token"}},
-	},
+	}, chatshortcut.MessageResourceDownloadConstraints()...),
 	Tips: []string{
 		`dws chat +search-msg --group <openConversationId> --query "changefree"`,
 		`dws chat +search-msg --senders <openDingTalkId> --at-me --days 3 --page-all`,
 	},
-	Validate: validateSearchMsg,
+	Validate: validateSearchMsgWithResources,
 	Execute: func(rt *shortcut.RuntimeContext) error {
 		params, err := searchMsgParams(rt)
 		if err != nil {
@@ -200,10 +207,20 @@ var SearchMsg = shortcut.Shortcut{
 		if hasMore && nextCursor != "" && nextCursor != "<nil>" {
 			payload["nextCursor"] = nextCursor
 		}
+		if rt.Bool("download-resources") {
+			payload["resourceDownloads"] = chatshortcut.DownloadMessageResources(rt, messages, "")
+		}
 		return rt.Output(payload)
 	},
 }

+func validateSearchMsgWithResources(rt *shortcut.RuntimeContext) error {
+	if err := validateSearchMsg(rt); err != nil {
+		return err
+	}
+	return chatshortcut.ValidateMessageResourceDownload(rt)
+}
+
 func validateSearchMsg(rt *shortcut.RuntimeContext) error {
 	hasFilter := rt.StrFirst("query", "keyword", "group", "conversation-id", "id", "message-type", "conversation-type", "chat-type") != "" ||
 		len(rt.StrSlice("groups")) > 0 ||
@@ -392,6 +409,14 @@ func searchMsgItems(data map[string]any) []map[string]any {
 	if data == nil {
 		return nil
 	}
+	for _, root := range []map[string]any{data, searchMsgChildMap(data, "result")} {
+		if root == nil {
+			continue
+		}
+		if groups, ok := root["conversationMessagesList"].([]any); ok {
+			return searchMsgFlattenGroups(groups)
+		}
+	}
 	keys := []string{"list", "messages", "messageList", "items", "data", "records", "result"}
 	for _, key := range keys {
 		if arr, ok := data[key].([]any); ok {
@@ -408,6 +433,53 @@ func searchMsgItems(data map[string]any) []map[string]any {
 	return nil
 }

+func searchMsgChildMap(data map[string]any, key string) map[string]any {
+	if value, ok := data[key].(map[string]any); ok {
+		return value
+	}
+	return nil
+}
+
+func searchMsgFlattenGroups(groups []any) []map[string]any {
+	out := make([]map[string]any, 0)
+	for _, rawGroup := range groups {
+		group, ok := rawGroup.(map[string]any)
+		if !ok {
+			continue
+		}
+		messages, ok := group["messages"].([]any)
+		if !ok {
+			continue
+		}
+		conversationID := strings.TrimSpace(fmt.Sprint(group["openConversationId"]))
+		conversationTitle := strings.TrimSpace(fmt.Sprint(group["title"]))
+		singleChat, hasSingleChat := group["singleChat"]
+		for _, rawMessage := range messages {
+			message, ok := rawMessage.(map[string]any)
+			if !ok {
+				continue
+			}
+			item := make(map[string]any, len(message)+3)
+			for key, value := range message {
+				item[key] = value
+			}
+			if _, exists := item["openConversationId"]; !exists &&
+				conversationID != "" && conversationID != "<nil>" {
+				item["openConversationId"] = conversationID
+			}
+			if _, exists := item["conversationTitle"]; !exists &&
+				conversationTitle != "" && conversationTitle != "<nil>" {
+				item["conversationTitle"] = conversationTitle
+			}
+			if _, exists := item["singleChat"]; !exists && hasSingleChat {
+				item["singleChat"] = singleChat
+			}
+			out = append(out, item)
+		}
+	}
+	return out
+}
+
 func searchMsgToMaps(arr []any) []map[string]any {
 	out := make([]map[string]any, 0, len(arr))
 	for _, it := range arr {
@@ -453,7 +525,7 @@ func searchMsgProjectWithReactions(m map[string]any, includeReactions bool) map[
 	if quoted := chatmsg.QuotedMessage(m); len(quoted) > 0 {
 		row["quotedMessage"] = quoted
 	}
-	if resources := chatmsg.Resources(m); len(resources) > 0 {
+	if resources := chatmsg.ResourcesDeep(m); len(resources) > 0 {
 		row["resourceRefs"] = resources
 	}
 	projectForwarded := func(item map[string]any) map[string]any {
@@ -73,7 +73,7 @@ func executeSearchMsg(t *testing.T, caller *searchMsgExecutionCaller, args ...st
 	root := newPlatformCoverageRoot()
 	var output bytes.Buffer
 	root.SetOut(&output)
-	root.SetArgs(append([]string{"chat", "+search-msg"}, args...))
+	root.SetArgs(append([]string{"chat", "+search-msg", "--yes"}, args...))
 	if err := root.Execute(); err != nil {
 		t.Fatal(err)
 	}
@@ -15,6 +15,7 @@ package smart

 import (
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut"
+	chatshortcut "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut/chat"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut/chatmsg"
 )

@@ -29,8 +30,8 @@ import (
 //     project each reply to {sender, text, createTime} tolerating field aliases;
 //  3. print via rt.Output as {replies, count} so it honours --format/--jq/--fields.
 //
-// Read-only: it only reads a topic's replies and reshapes them locally, never
-// posts or mutates anything.
+// The default path only reads and reshapes topic replies;
+// --download-resources additionally writes resource files locally.
 //
 //	dws chat +thread-replies --group <openconversationId> --thread-id <threadId>
 var ThreadReplies = shortcut.Shortcut{
@@ -41,27 +42,28 @@ var ThreadReplies = shortcut.Shortcut{
 	Intent: "当你已经拿到某个群里一条「话题消息」的 threadId/topicId、想快速看这条话题下的全部回复（谁在什么时间回复了什么），" +
 		"而不想拿到一大坨原始消息字段时使用；内部按 --group（群会话 ID）和 --thread-id（兼容 --topic-id）拉取该话题的回复列表，" +
 		"可选 --time 指定起始时间、--limit 指定每页条数，再在本地投影出每条回复的发言人、文本和回复时间。" +
-		"这是纯只读操作，只做拉取与本地投影，不会发送或修改任何消息。",
+		"默认只读且不会发送或修改任何消息；--download-resources 使用工作目录内安全路径、默认不覆盖和原子落盘，按既有安全下载约定无需交互确认。",
 	Risk: shortcut.RiskRead,
-	Flags: []shortcut.Flag{
+	Flags: append([]shortcut.Flag{
 		{Name: "group", Type: shortcut.FlagString, Desc: "群会话 ID（openConversationId，必填）", Required: true},
 		{Name: "thread-id", Type: shortcut.FlagString, Desc: "话题/线程 ID（可直接使用消息列表返回的 threadId）"},
 		{Name: "topic-id", Type: shortcut.FlagString, Desc: "--thread-id 的兼容别名"},
 		{Name: "time", Type: shortcut.FlagString, Desc: "起始时间，如 \"2025-03-01 00:00:00\"（可选）"},
 		{Name: "limit", Type: shortcut.FlagInt, Desc: "每页拉取的回复条数（可选）"},
 		{Name: "no-reactions", Type: shortcut.FlagBool, Desc: "不输出回复 reaction（默认输出）"},
-	},
-	Constraints: []shortcut.Constraint{
+	}, chatshortcut.MessageResourceDownloadFlags()...),
+	Constraints: append([]shortcut.Constraint{
 		{
 			Kind:        shortcut.ConstraintExactlyOne,
 			Flags:       []string{"thread-id", "topic-id"},
 			Description: "--thread-id 与兼容参数 --topic-id 必须且只能指定一个",
 		},
-	},
+	}, chatshortcut.MessageResourceDownloadConstraints()...),
 	Tips: []string{
 		`dws chat +thread-replies --group <openconversationId> --thread-id <threadId>`,
 		`dws chat +thread-replies --group <openconversationId> --thread-id <threadId> --time "2025-03-01 00:00:00" --limit 20`,
 	},
+	Validate: chatshortcut.ValidateMessageResourceDownload,
 	Execute: func(rt *shortcut.RuntimeContext) error {
 		// Step 1 — fetch the topic replies. Param keys (openconversationId /
 		// topicId / startTime / pageSize) are copied verbatim from chat.go's
@@ -96,6 +98,9 @@ var ThreadReplies = shortcut.Shortcut{
 			"count":   len(results),
 		}
 		chatmsg.ApplyMessagePagination(payload, data, items, "older")
+		if rt.Bool("download-resources") {
+			payload["resourceDownloads"] = chatshortcut.DownloadMessageResources(rt, items, rt.Str("group"))
+		}
 		return rt.Output(payload)
 	},
 }
@@ -43,22 +43,22 @@ cli_version: ">=1.0.15"

 | 服务 | shortcut 数 | multi skill | 发现命令 |
 |---|---:|---|---|
-| `aitable` | 29 | `dingtalk-aitable` | `dws shortcut list --service aitable --format json` |
-| `attendance` | 19 | `dingtalk-misc` | `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` |
-| `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-misc` | `dws shortcut list --service ding --format json` |
-| `doc` | 17 | `dingtalk-doc` | `dws shortcut list --service doc --format json` |
-| `drive` | 7 | `dingtalk-drive` | `dws shortcut list --service drive --format json` |
-| `mail` | 10 | `dingtalk-mail` | `dws shortcut list --service mail --format json` |
-| `minutes` | 6 | `dingtalk-minutes` | `dws shortcut list --service minutes --format json` |
-| `oa` | 7 | `dingtalk-misc` | `dws shortcut list --service oa --format json` |
-| `report` | 2 | `dingtalk-misc` | `dws shortcut list --service report --format json` |
-| `sheet` | 2 | `dingtalk-misc` | `dws shortcut list --service sheet --format json` |
-| `todo` | 11 | `dingtalk-todo` | `dws shortcut list --service todo --format json` |
-| `wiki` | 1 | `dingtalk-wiki` | `dws shortcut list --service wiki --format json` |
+| `aitable` | 29 | `dingtalk-workspace` | `dws shortcut list --service aitable --format json` |
+| `attendance` | 19 | `dingtalk-workspace` | `dws shortcut list --service attendance --format json` |
+| `calendar` | 20 | `dingtalk-workspace` | `dws shortcut list --service calendar --format json` |
+| `chat` | 97 | `dingtalk-workspace` | `dws shortcut list --service chat --format json` |
+| `contact` | 14 | `dingtalk-workspace` | `dws shortcut list --service contact --format json` |
+| `devapp` | 19 | `dingtalk-workspace` | `dws shortcut list --service devapp --format json` |
+| `ding` | 4 | `dingtalk-workspace` | `dws shortcut list --service ding --format json` |
+| `doc` | 17 | `dingtalk-workspace` | `dws shortcut list --service doc --format json` |
+| `drive` | 7 | `dingtalk-workspace` | `dws shortcut list --service drive --format json` |
+| `mail` | 10 | `dingtalk-workspace` | `dws shortcut list --service mail --format json` |
+| `minutes` | 6 | `dingtalk-workspace` | `dws shortcut list --service minutes --format json` |
+| `oa` | 7 | `dingtalk-workspace` | `dws shortcut list --service oa --format json` |
+| `report` | 2 | `dingtalk-workspace` | `dws shortcut list --service report --format json` |
+| `sheet` | 2 | `dingtalk-workspace` | `dws shortcut list --service sheet --format json` |
+| `todo` | 11 | `dingtalk-workspace` | `dws shortcut list --service todo --format json` |
+| `wiki` | 1 | `dingtalk-workspace` | `dws shortcut list --service wiki --format json` |
 <!-- VISIBLE_SHORTCUTS_OVERVIEW_END -->

 ## 多组织 / 多账号
@@ -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 message send-by-bot` | `chat message send` | 需要机器人身份定期发送 |
-| "给张三发一条机器人单聊消息" | 机器人单聊 | `chat message send-by-bot --users` | — | 机器人批量单聊，先查 userId |
-| "CPU 超过 90% 自动告警" | Webhook 告警 | `chat message send-by-webhook` | `chat message send-by-bot` | 系统告警场景，需自定义 Webhook |
+| "通知群里的人都来开会" | 个人身份群发 | `chat +messages-send --as user` | `chat message send` | 统一入口校验身份、目标、内容和幂等键 |
+| "让机器人每天推送日报" | 机器人定时推送 | `chat +messages-send --as bot` | `chat message send-by-bot` | 需要 robotCode；定时调度由外层工作流负责 |
+| "给张三发一条机器人单聊消息" | 机器人单聊 | `chat +messages-send --as bot --users` | `chat message send-by-bot --users` | 机器人批量单聊，先查 userId |
+| "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 维度） |
-| "按发送者搜索/指定多个群搜索/多维度搜消息" | 多维度搜索消息 | `chat message search-advanced`（首选） | `chat message search` | 推荐首选，支持关键词、发送者、@我、多个会话等维度组合 |
+| "搜一下消息里的changefree链接" | 消息搜索 | `chat +search-msg` | `chat message search-advanced` | Shortcut 支持关键词、发送者、会话、消息类型、时间窗、全量翻页和批量富化 |
+| "按发送者搜索/指定多个群搜索/多维度搜消息" | 多维度搜索消息 | `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,29 +269,37 @@ alidocs 链接表面长得一样（`https://alidocs.dingtalk.com/i/nodes/{id}`

 ### 5. chat 内部 — 消息发送与撤回

-**用 `chat message send` 的场景**：
+**优先用 `chat +messages-send` 的场景**：
 - "帮我在群里发个消息提醒大家" — **个人身份**发群消息
 - "发个单聊消息给某人" — 个人身份发单聊：
  - 已有 userId 时直接使用 `--user`；已有 openDingTalkId 时使用 `--open-dingtalk-id`
-  - 纯文本/Markdown 单聊传 `--user` 时直接走 userId 发送能力，不需要先手动查询 openDingTalkId
-  - 富媒体消息（image/file）单聊优先使用 `--open-dingtalk-id`；传 `--user` 时 CLI 会尝试解析为 openDingTalkId 后发送
+  - `+messages-send --user` 对所有内容类型都会通过通讯录关键词搜索并按 userId 精确匹配 openDingTalkId；无需手动预查，`--dry-run` 也会执行这次只读解析
+  - 已持有 openDingTalkId 时优先使用显式 `--open-dingtalk-id`，避免额外解析
 - "发本地图片/文件/语音/视频到群里" — `dws chat message send ... --msg-type file --file-path <本地路径>`，CLI 内部自动上传并发送；png/jpg/pdf/mp4/zip 等任意扩展名都走这条，接收方看到的是可下载的文件附件。图片不会内联渲染，也不会生成 mediaId
 - "用已有 mediaId 发内联图片" — 仅当上游已经提供有效 mediaId 时，使用 `dws chat message send ... --msg-type image --media-id <mediaId>`；DWS CLI 不能把本地图片转换成 mediaId
 - "发图片+文字说明" — 不要硬塞进一条命令；先发图片/文件消息再补一条 `--text "..."` 即可

 ```bash
-dws chat message send --group <openConversationId> --msg-type file --file-path ./screenshot.png --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 --chat-id <openConversationId> --msg-type file --file ./screenshot.png --idempotency-key <key> --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。
-> 富媒体消息单聊优先使用 `--open-dingtalk-id`；传 `--user` 时 CLI 会尝试解析为 openDingTalkId 后发送。
+> ❌ 反模式：先把本地文件转换成 mediaId，或先经钉盘上传再拼装聊天消息。本地图片/文件一律用 `--msg-type file --file` 直发；`--msg-type image --media-id` 只接受上游已经提供的有效 mediaId。
+> 单聊已持有 openDingTalkId 时优先使用 `--open-dingtalk-id`；传 `--user` 时 CLI 会通过通讯录关键词搜索做 userId 精确匹配后发送。

-**用 `chat message send-by-bot` 的场景**：
+`+messages-send` 的 @ 占位符按身份自动规范化并补齐：user 使用 `<@id>` / `<@all>`；bot/webhook 使用 `@id` / `@手机号` / `@all`。声明 `--at-*` / `--at-all` 即可，不要再手工拼 `@10`。
+
+**用 `chat +messages-send-card` 的场景**：
+- 群聊流式卡片使用 `--group <openConversationId>`。
+- 单聊已有 userId 时使用 `--receiver <userId>`，CLI 始终通过通讯录关键词搜索并按 userId 精确匹配 openDingTalkId；即使 userId 以 D/d 开头也不会猜测类型，`--dry-run` 也会执行该解析。
+- 单聊已有 openDingTalkId 时必须显式使用 `--receiver-open-dingtalk-id <openDingTalkId>`，避免与 userId 混淆。
+- `--group`、`--receiver`、`--receiver-open-dingtalk-id` 严格三选一；传 `--content` 可在同一次调用中创建并结束卡片。
+
+**用 `chat +messages-send --as bot` 的场景**：
 - "让机器人在群里发一条通知" — **机器人身份**发消息
 - "给张三发一条机器人单聊消息" — 机器人单聊

-**用 `chat message send-by-webhook` 的场景**：
+**用 `chat +messages-send --as webhook` 的场景**：
 - "通过 Webhook 发告警到群里" — 自定义机器人 Webhook
 - 用户有 Webhook Token

@@ -302,16 +312,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 与 `+messages-resource-download` 都沿用安全本地下载的 `read/not_required` 契约，不应添加 `--yes` 或触发交互确认。输出只允许工作目录内相对路径、默认不覆盖并原子落盘；需要覆盖时必须由用户显式传 `--overwrite`。

 **不支持的场景**：
 - "撤回我刚发的消息"（但不知道消息 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`，仅在不适用时降级到原子命令。

 ---

@@ -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 与 `+messages-resource-download` 都沿用安全本地下载的 `read/not_required` 契约，不应添加 `--yes` 或触发交互确认。下载只允许工作目录内相对路径、默认不覆盖并原子落盘；需要覆盖时必须由用户显式传 `--overwrite`。
+- 下载器仅接受经审查的钉钉与公网 OSS HTTPS 地址并逐跳校验重定向；跨主机时不会转发下层提供的请求头。新官方域名被拒绝时记录错误中的 host 供审查，不要放宽为任意 HTTPS。
+
 ### group (群组管理)

 #### 创建群 — 当前登录用户自动成为群主
@@ -1,6 +1,6 @@
 ---
 name: dingtalk-chat
-description: 钉钉群聊与消息。Use when 用户提到 发消息/单聊/群聊/建群/拉人进群/改群名/搜索群/群成员管理/@消息/撤回消息/机器人群发/Webhook通知/发图片或文件到群/标记未读/清除红点/置顶消息/全部群列表。不做紧急 DING/短信/电话（走 dingtalk-misc）、邮件（走 dingtalk-mail）、班级群（走 dingtalk-misc）。命令前缀：dws chat。
+description: 钉钉群聊与消息。Use when 用户提到 发消息/编辑或撤回消息/单聊/群聊/建群/普通群升级外部群/群昵称/会话分组/群成员管理/@消息/搜索聊天记录/话题回复/收藏消息/机器人群发/Webhook通知/发送或下载消息图片与文件。不做紧急 DING/短信/电话（走 dingtalk-misc）、邮件（走 dingtalk-mail）、班级群（走 dingtalk-misc）。命令前缀：dws chat。
 metadata:
  cli_version: ">=0.2.14"
  category: product
@@ -28,58 +28,126 @@ metadata:
 | `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` | read | 拉取某个会话（群聊或单聊）的消息列表并投影出发言人/文本/时间 |
 | `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-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` | read | 安全下载消息资源（图片/视频/语音/文件）到工作目录内，无需交互确认 |
+| `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` | read | 多维搜索消息，可全量翻页并批量富化详情 |
 | `dws chat +send-to-group` | write | 按群名直接给群发消息（自动搜群解析 openConversationId） |
+| `dws chat +thread-replies` | read | 拉取某条话题消息的全部回复并投影出发言人/文本/时间 |
 | `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`。
+- 上述五个查询 Shortcut 与 `+messages-resource-download` 都沿用安全本地下载的 `read/not_required` 契约，不应添加 `--yes` 或触发交互确认。下载只允许工作目录内相对路径、默认不覆盖并原子落盘；需要覆盖时必须由用户显式传 `--overwrite`。
+- `+messages-send` 会按身份规范化 @ 占位符：user 使用 `<@id>` / `<@all>`，bot/webhook 使用 `@id` / `@手机号` / `@all`；只需声明 `--at-*` / `--at-all`，缺失占位符会自动补齐。
+- `+messages-send --as user --user <userId>` 会通过通讯录关键词搜索并按 userId 精确匹配 openDingTalkId，所有内容类型与 `--dry-run` 都使用同一只读解析链路；已有 openDingTalkId 时直接传 `--open-dingtalk-id`。
+- 流式卡片优先用 `+messages-send-card`：群聊传 `--group`，单聊 userId 传 `--receiver` 并由 CLI 通过通讯录关键词搜索做 userId 精确匹配，已有 openDingTalkId 则必须显式传 `--receiver-open-dingtalk-id`；三者严格三选一，禁止根据首字母猜身份类型。
+
 ## 意图表

 | 用户说 | 命令 |
 |--------|------|
-| "发消息给张三" | `dws chat message send --open-dingtalk-id <id> --text "<内容>"` |
-| "发到XX群" | `dws chat search --query "<群名>"` → `dws chat message send --group <openConversationId> --text "<内容>"` |
+| "发消息给张三" | `dws chat +messages-send --as user --open-dingtalk-id <id> --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 group rename` / `dws chat group members remove` |
-| "@我消息" | `dws chat message list-mentions` |
-| "查群聊记录" | `dws chat search --query "<群名>"` → `dws chat message list --group <openConversationId> --time "<yyyy-MM-dd HH:mm:ss>" --direction older` |
-| "用机器人发消息" | `dws chat message send-by-bot --robot-code <code> --group <id>` |
-| "Webhook 推一条" | `dws chat message send-by-webhook --token <token>` |
+| "改群名" / "踢人" | `dws chat group rename` / `dws chat group members remove --yes`（踢人不可逆，先确认目标） |
+| "@我消息" | `dws chat +at-me` |
+| "查群聊记录" | `dws chat +chat-messages --group <openConversationId>` |
+| "收藏/取消收藏这条消息" | `dws chat +flag-create` / `dws chat +flag-cancel` |
+| "查看我收藏的消息" | `dws chat +flag-list` |
+| "用机器人发消息" | `dws chat +messages-send --as bot --robot-code <code> --chat-id <id> --text "<内容>"` |
+| "Webhook 推一条" | `dws chat +messages-send --as webhook --webhook-token <token> --text "<内容>"` |
+| "发送流式卡片" | `dws chat +messages-send-card --group <openConversationId> --content "<内容>"`；单聊 userId 改用 `--receiver`，openDingTalkId 改用 `--receiver-open-dingtalk-id` |
 | "撤回消息" | `dws chat message recall --conversation-id <openConversationId> --msg-id <openMessageId>` |
 | "标记未读 / 清除红点 / 全部已读" | `dws chat mark-unread` / `dws chat clear-red-point` / `dws chat clear-all-red-point` |
 | "置顶某条消息 / 取消消息置顶" | `dws chat message set-top-msg` / `dws chat message unset-top-msg` |
@@ -4,6 +4,26 @@

 > 命令别名：`dws im` 等价于 `dws chat`。

+## 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` 只暴露下层真实支持的身份能力，并自动规范化、补齐对应身份的 @ 占位符。
+- `+search-msg --page-all` 连续翻页并默认按消息 ID 批量富化；续页或富化失败会保留已取得结果并返回逐项失败 ledger。
+- 五个查询 Shortcut 的 `--download-resources` 沿用安全本地下载的 `read/not_required` 契约，不应添加 `--yes` 或触发交互确认。引用、回复、合并转发中的资源使用 `resourceRefs` 自带的子消息 `messageId`；仅当子消息缺会话 ID 时继承父消息 `openConversationId`。
+- `+messages-resource-download` 同样无需交互确认，但只允许工作目录内相对路径、默认拒绝覆盖并原子落盘；需要覆盖时必须由用户显式传 `--overwrite`。
+- 下载器只接受经审查的钉钉与公网 OSS HTTPS 地址并逐跳校验重定向；跨主机时不会转发下层提供的请求头。
+
 ## 适用范围与安全硬约束

 `chat` 覆盖钉钉会话、群聊、群成员、会话消息、机器人消息、Webhook、会话状态和群身份管理。
@@ -29,6 +29,9 @@ skill 作为入口进行二级路由。
 - 命令或参数不确定时，先运行最接近层级的 `dws <path> --help`；禁止把自然语言
  同义词直接拼成命令。
 - 后续步骤使用的 ID 必须来自前一步真实返回；多人同名、多目标或类型不明时先消歧。
+- 多账号场景只传组织时，使用该组织唯一 `isOrgCurrent=true` 的默认账号；多账号组织
+  没有默认账号时先让用户指定账号，禁止选择第一项、最近登录或最近使用账号。账号
+  选择与跨组织规则详见 `../dingtalk-profile/SKILL.md`。
 - 不输出、转述或记录 token、refresh token、appSecret 等凭据。宿主已注入认证时
  不要求用户重新提供凭据。
 - 写入操作必须符合用户明确意图。删除、审批决策及其他不可逆/高影响操作，先展示
@@ -288,8 +288,8 @@ alidocs 链接表面长得一样（`https://alidocs.dingtalk.com/i/nodes/{id}`
 - "帮我在群里发个消息提醒大家" — **个人身份**发群消息
 - "发个单聊消息给某人" — 个人身份发单聊：
  - 已有 userId 时直接使用 `--user`；已有 openDingTalkId 时使用 `--open-dingtalk-id`
-  - 纯文本/Markdown 单聊传 `--user` 时直接走 userId 发送能力，不需要先手动查询 openDingTalkId
-  - 富媒体消息（image/file）单聊优先使用 `--open-dingtalk-id`；传 `--user` 时 CLI 会尝试解析为 openDingTalkId 后发送
+  - `+messages-send --user` 对所有内容类型都会通过通讯录关键词搜索并按 userId 精确匹配 openDingTalkId；无需手动预查，`--dry-run` 也会执行这次只读解析
+  - 已持有 openDingTalkId 时优先使用显式 `--open-dingtalk-id`，避免额外解析
 - "发张图片/截图/语音/视频/文件到群里" / "发张图给某某" — **统一一条命令**：`dws chat message send ... --msg-type file --file-path <本地路径>`，CLI 内部自动上传并发送，**任意扩展名（png/jpg/pdf/mp4/zip…）都走这条**
 - "发图片+文字说明" — 不要硬塞进一条命令；先发文件消息再补一条 `--text "..."` 即可

@@ -299,7 +299,13 @@ dws chat message send --open-dingtalk-id <openDingTalkId> --msg-type file --file
 ```

 > ❌ 反模式：调 `dt_media_upload` / `extract_media_id.py` / `drive upload` / `drive download` 等前置工具再 `--msg-type image --media-id`。这是**旧链路**，仅当上游已持有 mediaId 才用；新场景一律 `--file-path` 直发，避免长链路与“空白图”现象。
-> 富媒体消息单聊优先使用 `--open-dingtalk-id`；传 `--user` 时 CLI 会尝试解析为 openDingTalkId 后发送。
+> 单聊已持有 openDingTalkId 时优先使用 `--open-dingtalk-id`；传 `--user` 时 CLI 会通过通讯录关键词搜索做 userId 精确匹配后发送。
+
+**用 `chat +messages-send-card` 的场景**：
+- 群聊流式卡片使用 `--group <openConversationId>`。
+- 单聊已有 userId 时使用 `--receiver <userId>`，CLI 始终通过通讯录关键词搜索并按 userId 精确匹配 openDingTalkId；即使 userId 以 D/d 开头也不会猜测类型，`--dry-run` 也会执行该解析。
+- 单聊已有 openDingTalkId 时必须显式使用 `--receiver-open-dingtalk-id <openDingTalkId>`，避免与 userId 混淆。
+- `--group`、`--receiver`、`--receiver-open-dingtalk-id` 严格三选一；传 `--content` 可在同一次调用中创建并结束卡片。

 - "发送位置/坐标/地址到群里" / "发个位置给某某" — `dws chat message send ... --msg-type location --latitude <纬度> --longitude <经度> --location-name <地址名称> --map-thumbnail-url @mediaId`；地图缩略图需先通过 `dt_media_upload` 上传获取 mediaId
Author	SHA1	Message	Date
chichuan	9dbbd64f3c	Merge branch 'main' into codex/im-shortcut-gap-fill	2026-07-30 11:31:19 +08:00
github-actions[bot]	7ba12a8e4c	chore: update formula for v1.0.55 [skip ci]	2026-07-30 03:11:41 +00:00
chichuan	82d02096f7	Merge pull request #833 from DingTalk-Real-AI/codex/changelog-v1.0.55-promote-beta.8 docs(release): promote v1.0.55-beta.8 baseline	2026-07-30 11:00:51 +08:00
Dennis	41372b0597	Merge remote-tracking branch 'origin/main' into codex/im-shortcut-gap-fill	2026-07-30 10:32:58 +08:00
chichuan	ad08b6b499	docs(release): promote v1.0.55-beta.8	2026-07-30 10:32:20 +08:00
Dennis	cffc48406c	fix(im): resolve direct recipients via contact search	2026-07-30 10:29:39 +08:00
github-actions[bot]	250aab3ef1	chore: update beta formula for v1.0.55-beta.8 [skip ci]	2026-07-30 02:28:33 +00:00
chichuan	e36b6dc049	Merge pull request #832 from DingTalk-Real-AI/codex/changelog-v1.0.55-beta.8 docs(release): add v1.0.55-beta.8 notes	2026-07-30 10:19:15 +08:00
Dennis	f9e3476d42	Merge remote-tracking branch 'origin/main' into codex/im-shortcut-gap-fill	2026-07-30 10:02:34 +08:00
chichuan	d9d62fb2f7	docs(release): add v1.0.55-beta.8 notes	2026-07-30 09:55:16 +08:00
github-actions[bot]	f9f61a4cc6	Merge pull request #825 from DingTalk-Real-AI/codex/changelog-v1.0.55 docs(release): add v1.0.55 stable notes	2026-07-30 09:39:02 +08:00
Dennis	2b48f27a4b	fix(im): harden shortcut review follow-ups	2026-07-29 23:35:52 +08:00
Dennis	bf79a67efe	fix(im): close shortcut review gaps	2026-07-29 21:25:24 +08:00
chichuan	8d22cd553a	docs(release): add v1.0.55 stable notes	2026-07-29 20:42:19 +08:00
Dennis	95d262bbb2	Merge remote-tracking branch 'origin/main' into codex/im-shortcut-gap-fill	2026-07-29 19:32:18 +08:00
Dennis	d5c260c7c0	fix(im): address shortcut review regressions	2026-07-29 19:31:48 +08:00
github-actions[bot]	4f31863aae	chore: update beta formula for v1.0.55-beta.7 [skip ci]	2026-07-29 10:19:40 +00:00
chichuan	6de2bf1518	docs(release): 合入 beta.7 发布说明（风险等级：低）发布模块：CHANGELOG。补充 v1.0.55-beta.7 的完整变更说明，并保留失败 beta.6 的审计记录。风险等级：低。	2026-07-29 18:09:24 +08:00
Dennis	9c297d0520	Merge remote-tracking branch 'origin/main' into codex/im-shortcut-gap-fill	2026-07-29 18:02:49 +08:00
chichuan	78b724480e	docs(release): 补充 beta.7 完整发布说明（风险等级：低）	2026-07-29 18:02:40 +08:00
Dennis	37230d2d4d	chore(schema): refresh shortcut skill source hashes	2026-07-29 18:01:54 +08:00
github-actions[bot]	4724c30f4b	Merge pull request #821 from typefield/agent/restore-shared-account-rule fix(skills): restore multi-account safety rule in dws-shared SKILL.md	2026-07-29 17:56:16 +08:00
Dennis	fde6b59074	Merge remote-tracking branch 'origin/main' into codex/im-shortcut-gap-fill # Conflicts: # internal/app/schema_shortcut_contract_test.go # internal/cli/schema_agent_metadata/index.json # internal/cli/schema_agent_metadata_audit.json # internal/cli/schema_catalog/catalog.json # internal/cli/schema_command_registry/products/chat.json # internal/cli/schema_hints/runtime-surface-completeness.json # skills/multi/dingtalk-chat/SKILL.md # skills/multi/dingtalk-chat/references/chat.md	2026-07-29 17:51:27 +08:00
玉澜	76b9f1536a	test(app): pin multi-account safety rule in embedded dws-shared skill Replace the CI classifier change with a real PR-level regression contract: materialize the embedded multi skill source and assert dws-shared/SKILL.md keeps the 禁止选择第一项、最近登录或最近使用账号 rule that the MultiSkill e2e release gate requires. The new test file also makes the revision full-suite so all quality gates run on this PR.	2026-07-29 17:42:04 +08:00
玉澜	809b9b3570	ci: classify skills/ changes as docs-only for fast path Skill markdown files are agent documentation embedded at build time; they carry no Go code changes. Without this classification a one-line SKILL.md edit triggers the full -race test suite on internal/app and reverse dependencies, which exceeds the 8m job timeout and fails CI deterministically.	2026-07-29 17:36:56 +08:00
玉澜	0be5b73518	fix(skills): restore multi-account safety rule in dws-shared SKILL.md Commit `dc20ddec` dropped the 禁止选择第一项、最近登录或最近使用账号 rule from dws-shared/SKILL.md during the multi-skill refactor while the MultiSkill e2e contract still asserts it there, blocking the v1.0.55-beta.6 release run. Restore the rule as a mandatory-contract bullet pointing at dingtalk-profile/SKILL.md for the full selection and cross-org rules.	2026-07-29 17:19:31 +08:00
wxianfeng	4567dd1cd6	fix(im): gate optional resource downloads at runtime	2026-07-29 15:33:01 +08:00
Dennis	75bb01bb64	docs(skill): align IM shortcut routing	2026-07-29 14:45:28 +08:00
Dennis	11a7ab8b7c	fix(im): harden shortcut downloads and message context	2026-07-29 14:20:39 +08:00
Dennis	41e0fb381a	feat(im): close shortcut capability gaps	2026-07-29 13:29:53 +08:00