Merge remote-tracking branch 'origin/main' into calendar_skill_opt1

# Conflicts:
#	skills/multi/dingtalk-calendar/SKILL.md
#	skills/multi/dingtalk-calendar/references/03-meeting.md
#	skills/multi/dingtalk-calendar/references/lite-recipes.md

.changes/released/1.0.59-beta.2/schema-catalog-json-projection.md

@@ -0,0 +1,8 @@
+---
+category: Changed
+---
+
+- **Faster Schema Catalog assembly** — projects typed values into payload JSON
+  without re-running a validation scan over documents `json.Marshal` has just
+  produced, cutting roughly a third of the projection work across the full tool
+  set. Untrusted JSON input keeps its existing validation.

.changes/released/1.0.59-beta.3/1006-aitable-pagination-minutes-unshare.md

@@ -0,0 +1,11 @@
+---
+category: Fixed
+---
+
+- **Aitable pagination and Minutes unshare verification** (#1006) — keeps
+  record queries on the service's 20-record page boundary so multi-page reads
+  and mutation readbacks no longer report false retryable failures, preserves
+  `totalCount` when supplied, validates `--dry-run` plans before transport,
+  follows active deletion readback continuations before proving absence, and
+  rejects Minutes unshare success until the listening note exists and the
+  service acknowledges the exact task and member targets.

.changes/released/1.0.59-beta.3/928-chat-bot-group-reply.md

@@ -0,0 +1,5 @@
+---
+category: Added
+---
+
+- **Robot group reference replies** (#928) — `chat message send-by-bot` supports paired `--reply` and `--ref-sender` flags for Markdown replies that quote an existing group message.

.changes/released/1.0.59-beta.3/960-doc-readback-verification.md

@@ -0,0 +1,5 @@
+---
+category: Fixed
+---
+
+- **Document write verification** (#960) — avoids false partial-success results when normalized Markdown, paginated blocks, inline images, or version reverts are confirmed by server readback. Document reverts and media inserts now require explicit readback evidence and report partial success when the server cannot prove the requested result.

.changes/released/1.0.59-beta.3/aitable-param-aliases.md

@@ -0,0 +1,5 @@
+---
+category: Changed
+---
+
+- **AI Table parameter aliases** — accepts reviewed equivalent spellings for Base, table, workflow, search, pagination, and description parameters while keeping role-changing or semantically ambiguous inputs blocked.

.changes/released/1.0.59-beta.3/aitable-record-stats.md

@@ -0,0 +1,9 @@
+---
+category: Added
+---
+
+- **AI Table server-side statistics** — adds `dws aitable record stats` for
+  ungrouped record-set metrics through `query_records_stats`, plus `dws aitable
+  record group-stats` for grouped, distinct, and advanced aggregation through
+  `query_stats`; both commands validate their JSON aggregation contracts before
+  dispatch.

.changes/released/1.0.59-beta.3/calendar-event-share-info.md

@@ -0,0 +1,5 @@
+---
+category: Added
+---
+
+- **Calendar event share-info** (#980) — adds `dws calendar event share-info` to fetch a calendar event's share info (title, organizer, location, join info) for sharing with others; supports `--calendar-id` and `--language`.

.changes/released/1.0.59-beta.3/calendar-todo-shortcut-alignment.md

@@ -0,0 +1,11 @@
+---
+category: Added
+---
+
+- **Calendar and To-do Shortcut workflows** — aligns 47 public task-oriented
+  entries with lark-cli where the DingTalk backend supports equivalent
+  semantics, rejects malformed or missing collections instead of returning
+  false empty success, preserves truthful pagination, and requires stable
+  identifiers plus read-back or explicit terminal receipts for writes. Adds
+  deterministic contract coverage, a PII-safe live E2E runner, and a sanitized
+  capability review with documented platform boundaries.

.changes/released/1.0.59-beta.3/chat-sender-identity-contract.md

@@ -0,0 +1,5 @@
+---
+category: Fixed
+---
+
+- **Chat sender identity guards** — preserves unverified mixed sender inputs after exact message `senderId` matches and aligns `--sender-query` Skill guidance with fail-closed Runtime behavior.

.changes/released/1.0.59-beta.3/doc-drive-description-scope.md

@@ -0,0 +1,5 @@
+---
+category: Changed
+---
+
+- **Doc/drive description scope** — restates the `dingtalk-doc` description as document-entity-and-content operations with an explicit exclusion list, and narrows `dingtalk-drive` to file-level management of DingTalk documents, so first-round Agent selection separates content work from file management without changing CLI behavior.

.changes/released/1.0.59-beta.3/doc-sheet-comment-lifecycle.md

@@ -0,0 +1,10 @@
+---
+category: Added
+---
+
+- **Doc and Sheet comment lifecycle commands** — adds `comment batch-query`,
+  `comment resolve`, `comment restore`, and the lightweight
+  `comment react-reply` to both `dws doc` and `dws sheet`. The two domains share
+  the same `doc-comment` MCP capabilities; batch queries preserve input order
+  for repeated `topicId:commentKey` references, while reaction replies require
+  DingTalk reaction names such as `憨笑` or `鼓掌` rather than raw Unicode emoji.

.changes/released/1.0.59-beta.3/sheet-source-range-dropdowns.md

@@ -0,0 +1,6 @@
+---
+category: Added
+---
+
+- **Sheet SourceRange dropdowns** — supports range-backed dropdowns across direct, cell, and batch write paths, with structured readback for valid and invalid references. Batch `set-dropdown` now rejects unsupported top-level `colors` / `source-colors`; Inline colors belong in `options[].color`, while SourceRange color writes remain unsupported.
+- **Sheet read completion metadata** — documents and preserves returned ranges, truncation reasons, and partial-read status for large range and CSV reads.

.changes/released/1.0.59-beta.3/windows-event-bus-lifecycle.md

@@ -0,0 +1,5 @@
+---
+category: Fixed
+---
+
+- **Windows event bus lifecycle** — start event consumers without unsupported inherited file descriptors, stop buses through local IPC with a termination fallback, and preserve subscription cleanup when startup fails.

.github/workflows/ci.yml

@@ -523,12 +523,22 @@ jobs:
     # shards at full-suite scope; release-scripts is included because its
     # dedicated job only runs at full-suite or release-sensitive scope, and
     # dropping it here would stop testing test/scripts changes entirely.
+    # internal/app is carried by one shard per bounded partition rather than a
+    # single app shard: the partitions used to run end to end inside one job,
+    # where the Schema partition alone owned most of the wall clock. The
+    # app-<partition> names are pinned to the helper's partition set by
+    # TestCIAppRacePartitionMatrixMatchesHelper, so a partition can never lose
+    # its job silently.
     timeout-minutes: 20
     strategy:
       fail-fast: false
       matrix:
         shard:
-          - app
+          - app-schema
+          - app-a-b
+          - app-c
+          - app-d-r
+          - app-s-z-example-fuzz
           - generators
           - helpers
           - cli
@@ -570,9 +580,16 @@ jobs:
           TEST_SHARD: ${{ matrix.shard }}
         run: |
           set -euo pipefail
+          # Every app partition shard tests the same single internal/app
+          # package, so the impacted-package query uses the base shard name and
+          # the partition only selects which tests run.
+          package_shard="$TEST_SHARD"
+          case "$TEST_SHARD" in
+            app-*) package_shard=app ;;
+          esac
           package_output="$(
             ./scripts/ci/changed-test-packages.sh \
-              list-shard "$TEST_SHARD" "$TEST_BASE_REF" "$TEST_HEAD_REF"
+              list-shard "$package_shard" "$TEST_BASE_REF" "$TEST_HEAD_REF"
           )"
           if [ -z "$package_output" ]; then
             echo "No buildable Go package in shard $TEST_SHARD is affected by this revision." \
@@ -612,14 +629,19 @@ jobs:
               exit 1
             }
           done
-          if [ "$TEST_SHARD" = "app" ]; then
-            # A single long-lived app test process retains every constructed
-            # command tree in framework registries. Isolate Schema assembly and
-            # bounded name ranges so each process releases that state on exit.
-            test "${#packages[@]}" -eq 1
-            ./scripts/ci/run-app-race-tests.sh run "${packages[0]}"
-            exit 0
-          fi
+          case "$TEST_SHARD" in
+            app-*)
+              # A single long-lived app test process retains every constructed
+              # command tree in framework registries. Each partition is its own
+              # job, so that state is released when the process exits and the
+              # partitions run concurrently instead of end to end. The helper
+              # still verifies that the partition patterns cover every top-level
+              # test exactly once before running the one it was asked for.
+              test "${#packages[@]}" -eq 1
+              ./scripts/ci/run-app-race-tests.sh run "${packages[0]}" "${TEST_SHARD#app-}"
+              exit 0
+              ;;
+          esac
           if [ "$TEST_SHARD" = "release-scripts" ]; then
             # Mirror the dedicated release-contract job: these suites shell out
             # to archive tooling and are not race-instrumented there.
@@ -640,14 +662,21 @@ jobs:
     needs: lint
     if: ${{ needs.lint.outputs.changelog_only != 'true' && needs.lint.outputs.docs_only != 'true' && needs.lint.outputs.full_suite == 'true' }}
     runs-on: ubuntu-latest
-    # app runs several independently bounded processes; cli/smoke need headroom
-    # beyond go test -timeout for setup + assembly.
+    # internal/app is split across one shard per bounded partition so the
+    # partitions run concurrently and each releases its framework registries
+    # when the process exits; cli/smoke need headroom beyond go test -timeout for
+    # setup + assembly. The app-<partition> names are pinned to the helper's
+    # partition set by TestCIAppRacePartitionMatrixMatchesHelper.
     timeout-minutes: 20
     strategy:
       fail-fast: false
       matrix:
         shard:
-          - app
+          - app-schema
+          - app-a-b
+          - app-c
+          - app-d-r
+          - app-s-z-example-fuzz
           - generators
           - helpers
           - cli
@@ -673,18 +702,30 @@ jobs:
           TEST_SHARD: ${{ matrix.shard }}
         run: |
           set -euo pipefail
-          package_output="$(./scripts/ci/test-packages.sh list "$TEST_SHARD")"
+          # Every app partition shard tests the same single internal/app
+          # package, so the package query uses the base shard name and the
+          # partition only selects which tests run.
+          package_shard="$TEST_SHARD"
+          case "$TEST_SHARD" in
+            app-*) package_shard=app ;;
+          esac
+          package_output="$(./scripts/ci/test-packages.sh list "$package_shard")"
           test -n "$package_output"
           mapfile -t packages <<< "$package_output"
           test "${#packages[@]}" -gt 0
-          if [ "$TEST_SHARD" = "app" ]; then
-            # A single long-lived app test process retains every constructed
-            # command tree in framework registries. Isolate Schema assembly and
-            # bounded name ranges so each process releases that state on exit.
-            test "${#packages[@]}" -eq 1
-            ./scripts/ci/run-app-race-tests.sh run "${packages[0]}"
-            exit 0
-          fi
+          case "$TEST_SHARD" in
+            app-*)
+              # A single long-lived app test process retains every constructed
+              # command tree in framework registries. Each partition is its own
+              # job, so that state is released when the process exits and the
+              # partitions run concurrently instead of end to end. The helper
+              # still verifies that the partition patterns cover every top-level
+              # test exactly once before running the one it was asked for.
+              test "${#packages[@]}" -eq 1
+              ./scripts/ci/run-app-race-tests.sh run "${packages[0]}" "${TEST_SHARD#app-}"
+              exit 0
+              ;;
+          esac
           # cli/smoke own heavy NewRootCommand / Schema assembly under -race;
           # give them a dedicated package timeout on slower hosted runners.
           timeout_budget=12m

.gitignore

@@ -73,3 +73,6 @@ coverage-*.txt
 
 # stray compiled generator binary (source lives in internal/generator/cmd_param_aliases/)
 /cmd_param_aliases
+
+# Local product-skill design materials (not for repository pushes)
+/design-dws-product-skills/

CHANGELOG.md

@@ -6,6 +6,92 @@ The format is inspired by [Keep a Changelog](https://keepachangelog.com/) and th
 
 ## [Unreleased]
 
+## [1.0.59-beta.3] - 2026-08-19
+
+### Added
+
+- **Robot group reference replies** (#928) — `chat message send-by-bot` supports paired `--reply` and `--ref-sender` flags for Markdown replies that quote an existing group message.
+
+- **AI Table server-side statistics** — adds `dws aitable record stats` for
+  ungrouped record-set metrics through `query_records_stats`, plus `dws aitable
+  record group-stats` for grouped, distinct, and advanced aggregation through
+  `query_stats`; both commands validate their JSON aggregation contracts before
+  dispatch.
+
+- **Calendar event share-info** (#980) — adds `dws calendar event share-info` to fetch a calendar event's share info (title, organizer, location, join info) for sharing with others; supports `--calendar-id` and `--language`.
+
+- **Calendar and To-do Shortcut workflows** — aligns 47 public task-oriented
+  entries with lark-cli where the DingTalk backend supports equivalent
+  semantics, rejects malformed or missing collections instead of returning
+  false empty success, preserves truthful pagination, and requires stable
+  identifiers plus read-back or explicit terminal receipts for writes. Adds
+  deterministic contract coverage, a PII-safe live E2E runner, and a sanitized
+  capability review with documented platform boundaries.
+
+- **Doc and Sheet comment lifecycle commands** — adds `comment batch-query`,
+  `comment resolve`, `comment restore`, and the lightweight
+  `comment react-reply` to both `dws doc` and `dws sheet`. The two domains share
+  the same `doc-comment` MCP capabilities; batch queries preserve input order
+  for repeated `topicId:commentKey` references, while reaction replies require
+  DingTalk reaction names such as `憨笑` or `鼓掌` rather than raw Unicode emoji.
+
+- **Sheet SourceRange dropdowns** — supports range-backed dropdowns across direct, cell, and batch write paths, with structured readback for valid and invalid references. Batch `set-dropdown` now rejects unsupported top-level `colors` / `source-colors`; Inline colors belong in `options[].color`, while SourceRange color writes remain unsupported.
+- **Sheet read completion metadata** — documents and preserves returned ranges, truncation reasons, and partial-read status for large range and CSV reads.
+
+### Changed
+
+- **AI Table parameter aliases** — accepts reviewed equivalent spellings for Base, table, workflow, search, pagination, and description parameters while keeping role-changing or semantically ambiguous inputs blocked.
+
+- **Doc/drive description scope** — restates the `dingtalk-doc` description as document-entity-and-content operations with an explicit exclusion list, and narrows `dingtalk-drive` to file-level management of DingTalk documents, so first-round Agent selection separates content work from file management without changing CLI behavior.
+
+### Fixed
+
+- **Aitable pagination and Minutes unshare verification** (#1006) — keeps
+  record queries on the service's 20-record page boundary so multi-page reads
+  and mutation readbacks no longer report false retryable failures, preserves
+  `totalCount` when supplied, validates `--dry-run` plans before transport,
+  follows active deletion readback continuations before proving absence, and
+  rejects Minutes unshare success until the listening note exists and the
+  service acknowledges the exact task and member targets.
+
+- **Document write verification** (#960) — avoids false partial-success results when normalized Markdown, paginated blocks, inline images, or version reverts are confirmed by server readback. Document reverts and media inserts now require explicit readback evidence and report partial success when the server cannot prove the requested result.
+
+- **Chat sender identity guards** — preserves unverified mixed sender inputs after exact message `senderId` matches and aligns `--sender-query` Skill guidance with fail-closed Runtime behavior.
+
+- **Windows event bus lifecycle** — start event consumers without unsupported inherited file descriptors, stop buses through local IPC with a termination fallback, and preserve subscription cleanup when startup fails.
+
+
+## [1.0.59-beta.2] - 2026-08-17
+
+### Added
+
+- **Privacy-safe CLI telemetry** (#1009) — reports reviewed command outcomes and profile identity dimensions while excluding command arguments, output, paths, device fingerprints, and automatic system dimensions; `DO_NOT_TRACK=1` disables reporting.
+
+- **Feedback survey entry in root help** (#1019) — `dws --help` now closes with a Feedback section linking the user-experience survey form.
+
+- **Wiki Shortcut workflows** — publishes 20 reviewed space, member, node, and
+  activity shortcuts with strict collection validation, cursor handling,
+  write-terminal evidence, safe read-backs where the backend supports them,
+  task-oriented routing, and documented backend
+  boundaries.
+
+### Changed
+
+- **Chat IM ID flags** (#954) — standardizes chat command entry points on `--conversation-id` for conversation IDs and `--message-id` for message IDs, so help, Schema, and Agent recommendations use the same canonical flags.
+- **Legacy chat flag compatibility** (#954) — keeps older chat IM ID flags such as `--group`, `--id`, `--chat`, `--open-conversation-id`, `--msg-id`, and `--open-message-id` working as compatibility aliases where applicable, while hiding migrated aliases from recommended help and Schema surfaces.
+- **Chat group bots target flag** (#954) — keeps `dws chat group bots` on the visible `--group` flag; this command does not register `--group-name`, and `--group` accepts either an openConversationId or a uniquely resolved group name.
+
+- **Faster Schema Catalog assembly** — projects typed values into payload JSON
+  without re-running a validation scan over documents `json.Marshal` has just
+  produced, cutting roughly a third of the projection work across the full tool
+  set. Untrusted JSON input keeps its existing validation.
+
+### Fixed
+
+- **Chat card update evidence** — distinguishes an accepted update request from an independently verified visible update, preserving the real `bizId` and warning callers not to repeat an unverified write.
+- **Chat command guidance** — splits message and group references by task and explains that `--from` is ambiguous between sender and time-range intent.
+
+
 ## [1.0.59-beta.1] - 2026-08-14
 
 ### Added

Formula/dingtalk-workspace-cli-beta.rb

@@ -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.59-beta.1"
+  version "1.0.59-beta.3"
   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.59-beta.1/dws-darwin-arm64.tar.gz"
-      sha256 "36a30f3496e0f759c15c0b09f67dbd23b8ecdfff2eebe572f88125b26485830f"
+      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.59-beta.3/dws-darwin-arm64.tar.gz"
+      sha256 "9c99adcefd9104368eb443f0a1b4af8e7aceaa1ffdd4462e486854c1692bb6ce"
     else
-      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.59-beta.1/dws-darwin-amd64.tar.gz"
-      sha256 "e7a04906380efd8da88cd112e6a512bb6470a3956dc370150037ed6e314db445"
+      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.59-beta.3/dws-darwin-amd64.tar.gz"
+      sha256 "f5cc8efb1f982d68ae549190fd683292359c2ab542b532fa52bb35e6b5c049af"
     end
   end
 
   on_linux do
     if Hardware::CPU.arm?
-      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.59-beta.1/dws-linux-arm64.tar.gz"
-      sha256 "f59ab055f3e841e4cebc964ae3ef969668475548abaaf8bede44afdca9a3e28d"
+      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.59-beta.3/dws-linux-arm64.tar.gz"
+      sha256 "7a4efd04b417ce8013b1e431274b396179958da244164f59974358ba327ff093"
     else
-      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.59-beta.1/dws-linux-amd64.tar.gz"
-      sha256 "2c8f919489d958c7d49262615e81faac70a9fbcae2d589ab54a0bb3c5700a057"
+      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.59-beta.3/dws-linux-amd64.tar.gz"
+      sha256 "90181e8f2e9010c1943a5773c3d45d7d3ac85d6bc93e18a9aaa7c69909e553d7"
     end
   end
 
   resource "skills" do
-    url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.59-beta.1/dws-skills.zip"
-    sha256 "25f4a7e1d01fa4d771d79201b34b11ee8a24182bdcdc94bfb98d2bd5845bed3b"
+    url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.59-beta.3/dws-skills.zip"
+    sha256 "e7028914a4a826af9b18ed4922d68fa8f279473817fed4f305465bc8a7aad363"
   end
 
   def install

docs/cli-interface-flag-migrations.md

@@ -41,7 +41,7 @@ PR merge-base 同时拥有快照生成器、比较器和已审批清单。门禁
 scripts/policy/interface-migrations/approved-flag-migrations-v1.json
 ```
 
-清单使用严格 JSON 解析：版本、字段名大小写、JSON 值类型、命令路径和 flag 名都必须精确；拒绝重复键、未知键、scalar `null` 与尾随 JSON 值，`reason` 不能为空；禁止 `*`、`?`、前缀规则或其他 wildcard。当前清单登记了 IM ID rename 的 `pending` 记录；`pending` 只记录已评审计划，候选与 merge-base 仍必须精确匹配 `before`，因此本治理 PR **不授权 PR #904 或任何产品接口变化**。
+清单使用严格 JSON 解析：版本、字段名大小写、JSON 值类型、命令路径和 flag 名都必须精确；拒绝重复键、未知键、scalar `null` 与尾随 JSON 值，`reason` 不能为空；禁止 `*`、`?`、前缀规则或其他 wildcard。清单中的 `pending` 记录只记录已评审计划，并授权其精确列出的后续产品迁移；候选与 merge-base 仍必须精确匹配 `before`，不能授权同一个提交中的接口变化，也不能作为其他命令或参数的通配豁免。
 
 ## 两阶段迁移与回执清理
 

docs/shortcut-public-catalog.json

@@ -1,6 +1,6 @@
 {
-  "generated_at": "2026-08-14T13:50:36.324505",
-  "count": 418,
+  "generated_at": "2026-08-18T17:38:50.904696",
+  "count": 436,
   "results": [
     {
       "suite": "semantic",
@@ -489,7 +489,7 @@
       "risk": "read",
       "status": "reviewed_available",
       "disposition": "semantic_adapter",
-      "semantic_delta": "统一 ID、筛选、关键词和分页查询，并投影稳定的 records/count/cursor 结果。",
+      "semantic_delta": "统一 ID、筛选、关键词、字段投影和分页查询；fieldIds 只返回用户要求的列，并投影稳定的 records/count/cursor 结果。",
       "availability": "available"
     },
     {
@@ -692,6 +692,16 @@
       "semantic_delta": "按当前父目录语义调整文件夹展示顺序。",
       "availability": "available"
     },
+    {
+      "suite": "semantic",
+      "service": "aitable",
+      "command": "+table-bootstrap",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "在已有 Base 中声明式创建一张表和字段，字段自动分片，逐层读回验证并发布可恢复检查点。",
+      "availability": "available"
+    },
     {
       "suite": "semantic",
       "service": "aitable",
@@ -1056,144 +1066,274 @@
       "status": "real-ok"
     },
     {
-      "suite": "read",
+      "suite": "semantic",
       "service": "calendar",
       "command": "+agenda",
       "risk": "read",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "严格验证 result.events 与分页证据，稳定投影 id 为 eventId；显式空数组才是空日程。",
+      "availability": "available"
     },
     {
-      "suite": "read",
+      "suite": "semantic",
       "service": "calendar",
       "command": "+attendee-list",
       "risk": "read",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "严格验证参会人数组并投影显示名、响应状态和 self；真实后端不返回稳定参会人 userId，因此不伪造身份字段。",
+      "availability": "available"
     },
     {
-      "suite": "write",
+      "suite": "semantic",
       "service": "calendar",
       "command": "+book",
       "risk": "write",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "按参会人姓名解析后创建日程，并在多步骤路径提供失败回滚与详情读回。",
+      "availability": "available"
     },
     {
-      "suite": "read",
+      "suite": "semantic",
       "service": "calendar",
       "command": "+book-list",
       "risk": "read",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "严格验证日历本数组并稳定投影 calendarId，缺失数组不再误报为空。",
+      "availability": "available"
     },
     {
-      "suite": "read",
+      "suite": "semantic",
       "service": "calendar",
       "command": "+book-search",
       "risk": "read",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "按日历本名称搜索并严格区分零命中与协议错误。",
+      "availability": "available"
     },
     {
-      "suite": "write",
+      "suite": "semantic",
       "service": "calendar",
       "command": "+cancel-event",
       "risk": "high-risk-write",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "删除前读取并展示目标，经高风险确认后取消指定日程。",
+      "availability": "available"
     },
     {
-      "suite": "read",
+      "suite": "semantic",
       "service": "calendar",
       "command": "+conflicts",
       "risk": "read",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "在指定范围分析重叠日程并输出冲突对，避免人工逐项比对。",
+      "availability": "available"
     },
     {
-      "suite": "read",
+      "suite": "semantic",
+      "service": "calendar",
+      "command": "+create",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "创建响应必须给出 eventId/id，且标题和起止时间通过详情读回后才成功。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
       "service": "calendar",
       "command": "+free",
       "risk": "read",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "按姓名解析参与者后查询闲忙，省去手工 userId 解析。",
+      "availability": "available"
     },
     {
-      "suite": "read",
+      "suite": "semantic",
       "service": "calendar",
       "command": "+free-slots",
       "risk": "read",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "从已有日程计算工作时段内空档，并显式输出满足时长的候选区间。",
+      "availability": "available"
     },
     {
-      "suite": "read",
+      "suite": "semantic",
       "service": "calendar",
       "command": "+freebusy",
       "risk": "read",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "统一按用户或会议室 ID 查询指定范围闲忙，并声明至少一类目标约束。",
+      "availability": "available"
     },
     {
-      "suite": "write",
+      "suite": "semantic",
+      "service": "calendar",
+      "command": "+get",
+      "risk": "read",
+      "status": "reviewed_available",
+      "disposition": "schema_leaf",
+      "semantic_delta": "严格读取日程对象并把稳定 id 规范化为 eventId，拒绝空响应和对象漂移。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
       "service": "calendar",
       "command": "+invite",
       "risk": "write",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "按姓名唯一解析用户后邀请到已有日程。",
+      "availability": "available"
     },
     {
-      "suite": "read",
+      "suite": "semantic",
       "service": "calendar",
       "command": "+my-free",
       "risk": "read",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "以当前用户身份查询一个时间段是否空闲。",
+      "availability": "available"
     },
     {
-      "suite": "read",
+      "suite": "semantic",
       "service": "calendar",
       "command": "+next-event",
       "risk": "read",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "在未来时间窗内定位最近的下一场日程。",
+      "availability": "available"
     },
     {
-      "suite": "write",
+      "suite": "semantic",
       "service": "calendar",
       "command": "+reschedule",
       "risk": "write",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "修改前读取目标日程，再更新完整起止时间。",
+      "availability": "available"
     },
     {
-      "suite": "read",
+      "suite": "semantic",
+      "service": "calendar",
+      "command": "+room-find",
+      "risk": "read",
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "按单个未来时间段严格查询可用会议室，公开真实 page/pageSize/hasMore 证据和后端筛选边界。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
       "service": "calendar",
       "command": "+room-groups",
       "risk": "read",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "严格读取 result.groupList，避免会议室分组被响应 wrapper 漂移静默清空。",
+      "availability": "available"
     },
     {
-      "suite": "read",
+      "suite": "semantic",
       "service": "calendar",
       "command": "+room-search",
       "risk": "read",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "按名称查询会议室但不声称检查时间可用性；缺失会议室数组直接失败。",
+      "availability": "available"
     },
     {
-      "suite": "read",
+      "suite": "semantic",
+      "service": "calendar",
+      "command": "+rsvp",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "把直白 RSVP 动作映射为 responseStatus，拒绝空 ack，并在写后读取日程终态。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "calendar",
+      "command": "+search-event",
+      "risk": "read",
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "在服务端日程当前页按标题、描述和地点过滤，同时保留 hasMore/nextCursor，绝不把单页零命中当全局未找到。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
       "service": "calendar",
       "command": "+suggest-time",
       "risk": "read",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "按姓名逐个唯一解析参与者，再查询大家共同可用的建议时间。",
+      "availability": "available"
     },
     {
-      "suite": "read",
+      "suite": "semantic",
+      "service": "calendar",
+      "command": "+suggestion",
+      "risk": "read",
+      "status": "reviewed_available",
+      "disposition": "schema_leaf",
+      "semantic_delta": "直接按 userId 查询建议时段，严格区分显式空 recommendEventTimes 与缺失或畸形响应。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
       "service": "calendar",
       "command": "+today",
       "risk": "read",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "查询并整理今天的日程视图。",
+      "availability": "available"
     },
     {
-      "suite": "read",
+      "suite": "semantic",
       "service": "calendar",
       "command": "+tomorrow",
       "risk": "read",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "查询并整理明天的日程视图。",
+      "availability": "available"
     },
     {
-      "suite": "read",
+      "suite": "semantic",
+      "service": "calendar",
+      "command": "+update",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "组合字段与参会人分阶段更新，明确非事务步骤并以详情和参会人列表读回验证。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
       "service": "calendar",
       "command": "+week",
       "risk": "read",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "查询并按日期整理本周日程。",
+      "availability": "available"
     },
     {
       "suite": "semantic",
@@ -3582,81 +3722,214 @@
       "status": "real-ok"
     },
     {
-      "suite": "write",
+      "suite": "semantic",
       "service": "todo",
       "command": "+assign",
       "risk": "write",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "保留历史按姓名解析后创建并指派的新任务语义，避免同名破坏性变更。",
+      "availability": "available"
     },
     {
-      "suite": "write",
+      "suite": "semantic",
       "service": "todo",
       "command": "+assign-multi",
       "risk": "write",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "全部姓名唯一解析后才创建一次，并以单一统一结果输出稳定 taskId。",
+      "availability": "available"
     },
     {
-      "suite": "read",
+      "suite": "semantic",
+      "service": "todo",
+      "command": "+comment",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "新增评论必须取得稳定 commentId，并分页读回验证内容。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "todo",
+      "command": "+complete",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "先读当前状态避免重复写，必要时完成后再读回核验。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "todo",
+      "command": "+create",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "创建后要求稳定 taskId，并读取 todoDetailModel 验证标题。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
       "service": "todo",
       "command": "+created-todos",
       "risk": "read",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "遍历创建者角色的全部分页后投影。",
+      "availability": "available"
     },
     {
-      "suite": "read",
+      "suite": "semantic",
+      "service": "todo",
+      "command": "+due-today",
+      "risk": "read",
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "按本地日历日构造服务端截止窗口并遍历全部分页。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
       "service": "todo",
       "command": "+get",
       "risk": "read",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "严格绑定 todoDetailModel.taskId，缺失或错绑均失败。",
+      "availability": "available"
     },
     {
-      "suite": "read",
+      "suite": "semantic",
       "service": "todo",
       "command": "+get-my-tasks",
       "risk": "read",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "严格识别 todoCards/hasMore/page/size；显式空数组才是空结果，并支持有界全量分页。",
+      "availability": "available"
     },
     {
-      "suite": "read",
+      "suite": "semantic",
+      "service": "todo",
+      "command": "+get-related-tasks",
+      "risk": "read",
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "遍历与我相关三种角色的全部分页并按 taskId 去重。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
       "service": "todo",
       "command": "+list-attachment",
       "risk": "read",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "严格区分显式空附件与缺失容器，并要求每项稳定附件 ID。",
+      "availability": "available"
     },
     {
-      "suite": "read",
+      "suite": "semantic",
       "service": "todo",
       "command": "+list-comment",
       "risk": "read",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "严格区分显式空评论与缺失容器，并要求每项稳定 commentId。",
+      "availability": "available"
     },
     {
-      "suite": "read",
+      "suite": "semantic",
       "service": "todo",
       "command": "+list-sub",
       "risk": "read",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "严格校验子待办容器、对象元素和稳定 taskId。",
+      "availability": "available"
     },
     {
-      "suite": "read",
+      "suite": "semantic",
       "service": "todo",
       "command": "+overdue",
       "risk": "read",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "遍历执行者角色的全部分页并按当前时间筛选逾期项。",
+      "availability": "available"
     },
     {
-      "suite": "write",
+      "suite": "semantic",
+      "service": "todo",
+      "command": "+related-tasks",
+      "risk": "read",
+      "status": "reviewed_available",
+      "disposition": "alias_internal",
+      "semantic_delta": "保留旧命令拼写，新的 Agent 路由统一使用 +get-related-tasks。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
       "service": "todo",
       "command": "+remind",
       "risk": "write",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "解析当前用户后创建给自己的待办；该命令不是独立提醒规则。",
+      "availability": "available"
     },
     {
-      "suite": "write",
+      "suite": "semantic",
+      "service": "todo",
+      "command": "+reminder",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "严格验证提醒参数和 success=true 终端回执；上游不能读回规则，固定 verified=false。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "todo",
+      "command": "+reopen",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "先读当前状态避免重复写，必要时重开后再读回核验。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "todo",
+      "command": "+search",
+      "risk": "read",
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "遍历全部 hasMore 分页并按标题匹配；达到页上限仍未耗尽时失败。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
       "service": "todo",
       "command": "+todo-done",
       "risk": "write",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "跨全部分页按标题唯一定位后完成任务。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "todo",
+      "command": "+update",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "更新指定字段后读取详情逐字段核验。",
+      "availability": "available"
     },
     {
       "suite": "semantic",

docs/shortcut-report.html

@@ -102,7 +102,7 @@
       <tr><td><code>minutes +latest-minutes</code></td><td>列妙记→取最新一条详情</td><td class="c ok">编译/挂载</td></tr>
       <tr><td><code>minutes +action-items</code></td><td>列妙记→取最新→取其待办</td><td class="c ok">编译/挂载</td></tr>
       <tr><td><code>wiki +wiki-new-doc --space &lt;名&gt;</code></td><td>按名搜知识空间→建文档（跨 doc server 路由）</td><td class="c ok">编译/挂载</td></tr>
-      <tr><td><code>doc +doc-append --doc --text</code></td><td>文档末尾追加文本</td><td class="c ok">编译/挂载</td></tr>
+      <tr><td><code>doc +doc-append --doc --content</code></td><td>文档末尾追加文本</td><td class="c ok">编译/挂载</td></tr>
       <tr><td><code>doc +share-doc --to &lt;名&gt; --url</code></td><td>解析人→把文档链接私信 TA（跨服务）</td><td class="c ok">编译/挂载</td></tr>
     </tbody>
   </table>

docs/shortcut-report.md

@@ -56,13 +56,13 @@
 
 | shortcut | 多步/智能逻辑 | 验证 |
 |----------|--------------|------|
-| `chat +dm --to <姓名> --text` | 搜人→解析唯一 userId→发单聊；多人消歧 | ✅ dry-run 真机 |
+| `chat +dm --to <姓名> --content` | 搜人→解析唯一 userId→发单聊；多人消歧 | ✅ dry-run 真机 |
 | `contact +lookup --name <姓名>` | 搜人→解析 userId→取完整资料 | ✅ **真机端到端** |
 | `todo +assign --to <姓名> --task` | 解析人→建待办并把 TA 设为执行人 | ✅ dry-run 真机 |
-| `chat +send-to-group --group <群名> --text` | 按群名搜群(search_groups)→消歧→发消息 | ✅ 编译/挂载 |
+| `chat +send-to-group --group <群名> --content` | 按群名搜群(search_groups)→消歧→发消息 | ✅ 编译/挂载 |
 | `calendar +book --title --start --end [--with <姓名CSV>]` | 建日程→按名加参与者→**失败回滚删日程**（对标 lark `calendar +create`） | ✅ dry-run 真机 |
 | `calendar +free --who <姓名> --start --end` | 解析人→查其时段忙闲 | ✅ **真机端到端**（解析 202397→查忙闲） |
-| `chat +broadcast --to <姓名CSV> --text` | 多名逐一解析→群发单聊，失败汇总不中断 | ✅ 编译/挂载 |
+| `chat +broadcast --to <姓名CSV> --content` | 多名逐一解析→群发单聊，失败汇总不中断 | ✅ 编译/挂载 |
 | `minutes +latest-minutes` | 列妙记→取最新一条详情 | ✅ 编译/挂载 |
 | `chat +group-members --group <群名>` | 按群名搜群→列群成员 | ✅ 编译/挂载 |
 | `contact +org --name <姓名>` | 解析人→取详情拿 deptId→查部门详情 | ✅ **真机端到端**（3 步：董鑫阳→模型算法/16人） |
@@ -76,7 +76,7 @@
 | `todo +todo-done --task <关键词>` | 列我的待办→按标题匹配→标记完成 | ✅ 编译/挂载 |
 | `calendar +reschedule --event <id>` | 查日程详情→改时间（查→改机械多步） | ✅ 编译/挂载 |
 | `wiki +wiki-new-doc --space <名>` | 按名搜知识空间→在其下建文档（跨 doc server 路由） | ✅ 编译/挂载 |
-| `doc +doc-append --doc --text` | 文档末尾追加文本（update_document append 模式） | ✅ 编译/挂载 |
+| `doc +doc-append --doc --content` | 文档末尾追加文本（update_document append 模式） | ✅ 编译/挂载 |
 | `minutes +action-items` | 列妙记→取最新→取其待办事项 | ✅ 编译/挂载 |
 | `minutes +detail --id <taskUuid>` | 一条命令聚合听记 basic/summary/keywords/transcript/todos，partial-failure 容错 | ✅ 全量测试 |
 | `minutes +replace-batch --id --pair "原文=>替换"…` | 多组批量替换文字，去重校验+逐组结果聚合 | ✅ 全量测试 |

docs/superpowers/specs/2026-08-14-oa-attachment-download-url-output-design.md

@@ -0,0 +1,55 @@
+# OA Attachment Download URL Output Design
+
+## Goal
+
+Keep the existing command and MCP request unchanged while making the returned
+OSS signed URL directly copyable from JSON output:
+
+```text
+dws oa approval attachment download-url
+```
+
+## Scope
+
+Only `oa approval attachment download-url` changes. The other OA attachment
+commands and the global JSON formatter retain their current behavior.
+
+## Design
+
+The command continues to invoke MCP server `oa`, tool
+`get_attachment_download_url`, with the same arguments. Its leaf declaration
+provides a command-specific `Call` callback that invokes the existing MCP
+dispatcher with HTML escaping disabled when the selected output format is
+JSON. This preserves literal `&` separators in `result.downloadUri` instead of
+rendering them as `\u0026`.
+
+For `raw`, `table`, and other non-JSON formats, the callback uses the existing
+escaped dispatcher behavior so their current rendering remains unchanged.
+
+The change does not alter the URL, decode or re-sign it, download the file, or
+change global JSON serialization.
+
+## Error Handling
+
+Authentication, MCP transport, gateway, PAT, and business errors continue
+through the existing dispatcher and retain their current classification and
+output behavior.
+
+## Verification
+
+Add a `TestCrossPlatformCoverage*` regression test that executes the real Cobra
+leaf in explicit JSON mode with a fake MCP result containing a signed URL. It
+must verify:
+
+- the request still targets `oa/get_attachment_download_url`;
+- the exact request arguments remain unchanged, including omission of the
+  optional boolean when the flag was not supplied;
+- stdout contains literal `&OSSAccessKeyId=` and `&Signature=`;
+- stdout contains no `\u0026` escape.
+
+The fake caller must report JSON format (or the command must be executed with
+`--format json`) so the test fails against the current escaped JSON path rather
+than accidentally exercising raw MCP text output.
+
+Run the focused OA attachment tests, format modified Go files, and rebuild the
+CLI. No commit is created.

go.mod

@@ -18,6 +18,7 @@ require (
 	github.com/muesli/termenv v0.16.0
 	github.com/open-dingtalk/dingtalk-stream-sdk-go v0.9.2-beta.1
 	github.com/spf13/cobra v1.10.2
+	github.com/yuin/goldmark v1.8.5
 	github.com/zalando/go-keyring v0.2.8
 	gitlab.alibaba-inc.com/aes/aem-go-sdk v0.3.0
 	golang.org/x/crypto v0.49.0

go.sum

@@ -105,6 +105,8 @@ github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu
 github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
 github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e h1:JVG44RsyaB9T2KIHavMF/ppJZNG9ZpyihvCd0w101no=
 github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e/go.mod h1:RbqR21r5mrJuqunuUZ/Dhy/avygyECGrLceyNeo4LiM=
+github.com/yuin/goldmark v1.8.5 h1:r6N5afV5qj/5S4UTch8agZHJ8UxNCMwX7WjkkJam2NA=
+github.com/yuin/goldmark v1.8.5/go.mod h1:ip/1k0VRfGynBgxOz0yCqHrbZXhcjxyuS66Brc7iBKg=
 github.com/zalando/go-keyring v0.2.8 h1:6sD/Ucpl7jNq10rM2pgqTs0sZ9V3qMrqfIIy5YPccHs=
 github.com/zalando/go-keyring v0.2.8/go.mod h1:tsMo+VpRq5NGyKfxoBVjCuMrG47yj8cmakZDO5QGii0=
 go.yaml.in/yaml/v3 v3.0.4/go.mod h1:DhzuOOF2ATzADvBadXxruRBLzYTpT36CKvDb3+aBEFg=

internal/app/event_command.go

@@ -1220,7 +1220,8 @@ func newEventStopCommandWithFlags(globalFlags ...*GlobalFlags) *cobra.Command {
 			editionName := editionNameOrDefault()
 			clientIDHash := dwsevent.ClientIDHash(clientID)
 			workDir := eventWorkDir(configDir, editionName, dwsevent.SourceKindAppStream, clientIDHash)
-			if err := eventStopBus(busctl.StopConfig{WorkDir: workDir}); err != nil {
+			ipcEndpoint := defaultIPCEndpoint(workDir, editionName, dwsevent.SourceKindAppStream, clientIDHash)
+			if err := eventStopBus(busctl.StopConfig{WorkDir: workDir, IPCEndpoint: ipcEndpoint}); err != nil {
 				if errors.Is(err, busctl.ErrNotRunning) {
 					fmt.Fprintln(c.OutOrStdout(), "bus is not running")
 					return nil

internal/app/event_personal_command.go

@@ -1220,7 +1220,7 @@ func runPersonalEventStop(c *cobra.Command, opts personalStopOptions) error {
 	}
 
 	busState := "personal bus stopped"
-	if err := personalStopBus(busctl.StopConfig{WorkDir: workDir}); err != nil {
+	if err := personalStopBus(busctl.StopConfig{WorkDir: workDir, IPCEndpoint: ipcEndpoint}); err != nil {
 		if errors.Is(err, busctl.ErrNotRunning) {
 			busState = "personal bus is not running"
 		} else {

internal/app/param_alias_e2e_test.go

@@ -52,6 +52,8 @@ func (c *paramAliasCaptureCaller) paramAliasResponseForTool(tool string) string
 	switch tool {
 	case "list_calendar_events":
 		return `{"result":{"events":[]}}`
+	case "query_records":
+		return `{"success":true,"status":"success","error":{},"data":{}}`
 	case "search_mail_users":
 		return `{"users":[{"name":"Fixture User","email":"fixture@example.com","id":"fixture-user"}]}`
 	case "search_dept_by_keyword":
@@ -63,9 +65,11 @@ func (c *paramAliasCaptureCaller) paramAliasResponseForTool(tool string) string
 	case "list_doc_versions":
 		return `{"result":{"items":[{"version":3}]}}`
 	case "revert_doc_version":
-		return `{"version":3}`
+		return `{"revertedToVersion":3}`
 	case "search_doc_templates":
 		return `{"result":[{"templateId":"fixture-template-id"}]}`
+	case "list_workflows":
+		return `{"workflows":[]}`
 	case "create_document":
 		return `{"nodeId":"fixture-node"}`
 	case "list_files":

internal/app/param_alias_payload_equivalence_test.go

@@ -27,12 +27,23 @@ const (
 // its spelling while holding every other input constant.
 var paramAliasCompleteCommands = map[string][]string{
 	"aitable +base-search":                     {"aitable", "+base-search", "--query", "fixture"},
+	"aitable +export-data":                     {"aitable", "+export-data", "--base-id", "base-1", "--scope", "all", "--format", "excel"},
 	"aitable +field-get":                       {"aitable", "+field-get", "--base-id", "base-1", "--table-id", "table-1"},
+	"aitable +find-record":                     {"aitable", "+find-record", "--base", "base-1", "--table", "table-1", "--query", "fixture"},
 	"aitable +list-tables":                     {"aitable", "+list-tables", "--base", "base-1"},
 	"aitable +record-query":                    {"aitable", "+record-query", "--base-id", "base-1", "--table-id", "table-1", "--query", "fixture"},
+	"aitable +record-share-links":              {"aitable", "+record-share-links", "--base", "base-1", "--table", "table-1", "--record-ids", "record-1"},
 	"aitable +record-share-url":                {"aitable", "+record-share-url", "--base-id", "base-1", "--table-id", "table-1", "--record-ids", "record-1"},
 	"aitable +table-get":                       {"aitable", "+table-get", "--base-id", "base-1"},
+	"aitable +workflow-list":                   {"aitable", "+workflow-list", "--base-id", "base-1", "--limit", "7"},
+	"aitable attachment upload":                {"aitable", "attachment", "upload", "--base-id", "base-1", "--file-name", "fixture.txt", "--size", "7"},
+	"aitable base list":                        {"aitable", "base", "list", "--cursor", "cursor-1", "--limit", "7"},
+	"aitable base update":                      {"aitable", "base", "update", "--base-id", "base-1", "--name", "Fixture Base", "--desc", "fixture description"},
+	"aitable field search-options":             {"aitable", "field", "search-options", "--base-id", "base-1", "--table-id", "table-1", "--field-id", "field-1", "--keyword", "fixture", "--limit", "7"},
 	"aitable record query":                     {"aitable", "record", "query", "--base-id", "base-1", "--table-id", "table-1", "--limit", "7"},
+	"aitable workflow get":                     {"aitable", "workflow", "get", "--base-id", "base-1", "--workflow-id", "workflow-1"},
+	"aitable workflow history":                 {"aitable", "workflow", "history", "--base-id", "base-1", "--workflow-id", "workflow-1", "--after-time", "1000", "--before-time", "2000", "--page", "2", "--size", "25"},
+	"aitable workflow run":                     {"aitable", "workflow", "run", "--base-id", "base-1", "--workflow-id", "workflow-1", "--table-id", "table-1", "--record-ids", "record-1", "--yes"},
 	"attendance check result":                  {"attendance", "check", "result", "--users", "user-1,user-2", "--start", "2026-03-01", "--end", "2026-03-02"},
 	"attendance +check-result":                 {"attendance", "+check-result", "--users", "user-1,user-2", "--start", "2026-03-01", "--end", "2026-03-02"},
 	"calendar event list":                      {"calendar", "event", "list", "--start", "2026-03-10T14:00:00+08:00", "--end", "2026-03-10T18:00:00+08:00", "--calendar-id", "primary", "--cursor", "cursor-1", "--limit", "7"},
@@ -62,12 +73,12 @@ var paramAliasCompleteCommands = map[string][]string{
 	"chat +messages-list":                      {"chat", "+messages-list", "--group", "fixture-conversation", "--time", "2026-03-10 00:00:00", "--limit", "7"},
 	"chat +messages-list-direct":               {"chat", "+messages-list-direct", "--user", "user-1", "--time", "2026-03-10 00:00:00", "--limit", "7"},
 	"chat +messages-list-unread-conversations": {"chat", "+messages-list-unread-conversations", "--count", "7", "--exclude-muted"},
-	"chat +messages-reply":                     {"chat", "+messages-reply", "--conversation-id", "fixture-conversation", "--ref-msg-id", "message-1", "--ref-sender", appFixtureCurrentDOpenID, "--text", "hello fixture", "--yes"},
+	"chat +messages-reply":                     {"chat", "+messages-reply", "--group", "fixture-conversation", "--ref-msg-id", "message-1", "--ref-sender", appFixtureCurrentDOpenID, "--content", "hello fixture", "--yes"},
 	"chat +messages-resource-download":         {"chat", "+messages-resource-download", "--resource-id", "resource-1", "--message-id", "message-1", "--open-conversation-id", "fixture-conversation", "--output", "downloads/fixture.bin"},
 	"chat +messages-set-pin":                   {"chat", "+messages-set-pin", "--open-conversation-id", "fixture-conversation", "--msg-id", "message-1", "--yes"},
-	"chat +messages-send-by-webhook":           {"chat", "+messages-send-by-webhook", "--token", "fixture-token", "--title", "Fixture Alert", "--text", "fixture", "--at-users", "user-1,user-2", "--yes"},
+	"chat +messages-send-by-webhook":           {"chat", "+messages-send-by-webhook", "--token", "fixture-token", "--title", "Fixture Alert", "--content", "fixture", "--at-users", "user-1,user-2", "--yes"},
 	"chat +search-msg":                         {"chat", "+search-msg", "--group", "fixture-conversation", "--query", "fixture", "--start", "2026-03-10T00:00:00+08:00", "--end", "2026-03-11T00:00:00+08:00", "--no-enrich"},
-	"chat +send-to-group":                      {"chat", "+send-to-group", "--group", "Fixture Group", "--text", "hello fixture", "--yes"},
+	"chat +send-to-group":                      {"chat", "+send-to-group", "--group", "Fixture Group", "--content", "hello fixture", "--yes"},
 	"chat +unread-chats":                       {"chat", "+unread-chats", "--count", "7", "--exclude-muted"},
 	"chat bot find":                            {"chat", "bot", "find", "--query", "fixture", "--limit", "7"},
 	"chat bot search":                          {"chat", "bot", "search", "--name", "Fixture Bot", "--page", "2", "--size", "7"},
@@ -93,11 +104,11 @@ var paramAliasCompleteCommands = map[string][]string{
 	"chat message list-by-ids":                 {"chat", "message", "list-by-ids", "--msg-ids", "message-1,message-2"},
 	"chat message list-unread-conversations":   {"chat", "message", "list-unread-conversations", "--count", "7", "--exclude-muted"},
 	"chat message recall":                      {"chat", "message", "recall", "--conversation-id", "fixture-conversation", "--msg-id", "message-1", "--yes"},
-	"chat message reply":                       {"chat", "message", "reply", "--conversation-id", "fixture-conversation", "--ref-msg-id", "message-1", "--ref-sender", appFixtureCurrentDOpenID, "--text", "hello fixture", "--yes"},
+	"chat message reply":                       {"chat", "message", "reply", "--group", "fixture-conversation", "--ref-msg-id", "message-1", "--ref-sender", appFixtureCurrentDOpenID, "--content", "hello fixture", "--yes"},
 	"chat message search-advanced":             {"chat", "message", "search-advanced", "--conversation-ids", "fixture-conversation", "--query", "fixture"},
-	"chat message send":                        {"chat", "message", "send", "--user", appFixtureCurrentDOpenID, "--text", "hello fixture", "--idempotency-key", "param-alias-equivalence", "--yes"},
+	"chat message send":                        {"chat", "message", "send", "--user", appFixtureCurrentDOpenID, "--content", "hello fixture", "--idempotency-key", "param-alias-equivalence", "--yes"},
 	"chat message send-by-bot":                 {"chat", "message", "send-by-bot", "--robot-code", "robot-1", "--group", "fixture-conversation", "--title", "Fixture Alert", "--text", "@user-1 @user-2 fixture", "--at-user-ids", "user-1,user-2", "--yes"},
-	"chat message send-by-webhook":             {"chat", "message", "send-by-webhook", "--token", "fixture-token", "--title", "Fixture Alert", "--text", "fixture", "--at-users", "user-1,user-2", "--yes"},
+	"chat message send-by-webhook":             {"chat", "message", "send-by-webhook", "--token", "fixture-token", "--title", "Fixture Alert", "--content", "fixture", "--at-users", "user-1,user-2", "--yes"},
 	"contact +dept-members":                    {"contact", "+dept-members", "--dept", "Fixture Dept"},
 	"contact +list-sub-depts":                  {"contact", "+list-sub-depts", "--dept", "1"},
 	"contact +resolve-dept":                    {"contact", "+resolve-dept", "--name", "Fixture Dept"},
@@ -116,7 +127,7 @@ var paramAliasCompleteCommands = map[string][]string{
 	"doc +copy":                                {"doc", "+copy", "--node", "node-1", "--workspace", "workspace-1", "--yes"},
 	"doc +create":                              {"doc", "+create", "--name", "Fixture Document", "--content", "fixture body", "--doc-format", "markdown"},
 	"doc +create-from-template":                {"doc", "+create-from-template", "--query", "fixture template", "--name", "Fixture From Template", "--folder", "folder-1", "--workspace", "workspace-1"},
-	"doc +doc-append":                          {"doc", "+doc-append", "--doc", "node-1", "--text", "fixture appendix", "--yes"},
+	"doc +doc-append":                          {"doc", "+doc-append", "--doc", "node-1", "--content", "fixture appendix", "--yes"},
 	"doc +export-submit":                       {"doc", "+export-submit", "--node", "node-1", "--export-format", "docx"},
 	"doc +fetch":                               {"doc", "+fetch", "--node", "node-1", "--scope", "section", "--start-block-id", "block-1"},
 	"doc +find-doc":                            {"doc", "+find-doc", "--query", "fixture", "--limit", "7"},
@@ -132,8 +143,8 @@ var paramAliasCompleteCommands = map[string][]string{
 	"doc +version-save":                        {"doc", "+version-save", "--node", "node-1", "--yes"},
 	"doc +update":                              {"doc", "+update", "--node", "node-1", "--command", "overwrite", "--content", `["root",{}]`, "--doc-format", "jsonml", "--expected-revision", "1", "--yes"},
 	"doc +export":                              {"doc", "+export", "--node", "node-1", "--export-format", "docx", "--output", "exports/fixture.docx"},
-	"doc block insert":                         {"doc", "block", "insert", "--node", "node-1", "--text", "fixture paragraph", "--yes"},
-	"doc block update":                         {"doc", "block", "update", "--node", "node-1", "--block-id", "block-1", "--text", "fixture paragraph", "--yes"},
+	"doc block insert":                         {"doc", "block", "insert", "--node", "node-1", "--content", "fixture paragraph", "--yes"},
+	"doc block update":                         {"doc", "block", "update", "--node", "node-1", "--block-id", "block-1", "--content", "fixture paragraph", "--yes"},
 	"doc comment create":                       {"doc", "comment", "create", "--node", "node-1", "--content", "fixture comment", "--yes"},
 	"doc comment create-inline":                {"doc", "comment", "create-inline", "--node", "node-1", "--block-id", "block-1", "--start", "0", "--end", "7", "--content", "fixture comment", "--yes"},
 	"doc comment delete":                       {"doc", "comment", "delete", "--node", "node-1", "--comment-key", "comment-1", "--yes"},
@@ -196,7 +207,7 @@ var paramAliasCompleteCommandVariants = map[string]map[string][]string{
 		"workspace": {"doc", "+copy", "--node", "node-1", "--workspace", "workspace-1", "--yes"},
 	},
 	"doc block insert": {
-		"parent-block": {"doc", "block", "insert", "--node", "node-1", "--parent-block", "parent-block-1", "--index", "0", "--text", "fixture paragraph", "--yes"},
+		"parent-block": {"doc", "block", "insert", "--node", "node-1", "--parent-block", "parent-block-1", "--index", "0", "--content", "fixture paragraph", "--yes"},
 	},
 	"doc +inspect": {
 		"include-permissions": {"doc", "+inspect", "--node", "node-1", "--include-permissions"},
@@ -219,8 +230,8 @@ var paramAliasCompleteCommandVariants = map[string]map[string][]string{
 		"sender-open-dingtalk-id": {"chat", "message", "list-by-sender", "--sender-open-dingtalk-id", appFixtureCurrentDOpenID, "--start", "2026-03-10T00:00:00+08:00", "--end", "2026-03-11T00:00:00+08:00", "--limit", "7", "--cursor", "0"},
 	},
 	"chat message send": {
-		"group":     {"chat", "message", "send", "--group", "fixture-conversation", "--text", "hello fixture", "--idempotency-key", "param-alias-equivalence-group", "--yes"},
-		"file-path": {"chat", "message", "send", "--group", "fixture-conversation", "--msg-type", "file", "--file-path", "../../go.mod", "--dentry-id", "1", "--space-id", "2", "--idempotency-key", "param-alias-equivalence-file", "--yes"},
+		"group": {"chat", "message", "send", "--group", "fixture-conversation", "--content", "hello fixture", "--idempotency-key", "param-alias-equivalence-group", "--yes"},
+		"file":  {"chat", "message", "send", "--group", "fixture-conversation", "--msg-type", "file", "--file", "../../go.mod", "--dentry-id", "1", "--space-id", "2", "--idempotency-key", "param-alias-equivalence-file", "--yes"},
 	},
 	"chat +conversation-set-top": {
 		"conversation-ids": {"chat", "+conversation-set-top", "--conversation-ids", "fixture-conversation-1,fixture-conversation-2", "--yes"},
@@ -260,7 +271,6 @@ var paramAliasNewIMCases = []struct {
 	{command: "chat message list-favorites", emitted: "limit", canonical: "size"},
 	{command: "chat message list-unread-conversations", emitted: "limit", canonical: "count"},
 	{command: "chat message list-unread-conversations", emitted: "size", canonical: "count"},
-	{command: "chat message send", emitted: "file", canonical: "file-path"},
 	{command: "chat message send-by-bot", emitted: "at-users", canonical: "at-user-ids"},
 	{command: "chat message send-by-webhook", emitted: "at-user-ids", canonical: "at-users"},
 	{command: "chat +chat-update", emitted: "chat-id", canonical: "group"},
@@ -278,7 +288,7 @@ var paramAliasNewIMCases = []struct {
 	{command: "chat +chat-members-get", emitted: "chat", canonical: "id"},
 	{command: "chat +messages-list", emitted: "start", canonical: "time"},
 	{command: "chat +messages-reply", emitted: "msg-id", canonical: "ref-msg-id"},
-	{command: "chat +messages-reply", emitted: "chat", canonical: "conversation-id"},
+	{command: "chat +messages-reply", emitted: "chat", canonical: "group"},
 	{command: "chat +flag-cancel", emitted: "group", canonical: "conversation-id"},
 	{command: "chat +flag-cancel", emitted: "chat", canonical: "conversation-id"},
 	{command: "chat +flag-create", emitted: "group", canonical: "conversation-id"},
@@ -372,16 +382,113 @@ var paramAliasNewDriveCases = []struct {
 	{command: "drive +upload", emitted: "file-id", canonical: "node"},
 }
 
-// paramAliasNewDriveConfirmationCases selects one newly reviewed alias for
-// every Drive command in the expansion whose declared runtime safety requires
-// confirmation. The full matrix below proves all spellings preserve the
-// confirmed payload; this smaller matrix proves aliases cannot cross the
-// confirmation boundary before any transport call is made.
-var paramAliasNewDriveConfirmationCases = []struct {
+// paramAliasAITableDeleteDisableCompleteCommands contains complete invocations
+// for every AITable delete/disable command whose confirmation boundary is
+// reached by aliases introduced in the AITable expansion. These templates are
+// intentionally separate from paramAliasCompleteCommands: that map mirrors
+// the reviewed validation fixture one-for-one, while this matrix exhaustively
+// proves the safety boundary for generated aliases beyond the fixture sample.
+var paramAliasAITableDeleteDisableCompleteCommands = map[string][]string{
+	"aitable +advperm-disable":      {"aitable", "+advperm-disable", "--base-id", "base-1", "--yes"},
+	"aitable +base-delete":          {"aitable", "+base-delete", "--base-id", "base-1", "--yes"},
+	"aitable +chart-delete":         {"aitable", "+chart-delete", "--base-id", "base-1", "--dashboard-id", "dashboard-1", "--chart-id", "chart-1", "--yes"},
+	"aitable +dashboard-delete":     {"aitable", "+dashboard-delete", "--base-id", "base-1", "--dashboard-id", "dashboard-1", "--yes"},
+	"aitable +field-delete":         {"aitable", "+field-delete", "--base-id", "base-1", "--table-id", "table-1", "--field-id", "field-1", "--yes"},
+	"aitable +form-delete":          {"aitable", "+form-delete", "--base-id", "base-1", "--table-id", "table-1", "--view-id", "view-1", "--yes"},
+	"aitable +record-delete":        {"aitable", "+record-delete", "--base-id", "base-1", "--table-id", "table-1", "--record-ids", "record-1", "--yes"},
+	"aitable +role-delete":          {"aitable", "+role-delete", "--base-id", "base-1", "--role-id", "role-1", "--yes"},
+	"aitable +section-delete":       {"aitable", "+section-delete", "--base-id", "base-1", "--section-id", "section-1", "--yes"},
+	"aitable +table-delete":         {"aitable", "+table-delete", "--base-id", "base-1", "--table-id", "table-1", "--yes"},
+	"aitable +view-delete":          {"aitable", "+view-delete", "--base-id", "base-1", "--table-id", "table-1", "--view-id", "view-1", "--yes"},
+	"aitable +workflow-disable":     {"aitable", "+workflow-disable", "--base-id", "base-1", "--workflow-id", "workflow-1", "--yes"},
+	"aitable advperm disable":       {"aitable", "advperm", "disable", "--base-id", "base-1", "--yes"},
+	"aitable advperm role-delete":   {"aitable", "advperm", "role-delete", "--base-id", "base-1", "--role-id", "role-1", "--yes"},
+	"aitable base delete":           {"aitable", "base", "delete", "--base-id", "base-1", "--yes"},
+	"aitable chart delete":          {"aitable", "chart", "delete", "--base-id", "base-1", "--dashboard-id", "dashboard-1", "--chart-id", "chart-1", "--yes"},
+	"aitable dashboard delete":      {"aitable", "dashboard", "delete", "--base-id", "base-1", "--dashboard-id", "dashboard-1", "--yes"},
+	"aitable field delete":          {"aitable", "field", "delete", "--base-id", "base-1", "--table-id", "table-1", "--field-id", "field-1", "--yes"},
+	"aitable form delete":           {"aitable", "form", "delete", "--base-id", "base-1", "--table-id", "table-1", "--view-id", "view-1", "--yes"},
+	"aitable form questions delete": {"aitable", "form", "questions", "delete", "--base-id", "base-1", "--table-id", "table-1", "--field-id", "field-1", "--yes"},
+	"aitable record delete":         {"aitable", "record", "delete", "--base-id", "base-1", "--table-id", "table-1", "--record-ids", "record-1", "--yes"},
+	"aitable table delete":          {"aitable", "table", "delete", "--base-id", "base-1", "--table-id", "table-1", "--yes"},
+	"aitable view delete":           {"aitable", "view", "delete", "--base-id", "base-1", "--table-id", "table-1", "--view-id", "view-1", "--yes"},
+	"aitable workflow disable":      {"aitable", "workflow", "disable", "--base-id", "base-1", "--workflow-id", "workflow-1", "--yes"},
+}
+
+// paramAliasNewAITableDeleteDisableCases is the exhaustive set of alias
+// tuples newly introduced by this change on AITable delete/disable commands
+// that require confirmation. Every tuple must remain on both sides of the
+// confirmation gate: rejected with zero calls before --yes, and exactly
+// payload-equivalent to its canonical spelling after --yes.
+var paramAliasNewAITableDeleteDisableCases = []struct {
 	command   string
 	emitted   string
 	canonical string
 }{
+	{command: "aitable +advperm-disable", emitted: "base", canonical: "base-id"},
+	{command: "aitable +advperm-disable", emitted: "base-token", canonical: "base-id"},
+	{command: "aitable +base-delete", emitted: "base", canonical: "base-id"},
+	{command: "aitable +base-delete", emitted: "base-token", canonical: "base-id"},
+	{command: "aitable +chart-delete", emitted: "base", canonical: "base-id"},
+	{command: "aitable +chart-delete", emitted: "base-token", canonical: "base-id"},
+	{command: "aitable +dashboard-delete", emitted: "base", canonical: "base-id"},
+	{command: "aitable +dashboard-delete", emitted: "base-token", canonical: "base-id"},
+	{command: "aitable +field-delete", emitted: "base", canonical: "base-id"},
+	{command: "aitable +field-delete", emitted: "base-token", canonical: "base-id"},
+	{command: "aitable +field-delete", emitted: "table", canonical: "table-id"},
+	{command: "aitable +form-delete", emitted: "base", canonical: "base-id"},
+	{command: "aitable +form-delete", emitted: "base-token", canonical: "base-id"},
+	{command: "aitable +form-delete", emitted: "table", canonical: "table-id"},
+	{command: "aitable +record-delete", emitted: "base", canonical: "base-id"},
+	{command: "aitable +record-delete", emitted: "base-token", canonical: "base-id"},
+	{command: "aitable +record-delete", emitted: "table", canonical: "table-id"},
+	{command: "aitable +role-delete", emitted: "base", canonical: "base-id"},
+	{command: "aitable +role-delete", emitted: "base-token", canonical: "base-id"},
+	{command: "aitable +section-delete", emitted: "base", canonical: "base-id"},
+	{command: "aitable +section-delete", emitted: "base-token", canonical: "base-id"},
+	{command: "aitable +table-delete", emitted: "base", canonical: "base-id"},
+	{command: "aitable +table-delete", emitted: "base-token", canonical: "base-id"},
+	{command: "aitable +table-delete", emitted: "table", canonical: "table-id"},
+	{command: "aitable +view-delete", emitted: "base", canonical: "base-id"},
+	{command: "aitable +view-delete", emitted: "base-token", canonical: "base-id"},
+	{command: "aitable +view-delete", emitted: "table", canonical: "table-id"},
+	{command: "aitable +workflow-disable", emitted: "base", canonical: "base-id"},
+	{command: "aitable +workflow-disable", emitted: "base-token", canonical: "base-id"},
+	{command: "aitable +workflow-disable", emitted: "flow-id", canonical: "workflow-id"},
+	{command: "aitable advperm disable", emitted: "base-token", canonical: "base-id"},
+	{command: "aitable advperm role-delete", emitted: "base-token", canonical: "base-id"},
+	{command: "aitable base delete", emitted: "base-token", canonical: "base-id"},
+	{command: "aitable chart delete", emitted: "base-token", canonical: "base-id"},
+	{command: "aitable dashboard delete", emitted: "base-token", canonical: "base-id"},
+	{command: "aitable field delete", emitted: "base-token", canonical: "base-id"},
+	{command: "aitable field delete", emitted: "table", canonical: "table-id"},
+	{command: "aitable form delete", emitted: "base-token", canonical: "base-id"},
+	{command: "aitable form delete", emitted: "table", canonical: "table-id"},
+	{command: "aitable form questions delete", emitted: "base-token", canonical: "base-id"},
+	{command: "aitable form questions delete", emitted: "table", canonical: "table-id"},
+	{command: "aitable record delete", emitted: "base-token", canonical: "base-id"},
+	{command: "aitable record delete", emitted: "table", canonical: "table-id"},
+	{command: "aitable table delete", emitted: "base-token", canonical: "base-id"},
+	{command: "aitable table delete", emitted: "table", canonical: "table-id"},
+	{command: "aitable view delete", emitted: "base-token", canonical: "base-id"},
+	{command: "aitable view delete", emitted: "table", canonical: "table-id"},
+	{command: "aitable workflow disable", emitted: "base-token", canonical: "base-id"},
+	{command: "aitable workflow disable", emitted: "flow-id", canonical: "workflow-id"},
+}
+
+// paramAliasNewConfirmationCases selects newly reviewed aliases for commands
+// whose declared runtime safety requires confirmation. The full matrix below
+// proves all spellings preserve the confirmed payload; this smaller matrix
+// proves aliases cannot cross the confirmation boundary before any transport
+// call is made.
+var paramAliasNewConfirmationCases = []struct {
+	command   string
+	emitted   string
+	canonical string
+}{
+	{command: "aitable workflow run", emitted: "base-token", canonical: "base-id"},
+	{command: "aitable workflow run", emitted: "flow-id", canonical: "workflow-id"},
+	{command: "aitable workflow run", emitted: "table", canonical: "table-id"},
 	{command: "drive +delete", emitted: "file-id", canonical: "node"},
 	{command: "drive +publish-unset", emitted: "document-url", canonical: "node"},
 	{command: "drive +recycle-restore", emitted: "recycle-item-id", canonical: "id"},
@@ -402,7 +509,27 @@ var paramAliasNewDriveConfirmationCases = []struct {
 // That duplicated command construction was enough to push the pre-existing
 // macOS app suite beyond its package-level 10-minute timeout.
 var paramAliasRepresentativePayloadCases = map[string]bool{
+	paramAliasPayloadCaseKey("aitable +export-data", "export-format"):                true, // shortcut-local export format keeps the final payload
+	paramAliasPayloadCaseKey("aitable +find-record", "base-id"):                      true, // shortcut Base ID compatibility
+	paramAliasPayloadCaseKey("aitable +find-record", "table-id"):                     true, // shortcut Table ID compatibility
 	paramAliasPayloadCaseKey("aitable +record-query", "base"):                        true, // concept alias on a shortcut read
+	paramAliasPayloadCaseKey("aitable +record-share-links", "base-id"):               true, // observed experiment Base ID spelling
+	paramAliasPayloadCaseKey("aitable +record-share-links", "table-id"):              true, // observed experiment Table ID spelling
+	paramAliasPayloadCaseKey("aitable +workflow-list", "max-results"):                true, // shortcut pagination-size alias
+	paramAliasPayloadCaseKey("aitable attachment upload", "file-size"):               true, // byte-size command override
+	paramAliasPayloadCaseKey("aitable base list", "next-cursor"):                     true, // cursor concept alias
+	paramAliasPayloadCaseKey("aitable base update", "description"):                   true, // plain description alias on a write command
+	paramAliasPayloadCaseKey("aitable field search-options", "query"):                true, // search keyword concept alias
+	paramAliasPayloadCaseKey("aitable workflow get", "flow-id"):                      true, // workflow ID concept alias
+	paramAliasPayloadCaseKey("aitable workflow history", "base-token"):               true, // Base ID concept alias
+	paramAliasPayloadCaseKey("aitable workflow history", "end-time"):                 true, // upper time-bound override
+	paramAliasPayloadCaseKey("aitable workflow history", "flow-id"):                  true, // workflow ID concept alias
+	paramAliasPayloadCaseKey("aitable workflow history", "page-index"):               true, // zero-based page override
+	paramAliasPayloadCaseKey("aitable workflow history", "page-size"):                true, // page-size concept alias
+	paramAliasPayloadCaseKey("aitable workflow history", "start-time"):               true, // lower time-bound override
+	paramAliasPayloadCaseKey("aitable workflow run", "base-token"):                   true, // Base ID concept alias on a confirmed write
+	paramAliasPayloadCaseKey("aitable workflow run", "flow-id"):                      true, // workflow ID concept alias on a confirmed write
+	paramAliasPayloadCaseKey("aitable workflow run", "table"):                        true, // Table ID concept alias on a confirmed write
 	paramAliasPayloadCaseKey("attendance check result", "user-ids"):                  true, // list-valued concept alias
 	paramAliasPayloadCaseKey("calendar event list", "date"):                          true, // time concept alias
 	paramAliasPayloadCaseKey("chat message add-favorite", "msg-id"):                  true, // scoped IM identifier alias
@@ -426,7 +553,11 @@ var paramAliasRepresentativePayloadCases = map[string]bool{
 	paramAliasPayloadCaseKey("doc +update", "revision"):                              true, // optimistic edit revision alias
 	paramAliasPayloadCaseKey("doc +access-grant", "doc-id"):                          true, // permission write keeps document identity
 	paramAliasPayloadCaseKey("doc +version-revert", "version-number"):                true, // high-write version role with canonical confirmation
-	paramAliasPayloadCaseKey("doc block insert", "content"):                          true, // block write content alias
+	paramAliasPayloadCaseKey("chat +messages-reply", "conversation-id"):              true, // renamed conversation Primary keeps final reply payload
+	paramAliasPayloadCaseKey("chat message send", "file-path"):                       true, // renamed local-file Primary reaches the same final payload
+	paramAliasPayloadCaseKey("doc +doc-append", "text"):                              true, // shortcut content rename keeps append payload
+	paramAliasPayloadCaseKey("doc block insert", "text"):                             true, // block write content compatibility alias
+	paramAliasPayloadCaseKey("doc block update", "text"):                             true, // update uses the same typed compatibility path
 	paramAliasPayloadCaseKey("doc block insert", "parent-block-id"):                  true, // scoped block-role alias
 	paramAliasPayloadCaseKey("doc comment delete", "comment-id"):                     true, // destructive comment-key alias
 	paramAliasPayloadCaseKey("doc comment reply", "mentioned-open-conversation-ids"): true, // list-valued group mention role
@@ -629,13 +760,116 @@ func TestCrossPlatformCoverageNewDriveParamAliasesReachCanonicalEquivalentFinalP
 	}
 }
 
-func TestCrossPlatformCoverageNewDriveParamAliasesCannotBypassConfirmation(t *testing.T) {
-	for _, test := range paramAliasNewDriveConfirmationCases {
+func TestCrossPlatformCoverageNewAITableDeleteDisableAliasesPreserveConfirmationAndPayload(t *testing.T) {
+	coveredCommands := make(map[string]bool)
+	reviewedAliases := make(map[string]string, len(paramAliasNewAITableDeleteDisableCases))
+	for _, test := range paramAliasNewAITableDeleteDisableCases {
+		test := test
+		caseKey := paramAliasPayloadCaseKey(test.command, test.emitted)
+		if previous, duplicate := reviewedAliases[caseKey]; duplicate {
+			t.Fatalf("duplicate AITable delete/disable alias case %q: --%s and --%s", caseKey, previous, test.canonical)
+		}
+		reviewedAliases[caseKey] = test.canonical
+		t.Run(test.command+"/"+test.emitted, func(t *testing.T) {
+			complete, ok := paramAliasAITableDeleteDisableCompleteCommands[test.command]
+			if !ok {
+				t.Fatal("reviewed AITable delete/disable alias has no complete safety template")
+			}
+			coveredCommands[test.command] = true
+
+			canonicalArgs := append([]string(nil), complete...)
+			aliasArgs, replacements := replaceLongFlag(canonicalArgs, test.canonical, test.emitted)
+			if replacements != 1 {
+				t.Fatalf("complete command must contain canonical --%s exactly once; replacements=%d args=%v", test.canonical, replacements, canonicalArgs)
+			}
+			unconfirmedArgs, removals := removeExactArg(aliasArgs, "--yes")
+			if removals != 1 {
+				t.Fatalf("safety template must contain --yes exactly once; removals=%d args=%v", removals, aliasArgs)
+			}
+
+			entry, exists := cli.LookupParamAlias(test.command)
+			target, active := entry.ResolveAlias(test.emitted)
+			if !exists || !active || target != test.canonical {
+				t.Fatalf("reviewed AITable alias --%s resolution = exists:%v active:%v target:%q, want --%s", test.emitted, exists, active, target, test.canonical)
+			}
+
+			unconfirmedCaller := &paramAliasCaptureCaller{}
+			ctx, unconfirmedErr := executeParamAliasPayloadE2E(t, unconfirmedCaller, unconfirmedArgs...)
+			if ctx == nil {
+				t.Fatal("unconfirmed AITable alias command skipped PreParse")
+			}
+			var appErr *apperrors.Error
+			if !errors.As(unconfirmedErr, &appErr) || appErr.Reason != "confirmation_required" {
+				t.Fatalf("unconfirmed AITable alias command error = %#v, want confirmation_required\nargs=%v", unconfirmedErr, unconfirmedArgs)
+			}
+			if len(unconfirmedCaller.calls) != 0 {
+				t.Fatalf("unconfirmed AITable alias crossed the transport boundary: args=%v calls=%#v", unconfirmedArgs, unconfirmedCaller.calls)
+			}
+
+			canonicalCaller := &paramAliasCaptureCaller{}
+			_, canonicalErr := executeParamAliasPayloadE2E(t, canonicalCaller, canonicalArgs...)
+			if canonicalErr != nil {
+				t.Fatalf("confirmed canonical command failed: %v\nargs=%v\ncalls=%#v", canonicalErr, canonicalArgs, canonicalCaller.calls)
+			}
+			if len(canonicalCaller.calls) == 0 {
+				t.Fatalf("confirmed canonical command reached no final transport payload: args=%v", canonicalArgs)
+			}
+
+			aliasCaller := &paramAliasCaptureCaller{}
+			aliasCtx, aliasErr := executeParamAliasPayloadE2E(t, aliasCaller, aliasArgs...)
+			if aliasErr != nil {
+				t.Fatalf("confirmed alias command failed: %v\nargs=%v\ncalls=%#v", aliasErr, aliasArgs, aliasCaller.calls)
+			}
+			if aliasCtx == nil {
+				t.Fatal("confirmed AITable alias command skipped PreParse")
+			}
+			if !reflect.DeepEqual(aliasCaller.calls, canonicalCaller.calls) {
+				t.Fatalf("confirmed final transport calls differ\ncanonical args: %v\nalias args: %v\ncanonical calls: %#v\nalias calls: %#v", canonicalArgs, aliasArgs, canonicalCaller.calls, aliasCaller.calls)
+			}
+		})
+	}
+
+	for command := range paramAliasAITableDeleteDisableCompleteCommands {
+		if !coveredCommands[command] {
+			t.Errorf("AITable delete/disable safety template %q has no reviewed alias case", command)
+		}
+	}
+	if len(coveredCommands) != len(paramAliasAITableDeleteDisableCompleteCommands) {
+		t.Fatalf("AITable delete/disable safety coverage = %d commands, want %d", len(coveredCommands), len(paramAliasAITableDeleteDisableCompleteCommands))
+	}
+
+	activeAliases := 0
+	for command := range paramAliasAITableDeleteDisableCompleteCommands {
+		entry, exists := cli.LookupParamAlias(command)
+		if !exists {
+			t.Errorf("AITable delete/disable safety command %q has no generated alias entry", command)
+			continue
+		}
+		for emitted, canonical := range entry.Aliases {
+			activeAliases++
+			caseKey := paramAliasPayloadCaseKey(command, emitted)
+			reviewedCanonical, reviewed := reviewedAliases[caseKey]
+			if !reviewed {
+				t.Errorf("active AITable delete/disable alias %q --%s -> --%s has no confirmation/payload case", command, emitted, canonical)
+				continue
+			}
+			if reviewedCanonical != canonical {
+				t.Errorf("reviewed AITable delete/disable alias %q --%s target = --%s, generated --%s", command, emitted, reviewedCanonical, canonical)
+			}
+		}
+	}
+	if activeAliases != len(reviewedAliases) {
+		t.Fatalf("AITable delete/disable generated alias coverage = %d, want %d reviewed cases", activeAliases, len(reviewedAliases))
+	}
+}
+
+func TestCrossPlatformCoverageNewParamAliasesCannotBypassConfirmation(t *testing.T) {
+	for _, test := range paramAliasNewConfirmationCases {
 		test := test
 		t.Run(test.command+"/"+test.emitted, func(t *testing.T) {
 			complete, ok := paramAliasCompleteCommand(test.command, test.canonical)
 			if !ok {
-				t.Fatal("reviewed Drive confirmation alias has no complete-command E2E template")
+				t.Fatal("reviewed confirmation alias has no complete-command E2E template")
 			}
 			aliasArgs, replacements := replaceLongFlag(complete, test.canonical, test.emitted)
 			if replacements != 1 {
@@ -649,7 +883,7 @@ func TestCrossPlatformCoverageNewDriveParamAliasesCannotBypassConfirmation(t *te
 			entry, exists := cli.LookupParamAlias(test.command)
 			target, active := entry.ResolveAlias(test.emitted)
 			if !exists || !active || target != test.canonical {
-				t.Fatalf("reviewed Drive alias --%s resolution = exists:%v active:%v target:%q, want --%s", test.emitted, exists, active, target, test.canonical)
+				t.Fatalf("reviewed confirmation alias --%s resolution = exists:%v active:%v target:%q, want --%s", test.emitted, exists, active, target, test.canonical)
 			}
 
 			caller := &paramAliasCaptureCaller{}

internal/app/root_help_test.go

@@ -264,7 +264,7 @@ func TestRootChatMediaUploadWithoutAppCredentialsReturnsMigrationValidation(t *t
 	}
 
 	got := output.String() + "\n" + err.Error()
-	for _, want := range []string{"已下线", "chat message send --msg-type file --file-path"} {
+	for _, want := range []string{"已下线", "chat message send --msg-type file --file"} {
 		if !strings.Contains(got, want) {
 			t.Fatalf("chat media upload migration output missing %q:\n%s", want, got)
 		}
@@ -439,7 +439,7 @@ func TestChatFileUploadDownlinedButMessageFileSendStays(t *testing.T) {
 		t.Fatalf("chat file upload error = nil, want downline error\n%s", got)
 	}
 	got = got + "\n" + err.Error()
-	for _, want := range []string{"已下线", "upload_conversation_file_by_url", "chat message send --msg-type file --file-path"} {
+	for _, want := range []string{"已下线", "upload_conversation_file_by_url", "chat message send --msg-type file --file"} {
 		if !strings.Contains(got, want) {
 			t.Fatalf("chat file upload output missing %q:\n%s", want, got)
 		}
@@ -462,6 +462,53 @@ func TestCalendarEventListDryRunPreviewsOnly(t *testing.T) {
 	}
 }
 
+func TestCalendarEventShareInfoDryRunPreviewsOnly(t *testing.T) {
+	got, err := executeRootCaptureStdout(t, []string{
+		"--dry-run", "calendar", "event", "share-info",
+		"--id", "EVT_001",
+		"--language", "zh-CN",
+		"--calendar-id", "primary",
+	})
+	if err != nil {
+		t.Fatalf("calendar event share-info --dry-run error = %v\n%s", err, got)
+	}
+	for _, want := range []string{"get_event_share_info", "eventId", "EVT_001", "zh-CN", "primary"} {
+		if !strings.Contains(got, want) {
+			t.Fatalf("calendar event share-info dry-run output missing %q:\n%s", want, got)
+		}
+	}
+}
+
+func TestCalendarEventShareInfoRequiresEventID(t *testing.T) {
+	got, err := executeRootCaptureStdout(t, []string{
+		"--dry-run", "calendar", "event", "share-info",
+	})
+	if err == nil {
+		t.Fatalf("calendar event share-info without --id: expected error, got nil\n%s", got)
+	}
+	if strings.Contains(got, "\"executed\": true") {
+		t.Fatalf("share-info without --id must not execute:\n%s", got)
+	}
+}
+
+func TestCalendarEventShareInfoOmitsOptionalArgs(t *testing.T) {
+	got, err := executeRootCaptureStdout(t, []string{
+		"--dry-run", "calendar", "event", "share-info",
+		"--id", "EVT_001",
+	})
+	if err != nil {
+		t.Fatalf("calendar event share-info --dry-run with only --id error = %v\n%s", err, got)
+	}
+	if !strings.Contains(got, "\"eventId\"") {
+		t.Fatalf("calendar event share-info dry-run output missing eventId:\n%s", got)
+	}
+	for _, unwanted := range []string{"\"calendarId\"", "\"language\""} {
+		if strings.Contains(got, unwanted) {
+			t.Fatalf("calendar event share-info dry-run with only --id should not contain %q:\n%s", unwanted, got)
+		}
+	}
+}
+
 func TestRootKeepsSVIPChatCompatibilityFlags(t *testing.T) {
 	root := NewRootCommand()
 

internal/app/schema_calendar_shortcut_contract_test.go

@@ -0,0 +1,49 @@
+// 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 app
+
+import "testing"
+
+func TestCrossPlatformCoverageCalendarAgendaFinalSchemaPreservesCompositeProperties(t *testing.T) {
+	snapshot := fullSchemaSnapshotForTest(t)
+	tool := snapshot.Tools["calendar.shortcut_agenda"]
+	if tool == nil {
+		t.Fatal("calendar.shortcut_agenda is missing from final Schema")
+	}
+	parameters := schemaContractMap(tool["parameters"])
+	for flag, want := range map[string]string{
+		"start": "start",
+		"end":   "end",
+	} {
+		parameter := parameters[flag]
+		if parameter == nil {
+			t.Fatalf("calendar.shortcut_agenda --%s is missing from final Schema", flag)
+		}
+		if got := schemaContractString(parameter["property"]); got != want {
+			t.Errorf("calendar.shortcut_agenda --%s property=%q, want %q", flag, got, want)
+		}
+	}
+	if got := schemaContractString(tool["interface_mode"]); got != "composite" {
+		t.Fatalf("calendar.shortcut_agenda interface_mode=%q, want composite", got)
+	}
+	result := schemaContractMap(tool["result"])
+	dataSchema := schemaContractMap(result["data_schema"])
+	properties := schemaContractMap(dataSchema["properties"])
+	for _, field := range []string{"hasMore", "nextCursor"} {
+		if _, exists := properties[field]; exists {
+			t.Fatalf("calendar.shortcut_agenda Result data_schema leaked pagination field %q", field)
+		}
+	}
+	if properties["complete"] == nil {
+		t.Fatal("calendar.shortcut_agenda Result data_schema is missing complete")
+	}
+	pagination, ok := tool["pagination"].(map[string]any)
+	if !ok {
+		t.Fatalf("calendar.shortcut_agenda pagination=%T, want object", tool["pagination"])
+	}
+	if got := schemaContractString(pagination["meta_path"]); got != "meta.pagination" {
+		t.Fatalf("calendar.shortcut_agenda pagination meta_path=%q, want meta.pagination", got)
+	}
+}

internal/app/schema_contract_test.go

@@ -400,6 +400,7 @@ func schemaContractPayloadForBoundCanonicals(t *testing.T, root *cobra.Command,
 func TestChatSchemaSeparatesSendAndReply(t *testing.T) {
 	snapshot := schemaContractPayloadForBoundCanonicals(t, NewRootCommand(),
 		"chat.send_personal_message",
+		"chat.send_robot_message",
 		"chat.reply_personal_message",
 	)
 
@@ -418,6 +419,19 @@ func TestChatSchemaSeparatesSendAndReply(t *testing.T) {
 	if _, exists := snapshot.Tools["chat.upload_conversation_file"]; exists {
 		t.Fatal("downlined chat file upload must not be advertised in Schema")
 	}
+
+	botReply := snapshot.Tools["chat.send_robot_message"]
+	botParams := schemaContractMap(botReply["parameters"])
+	if got := schemaContractString(botParams["reply"]["property"]); got != "referenceOpenMessageId" {
+		t.Fatalf("bot --reply property = %q", got)
+	}
+	if got := schemaContractString(botParams["ref-sender"]["property"]); got != "srcMsgSendOpenDingTalkId" {
+		t.Fatalf("bot --ref-sender property = %q", got)
+	}
+	if got, ok := botParams["title"]["required"].(bool); !ok || got {
+		t.Fatalf("bot --title required = %#v, want false for conditional Markdown input", botParams["title"]["required"])
+	}
+	assertSchemaContractConstraintGroup(t, botReply, "require_together", []string{"reply", "ref-sender"})
 }
 
 func TestCalendarAttendeeDeleteSchemaMatchesRuntimeGate(t *testing.T) {

internal/app/schema_oa_attachment_contract_test.go

@@ -0,0 +1,166 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+
+package app
+
+import (
+	"bytes"
+	"encoding/json"
+	"reflect"
+	"strings"
+	"testing"
+)
+
+func TestCrossPlatformCoverageOAAttachmentDeliveredSchemaMatchesExecutableHelp(t *testing.T) {
+	tests := []struct {
+		cliPath        string
+		canonical      string
+		rpc            string
+		description    string
+		effect         string
+		resultType     string
+		resultFields   map[string]string
+		sensitivePaths []string
+	}{
+		{
+			cliPath:     "oa approval attachment download-url",
+			canonical:   "oa.get_attachment_download_url",
+			rpc:         "get_attachment_download_url",
+			description: "获取审批附件下载授权并生成临时下载链接",
+			effect:      "read",
+			resultType:  "object",
+			resultFields: map[string]string{
+				"spaceId": "integer", "agentId": "integer", "downloadUri": "string",
+				"class": "string", "fileId": "string",
+			},
+			sensitivePaths: []string{"downloadUri"},
+		},
+		{
+			cliPath:     "oa approval attachment authorize-download",
+			canonical:   "oa.auth_download_file",
+			rpc:         "auth_download_file",
+			description: "批量授权当前用户下载指定的审批钉盘文件",
+			effect:      "write",
+			resultType:  "boolean",
+		},
+		{
+			cliPath:     "oa approval attachment authorize-preview",
+			canonical:   "oa.auth_preview_attachment",
+			rpc:         "auth_preview_attachment",
+			description: "批量授权当前用户预览审批单中的附件",
+			effect:      "write",
+			resultType:  "object",
+			resultFields: map[string]string{
+				"spaceId": "integer", "agentId": "integer", "class": "string",
+			},
+		},
+	}
+
+	for _, test := range tests {
+		t.Run(test.rpc, func(t *testing.T) {
+			root := NewRootCommand()
+			command := exactCommandForTest(root, test.cliPath)
+			if command == nil {
+				t.Fatalf("executable command %q is missing", test.cliPath)
+			}
+
+			var stdout, stderr bytes.Buffer
+			root.SetOut(&stdout)
+			root.SetErr(&stderr)
+			root.SetArgs([]string{"schema", test.cliPath, "--format", "json"})
+			if err := root.Execute(); err != nil {
+				t.Fatalf("execute delivery schema leaf: %v; stderr=%s", err, stderr.String())
+			}
+
+			var tool map[string]any
+			if err := json.Unmarshal(stdout.Bytes(), &tool); err != nil {
+				t.Fatalf("decode delivery schema leaf: %v", err)
+			}
+			if got := schemaContractString(tool["canonical_path"]); got != test.canonical {
+				t.Fatalf("canonical_path = %q, want %q", got, test.canonical)
+			}
+			if got := schemaContractString(tool["primary_cli_path"]); got != test.cliPath {
+				t.Fatalf("primary_cli_path = %q, want %q", got, test.cliPath)
+			}
+			if got := schemaContractString(tool["description"]); !strings.HasPrefix(got, test.description) {
+				t.Fatalf("description = %q, want prefix %q", got, test.description)
+			}
+			if got := schemaContractString(tool["interface_mode"]); got != "mcp" {
+				t.Fatalf("interface_mode = %q, want mcp", got)
+			}
+			if got := schemaContractString(tool["availability"]); got != "available" {
+				t.Fatalf("availability = %q, want available", got)
+			}
+			interfaceRef := schemaInterfaceObject(tool["interface_ref"])
+			if got := schemaContractString(interfaceRef["product_id"]); got != "oa" {
+				t.Fatalf("interface_ref.product_id = %q, want oa", got)
+			}
+			if got := schemaContractString(interfaceRef["rpc_name"]); got != test.rpc {
+				t.Fatalf("interface_ref.rpc_name = %q, want %q", got, test.rpc)
+			}
+			if got := schemaContractString(tool["effect"]); got != test.effect {
+				t.Fatalf("effect = %q, want %q", got, test.effect)
+			}
+			if got := schemaContractString(tool["risk"]); got != "low" {
+				t.Fatalf("risk = %q, want low", got)
+			}
+			if got := schemaContractString(tool["confirmation"]); got != "not_required" {
+				t.Fatalf("confirmation = %q, want not_required", got)
+			}
+			if got := schemaContractString(tool["idempotency"]); got != "idempotent" {
+				t.Fatalf("idempotency = %q, want idempotent", got)
+			}
+			fullResult := oaAttachmentResultContract(t, tool, test.resultType, test.resultFields, test.sensitivePaths)
+
+			stdout.Reset()
+			stderr.Reset()
+			root.SetArgs([]string{"schema", test.cliPath, "--compact", "--format", "json"})
+			if err := root.Execute(); err != nil {
+				t.Fatalf("execute compact delivery schema leaf: %v; stderr=%s", err, stderr.String())
+			}
+			var compactTool map[string]any
+			if err := json.Unmarshal(stdout.Bytes(), &compactTool); err != nil {
+				t.Fatalf("decode compact delivery schema leaf: %v", err)
+			}
+			compactResult, ok := compactTool["result"].(map[string]any)
+			if !ok {
+				t.Fatalf("compact result = %#v, want object", compactTool["result"])
+			}
+			if !reflect.DeepEqual(compactResult, fullResult) {
+				t.Fatalf("compact/full result projection differs\ncompact: %#v\nfull: %#v", compactResult, fullResult)
+			}
+			if problem := schemaHelpFlagCompletenessProblem(test.canonical, test.cliPath, command, tool); problem != "" {
+				t.Fatal(problem)
+			}
+		})
+	}
+}
+
+func oaAttachmentResultContract(t *testing.T, tool map[string]any, resultType string, fields map[string]string, sensitivePaths []string) map[string]any {
+	t.Helper()
+	result, ok := tool["result"].(map[string]any)
+	if !ok {
+		t.Fatalf("full result = %#v, want object", tool["result"])
+	}
+	if got, want := schemaContractStringSlice(result["outcomes"]), []string{"success", "failure"}; !reflect.DeepEqual(got, want) {
+		t.Fatalf("result.outcomes = %#v, want %#v", got, want)
+	}
+	if got := schemaContractStringSlice(result["sensitive_paths"]); !reflect.DeepEqual(got, sensitivePaths) {
+		t.Fatalf("result.sensitive_paths = %#v, want %#v", got, sensitivePaths)
+	}
+	dataSchema, ok := result["data_schema"].(map[string]any)
+	if !ok || schemaContractString(dataSchema["type"]) != resultType {
+		t.Fatalf("result.data_schema = %#v, want type %q", result["data_schema"], resultType)
+	}
+	properties, _ := dataSchema["properties"].(map[string]any)
+	if len(properties) != len(fields) {
+		t.Fatalf("result.data_schema.properties = %#v, want fields %#v", properties, fields)
+	}
+	for name, fieldType := range fields {
+		property, ok := properties[name].(map[string]any)
+		if !ok || schemaContractString(property["type"]) != fieldType {
+			t.Fatalf("result.data_schema.properties.%s = %#v, want type %q", name, properties[name], fieldType)
+		}
+	}
+	return result
+}

internal/app/schema_shortcut_contract_test.go

@@ -16,12 +16,12 @@ import (
 )
 
 const (
-	publicShortcutCount = 418
+	publicShortcutCount = 435
 	// schemaPublishedShortcutCount counts every delivered *.shortcut_* tool,
 	// including the hidden historical minutes.shortcut_minutes_search contract.
-	schemaPublishedShortcutCount = 420
+	schemaPublishedShortcutCount = 438
 	// publiclyDeliveredShortcutCount is the public-catalog subset of that surface.
-	publiclyDeliveredShortcutCount = 418
+	publiclyDeliveredShortcutCount = 435
 )
 
 func TestDeliverySchemaCoversOrExactlyExcludesEveryPublicShortcutContract(t *testing.T) {
@@ -140,6 +140,25 @@ func TestDeliveryShortcutProgressiveQueriesReturnCompleteContracts(t *testing.T)
 	assertChatCatalogCompleteLeafContracts(t)
 }
 
+func TestCrossPlatformCoverageAITableTableBootstrapPublishesResultContract(t *testing.T) {
+	leaf := executeShortcutSchemaQuery(t, "--cli-path", "aitable +table-bootstrap")
+	result, _ := leaf["result"].(map[string]any)
+	if got, want := schemaContractStringSlice(result["outcomes"]), []string{"success", "failure"}; !schemaContractJSONEqual(got, want) {
+		t.Fatalf("aitable +table-bootstrap outcomes = %#v, want %#v", got, want)
+	}
+	dataSchema, _ := result["data_schema"].(map[string]any)
+	properties := schemaContractMap(dataSchema["properties"])
+	status := properties["status"]
+	if got, want := schemaContractStringSlice(status["enum"]), []string{"success", "planned", "partial_success", "unknown"}; !schemaContractJSONEqual(got, want) {
+		t.Fatalf("aitable +table-bootstrap status enum = %#v, want %#v", got, want)
+	}
+	for _, property := range []string{"contractVersion", "operation", "executed", "retryable", "plan", "completedSteps", "verification", "checkpoint", "knownSideEffects", "result"} {
+		if properties[property] == nil {
+			t.Errorf("aitable +table-bootstrap final Result data_schema is missing %q", property)
+		}
+	}
+}
+
 func TestDeliveryWikiSpaceSearchDeclaresCompatibilityAdapter(t *testing.T) {
 	leaf := executeShortcutSchemaQuery(t, "--cli-path", "wiki +space-search")
 	if got := schemaContractString(leaf["interface_mode"]); got != "composite" {

internal/cli/primary_param_schema_governance_test.go

@@ -0,0 +1,242 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+
+package cli
+
+import "testing"
+
+func TestPrimaryParamMigrationKeepsConceptDirectionCommandScoped(t *testing.T) {
+	concepts, err := LoadParamConcepts()
+	if err != nil {
+		t.Fatalf("LoadParamConcepts() error = %v", err)
+	}
+	if got := concepts.ByConcept["content_text"].CanonicalHint; got != "text" {
+		t.Fatalf("content_text canonical hint = %q, want unchanged global hint text", got)
+	}
+	if got := concepts.ByConcept["open_conversation_id"].CanonicalHint; got != "conversation-id" {
+		t.Fatalf("open_conversation_id canonical hint = %q, want unchanged global hint conversation-id", got)
+	}
+
+	content := concepts.ByConcept["content_text"]
+	docNode := concepts.ByConcept["doc_node_id"]
+	docAppend, problems := reduceLeafParamAliases(
+		"doc +doc-append",
+		realMap(
+			realFlag{name: "content"},
+			realFlag{name: "text", hidden: true},
+			realFlag{name: "doc"},
+		),
+		[]Concept{content, docNode},
+		CommandOverride{},
+	)
+	if len(problems) != 0 {
+		t.Fatalf("doc +doc-append reduction problems = %v", problems)
+	}
+	assertPrimaryParamAlias(t, docAppend, "body", "content")
+	assertPrimaryParamAlias(t, docAppend, "node", "doc")
+
+	insertOverride := primaryParamOverride(t, concepts, "doc block insert")
+	docInsert, problems := reduceLeafParamAliases(
+		"doc block insert",
+		realMap(
+			realFlag{name: "content"},
+			realFlag{name: "text", hidden: true},
+			realFlag{name: "parent-block"},
+			realFlag{name: "ref-block"},
+		),
+		[]Concept{content},
+		insertOverride,
+	)
+	if len(problems) != 0 {
+		t.Fatalf("doc block insert reduction problems = %v", problems)
+	}
+	assertPrimaryParamAlias(t, docInsert, "body", "content")
+
+	docUpdate, problems := reduceLeafParamAliases(
+		"doc block update",
+		realMap(realFlag{name: "content"}, realFlag{name: "text", hidden: true}),
+		[]Concept{content},
+		CommandOverride{},
+	)
+	if len(problems) != 0 {
+		t.Fatalf("doc block update reduction problems = %v", problems)
+	}
+	assertPrimaryParamAlias(t, docUpdate, "body", "content")
+
+	replyOverride := primaryParamOverride(t, concepts, "chat +messages-reply")
+	chatReply, problems := reduceLeafParamAliases(
+		"chat +messages-reply",
+		realMap(
+			realFlag{name: "group"},
+			realFlag{name: "conversation-id", hidden: true},
+			realFlag{name: "ref-msg-id"},
+		),
+		[]Concept{concepts.ByConcept["open_conversation_id"]},
+		replyOverride,
+	)
+	if len(problems) != 0 {
+		t.Fatalf("chat +messages-reply reduction problems = %v", problems)
+	}
+	for _, emitted := range []string{"chat", "chat-id", "open-conversation-id"} {
+		assertPrimaryParamAlias(t, chatReply, emitted, "group")
+	}
+	assertPrimaryParamAlias(t, chatReply, "msg-id", "ref-msg-id")
+	if chatReply.IsBlocked("group") {
+		t.Fatal("chat +messages-reply canonical --group must not remain blocked")
+	}
+}
+
+func TestPrimaryParamMigrationUpdatesReviewedFixturesAndMappingKeys(t *testing.T) {
+	concepts, err := LoadParamConcepts()
+	if err != nil {
+		t.Fatalf("LoadParamConcepts() error = %v", err)
+	}
+	fixtures := []ParamFixtureCase{
+		{Command: "doc +doc-append", Emitted: "text", Expect: "content", Via: "native:reviewed-compatibility-alias"},
+		{Command: "doc +doc-append", Emitted: "node", Expect: "doc", Via: "concept:doc_node_id"},
+		{Command: "doc block insert", Emitted: "text", Expect: "content", Via: "native:reviewed-compatibility-alias", Occ: 2},
+		{Command: "doc block update", Emitted: "text", Expect: "content", Via: "native:reviewed-compatibility-alias", Occ: 6},
+		{Command: "chat message send", Emitted: "file-path", Expect: "file", Via: "native:reviewed-compatibility-alias"},
+		{Command: "chat +messages-reply", Emitted: "conversation-id", Expect: "group", Via: "native:reviewed-compatibility-alias"},
+		{Command: "chat +messages-reply", Emitted: "chat", Expect: "group", Via: "concept:open_conversation_id"},
+		{Command: "chat +messages-reply", Emitted: "open-conversation-id", Expect: "group", Via: "concept:open_conversation_id"},
+	}
+	for _, want := range fixtures {
+		found := false
+		for _, got := range concepts.Fixture {
+			if got == want {
+				found = true
+				break
+			}
+		}
+		if !found {
+			t.Errorf("reviewed fixture missing %#v", want)
+		}
+	}
+
+	tests := []struct {
+		oldKey string
+		newKey string
+		reason string
+	}{
+		{"chat.reply_personal_message --text", "chat.reply_personal_message --content", "serialized into the aggregate content JSON string"},
+		{"chat.send_personal_message --file-path", "chat.send_personal_message --file", "local upload/preprocessing input"},
+		{"chat.send_personal_message --text", "chat.send_personal_message --content", "serialized into the aggregate content payload"},
+		{"doc.insert_document_block --text", "doc.insert_document_block --content", "aggregate convenience input used to build element"},
+		{"doc.update_document_block --text", "doc.update_document_block --content", "aggregate convenience input used to build element"},
+		{"todo.add_todo_attachment --file-path", "todo.add_todo_attachment --file", "local upload input used to construct attachmentList"},
+	}
+	for _, test := range tests {
+		if _, exists := reviewedSchemaParameterMappingExclusions[test.oldKey]; exists {
+			t.Errorf("stale mapping exclusion remains at %q", test.oldKey)
+		}
+		if got := reviewedSchemaParameterMappingExclusions[test.newKey]; got != test.reason {
+			t.Errorf("mapping exclusion %q reason = %q, want %q", test.newKey, got, test.reason)
+		}
+	}
+}
+
+func TestPrimaryParamMigrationPreservesDeliverySchemaSignatures(t *testing.T) {
+	tests := []struct {
+		path             string
+		primary          string
+		legacy           string
+		required         bool
+		cliRequired      bool
+		property         string
+		propertyFrom     string
+		format           string
+		requiredWhen     string
+		requiredWhenFrom string
+	}{
+		{path: "aisearch person", primary: "query", legacy: "keyword", required: true, property: "keyword", propertyFrom: "native_annotation", requiredWhenFrom: "default"},
+		{path: "chat message reply", primary: "content", legacy: "text", required: true, cliRequired: true, propertyFrom: "reviewed_mapping_exclusion", requiredWhenFrom: "default"},
+		{path: "chat message send", primary: "content", legacy: "text", propertyFrom: "reviewed_mapping_exclusion", requiredWhenFrom: "default"},
+		{path: "chat message send", primary: "file", legacy: "file-path", propertyFrom: "reviewed_mapping_exclusion", format: "file-path", requiredWhen: "msg-type is file or audio or video", requiredWhenFrom: "typed_parameter_metadata"},
+		{path: "chat message send-by-webhook", primary: "content", legacy: "text", required: true, cliRequired: true, property: "text", propertyFrom: "native_annotation", requiredWhenFrom: "default"},
+		{path: "chat +broadcast", primary: "content", legacy: "text", required: true, property: "text", propertyFrom: "native_annotation", requiredWhenFrom: "default"},
+		{path: "chat +dm", primary: "content", legacy: "text", required: true, property: "text", propertyFrom: "native_annotation", requiredWhenFrom: "default"},
+		{path: "chat +send-to-group", primary: "content", legacy: "text", required: true, property: "text", propertyFrom: "native_annotation", requiredWhenFrom: "default"},
+		{path: "chat +messages-send-by-bot", primary: "content", legacy: "text", required: true, property: "text", propertyFrom: "native_annotation", requiredWhenFrom: "default"},
+		{path: "chat +messages-batch-send-by-bot", primary: "content", legacy: "text", required: true, property: "text", propertyFrom: "native_annotation", requiredWhenFrom: "default"},
+		{path: "chat +messages-send-by-webhook", primary: "content", legacy: "text", required: true, property: "text", propertyFrom: "native_annotation", requiredWhenFrom: "default"},
+		{path: "chat +messages-reply", primary: "content", legacy: "text", required: true, property: "text", propertyFrom: "native_annotation", requiredWhenFrom: "default"},
+		{path: "chat +messages-reply", primary: "group", legacy: "conversation-id", required: true, property: "conversationId", propertyFrom: "native_annotation", requiredWhenFrom: "default"},
+		{path: "doc +doc-append", primary: "content", legacy: "text", required: true, property: "text", propertyFrom: "native_annotation", requiredWhenFrom: "default"},
+		{path: "doc block insert", primary: "content", legacy: "text", propertyFrom: "reviewed_mapping_exclusion", requiredWhenFrom: "default"},
+		{path: "doc block update", primary: "content", legacy: "text", propertyFrom: "reviewed_mapping_exclusion", requiredWhenFrom: "default"},
+		{path: "todo task add-attachment", primary: "file", legacy: "file-path", required: true, propertyFrom: "reviewed_mapping_exclusion", requiredWhenFrom: "default"},
+	}
+	for _, test := range tests {
+		t.Run(test.path+"/"+test.primary, func(t *testing.T) {
+			leaf, err := queryDeliverySchemaPayload([]string{test.path})
+			if err != nil {
+				t.Fatal(err)
+			}
+			parameters := schemaMap(leaf["parameters"])
+			parameter, exists := parameters[test.primary]
+			if !exists {
+				t.Fatalf("%s missing visible Primary --%s", test.path, test.primary)
+			}
+			if _, exists := parameters[test.legacy]; exists {
+				t.Fatalf("%s unexpectedly publishes hidden legacy --%s", test.path, test.legacy)
+			}
+			if got := parameter["type"]; got != "string" {
+				t.Errorf("%s --%s type = %#v, want string", test.path, test.primary, got)
+			}
+			if got := parameter["required"]; got != test.required {
+				t.Errorf("%s --%s required = %#v, want %v", test.path, test.primary, got, test.required)
+			}
+			if got, _ := parameter["cli_required"].(bool); got != test.cliRequired {
+				t.Errorf("%s --%s cli_required = %#v, want %v", test.path, test.primary, parameter["cli_required"], test.cliRequired)
+			}
+			if got, _ := parameter["property"].(string); got != test.property {
+				t.Errorf("%s --%s property = %q, want %q", test.path, test.primary, got, test.property)
+			}
+			if got := parameter["interface_type"]; got != nil && got != "" {
+				t.Errorf("%s --%s interface_type = %#v, want omitted/empty", test.path, test.primary, got)
+			}
+			if got, _ := parameter["format"].(string); got != test.format {
+				t.Errorf("%s --%s format = %q, want %q", test.path, test.primary, got, test.format)
+			}
+			if got, _ := parameter["required_when"].(string); got != test.requiredWhen {
+				t.Errorf("%s --%s required_when = %q, want %q", test.path, test.primary, got, test.requiredWhen)
+			}
+
+			provenance := schemaMap(parameter["field_provenance"])
+			propertyProvenance := provenance["property"]
+			if got := propertyProvenance["source"]; got != test.propertyFrom {
+				t.Errorf("%s --%s property source = %#v, want %s", test.path, test.primary, got, test.propertyFrom)
+			}
+			typeProvenance := provenance["type"]
+			if got := typeProvenance["source"]; got != "cobra_flag_type" {
+				t.Errorf("%s --%s type source = %#v, want cobra_flag_type", test.path, test.primary, got)
+			}
+			requiredWhenProvenance := provenance["required_when"]
+			if got := requiredWhenProvenance["source"]; got != test.requiredWhenFrom {
+				t.Errorf("%s --%s required_when source = %#v, want %s", test.path, test.primary, got, test.requiredWhenFrom)
+			}
+		})
+	}
+}
+
+func primaryParamOverride(t *testing.T, concepts ParamConcepts, path string) CommandOverride {
+	t.Helper()
+	for _, override := range concepts.Overrides {
+		if override.CommandPath == path {
+			return override
+		}
+	}
+	t.Fatalf("command override %q not found", path)
+	return CommandOverride{}
+}
+
+func assertPrimaryParamAlias(t *testing.T, entry *ParamAliasEntry, emitted, want string) {
+	t.Helper()
+	if entry == nil {
+		t.Fatalf("alias entry is nil; want %s -> %s", emitted, want)
+	}
+	if got, ok := entry.ResolveAlias(emitted); !ok || got != want {
+		t.Fatalf("ResolveAlias(%q) = %q (ok=%v), want %q", emitted, got, ok, want)
+	}
+}

internal/cli/schema_constraints_runtime.go

@@ -68,9 +68,9 @@ func init() {
 	registerRequireOneOf("devdoc.search_open_platform_docs_rag", "query", "keyword")
 	registerRequireOneOf("event.consume", "event_key", "subscribe-id")
 	registerExclusiveOneOf("event.stop", "all", "subscribe_id")
-	registerRequireOneOf("doc.insert_document_block", "text", "heading", "element")
+	registerRequireOneOf("doc.insert_document_block", "content", "heading", "element")
 	registerExclusiveOneOf("doc.update_document", "content", "content-file")
-	registerRequireOneOf("doc.update_document_block", "text", "heading", "element")
+	registerRequireOneOf("doc.update_document_block", "content", "heading", "element")
 	registerRequireOneOf("pat.batch_grant", "scope", "product", "products", "domain", "domains", "recommend")
 	registerRequireOneOf("mail.search_mail_users", "keyword", "employee-no")
 	// --body is a hidden compatibility alias for the public --content flag.

internal/cli/schema_contract_model.go

@@ -1127,21 +1127,37 @@ func putRawJSON(payload map[string]any, key string, raw json.RawMessage) error {
 	return nil
 }
 
+// rawJSONValue decodes a JSON value that may come from an untrusted source, so
+// it validates before decoding. Callers holding output that json.Marshal just
+// produced should use typedJSONValue instead of paying the validation scan.
 func rawJSONValue(raw json.RawMessage) (any, error) {
 	if !json.Valid(raw) {
 		return nil, fmt.Errorf("invalid JSON value")
 	}
+	return decodeValidJSONValue(raw), nil
+}
+
+// decodeValidJSONValue decodes JSON whose validity the caller has already
+// established, either by json.Valid or by having just marshaled it. Decode
+// errors are unreachable under that precondition and are therefore discarded,
+// exactly as this path behaved when the decode was inlined into rawJSONValue.
+func decodeValidJSONValue(raw json.RawMessage) any {
 	decoder := json.NewDecoder(bytes.NewReader(raw))
 	decoder.UseNumber()
 	var value any
 	_ = decoder.Decode(&value)
-	return value, nil
+	return value
 }
 
+// typedJSONValue projects a typed value into the generic JSON shape the payload
+// renderers consume. json.Marshal output is valid by construction, so this path
+// decodes it directly: routing through rawJSONValue re-scanned every marshaled
+// document with json.Valid, which measured ~34% of Schema Catalog assembly time
+// across the 1121-tool set (26.0s -> 17.2s for the internal/app schema suite).
 func typedJSONValue(value any) (any, error) {
 	data, err := json.Marshal(value)
 	if err != nil {
 		return nil, err
 	}
-	return rawJSONValue(data)
+	return decodeValidJSONValue(data), nil
 }

internal/cli/schema_parameter_mapping_ledger.go

@@ -269,20 +269,20 @@ var reviewedSchemaParameterMappingExclusions = map[string]string{
 	"chat.update_text_emotion --conversation-id":                         "Reviewed unpinned adapter: chat.update_text_emotion has no singular pinned interface_ref; --conversation-id is a CLI wrapper input and does not publish a direct interface property.",
 	"chat.reply_personal_message --ref-msg-id":                           "serialized into the aggregate content JSON string",
 	"chat.reply_personal_message --ref-sender":                           "resolved then serialized into the aggregate content JSON string",
-	"chat.reply_personal_message --text":                                 "serialized into the aggregate content JSON string",
+	"chat.reply_personal_message --content":                              "serialized into the aggregate content JSON string",
 	"chat.search_groups --cursor":                                        "Reviewed unpinned adapter: chat.search_groups has no singular pinned interface_ref; --cursor is a CLI wrapper input and does not publish a direct interface property.",
 	"chat.search_groups --exclude-muted":                                 "Reviewed unpinned adapter: chat.search_groups has no singular pinned interface_ref; --exclude-muted is a CLI wrapper input and does not publish a direct interface property.",
 	"chat.search_groups --limit":                                         "Reviewed unpinned adapter: chat.search_groups has no singular pinned interface_ref; --limit is a CLI wrapper input and does not publish a direct interface property.",
 	"chat.search_messages --user":                                        "conditional wrapper: parseCSVValues + appendChatIDArgs routes each supplied identifier to senderUserIds or senderOpenDingTakIds according to its runtime ID shape; there is no single RPC property for this flag",
 	"chat.search_messages --users":                                       "conditional wrapper/alias of --user: parseCSVValues + appendChatIDArgs routes each supplied identifier to senderUserIds or senderOpenDingTakIds according to its runtime ID shape; there is no single RPC property for this flag",
 	"chat.send_personal_message --contact-id":                            "serialized into the aggregate content payload",
-	"chat.send_personal_message --file-path":                             "local upload/preprocessing input",
+	"chat.send_personal_message --file":                                  "local upload/preprocessing input",
 	"chat.send_personal_message --latitude":                              "serialized into the aggregate content payload",
 	"chat.send_personal_message --location-name":                         "serialized into the aggregate content payload",
 	"chat.send_personal_message --longitude":                             "serialized into the aggregate content payload",
 	"chat.send_personal_message --map-thumbnail-url":                     "serialized into the aggregate content payload",
 	"chat.send_personal_message --media-id":                              "serialized into the aggregate content payload",
-	"chat.send_personal_message --text":                                  "serialized into the aggregate content payload",
+	"chat.send_personal_message --content":                               "serialized into the aggregate content payload",
 	"chat.send_personal_message --title":                                 "serialized into the aggregate content payload",
 	"chat.send_personal_message --user":                                  "resolves a userId to receiverOpenDingTalkId when possible and otherwise uses the unpinned receiverUserId compatibility property",
 	"chat.set_group_member_mute_list --user":                             "conditional wrapper/alias of --users: userIds are remotely resolved to openDingTalkIds outside dry-run and otherwise may be sent as uids; openDingTalkId inputs are sent as openDingTalkIds, so one exact property would misdescribe execution",
@@ -406,7 +406,7 @@ var reviewedSchemaParameterMappingExclusions = map[string]string{
 	"doc.insert_document_block --fix-jsonml":                             "local JSONML normalization control",
 	"doc.insert_document_block --heading":                                "aggregate convenience input used to build element",
 	"doc.insert_document_block --level":                                  "aggregate convenience input used to build element",
-	"doc.insert_document_block --text":                                   "aggregate convenience input used to build element",
+	"doc.insert_document_block --content":                                "aggregate convenience input used to build element",
 	"doc.list_document_blocks --block-id":                                "runtime extension sends blockId, which is absent from the pinned list_document_blocks metadata",
 	"doc.reply_comment --mentioned-open-conversation-id":                 "Runtime extension sends mentionedOpenConversationIds, which is absent from the immutable pinned reply_comment metadata at its declared source revision.",
 	"doc.style_background_clear --node":                                  "Reviewed unpinned adapter: doc.style_background_clear has no singular pinned interface_ref; --node is a CLI wrapper input and does not publish a direct interface property.",
@@ -438,7 +438,7 @@ var reviewedSchemaParameterMappingExclusions = map[string]string{
 	"doc.update_document_block --fix-jsonml":                             "local JSONML normalization control",
 	"doc.update_document_block --heading":                                "aggregate convenience input used to build element",
 	"doc.update_document_block --level":                                  "aggregate convenience input used to build element",
-	"doc.update_document_block --text":                                   "aggregate convenience input used to build element",
+	"doc.update_document_block --content":                                "aggregate convenience input used to build element",
 	"doc.version_list --cursor":                                          "Reviewed unpinned adapter: doc.version_list has no singular pinned interface_ref; --cursor is a CLI wrapper input and does not publish a direct interface property.",
 	"doc.version_list --limit":                                           "Reviewed unpinned adapter: doc.version_list has no singular pinned interface_ref; --limit is a CLI wrapper input and does not publish a direct interface property.",
 	"doc.version_list --node":                                            "Reviewed unpinned adapter: doc.version_list has no singular pinned interface_ref; --node is a CLI wrapper input and does not publish a direct interface property.",
@@ -659,7 +659,7 @@ var reviewedSchemaParameterMappingExclusions = map[string]string{
 	"sheet.write_image --file":                                           "local upload input used to obtain resourceId/resourceUrl",
 	"sheet.write_image --mime-type":                                      "local upload metadata",
 	"sheet.write_image --name":                                           "local upload metadata",
-	"todo.add_todo_attachment --file-path":                               "local upload input used to construct attachmentList",
+	"todo.add_todo_attachment --file":                                    "local upload input used to construct attachmentList",
 	"todo.get_user_todos_in_current_org --query-all":                     "Local route selector: the default path calls get_user_todos_in_current_org, while --query-all switches to get_user_todos; it is not a property of the pinned default RPC.",
 	"todo.list_todo_attachment --task-id":                                "Reviewed unpinned adapter: --task-id is nested under todoAttachmentListRequest at runtime, while the immutable pinned MCP snapshot has no interface_ref for todo.list_todo_attachment.",
 	"wiki.create_wikiSpace --icon":                                       "runtime extension sends icon, which is absent from the pinned create_wikiSpace metadata",

internal/cli/schema_parameters_runtime.go

@@ -77,7 +77,7 @@ func cloneRuntimeSchemaStringMap(source map[string]string) map[string]string {
 
 func init() {
 	RegisterRuntimeSchemaParameterMetadata("aisearch.enterprise_person_search", RuntimeSchemaParameterMetadata{
-		Required: []string{"keyword"},
+		Required: []string{"query"},
 	})
 	RegisterRuntimeSchemaParameterMetadata("aitable.export_data", RuntimeSchemaParameterMetadata{
 		RequiredWhen: map[string]string{
@@ -146,8 +146,8 @@ func init() {
 	})
 	RegisterRuntimeSchemaParameterMetadata("chat.send_personal_message", RuntimeSchemaParameterMetadata{
 		RequiredWhen: map[string]string{
-			"media-id":  "msg-type is image",
-			"file-path": "msg-type is file or audio or video",
+			"media-id": "msg-type is image",
+			"file":     "msg-type is file or audio or video",
 		},
 		Examples: map[string]string{"media-id": "@lADP_schema_smoke"},
 	})

internal/event/bus/coverage_edges_test.go

@@ -361,13 +361,18 @@ func TestCrossPlatformCoverageDaemonMethodEdges(t *testing.T) {
 		}
 		return nil, net.ErrClosed
 	}}
-	d := &daemon{listener: l, log: logger, hub: NewHub(1), idleStop: make(chan struct{})}
+	d := &daemon{listener: l, log: logger, hub: NewHub(1), idleStop: make(chan struct{}), stopReq: make(chan string, 1)}
 	d.acceptLoop(context.Background())
 	d.shuttingDown.Store(true)
 	d.acceptLoop(context.Background())
 	d.triggerShutdown("test")
-	if !l.closed {
-		t.Fatal("trigger did not close listener")
+	select {
+	case reason := <-d.stopReq:
+		if reason != "test" {
+			t.Fatalf("stop reason = %q", reason)
+		}
+	default:
+		t.Fatal("trigger did not notify lifecycle loop")
 	}
 
 	d = &daemon{listener: &scriptedListener{accept: func() (net.Conn, error) { return nil, net.ErrClosed }}, log: logger, hub: NewHub(1), idleStop: make(chan struct{})}

internal/event/bus/daemon.go

@@ -186,6 +186,7 @@ func Run(ctx context.Context, cfg Config) error {
 		dedup:    dd,
 		started:  time.Now().UTC(),
 		idleStop: make(chan struct{}),
+		stopReq:  make(chan string, 1),
 	}
 
 	// 4. Signal ready BEFORE accepting consumers (avoids a slow-fork
@@ -263,6 +264,9 @@ func Run(ctx context.Context, cfg Config) error {
 		}
 	case <-d.idleStop:
 		log.Info("bus: idle timeout reached, shutting down")
+	case reason := <-d.stopReq:
+		shutdownReason = reason
+		log.Info("bus: shutdown requested via IPC", "reason", reason)
 	}
 
 	// 7. Graceful shutdown — cancel runCtx first so all background
@@ -292,6 +296,7 @@ type daemon struct {
 	shutdownMu   sync.Mutex
 	shuttingDown atomic.Bool
 	idleStop     chan struct{}
+	stopReq      chan string
 
 	credentialHandoffMu sync.Mutex
 	terminalMu          sync.RWMutex
@@ -749,15 +754,17 @@ func (d *daemon) idleWatch(ctx context.Context) {
 	}
 }
 
-// triggerShutdown is called from RPC handlers that want to end the bus.
-// It works by closing the listener (which unblocks Run's select via the
-// source error path, indirectly). For v1 a full ctx-cancellation hook is
-// out of scope; busctl/stop also sends SIGTERM which is the authoritative
-// shutdown path.
+// triggerShutdown is called from RPC handlers that want to end the bus. The
+// buffered request wakes Run's lifecycle select, which then cancels the cloud
+// source and performs the same graceful shutdown used for signals and idle
+// expiry. It is intentionally non-blocking so repeated stop requests cannot
+// strand connection handlers.
 func (d *daemon) triggerShutdown(reason string) {
 	d.log.Info("bus: shutdown triggered via IPC", "reason", reason)
-	_ = d.listener.Close() // unblocks Accept(), but doesn't kill Source
-	// Best-effort: a future version wires a context.CancelFunc here.
+	select {
+	case d.stopReq <- reason:
+	default:
+	}
 }
 
 // shutdown performs the graceful tear-down sequence:

internal/event/bus/daemon_test.go

@@ -141,6 +141,67 @@ func TestDaemon_RunStartsAndShutsDownCleanly(t *testing.T) {
 	}
 }
 
+func TestCrossPlatformCoverageDaemonIPCStopShutsDownCleanly(t *testing.T) {
+	workDir := shortTempDir(t)
+	identityHash := dwsevent.IdentityHash(workDir)
+	endpoint := dwsevent.IPCEndpoint(workDir, "open", dwsevent.SourceKindAppStream, identityHash)
+	runDone := make(chan error, 1)
+	go func() {
+		runDone <- Run(context.Background(), Config{
+			WorkDir:      workDir,
+			IPCEndpoint:  endpoint,
+			ClientID:     "ding_ipc_stop_test",
+			Edition:      "open",
+			SourceKind:   dwsevent.SourceKindAppStream,
+			IdentityHash: identityHash,
+			Source:       &fakeSource{},
+		})
+	}()
+
+	var conn net.Conn
+	deadline := time.Now().Add(3 * time.Second)
+	for time.Now().Before(deadline) {
+		var err error
+		conn, err = transport.Dial(endpoint)
+		if err == nil {
+			break
+		}
+		time.Sleep(10 * time.Millisecond)
+	}
+	if conn == nil {
+		t.Fatal("bus IPC endpoint did not become ready")
+	}
+	w := transport.NewWriter(conn)
+	r := transport.NewReader(conn)
+	if err := w.WriteJSON(transport.Hello{
+		Type:        transport.FrameTypeHello,
+		ConsumerPID: os.Getpid(),
+		Role:        transport.HelloRoleStop,
+	}); err != nil {
+		t.Fatalf("write stop hello: %v", err)
+	}
+	var bye transport.Bye
+	if err := r.ReadJSON(&bye); err != nil {
+		t.Fatalf("read stop response: %v", err)
+	}
+	_ = conn.Close()
+	if bye.Type != transport.FrameTypeBye || bye.Reason != "stop_request" {
+		t.Fatalf("stop response = %#v", bye)
+	}
+
+	select {
+	case err := <-runDone:
+		if err != nil {
+			t.Fatalf("Run returned after IPC stop: %v", err)
+		}
+	case <-time.After(3 * time.Second):
+		t.Fatal("Run did not return after IPC stop")
+	}
+	if pid := ReadHolderPID(filepath.Join(workDir, LockFileName)); pid != 0 {
+		t.Fatalf("bus lock retained pid %d after IPC stop", pid)
+	}
+}
+
 func TestDaemon_ConsumerReceivesEvents(t *testing.T) {
 	skipOnWindows(t, "uses Unix socket dial")
 	workDir := shortTempDir(t)

internal/event/bus/lockfile.go

@@ -114,6 +114,47 @@ func ReadHolderPID(path string) int {
 	return parsePID(b)
 }
 
+// ValidateHolderOwnership reports whether pid still owns the exclusive lock at
+// path. If the lock can be acquired, no daemon owns it: the PID payload is
+// stale and is cleared while the probe holds the lock. The PID is read again
+// after a busy result so a daemon replacement cannot be mistaken for the
+// original owner.
+//
+// Callers use this immediately before sending a process-level termination
+// fallback. A live PID by itself is not proof of ownership because operating
+// systems may reuse PIDs after an unclean daemon exit.
+func ValidateHolderOwnership(path string, pid int) (bool, error) {
+	if pid <= 0 || ReadHolderPID(path) != pid {
+		return false, nil
+	}
+
+	probe, err := busTryAcquire(path)
+	if err != nil {
+		if errors.Is(err, ErrBusy) {
+			return ReadHolderPID(path) == pid, nil
+		}
+		return false, fmt.Errorf("bus: verify lock owner: %w", err)
+	}
+	defer probe.Close()
+
+	// We own the lock, so the recorded PID cannot own it. Clear only the PID
+	// we validated above; a changed payload is left untouched defensively.
+	f := probe.File()
+	if _, err := busSeek(f, 0, io.SeekStart); err != nil {
+		return false, fmt.Errorf("bus: seek stale lock: %w", err)
+	}
+	current, err := busReadAll(f)
+	if err != nil {
+		return false, fmt.Errorf("bus: read stale lock: %w", err)
+	}
+	if parsePID(current) == pid {
+		if err := truncateAndWritePID(f, 0); err != nil {
+			return false, fmt.Errorf("bus: clear stale PID: %w", err)
+		}
+	}
+	return false, nil
+}
+
 // Close releases the flock and best-effort blanks the PID body so a stale
 // reader (e.g. `event status` racing our shutdown) does not see our
 // long-dead PID and try to signal it. The lock file itself is NOT removed

internal/event/bus/lockfile_test.go

@@ -16,9 +16,13 @@ package bus
 import (
 	"errors"
 	"fmt"
+	"io"
 	"os"
 	"path/filepath"
 	"testing"
+
+	eventlock "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/lock"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam"
 )
 
 func TestAcquire_WritesOurPID(t *testing.T) {
@@ -112,6 +116,109 @@ func TestReadHolderPID_MalformedReturnsZero(t *testing.T) {
 	}
 }
 
+func TestCrossPlatformCoverageValidateHolderOwnershipHeldLock(t *testing.T) {
+	path := filepath.Join(t.TempDir(), LockFileName)
+	held, err := busTryAcquire(path)
+	if err != nil {
+		t.Fatalf("hold lock: %v", err)
+	}
+	defer held.Close()
+	if err := truncateAndWritePID(held.File(), os.Getpid()); err != nil {
+		t.Fatalf("write holder PID: %v", err)
+	}
+
+	owned, err := ValidateHolderOwnership(path, os.Getpid())
+	if err != nil {
+		t.Fatalf("ValidateHolderOwnership: %v", err)
+	}
+	if !owned {
+		t.Fatal("held lock was not attributed to its recorded PID")
+	}
+}
+
+func TestCrossPlatformCoverageValidateHolderOwnershipClearsReusedPID(t *testing.T) {
+	path := filepath.Join(t.TempDir(), LockFileName)
+	// The current PID is alive but deliberately does not hold this lock. This
+	// models a stale daemon PID that the OS has reassigned to another process.
+	if err := os.WriteFile(path, []byte(fmt.Sprintf("%d\n", os.Getpid())), 0o600); err != nil {
+		t.Fatalf("write stale PID: %v", err)
+	}
+
+	owned, err := ValidateHolderOwnership(path, os.Getpid())
+	if err != nil {
+		t.Fatalf("ValidateHolderOwnership: %v", err)
+	}
+	if owned {
+		t.Fatal("live reused PID without the bus lock was accepted as owner")
+	}
+	if got := ReadHolderPID(path); got != 0 {
+		t.Fatalf("stale PID after validation = %d, want cleared", got)
+	}
+}
+
+func TestCrossPlatformCoverageValidateHolderOwnershipRejectsMismatch(t *testing.T) {
+	path := filepath.Join(t.TempDir(), LockFileName)
+	if err := os.WriteFile(path, []byte("123\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	owned, err := ValidateHolderOwnership(path, 456)
+	if err != nil || owned {
+		t.Fatalf("ValidateHolderOwnership mismatch = %v, %v", owned, err)
+	}
+}
+
+func TestCrossPlatformCoverageValidateHolderOwnershipErrors(t *testing.T) {
+	errInjected := errors.New("injected ownership validation failure")
+	writeLivePID := func(t *testing.T) string {
+		t.Helper()
+		path := filepath.Join(t.TempDir(), LockFileName)
+		if err := os.WriteFile(path, []byte(fmt.Sprintf("%d\n", os.Getpid())), 0o600); err != nil {
+			t.Fatal(err)
+		}
+		return path
+	}
+
+	t.Run("probe", func(t *testing.T) {
+		path := writeLivePID(t)
+		testseam.Swap(t, &busTryAcquire, func(string) (*eventlock.File, error) {
+			return nil, errInjected
+		})
+		if _, err := ValidateHolderOwnership(path, os.Getpid()); !errors.Is(err, errInjected) {
+			t.Fatalf("probe error = %v", err)
+		}
+	})
+
+	t.Run("seek", func(t *testing.T) {
+		path := writeLivePID(t)
+		testseam.Swap(t, &busSeek, func(*os.File, int64, int) (int64, error) {
+			return 0, errInjected
+		})
+		if _, err := ValidateHolderOwnership(path, os.Getpid()); !errors.Is(err, errInjected) {
+			t.Fatalf("seek error = %v", err)
+		}
+	})
+
+	t.Run("read", func(t *testing.T) {
+		path := writeLivePID(t)
+		testseam.Swap(t, &busReadAll, func(io.Reader) ([]byte, error) {
+			return nil, errInjected
+		})
+		if _, err := ValidateHolderOwnership(path, os.Getpid()); !errors.Is(err, errInjected) {
+			t.Fatalf("read error = %v", err)
+		}
+	})
+
+	t.Run("clear", func(t *testing.T) {
+		path := writeLivePID(t)
+		testseam.Swap(t, &busTruncate, func(*os.File, int64) error {
+			return errInjected
+		})
+		if _, err := ValidateHolderOwnership(path, os.Getpid()); !errors.Is(err, errInjected) {
+			t.Fatalf("clear error = %v", err)
+		}
+	})
+}
+
 func TestAcquire_AfterReleaseReclaimable(t *testing.T) {
 	path := filepath.Join(t.TempDir(), LockFileName)
 	l1, err := Acquire(path)

internal/event/busctl/coverage_edges_test.go

@@ -284,11 +284,13 @@ func TestCrossPlatformCoverageQueryStatusAndEntryEdges(t *testing.T) {
 
 func TestCrossPlatformCoverageStopInjectedEdges(t *testing.T) {
 	origRead := stopReadHolderPID
+	origValidateOwner := stopValidateHolderOwner
 	origAlive := stopAlive
 	origFind := stopFindProcess
 	origSignal := stopSignalProcess
 	t.Cleanup(func() {
 		stopReadHolderPID = origRead
+		stopValidateHolderOwner = origValidateOwner
 		stopAlive = origAlive
 		stopFindProcess = origFind
 		stopSignalProcess = origSignal
@@ -307,6 +309,7 @@ func TestCrossPlatformCoverageStopInjectedEdges(t *testing.T) {
 		t.Fatal(err)
 	}
 	stopFindProcess = func(int) (*os.Process, error) { return proc, nil }
+	stopValidateHolderOwner = func(string, int) (bool, error) { return true, nil }
 	stopSignalProcess = func(*os.Process, os.Signal) error { return os.ErrProcessDone }
 	if err := Stop(StopConfig{WorkDir: "x"}); err != nil {
 		t.Fatalf("done signal = %v", err)

internal/event/busctl/discover.go

@@ -112,8 +112,9 @@ func Discover(cfg DiscoverConfig) (net.Conn, error) {
 		return nil, fmt.Errorf("busctl: mkdir workdir: %w", err)
 	}
 	_, spawnErr := cfg.Spawn(SpawnConfig{
-		ClientID:  cfg.ClientID,
-		ExtraArgs: cfg.SpawnExtraArgs,
+		ClientID:    cfg.ClientID,
+		IPCEndpoint: cfg.IPCEndpoint,
+		ExtraArgs:   cfg.SpawnExtraArgs,
 	})
 	if spawnErr != nil && !errors.Is(spawnErr, ErrSpawnFailed) {
 		// Hard error (couldn't even exec the child). Stop here — no bus

internal/event/busctl/discover_test.go

@@ -122,7 +122,10 @@ func TestDiscover_NoBus_SpawnSucceeds(t *testing.T) {
 			closer()
 		}
 	})
-	fakeSpawn := func(SpawnConfig) (int, error) {
+	fakeSpawn := func(cfg SpawnConfig) (int, error) {
+		if cfg.IPCEndpoint != sock {
+			t.Fatalf("spawn IPC endpoint = %q, want %q", cfg.IPCEndpoint, sock)
+		}
 		closer = startStubBus(t, sock)
 		return 12345, nil
 	}

internal/event/busctl/spawn.go

@@ -43,18 +43,14 @@ var (
 	spawnPipe       = os.Pipe
 )
 
-// ErrSpawnFailed is returned when the child reports startup failure via
-// the ready pipe ('E' byte). The child's exit error / log file holds the
-// actual cause; this sentinel just lets the caller distinguish "ready
-// pipe said no" from "ready pipe timed out / closed early".
-var ErrSpawnFailed = errors.New("busctl: bus child reported startup failure on ready pipe")
+// ErrSpawnFailed is returned when the child reports startup failure through
+// the Unix ready pipe or exits before binding the Windows named pipe.
+var ErrSpawnFailed = errors.New("busctl: bus child reported startup failure")
 
 // ErrSpawnTimeout is returned when ReadyTimeout elapses without any signal.
 var ErrSpawnTimeout = errors.New("busctl: bus child did not signal readiness within deadline")
 
-// SpawnConfig describes one spawn attempt. ClientID is the only field
-// inspected by the child; the rest govern process attributes the parent
-// applies before exec.
+// SpawnConfig describes one spawn attempt.
 type SpawnConfig struct {
 	// ExecPath is the dws binary to exec. Default os.Executable().
 	ExecPath string
@@ -62,18 +58,23 @@ type SpawnConfig struct {
 	// ClientID is passed as `--client-id` to `dws event _bus`. Required.
 	ClientID string
 
+	// IPCEndpoint is the bus endpoint the child binds. Windows uses the
+	// existing named pipe as its readiness handshake because os/exec does not
+	// support ExtraFiles there. Unix keeps the inherited ready-pipe protocol.
+	IPCEndpoint string
+
 	// ExtraArgs are appended after `--client-id`. Empty for normal use; tests
 	// pass `--extra-flag-for-test` etc.
 	ExtraArgs []string
 
-	// Env to pass to the child. Defaults to os.Environ(). The ReadyFDEnv
-	// entry is appended automatically.
+	// Env to pass to the child. Defaults to os.Environ(). Unix appends the
+	// ReadyFDEnv entry automatically; Windows removes any inherited copy.
 	Env []string
 }
 
-// Spawn forks a detached `dws event _bus --client-id <id>` child process and
-// waits for it to signal readiness via the ready pipe. Returns the child's
-// PID on success — the caller can then dial the bus IPC endpoint.
+// spawnWithReadyPipe is the Unix implementation behind Spawn. It forks a
+// detached `dws event _bus --client-id <id>` child and waits for the inherited
+// ready pipe. Windows has a named-pipe implementation in spawn_windows.go.
 //
 // stdio detach (plan invariant #7):
 //   - cmd.Stdout / cmd.Stderr set to nil so the child's own writes don't
@@ -89,7 +90,7 @@ type SpawnConfig struct {
 // Parent (this function):
 //   - Holds the read end open until either 1 byte is read or ReadyTimeout
 //   - Returns ErrSpawnFailed for 'E', ErrSpawnTimeout otherwise
-func Spawn(cfg SpawnConfig) (pid int, err error) {
+func spawnWithReadyPipe(cfg SpawnConfig) (pid int, err error) {
 	if cfg.ClientID == "" {
 		return 0, errors.New("busctl: SpawnConfig.ClientID is required")
 	}

internal/event/busctl/spawn_test.go

@@ -22,6 +22,8 @@ import (
 	"strings"
 	"testing"
 	"time"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/transport"
 )
 
 // Test child mode: when DWS_BUSCTL_TEST_CHILD is set, this test binary
@@ -35,7 +37,8 @@ import (
 // env-marker pattern is what Go's own os/exec tests use and stays
 // confined to this file.
 const (
-	childEnvMarker = "DWS_BUSCTL_TEST_CHILD"
+	childEnvMarker   = "DWS_BUSCTL_TEST_CHILD"
+	childEndpointEnv = "DWS_BUSCTL_TEST_ENDPOINT"
 	// values:
 	//   "ready"        — write 'R' then sleep 30s (parent should see ready)
 	//   "fail"         — write 'E' then exit (parent should see ErrSpawnFailed)
@@ -70,6 +73,26 @@ func TestMain(m *testing.M) {
 		writeReady('R')
 		time.Sleep(30 * time.Second)
 		os.Exit(0)
+	case "windows-ready":
+		listener, err := transport.Listen(os.Getenv(childEndpointEnv))
+		if err != nil {
+			os.Exit(3)
+		}
+		defer listener.Close()
+		conn, err := listener.Accept()
+		if err != nil {
+			os.Exit(4)
+		}
+		_ = conn.Close()
+		time.Sleep(30 * time.Second)
+		os.Exit(0)
+	case "windows-fail":
+		os.Exit(5)
+	case "windows-exit":
+		os.Exit(0)
+	case "windows-stall":
+		time.Sleep(30 * time.Second)
+		os.Exit(0)
 	}
 	os.Exit(m.Run())
 }

internal/event/busctl/spawn_unix.go

@@ -20,6 +20,13 @@ import (
 	"syscall"
 )
 
+// Spawn starts the detached bus and waits for its inherited ready pipe.
+// ExtraFiles is intentionally confined to Unix: Go does not support it on
+// Windows.
+func Spawn(cfg SpawnConfig) (pid int, err error) {
+	return spawnWithReadyPipe(cfg)
+}
+
 // applyDetach configures the child to live past parent death and not share
 // the parent's controlling terminal. Setsid puts the child in a new
 // session, so SIGHUP on the parent's controlling tty (e.g. SSH disconnect)

internal/event/busctl/spawn_windows.go

@@ -16,14 +16,101 @@
 package busctl
 
 import (
+	"fmt"
+	"os"
 	"os/exec"
+	"strings"
 	"syscall"
+	"time"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/transport"
 )
 
 // CREATE_NEW_PROCESS_GROUP (0x00000200) prevents the child from receiving
 // the parent's Ctrl+C signal, similar in spirit to Setsid on Unix.
 const createNewProcessGroup = 0x00000200
 
+var (
+	spawnWindowsDial         = transport.Dial
+	spawnWindowsPollInterval = 25 * time.Millisecond
+)
+
+// Spawn starts a detached Windows bus without cmd.ExtraFiles (unsupported by
+// Go on Windows). Readiness is confirmed by dialing the bus's existing named
+// pipe. The child is reaped in the background after readiness, while an early
+// process exit is surfaced as ErrSpawnFailed.
+func Spawn(cfg SpawnConfig) (pid int, err error) {
+	if strings.TrimSpace(cfg.ClientID) == "" {
+		return 0, fmt.Errorf("busctl: SpawnConfig.ClientID is required")
+	}
+	if strings.TrimSpace(cfg.IPCEndpoint) == "" {
+		return 0, fmt.Errorf("busctl: SpawnConfig.IPCEndpoint is required on Windows")
+	}
+	if cfg.ExecPath == "" {
+		execPath, err := spawnExecutable()
+		if err != nil {
+			return 0, fmt.Errorf("busctl: locate executable: %w", err)
+		}
+		cfg.ExecPath = execPath
+	}
+	if cfg.Env == nil {
+		cfg.Env = os.Environ()
+	}
+
+	args := append([]string{"event", "_bus", "--client-id", cfg.ClientID}, cfg.ExtraArgs...)
+	cmd := exec.Command(cfg.ExecPath, args...)
+	cmd.Env = withoutReadyFDEnv(cfg.Env)
+	cmd.Stdin = nil
+	cmd.Stdout = nil
+	cmd.Stderr = nil
+	applyDetach(cmd)
+	if err := cmd.Start(); err != nil {
+		return 0, fmt.Errorf("busctl: start %s: %w", cfg.ExecPath, err)
+	}
+	pid = cmd.Process.Pid
+
+	waitDone := make(chan error, 1)
+	go func() { waitDone <- cmd.Wait() }()
+	timer := time.NewTimer(ReadyTimeout)
+	defer timer.Stop()
+	ticker := time.NewTicker(spawnWindowsPollInterval)
+	defer ticker.Stop()
+
+	for {
+		if conn, dialErr := spawnWindowsDial(cfg.IPCEndpoint); dialErr == nil {
+			_ = conn.Close()
+			return pid, nil
+		}
+		select {
+		case waitErr := <-waitDone:
+			if waitErr == nil {
+				return pid, fmt.Errorf("%w: child exited before binding named pipe", ErrSpawnFailed)
+			}
+			return pid, fmt.Errorf("%w: %v", ErrSpawnFailed, waitErr)
+		case <-timer.C:
+			_ = cmd.Process.Kill()
+			select {
+			case <-waitDone:
+			case <-time.After(time.Second):
+			}
+			return pid, ErrSpawnTimeout
+		case <-ticker.C:
+		}
+	}
+}
+
+func withoutReadyFDEnv(env []string) []string {
+	prefix := strings.ToUpper(ReadyFDEnv) + "="
+	out := make([]string, 0, len(env))
+	for _, entry := range env {
+		if strings.HasPrefix(strings.ToUpper(entry), prefix) {
+			continue
+		}
+		out = append(out, entry)
+	}
+	return out
+}
+
 func applyDetach(cmd *exec.Cmd) {
 	cmd.SysProcAttr = &syscall.SysProcAttr{
 		CreationFlags: createNewProcessGroup,

internal/event/busctl/spawn_windows_test.go

@@ -0,0 +1,132 @@
+// 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.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+//go:build windows
+
+package busctl
+
+import (
+	"errors"
+	"fmt"
+	"os"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam"
+)
+
+func TestCrossPlatformCoverageWindowsSpawnUsesNamedPipeReadiness(t *testing.T) {
+	endpoint := fmt.Sprintf(`\\.\pipe\dws-event-spawn-test-%d-%d`, os.Getpid(), time.Now().UnixNano())
+	pid, err := spawnWithMarker(t, "windows-ready", func(cfg *SpawnConfig) {
+		cfg.IPCEndpoint = endpoint
+		cfg.Env = append(cfg.Env, childEndpointEnv+"="+endpoint)
+	})
+	if err != nil {
+		t.Fatalf("Spawn() = %v", err)
+	}
+	if pid <= 0 {
+		t.Fatalf("Spawn() pid = %d", pid)
+	}
+	proc, err := os.FindProcess(pid)
+	if err != nil {
+		t.Fatal(err)
+	}
+	_ = proc.Kill()
+}
+
+func TestCrossPlatformCoverageWindowsSpawnReportsEarlyExit(t *testing.T) {
+	endpoint := fmt.Sprintf(`\\.\pipe\dws-event-spawn-fail-%d-%d`, os.Getpid(), time.Now().UnixNano())
+	_, err := spawnWithMarker(t, "windows-fail", func(cfg *SpawnConfig) {
+		cfg.IPCEndpoint = endpoint
+	})
+	if !errors.Is(err, ErrSpawnFailed) {
+		t.Fatalf("Spawn() error = %v, want ErrSpawnFailed", err)
+	}
+}
+
+func TestCrossPlatformCoverageWindowsSpawnReportsCleanEarlyExit(t *testing.T) {
+	endpoint := fmt.Sprintf(`\\.\pipe\dws-event-spawn-exit-%d-%d`, os.Getpid(), time.Now().UnixNano())
+	_, err := spawnWithMarker(t, "windows-exit", func(cfg *SpawnConfig) {
+		cfg.IPCEndpoint = endpoint
+	})
+	if !errors.Is(err, ErrSpawnFailed) {
+		t.Fatalf("Spawn() error = %v, want ErrSpawnFailed", err)
+	}
+}
+
+func TestCrossPlatformCoverageWindowsSpawnResolvesExecutable(t *testing.T) {
+	endpoint := fmt.Sprintf(`\\.\pipe\dws-event-spawn-resolve-%d-%d`, os.Getpid(), time.Now().UnixNano())
+	testseam.Swap(t, &spawnExecutable, func() (string, error) { return os.Args[0], nil })
+	pid, err := spawnWithMarker(t, "windows-ready", func(cfg *SpawnConfig) {
+		cfg.ExecPath = ""
+		cfg.IPCEndpoint = endpoint
+		cfg.Env = append(cfg.Env, childEndpointEnv+"="+endpoint)
+	})
+	if err != nil {
+		t.Fatalf("Spawn() = %v", err)
+	}
+	proc, err := os.FindProcess(pid)
+	if err != nil {
+		t.Fatal(err)
+	}
+	_ = proc.Kill()
+}
+
+func TestCrossPlatformCoverageWindowsSpawnValidationAndStartErrors(t *testing.T) {
+	endpoint := fmt.Sprintf(`\\.\pipe\dws-event-spawn-errors-%d-%d`, os.Getpid(), time.Now().UnixNano())
+	if _, err := Spawn(SpawnConfig{ClientID: "client"}); err == nil {
+		t.Fatal("missing endpoint unexpectedly succeeded")
+	}
+	testseam.Swap(t, &spawnExecutable, func() (string, error) {
+		return "", errors.New("executable unavailable")
+	})
+	if _, err := Spawn(SpawnConfig{ClientID: "client", IPCEndpoint: endpoint}); err == nil {
+		t.Fatal("executable lookup unexpectedly succeeded")
+	}
+	if _, err := Spawn(SpawnConfig{
+		ClientID:    "client",
+		IPCEndpoint: endpoint,
+		ExecPath:    `C:\\definitely-missing-dws.exe`,
+	}); err == nil {
+		t.Fatal("missing executable unexpectedly started")
+	}
+}
+
+func TestCrossPlatformCoverageWindowsSpawnReadyTimeoutTerminatesChild(t *testing.T) {
+	endpoint := fmt.Sprintf(`\\.\pipe\dws-event-spawn-stall-%d-%d`, os.Getpid(), time.Now().UnixNano())
+	testseam.Swap(t, &ReadyTimeout, 100*time.Millisecond)
+	_, err := spawnWithMarker(t, "windows-stall", func(cfg *SpawnConfig) {
+		cfg.IPCEndpoint = endpoint
+	})
+	if !errors.Is(err, ErrSpawnTimeout) {
+		t.Fatalf("Spawn() error = %v, want ErrSpawnTimeout", err)
+	}
+}
+
+func TestCrossPlatformCoverageWindowsSpawnRemovesInheritedReadyFD(t *testing.T) {
+	env := withoutReadyFDEnv([]string{
+		"PATH=C:\\Windows",
+		ReadyFDEnv + "=3",
+		strings.ToLower(ReadyFDEnv) + "=4",
+	})
+	if len(env) != 1 || !strings.HasPrefix(env[0], "PATH=") {
+		t.Fatalf("withoutReadyFDEnv() = %#v", env)
+	}
+}
+
+func TestCrossPlatformCoverageWindowsUnixReadyPipeValidation(t *testing.T) {
+	if _, err := spawnWithReadyPipe(SpawnConfig{}); err == nil {
+		t.Fatal("spawnWithReadyPipe() unexpectedly accepted an empty client ID")
+	}
+}

internal/event/busctl/stop.go

@@ -17,15 +17,17 @@ import (
 	"errors"
 	"fmt"
 	"os"
+	"strings"
 	"time"
 
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/bus"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/process"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/transport"
 )
 
-// DefaultStopTimeout is the wall-clock budget Stop waits for the bus to
-// exit after the signal is sent. 5s covers the bus's own graceful tear-down
-// (broadcast Bye → consumer goroutines drain → cleanup) with margin.
+// DefaultStopTimeout is the wall-clock budget Stop waits for each graceful or
+// fallback termination phase. 5s covers the bus's own tear-down (broadcast
+// Bye → consumer goroutines drain → cleanup) with margin.
 const DefaultStopTimeout = 5 * time.Second
 
 // ErrNotRunning indicates bus.lock either does not exist or its recorded
@@ -33,20 +35,32 @@ const DefaultStopTimeout = 5 * time.Second
 // distinguish "nothing to stop" from "failed to stop".
 var ErrNotRunning = errors.New("busctl: bus is not running")
 
+// ErrOwnerUnverified indicates the PID from bus.lock is alive but no longer
+// owns that lock. Stop refuses to send a process-level signal in this state
+// because the operating system may have reused the stale PID.
+var ErrOwnerUnverified = errors.New("busctl: bus process ownership could not be verified")
+
 var (
-	stopReadHolderPID = bus.ReadHolderPID
-	stopAlive         = process.Alive
-	stopFindProcess   = os.FindProcess
-	stopSignalProcess = func(proc *os.Process, signal os.Signal) error { return proc.Signal(signal) }
+	stopReadHolderPID       = bus.ReadHolderPID
+	stopValidateHolderOwner = bus.ValidateHolderOwnership
+	stopAlive               = process.Alive
+	stopFindProcess         = os.FindProcess
+	stopSignalProcess       = func(proc *os.Process, signal os.Signal) error { return proc.Signal(signal) }
+	stopDial                = transport.Dial
+	stopRequest             = requestBusStop
+	stopWaitForBusExit      = waitForBusExit
 )
 
 // StopConfig identifies the target bus and tunes timing.
 type StopConfig struct {
 	// WorkDir holds bus.lock; Stop reads the PID from there.
 	WorkDir string
-	// Timeout is the total wall-clock budget for graceful exit. After this,
-	// Stop returns an error; it does NOT escalate to SIGKILL — leave that
-	// to the operator.
+	// IPCEndpoint enables the cross-platform graceful stop RPC. Callers that
+	// know the bus identity should always provide it. Empty preserves the
+	// legacy signal-only fallback for compatibility and focused tests.
+	IPCEndpoint string
+	// Timeout is the wall-clock budget for graceful exit and, if required,
+	// the subsequent platform termination fallback.
 	Timeout time.Duration
 }
 
@@ -54,13 +68,12 @@ type StopConfig struct {
 // for the process to actually die. Returns ErrNotRunning if no bus is
 // running for that work dir.
 //
-// Implementation note: on Unix we send SIGTERM. The bus daemon's Run loop
-// watches its parent ctx for cancellation; the cobra `event _bus` command
-// wires signal.NotifyContext so SIGTERM triggers ctx.Done() → graceful
-// shutdown path. On Windows we use os.Process.Signal(os.Interrupt) which
-// the Go runtime maps to TerminateProcess for processes outside our
-// console group; for v1 that's acceptable (Windows graceful shutdown is
-// future work — plan §16 v2).
+// Stop first asks the bus to shut down through its owner-only IPC endpoint.
+// This is the normal path on every platform and lets the daemon cancel its
+// cloud source, notify consumers, and release its lock. If the endpoint is
+// unavailable (for example an older bus) or graceful shutdown times out, the
+// platform signal is used as a compatibility fallback: SIGTERM on Unix and
+// TerminateProcess via os.Kill on Windows.
 func Stop(cfg StopConfig) error {
 	if cfg.WorkDir == "" {
 		return errors.New("busctl: StopConfig.WorkDir is required")
@@ -81,6 +94,32 @@ func Stop(cfg StopConfig) error {
 	if err != nil {
 		return fmt.Errorf("busctl: find process %d: %w", pid, err)
 	}
+	if strings.TrimSpace(cfg.IPCEndpoint) != "" {
+		if err := stopRequest(cfg.IPCEndpoint); err == nil && stopWaitForBusExit(pid, cfg.Timeout) {
+			return nil
+		}
+	}
+
+	// The bus may finish shutting down immediately after the graceful wait
+	// reaches its deadline (or after a failed IPC request). Recheck before
+	// inspecting ownership so a completed stop is not reported as stale.
+	if !stopAlive(pid) {
+		return nil
+	}
+	owner, err := stopValidateHolderOwner(LockPath(cfg.WorkDir), pid)
+	if err != nil {
+		return fmt.Errorf("busctl: verify bus pid=%d ownership: %w", pid, err)
+	}
+	if !owner {
+		// ValidateHolderOwnership observes a released lock both for a stale,
+		// reused PID and for a bus that exits during the ownership probe. Only
+		// the still-alive case is unsafe to signal.
+		if !stopAlive(pid) {
+			return nil
+		}
+		return fmt.Errorf("%w: pid=%d does not own %s; stale PID was not signalled", ErrOwnerUnverified, pid, LockPath(cfg.WorkDir))
+	}
+
 	if err := stopSignalProcess(proc, stopSignal()); err != nil {
 		// On many Unix platforms Signal returns "process already finished"
 		// when the bus has just exited on its own — treat that as success.
@@ -90,13 +129,45 @@ func Stop(cfg StopConfig) error {
 		return fmt.Errorf("busctl: signal bus pid=%d: %w", pid, err)
 	}
 
-	// Poll for actual exit.
-	deadline := time.Now().Add(cfg.Timeout)
-	for time.Now().Before(deadline) {
-		if !stopAlive(pid) {
-			return nil
-		}
-		time.Sleep(50 * time.Millisecond)
+	if stopWaitForBusExit(pid, cfg.Timeout) {
+		return nil
 	}
 	return fmt.Errorf("busctl: bus pid=%d did not exit within %s", pid, cfg.Timeout)
 }
+
+func requestBusStop(endpoint string) error {
+	conn, err := stopDial(endpoint)
+	if err != nil {
+		return fmt.Errorf("busctl: dial bus for stop: %w", err)
+	}
+	defer conn.Close()
+	_ = conn.SetDeadline(time.Now().Add(DefaultStatusRPCTimeout))
+	w := transport.NewWriter(conn)
+	r := transport.NewReader(conn)
+	if err := w.WriteJSON(transport.Hello{
+		Type:        transport.FrameTypeHello,
+		ConsumerPID: os.Getpid(),
+		Role:        transport.HelloRoleStop,
+	}); err != nil {
+		return fmt.Errorf("busctl: write stop hello: %w", err)
+	}
+	var bye transport.Bye
+	if err := r.ReadJSON(&bye); err != nil {
+		return fmt.Errorf("busctl: read stop response: %w", err)
+	}
+	if bye.Type != transport.FrameTypeBye || bye.Reason != "stop_request" {
+		return fmt.Errorf("busctl: unexpected stop response type=%q reason=%q", bye.Type, bye.Reason)
+	}
+	return nil
+}
+
+func waitForBusExit(pid int, timeout time.Duration) bool {
+	deadline := time.Now().Add(timeout)
+	for time.Now().Before(deadline) {
+		if !stopAlive(pid) {
+			return true
+		}
+		time.Sleep(50 * time.Millisecond)
+	}
+	return !stopAlive(pid)
+}

internal/event/busctl/stop_test.go

@@ -16,6 +16,7 @@ package busctl
 import (
 	"context"
 	"errors"
+	"net"
 	"os"
 	"os/exec"
 	"path/filepath"
@@ -23,7 +24,10 @@ import (
 	"testing"
 	"time"
 
+	dwsevent "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/bus"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/transport"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam"
 )
 
 func TestStop_NotRunningWhenLockMissing(t *testing.T) {
@@ -34,7 +38,7 @@ func TestStop_NotRunningWhenLockMissing(t *testing.T) {
 	}
 }
 
-func TestStop_NotRunningWhenPIDDead(t *testing.T) {
+func TestCrossPlatformCoverageStopNotRunningWhenPIDDead(t *testing.T) {
 	dir := shortTempDir(t)
 	// Write a definitely-dead PID into bus.lock.
 	if err := os.WriteFile(LockPath(dir), []byte("2147483646\n"), 0o600); err != nil {
@@ -46,6 +50,269 @@ func TestStop_NotRunningWhenPIDDead(t *testing.T) {
 	}
 }
 
+func TestCrossPlatformCoverageStopPrefersGracefulIPC(t *testing.T) {
+	const pid = 4242
+	stopped := false
+	signals := 0
+	testseam.Swap(t, &stopReadHolderPID, func(string) int { return pid })
+	testseam.Swap(t, &stopAlive, func(int) bool { return !stopped })
+	proc, err := os.FindProcess(os.Getpid())
+	if err != nil {
+		t.Fatal(err)
+	}
+	testseam.Swap(t, &stopFindProcess, func(int) (*os.Process, error) { return proc, nil })
+	testseam.Swap(t, &stopRequest, func(endpoint string) error {
+		if endpoint != "test-endpoint" {
+			t.Fatalf("stop endpoint = %q", endpoint)
+		}
+		stopped = true
+		return nil
+	})
+	testseam.Swap(t, &stopSignalProcess, func(*os.Process, os.Signal) error {
+		signals++
+		return nil
+	})
+
+	if err := Stop(StopConfig{
+		WorkDir:     "test-workdir",
+		IPCEndpoint: "test-endpoint",
+		Timeout:     time.Second,
+	}); err != nil {
+		t.Fatalf("Stop() = %v", err)
+	}
+	if signals != 0 {
+		t.Fatalf("graceful IPC stop used %d process signals", signals)
+	}
+}
+
+func TestCrossPlatformCoverageStopDoesNotSignalUnverifiedReusedPID(t *testing.T) {
+	const pid = 4242
+	testseam.Swap(t, &stopReadHolderPID, func(string) int { return pid })
+	testseam.Swap(t, &stopAlive, func(int) bool { return true })
+	proc, err := os.FindProcess(os.Getpid())
+	if err != nil {
+		t.Fatal(err)
+	}
+	testseam.Swap(t, &stopFindProcess, func(int) (*os.Process, error) { return proc, nil })
+	testseam.Swap(t, &stopRequest, func(string) error { return errors.New("stale endpoint") })
+	testseam.Swap(t, &stopValidateHolderOwner, func(path string, gotPID int) (bool, error) {
+		if path != LockPath("test-workdir") || gotPID != pid {
+			t.Fatalf("ownership check path=%q pid=%d", path, gotPID)
+		}
+		return false, nil
+	})
+	signals := 0
+	testseam.Swap(t, &stopSignalProcess, func(*os.Process, os.Signal) error {
+		signals++
+		return nil
+	})
+
+	err = Stop(StopConfig{
+		WorkDir:     "test-workdir",
+		IPCEndpoint: "stale-endpoint",
+		Timeout:     time.Millisecond,
+	})
+	if !errors.Is(err, ErrOwnerUnverified) {
+		t.Fatalf("Stop() error = %v, want ErrOwnerUnverified", err)
+	}
+	if signals != 0 {
+		t.Fatalf("unverified reused PID received %d signals", signals)
+	}
+}
+
+func TestCrossPlatformCoverageStopAcceptsExitAtGracefulTimeoutBoundary(t *testing.T) {
+	const pid = 4242
+
+	t.Run("before ownership validation", func(t *testing.T) {
+		exited := false
+		validated := false
+		testseam.Swap(t, &stopReadHolderPID, func(string) int { return pid })
+		testseam.Swap(t, &stopAlive, func(int) bool { return !exited })
+		proc, err := os.FindProcess(os.Getpid())
+		if err != nil {
+			t.Fatal(err)
+		}
+		testseam.Swap(t, &stopFindProcess, func(int) (*os.Process, error) { return proc, nil })
+		testseam.Swap(t, &stopRequest, func(string) error { return nil })
+		testseam.Swap(t, &stopWaitForBusExit, func(int, time.Duration) bool {
+			exited = true
+			return false
+		})
+		testseam.Swap(t, &stopValidateHolderOwner, func(string, int) (bool, error) {
+			validated = true
+			return false, nil
+		})
+
+		if err := Stop(StopConfig{WorkDir: "test-workdir", IPCEndpoint: "test-endpoint"}); err != nil {
+			t.Fatalf("Stop() = %v, want success after bus exit", err)
+		}
+		if validated {
+			t.Fatal("ownership was validated after the bus had already exited")
+		}
+	})
+
+	t.Run("during ownership validation", func(t *testing.T) {
+		exited := false
+		signals := 0
+		testseam.Swap(t, &stopReadHolderPID, func(string) int { return pid })
+		testseam.Swap(t, &stopAlive, func(int) bool { return !exited })
+		proc, err := os.FindProcess(os.Getpid())
+		if err != nil {
+			t.Fatal(err)
+		}
+		testseam.Swap(t, &stopFindProcess, func(int) (*os.Process, error) { return proc, nil })
+		testseam.Swap(t, &stopRequest, func(string) error { return nil })
+		testseam.Swap(t, &stopWaitForBusExit, func(int, time.Duration) bool { return false })
+		testseam.Swap(t, &stopValidateHolderOwner, func(string, int) (bool, error) {
+			exited = true
+			return false, nil
+		})
+		testseam.Swap(t, &stopSignalProcess, func(*os.Process, os.Signal) error {
+			signals++
+			return nil
+		})
+
+		if err := Stop(StopConfig{WorkDir: "test-workdir", IPCEndpoint: "test-endpoint"}); err != nil {
+			t.Fatalf("Stop() = %v, want success after exit during ownership validation", err)
+		}
+		if signals != 0 {
+			t.Fatalf("exited bus received %d fallback signals", signals)
+		}
+	})
+}
+
+func TestCrossPlatformCoverageStopReportsOwnershipValidationError(t *testing.T) {
+	const pid = 4242
+	errInjected := errors.New("ownership validation failed")
+	testseam.Swap(t, &stopReadHolderPID, func(string) int { return pid })
+	testseam.Swap(t, &stopAlive, func(int) bool { return true })
+	proc, err := os.FindProcess(os.Getpid())
+	if err != nil {
+		t.Fatal(err)
+	}
+	testseam.Swap(t, &stopFindProcess, func(int) (*os.Process, error) { return proc, nil })
+	testseam.Swap(t, &stopValidateHolderOwner, func(string, int) (bool, error) {
+		return false, errInjected
+	})
+	signals := 0
+	testseam.Swap(t, &stopSignalProcess, func(*os.Process, os.Signal) error {
+		signals++
+		return nil
+	})
+
+	err = Stop(StopConfig{WorkDir: "test-workdir"})
+	if !errors.Is(err, errInjected) {
+		t.Fatalf("Stop() error = %v, want injected ownership error", err)
+	}
+	if signals != 0 {
+		t.Fatalf("ownership validation error sent %d signals", signals)
+	}
+}
+
+func TestCrossPlatformCoverageRequestBusStopProtocol(t *testing.T) {
+	dir := shortTempDir(t)
+	endpoint := dwsevent.IPCEndpoint(
+		dir,
+		"open",
+		dwsevent.SourceKindAppStream,
+		dwsevent.IdentityHash(dir),
+	)
+	listener, err := transport.Listen(endpoint)
+	if err != nil {
+		t.Fatalf("Listen() = %v", err)
+	}
+	defer listener.Close()
+	serverDone := make(chan error, 1)
+	go func() {
+		conn, err := listener.Accept()
+		if err != nil {
+			serverDone <- err
+			return
+		}
+		defer conn.Close()
+		r := transport.NewReader(conn)
+		w := transport.NewWriter(conn)
+		var hello transport.Hello
+		if err := r.ReadJSON(&hello); err != nil {
+			serverDone <- err
+			return
+		}
+		if hello.Type != transport.FrameTypeHello || hello.Role != transport.HelloRoleStop {
+			serverDone <- errors.New("unexpected stop hello")
+			return
+		}
+		serverDone <- w.WriteJSON(transport.Bye{
+			Type:   transport.FrameTypeBye,
+			Reason: "stop_request",
+		})
+	}()
+
+	if err := requestBusStop(endpoint); err != nil {
+		t.Fatalf("requestBusStop() = %v", err)
+	}
+	if err := <-serverDone; err != nil {
+		t.Fatalf("stop protocol server = %v", err)
+	}
+}
+
+func TestCrossPlatformCoverageRequestBusStopErrors(t *testing.T) {
+	t.Run("dial", func(t *testing.T) {
+		testseam.Swap(t, &stopDial, func(string) (net.Conn, error) {
+			return nil, errors.New("dial failed")
+		})
+		if err := requestBusStop("test-endpoint"); err == nil {
+			t.Fatal("requestBusStop() unexpectedly succeeded")
+		}
+	})
+
+	t.Run("write", func(t *testing.T) {
+		testseam.Swap(t, &stopDial, func(string) (net.Conn, error) {
+			return &queryErrorConn{failAt: 1}, nil
+		})
+		if err := requestBusStop("test-endpoint"); err == nil {
+			t.Fatal("requestBusStop() unexpectedly succeeded")
+		}
+	})
+
+	t.Run("read", func(t *testing.T) {
+		testseam.Swap(t, &stopDial, func(string) (net.Conn, error) {
+			return &queryErrorConn{}, nil
+		})
+		if err := requestBusStop("test-endpoint"); err == nil {
+			t.Fatal("requestBusStop() unexpectedly succeeded")
+		}
+	})
+
+	t.Run("unexpected response", func(t *testing.T) {
+		client, server := net.Pipe()
+		t.Cleanup(func() {
+			_ = client.Close()
+			_ = server.Close()
+		})
+		testseam.Swap(t, &stopDial, func(string) (net.Conn, error) {
+			return client, nil
+		})
+		serverDone := make(chan error, 1)
+		go func() {
+			var hello transport.Hello
+			if err := transport.NewReader(server).ReadJSON(&hello); err != nil {
+				serverDone <- err
+				return
+			}
+			serverDone <- transport.NewWriter(server).WriteJSON(transport.Bye{
+				Type:   transport.FrameTypeBye,
+				Reason: "unexpected",
+			})
+		}()
+		if err := requestBusStop("test-endpoint"); err == nil {
+			t.Fatal("requestBusStop() unexpectedly succeeded")
+		}
+		if err := <-serverDone; err != nil {
+			t.Fatalf("stop protocol server = %v", err)
+		}
+	})
+}
+
 func TestStop_SignalsLiveProcess(t *testing.T) {
 	skipOnWindows(t)
 	dir := shortTempDir(t)
@@ -63,6 +330,7 @@ func TestStop_SignalsLiveProcess(t *testing.T) {
 		}
 	}()
 	pid := cmd.Process.Pid
+	testseam.Swap(t, &stopValidateHolderOwner, func(string, int) (bool, error) { return true, nil })
 
 	// Reap the child in background so Wait doesn't leave a zombie.
 	waited := make(chan error, 1)
@@ -111,6 +379,7 @@ func TestStop_TimeoutWhenChildIgnoresSignal(t *testing.T) {
 		_, _ = cmd.Process.Wait()
 	}()
 	pid := cmd.Process.Pid
+	testseam.Swap(t, &stopValidateHolderOwner, func(string, int) (bool, error) { return true, nil })
 
 	if err := os.WriteFile(LockPath(dir), []byte(strconv.Itoa(pid)+"\n"), 0o600); err != nil {
 		t.Fatal(err)

internal/event/busctl/stop_windows.go

@@ -17,8 +17,7 @@ package busctl
 
 import "os"
 
-// stopSignal returns the graceful-shutdown signal for Windows. The Go
-// runtime maps os.Interrupt to TerminateProcess for non-console-group
-// processes — not truly graceful, but acceptable for v1 (Windows graceful
-// shutdown via Ctrl+Break is in the v2 backlog, plan §16).
-func stopSignal() os.Signal { return os.Interrupt }
+// stopSignal is only the fallback after the graceful IPC stop path fails or
+// times out. Go maps os.Kill to TerminateProcess on Windows; os.Interrupt is
+// unsupported and returns syscall.EWINDOWS.
+func stopSignal() os.Signal { return os.Kill }

internal/event/busctl/stop_windows_test.go

@@ -0,0 +1,27 @@
+// 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.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+//go:build windows
+
+package busctl
+
+import (
+	"os"
+	"testing"
+)
+
+func TestCrossPlatformCoverageWindowsStopFallbackUsesKill(t *testing.T) {
+	if stopSignal() != os.Kill {
+		t.Fatalf("stopSignal() = %v, want os.Kill", stopSignal())
+	}
+}

internal/helpers/aisearch.go

@@ -3,18 +3,21 @@ package helpers
 import (
 	"strings"
 
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract"
 	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
 	"github.com/spf13/cobra"
-
-	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract"
 )
 
 // boolPtr returns a pointer to v, for ParamDecl.Required declarations.
 func boolPtr(v bool) *bool { return &v }
 
-// aisearchKeywordAliases 是 --keyword flag 的同义瞎猜兜底列表。
-// 模型可能写 --name / --q / --query / --text，这些都被识别为 keyword。
-var aisearchKeywordAliases = []string{"name", "q", "query", "text"}
+// 这些是原有的宽松兜底名，不属于本次 Primary 迁移；保持原生 hidden
+// 注册，不给它们新增 alias_of/origin 元数据。
+var aisearchPersonGuessFlags = []string{"name", "q", "text"}
+
+// 历史解析优先级必须独立于新旧 Primary：双传时旧 --keyword 始终获胜。
+var aisearchQueryResolutionOrder = []string{"keyword", "name", "q", "query", "text"}
 
 // flagValue 安全地读取 flag 值：先查 local，再查自身 PersistentFlags，
 // 再查 parents 的 PersistentFlags。比 cmd.Flags().GetString 更鲁棒，
@@ -58,14 +61,11 @@ func aisearchFlagOrDefault(cmd *cobra.Command, primary, def string, aliases ...s
 	return def
 }
 
-// resolveAisearchKeyword 从命令的 flag 中解析 keyword：优先 --keyword，
-// 否则 fallback 到 aisearchKeywordAliases 中的任一同义 flag。
+// resolveAisearchKeyword 按历史顺序解析人员搜索词。虽然公开 Primary 已改为
+// --query，但兼容期内显式旧 --keyword 的值仍优先。
 func resolveAisearchKeyword(cmd *cobra.Command) string {
-	if v := flagValue(cmd, "keyword"); v != "" {
-		return v
-	}
-	for _, alias := range aisearchKeywordAliases {
-		if v := flagValue(cmd, alias); v != "" {
+	for _, name := range aisearchQueryResolutionOrder {
+		if v := flagValue(cmd, name); v != "" {
 			return v
 		}
 	}
@@ -73,9 +73,23 @@ func resolveAisearchKeyword(cmd *cobra.Command) string {
 }
 
 func addAisearchPersonFlags(cmd *cobra.Command) {
-	cmd.Flags().StringP("keyword", "w", "", "搜索关键词 (必填，如人名、技能关键词等)")
+	// Alias evidence must be emitted by corecmd.FlagSpec.Aliases. Build the pair
+	// on a temporary declaration command so the legacy alias can retain its
+	// historical -w shorthand without extending the global alias mechanism or
+	// assigning that shorthand to the new --query Primary.
+	declaration := &cobra.Command{Use: "aisearch-query-flags"}
+	corecmd.RegisterFlags(declaration, []corecmd.FlagSpec{{
+		Name:    "query",
+		Usage:   "搜索关键词 (必填，如人名、技能关键词等)",
+		Aliases: []string{"keyword"},
+	}})
+	queryFlag := declaration.Flags().Lookup("query")
+	keywordFlag := declaration.Flags().Lookup("keyword")
+	keywordFlag.Shorthand = "w"
+	cmd.Flags().AddFlag(queryFlag)
+	cmd.Flags().AddFlag(keywordFlag)
 	cmd.Flags().StringP("dimension", "d", "all", "查询维度: all/name/department/position/duty/supervisor/subordinate/phone/jobNumber，多个用逗号分隔")
-	for _, alias := range aisearchKeywordAliases {
+	for _, alias := range aisearchPersonGuessFlags {
 		cmd.Flags().String(alias, "", "")
 		_ = cmd.Flags().MarkHidden(alias)
 	}
@@ -98,8 +112,7 @@ func runAisearchPerson(cmd *cobra.Command, _ []string) error {
 	}
 	keyword := resolveAisearchKeyword(cmd)
 	if keyword == "" {
-		// 复用原有报错文案（"keyword is required"）
-		return validateRequiredFlags(cmd, "keyword")
+		return validateRequiredFlags(cmd, "query")
 	}
 	dimensions := parseDimensions(flagValue(cmd, "dimension"))
 	return callMCPTool("enterprise_person_search", map[string]any{
@@ -188,8 +201,8 @@ func newAisearchCommand() *cobra.Command {
 		Use:   "aisearch",
 		Short: "AI 搜问",
 		Long:  `AI 搜问：搜索企业人员信息、企业内部知识内容与企业内部行为记录。`,
-		// 智能 root：模型常漏 person 子命令直接 dws aisearch --keyword xxx，
-		// 检测到 keyword 就自动等价于 person；否则退回 group help。
+		// 智能 root：模型常漏 person 子命令直接 dws aisearch --query xxx，
+		// 检测到 query 就自动等价于 person；否则退回 group help。
 		RunE: func(cmd *cobra.Command, args []string) error {
 			if resolveAisearchKeyword(cmd) != "" {
 				return runAisearchPerson(cmd, args)
@@ -199,9 +212,9 @@ func newAisearchCommand() *cobra.Command {
 	}
 
 	// root 和 person 各自定义同一组本地 flag，这样：
-	//   - dws aisearch --keyword xxx           ← root 自己能解析
-	//   - dws aisearch person --keyword xxx    ← person 本地 flag
-	//   - dws aisearch search --keyword xxx    ← search 是 person 的 alias
+	//   - dws aisearch --query xxx           ← root 自己能解析
+	//   - dws aisearch person --query xxx    ← person 本地 flag
+	//   - dws aisearch search --query xxx    ← search 是 person 的 alias
 	// 不能放在 product PersistentFlags：否则 enterprise/behavior 会公开接受
 	// 它们不拥有的 person-only dimension，破坏 Help ↔ Schema 完整性。
 	addAisearchPersonFlags(root)
@@ -219,7 +232,7 @@ func newAisearchCommand() *cobra.Command {
 			"query", "people", "ask", "find", "lookup",
 			"contact",
 		},
-		// 显式声明允许任意位置参数：模型可能写 dws aisearch person search --keyword xxx，
+		// 显式声明允许任意位置参数：模型可能写 dws aisearch person search --query xxx，
 		// 此时 "search" 会作为 positional arg 被忽略，不报错。
 		Args:  cobra.ArbitraryArgs,
 		Short: "搜索企业人员",
@@ -237,13 +250,13 @@ func newAisearchCommand() *cobra.Command {
   jobNumber    工号
 
 多个维度用逗号分隔。`,
-		Example: `  dws aisearch person --keyword "张三" --dimension department
-  dws aisearch person --keyword "产品部" --dimension department
-  dws aisearch person --keyword "五道" --dimension supervisor
-  dws aisearch person --keyword "AI搜问" --dimension duty
-  dws aisearch person --keyword "李四" --dimension name,department
-  dws aisearch person --keyword "13800138000" --dimension phone
-  dws aisearch person --keyword "W12345" --dimension jobNumber`,
+		Example: `  dws aisearch person --query "张三" --dimension department
+  dws aisearch person --query "产品部" --dimension department
+  dws aisearch person --query "五道" --dimension supervisor
+  dws aisearch person --query "AI搜问" --dimension duty
+  dws aisearch person --query "李四" --dimension name,department
+  dws aisearch person --query "13800138000" --dimension phone
+  dws aisearch person --query "W12345" --dimension jobNumber`,
 		RunE: runAisearchPerson,
 	}
 	DeclareLeafMetadata(personCmd, LeafSpec{
@@ -277,10 +290,13 @@ func newAisearchCommand() *cobra.Command {
 					"搜企业知识内容时用 aisearch enterprise；搜行为记录时用 aisearch behavior",
 				},
 				Examples: []string{
-					"dws aisearch person --keyword \"张三\" --dimension name --format json",
-					"dws aisearch person --keyword \"五道\" --dimension supervisor --format json",
+					"dws aisearch person --query \"张三\" --dimension name --format json",
+					"dws aisearch person --query \"五道\" --dimension supervisor --format json",
 				},
 			},
+			Parameters: []contract.ParamDecl{
+				{Name: "query", Property: "keyword", Required: boolPtr(true)},
+			},
 		},
 	})
 	addAisearchPersonFlags(personCmd)

internal/helpers/aisearch_test.go

@@ -4,7 +4,12 @@
 
 package helpers
 
-import "testing"
+import (
+	"strings"
+	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/runtimeannotate"
+)
 
 func TestAisearchPersonFlagsDoNotLeakIntoContentCommands(t *testing.T) {
 	root := newAisearchCommand()
@@ -12,12 +17,34 @@ func TestAisearchPersonFlagsDoNotLeakIntoContentCommands(t *testing.T) {
 	if err != nil {
 		t.Fatal(err)
 	}
-	for _, name := range []string{"keyword", "dimension"} {
+	for _, name := range []string{"query", "dimension"} {
 		flag := person.Flags().Lookup(name)
 		if flag == nil || flag.Hidden {
 			t.Fatalf("person --%s = %#v, want visible local flag", name, flag)
 		}
 	}
+	if person.Flags().Lookup("query").Shorthand != "" {
+		t.Fatal("new Primary --query must not acquire a shorthand")
+	}
+	keyword := person.Flags().Lookup("keyword")
+	if keyword == nil || !keyword.Hidden || keyword.Shorthand != "w" {
+		t.Fatalf("person --keyword = %#v, want hidden legacy flag with -w", keyword)
+	}
+	if got := keyword.Annotations[runtimeannotate.AnnotationFlagAliasOf]; len(got) != 1 || got[0] != "query" {
+		t.Fatalf("person --keyword alias_of = %#v, want query", got)
+	}
+	if got := keyword.Annotations[runtimeannotate.AnnotationFlagAliasOrigin]; len(got) != 1 || got[0] != runtimeannotate.FlagAliasOriginCorecmdV1 {
+		t.Fatalf("person --keyword alias_origin = %#v, want %q", got, runtimeannotate.FlagAliasOriginCorecmdV1)
+	}
+	for _, name := range []string{"name", "q", "text"} {
+		flag := person.Flags().Lookup(name)
+		if flag == nil || !flag.Hidden {
+			t.Fatalf("person --%s = %#v, want preserved hidden guess flag", name, flag)
+		}
+		if got := flag.Annotations[runtimeannotate.AnnotationFlagAliasOf]; len(got) != 0 {
+			t.Fatalf("person --%s unexpectedly gained alias_of metadata: %#v", name, got)
+		}
+	}
 
 	for _, path := range []string{"enterprise", "behavior"} {
 		cmd, _, err := root.Find([]string{path})
@@ -35,3 +62,38 @@ func TestAisearchPersonFlagsDoNotLeakIntoContentCommands(t *testing.T) {
 		}
 	}
 }
+
+func TestAisearchPersonQueryPrimaryCompatibility(t *testing.T) {
+	tests := []struct {
+		name string
+		args []string
+		want string
+	}{
+		{name: "root new", args: []string{"--query", "new"}, want: "new"},
+		{name: "root old", args: []string{"--keyword", "old"}, want: "old"},
+		{name: "root old shorthand", args: []string{"-w", "old-short"}, want: "old-short"},
+		{name: "root both old wins", args: []string{"--query", "new", "--keyword", "old"}, want: "old"},
+		{name: "person new", args: []string{"person", "--query", "new"}, want: "new"},
+		{name: "person old", args: []string{"person", "--keyword", "old"}, want: "old"},
+		{name: "person old shorthand", args: []string{"person", "-w", "old-short"}, want: "old-short"},
+		{name: "person both old wins", args: []string{"person", "--query", "new", "--keyword", "old"}, want: "old"},
+	}
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			caller := &scriptedToolCaller{}
+			installScriptedCaller(t, caller)
+			if err := executeFilterCoverage(t, newAisearchCommand(), tc.args...); err != nil {
+				t.Fatal(err)
+			}
+			if caller.tool != "enterprise_person_search" || caller.args["keyword"] != tc.want {
+				t.Fatalf("call = %s %#v, want backend keyword %q", caller.tool, caller.args, tc.want)
+			}
+		})
+	}
+
+	installScriptedCaller(t, &scriptedToolCaller{})
+	err := executeFilterCoverage(t, newAisearchCommand(), "person")
+	if err == nil || !strings.Contains(err.Error(), "--query") || strings.Contains(err.Error(), "--keyword") {
+		t.Fatalf("missing query error = %v, want only new Primary", err)
+	}
+}

internal/helpers/aitable.go

@@ -520,6 +520,102 @@ func normalizeFilters(parsed any) any {
 	}
 }
 
+type aitableStatsItem struct {
+	FieldID   string `json:"fieldId"`
+	StatsType string `json:"statsType"`
+}
+
+func aitableStatsValidationf(format string, args ...any) error {
+	return apperrors.NewValidation(fmt.Sprintf(format, args...))
+}
+
+func parseAitableStatsItems(raw string, uppercase, uniqueFields bool, maxItems int) ([]map[string]any, error) {
+	var items []aitableStatsItem
+	if err := json.Unmarshal([]byte(raw), &items); err != nil {
+		return nil, aitableStatsValidationf("--stats 必须是 JSON 数组: %v", err)
+	}
+	var strictItems []aitableStatsItem
+	decoder := json.NewDecoder(strings.NewReader(raw))
+	decoder.DisallowUnknownFields()
+	if err := decoder.Decode(&strictItems); err != nil {
+		return nil, aitableStatsValidationf("--stats 包含不支持的字段: %v", err)
+	}
+	items = strictItems
+	if len(items) == 0 {
+		return nil, aitableStatsValidationf("--stats 至少需要一个统计项")
+	}
+	if maxItems > 0 && len(items) > maxItems {
+		return nil, aitableStatsValidationf("--stats 单次最多支持 %d 个统计项，got %d", maxItems, len(items))
+	}
+
+	seenFields := make(map[string]struct{}, len(items))
+	out := make([]map[string]any, 0, len(items))
+	for index, item := range items {
+		item.FieldID = strings.TrimSpace(item.FieldID)
+		item.StatsType = strings.TrimSpace(item.StatsType)
+		if item.FieldID == "" || item.StatsType == "" {
+			return nil, aitableStatsValidationf("--stats[%d] 的 fieldId 和 statsType 均不能为空", index)
+		}
+		if uniqueFields {
+			if _, exists := seenFields[item.FieldID]; exists {
+				return nil, aitableStatsValidationf("--stats 中 fieldId %q 重复；query_records_stats 要求同一字段的多个统计类型拆成多次调用", item.FieldID)
+			}
+			seenFields[item.FieldID] = struct{}{}
+		}
+		if uppercase && item.StatsType != strings.ToUpper(item.StatsType) {
+			return nil, aitableStatsValidationf("--stats[%d].statsType 必须使用大写枚举值，got %q", index, item.StatsType)
+		}
+		if !uppercase && item.StatsType != strings.ToLower(item.StatsType) {
+			return nil, aitableStatsValidationf("--stats[%d].statsType 必须使用小写值，got %q", index, item.StatsType)
+		}
+		out = append(out, map[string]any{"fieldId": item.FieldID, "statsType": item.StatsType})
+	}
+	return out, nil
+}
+
+func parseAitableObjectFlag(name, raw string) (map[string]any, error) {
+	decoder := json.NewDecoder(strings.NewReader(raw))
+	decoder.UseNumber()
+	var value map[string]any
+	if err := decoder.Decode(&value); err != nil {
+		return nil, aitableStatsValidationf("--%s 必须是 JSON 对象: %v", name, err)
+	}
+	if value == nil {
+		return nil, aitableStatsValidationf("--%s 必须是 JSON 对象，不能是 null", name)
+	}
+	var trailing any
+	if err := decoder.Decode(&trailing); err != io.EOF {
+		if err == nil {
+			return nil, aitableStatsValidationf("--%s 只能包含一个 JSON 对象", name)
+		}
+		return nil, aitableStatsValidationf("--%s 包含无效的尾随内容: %v", name, err)
+	}
+	return value, nil
+}
+
+func validateAitableStatsFilters(value map[string]any, rawJSON string) error {
+	if err := validateFiltersStructure(value, rawJSON); err != nil {
+		return aitableStatsValidationf("%v", err)
+	}
+	return nil
+}
+
+func validateAitableArrayDSL(name, raw string) error {
+	var value []any
+	if err := json.Unmarshal([]byte(raw), &value); err != nil {
+		return aitableStatsValidationf("--%s 必须是 JSON 数组字符串: %v", name, err)
+	}
+	if len(value) == 0 {
+		return aitableStatsValidationf("--%s 至少需要一个条目", name)
+	}
+	for index, item := range value {
+		if _, ok := item.(map[string]any); !ok {
+			return aitableStatsValidationf("--%s[%d] 必须是 JSON 对象，got %T", name, index, item)
+		}
+	}
+	return nil
+}
+
 // normalizeViewConfigFilter 将 view config 中的 filter 字段规范化为服务端要求的数组格式。
 // 服务端 POJO 要求 config.filter 为 []FilterRule（JSON array）。
 // 常见错误格式：
@@ -695,15 +791,29 @@ const aitableMaxRetries = 3
 // callAitableTool 是 aitable 专用的 MCP 调用入口，带自动重试。
 // 替代直接调用 callMCPTool，对网络抖动和服务端瞬态错误进行透明重试。
 func callAitableTool(toolName string, args map[string]any) error {
+	return callAitableToolContext(context.Background(), toolName, args)
+}
+
+func callAitableToolContext(ctx context.Context, toolName string, args map[string]any) error {
+	if ctx == nil {
+		ctx = context.Background()
+	}
 	var lastErr error
 	for attempt := 0; attempt <= aitableMaxRetries; attempt++ {
+		if err := ctx.Err(); err != nil {
+			return err
+		}
 		if attempt > 0 {
 			backoff := time.Duration(1<<(attempt-1)) * time.Second // 1s, 2s, 4s
 			fmt.Fprintf(os.Stderr, "[aitable retry %d/%d] %s after %v...\n", attempt, aitableMaxRetries, toolName, backoff)
-			helperSleep(backoff)
+			select {
+			case <-ctx.Done():
+				return ctx.Err()
+			case <-helperAfter(backoff):
+			}
 		}
 
-		err := callMCPTool(toolName, args)
+		err := callMCPToolContext(ctx, toolName, args)
 		if err == nil {
 			return nil
 		}
@@ -1098,7 +1208,7 @@ func newAitableCommand() *cobra.Command {
   dws aitable base       [list|search|get|get-primary-doc-id|create|update|delete|copy]  Base 管理
   dws aitable table      [get|create|update|delete]                                     数据表管理
   dws aitable field      [get|create|update|delete|search-options]                      字段管理
-  dws aitable record     [query|create|update|delete]                                   记录管理
+  dws aitable record     [query|stats|group-stats|create|update|delete]                 记录管理
   dws aitable view       [get|create|update|delete]                                     视图管理
   dws aitable form       [list|delete|update]                                           表单管理
   dws aitable form field [list|update|hide]                                             表单字段管理
@@ -1781,7 +1891,7 @@ config 结构参考：
 			if v, _ := cmd.Flags().GetString("field-ids"); v != "" {
 				toolArgs["fieldIds"] = parseCSVValues(v)
 			}
-			return callAitableTool("get_fields", toolArgs)
+			return callAitableToolContext(cmd.Context(), "get_fields", toolArgs)
 		},
 	}
 	DeclareLeafMetadata(fieldGetCmd, LeafSpec{
@@ -2245,6 +2355,199 @@ newFieldName、config、aiConfig 至少传入一项。
 		},
 	})
 
+	recordStatsCmd := &cobra.Command{
+		Use:   "stats",
+		Short: "整表或过滤后的字段聚合统计",
+		Long: `对单张数据表执行不分组的服务端聚合，底层调用 query_records_stats。
+适用于记录计数、求和、平均值、最大值、最小值、中位数、去重数、完整率等标量统计。
+
+--stats 是 JSON 数组，单次最多 20 项；每项必须包含 fieldId 和大写 statsType。
+同一个 fieldId 不能在一次请求中重复，如需对同一字段计算多个指标，请拆成多次调用。
+常用 statsType：COUNT、COUNT_COLUMN、SUM、AVG、MAX、MIN、MEDIAN、STANDARD_DEVIATION、RANGE、
+DISTINCT、DISTINCT_RATIO、EXISTS、UN_EXISTS、EXIST_RATIO、UN_EXIST_RATIO、CHECKED、UN_CHECKED、
+CHECKED_RATIO、UN_CHECKED_RATIO、LATEST_DATE、EARLIEST_DATE、DATE_RANGE、DATE_RANGE_MONTH。
+
+需要统计全部匹配记录时不要传 --limit；limit 会改变参与统计的记录范围。
+lt/gt/lte/gte 的过滤值必须使用 JSON 数字；单选/多选过滤建议使用 field get 返回的选项 ID。`,
+		Example: `  dws aitable record stats --base-id BASE_ID --table-id TABLE_ID --stats '[{"fieldId":"fldAmount","statsType":"SUM"}]'
+  dws aitable record stats --base-id BASE_ID --table-id TABLE_ID --filters '{"operator":"and","operands":[{"operator":"gt","operands":["fldAmount",0]}]}' --stats '[{"fieldId":"fldTitle","statsType":"COUNT"}]'`,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			if err := validateRequiredFlags(cmd, "table-id", "stats"); err != nil {
+				return err
+			}
+			baseID, err := mustFlagOrFallback(cmd, "base-id", "base")
+			if err != nil {
+				return err
+			}
+			stats, err := parseAitableStatsItems(mustGetFlag(cmd, "stats"), true, true, 20)
+			if err != nil {
+				return err
+			}
+			toolArgs := map[string]any{
+				"baseId":  baseID,
+				"tableId": mustGetFlag(cmd, "table-id"),
+				"stats":   stats,
+			}
+			if raw, _ := cmd.Flags().GetString("filters"); raw != "" {
+				filters, err := parseAitableObjectFlag("filters", raw)
+				if err != nil {
+					return err
+				}
+				if err := validateAitableStatsFilters(filters, raw); err != nil {
+					return err
+				}
+				toolArgs["filters"] = normalizeFilters(filters)
+			}
+			if raw, _ := cmd.Flags().GetString("sort"); raw != "" {
+				if err := validateAitableArrayDSL("sort", raw); err != nil {
+					return err
+				}
+				// query_records_stats 的 MCP Schema 将 sort 定义为 JSON 数组编码后的字符串，
+				// 与 query_records 使用的数组类型不同。
+				toolArgs["sort"] = raw
+			}
+			if value, _ := cmd.Flags().GetInt("limit"); cmd.Flags().Changed("limit") {
+				if value <= 0 {
+					return aitableStatsValidationf("--limit 必须大于 0；统计全部匹配记录时请省略该参数")
+				}
+				toolArgs["limit"] = value
+			}
+			if value, _ := cmd.Flags().GetString("keyword"); value != "" {
+				toolArgs["keyword"] = value
+			}
+			if value, _ := cmd.Flags().GetString("search-field-ids"); value != "" {
+				toolArgs["searchFieldIds"] = parseCSVValues(value)
+			}
+			if value, _ := cmd.Flags().GetString("data-version"); value != "" {
+				toolArgs["dataVersion"] = value
+			}
+			return callAitableTool("query_records_stats", toolArgs)
+		},
+	}
+	DeclareLeafMetadata(recordStatsCmd, LeafSpec{
+		Safety: aitableSafetyRead(),
+		Contract: LeafContract{
+			Identity: contract.ToolIdentitySpec{
+				ProductID:      "aitable",
+				Name:           "query_records_stats",
+				CanonicalPath:  "aitable.query_records_stats",
+				CLIPath:        "aitable record stats",
+				PrimaryCLIPath: "aitable record stats",
+			},
+			Description: "对整表或过滤后的记录执行不分组字段聚合。",
+			Interface:   aitableMCPInterface("query_records_stats"),
+			Selection: contract.SelectionSpec{
+				AgentSummary: "对整表或过滤后的记录执行不分组字段聚合。",
+				UseWhen:      []string{"需要记录总数、SUM/AVG/MAX/MIN、中位数、去重数、完整率等标量统计时，优先服务端聚合"},
+				AvoidWhen:    []string{"需要按字段分组或使用 query_stats 高级聚合时用 record group-stats；需要行级明细时用 record query"},
+				Examples:     []string{`dws aitable record stats --base-id <BASE_ID> --table-id <TABLE_ID> --stats '[{"fieldId":"<FIELD_ID>","statsType":"COUNT"}]'`},
+			},
+			Parameters: []contract.ParamDecl{
+				{Name: "base-id", Property: "baseId", Required: boolPtr(true)},
+				{Name: "table-id", Property: "tableId", Required: boolPtr(true)},
+				{Name: "stats", Property: "stats", Required: boolPtr(true), InterfaceType: "array"},
+				{Name: "filters", Property: "filters", InterfaceType: "object"},
+				{Name: "search-field-ids", Property: "searchFieldIds", InterfaceType: "array"},
+				{Name: "data-version", Property: "dataVersion"},
+			},
+			Result: aitableRecordsStatsResultSpec(),
+		},
+	})
+
+	recordGroupStatsCmd := &cobra.Command{
+		Use:   "group-stats",
+		Short: "分组、去重及高级聚合统计",
+		Long: `对单张数据表执行分组或高级服务端聚合，底层调用 query_stats，最多返回 1000 个分组。
+适用于按一个或多个字段分组、条件唯一实体计数，以及 distinct、distinct_ratio 等高级统计。
+
+--stats 是 JSON 数组，每项包含 fieldId 和小写 statsType。基础类型为 sum、avg、count、max、min；
+部分后端也支持 median、distinct、distinct_ratio 等高级类型，不支持时服务端会返回明确错误。
+--group 是 JSON 数组编码后的字符串，不分组的 DISTINCT 标量统计可以省略。
+不要依赖服务端 limit 选择 Top N；应在不超过 1000 个分组时获取完整结果后再排序。`,
+		Example: `  dws aitable record group-stats --base-id BASE_ID --table-id TABLE_ID --group '[{"fieldId":"fldCategory","direction":"ASC","fieldConfig":null,"arraySplitMode":true}]' --stats '[{"fieldId":"fldAmount","statsType":"sum"}]'
+  dws aitable record group-stats --base-id BASE_ID --table-id TABLE_ID --stats '[{"fieldId":"fldStore","statsType":"distinct"}]'`,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			if err := validateRequiredFlags(cmd, "table-id", "stats"); err != nil {
+				return err
+			}
+			baseID, err := mustFlagOrFallback(cmd, "base-id", "base")
+			if err != nil {
+				return err
+			}
+			stats, err := parseAitableStatsItems(mustGetFlag(cmd, "stats"), false, false, 0)
+			if err != nil {
+				return err
+			}
+			toolArgs := map[string]any{
+				"baseId":  baseID,
+				"tableId": mustGetFlag(cmd, "table-id"),
+				"stats":   stats,
+			}
+			if raw, _ := cmd.Flags().GetString("filters"); raw != "" {
+				filters, err := parseAitableObjectFlag("filters", raw)
+				if err != nil {
+					return err
+				}
+				if err := validateAitableStatsFilters(filters, raw); err != nil {
+					return err
+				}
+				toolArgs["filters"] = normalizeFilters(filters)
+			}
+			if raw, _ := cmd.Flags().GetString("group"); raw != "" {
+				if err := validateAitableArrayDSL("group", raw); err != nil {
+					return err
+				}
+				toolArgs["group"] = raw
+			}
+			if raw, _ := cmd.Flags().GetString("sort"); raw != "" {
+				if err := validateAitableArrayDSL("sort", raw); err != nil {
+					return err
+				}
+				toolArgs["sortDsl"] = raw
+			}
+			if value, _ := cmd.Flags().GetInt("limit"); cmd.Flags().Changed("limit") {
+				if value < 1 || value > 1000 {
+					return aitableStatsValidationf("--limit 必须在 [1, 1000] 范围内，got %d", value)
+				}
+				toolArgs["limit"] = value
+			}
+			if value, _ := cmd.Flags().GetString("data-version"); value != "" {
+				toolArgs["dataVersion"] = value
+			}
+			return callAitableTool("query_stats", toolArgs)
+		},
+	}
+	DeclareLeafMetadata(recordGroupStatsCmd, LeafSpec{
+		Safety: aitableSafetyRead(),
+		Contract: LeafContract{
+			Identity: contract.ToolIdentitySpec{
+				ProductID:      "aitable",
+				Name:           "query_stats",
+				CanonicalPath:  "aitable.query_stats",
+				CLIPath:        "aitable record group-stats",
+				PrimaryCLIPath: "aitable record group-stats",
+			},
+			Description: "按字段分组，或执行去重等高级聚合统计。",
+			Interface:   aitableMCPInterface("query_stats"),
+			Selection: contract.SelectionSpec{
+				AgentSummary: "按字段分组，或执行去重等高级聚合统计。",
+				UseWhen:      []string{"需要各分类/实体的分组统计，或对满足条件的门店、客户、商品等执行 DISTINCT 唯一计数时"},
+				AvoidWhen:    []string{"普通不分组 COUNT/SUM/AVG/MAX/MIN 优先用 record stats；原始记录和 Top N 明细用 record query"},
+				Examples:     []string{`dws aitable record group-stats --base-id <BASE_ID> --table-id <TABLE_ID> --stats '[{"fieldId":"<FIELD_ID>","statsType":"distinct"}]'`},
+			},
+			Parameters: []contract.ParamDecl{
+				{Name: "base-id", Property: "baseId", Required: boolPtr(true)},
+				{Name: "table-id", Property: "tableId", Required: boolPtr(true)},
+				{Name: "stats", Property: "stats", Required: boolPtr(true), InterfaceType: "array"},
+				{Name: "filters", Property: "filters", InterfaceType: "object"},
+				{Name: "group", Property: "group"},
+				{Name: "sort", Property: "sortDsl"},
+				{Name: "data-version", Property: "dataVersion"},
+			},
+			Result: aitableGroupedStatsResultSpec(),
+		},
+	})
+
 	recordCreateCmd := &cobra.Command{
 		Use:   "create",
 		Short: "新增记录",
@@ -7230,6 +7533,23 @@ parentSectionId 为空串表示该节点在 Base 根目录下。
 	recordQueryCmd.Flags().Int("page-limit", 50, "自动翻页最大页数（仅 --all 时生效）。默认 50 页（约 5000 条）；设为 0 表示显式不限页数；超限时错误详情保留已取记录和续传 cursor")
 	recordQueryCmd.Flags().String("view-id", "", "视图 ID（record query 不支持按视图过滤，此参数会被忽略并给出提示）")
 	_ = recordQueryCmd.Flags().MarkHidden("view-id")
+	recordStatsCmd.Flags().String("base-id", "", "Base ID（通过 base get 确认目标）(必填)")
+	recordStatsCmd.Flags().String("table-id", "", "Table ID（通过 table get 获取）(必填)")
+	recordStatsCmd.Flags().String("stats", "", `统计项 JSON 数组（必填），例如 [{"fieldId":"fldAmount","statsType":"SUM"}]；statsType 必须大写，最多 20 项且 fieldId 不得重复`)
+	recordStatsCmd.Flags().String("filters", "", "结构化过滤条件 JSON 对象；数值比较值必须是 JSON 数字")
+	recordStatsCmd.Flags().String("sort", "", `参与统计记录的排序 DSL（JSON 数组字符串），例如 [{"fieldId":"fldDate","direction":"ASC"}]`)
+	recordStatsCmd.Flags().Int("limit", 0, "参与统计的最大记录数；省略表示统计全部匹配记录")
+	recordStatsCmd.Flags().String("keyword", "", "全文关键词，仅匹配的记录参与统计")
+	recordStatsCmd.Flags().String("search-field-ids", "", "关键词搜索字段 ID 列表，逗号分隔；仅 --keyword 非空时生效")
+	recordStatsCmd.Flags().String("data-version", "", "可选数据版本；通常省略以使用最新版本")
+	recordGroupStatsCmd.Flags().String("base-id", "", "Base ID（通过 base get 确认目标）(必填)")
+	recordGroupStatsCmd.Flags().String("table-id", "", "Table ID（通过 table get 获取）(必填)")
+	recordGroupStatsCmd.Flags().String("stats", "", `统计项 JSON 数组（必填），例如 [{"fieldId":"fldAmount","statsType":"sum"}]；statsType 必须小写`)
+	recordGroupStatsCmd.Flags().String("filters", "", "结构化过滤条件 JSON 对象；数值比较值必须是 JSON 数字")
+	recordGroupStatsCmd.Flags().String("group", "", `分组字段 DSL（JSON 数组字符串）；不分组的 distinct 统计可省略`)
+	recordGroupStatsCmd.Flags().String("sort", "", "统计结果排序 DSL（JSON 数组字符串），映射到 MCP sortDsl")
+	recordGroupStatsCmd.Flags().Int("limit", 0, "返回的分组结果数，范围 1-1000；省略表示不额外限制")
+	recordGroupStatsCmd.Flags().String("data-version", "", "可选数据版本；通常省略以使用最新版本")
 	recordCreateCmd.Flags().String("base-id", "", "Base ID，可通过 base list 或 base search 获取 (必填)")
 	recordCreateCmd.Flags().String("table-id", "", "Table ID，可通过 base get 获取 (必填)")
 	recordCreateCmd.Flags().String("records", "", "待创建的记录列表 JSON 数组，单次最多 100 条 (必填)")
@@ -7294,7 +7614,7 @@ parentSectionId 为空串表示该节点在 Base 根目录下。
 	recordPrimaryDocCreateCmd.Flags().String("record-id", "", "目标 Record ID (必填)")
 
 	recordCmd.AddCommand(
-		recordQueryCmd, recordCreateCmd,
+		recordQueryCmd, recordStatsCmd, recordGroupStatsCmd, recordCreateCmd,
 		recordUpdateCmd, recordDeleteCmd,
 		recordBatchUpdateCmd,
 		recordHistoryListCmd,

internal/helpers/aitable_command_edges_test.go

@@ -9,6 +9,7 @@ import (
 	"testing"
 	"time"
 
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition"
 )
 
@@ -18,6 +19,22 @@ type aitableCommandCoverageCaller struct {
 	response map[string]string
 }
 
+type aitableCommandContextKey struct{}
+
+type aitableCommandContextCaller struct {
+	value any
+}
+
+func (c *aitableCommandContextCaller) CallTool(ctx context.Context, _, _ string, _ map[string]any) (*edition.ToolResult, error) {
+	c.value = ctx.Value(aitableCommandContextKey{})
+	return nil, context.Canceled
+}
+
+func (*aitableCommandContextCaller) Format() string { return "json" }
+func (*aitableCommandContextCaller) DryRun() bool   { return false }
+func (*aitableCommandContextCaller) Fields() string { return "" }
+func (*aitableCommandContextCaller) JQ() string     { return "" }
+
 func (c *aitableCommandCoverageCaller) CallTool(_ context.Context, _, tool string, _ map[string]any) (*edition.ToolResult, error) {
 	if c.err != nil {
 		return nil, c.err
@@ -67,6 +84,11 @@ func TestCrossPlatformCoverageAitableRetryWrappersExhaustAndRecover(t *testing.T
 	oldDeps, oldSleep := deps, helperSleep
 	t.Cleanup(func() { deps, helperSleep = oldDeps, oldSleep })
 	helperSleep = func(time.Duration) {}
+	testseam.Swap(t, &helperAfter, func(time.Duration) <-chan time.Time {
+		ready := make(chan time.Time, 1)
+		ready <- time.Time{}
+		return ready
+	})
 
 	retryable := fmt.Errorf("timeout: retryable: true")
 	caller := &aitableTestCaller{errors: []error{retryable, retryable, retryable, retryable}}
@@ -86,6 +108,48 @@ func TestCrossPlatformCoverageAitableRetryWrappersExhaustAndRecover(t *testing.T
 	if err := callAitableHelperTool("retry", nil); err == nil {
 		t.Fatal("exhausted helper retries returned nil")
 	}
+
+	caller = &aitableTestCaller{}
+	installAitableDeps(t, caller)
+	if err := callAitableToolContext(nil, "nil-context", nil); err != nil {
+		t.Fatalf("nil context was not normalized: %v", err)
+	}
+
+	caller = &aitableTestCaller{errors: []error{retryable}}
+	installAitableDeps(t, caller)
+	ctx, cancel := context.WithCancel(context.Background())
+	backoffPending := make(chan time.Time)
+	testseam.Swap(t, &helperAfter, func(time.Duration) <-chan time.Time {
+		cancel()
+		return backoffPending
+	})
+	if err := callAitableToolContext(ctx, "cancel-during-backoff", nil); err != context.Canceled {
+		t.Fatalf("cancel during retry backoff = %v, want %v", err, context.Canceled)
+	}
+}
+
+func TestCrossPlatformCoverageAitableFieldListPreservesCommandContext(t *testing.T) {
+	old := deps
+	t.Cleanup(func() { deps = old })
+	caller := &aitableCommandContextCaller{}
+	InitDeps(caller)
+	deps.Out.w = io.Discard
+	deps.Out.errW = io.Discard
+
+	root := newAitableCommand()
+	installExampleGlobalFlags(root)
+	root.SilenceErrors = true
+	root.SilenceUsage = true
+	root.SetOut(io.Discard)
+	root.SetErr(io.Discard)
+	root.SetArgs([]string{"field", "list", "--base-id=b", "--table-id=t"})
+	ctx := context.WithValue(context.Background(), aitableCommandContextKey{}, "field-list-context")
+	if err := root.ExecuteContext(ctx); err == nil {
+		t.Fatal("field list context probe unexpectedly succeeded")
+	}
+	if caller.value != "field-list-context" {
+		t.Fatalf("field list caller context value = %#v", caller.value)
+	}
 }
 
 func TestCrossPlatformCoverageAitableCommandValidationEdges(t *testing.T) {

internal/helpers/aitable_schema.go

@@ -14,6 +14,8 @@
 package helpers
 
 import (
+	"encoding/json"
+
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract"
 )
 
@@ -72,3 +74,102 @@ func aitableCompositeInterface(reason string) *contract.InterfaceSpec {
 		Reason:       reason,
 	}
 }
+
+func aitableRecordsStatsResultSpec() *contract.ResultSpec {
+	return &contract.ResultSpec{
+		Outcomes: []contract.ResultOutcome{
+			contract.ResultOutcomeSuccess,
+			contract.ResultOutcomeFailure,
+		},
+		DataSchema: json.RawMessage(`{
+  "type":"object",
+  "description":"不分组的字段聚合结果",
+  "properties":{
+    "results":{
+      "type":"array",
+      "description":"按数据版本返回的聚合结果批次",
+      "items":{
+        "type":"object",
+        "properties":{
+          "dataVersion":{"description":"参与统计的数据版本"},
+          "deltaVersion":{"description":"聚合结果的增量版本"},
+          "results":{
+            "type":"array",
+            "description":"请求中各统计项的结果",
+            "items":{
+              "type":"object",
+              "properties":{
+                "fieldId":{"type":"string","description":"被统计的字段 ID"},
+                "statsType":{"type":"string","description":"实际执行的统计类型"},
+                "value":{"description":"统计值；具体 JSON 类型取决于统计类型和字段类型"}
+              },
+              "required":["fieldId","statsType","value"],
+              "additionalProperties":true
+            }
+          }
+        },
+        "required":["results"],
+        "additionalProperties":true
+      }
+    }
+  },
+  "required":["results"],
+  "additionalProperties":true
+}`),
+	}
+}
+
+func aitableGroupedStatsResultSpec() *contract.ResultSpec {
+	return &contract.ResultSpec{
+		Outcomes: []contract.ResultOutcome{
+			contract.ResultOutcomeSuccess,
+			contract.ResultOutcomeFailure,
+		},
+		DataSchema: json.RawMessage(`{
+  "type":"object",
+  "description":"分组或高级字段聚合结果",
+  "properties":{
+    "dataVersion":{"description":"参与统计的数据版本"},
+    "results":{
+      "type":"array",
+      "description":"每个分组一条结果；未分组时通常只有一条",
+      "items":{
+        "type":"object",
+        "properties":{
+          "groupKeys":{
+            "type":"array",
+            "description":"当前结果的分组键",
+            "items":{
+              "type":"object",
+              "properties":{
+                "fieldId":{"type":"string","description":"分组字段 ID"},
+                "value":{"description":"分组值；编码取决于字段类型"},
+                "recordCount":{"type":"integer","description":"该分组包含的记录数"}
+              },
+              "additionalProperties":true
+            }
+          },
+          "fieldStatsMap":{
+            "type":"object",
+            "description":"按字段 ID 索引的聚合值",
+            "additionalProperties":{
+              "type":"object",
+              "properties":{
+                "action":{"type":"string","description":"实际执行的统计动作"},
+                "value":{"description":"统计值；具体 JSON 类型取决于统计动作和字段类型"}
+              },
+              "required":["action","value"],
+              "additionalProperties":true
+            }
+          }
+        },
+        "required":["fieldStatsMap"],
+        "additionalProperties":true
+      }
+    }
+  },
+  "required":["results"],
+  "additionalProperties":true
+}`),
+	}
+}

internal/helpers/aitable_stats_test.go

@@ -0,0 +1,278 @@
+// Copyright 2026 Alibaba Group
+// SPDX-License-Identifier: Apache-2.0
+
+package helpers
+
+import (
+	"encoding/json"
+	"errors"
+	"reflect"
+	"strings"
+	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contractfinal"
+	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
+)
+
+func runAitableStatsCLI(t *testing.T, args ...string) (*aitableTestCaller, error) {
+	t.Helper()
+	caller := &aitableTestCaller{}
+	installAitableDeps(t, caller)
+	command := newAitableCommand()
+	command.SilenceErrors = true
+	command.SilenceUsage = true
+	command.SetArgs(args)
+	return caller, command.Execute()
+}
+
+func TestCrossPlatformCoverageAitableRecordsStatsForwardsValidatedContract(t *testing.T) {
+	caller, err := runAitableStatsCLI(t,
+		"record", "stats",
+		"--base-id", "base-stats",
+		"--table-id", "table-stats",
+		"--stats", `[{"fieldId":"fldCount","statsType":"COUNT"},{"fieldId":"fldAmount","statsType":"SUM"}]`,
+		"--filters", `{"operator":"and","operands":[{"operator":"gt","operands":["fldAmount",0]}]}`,
+		"--sort", `[{"fieldId":"fldAmount","direction":"DESC"}]`,
+		"--limit", "500",
+		"--keyword", "华东",
+		"--search-field-ids", "fldName,fldRegion",
+		"--data-version", "42",
+	)
+	if err != nil {
+		t.Fatalf("record stats returned error: %v", err)
+	}
+	if len(caller.calls) != 1 {
+		t.Fatalf("tool calls = %d, want 1", len(caller.calls))
+	}
+	call := caller.calls[0]
+	if call.server != "aitable" || call.tool != "query_records_stats" {
+		t.Fatalf("tool = %s/%s, want aitable/query_records_stats", call.server, call.tool)
+	}
+	wantStats := []map[string]any{
+		{"fieldId": "fldCount", "statsType": "COUNT"},
+		{"fieldId": "fldAmount", "statsType": "SUM"},
+	}
+	if !reflect.DeepEqual(call.args["stats"], wantStats) {
+		t.Fatalf("stats = %#v, want %#v", call.args["stats"], wantStats)
+	}
+	filters := call.args["filters"].(map[string]any)
+	condition := filters["operands"].([]any)[0].(map[string]any)
+	if got := condition["operands"].([]any)[1]; got != json.Number("0") {
+		t.Fatalf("numeric filter value = %#v (%T), want json.Number(0)", got, got)
+	}
+	if call.args["sort"] != `[{"fieldId":"fldAmount","direction":"DESC"}]` ||
+		call.args["limit"] != 500 || call.args["keyword"] != "华东" || call.args["dataVersion"] != "42" {
+		t.Fatalf("forwarded args = %#v", call.args)
+	}
+	if !reflect.DeepEqual(call.args["searchFieldIds"], []string{"fldName", "fldRegion"}) {
+		t.Fatalf("searchFieldIds = %#v", call.args["searchFieldIds"])
+	}
+}
+
+func TestCrossPlatformCoverageAitableGroupStatsForwardsStringDSL(t *testing.T) {
+	group := `[{"fieldId":"fldRegion","direction":"ASC","fieldConfig":null,"arraySplitMode":true}]`
+	sortDSL := `[{"fieldId":"fldAmount","direction":"DESC"}]`
+	caller, err := runAitableStatsCLI(t,
+		"record", "group-stats",
+		"--base-id", "base-stats",
+		"--table-id", "table-stats",
+		"--stats", `[{"fieldId":"fldStore","statsType":"distinct"},{"fieldId":"fldAmount","statsType":"avg"}]`,
+		"--filters", `{"operator":"OR","operands":[{"operator":"not_before","operands":["fldDate","2026-01-01"]}]}`,
+		"--group", group,
+		"--sort", sortDSL,
+		"--limit", "1000",
+		"--data-version", "43",
+	)
+	if err != nil {
+		t.Fatalf("record group-stats returned error: %v", err)
+	}
+	if len(caller.calls) != 1 {
+		t.Fatalf("tool calls = %d, want 1", len(caller.calls))
+	}
+	call := caller.calls[0]
+	if call.server != "aitable" || call.tool != "query_stats" {
+		t.Fatalf("tool = %s/%s, want aitable/query_stats", call.server, call.tool)
+	}
+	if call.args["group"] != group || call.args["sortDsl"] != sortDSL || call.args["limit"] != 1000 || call.args["dataVersion"] != "43" {
+		t.Fatalf("forwarded args = %#v", call.args)
+	}
+	stats := call.args["stats"].([]map[string]any)
+	if len(stats) != 2 || stats[0]["statsType"] != "distinct" || stats[1]["statsType"] != "avg" {
+		t.Fatalf("stats = %#v", stats)
+	}
+}
+
+func TestCrossPlatformCoverageAitableStatsRejectsInvalidInputsBeforeCallingMCP(t *testing.T) {
+	tests := []struct {
+		name    string
+		args    []string
+		wantErr string
+	}{
+		{
+			name:    "records stats require uppercase",
+			args:    []string{"record", "stats", "--base-id", "b", "--table-id", "t", "--stats", `[{"fieldId":"f","statsType":"count"}]`},
+			wantErr: "大写",
+		},
+		{
+			name:    "records stats require at least one item",
+			args:    []string{"record", "stats", "--base-id", "b", "--table-id", "t", "--stats", `[]`},
+			wantErr: "至少需要一个统计项",
+		},
+		{
+			name: "records stats enforce item cap",
+			args: []string{"record", "stats", "--base-id", "b", "--table-id", "t", "--stats", `[
+				{"fieldId":"f01","statsType":"COUNT"},{"fieldId":"f02","statsType":"COUNT"},
+				{"fieldId":"f03","statsType":"COUNT"},{"fieldId":"f04","statsType":"COUNT"},
+				{"fieldId":"f05","statsType":"COUNT"},{"fieldId":"f06","statsType":"COUNT"},
+				{"fieldId":"f07","statsType":"COUNT"},{"fieldId":"f08","statsType":"COUNT"},
+				{"fieldId":"f09","statsType":"COUNT"},{"fieldId":"f10","statsType":"COUNT"},
+				{"fieldId":"f11","statsType":"COUNT"},{"fieldId":"f12","statsType":"COUNT"},
+				{"fieldId":"f13","statsType":"COUNT"},{"fieldId":"f14","statsType":"COUNT"},
+				{"fieldId":"f15","statsType":"COUNT"},{"fieldId":"f16","statsType":"COUNT"},
+				{"fieldId":"f17","statsType":"COUNT"},{"fieldId":"f18","statsType":"COUNT"},
+				{"fieldId":"f19","statsType":"COUNT"},{"fieldId":"f20","statsType":"COUNT"},
+				{"fieldId":"f21","statsType":"COUNT"}
+			]`},
+			wantErr: "单次最多支持 20 个统计项",
+		},
+		{
+			name:    "records stats require item fields",
+			args:    []string{"record", "stats", "--base-id", "b", "--table-id", "t", "--stats", `[{"fieldId":" ","statsType":"COUNT"}]`},
+			wantErr: "均不能为空",
+		},
+		{
+			name:    "records stats reject unknown item fields",
+			args:    []string{"record", "stats", "--base-id", "b", "--table-id", "t", "--stats", `[{"fieldId":"f","statsType":"COUNT","unknownKey":123}]`},
+			wantErr: "不支持的字段",
+		},
+		{
+			name:    "records stats reject duplicate field",
+			args:    []string{"record", "stats", "--base-id", "b", "--table-id", "t", "--stats", `[{"fieldId":"f","statsType":"COUNT"},{"fieldId":"f","statsType":"SUM"}]`},
+			wantErr: "重复",
+		},
+		{
+			name:    "group stats require lowercase",
+			args:    []string{"record", "group-stats", "--base-id", "b", "--table-id", "t", "--stats", `[{"fieldId":"f","statsType":"COUNT"}]`},
+			wantErr: "小写",
+		},
+		{
+			name:    "group must be array DSL",
+			args:    []string{"record", "group-stats", "--base-id", "b", "--table-id", "t", "--stats", `[{"fieldId":"f","statsType":"count"}]`, "--group", `{}`},
+			wantErr: "JSON 数组",
+		},
+		{
+			name:    "group limit capped",
+			args:    []string{"record", "group-stats", "--base-id", "b", "--table-id", "t", "--stats", `[{"fieldId":"f","statsType":"count"}]`, "--limit", "1001"},
+			wantErr: "[1, 1000]",
+		},
+		{
+			name:    "filters require logical root",
+			args:    []string{"record", "stats", "--base-id", "b", "--table-id", "t", "--stats", `[{"fieldId":"f","statsType":"COUNT"}]`, "--filters", `{"operator":"eq","operands":[]}`},
+			wantErr: `root "operator" must be "and" or "or"`,
+		},
+		{
+			name:    "records filters reject malformed JSON",
+			args:    []string{"record", "stats", "--base-id", "b", "--table-id", "t", "--stats", `[{"fieldId":"f","statsType":"COUNT"}]`, "--filters", `{`},
+			wantErr: "必须是 JSON 对象",
+		},
+		{
+			name:    "records filters reject null",
+			args:    []string{"record", "stats", "--base-id", "b", "--table-id", "t", "--stats", `[{"fieldId":"f","statsType":"COUNT"}]`, "--filters", `null`},
+			wantErr: "不能是 null",
+		},
+		{
+			name:    "records filters reject a second JSON value",
+			args:    []string{"record", "stats", "--base-id", "b", "--table-id", "t", "--stats", `[{"fieldId":"f","statsType":"COUNT"}]`, "--filters", `{} {}`},
+			wantErr: "只能包含一个 JSON 对象",
+		},
+		{
+			name:    "records filters reject invalid trailing content",
+			args:    []string{"record", "stats", "--base-id", "b", "--table-id", "t", "--stats", `[{"fieldId":"f","statsType":"COUNT"}]`, "--filters", `{} trailing`},
+			wantErr: "无效的尾随内容",
+		},
+		{
+			name:    "records filters require operand array",
+			args:    []string{"record", "stats", "--base-id", "b", "--table-id", "t", "--stats", `[{"fieldId":"f","statsType":"COUNT"}]`, "--filters", `{"operator":"and","operands":{}}`},
+			wantErr: `"operands" must be an array`,
+		},
+		{
+			name:    "records filters reject silently unsupported operators",
+			args:    []string{"record", "stats", "--base-id", "b", "--table-id", "t", "--stats", `[{"fieldId":"f","statsType":"COUNT"}]`, "--filters", `{"operator":"and","operands":[{"operator":"date_between","operands":["fldDate",[1,2]]}]}`},
+			wantErr: `unsupported filter operator "date_between"`,
+		},
+		{
+			name:    "records sort requires an item",
+			args:    []string{"record", "stats", "--base-id", "b", "--table-id", "t", "--stats", `[{"fieldId":"f","statsType":"COUNT"}]`, "--sort", `[]`},
+			wantErr: "至少需要一个条目",
+		},
+		{
+			name:    "records sort items must be objects",
+			args:    []string{"record", "stats", "--base-id", "b", "--table-id", "t", "--stats", `[{"fieldId":"f","statsType":"COUNT"}]`, "--sort", `[1]`},
+			wantErr: "必须是 JSON 对象",
+		},
+		{
+			name:    "records limit must be positive",
+			args:    []string{"record", "stats", "--base-id", "b", "--table-id", "t", "--stats", `[{"fieldId":"f","statsType":"COUNT"}]`, "--limit", "0"},
+			wantErr: "必须大于 0",
+		},
+		{
+			name:    "group filters reject malformed JSON",
+			args:    []string{"record", "group-stats", "--base-id", "b", "--table-id", "t", "--stats", `[{"fieldId":"f","statsType":"count"}]`, "--filters", `{`},
+			wantErr: "必须是 JSON 对象",
+		},
+		{
+			name:    "group filters require logical root",
+			args:    []string{"record", "group-stats", "--base-id", "b", "--table-id", "t", "--stats", `[{"fieldId":"f","statsType":"count"}]`, "--filters", `{"operator":"eq","operands":[]}`},
+			wantErr: `root "operator" must be "and" or "or"`,
+		},
+		{
+			name:    "group filters reject silently unsupported operators",
+			args:    []string{"record", "group-stats", "--base-id", "b", "--table-id", "t", "--stats", `[{"fieldId":"f","statsType":"count"}]`, "--filters", `{"operator":"and","operands":[{"operator":"date_between","operands":["fldDate",[1,2]]}]}`},
+			wantErr: `unsupported filter operator "date_between"`,
+		},
+		{
+			name:    "group sort rejects invalid DSL",
+			args:    []string{"record", "group-stats", "--base-id", "b", "--table-id", "t", "--stats", `[{"fieldId":"f","statsType":"count"}]`, "--sort", `{}`},
+			wantErr: "JSON 数组",
+		},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			caller, err := runAitableStatsCLI(t, test.args...)
+			if err == nil || !strings.Contains(err.Error(), test.wantErr) {
+				t.Fatalf("error = %v, want containing %q", err, test.wantErr)
+			}
+			var structured *apperrors.Error
+			if !errors.As(err, &structured) || structured.Category != apperrors.CategoryValidation {
+				t.Fatalf("error = %#v, want structured validation error", err)
+			}
+			if len(caller.calls) != 0 {
+				t.Fatalf("tool calls = %d, want 0", len(caller.calls))
+			}
+		})
+	}
+}
+
+func TestCrossPlatformCoverageAitableStatsPublishInterfaceAndResultContracts(t *testing.T) {
+	root := newAitableCommand()
+	tests := []struct {
+		path string
+		rpc  string
+	}{
+		{path: "aitable record stats", rpc: "query_records_stats"},
+		{path: "aitable record group-stats", rpc: "query_stats"},
+	}
+	for _, test := range tests {
+		leaf := findCLIPath(root, test.path)
+		if leaf == nil {
+			t.Fatalf("missing leaf %q", test.path)
+		}
+		final, ok := contractfinal.RuntimeContractFinal(leaf)
+		if !ok || final.Interface == nil || final.Interface.Ref == nil || final.Interface.Ref.RPCName != test.rpc {
+			t.Fatalf("%s interface = %#v", test.path, final.Interface)
+		}
+		if final.Result == nil || len(final.Result.Outcomes) == 0 || len(final.Result.DataSchema) == 0 {
+			t.Fatalf("%s result = %#v", test.path, final.Result)
+		}
+	}
+}

internal/helpers/calendar.go

@@ -230,7 +230,7 @@ func newCalendarCommand() *cobra.Command {
 		Long: `管理钉钉日历：日程、参会人、会议室、闲忙、附件、日历本、访问权限。调用前必须先使用 --help 查看参数结构。
 
 命令结构:
-  dws calendar event       [list|get|create|update|delete|suggest|respond|instances]  日程管理
+  dws calendar event       [list|get|create|update|delete|suggest|respond|instances|share-info]  日程管理
   dws calendar attendee    [list|add|delete]                 参会人管理
   dws calendar room        [search|add|delete|list-groups]   会议室管理
   dws calendar busy        search                           闲忙查询 (可查人、查会议室)
@@ -2259,7 +2259,87 @@ func newCalendarCommand() *cobra.Command {
 	eventInstancesCmd.Flags().Int("count", 0, "")
 	_ = eventInstancesCmd.Flags().MarkHidden("count")
 
-	eventCmd.AddCommand(eventListCmd, eventGetCmd, eventCreateCmd, eventUpdateCmd, eventDeleteCmd, eventSuggestCmd, eventRespondCmd, eventInstancesCmd)
+	eventShareInfoCmd := &cobra.Command{
+		Use:     "share-info",
+		Aliases: []string{"share_info"},
+		Short:   "获取日程的分享信息",
+		Long:    `根据日程 ID 获取日程的分享信息，展示日程主题、组织人、地点、入会信息等，用于向他人分享日程。eventId 可通过 dws calendar event list 获取。`,
+		Example: `  dws calendar event share-info --id EVENT_ID
+  dws calendar event share-info --id EVENT_ID --language zh-CN
+  dws calendar event share-info --id EVENT_ID --calendar-id primary`,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			eventID, err := mustFlagOrFallback(cmd, "id", "event", "event-id", "eventId")
+			if err != nil {
+				return err
+			}
+			toolArgs := map[string]any{"eventId": eventID}
+			if v := flagOrFallback(cmd, "calendar-id", "calendarId", "calendar"); v != "" {
+				toolArgs["calendarId"] = v
+			}
+			if v := flagOrFallback(cmd, "language", "lang"); v != "" {
+				toolArgs["language"] = v
+			}
+			return callMCPTool("get_event_share_info", toolArgs)
+		},
+	}
+	DeclareLeafMetadata(eventShareInfoCmd, LeafSpec{
+		Safety: contract.SafetySpec{
+			Effect: "read", Risk: "low",
+			Confirmation: "not_required", Idempotency: "idempotent",
+		},
+		Contract: LeafContract{
+			Identity: contract.ToolIdentitySpec{
+				ProductID:      "calendar",
+				Name:           "get_event_share_info",
+				CanonicalPath:  "calendar.get_event_share_info",
+				CLIPath:        "calendar event share-info",
+				PrimaryCLIPath: "calendar event share-info",
+				Aliases:        []string{"calendar event share_info"},
+			},
+			Description: "获取日程的分享信息",
+			Interface: &contract.InterfaceSpec{
+				Mode:         "mcp",
+				Availability: "available",
+				Ref:          &contract.InterfaceRefSpec{ProductID: "calendar", RPCName: "get_event_share_info"},
+			},
+			Selection: contract.SelectionSpec{
+				AgentSummary: "获取日程的分享信息（主题、组织人、地点、入会信息等）",
+				UseWhen:      []string{"已知 eventId，需要获取日程分享信息或入会信息用于分享给他人时"},
+				AvoidWhen: []string{
+					"要查看日程详情改用 dws calendar event get",
+					"未知 eventId 时先 dws calendar event list",
+				},
+				Examples: []string{
+					"dws calendar event share-info --id <EVENT_ID>",
+					"dws calendar event share-info --id <EVENT_ID> --language zh-CN",
+				},
+			},
+			Parameters: []contract.ParamDecl{
+				{Name: "id", Property: "eventId", Required: boolPtr(true)},
+				{Name: "calendar-id", Property: "calendarId"},
+				{Name: "language", Property: "language"},
+			},
+		},
+	})
+
+	// EventShareInfo flags
+	eventShareInfoCmd.Flags().String("id", "", "日程 ID (必填)")
+	eventShareInfoCmd.Flags().String("event", "", "")
+	_ = eventShareInfoCmd.Flags().MarkHidden("event")
+	eventShareInfoCmd.Flags().String("event-id", "", "")
+	_ = eventShareInfoCmd.Flags().MarkHidden("event-id")
+	eventShareInfoCmd.Flags().String("eventId", "", "")
+	_ = eventShareInfoCmd.Flags().MarkHidden("eventId")
+	eventShareInfoCmd.Flags().String("calendar-id", "", "日历 ID (默认 primary 主日历)")
+	eventShareInfoCmd.Flags().String("calendarId", "", "")
+	_ = eventShareInfoCmd.Flags().MarkHidden("calendarId")
+	eventShareInfoCmd.Flags().String("calendar", "", "")
+	_ = eventShareInfoCmd.Flags().MarkHidden("calendar")
+	eventShareInfoCmd.Flags().String("language", "", "语言代码 (可选，如 zh-CN)")
+	eventShareInfoCmd.Flags().String("lang", "", "")
+	_ = eventShareInfoCmd.Flags().MarkHidden("lang")
+
+	eventCmd.AddCommand(eventListCmd, eventGetCmd, eventCreateCmd, eventUpdateCmd, eventDeleteCmd, eventSuggestCmd, eventRespondCmd, eventInstancesCmd, eventShareInfoCmd)
 
 	// participant
 	participantCmd.PersistentFlags().String("event", "", "日程 ID (必填)")

internal/helpers/chat.go

@@ -19,15 +19,29 @@ import (
 
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/cli"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract"
 	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut/chatmsg"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut/targetresolver"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition"
 	"github.com/spf13/cobra"
-
-	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract"
 )
 
+// promoteLegacyChatString copies an explicitly supplied legacy flag into the
+// new canonical flag. Cobra validates MarkFlagRequired after PreRunE, and the
+// overwrite also preserves the migration rule that a legacy value wins when
+// both spellings are present.
+func promoteLegacyChatString(cmd *cobra.Command, canonical, legacy string) error {
+	if !cmd.Flags().Changed(legacy) {
+		return nil
+	}
+	value, err := cmd.Flags().GetString(legacy)
+	if err != nil {
+		return err
+	}
+	return cmd.Flags().Set(canonical, value)
+}
+
 func callProjectedChatMessages(cmd *cobra.Command, toolName string, args map[string]any, search bool) error {
 	if deps.Caller.DryRun() {
 		return callMCPToolOnServer("chat", toolName, args)
@@ -3144,7 +3158,7 @@ func newChatCommand() *cobra.Command {
   --open-dingtalk-id   单聊接收人 openDingTalkId
 
 纯文本 / Markdown 消息（默认）：
-  无需指定 --msg-type，直接传消息内容即可。推荐使用 --text flag 传递内容（尤其当内容含换行、引号等特殊字符时），也支持位置参数。可选 --title 作为消息标题。
+  无需指定 --msg-type，直接传消息内容即可。推荐使用 --content flag 传递内容（尤其当内容含换行、引号等特殊字符时），也支持位置参数。可选 --title 作为消息标题。
   图文混排时，公网图片 URL 需要写成 Markdown 图片语法：![图片标题](https://example.com/image.png)，才会以内联图片展示。
   如果省略开头的 !，例如 [图片标题](https://example.com/image.png)，将按链接/URL 展示，不会渲染为图片。
 
@@ -3154,24 +3168,24 @@ func newChatCommand() *cobra.Command {
   获取 openMessageId 和 openConversationId，无需再按消息内容反查。
 
 本地图片 / 文件消息：
-  统一使用 --msg-type file --file-path <本地路径>。CLI 会完成上传并按 file 消息发送；
+  统一使用 --msg-type file --file <本地路径>。CLI 会完成上传并按 file 消息发送；
   .png/.jpg 也会显示为可下载的文件附件，不会生成 mediaId 或渲染成内联图片。
 
 旧版内联图片消息：
   仅当上游已经提供有效 mediaId 时，使用 --msg-type image --media-id。
   当前 CLI 不提供本地文件到 mediaId 的上传能力。`,
-		Example: `  dws chat message send --conversation-id <openconversation_id> "hello"
-  dws chat message send --user <userId> "请查收"
-  dws chat message send --open-dingtalk-id <openDingTalkId> "请查收"
-  dws chat message send --conversation-id <openconversation_id> --title "周报提醒" "请大家本周五前提交周报"
+		Example: `  dws chat message send --conversation-id <openconversation_id> --content "hello"
+  dws chat message send --user <userId> --content "请查收"
+  dws chat message send --open-dingtalk-id <openDingTalkId> --content "请查收"
+  dws chat message send --conversation-id <openconversation_id> --title "周报提醒" --content "请大家本周五前提交周报"
   # 图文混排 Markdown：公网图片 URL 需要写成 ![图片标题](URL) 才会以内联图片展示
-  dws chat message send --conversation-id <openconversation_id> --text $'这是图文说明\n\n![这个是展示图片标题](https://down.dingtalk.com/media/lQLPM5jiBEiBNjswMLAKd_CTzm8eowpEWPT_7-cA_48_48.png)'
+  dws chat message send --conversation-id <openconversation_id> --content $'这是图文说明\n\n![这个是展示图片标题](https://down.dingtalk.com/media/lQLPM5jiBEiBNjswMLAKd_CTzm8eowpEWPT_7-cA_48_48.png)'
   # 发送本地图片或文件（图片会作为可下载的 file 附件发送）
-  dws chat message send --conversation-id <openconversation_id> --msg-type file --file-path ./screenshot.png
-  dws chat message send --conversation-id <openconversation_id> --msg-type file --file-path ./report.pdf
+  dws chat message send --conversation-id <openconversation_id> --msg-type file --file ./screenshot.png
+  dws chat message send --conversation-id <openconversation_id> --msg-type file --file ./report.pdf
   # 发送本地音频/视频（audio/video 是 file 的语义别名）
-  dws chat message send --conversation-id <openconversation_id> --msg-type audio --file-path ./recording.mp3
-  dws chat message send --conversation-id <openconversation_id> --msg-type video --file-path ./demo.mp4
+  dws chat message send --conversation-id <openconversation_id> --msg-type audio --file ./recording.mp3
+  dws chat message send --conversation-id <openconversation_id> --msg-type video --file ./demo.mp4
   # 旧版内联图片：仅当上游已经持有有效 mediaId 时使用
   dws chat message send --conversation-id <openconversation_id> --msg-type image --media-id <mediaId>
 # 查询群 ID: dws chat search --query "群名"
@@ -3250,7 +3264,7 @@ func newChatCommand() *cobra.Command {
 					contentJSON = fmt.Sprintf(`{"mediaId":"%s"}`, mediaId)
 				case "file", "audio", "video":
 					serviceMsgType = "file"
-					filePath, _ := cmd.Flags().GetString("file-path")
+					filePath := flagOrFallback(cmd, "file-path", "file")
 					dentryId, _ := cmd.Flags().GetInt64("dentry-id")
 					spaceId, _ := cmd.Flags().GetInt64("space-id")
 					if (dentryId == 0) != (spaceId == 0) {
@@ -3281,7 +3295,7 @@ func newChatCommand() *cobra.Command {
 							}
 							contentJSON, _ = buildConversationFileContent(dentryId, spaceId, meta)
 						} else if dentryId == 0 || spaceId == 0 {
-							return fmt.Errorf("--file-path must be a readable local file, or pass legacy --dentry-id and --space-id: %w", err)
+							return fmt.Errorf("--file must be a readable local file, or pass legacy --dentry-id and --space-id: %w", err)
 						}
 					}
 					if contentJSON == "" {
@@ -3289,7 +3303,7 @@ func newChatCommand() *cobra.Command {
 						fileType, _ := cmd.Flags().GetString("file-type")
 						fileSize, _ := cmd.Flags().GetInt64("file-size")
 						if dentryId == 0 || spaceId == 0 || fileName == "" {
-							return fmt.Errorf("readable local --file-path is required for msgType=file; legacy flags --dentry-id, --space-id, --file-name are still supported")
+							return fmt.Errorf("readable local --file is required for msgType=file; legacy flags --dentry-id, --space-id, --file-name are still supported")
 						}
 						contentJSON = fmt.Sprintf(`{"dentryId":%d,"spaceId":%d,"fileName":"%s","fileType":"%s","filePath":"%s","fileSize":%d}`,
 							dentryId, spaceId, fileName, fileType, filePath, fileSize)
@@ -3335,7 +3349,7 @@ func newChatCommand() *cobra.Command {
 				text = args[0]
 			}
 			if text == "" {
-				return fmt.Errorf("message content required (use --text or positional arg, or --media-id for image)")
+				return fmt.Errorf("message content required (use --content or positional arg, or --media-id for image)")
 			}
 			title, _ := cmd.Flags().GetString("title")
 			if title == "" {
@@ -3395,7 +3409,7 @@ func newChatCommand() *cobra.Command {
 				AgentSummary: "以当前用户身份发送群聊或单聊消息",
 				UseWhen:      []string{"用户明确要以个人身份发送文本或媒体消息时；响应返回 openTaskId 后用 chat message query-send-status 确认投递并取得后续操作所需的消息 ID"},
 				AvoidWhen:    []string{"机器人身份或 Webhook 发送应使用对应命令"},
-				Examples:     []string{"dws chat message send --group <openConversationId> \"项目已更新\""},
+				Examples:     []string{"dws chat message send --group <openConversationId> --content \"项目已更新\""},
 			},
 			Parameters: []contract.ParamDecl{
 				{Name: "ai-tag", Property: "clawType", InterfaceType: "string"},
@@ -3413,10 +3427,11 @@ func newChatCommand() *cobra.Command {
 	chatMessageSendByBotCmd := &cobra.Command{
 		Use:   "send-by-bot",
 		Short: "机器人发送消息（--conversation-id 群聊 / --users 单聊）",
-		Long: `群聊：传 --conversation-id 指定群；单聊：传 --users 或 --open-dingtalk-ids 指定用户列表，与 --conversation-id 只能选其一，不能同时指定。省略 --msg-type 时发送 Markdown；图片使用 --msg-type image --image-url；本地文件使用 --msg-type file --file-path，CLI 完成上传后发送。
+		Long: `群聊：传 --conversation-id 指定群；单聊：传 --users 或 --open-dingtalk-ids 指定用户列表，与 --conversation-id 只能选其一，不能同时指定。省略 --msg-type 时发送 Markdown；图片使用 --msg-type image --image-url；本地文件使用 --msg-type file --file-path，CLI 完成上传后发送。机器人引用回复仅支持群聊 Markdown，同时传 --reply（原消息 openMessageId）和 --ref-sender（原消息发送者 openDingTalkId）；回复可省略 --title，CLI 会从正文生成标题。
 
 ⚠️ 重要：该接口会真实发送消息到目标会话，不可用于测试或试探性调用。调用前必须确认消息内容和接收对象无误。`,
 		Example: `  dws chat message send-by-bot --robot-code <robot-code> --conversation-id <openconversation_id> --title "日报" --text "## 今日完成..."
+  dws chat message send-by-bot --robot-code <robot-code> --conversation-id <openconversation_id> --reply <openMessageId> --ref-sender <openDingTalkId> --text "收到"
   dws chat message send-by-bot --robot-code <robot-code> --conversation-id <openconversation_id> --msg-type image --image-url "https://example.com/image.png"
   dws chat message send-by-bot --robot-code <robot-code> --conversation-id <openconversation_id> --msg-type file --file-path ./report.pdf
   dws chat message send-by-bot --robot-code <robot-code> --users userId1,userId2 --title "提醒" --text "请提交周报"
@@ -3433,10 +3448,17 @@ func newChatCommand() *cobra.Command {
 			text := mustGetFlag(cmd, "text")
 			imageURL := strings.TrimSpace(mustGetFlag(cmd, "image-url"))
 			filePath := mustGetFlag(cmd, "file-path")
+			referenceOpenMessageID := strings.TrimSpace(mustGetFlag(cmd, "reply"))
+			refSender := strings.TrimSpace(mustGetFlag(cmd, "ref-sender"))
+			replyChanged := cmd.Flags().Changed("reply")
+			refSenderChanged := cmd.Flags().Changed("ref-sender")
 
 			if err := validateRequiredFlags(cmd, "robot-code"); err != nil {
 				return err
 			}
+			if replyChanged != refSenderChanged || (replyChanged && (referenceOpenMessageID == "" || refSender == "")) {
+				return fmt.Errorf("--reply and --ref-sender must be specified together")
+			}
 			if msgType == "" {
 				if imageURL != "" {
 					return fmt.Errorf("--msg-type image is required when using --image-url")
@@ -3448,8 +3470,17 @@ func newChatCommand() *cobra.Command {
 			}
 			switch msgType {
 			case "markdown":
-				if err := validateRequiredFlags(cmd, "title", "text"); err != nil {
-					return err
+				if referenceOpenMessageID != "" {
+					if err := validateRequiredFlags(cmd, "text"); err != nil {
+						return err
+					}
+					if title == "" {
+						title = sanitizeTitleFromText(text)
+					}
+				} else {
+					if err := validateRequiredFlags(cmd, "title", "text"); err != nil {
+						return err
+					}
 				}
 			case "image":
 				if imageURL == "" {
@@ -3475,6 +3506,22 @@ func newChatCommand() *cobra.Command {
 				return fmt.Errorf("--conversation-id or --users/--open-dingtalk-ids is required")
 			}
 
+			if referenceOpenMessageID != "" {
+				if chatID == "" {
+					return fmt.Errorf("--reply and --ref-sender are only supported with --conversation-id")
+				}
+				if msgType != "markdown" {
+					return fmt.Errorf("--reply and --ref-sender only support Markdown group messages")
+				}
+				if !isOpenDingTalkID(refSender) {
+					resolved, err := resolveOpenDingTalkID(cmd.Context(), refSender)
+					if err != nil {
+						return err
+					}
+					refSender = resolved
+				}
+			}
+
 			userIDs := splitCommaList(usersStr)
 			openDingTalkIDs := splitCommaList(openDingtalkIdsStr)
 			fileURL := ""
@@ -3540,6 +3587,10 @@ func newChatCommand() *cobra.Command {
 					toolArgs["msgKey"] = "sampleMarkdownDX"
 				}
 				toolArgs["openConversationId"] = chatID
+				if referenceOpenMessageID != "" {
+					toolArgs["referenceOpenMessageId"] = referenceOpenMessageID
+					toolArgs["srcMsgSendOpenDingTalkId"] = refSender
+				}
 				if len(atUserIds) > 0 {
 					toolArgs["atUserIds"] = atUserIds
 				}
@@ -3586,17 +3637,20 @@ func newChatCommand() *cobra.Command {
 				CLIPath:        "chat message send-by-bot",
 				PrimaryCLIPath: "chat message send-by-bot",
 			},
-			Description: "以应用机器人身份发送 Markdown、图片或文件群消息或批量单聊",
+			Description: "以应用机器人身份发送 Markdown、图片或文件群消息、群聊引用回复或批量单聊",
 			Interface: &contract.InterfaceSpec{
 				Mode:         "composite",
 				Availability: "available",
 				Reason:       "命令包含多个 RPC、条件分派或本地 HTTP/文件步骤，不能绑定为单一 interface_ref",
 			},
 			Selection: contract.SelectionSpec{
-				AgentSummary: "以应用机器人身份发送 Markdown、图片或文件群消息或批量单聊",
-				UseWhen:      []string{"已有 robotCode 且需要机器人身份投递 Markdown、图片或文件时"},
+				AgentSummary: "以应用机器人身份发送 Markdown、图片或文件群消息、群聊引用回复或批量单聊",
+				UseWhen:      []string{"已有 robotCode 且需要机器人身份投递 Markdown、图片或文件时", "需要机器人在群聊中引用回复一条已有消息时"},
 				AvoidWhen:    []string{"个人身份发送或自定义 Webhook 告警不要使用"},
-				Examples:     []string{"dws chat message send-by-bot --robot-code <robotCode> --group <openConversationId> --title \"日报\" --text \"今日进展\""},
+				Examples: []string{
+					"dws chat message send-by-bot --robot-code <robotCode> --group <openConversationId> --title \"日报\" --text \"今日进展\"",
+					"dws chat message send-by-bot --robot-code <robotCode> --group <openConversationId> --reply <openMessageId> --ref-sender <openDingTalkId> --text \"收到\"",
+				},
 			},
 			// Keep title/text required_when out of Schema: the runtime switch above
 			// enforces Markdown inputs, while adding it breaks merge-base compatibility.
@@ -3605,6 +3659,8 @@ func newChatCommand() *cobra.Command {
 				{Name: "msg-type", RequiredWhen: "image-url or file-path is provided", Enum: []string{"markdown", "image", "file"}},
 				{Name: "image-url", RequiredWhen: "msg-type is image"},
 				{Name: "file-path", RequiredWhen: "msg-type is file"},
+				{Name: "reply", Property: "referenceOpenMessageId", RequiredWhen: "ref-sender is provided", InterfaceType: "string"},
+				{Name: "ref-sender", Property: "srcMsgSendOpenDingTalkId", RequiredWhen: "reply is provided", InterfaceType: "string"},
 			},
 		},
 	})
@@ -3674,19 +3730,25 @@ func newChatCommand() *cobra.Command {
 	chatMessageSendByWebhookCmd := &cobra.Command{
 		Use:   "send-by-webhook",
 		Short: "自定义机器人 Webhook 发送群消息",
-		Long: `通过自定义机器人 Webhook 发送群消息。@ 人时需在 --text 中包含 @userId 或 @手机号，否则 @ 不生效。
+		Long: `通过自定义机器人 Webhook 发送群消息。@ 人时需在 --content 中包含 @userId 或 @手机号，否则 @ 不生效。
 
 ⚠️ 重要：该接口会真实发送消息到目标群聊，不可用于测试或试探性调用。调用前必须确认消息内容无误。`,
-		Example: `  dws chat message send-by-webhook --token <webhook-token> --title "告警" --text "CPU 超 90%" --at-all
-  dws chat message send-by-webhook --token <webhook-token> --title "test" --text "hi @118785" --at-users 118785`,
+		Example: `  dws chat message send-by-webhook --token <webhook-token> --title "告警" --content "CPU 超 90%" --at-all
+  dws chat message send-by-webhook --token <webhook-token> --title "test" --content "hi @118785" --at-users 118785`,
+		PreRunE: func(cmd *cobra.Command, args []string) error {
+			return promoteLegacyChatString(cmd, "content", "text")
+		},
 		RunE: func(cmd *cobra.Command, args []string) error {
-			if err := validateRequiredFlags(cmd, "token", "title", "text"); err != nil {
+			if err := promoteLegacyChatString(cmd, "content", "text"); err != nil {
+				return err
+			}
+			if err := validateRequiredFlags(cmd, "token", "title", "content"); err != nil {
 				return err
 			}
 			toolArgs := map[string]any{
 				"robotToken": mustGetFlag(cmd, "token"),
 				"title":      mustGetFlag(cmd, "title"),
-				"text":       mustGetFlag(cmd, "text"),
+				"text":       mustGetFlag(cmd, "content"),
 			}
 			if v, _ := cmd.Flags().GetBool("at-all"); v {
 				toolArgs["isAtAll"] = true
@@ -3761,11 +3823,12 @@ func newChatCommand() *cobra.Command {
 					"使用企业机器人 robot-code 发消息时用 chat message send-by-bot",
 					"以个人身份发消息时用 chat message send",
 				},
-				Examples: []string{"dws chat message send-by-webhook --token <webhook-token> --title \"告警\" --text \"CPU 超 90%\" --at-all"},
+				Examples: []string{"dws chat message send-by-webhook --token <webhook-token> --title \"告警\" --content \"CPU 超 90%\" --at-all"},
 			},
 			Parameters: []contract.ParamDecl{
 				{Name: "at-all", Property: "isAtAll"},
 				{Name: "at-users", Property: "atUserIds"},
+				{Name: "content", Property: "text"},
 				{Name: "token", Property: "robotToken"},
 			},
 		},
@@ -4314,7 +4377,7 @@ chat message edit 或 chat message recall 的 --message-id 和 --conversation-id
 		Example: `  dws chat message recall --conversation-id <openConversationId> --message-id <openMessageId>
 
   # 发送后撤回：send -> query-send-status -> recall
-  dws chat message send --conversation-id <openConversationId> --text "待撤回的内容"
+  dws chat message send --conversation-id <openConversationId> --content "待撤回的内容"
   dws chat message query-send-status --open-task-id <上一步返回的openTaskId>
   dws chat message recall --conversation-id <上一步返回的openConversationId> --message-id <上一步返回的openMessageId>`,
 		RunE: func(cmd *cobra.Command, args []string) error {
@@ -4375,7 +4438,7 @@ chat message edit 或 chat message recall 的 --message-id 和 --conversation-id
 		Example: `  dws chat message edit --conversation-id <openConversationId> --message-id <openMessageId> --text "更新后的内容"
 
   # 发送后编辑：send -> query-send-status -> edit
-  dws chat message send --conversation-id <openConversationId> --text "原始内容"
+  dws chat message send --conversation-id <openConversationId> --content "原始内容"
   dws chat message query-send-status --open-task-id <上一步返回的openTaskId>
   dws chat message edit --conversation-id <上一步返回的openConversationId> --message-id <上一步返回的openMessageId> --text "更新后的内容"
 
@@ -4711,21 +4774,19 @@ chat message edit 或 chat message recall 的 --message-id 和 --conversation-id
 	chatMessageSendCmd.Flags().String("user", "", "单聊接收人 userId（单聊时与 --open-dingtalk-id 二选一）")
 	chatMessageSendCmd.Flags().String("open-dingtalk-id", "", "单聊接收人 openDingTalkId（单聊时与 --user 二选一）")
 	chatMessageSendCmd.Flags().String("title", "", "消息标题，显示在消息列表（可选，未指定时使用消息内容）")
-	// 别名注册: --text/--content/--body/--message/--markdown → 位置参数
-	chatMessageSendCmd.Flags().String("text", "", "消息内容（推荐方式，也可用位置参数传递。内容含换行/特殊字符时必须使用此 flag）")
-	chatMessageSendCmd.Flags().String("content", "", "--text 的别名")
-	chatMessageSendCmd.Flags().String("body", "", "--text 的别名")
-	chatMessageSendCmd.Flags().String("message", "", "--text 的别名")
-	chatMessageSendCmd.Flags().String("markdown", "", "--text 的别名")
-	// --text 不再隐藏，作为首选传参方式展示在 help 中
-	_ = chatMessageSendCmd.Flags().MarkHidden("content")
-	_ = chatMessageSendCmd.Flags().MarkHidden("body")
-	_ = chatMessageSendCmd.Flags().MarkHidden("message")
-	_ = chatMessageSendCmd.Flags().MarkHidden("markdown")
+	corecmd.RegisterFlags(chatMessageSendCmd, []corecmd.FlagSpec{{
+		Name:    "content",
+		Usage:   "消息内容（推荐方式，也可用位置参数传递。内容含换行/特殊字符时必须使用此 flag）",
+		Aliases: []string{"text"},
+	}})
+	for _, alias := range []string{"body", "message", "markdown"} {
+		chatMessageSendCmd.Flags().String(alias, "", "--content 的兼容别名")
+		_ = chatMessageSendCmd.Flags().MarkHidden(alias)
+	}
 	chatMessageSendCmd.Flags().Bool("at-all", false, "@所有人（仅群聊时生效，可选）,设置时，消息内容中一定要包含对应的占位符<@all>")
 	chatMessageSendCmd.Flags().String("at-open-dingtalk-ids", "", "@指定成员的 openDingTalkId 列表，逗号分隔（仅群聊时生效，可选）,设置--at-open-dingtalk-ids openDingTalkId1,openDingTalkId2时，消息内容中一定要包含对应格式的占位符<@openDingTalkId1> <@openDingTalkId2>")
 	chatMessageSendCmd.Flags().String("media-id", "", "上游已提供的图片 mediaId（仅旧版 msgType=image；CLI 不提供本地上传到 mediaId）")
-	chatMessageSendCmd.Flags().String("msg-type", "", "富媒体消息类型: image/file/audio/video/location/profile（本地图片/文件推荐 file --file-path；image 仅接受已有 mediaId）")
+	chatMessageSendCmd.Flags().String("msg-type", "", "富媒体消息类型: image/file/audio/video/location/profile（本地图片/文件推荐 file --file；image 仅接受已有 mediaId）")
 	chatMessageSendCmd.Flags().String("latitude", "", "位置消息纬度（msgType=location 时必填）")
 	chatMessageSendCmd.Flags().String("longitude", "", "位置消息经度（msgType=location 时必填）")
 	chatMessageSendCmd.Flags().String("location-name", "", "位置消息地址名称（msgType=location 时必填）")
@@ -4735,7 +4796,11 @@ chat message edit 或 chat message recall 的 --message-id 和 --conversation-id
 	chatMessageSendCmd.Flags().Int64("space-id", 0, "空间 ID（与 --dentry-id 成对传入时跳过自动上传）")
 	chatMessageSendCmd.Flags().String("file-name", "", "文件名")
 	chatMessageSendCmd.Flags().String("file-type", "", "文件类型/扩展名")
-	chatMessageSendCmd.Flags().String("file-path", "", "本地文件路径（msgType=file/audio/video 时直接上传并按 file 消息发送）")
+	corecmd.RegisterFlags(chatMessageSendCmd, []corecmd.FlagSpec{{
+		Name:    "file",
+		Usage:   "本地文件路径（msgType=file/audio/video 时直接上传并按 file 消息发送）",
+		Aliases: []string{"file-path"},
+	}})
 	chatMessageSendCmd.Flags().Int64("file-size", 0, "文件大小，单位字节")
 	_ = chatMessageSendCmd.Flags().MarkHidden("dentry-id")
 	_ = chatMessageSendCmd.Flags().MarkHidden("space-id")
@@ -4756,19 +4821,19 @@ chat message edit 或 chat message recall 的 --message-id 和 --conversation-id
 	cli.AnnotateRuntimePositionals(chatMessageSendCmd, contract.RuntimeSchemaPositional{
 		Name:        "content",
 		Type:        "string",
-		Description: "消息内容（也可使用 --text；富媒体消息可省略）",
+		Description: "消息内容（也可使用 --content；富媒体消息可省略）",
 		Required:    false,
 		Index:       0,
 	})
 	cli.AnnotateRuntimeFlagEnum(chatMessageSendCmd, "msg-type", "image", "file", "audio", "video")
-	cli.AnnotateRuntimeFlagFormat(chatMessageSendCmd, "file-path", "file-path")
+	cli.AnnotateRuntimeFlagFormat(chatMessageSendCmd, "file", "file-path")
 
 	chatMessageSendByBotCmd.Flags().String("robot-code", "", "机器人 Code (必填)")
 	_ = chatMessageSendByBotCmd.MarkFlagRequired("robot-code")
 	chatMessageSendByBotCmd.Flags().String("conversation-id", "", "群聊 openConversationId（群聊时必填）")
 	chatMessageSendByBotCmd.Flags().String("users", "", "用户 userId 列表，逗号分隔，最多20个（单聊时必填）")
 	chatMessageSendByBotCmd.Flags().String("msg-type", "", "消息类型: markdown/image/file（省略时为 markdown；图片使用 image --image-url；本地文件使用 file --file-path）")
-	chatMessageSendByBotCmd.Flags().String("title", "", "Markdown 消息标题（发送 Markdown 时必填）")
+	chatMessageSendByBotCmd.Flags().String("title", "", "Markdown 消息标题（发送普通 Markdown 时必填；引用回复省略时从正文生成）")
 	chatMessageSendByBotCmd.Flags().String("text", "", "Markdown 消息内容（发送 Markdown 时必填；稳定换行用空行，转义形式写 \\n\\n，不要只写 \\n）")
 	chatMessageSendByBotCmd.Flags().String("image-url", "", "公网图片 URL（msgType=image 时必填）")
 	chatMessageSendByBotCmd.Flags().String("file-path", "", "本地文件路径（msgType=file 时直接上传并按 file 消息发送）")
@@ -4776,9 +4841,13 @@ chat message edit 或 chat message recall 的 --message-id 和 --conversation-id
 	chatMessageSendByBotCmd.Flags().String("open-dingtalk-ids", "", "用户 openDingtalkId 列表，逗号分隔（单聊时可替代 --users，可选）")
 	chatMessageSendByBotCmd.Flags().String("at-open-dingtalk-ids", "", "@指定成员的 openDingtalkId 列表，逗号分隔（仅群聊时生效，可选）")
 	chatMessageSendByBotCmd.Flags().Bool("at-all", false, "@所有人（可选），服务端接收字符串 true/false")
+	chatMessageSendByBotCmd.Flags().String("reply", "", "被引用消息的 openMessageId（仅群聊 Markdown；必须与 --ref-sender 同时使用）")
+	chatMessageSendByBotCmd.Flags().String("ref-sender", "", "被引用消息发送者的 openDingTalkId（仅群聊 Markdown；必须与 --reply 同时使用）")
+	chatMessageSendByBotCmd.MarkFlagsRequiredTogether("reply", "ref-sender")
 	cli.AnnotateRuntimeConstraints(chatMessageSendByBotCmd, cli.RuntimeSchemaConstraints{
 		MutuallyExclusive: [][]string{{"group", "users"}},
 		RequireOneOf:      [][]string{{"group", "users"}},
+		RequireTogether:   [][]string{{"reply", "ref-sender"}},
 	})
 	cli.AnnotateRuntimeFlagFormat(chatMessageSendByBotCmd, "file-path", "file-path")
 
@@ -4792,8 +4861,12 @@ chat message edit 或 chat message recall 的 --message-id 和 --conversation-id
 	_ = chatMessageSendByWebhookCmd.MarkFlagRequired("token")
 	chatMessageSendByWebhookCmd.Flags().String("title", "", "消息标题 (必填)")
 	_ = chatMessageSendByWebhookCmd.MarkFlagRequired("title")
-	chatMessageSendByWebhookCmd.Flags().String("text", "", "消息内容 (必填)")
-	_ = chatMessageSendByWebhookCmd.MarkFlagRequired("text")
+	corecmd.RegisterFlags(chatMessageSendByWebhookCmd, []corecmd.FlagSpec{{
+		Name:    "content",
+		Usage:   "消息内容 (必填)",
+		Aliases: []string{"text"},
+	}})
+	_ = chatMessageSendByWebhookCmd.MarkFlagRequired("content")
 	chatMessageSendByWebhookCmd.Flags().Bool("at-all", false, "@ 所有人")
 	chatMessageSendByWebhookCmd.Flags().String("at-mobiles", "", "@ 指定手机号，逗号分隔")
 	chatMessageSendByWebhookCmd.Flags().String("at-users", "", "@ 指定用户，逗号分隔")
@@ -5003,7 +5076,7 @@ chat message edit 或 chat message recall 的 --message-id 和 --conversation-id
 		Use:   "conversation-info",
 		Short: "获取会话基础信息",
 		Long: `获取指定会话的基础信息。
-发送本地文件消息请优先使用 dws chat message send --msg-type file --file-path <本地文件>，CLI 不再要求调用方获取或传递 spaceId。`,
+发送本地文件消息请优先使用 dws chat message send --msg-type file --file <本地文件>，CLI 不再要求调用方获取或传递 spaceId。`,
 		Example: `  dws chat conversation-info --conversation-id <openConversationId> --format json
   dws chat conversation-info --user <userId> --format json
   dws chat conversation-info --open-dingtalk-id <openDingTalkId> --format json`,
@@ -5118,11 +5191,11 @@ chat message edit 或 chat message recall 的 --message-id 和 --conversation-id
 		Hidden: true,
 		Long: `chat file upload 已下线，不再调用 chat/upload_conversation_file_by_url。
 
-发送本地文件消息请改用 chat message send --msg-type file --file-path；该路径仍然可用，CLI 内部会完成本地文件上传和消息发送。`,
-		Example: `  dws chat message send --conversation-id <openConversationId> --msg-type file --file-path ./report.pdf --format json
-  dws chat message send --open-dingtalk-id <openDingTalkId> --msg-type file --file-path ./report.pdf --format json`,
+发送本地文件消息请改用 chat message send --msg-type file --file；该路径仍然可用，CLI 内部会完成本地文件上传和消息发送。`,
+		Example: `  dws chat message send --conversation-id <openConversationId> --msg-type file --file ./report.pdf --format json
+  dws chat message send --open-dingtalk-id <openDingTalkId> --msg-type file --file ./report.pdf --format json`,
 		RunE: func(cmd *cobra.Command, args []string) error {
-			return fmt.Errorf("chat file upload 已下线；chat/upload_conversation_file_by_url 当前不可用。发送本地文件请改用: dws chat message send --msg-type file --file-path <本地路径>")
+			return fmt.Errorf("chat file upload 已下线；chat/upload_conversation_file_by_url 当前不可用。发送本地文件请改用: dws chat message send --msg-type file --file <本地路径>")
 		},
 	}
 	chatFileUploadCmd.Flags().String("conversation-id", "", "群聊 openConversationId（群聊时使用）")
@@ -6888,10 +6961,22 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成
   - 群聊：dws chat search --query "群名"
   - 单聊：dws chat conversation-info --open-dingtalk-id <openDingTalkId>
           （人员信息可通过 dws contact user search --keyword "姓名" --format json 获取）`,
-		Example: `  dws chat message reply --conversation-id <openConversationId> --ref-msg-id <openMessageId> --ref-sender <openDingTalkId> --text "收到，马上处理"
-  dws chat message reply --conversation-id <openConversationId> --ref-msg-id <openMessageId> --ref-sender <openDingTalkId> --text "请看一下" --at-open-dingtalk-ids <mentionedOpenDingTalkId>`,
+		Example: `  dws chat message reply --group <openConversationId> --ref-msg-id <openMessageId> --ref-sender <openDingTalkId> --content "收到，马上处理"
+  dws chat message reply --group <openConversationId> --ref-msg-id <openMessageId> --ref-sender <openDingTalkId> --content "请看一下" --at-open-dingtalk-ids <mentionedOpenDingTalkId>`,
+		PreRunE: func(cmd *cobra.Command, args []string) error {
+			if err := promoteLegacyChatString(cmd, "group", "conversation-id"); err != nil {
+				return err
+			}
+			return promoteLegacyChatString(cmd, "content", "text")
+		},
 		RunE: func(cmd *cobra.Command, args []string) error {
-			if err := validateRequiredFlags(cmd, "conversation-id", "ref-msg-id", "ref-sender", "text"); err != nil {
+			if err := promoteLegacyChatString(cmd, "group", "conversation-id"); err != nil {
+				return err
+			}
+			if err := promoteLegacyChatString(cmd, "content", "text"); err != nil {
+				return err
+			}
+			if err := validateRequiredFlags(cmd, "group", "ref-msg-id", "ref-sender", "content"); err != nil {
 				return err
 			}
 			refSender := mustGetFlag(cmd, "ref-sender")
@@ -6908,7 +6993,7 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成
 				clawType = edition.ClawType()
 			}
 			toolArgs := map[string]any{
-				"openConversationId": mustGetFlag(cmd, "conversation-id"),
+				"openConversationId": mustGetFlag(cmd, "group"),
 				"msgType":            "reply",
 				"clawType":           clawType,
 			}
@@ -6916,7 +7001,7 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成
 			atOpenIDs := mustGetFlag(cmd, "at-open-dingtalk-ids")
 			replyText := applyCurrentUserGroupMentions(
 				toolArgs,
-				mustGetFlag(cmd, "text"),
+				mustGetFlag(cmd, "content"),
 				atOpenIDs,
 				atAll,
 			)
@@ -6958,24 +7043,32 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成
 				AgentSummary: "引用指定消息发送个人回复",
 				UseWhen:      []string{"用户要针对某条已有消息进行引用回复时"},
 				AvoidWhen:    []string{"无需引用上下文的普通消息使用 chat message send"},
-				Examples:     []string{"dws chat message reply --conversation-id <openConversationId> --ref-msg-id <openMessageId> --ref-sender <openDingTalkId> --text \"收到\""},
+				Examples:     []string{"dws chat message reply --group <openConversationId> --ref-msg-id <openMessageId> --ref-sender <openDingTalkId> --content \"收到\""},
 			},
 			Parameters: []contract.ParamDecl{
 				{Name: "ai-tag", Property: "clawType", InterfaceType: "string"},
 				{Name: "at-all", Property: "atAll", Required: boolPtr(false), InterfaceType: "boolean"},
 				{Name: "at-open-dingtalk-ids", Property: "atOpenDingTalkIds", Required: boolPtr(false), InterfaceType: "array"},
-				{Name: "conversation-id", Property: "openConversationId"},
+				{Name: "group", Property: "openConversationId"},
 			},
 		},
 	})
-	chatMessageReplyCmd.Flags().String("conversation-id", "", "会话 openConversationId (必填，支持单聊/群聊)")
-	_ = chatMessageReplyCmd.MarkFlagRequired("conversation-id")
+	corecmd.RegisterFlags(chatMessageReplyCmd, []corecmd.FlagSpec{{
+		Name:    "group",
+		Usage:   "会话 openConversationId (必填，支持单聊/群聊)",
+		Aliases: []string{"conversation-id"},
+	}})
+	_ = chatMessageReplyCmd.MarkFlagRequired("group")
 	chatMessageReplyCmd.Flags().String("ref-msg-id", "", "被引用的消息 openMessageId (必填)")
 	_ = chatMessageReplyCmd.MarkFlagRequired("ref-msg-id")
 	chatMessageReplyCmd.Flags().String("ref-sender", "", "被引用消息的发送者 openDingTalkId (必填)")
 	_ = chatMessageReplyCmd.MarkFlagRequired("ref-sender")
-	chatMessageReplyCmd.Flags().String("text", "", "回复内容 (必填)")
-	_ = chatMessageReplyCmd.MarkFlagRequired("text")
+	corecmd.RegisterFlags(chatMessageReplyCmd, []corecmd.FlagSpec{{
+		Name:    "content",
+		Usage:   "回复内容 (必填)",
+		Aliases: []string{"text"},
+	}})
+	_ = chatMessageReplyCmd.MarkFlagRequired("content")
 	chatMessageReplyCmd.Flags().String("uuid", "", "幂等键（可选）")
 	chatMessageReplyCmd.Flags().Bool("ai-tag", true, "消息是否带 AI 发送角标（默认 true）")
 	chatMessageReplyCmd.Flags().Bool("at-all", false, "@所有人（仅群聊时生效；正文缺少 <@all> 时自动补齐）")

internal/helpers/chat_coverage_more_test.go

@@ -446,6 +446,100 @@ func TestCrossPlatformCoverageChatBotRichMediaCoverage(t *testing.T) {
 		if caller.tool != "batch_send_robot_msg_to_users" || caller.args["msgType"] != "sampleMarkdownDX" {
 			t.Fatalf("direct markdown call = %s %#v", caller.tool, caller.args)
 		}
+		if _, exists := caller.args["referenceOpenMessageId"]; exists {
+			t.Fatalf("ordinary direct message unexpectedly contains reply fields: %#v", caller.args)
+		}
+	})
+
+	t.Run("group Markdown reference reply", func(t *testing.T) {
+		const senderOpenDingTalkID = "DAAAAAAAAAAAiE"
+		caller := &scriptedToolCaller{}
+		if err := runChatCoverageCommand(t, caller,
+			"message", "send-by-bot", "--robot-code", "robot", "--conversation-id", "group",
+			"--reply", "message-id", "--ref-sender", senderOpenDingTalkID,
+			"--text", "received",
+		); err != nil {
+			t.Fatal(err)
+		}
+		if caller.tool != "send_robot_group_message" ||
+			caller.args["referenceOpenMessageId"] != "message-id" ||
+			caller.args["srcMsgSendOpenDingTalkId"] != senderOpenDingTalkID ||
+			caller.args["title"] != "received" {
+			t.Fatalf("group reference reply call = %s %#v", caller.tool, caller.args)
+		}
+	})
+
+	t.Run("group reference reply resolves sender user ID", func(t *testing.T) {
+		caller := &scriptedToolCaller{steps: []scriptedToolStep{
+			{text: `{"result":[{"userId":"sender-user","openDingTalkId":"D-sender"}]}`},
+			{text: `{}`},
+		}}
+		if err := runChatCoverageCommand(t, caller,
+			"message", "send-by-bot", "--robot-code", "robot", "--conversation-id", "group",
+			"--reply", "message-id", "--ref-sender", "sender-user",
+			"--title", "reply", "--text", "received",
+		); err != nil {
+			t.Fatal(err)
+		}
+		if caller.tool != "send_robot_group_message" || caller.args["srcMsgSendOpenDingTalkId"] != "D-sender" {
+			t.Fatalf("resolved group reference reply = %s %#v", caller.tool, caller.args)
+		}
+	})
+
+	t.Run("direct RunE enforces paired reply flags", func(t *testing.T) {
+		err := runChatCoverageDirect(t, []string{"message", "send-by-bot"}, map[string]string{
+			"robot-code":      "robot",
+			"conversation-id": "group",
+			"reply":           "message-id",
+			"title":           "reply",
+			"text":            "received",
+		})
+		if err == nil || !strings.Contains(err.Error(), "must be specified together") {
+			t.Fatalf("direct RunE paired reply flags error = %v", err)
+		}
+	})
+
+	for _, tc := range []struct {
+		name string
+		args []string
+		want string
+	}{
+		{name: "reply requires sender", args: []string{"--reply", "message-id"}, want: "ref-sender"},
+		{name: "sender requires reply", args: []string{"--ref-sender", "D-sender"}, want: "reply"},
+		{name: "paired reply flags reject empty values", args: []string{"--reply=", "--ref-sender="}, want: "specified together"},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			args := []string{
+				"message", "send-by-bot", "--robot-code", "robot", "--conversation-id", "group",
+				"--title", "reply", "--text", "received",
+			}
+			err := runChatCoverageCommand(t, &scriptedToolCaller{}, append(args, tc.args...)...)
+			if err == nil || !strings.Contains(err.Error(), tc.want) {
+				t.Fatalf("paired reply flags error = %v, want %q", err, tc.want)
+			}
+		})
+	}
+
+	t.Run("reference reply is group only", func(t *testing.T) {
+		err := runChatCoverageCommand(t, &scriptedToolCaller{},
+			"message", "send-by-bot", "--robot-code", "robot", "--users", "user",
+			"--reply", "message-id", "--ref-sender", "D-sender",
+			"--title", "reply", "--text", "received",
+		)
+		if err == nil || !strings.Contains(err.Error(), "only supported with --conversation-id") {
+			t.Fatalf("direct reference reply error = %v", err)
+		}
+	})
+
+	t.Run("reference reply rejects rich media", func(t *testing.T) {
+		err := runChatCoverageCommand(t, &scriptedToolCaller{},
+			"message", "send-by-bot", "--robot-code", "robot", "--conversation-id", "group",
+			"--reply", "message-id", "--ref-sender", "D-sender",
+			"--msg-type", "image", "--image-url", "https://example.test/image.png",
+		)
+		if err == nil || !strings.Contains(err.Error(), "only support Markdown") {
+			t.Fatalf("rich-media reference reply error = %v", err)
+		}
 	})
 
 	t.Run("direct image", func(t *testing.T) {

internal/helpers/chat_media_upload.go

@@ -18,7 +18,7 @@ import (
 	"github.com/spf13/cobra"
 )
 
-const chatMediaUploadReplacement = "dws chat message send --msg-type file --file-path <本地路径>"
+const chatMediaUploadReplacement = "dws chat message send --msg-type file --file <本地路径>"
 
 func newChatMediaGroup() *cobra.Command {
 	media := &cobra.Command{
@@ -43,11 +43,11 @@ func newChatMediaUploadCommand() *cobra.Command {
 		Deprecated: "请改用 " + chatMediaUploadReplacement,
 		Long: `此命令仅为 1.x 命令行兼容保留，不再读取应用凭证或调用旧版媒体上传接口。
 
-发送本地图片或文件时，请使用 chat message send --msg-type file --file-path。
+发送本地图片或文件时，请使用 chat message send --msg-type file --file。
 该路径会把图片作为可下载的 file 消息发送，不会生成 mediaId，也不会渲染成内联 image 消息。
 如果上游已经提供 mediaId，仍可使用 chat message send --msg-type image --media-id。`,
-		Example: "  dws chat message send --group <openConversationId> --msg-type file --file-path ./screenshot.png\n" +
-			"  dws chat message send --open-dingtalk-id <openDingTalkId> --msg-type file --file-path ./report.pdf",
+		Example: "  dws chat message send --conversation-id <openConversationId> --msg-type file --file ./screenshot.png\n" +
+			"  dws chat message send --open-dingtalk-id <openDingTalkId> --msg-type file --file ./report.pdf",
 		Args:              cobra.NoArgs,
 		DisableAutoGenTag: true,
 		RunE: func(*cobra.Command, []string) error {
@@ -56,7 +56,7 @@ func newChatMediaUploadCommand() *cobra.Command {
 	}
 	// Keep the historical flags so existing argv remains parseable while the
 	// 1.x compatibility command returns an actionable migration error.
-	cmd.Flags().String("file", "", "旧版兼容参数；本地文件请改用 chat message send --file-path")
+	cmd.Flags().String("file", "", "旧版兼容参数；本地文件请改用 chat message send --file")
 	cmd.Flags().String("type", "image", "旧版兼容参数；不再执行媒体上传")
 	return cmd
 }

internal/helpers/chat_media_upload_coverage_more_test.go

@@ -28,7 +28,7 @@ func TestCrossPlatformCoverageChatMediaUploadIsDeprecatedCompatibilityStub(t *te
 	if err == nil {
 		t.Fatal("deprecated media upload returned nil error")
 	}
-	for _, want := range []string{"已下线", "chat message send", "--msg-type file", "--file-path", "--media-id"} {
+	for _, want := range []string{"已下线", "chat message send", "--msg-type file", "--file", "--media-id"} {
 		if !strings.Contains(err.Error(), want) {
 			t.Fatalf("media upload migration error missing %q: %v", want, err)
 		}

internal/helpers/comment_base.go

@@ -0,0 +1,328 @@
+// 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.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package helpers
+
+import (
+	"encoding/json"
+	"fmt"
+	"strings"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract"
+	"github.com/spf13/cobra"
+)
+
+const commentServer = "doc-comment"
+
+var commentBatchResultSchema = json.RawMessage(`{
+  "type":"object",
+  "description":"按请求顺序返回的评论详情",
+  "properties":{
+    "commentList":{
+      "type":"array",
+      "description":"与请求 comments 顺序一致的评论详情列表",
+      "items":{
+        "type":"object",
+        "description":"单条评论查询结果；不存在时 found=false",
+        "properties":{
+          "topicId":{"type":"string","description":"评论主题 ID"},
+          "commentKey":{"type":"string","description":"评论唯一标识"},
+          "found":{"type":"boolean","description":"该 topicId/commentKey 是否存在"},
+          "content":{"type":["string","null"],"description":"纯文本评论内容"},
+          "quote":{"type":["string","null"],"description":"划词评论引用内容"},
+          "creatorId":{"type":["string","null"],"description":"创建者用户 ID"},
+          "createTime":{"type":["integer","null"],"description":"创建时间，毫秒时间戳"},
+          "updateTime":{"type":["integer","null"],"description":"更新时间，毫秒时间戳"},
+          "isSolved":{"type":["boolean","null"],"description":"是否已解决"},
+          "isEmoji":{"type":["boolean","null"],"description":"是否为表情回复"},
+          "replyCommentKey":{"type":["string","null"],"description":"被回复评论的标识"}
+        },
+        "required":["topicId","commentKey","found"],
+        "additionalProperties":true
+      }
+    }
+  },
+  "required":["commentList"],
+  "additionalProperties":true
+}`)
+
+var commentStatusResultSchema = json.RawMessage(`{
+  "type":"object",
+  "description":"评论解决状态更新结果",
+  "properties":{
+    "commentKey":{"type":"string","description":"评论唯一标识"},
+    "resolved":{"type":"boolean","description":"更新后的解决状态"},
+    "message":{"type":"string","description":"操作结果消息"}
+  },
+  "required":["commentKey","resolved"],
+  "additionalProperties":true
+}`)
+
+var commentReactionResultSchema = json.RawMessage(`{
+  "type":"object",
+  "description":"表情回复创建结果",
+  "properties":{
+    "commentKey":{"type":"string","description":"新建表情回复的评论标识"},
+    "message":{"type":"string","description":"操作结果消息"}
+  },
+  "required":["commentKey"],
+  "additionalProperties":true
+}`)
+
+// newCommentBaseCommands returns the base comment commands shared by Doc and Sheet.
+// Both resource domains call the same comment MCP tools; only CLI identity and
+// guidance differ.
+func newCommentBaseCommands(surface string) []*cobra.Command {
+	batchCmd := newCommentBatchQueryCommand(surface)
+	resolveCmd := newCommentStatusCommand(surface, true)
+	restoreCmd := newCommentStatusCommand(surface, false)
+	reactCmd := newCommentReactionCommand(surface)
+	commands := []*cobra.Command{batchCmd, resolveCmd, restoreCmd, reactCmd}
+	for _, cmd := range commands {
+		addCommentNodeAliases(cmd)
+	}
+	return commands
+}
+
+func newCommentBatchQueryCommand(surface string) *cobra.Command {
+	resourceName := commentResourceName(surface)
+	cmd := &cobra.Command{
+		Use:     "batch-query",
+		Aliases: []string{"batch-query-comments", "batch"},
+		Short:   "按 topicId + commentKey 批量查询评论详情",
+		Long: `批量查询同一文档或表格中的评论详情，单次最多 100 条。
+
+--comment-ref 可重复传入，格式为 topicId:commentKey。topicId 和 commentKey
+均可从 comment list 的返回结果中获得。结果严格保持输入顺序；不存在的评论
+会返回 found=false 的占位项。`,
+		Example: fmt.Sprintf("  dws %s comment batch-query --node <NODE_ID> --comment-ref global:<COMMENT_KEY> --comment-ref <TOPIC_ID>:<COMMENT_KEY> --format json", surface),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			nodeID, err := mustFlagOrFallback(cmd, "node", "url", "id", "node-id", "doc-id", "file-id")
+			if err != nil {
+				return err
+			}
+			rawRefs, _ := cmd.Flags().GetStringSlice("comment-ref")
+			refs, err := parseCommentRefs(rawRefs)
+			if err != nil {
+				return err
+			}
+			return callMCPToolOnServer(commentServer, "batch_query_comments", map[string]any{
+				"nodeId":   nodeID,
+				"comments": refs,
+			})
+		},
+	}
+	DeclareLeafMetadata(cmd, LeafSpec{
+		Safety: contract.SafetySpec{
+			Effect: "read", Risk: "low", Confirmation: "not_required", Idempotency: "idempotent",
+		},
+		Contract: LeafContract{
+			Identity:    commentIdentity(surface, "batch_query_comments", "batch-query"),
+			Description: "按 topicId + commentKey 批量查询评论详情，保持输入顺序并显式标记缺失项",
+			Result: &contract.ResultSpec{
+				Outcomes:   []contract.ResultOutcome{contract.ResultOutcomeSuccess, contract.ResultOutcomeFailure},
+				DataSchema: commentBatchResultSchema,
+			},
+			Interface: commentInterface("batch_query_comments"),
+			Selection: contract.SelectionSpec{
+				AgentSummary: "已知多组 topicId/commentKey 时，一次获取完整评论详情",
+				UseWhen:      []string{fmt.Sprintf("需要回查%s comment list 结果中的多条评论详情，或批量核对评论是否仍存在时", resourceName)},
+				AvoidWhen:    []string{fmt.Sprintf("尚未取得%s评论的 topicId/commentKey 时先使用 comment list", resourceName)},
+				Examples:     []string{fmt.Sprintf("dws %s comment batch-query --node <NODE_ID> --comment-ref <TOPIC_ID>:<COMMENT_KEY> --format json", surface)},
+			},
+			Parameters: []contract.ParamDecl{
+				{Name: "node", Property: "nodeId"},
+				{Name: "comment-ref", Property: "comments", InterfaceType: "array"},
+			},
+		},
+	})
+	cmd.Flags().String("node", "", "文档或表格 ID / URL (必填)")
+	cmd.Flags().StringSlice("comment-ref", nil, "评论引用 topicId:commentKey，可重复；最多 100 条 (必填)")
+	return cmd
+}
+
+func newCommentStatusCommand(surface string, resolve bool) *cobra.Command {
+	resourceName := commentResourceName(surface)
+	use := "restore"
+	rpc := "restore_comment"
+	short := "将已解决评论恢复为未解决"
+	resolved := false
+	if resolve {
+		use = "resolve"
+		rpc = "resolve_comment"
+		short = "将评论标记为已解决"
+		resolved = true
+	}
+	cmd := &cobra.Command{
+		Use:     use,
+		Aliases: []string{use + "-comment"},
+		Short:   short,
+		Example: fmt.Sprintf("  dws %s comment %s --node <NODE_ID> --comment-key <COMMENT_KEY> --format json", surface, use),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			nodeID, err := mustFlagOrFallback(cmd, "node", "url", "id", "node-id", "doc-id", "file-id")
+			if err != nil {
+				return err
+			}
+			if err := validateRequiredFlags(cmd, "comment-key"); err != nil {
+				return err
+			}
+			return callMCPToolOnServer(commentServer, rpc, map[string]any{
+				"nodeId":     nodeID,
+				"commentKey": mustGetFlag(cmd, "comment-key"),
+			})
+		},
+	}
+	DeclareLeafMetadata(cmd, LeafSpec{
+		Safety: contract.SafetySpec{
+			Effect: "write", Risk: "low", Confirmation: "not_required", Idempotency: "idempotent",
+		},
+		Contract: LeafContract{
+			Identity:    commentIdentity(surface, rpc, use),
+			Description: short,
+			Result: &contract.ResultSpec{
+				Outcomes:   []contract.ResultOutcome{contract.ResultOutcomeSuccess, contract.ResultOutcomeFailure},
+				DataSchema: commentStatusResultSchema,
+			},
+			Interface: commentInterface(rpc),
+			Selection: contract.SelectionSpec{
+				AgentSummary: short,
+				UseWhen:      []string{fmt.Sprintf("用户明确要求把%s中的某条评论标记为%s时", resourceName, map[bool]string{true: "已解决", false: "未解决"}[resolved])},
+				AvoidWhen:    []string{fmt.Sprintf("永久删除%s评论使用 comment delete；修改文字使用 comment update", resourceName)},
+				Examples:     []string{fmt.Sprintf("dws %s comment %s --node <NODE_ID> --comment-key <COMMENT_KEY> --format json", surface, use)},
+			},
+			Parameters: []contract.ParamDecl{
+				{Name: "node", Property: "nodeId"},
+				{Name: "comment-key", Property: "commentKey"},
+			},
+		},
+	})
+	cmd.Flags().String("node", "", "文档或表格 ID / URL (必填)")
+	cmd.Flags().String("comment-key", "", "目标评论的 commentKey (必填)")
+	return cmd
+}
+
+func newCommentReactionCommand(surface string) *cobra.Command {
+	resourceName := commentResourceName(surface)
+	cmd := &cobra.Command{
+		Use:   "react-reply",
+		Short: "创建一条表情回复",
+		Long: `创建表情回复的便捷命令。底层复用 reply_comment，并固定传入 emoji=true。
+
+与 comment reply --emoji 一致，--reaction 必须填写钉钉表情名称，不要直接传
+Unicode Emoji。例如用户要求 😄 时传“憨笑”，要求 👏 时传“鼓掌”。
+
+当前轻量版仅支持创建，不包含删除或聚合能力。`,
+		Example: fmt.Sprintf("  dws %s comment react-reply --node <NODE_ID> --comment-key <COMMENT_KEY> --reaction \"憨笑\" --format json", surface),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			nodeID, err := mustFlagOrFallback(cmd, "node", "url", "id", "node-id", "doc-id", "file-id")
+			if err != nil {
+				return err
+			}
+			if err := validateRequiredFlags(cmd, "comment-key", "reaction"); err != nil {
+				return err
+			}
+			return callMCPToolOnServer(commentServer, "reply_comment", map[string]any{
+				"nodeId":          nodeID,
+				"replyCommentKey": mustGetFlag(cmd, "comment-key"),
+				"content":         mustGetFlag(cmd, "reaction"),
+				"emoji":           true,
+			})
+		},
+	}
+	DeclareLeafMetadata(cmd, LeafSpec{
+		Safety: contract.SafetySpec{
+			Effect: "write", Risk: "low", Confirmation: "not_required", Idempotency: "non_idempotent",
+		},
+		Contract: LeafContract{
+			Identity:    commentIdentity(surface, "react_reply", "react-reply"),
+			Description: "为指定评论创建表情回复（轻量版）",
+			Result: &contract.ResultSpec{
+				Outcomes:   []contract.ResultOutcome{contract.ResultOutcomeSuccess, contract.ResultOutcomeFailure},
+				DataSchema: commentReactionResultSchema,
+			},
+			Interface: commentInterface("reply_comment"),
+			Selection: contract.SelectionSpec{
+				AgentSummary: "使用钉钉表情名称为指定评论创建表情回复",
+				UseWhen:      []string{fmt.Sprintf("用户要用表情回应%s中的某条评论时；先将 Unicode Emoji 转为钉钉表情名称，例如 😄 转为憨笑、👏 转为鼓掌", resourceName)},
+				AvoidWhen:    []string{fmt.Sprintf("%s评论的普通文字回复使用 comment reply；当前轻量版不支持删除 reaction", resourceName)},
+				Examples:     []string{fmt.Sprintf("dws %s comment react-reply --node <NODE_ID> --comment-key <COMMENT_KEY> --reaction \"憨笑\" --format json", surface)},
+			},
+			Parameters: []contract.ParamDecl{
+				{Name: "node", Property: "nodeId"},
+				{Name: "comment-key", Property: "replyCommentKey"},
+				{Name: "reaction", Property: "content"},
+			},
+		},
+	})
+	cmd.Flags().String("node", "", "文档或表格 ID / URL (必填)")
+	cmd.Flags().String("comment-key", "", "被回应评论的 commentKey (必填)")
+	cmd.Flags().String("reaction", "", "钉钉表情名称，不是 Unicode Emoji；例如 😄=憨笑、👏=鼓掌 (必填)")
+	return cmd
+}
+
+func parseCommentRefs(rawRefs []string) ([]map[string]any, error) {
+	if len(rawRefs) == 0 {
+		return nil, fmt.Errorf("missing required flag(s): --comment-ref")
+	}
+	if len(rawRefs) > 100 {
+		return nil, fmt.Errorf("--comment-ref 最多可传 100 条，当前为 %d 条", len(rawRefs))
+	}
+	refs := make([]map[string]any, 0, len(rawRefs))
+	for index, raw := range rawRefs {
+		parts := strings.SplitN(strings.TrimSpace(raw), ":", 2)
+		if len(parts) != 2 || strings.TrimSpace(parts[0]) == "" || strings.TrimSpace(parts[1]) == "" {
+			return nil, fmt.Errorf("invalid --comment-ref[%d] %q: expected topicId:commentKey", index, raw)
+		}
+		refs = append(refs, map[string]any{
+			"topicId":    strings.TrimSpace(parts[0]),
+			"commentKey": strings.TrimSpace(parts[1]),
+		})
+	}
+	return refs, nil
+}
+
+func addCommentNodeAliases(cmd *cobra.Command) {
+	cmd.Flags().String("url", "", "")
+	cmd.Flags().String("id", "", "")
+	cmd.Flags().String("node-id", "", "")
+	cmd.Flags().String("doc-id", "", "")
+	cmd.Flags().String("file-id", "", "")
+	for _, name := range []string{"url", "id", "node-id", "doc-id", "file-id"} {
+		_ = cmd.Flags().MarkHidden(name)
+	}
+}
+
+func commentIdentity(surface, name, cliLeaf string) contract.ToolIdentitySpec {
+	return contract.ToolIdentitySpec{
+		ProductID:      surface,
+		Name:           name,
+		CanonicalPath:  surface + "." + name,
+		CLIPath:        surface + " comment " + cliLeaf,
+		PrimaryCLIPath: surface + " comment " + cliLeaf,
+	}
+}
+
+func commentResourceName(surface string) string {
+	if surface == "sheet" {
+		return "表格"
+	}
+	return "文档"
+}
+
+func commentInterface(rpc string) *contract.InterfaceSpec {
+	return &contract.InterfaceSpec{
+		Mode:         "mcp",
+		Availability: "available",
+		Ref:          &contract.InterfaceRefSpec{ProductID: commentServer, RPCName: rpc},
+	}
+}

internal/helpers/comment_base_test.go

@@ -0,0 +1,174 @@
+// 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.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package helpers
+
+import (
+	"io"
+	"os"
+	"reflect"
+	"strings"
+	"testing"
+
+	"github.com/spf13/cobra"
+)
+
+func executeCommentBaseCommand(t *testing.T, caller *docCommentMutationCaller, surface string, args ...string) error {
+	t.Helper()
+	previousDeps := deps
+	previousArgs := os.Args
+	t.Cleanup(func() {
+		deps = previousDeps
+		os.Args = previousArgs
+	})
+
+	InitDeps(caller)
+	deps.Out.w = io.Discard
+	os.Args = []string{"dws", surface}
+	var cmd *cobra.Command
+	if surface == "sheet" {
+		cmd = newSheetCommand()
+	} else {
+		cmd = newDocCommand()
+	}
+	cmd.PersistentFlags().Bool("yes", false, "skip confirmation")
+	cmd.SilenceErrors = true
+	cmd.SilenceUsage = true
+	cmd.SetArgs(args)
+	return cmd.Execute()
+}
+
+func TestCrossPlatformCoverageCommentBaseCommandsRegisteredForDocAndSheet(t *testing.T) {
+	for _, surface := range []struct {
+		name string
+		cmd  *cobra.Command
+	}{
+		{name: "doc", cmd: newDocCommand()},
+		{name: "sheet", cmd: newSheetCommand()},
+	} {
+		for _, leaf := range []string{"batch-query", "resolve", "restore", "react-reply"} {
+			cmd, remaining, err := surface.cmd.Find([]string{"comment", leaf})
+			if err != nil || len(remaining) != 0 {
+				t.Fatalf("dws %s comment %s not registered: cmd=%v remaining=%v err=%v",
+					surface.name, leaf, cmd, remaining, err)
+			}
+		}
+	}
+}
+
+func TestCrossPlatformCoverageDocCommentBatchQueryMapsStructuredRefs(t *testing.T) {
+	caller := &docCommentMutationCaller{}
+	err := executeCommentBaseCommand(t, caller, "doc",
+		"comment", "batch-query", "--node", "doc-1",
+		"--comment-ref", "global:comment-1", "--comment-ref", "topic-2:comment-2")
+	if err != nil {
+		t.Fatal(err)
+	}
+	want := docCommentMutationCall{
+		productID: commentServer,
+		toolName:  "batch_query_comments",
+		args: map[string]any{
+			"nodeId": "doc-1",
+			"comments": []map[string]any{
+				{"topicId": "global", "commentKey": "comment-1"},
+				{"topicId": "topic-2", "commentKey": "comment-2"},
+			},
+		},
+	}
+	if len(caller.calls) != 1 || !reflect.DeepEqual(caller.calls[0], want) {
+		t.Fatalf("calls = %#v, want %#v", caller.calls, want)
+	}
+}
+
+func TestCrossPlatformCoverageSheetCommentResolveAndRestoreUseSharedRPCs(t *testing.T) {
+	caller := &docCommentMutationCaller{}
+	if err := executeCommentBaseCommand(t, caller, "sheet",
+		"comment", "resolve", "--node", "sheet-1", "--comment-key", "comment-1"); err != nil {
+		t.Fatal(err)
+	}
+	if err := executeCommentBaseCommand(t, caller, "sheet",
+		"comment", "restore", "--node", "sheet-1", "--comment-key", "comment-1"); err != nil {
+		t.Fatal(err)
+	}
+	if len(caller.calls) != 2 {
+		t.Fatalf("calls = %#v", caller.calls)
+	}
+	if caller.calls[0].toolName != "resolve_comment" || caller.calls[1].toolName != "restore_comment" {
+		t.Fatalf("tools = %q, %q", caller.calls[0].toolName, caller.calls[1].toolName)
+	}
+	wantArgs := map[string]any{"nodeId": "sheet-1", "commentKey": "comment-1"}
+	if !reflect.DeepEqual(caller.calls[0].args, wantArgs) || !reflect.DeepEqual(caller.calls[1].args, wantArgs) {
+		t.Fatalf("calls = %#v, want args %#v", caller.calls, wantArgs)
+	}
+}
+
+func TestCrossPlatformCoverageCommentReactReplyForcesEmojiTrue(t *testing.T) {
+	caller := &docCommentMutationCaller{}
+	err := executeCommentBaseCommand(t, caller, "doc",
+		"comment", "react-reply", "--file-id", "doc-1",
+		"--comment-key", "comment-1", "--reaction", "鼓掌")
+	if err != nil {
+		t.Fatal(err)
+	}
+	want := docCommentMutationCall{
+		productID: commentServer,
+		toolName:  "reply_comment",
+		args: map[string]any{
+			"nodeId":          "doc-1",
+			"replyCommentKey": "comment-1",
+			"content":         "鼓掌",
+			"emoji":           true,
+		},
+	}
+	if len(caller.calls) != 1 || !reflect.DeepEqual(caller.calls[0], want) {
+		t.Fatalf("calls = %#v, want %#v", caller.calls, want)
+	}
+}
+
+func TestCrossPlatformCoverageCommentReactReplyGuidesDingTalkEmojiNames(t *testing.T) {
+	for _, surface := range []struct {
+		name string
+		cmd  *cobra.Command
+	}{
+		{name: "doc", cmd: newDocCommand()},
+		{name: "sheet", cmd: newSheetCommand()},
+	} {
+		cmd, remaining, err := surface.cmd.Find([]string{"comment", "react-reply"})
+		if err != nil || len(remaining) != 0 {
+			t.Fatalf("dws %s comment react-reply lookup: remaining=%v err=%v", surface.name, remaining, err)
+		}
+		reaction := cmd.Flags().Lookup("reaction")
+		if reaction == nil || !strings.Contains(reaction.Usage, "不是 Unicode Emoji") || !strings.Contains(reaction.Usage, "😄=憨笑") {
+			t.Fatalf("dws %s reaction guidance = %#v", surface.name, reaction)
+		}
+		if !strings.Contains(cmd.Long, "不要直接传") || !strings.Contains(cmd.Example, `--reaction "憨笑"`) {
+			t.Fatalf("dws %s react-reply help missing DingTalk emoji-name guidance", surface.name)
+		}
+	}
+}
+
+func TestCrossPlatformCoverageParseCommentRefsRejectsInvalidShapeAndLimit(t *testing.T) {
+	if _, err := parseCommentRefs(nil); err == nil {
+		t.Fatal("missing refs returned nil error")
+	}
+	if _, err := parseCommentRefs([]string{"missing-separator"}); err == nil {
+		t.Fatal("invalid ref returned nil error")
+	}
+	tooMany := make([]string, 101)
+	for index := range tooMany {
+		tooMany[index] = "global:comment"
+	}
+	if _, err := parseCommentRefs(tooMany); err == nil {
+		t.Fatal("101 refs returned nil error")
+	}
+}

internal/helpers/connect_media_test.go

@@ -96,7 +96,7 @@ func TestCallbackInboundMediaPreservesFutureRichTextAttachment(t *testing.T) {
 
 // TestExtractCallbackText covers the markdown / richText fallback path used
 // when SDK data.Text.Content is empty. This is the recovery path for
-// `dws chat message send --group ... --text ...` (defaults to msgType=markdown)
+// `dws chat message send --conversation-id ... --content ...` (defaults to msgType=markdown)
 // which otherwise gets silently dropped by the connector.
 func TestExtractCallbackText(t *testing.T) {
 	cases := []struct {

internal/helpers/connect_stream.go

@@ -1259,7 +1259,7 @@ func runStreamConnector(ctx context.Context, channel, clientID, clientSecret str
 		}
 		// Structured-text fallback: DingTalk leaves data.Text.Content blank on
 		// markdown / richText callbacks (the body ships in data.Content). Without
-		// this, `dws chat message send --group ... --text ...` — which defaults
+		// this, `dws chat message send --conversation-id ... --content ...` — which defaults
 		// to msgType=markdown — hits the drop branch below and the bot looks
 		// dead to the sender.
 		if text == "" {

internal/helpers/doc.go

@@ -9,15 +9,16 @@ import (
 	"net/url"
 	"os"
 	"path/filepath"
+	"sort"
 	"strconv"
 	"strings"
 	"time"
 
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/cli"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract"
 	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
 	"github.com/spf13/cobra"
-
-	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract"
 )
 
 // ──────────────────────────────────────────────────────────
@@ -492,10 +493,11 @@ func defaultHTTPGetFile(ctx context.Context, url string, headers map[string]stri
 	return nil
 }
 
-// runMediaInsert implements the three-step flow for inserting an attachment into a document:
+// runMediaInsert implements the four-step flow for inserting an attachment into a document:
 //  1. get_doc_attachment_upload_info → obtain uploadUrl + resourceId
 //  2. HTTP PUT file content to OSS
 //  3. insert_document_block with attachment element
+//  4. list_document_blocks → prove the uploaded resource is visible in the document
 func runMediaInsert(cmd *cobra.Command, _ []string) error {
 	nodeID, err := mustFlagOrFallback(cmd, "node", "url", "id", "node-id", "doc-id", "file-id")
 	if err != nil {
@@ -551,7 +553,7 @@ func runMediaInsert(cmd *cobra.Command, _ []string) error {
 	ctx := cmd.Context()
 
 	// Step 1: get upload credentials (uploadUrl + resourceId)
-	deps.Out.PrintInfo(fmt.Sprintf("[1/3] 获取附件上传凭证 (%s, %d bytes)...", fileName, fileSize))
+	deps.Out.PrintInfo(fmt.Sprintf("[1/4] 获取附件上传凭证 (%s, %d bytes)...", fileName, fileSize))
 
 	credText, err := callMCPToolReturnText(ctx, "get_doc_attachment_upload_info", map[string]any{
 		"nodeId":   nodeID,
@@ -569,7 +571,7 @@ func runMediaInsert(cmd *cobra.Command, _ []string) error {
 	}
 
 	// Step 2: HTTP PUT file to OSS
-	deps.Out.PrintInfo("[2/3] 上传文件到 OSS...")
+	deps.Out.PrintInfo("[2/4] 上传文件到 OSS...")
 
 	ossHeaders := map[string]string{
 		"Content-Type": mimeType,
@@ -592,7 +594,7 @@ func runMediaInsert(cmd *cobra.Command, _ []string) error {
 	}
 
 	// Step 3: insert block into document
-	deps.Out.PrintInfo("[3/3] 插入块到文档...")
+	deps.Out.PrintInfo("[3/4] 插入块到文档...")
 
 	const maxInlineImageSize = 20 * 1024 * 1024 // 20MB
 
@@ -644,7 +646,8 @@ func runMediaInsert(cmd *cobra.Command, _ []string) error {
 		insertArgs["referenceBlockId"] = v
 	}
 
-	if err := callMCPTool("insert_document_block", insertArgs); err != nil {
+	insertText, err := callMCPToolReturnText(ctx, "insert_document_block", insertArgs)
+	if err != nil {
 		return apperrors.NewAPI(
 			"附件已上传，但正文 block 插入结果未知；请先检查媒体列表，不要重复上传或插入",
 			apperrors.WithOperation("doc.media_insert"),
@@ -665,6 +668,23 @@ func runMediaInsert(cmd *cobra.Command, _ []string) error {
 			apperrors.WithCause(err),
 		)
 	}
+	insertResult := map[string]any{}
+	if strings.TrimSpace(insertText) != "" {
+		if err := json.Unmarshal([]byte(insertText), &insertResult); err != nil {
+			return docMediaInsertVerificationError(nodeID, resourceID, resourceURL, fileName,
+				fmt.Errorf("解析 insert_document_block 响应失败: %w", err))
+		}
+	}
+	insertedBlockID := insertedDocBlockID(insertResult)
+
+	deps.Out.PrintInfo("[4/4] 回读验证媒体块...")
+	verifiedBlockID, verifyErr := verifyInsertedDocMedia(ctx, nodeID, insertedBlockID, resourceID, resourceURL)
+	if verifyErr != nil {
+		return docMediaInsertVerificationError(nodeID, resourceID, resourceURL, fileName, verifyErr)
+	}
+	if insertedBlockID == "" {
+		insertedBlockID = verifiedBlockID
+	}
 
 	return deps.Out.PrintJSON(map[string]any{
 		"contractVersion": "doc.operation.v1",
@@ -674,16 +694,271 @@ func runMediaInsert(cmd *cobra.Command, _ []string) error {
 		"operation":       "doc.media_insert",
 		"data": map[string]any{
 			"nodeId": nodeID, "resourceId": resourceID, "resourceUrl": resourceURL,
-			"fileName": fileName, "mimeType": mimeType, "sizeBytes": fileSize, "inserted": true,
+			"blockId": insertedBlockID, "fileName": fileName, "mimeType": mimeType, "sizeBytes": fileSize,
+			"inserted": true, "verified": true,
 		},
 		"steps": []map[string]any{
 			{"name": "resolve_upload", "status": "success"},
 			{"name": "upload_oss", "status": "success"},
 			{"name": "insert_block", "status": "success"},
+			{"name": "verify", "status": "success"},
 		},
 	})
 }
 
+func docMediaInsertVerificationError(nodeID, resourceID, resourceURL, fileName string, cause error) error {
+	return apperrors.NewAPI(
+		"附件已上传且插块请求已执行，但回读未能证明媒体块落库；不要直接重试上传或插入",
+		apperrors.WithOperation("doc.media_insert"),
+		apperrors.WithReason("doc_media_insert_verification_failed"),
+		apperrors.WithFailureStage("verify"),
+		apperrors.WithExecutionStarted(true),
+		apperrors.WithRetryable(false),
+		apperrors.WithActions("运行 dws doc +media-list 检查 resourceId", "确认媒体不存在后再决定是否重新执行"),
+		apperrors.WithDetails(map[string]any{
+			"contractVersion": "doc.operation.v1", "status": "partial_success", "nodeId": nodeID,
+			"resourceId": resourceID, "resourceUrl": resourceURL, "fileName": fileName, "verified": false,
+			"steps": []map[string]any{
+				{"name": "resolve_upload", "status": "success"},
+				{"name": "upload_oss", "status": "success"},
+				{"name": "insert_block", "status": "success"},
+				{"name": "verify", "status": "failed"},
+			},
+		}),
+		apperrors.WithCause(cause),
+	)
+}
+
+var docMediaVerifyWait = waitForDocVerification
+
+func verifyInsertedDocMedia(ctx context.Context, nodeID, blockID, resourceID, resourceURL string) (string, error) {
+	delays := []time.Duration{250 * time.Millisecond, 500 * time.Millisecond, time.Second, 2 * time.Second, 4 * time.Second, 8 * time.Second}
+	var lastErr error
+	for attempt := 0; attempt <= len(delays); attempt++ {
+		blocks, err := readAllDocBlocksForVerification(ctx, nodeID)
+		if err != nil {
+			lastErr = err
+		} else {
+			lastErr = nil
+			if found := findVerifiedMediaBlock(blocks, blockID, resourceID, resourceURL); found != "" {
+				return found, nil
+			}
+		}
+		if attempt < len(delays) {
+			if err := docMediaVerifyWait(ctx, delays[attempt]); err != nil {
+				return "", err
+			}
+		}
+	}
+	if lastErr != nil {
+		return "", fmt.Errorf("媒体资源在有界回读窗口内仍无法读取: %w", lastErr)
+	}
+	return "", fmt.Errorf("媒体资源在有界回读窗口内仍不可见")
+}
+
+func waitForDocVerification(ctx context.Context, delay time.Duration) error {
+	if ctx == nil {
+		ctx = context.Background()
+	}
+	timer := time.NewTimer(delay)
+	defer timer.Stop()
+	select {
+	case <-ctx.Done():
+		return ctx.Err()
+	case <-timer.C:
+		return nil
+	}
+}
+
+func readAllDocBlocksForVerification(ctx context.Context, nodeID string) ([]any, error) {
+	const pageSize = 50
+	const maxItems = 5000
+	all := make([]any, 0, pageSize)
+	seenPageIdentities := map[string]bool{}
+	for start := 0; start < maxItems; start += pageSize {
+		text, err := callMCPToolReturnTextOnServer(ctx, "doc", "list_document_blocks", map[string]any{
+			"nodeId": nodeID, "format": "jsonml", "startIndex": start, "endIndex": start + pageSize - 1,
+		})
+		if err != nil {
+			return nil, err
+		}
+		var payload map[string]any
+		if err := json.Unmarshal([]byte(text), &payload); err != nil {
+			return nil, fmt.Errorf("解析 list_document_blocks 回读失败: %w", err)
+		}
+		payload = nestedDocMap(payload)
+		blocks, ok := payload["blocks"].([]any)
+		if !ok {
+			return nil, fmt.Errorf("list_document_blocks 回读缺少 blocks 数组")
+		}
+		pageIdentity := docBlockPageIdentity(blocks)
+		if pageIdentity != "" && seenPageIdentities[pageIdentity] {
+			return nil, fmt.Errorf("list_document_blocks 分页停滞")
+		}
+		if pageIdentity != "" {
+			seenPageIdentities[pageIdentity] = true
+		}
+		all = append(all, blocks...)
+		hasMore, hasMoreKnown := payload["hasMore"].(bool)
+		if hasMoreKnown && !hasMore {
+			return all, nil
+		}
+		if !hasMoreKnown {
+			if total, ok := docNumberAsInt(payload["totalCount"]); ok && len(all) >= total {
+				return all, nil
+			}
+		}
+		if !hasMoreKnown && len(blocks) < pageSize {
+			return all, nil
+		}
+		if len(blocks) == 0 {
+			return nil, fmt.Errorf("list_document_blocks 声明仍有下一页但当前页为空")
+		}
+	}
+	return nil, fmt.Errorf("文档块超过安全回读上限")
+}
+
+func docBlockPageIdentity(blocks []any) string {
+	if len(blocks) == 0 {
+		return ""
+	}
+	ids := make([]string, 0, len(blocks))
+	for _, value := range blocks {
+		id := ""
+		switch block := value.(type) {
+		case map[string]any:
+			id = directDocBlockIdentity(block)
+			if id == "" {
+				if element, ok := block["element"].(map[string]any); ok {
+					id = directDocBlockIdentity(element)
+				}
+			}
+		case []any:
+			if len(block) > 1 {
+				if attributes, ok := block[1].(map[string]any); ok {
+					id = directDocBlockIdentity(attributes)
+				}
+			}
+		}
+		if id == "" {
+			return ""
+		}
+		ids = append(ids, id)
+	}
+	encoded, _ := json.Marshal(ids)
+	return string(encoded)
+}
+
+func directDocBlockIdentity(block map[string]any) string {
+	for _, key := range []string{"blockId", "id", "uuid", "elementId"} {
+		if text, ok := block[key].(string); ok && strings.TrimSpace(text) != "" {
+			return strings.TrimSpace(text)
+		}
+	}
+	return ""
+}
+
+func nestedDocMap(data map[string]any) map[string]any {
+	for _, key := range []string{"result", "data"} {
+		if nested, ok := data[key].(map[string]any); ok {
+			return nestedDocMap(nested)
+		}
+	}
+	return data
+}
+
+func nestedDocString(value any, keys ...string) string {
+	switch typed := value.(type) {
+	case map[string]any:
+		for _, key := range keys {
+			if text, ok := typed[key].(string); ok && strings.TrimSpace(text) != "" {
+				return strings.TrimSpace(text)
+			}
+		}
+		orderedKeys := make([]string, 0, len(typed))
+		for key := range typed {
+			orderedKeys = append(orderedKeys, key)
+		}
+		sort.Strings(orderedKeys)
+		for _, key := range orderedKeys {
+			if text := nestedDocString(typed[key], keys...); text != "" {
+				return text
+			}
+		}
+	case []any:
+		for _, child := range typed {
+			if text := nestedDocString(child, keys...); text != "" {
+				return text
+			}
+		}
+	}
+	return ""
+}
+
+// insertedDocBlockID only accepts explicit block IDs from the insert result or
+// known response wrappers. Arbitrary IDs may belong to the document, operator,
+// or request and must not become a hard constraint for the media readback.
+func insertedDocBlockID(data map[string]any) string {
+	for _, key := range []string{"blockId", "elementId"} {
+		if text, ok := data[key].(string); ok && strings.TrimSpace(text) != "" {
+			return strings.TrimSpace(text)
+		}
+	}
+	for _, wrapper := range []string{"result", "data", "content"} {
+		if inner, ok := data[wrapper].(map[string]any); ok {
+			if text := insertedDocBlockID(inner); text != "" {
+				return text
+			}
+		}
+	}
+	return ""
+}
+
+func findVerifiedMediaBlock(blocks []any, blockID, resourceID, resourceURL string) string {
+	for _, value := range blocks {
+		candidateID := nestedDocString(value, "blockId", "id", "uuid")
+		if candidateID == "" || (blockID != "" && candidateID != blockID) {
+			continue
+		}
+		mediaValue := docMediaReadbackValue(value)
+		if resourceID != "" && nestedDocString(mediaValue, "resourceId") == resourceID {
+			return candidateID
+		}
+		if resourceURL != "" && nestedDocString(mediaValue, "resourceUrl", "src") == resourceURL {
+			return candidateID
+		}
+	}
+	return ""
+}
+
+func docMediaReadbackValue(value any) any {
+	block, ok := value.(map[string]any)
+	if !ok {
+		return value
+	}
+	encoded, ok := block["jsonml"].(string)
+	if !ok || strings.TrimSpace(encoded) == "" {
+		return value
+	}
+	var decoded any
+	if json.Unmarshal([]byte(encoded), &decoded) != nil {
+		return value
+	}
+	return decoded
+}
+
+func docNumberAsInt(value any) (int, bool) {
+	switch typed := value.(type) {
+	case float64:
+		if typed >= 0 && typed == float64(int(typed)) {
+			return int(typed), true
+		}
+	case int:
+		return typed, typed >= 0
+	}
+	return 0, false
+}
+
 // parseAttachmentUploadInfo extracts uploadUrl, resourceId and resourceUrl from the MCP tool response.
 func parseAttachmentUploadInfo(text string) (uploadURL, resourceID, resourceURL string, err error) {
 	var data map[string]any
@@ -743,7 +1018,7 @@ func inferMimeType(fileName string) string {
 }
 
 // buildBlockElement 从 flags 构建块元素 JSON 对象。
-// 优先级: --element (原始 JSON) > --heading > --text
+// 优先级: --element (原始 JSON) > --heading > --text (旧名) > --content
 func buildBlockElement(cmd *cobra.Command) (any, error) {
 	if raw, _ := cmd.Flags().GetString("element"); raw != "" {
 		var obj any
@@ -762,13 +1037,13 @@ func buildBlockElement(cmd *cobra.Command) (any, error) {
 			"heading":   map[string]any{"text": h, "level": level},
 		}, nil
 	}
-	if t, _ := cmd.Flags().GetString("text"); t != "" {
+	if t := flagOrFallback(cmd, "text", "content"); t != "" {
 		return map[string]any{
 			"blockType": "paragraph",
 			"paragraph": map[string]any{"text": t},
 		}, nil
 	}
-	return nil, fmt.Errorf("block content required: --text / --heading / --element")
+	return nil, fmt.Errorf("block content required: --content / --heading / --element")
 }
 
 // buildNodeTransferRunE creates a RunE handler for copy/move commands.
@@ -1852,12 +2127,12 @@ WARNING: --mode overwrite 为破坏性写入，会清空原文档全部内容。
 		Use:   "insert",
 		Short: "插入块元素",
 		Long: `向文档插入块元素。通过 --element 传入 JSON 格式的块元素。
-可用 --text 快速插入段落，--heading + --level 快速插入标题。
+可用 --content 快速插入段落，--heading + --level 快速插入标题。
 
 块类型: paragraph, heading, blockquote, callout, columns,
         orderedList, unorderedList, table, sheet, attachment, slot`,
 		Example: `  # 快捷插入段落
-  dws doc block insert --node DOC_ID --text "这是一段文字"
+  dws doc block insert --node DOC_ID --content "这是一段文字"
 
   # 快捷插入标题
   dws doc block insert --node DOC_ID --heading "二级标题" --level 2
@@ -1880,7 +2155,7 @@ WARNING: --mode overwrite 为破坏性写入，会清空原文档全部内容。
   dws doc block insert --node DOC_ID --element '{"blockType":"unorderedList","unorderedList":{"list":{"listId":"list-2"}},"children":[{"text":"第二项"}]}'
 
   # 在指定位置之前插入
-  dws doc block insert --node DOC_ID --text "插入内容" --ref-block BLOCK_ID --where before`,
+  dws doc block insert --node DOC_ID --content "插入内容" --ref-block BLOCK_ID --where before`,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			nodeID, err := mustFlagOrFallback(cmd, "node", "url", "id", "node-id", "doc-id", "file-id")
 			if err != nil {
@@ -1966,14 +2241,14 @@ WARNING: --mode overwrite 为破坏性写入，会清空原文档全部内容。
 			},
 			Selection: contract.SelectionSpec{
 				AgentSummary: "向文档插入块元素",
-				UseWhen:      []string{"在文档中插入新块（段落/标题等）；简单场景用 --text/--heading，复杂块用 --element JSON"},
+				UseWhen:      []string{"在文档中插入新块（段落/标题等）；简单场景用 --content/--heading，复杂块用 --element JSON"},
 				AvoidWhen: []string{
 					"整篇追加 Markdown 优先 doc update --mode append",
 					"插入本地文件附件优先 doc media insert",
 					"删块用 block delete；改已有块用 block update",
 				},
 				Examples: []string{
-					"dws doc block insert --node <DOC_ID> --text \"这是一段文字\" --format json",
+					"dws doc block insert --node <DOC_ID> --content \"这是一段文字\" --format json",
 					"dws doc block insert --node <DOC_ID> --heading \"二级标题\" --level 2 --format json",
 				},
 			},
@@ -1990,8 +2265,8 @@ WARNING: --mode overwrite 为破坏性写入，会清空原文档全部内容。
 		Use:   "update",
 		Short: "更新块元素",
 		Long: `更新文档中指定块的内容或样式。需提供 --block-id 和块元素内容。
-可用 --text 快速更新为段落，--heading + --level 快速更新为标题。`,
-		Example: `  dws doc block update --node DOC_ID --block-id BLOCK_ID --text "新内容"    # 查询 nodeId: dws doc search --query "..." 或 dws doc list  # 查询 blockId: dws doc block list --node <nodeId>
+可用 --content 快速更新为段落，--heading + --level 快速更新为标题。`,
+		Example: `  dws doc block update --node DOC_ID --block-id BLOCK_ID --content "新内容"    # 查询 nodeId: dws doc search --query "..." 或 dws doc list  # 查询 blockId: dws doc block list --node <nodeId>
   dws doc block update --node DOC_ID --block-id BLOCK_ID --element '{"blockType":"heading","heading":{"text":"新标题","level":1}}'`,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			if err := validateRequiredFlags(cmd, "block-id"); err != nil {
@@ -2063,7 +2338,7 @@ WARNING: --mode overwrite 为破坏性写入，会清空原文档全部内容。
 					"插入新块用 block insert；删除用 block delete",
 					"改文档显示名用 rename；整篇覆盖用 update overwrite",
 				},
-				Examples: []string{"dws doc block update --node <DOC_ID> --block-id <BLOCK_ID> --text \"新内容\" --format json"},
+				Examples: []string{"dws doc block update --node <DOC_ID> --block-id <BLOCK_ID> --content \"新内容\" --format json"},
 			},
 			Parameters: []contract.ParamDecl{
 				{Name: "content-format", Property: "format"},
@@ -2473,7 +2748,6 @@ WARNING: --mode overwrite 为破坏性写入，会清空原文档全部内容。
 
 	// block insert
 	blockInsertCmd.Flags().String("node", "", "文档 ID 或 URL (必填)")
-	blockInsertCmd.Flags().String("text", "", "快捷: 段落文本内容")
 	blockInsertCmd.Flags().String("heading", "", "快捷: 标题文本")
 	blockInsertCmd.Flags().Int("level", 1, "标题级别 1-6 (配合 --heading)")
 	blockInsertCmd.Flags().String("element", "", "块元素 JSON (高级)")
@@ -2487,7 +2761,6 @@ WARNING: --mode overwrite 为破坏性写入，会清空原文档全部内容。
 	// block update
 	blockUpdateCmd.Flags().String("node", "", "文档 ID 或 URL (必填)")
 	blockUpdateCmd.Flags().String("block-id", "", "目标块 ID (必填)")
-	blockUpdateCmd.Flags().String("text", "", "快捷: 段落文本内容")
 	blockUpdateCmd.Flags().String("heading", "", "快捷: 标题文本")
 	blockUpdateCmd.Flags().Int("level", 1, "标题级别 1-6 (配合 --heading)")
 	blockUpdateCmd.Flags().String("element", "", "块元素 JSON (高级)")
@@ -3242,6 +3515,7 @@ commentKey可从 dws doc comment create 或 dws doc comment list 返回结果中
 	}
 
 	commentCmd.AddCommand(commentListCmd, commentCreateCmd, commentReplyCmd, commentUpdateCmd, commentDeleteCmd, commentCreateInlineCmd)
+	commentCmd.AddCommand(newCommentBaseCommands("doc")...)
 
 	// ── permission (文档协作权限) ────────────────────────────
 	permissionCmd := &cobra.Command{
@@ -4368,6 +4642,16 @@ CLI 内部自动完成全部流程:
 			RegisterCrossProductAliases(child)
 		}
 	}
+	// Register the block content Primary after the cross-product pass. Registering
+	// --content earlier would make the global content/markdown group expand a new
+	// --markdown alias onto these commands, which is outside this migration.
+	for _, cmd := range []*cobra.Command{blockInsertCmd, blockUpdateCmd} {
+		corecmd.RegisterFlags(cmd, []corecmd.FlagSpec{{
+			Name:    "content",
+			Usage:   "快捷: 段落文本内容",
+			Aliases: []string{"text"},
+		}})
+	}
 
 	// ── deprecated 标记：文件管理命令已迁移到 drive ──
 	deprecatedDocToDrive := map[*cobra.Command]string{

internal/helpers/doc_command_edges_test.go

@@ -3,7 +3,9 @@ package helpers
 import (
 	"bytes"
 	"context"
+	"encoding/json"
 	"errors"
+	"fmt"
 	"io"
 	"net/http"
 	"net/http/httptest"
@@ -13,6 +15,7 @@ import (
 	"testing"
 	"time"
 
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition"
 	"github.com/spf13/cobra"
 )
@@ -74,6 +77,8 @@ func TestCrossPlatformCoverageDocUploadAndMediaErrorEdges(t *testing.T) {
 	t.Cleanup(func() { os.Args = oldArgs })
 	oldPut, oldGet := httpPutFile, httpGetFile
 	t.Cleanup(func() { httpPutFile, httpGetFile = oldPut, oldGet })
+	testseam.Swap(t, &helperSleep, func(time.Duration) {})
+	testseam.Swap(t, &docMediaVerifyWait, func(context.Context, time.Duration) error { return nil })
 	file := filepath.Join(t.TempDir(), "file.txt")
 	if err := os.WriteFile(file, []byte("content"), 0o600); err != nil {
 		t.Fatal(err)
@@ -193,6 +198,47 @@ func TestCrossPlatformCoverageDocUploadAndMediaErrorEdges(t *testing.T) {
 			t.Fatal("media insert failure returned nil")
 		}
 	})
+	t.Run("media insert response parse failure", func(t *testing.T) {
+		httpPutFile = func(context.Context, string, map[string]string, string, int64) error { return nil }
+		caller := &scriptedToolCaller{steps: []scriptedToolStep{
+			{text: `{"uploadUrl":"https://upload","resourceId":"resource"}`},
+			{text: `{`},
+		}}
+		if err := mediaCommand(t, caller, file, "text/plain"); err == nil {
+			t.Fatal("invalid media insert response returned nil")
+		}
+	})
+	t.Run("small image verifies src readback when upload also returns resource ID", func(t *testing.T) {
+		httpPutFile = func(context.Context, string, map[string]string, string, int64) error { return nil }
+		caller := &scriptedToolCaller{steps: []scriptedToolStep{
+			{text: `{"uploadUrl":"https://upload","resourceId":"resource","resourceUrl":"https://image"}`},
+			{text: `{"blockId":"media-block"}`},
+			{text: `{"blocks":[{"blockId":"media-block","jsonml":"[\"p\",{\"uuid\":\"media-block\"},[\"img\",{\"src\":\"https://image\"}]]"}],"hasMore":false}`},
+		}}
+		if err := mediaCommand(t, caller, file, "image/png"); err != nil {
+			t.Fatal(err)
+		}
+		if caller.calls != 3 {
+			t.Fatalf("media insert calls = %d, want credential, insert, and one readback", caller.calls)
+		}
+		if caller.args["format"] != "jsonml" {
+			t.Fatalf("media readback format = %#v, want jsonml", caller.args["format"])
+		}
+	})
+	t.Run("unrelated insert response IDs do not constrain media readback", func(t *testing.T) {
+		httpPutFile = func(context.Context, string, map[string]string, string, int64) error { return nil }
+		caller := &scriptedToolCaller{steps: []scriptedToolStep{
+			{text: `{"uploadUrl":"https://upload","resourceId":"resource","resourceUrl":"https://image"}`},
+			{text: `{"id":"document-id","operator":{"id":"operator-id"},"data":{"request":{"id":"request-id"}}}`},
+			{text: `{"blocks":[{"blockId":"media-block","jsonml":"[\"p\",{\"uuid\":\"media-block\"},[\"img\",{\"src\":\"https://image\"}]]"}],"hasMore":false}`},
+		}}
+		if err := mediaCommand(t, caller, file, "image/png"); err != nil {
+			t.Fatal(err)
+		}
+		if caller.calls != 3 {
+			t.Fatalf("media insert calls = %d, want credential, insert, and one readback", caller.calls)
+		}
+	})
 	t.Run("large image becomes attachment", func(t *testing.T) {
 		httpPutFile = func(context.Context, string, map[string]string, string, int64) error { return nil }
 		large := filepath.Join(t.TempDir(), "large.png")
@@ -202,7 +248,11 @@ func TestCrossPlatformCoverageDocUploadAndMediaErrorEdges(t *testing.T) {
 		if err := os.Truncate(large, 21*1024*1024); err != nil {
 			t.Fatal(err)
 		}
-		caller := &scriptedToolCaller{steps: []scriptedToolStep{{text: `{"uploadUrl":"https://upload","resourceId":"resource","resourceUrl":"https://image"}`}, {text: `{}`}}}
+		caller := &scriptedToolCaller{steps: []scriptedToolStep{
+			{text: `{"uploadUrl":"https://upload","resourceId":"resource","resourceUrl":"https://image"}`},
+			{text: `{}`},
+			{text: `{"blocks":[{"blockId":"media-block","element":{"attachment":{"resourceId":"resource"}}}],"hasMore":false}`},
+		}}
 		if err := mediaCommand(t, caller, large, "image/png"); err != nil {
 			t.Fatal(err)
 		}
@@ -240,6 +290,181 @@ func TestCrossPlatformCoverageDefaultDocHTTPTransportEdges(t *testing.T) {
 	}
 }
 
+func TestCrossPlatformCoverageDocMediaReadbackDefensiveEdges(t *testing.T) {
+	testseam.Swap(t, &helperSleep, func(time.Duration) {})
+	testseam.Swap(t, &docMediaVerifyWait, func(context.Context, time.Duration) error { return nil })
+	ctx := context.Background()
+
+	for _, tc := range []struct {
+		name  string
+		steps []scriptedToolStep
+	}{
+		{"call failure", []scriptedToolStep{{err: errors.New("read")}}},
+		{"invalid json", []scriptedToolStep{{text: `{`}}},
+		{"missing blocks", []scriptedToolStep{{text: `{}`}}},
+		{"stalled page", []scriptedToolStep{{text: `{"blocks":[{"id":"a"}],"hasMore":true}`}, {text: `{"blocks":[{"id":"a"}],"hasMore":true}`}}},
+		{"empty continued page", []scriptedToolStep{{text: `{"blocks":[],"hasMore":true}`}}},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			installScriptedCaller(t, &scriptedToolCaller{steps: tc.steps})
+			if _, err := readAllDocBlocksForVerification(ctx, "node"); err == nil {
+				t.Fatal("defensive readback returned nil")
+			}
+		})
+	}
+
+	t.Run("total count and nested payload", func(t *testing.T) {
+		installScriptedCaller(t, &scriptedToolCaller{steps: []scriptedToolStep{{text: `{"data":{"blocks":[{"id":"a"}],"totalCount":1}}`}}})
+		blocks, err := readAllDocBlocksForVerification(ctx, "node")
+		if err != nil || len(blocks) != 1 {
+			t.Fatalf("blocks=%#v err=%v", blocks, err)
+		}
+	})
+
+	t.Run("identical adjacent pages advance by requested indexes", func(t *testing.T) {
+		blocks := make([]any, 50)
+		for index := range blocks {
+			blocks[index] = map[string]any{"blockType": "paragraph"}
+		}
+		first, err := json.Marshal(map[string]any{"blocks": blocks, "hasMore": true, "totalCount": 100})
+		if err != nil {
+			t.Fatal(err)
+		}
+		second, err := json.Marshal(map[string]any{"blocks": blocks, "hasMore": false, "totalCount": 100})
+		if err != nil {
+			t.Fatal(err)
+		}
+		caller := &scriptedToolCaller{steps: []scriptedToolStep{{text: string(first)}, {text: string(second)}}}
+		installScriptedCaller(t, caller)
+		got, err := readAllDocBlocksForVerification(ctx, "node")
+		if err != nil || len(got) != 100 || caller.calls != 2 {
+			t.Fatalf("blocks=%d calls=%d err=%v, want 100 blocks from two pages", len(got), caller.calls, err)
+		}
+	})
+
+	t.Run("explicit has more overrides inconsistent total count", func(t *testing.T) {
+		caller := &scriptedToolCaller{steps: []scriptedToolStep{
+			{text: `{"blocks":[{"id":"first"}],"hasMore":true,"totalCount":1}`},
+			{text: `{"blocks":[{"id":"second"}],"hasMore":false,"totalCount":2}`},
+		}}
+		installScriptedCaller(t, caller)
+		got, err := readAllDocBlocksForVerification(ctx, "node")
+		if err != nil || len(got) != 2 || caller.calls != 2 {
+			t.Fatalf("blocks=%d calls=%d err=%v, want both explicitly advertised pages", len(got), caller.calls, err)
+		}
+	})
+
+	t.Run("page identity accepts nested and JSONML block IDs", func(t *testing.T) {
+		if got := docBlockPageIdentity([]any{map[string]any{"element": map[string]any{"blockId": "nested-block"}}}); got != `["nested-block"]` {
+			t.Fatalf("nested block page identity = %q", got)
+		}
+		if got := docBlockPageIdentity([]any{[]any{"p", map[string]any{"uuid": "jsonml-block"}}}); got != `["jsonml-block"]` {
+			t.Fatalf("JSONML block page identity = %q", got)
+		}
+	})
+
+	t.Run("unknown pagination short page", func(t *testing.T) {
+		installScriptedCaller(t, &scriptedToolCaller{steps: []scriptedToolStep{{text: `{"blocks":[{"id":"a"}]}`}}})
+		if blocks, err := readAllDocBlocksForVerification(ctx, "node"); err != nil || len(blocks) != 1 {
+			t.Fatalf("blocks=%#v err=%v", blocks, err)
+		}
+	})
+
+	t.Run("bounded retry failure", func(t *testing.T) {
+		installScriptedCaller(t, &scriptedToolCaller{steps: []scriptedToolStep{{text: `{"blocks":[],"hasMore":false}`}}})
+		if _, err := verifyInsertedDocMedia(ctx, "node", "", "missing", ""); err == nil {
+			t.Fatal("missing media unexpectedly verified")
+		}
+	})
+
+	t.Run("transient read failure retries", func(t *testing.T) {
+		caller := &scriptedToolCaller{steps: []scriptedToolStep{
+			{err: errors.New("temporary read failure")},
+			{text: `{"blocks":[{"blockId":"media-block","element":{"attachment":{"resourceId":"resource"}}}],"hasMore":false}`},
+		}}
+		installScriptedCaller(t, caller)
+		blockID, err := verifyInsertedDocMedia(ctx, "node", "media-block", "resource", "")
+		if err != nil || blockID != "media-block" || caller.calls != 2 {
+			t.Fatalf("blockID=%q calls=%d err=%v", blockID, caller.calls, err)
+		}
+	})
+
+	t.Run("block identity alone does not verify media", func(t *testing.T) {
+		installScriptedCaller(t, &scriptedToolCaller{steps: []scriptedToolStep{{text: `{"blocks":[{"blockId":"media-block","element":{"attachment":{"resourceId":"other-resource"}}}],"hasMore":false}`}}})
+		if _, err := verifyInsertedDocMedia(ctx, "node", "media-block", "resource", ""); err == nil {
+			t.Fatal("matching block ID with a different resource unexpectedly verified")
+		}
+	})
+
+	t.Run("block read safety limit", func(t *testing.T) {
+		steps := make([]scriptedToolStep, 100)
+		for index := range steps {
+			steps[index] = scriptedToolStep{text: fmt.Sprintf(`{"blocks":[{"id":"block-%d"}],"hasMore":true}`, index)}
+		}
+		installScriptedCaller(t, &scriptedToolCaller{steps: steps})
+		if _, err := readAllDocBlocksForVerification(ctx, "node"); err == nil {
+			t.Fatal("oversized block read returned nil")
+		}
+	})
+
+	if got := nestedDocMap(map[string]any{"result": map[string]any{"data": map[string]any{"ok": true}}}); got["ok"] != true {
+		t.Fatalf("nested map=%#v", got)
+	}
+	if nestedDocString(map[string]any{"x": []any{map[string]any{"id": " nested "}}}, "id") != "nested" || nestedDocString(3, "id") != "" {
+		t.Fatal("nested string traversal failed")
+	}
+	if got := nestedDocString(map[string]any{"z": map[string]any{"id": "last"}, "a": map[string]any{"id": "first"}}, "id"); got != "first" {
+		t.Fatalf("nested string traversal = %q, want deterministic key order", got)
+	}
+	if got := insertedDocBlockID(map[string]any{"id": "document", "result": map[string]any{"data": map[string]any{"blockId": " block "}}}); got != "block" {
+		t.Fatalf("trusted inserted block ID = %q, want block", got)
+	}
+	if got := insertedDocBlockID(map[string]any{"id": "document", "operator": map[string]any{"id": "operator"}, "data": map[string]any{"request": map[string]any{"id": "request"}}}); got != "" {
+		t.Fatalf("untrusted inserted block ID = %q, want empty", got)
+	}
+	blocks := []any{map[string]any{"id": "block", "resourceId": "rid"}, map[string]any{"id": "url-block", "resourceUrl": "https://media"}, map[string]any{"id": "src-block", "jsonml": `["p",{},["img",{"src":"https://image"}]]`}}
+	if findVerifiedMediaBlock(blocks, "block", "rid", "") != "block" || findVerifiedMediaBlock(blocks, "", "rid", "") != "block" || findVerifiedMediaBlock(blocks, "", "", "https://media") != "url-block" || findVerifiedMediaBlock(blocks, "src-block", "upload-resource", "https://image") != "src-block" || findVerifiedMediaBlock(blocks, "other-block", "upload-resource", "https://image") != "" || findVerifiedMediaBlock(blocks, "block", "wrong", "") != "" || findVerifiedMediaBlock(blocks, "", "missing", "") != "" {
+		t.Fatal("media block matching failed")
+	}
+	if findVerifiedMediaBlock([]any{map[string]any{"id": "bad-jsonml", "jsonml": `[`}}, "bad-jsonml", "", "https://image") != "" {
+		t.Fatal("invalid JSONML unexpectedly verified")
+	}
+	if got := docMediaReadbackValue("plain"); got != "plain" {
+		t.Fatalf("non-object media readback = %#v, want unchanged value", got)
+	}
+	for _, tc := range []struct {
+		value any
+		want  bool
+	}{
+		{float64(3), true}, {float64(-1), false}, {1.5, false}, {3, true}, {-1, false}, {"3", false},
+	} {
+		_, ok := docNumberAsInt(tc.value)
+		if ok != tc.want {
+			t.Fatalf("docNumberAsInt(%#v) ok=%v want=%v", tc.value, ok, tc.want)
+		}
+	}
+}
+
+func TestCrossPlatformCoverageDocMediaReadbackStopsOnCancellation(t *testing.T) {
+	if err := waitForDocVerification(nil, time.Nanosecond); err != nil {
+		t.Fatalf("completed verification wait = %v", err)
+	}
+	cancelled, cancel := context.WithCancel(context.Background())
+	cancel()
+	if err := waitForDocVerification(cancelled, time.Hour); !errors.Is(err, context.Canceled) {
+		t.Fatalf("cancelled verification wait = %v, want context.Canceled", err)
+	}
+
+	caller := &scriptedToolCaller{steps: []scriptedToolStep{{text: `{"blocks":[],"hasMore":false}`}}}
+	installScriptedCaller(t, caller)
+	if _, err := verifyInsertedDocMedia(cancelled, "node", "", "missing", ""); !errors.Is(err, context.Canceled) {
+		t.Fatalf("cancelled media verification = %v, want context.Canceled", err)
+	}
+	if caller.calls != 1 {
+		t.Fatalf("cancelled media verification calls = %d, want 1", caller.calls)
+	}
+}
+
 func TestCrossPlatformCoverageDocCreateUpdateAndBlockCommandEdges(t *testing.T) {
 	oldDeps, oldArgs, oldPut, oldGet := deps, os.Args, httpPutFile, httpGetFile
 	t.Cleanup(func() {

internal/helpers/doc_coverage_more_test.go

@@ -9,6 +9,7 @@ import (
 	"path/filepath"
 	"strings"
 	"testing"
+	"time"
 
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam"
 	"github.com/spf13/cobra"
@@ -194,6 +195,7 @@ func TestCrossPlatformCoverageDocDeprecationWrappersCoverage(t *testing.T) {
 }
 
 func TestCrossPlatformCoverageRunDocUploadDownloadAndMediaCoverage(t *testing.T) {
+	testseam.Swap(t, &docMediaVerifyWait, func(context.Context, time.Duration) error { return nil })
 	oldArgs := os.Args
 	os.Args = []string{"dws", "doc"}
 	t.Cleanup(func() { os.Args = oldArgs })

internal/helpers/helpers.go

@@ -155,7 +155,18 @@ func callMCPToolReturnTextOnServer(ctx context.Context, serverID, toolName strin
 // ReadToolCaller capability; if unavailable, it fails closed instead of
 // returning a synthetic dry-run envelope that looks like business data.
 func CallMCPReadToolTextOnServer(serverID, toolName string, args map[string]any) (string, error) {
-	return callMCPReadToolReturnTextOnServer(context.Background(), serverID, toolName, args)
+	return CallMCPReadToolTextOnServerContext(context.Background(), serverID, toolName, args)
+}
+
+// CallMCPReadToolTextOnServerContext is the cancellable form used by Cobra
+// commands and composite shortcuts. Keeping the caller context attached to the
+// transport lets SIGTERM/parent deadlines stop an in-flight MCP read and return
+// a structured error instead of leaving the CLI silent until the host kills it.
+func CallMCPReadToolTextOnServerContext(ctx context.Context, serverID, toolName string, args map[string]any) (string, error) {
+	if ctx == nil {
+		ctx = context.Background()
+	}
+	return callMCPReadToolReturnTextOnServer(ctx, serverID, toolName, args)
 }
 
 func callMCPReadToolReturnTextOnServer(ctx context.Context, serverID, toolName string, args map[string]any) (string, error) {
@@ -266,7 +277,17 @@ func parseMCPToolTextResult(serverID, toolName string, result *edition.ToolResul
 // print path. Exported for the shortcut layer's multi-step ("smart") shortcuts,
 // which chain several tool calls and need each intermediate result as data.
 func CallMCPToolTextOnServer(serverID, toolName string, args map[string]any) (string, error) {
-	return callMCPToolReturnTextOnServer(context.Background(), serverID, toolName, args)
+	return CallMCPToolTextOnServerContext(context.Background(), serverID, toolName, args)
+}
+
+// CallMCPToolTextOnServerContext invokes one MCP tool while preserving the
+// command's cancellation and deadline. Legacy callers may continue using
+// CallMCPToolTextOnServer, which intentionally retains background context.
+func CallMCPToolTextOnServerContext(ctx context.Context, serverID, toolName string, args map[string]any) (string, error) {
+	if ctx == nil {
+		ctx = context.Background()
+	}
+	return callMCPToolReturnTextOnServer(ctx, serverID, toolName, args)
 }
 
 // CallMCPToolDataOnServer invokes one tool without printing and decodes its
@@ -293,7 +314,11 @@ func CallMCPToolDataOnServer(ctx context.Context, serverID, toolName string, arg
 // callMCPTool 是通用的 MCP 工具调用入口：自动路由 → 调用 → 格式化输出。
 // 通过 resolveProductID() 自动确定目标 MCP Server，JSON 输出使用默认的 HTML 转义。
 func callMCPTool(toolName string, args map[string]any) error {
-	return callMCPToolInternalOpts("", toolName, args, false)
+	return callMCPToolContext(context.Background(), toolName, args)
+}
+
+func callMCPToolContext(ctx context.Context, toolName string, args map[string]any) error {
+	return callMCPToolInternalOptsContext(ctx, "", toolName, args, false)
 }
 
 // callMCPToolUnescaped 与 callMCPTool 功能相同，但 JSON 输出禁用 HTML 转义。
@@ -306,7 +331,7 @@ func callMCPToolUnescaped(toolName string, args map[string]any) error {
 // callMCPToolOnServer 在指定的 MCP Server 上调用工具，跳过 resolveProductID() 的自动路由。
 // 用于需要显式指定 serverID 的场景（如 credit 等多 server 产品）。
 func callMCPToolOnServer(serverID, toolName string, args map[string]any) error {
-	return callMCPToolInternalOpts(serverID, toolName, args, false)
+	return callMCPToolInternalOptsContext(context.Background(), serverID, toolName, args, false)
 }
 
 // CallMCPToolOnServer is the exported version of callMCPToolOnServer for use
@@ -315,6 +340,13 @@ func CallMCPToolOnServer(serverID, toolName string, args map[string]any) error {
 	return callMCPToolOnServer(serverID, toolName, args)
 }
 
+// CallMCPToolOnServerContext is the cancellable print-path variant for
+// Shortcut execution. It preserves the same output and error projection as the
+// legacy wrapper while allowing the root signal context to abort transport.
+func CallMCPToolOnServerContext(ctx context.Context, serverID, toolName string, args map[string]any) error {
+	return callMCPToolInternalOptsContext(ctx, serverID, toolName, args, false)
+}
+
 // GroupRunE is the exported version of groupRunE for use by extension packages.
 func GroupRunE(cmd *cobra.Command, args []string) error {
 	return groupRunE(cmd, args)
@@ -343,7 +375,13 @@ func MustGetStringFlag(cmd *cobra.Command, name string) string {
 //  3. 错误分类：网关错误 → 未登录 → PAT 错误 → 业务错误
 //  4. 根据 --format 标志选择输出格式（json / table / raw）
 func callMCPToolInternalOpts(explicitServerID, toolName string, args map[string]any, unescapeHTML bool) error {
-	ctx := context.Background()
+	return callMCPToolInternalOptsContext(context.Background(), explicitServerID, toolName, args, unescapeHTML)
+}
+
+func callMCPToolInternalOptsContext(ctx context.Context, explicitServerID, toolName string, args map[string]any, unescapeHTML bool) error {
+	if ctx == nil {
+		ctx = context.Background()
+	}
 
 	// DryRun 模式：仅预览工具名和参数，不实际调用 MCP Server
 	if deps.Caller.DryRun() {

internal/helpers/helpers_core_test.go

@@ -39,6 +39,20 @@ type helpersReadCaller struct {
 	readCalls  int
 }
 
+type helpersContextCaller struct {
+	*helpersCoreCaller
+	seenErr error
+}
+
+func (c *helpersContextCaller) CallTool(ctx context.Context, _ string, _ string, _ map[string]any) (*edition.ToolResult, error) {
+	c.calls++
+	c.seenErr = ctx.Err()
+	if c.seenErr != nil {
+		return nil, c.seenErr
+	}
+	return nil, errors.New("stop after context capture")
+}
+
 func (c *helpersReadCaller) CallReadTool(context.Context, string, string, map[string]any) (*edition.ToolResult, error) {
 	c.readCalls++
 	return c.readResult, c.readErr
@@ -128,6 +142,48 @@ func TestCrossPlatformCoverageReadLookupInitializationAndRegularExecution(t *tes
 	}
 }
 
+func TestCrossPlatformCoverageMCPContextWrappersPreserveCancellation(t *testing.T) {
+	caller := &helpersContextCaller{helpersCoreCaller: &helpersCoreCaller{format: "json"}}
+	installHelpersCoreDeps(t, caller)
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+
+	if _, err := CallMCPToolTextOnServerContext(ctx, "aitable", "get_fields", nil); err == nil {
+		t.Fatal("cancelled text call unexpectedly succeeded")
+	}
+	if !errors.Is(caller.seenErr, context.Canceled) || caller.calls != 1 {
+		t.Fatalf("text call context/calls = %v, %d", caller.seenErr, caller.calls)
+	}
+
+	if err := CallMCPToolOnServerContext(ctx, "aitable", "get_fields", nil); err == nil {
+		t.Fatal("cancelled print call unexpectedly succeeded")
+	}
+	if !errors.Is(caller.seenErr, context.Canceled) || caller.calls != 2 {
+		t.Fatalf("print call context/calls = %v, %d", caller.seenErr, caller.calls)
+	}
+
+	// Public context-aware wrappers intentionally accept nil for compatibility,
+	// but must normalize it before crossing the transport boundary.
+	if _, err := CallMCPToolTextOnServerContext(nil, "aitable", "get_fields", nil); err == nil {
+		t.Fatal("nil-context text call unexpectedly succeeded with a nil result")
+	}
+	if caller.seenErr != nil || caller.calls != 3 {
+		t.Fatalf("nil-context text call context/calls = %v, %d", caller.seenErr, caller.calls)
+	}
+	if _, err := CallMCPReadToolTextOnServerContext(nil, "aitable", "get_fields", nil); err == nil {
+		t.Fatal("nil-context read call unexpectedly succeeded with a nil result")
+	}
+	if caller.seenErr != nil || caller.calls != 4 {
+		t.Fatalf("nil-context read call context/calls = %v, %d", caller.seenErr, caller.calls)
+	}
+	if err := CallMCPToolOnServerContext(nil, "aitable", "get_fields", nil); err == nil {
+		t.Fatal("nil-context print call unexpectedly succeeded with a nil result")
+	}
+	if caller.seenErr != nil || caller.calls != 5 {
+		t.Fatalf("nil-context print call context/calls = %v, %d", caller.seenErr, caller.calls)
+	}
+}
+
 func TestCrossPlatformCoverageSharedDependenciesRoutingAndWrappers(t *testing.T) {
 	oldDeps := deps
 	deps = nil

internal/helpers/oa.go

@@ -10,7 +10,10 @@ import (
 	"strings"
 
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/cli"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract"
+	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/output"
 	"github.com/spf13/cobra"
 )
 
@@ -42,6 +45,283 @@ func oaFormValues(raw string) ([]map[string]string, error) {
 	return result, nil
 }
 
+func parseOAAttachmentFileInfos(raw string) ([]map[string]any, error) {
+	decoder := json.NewDecoder(strings.NewReader(raw))
+	decoder.UseNumber()
+	var items []map[string]any
+	if err := decoder.Decode(&items); err != nil {
+		return nil, fmt.Errorf("--file-infos JSON 解析失败: %w", err)
+	}
+	if err := rejectTrailingOAAttachmentJSON(decoder); err != nil {
+		return nil, err
+	}
+	if len(items) < 1 || len(items) > 10 {
+		return nil, fmt.Errorf("--file-infos 必须包含 1 至 10 个文件")
+	}
+
+	infos := make([]map[string]any, 0, len(items))
+	for index, item := range items {
+		for name := range item {
+			if name != "spaceId" && name != "fileId" {
+				return nil, fmt.Errorf("--file-infos 第 %d 项包含未知字段 %q", index+1, name)
+			}
+		}
+
+		spaceValue, ok := item["spaceId"]
+		if !ok {
+			return nil, fmt.Errorf("--file-infos 第 %d 项缺少 spaceId", index+1)
+		}
+		spaceID, ok := spaceValue.(json.Number)
+		if !ok {
+			return nil, fmt.Errorf("--file-infos 第 %d 项 spaceId 必须是数字", index+1)
+		}
+
+		fileValue, ok := item["fileId"]
+		if !ok {
+			return nil, fmt.Errorf("--file-infos 第 %d 项缺少 fileId", index+1)
+		}
+		fileID, ok := fileValue.(string)
+		if !ok {
+			return nil, fmt.Errorf("--file-infos 第 %d 项 fileId 必须是字符串", index+1)
+		}
+		fileID = strings.TrimSpace(fileID)
+		if fileID == "" {
+			return nil, fmt.Errorf("--file-infos 第 %d 项 fileId 不能为空", index+1)
+		}
+
+		infos = append(infos, map[string]any{"spaceId": spaceID, "fileId": fileID})
+	}
+	return infos, nil
+}
+
+func rejectTrailingOAAttachmentJSON(decoder *json.Decoder) error {
+	var extra any
+	if err := decoder.Decode(&extra); err != io.EOF {
+		if err == nil {
+			return fmt.Errorf("--file-infos JSON 包含多余内容")
+		}
+		return fmt.Errorf("--file-infos JSON 解析失败: %w", err)
+	}
+	return nil
+}
+
+func validateOAAttachmentFileInfos(cmd *cobra.Command, _ []string) error {
+	raw, _ := cmd.Flags().GetString("file-infos")
+	_, err := parseOAAttachmentFileInfos(raw)
+	return err
+}
+
+func validateOAPreviewFileIDs(cmd *cobra.Command, _ []string) error {
+	fileIDs, _ := cmd.Flags().GetStringSlice("file-ids")
+	if len(fileIDs) > 20 {
+		return fmt.Errorf("--file-ids 最多包含 20 个附件 ID")
+	}
+	for index, fileID := range fileIDs {
+		if strings.TrimSpace(fileID) == "" {
+			return fmt.Errorf("--file-ids 第 %d 项不能为空", index+1)
+		}
+	}
+	return nil
+}
+
+func callOAAttachmentResult(cmd *cobra.Command, tool string, args map[string]any) (output.CommandResult, error) {
+	data, err := CallMCPToolDataOnServer(cmd.Context(), "oa", tool, args)
+	if err != nil {
+		return nil, err
+	}
+	response, ok := data.(map[string]any)
+	if !ok {
+		return nil, apperrors.NewInternal(fmt.Sprintf("oa/%s 返回值不是 JSON 对象", tool))
+	}
+	result, ok := response["result"]
+	if !ok {
+		return nil, apperrors.NewInternal(fmt.Sprintf("oa/%s 返回值缺少 result", tool))
+	}
+	return output.Success(result), nil
+}
+
+func newOAAttachmentCommand() *cobra.Command {
+	attachmentCmd := &cobra.Command{
+		Use:   "attachment",
+		Short: "审批附件授权与下载链接",
+		RunE:  groupRunE,
+	}
+
+	downloadURLCmd := NewLeafCommand(LeafSpec{
+		Use:           "download-url",
+		Short:         "获取审批附件下载链接",
+		Example:       "  dws oa approval attachment download-url --instance-id <processInstanceId> --file-id <fileId>",
+		Server:        "oa",
+		Tool:          "get_attachment_download_url",
+		OutputRollout: output.RolloutUnifiedActive,
+		ResultCall:    callOAAttachmentResult,
+		Flags: []LeafFlag{
+			{Name: "instance-id", Usage: "审批实例 ID (必填)", Bind: "processInstanceId", Trim: true, Required: true, MarkRequired: true},
+			{Name: "file-id", Usage: "审批附件文件 ID (必填)", Bind: "fileId", Trim: true, Required: true, MarkRequired: true},
+			{Name: "with-comment-attachment", Usage: "是否包含评论中的附件", Kind: LeafBool, Bind: "withCommentAttachment"},
+		},
+		Safety: contract.SafetySpec{
+			Effect: "read", Risk: "low",
+			Confirmation: "not_required", Idempotency: "idempotent",
+		},
+		Contract: LeafContract{
+			Identity: contract.ToolIdentitySpec{
+				ProductID:      "oa",
+				Name:           "get_attachment_download_url",
+				CanonicalPath:  "oa.get_attachment_download_url",
+				CLIPath:        "oa approval attachment download-url",
+				PrimaryCLIPath: "oa approval attachment download-url",
+			},
+			Description: "获取审批附件下载授权并生成临时下载链接",
+			Result: &contract.ResultSpec{
+				Outcomes:       []contract.ResultOutcome{contract.ResultOutcomeSuccess, contract.ResultOutcomeFailure},
+				DataSchema:     json.RawMessage(`{"type":"object","description":"审批附件临时下载信息","properties":{"spaceId":{"type":"integer","description":"审批附件所在钉盘空间 ID"},"agentId":{"type":"integer","description":"审批应用 Agent ID"},"downloadUri":{"type":"string","description":"带临时授权签名的附件下载链接"},"class":{"type":"string","description":"服务端响应类型标识"},"fileId":{"type":"string","description":"审批附件文件 ID"}},"required":["spaceId","agentId","downloadUri","fileId"],"additionalProperties":true}`),
+				SensitivePaths: []string{"downloadUri"},
+			},
+			Interface: &contract.InterfaceSpec{
+				Mode:         "mcp",
+				Availability: "available",
+				Ref:          &contract.InterfaceRefSpec{ProductID: "oa", RPCName: "get_attachment_download_url"},
+			},
+			Selection: contract.SelectionSpec{
+				AgentSummary: "获取审批实例中指定附件的临时下载链接",
+				UseWhen:      []string{"已从审批详情获得 processInstanceId 和 fileId，需要获取附件下载链接时"},
+				AvoidWhen: []string{
+					"只需查看审批表单和附件元数据时使用 dws oa approval detail",
+					"需要将附件真正保存到本地时不要误认为本命令会下载文件；它只返回链接",
+				},
+				Examples: []string{"dws oa approval attachment download-url --instance-id <processInstanceId> --file-id <fileId>"},
+			},
+			Parameters: []contract.ParamDecl{
+				{Name: "instance-id", Property: "processInstanceId", InterfaceType: "string"},
+				{Name: "file-id", Property: "fileId", InterfaceType: "string"},
+				{Name: "with-comment-attachment", Property: "withCommentAttachment", InterfaceType: "boolean"},
+			},
+		},
+	})
+
+	authorizeDownloadCmd := NewLeafCommand(LeafSpec{
+		Use:           "authorize-download",
+		Short:         "授权当前用户下载审批钉盘文件",
+		Long:          "批量授权当前用户下载指定的审批钉盘文件。",
+		Example:       `  dws oa approval attachment authorize-download --file-infos '[{"spaceId":27827223951,"fileId":"232271651278"}]'`,
+		Server:        "oa",
+		Tool:          "auth_download_file",
+		OutputRollout: output.RolloutUnifiedActive,
+		ResultCall:    callOAAttachmentResult,
+		Flags: []LeafFlag{
+			{
+				Name: "file-infos", Usage: "审批钉盘文件信息 JSON 数组 (必填)",
+				Bind: "fileInfos", Trim: true, Required: true, MarkRequired: true,
+				Transform: func(raw string) (any, error) {
+					return parseOAAttachmentFileInfos(raw)
+				},
+			},
+		},
+		Constraints: []LeafConstraint{{
+			Kind: corecmd.Custom, Flags: []string{"file-infos"},
+			Description: "文件信息列表必须包含 1 至 10 项",
+		}},
+		Validate: validateOAAttachmentFileInfos,
+		Safety: contract.SafetySpec{
+			Effect: "write", Risk: "low",
+			Confirmation: "not_required", Idempotency: "idempotent",
+		},
+		Contract: LeafContract{
+			Identity: contract.ToolIdentitySpec{
+				ProductID:      "oa",
+				Name:           "auth_download_file",
+				CanonicalPath:  "oa.auth_download_file",
+				CLIPath:        "oa approval attachment authorize-download",
+				PrimaryCLIPath: "oa approval attachment authorize-download",
+			},
+			Description: "批量授权当前用户下载指定的审批钉盘文件",
+			Result: &contract.ResultSpec{
+				Outcomes:   []contract.ResultOutcome{contract.ResultOutcomeSuccess, contract.ResultOutcomeFailure},
+				DataSchema: json.RawMessage(`{"type":"boolean","description":"是否成功为当前用户授予审批钉盘文件下载权限"}`),
+			},
+			Interface: &contract.InterfaceSpec{
+				Mode:         "mcp",
+				Availability: "available",
+				Ref:          &contract.InterfaceRefSpec{ProductID: "oa", RPCName: "auth_download_file"},
+			},
+			Selection: contract.SelectionSpec{
+				AgentSummary: "使用审批钉盘 spaceId/fileId 批量授权当前用户下载文件",
+				UseWhen:      []string{"已有一个或多个审批钉盘文件的 spaceId 和 fileId，需要为当前用户取得下载权限时"},
+				AvoidWhen: []string{
+					"需要生成单个审批附件下载链接时使用 attachment download-url",
+					"需要授权在审批单内预览附件时使用 attachment authorize-preview",
+				},
+				Examples: []string{`dws oa approval attachment authorize-download --file-infos '[{"spaceId":27827223951,"fileId":"232271651278"}]'`},
+			},
+			Parameters: []contract.ParamDecl{
+				{Name: "file-infos", Property: "fileInfos", InterfaceType: "array"},
+			},
+		},
+	})
+
+	authorizePreviewCmd := NewLeafCommand(LeafSpec{
+		Use:           "authorize-preview",
+		Short:         "授权当前用户预览审批附件",
+		Long:          "批量授权当前用户预览审批单中的附件。",
+		Example:       "  dws oa approval attachment authorize-preview --instance-id <processInstanceId> --file-ids <fileId1>,<fileId2>",
+		Server:        "oa",
+		Tool:          "auth_preview_attachment",
+		OutputRollout: output.RolloutUnifiedActive,
+		ResultCall:    callOAAttachmentResult,
+		Flags: []LeafFlag{
+			{Name: "instance-id", Usage: "审批实例 ID (必填)", Bind: "processInstanceId", Trim: true, Required: true, MarkRequired: true},
+			{Name: "file-ids", Usage: "附件 ID 列表，多个用逗号分隔 (必填)", Kind: LeafStringSlice, Bind: "fileIdList", Required: true, MarkRequired: true},
+			{Name: "with-comment-attachment", Usage: "是否包含评论中的附件", Kind: LeafBool, Bind: "withCommentAttachment"},
+		},
+		Constraints: []LeafConstraint{{
+			Kind: corecmd.Custom, Flags: []string{"file-ids"},
+			Description: "附件 ID 列表最多包含 20 项且每项不能为空",
+		}},
+		Validate: validateOAPreviewFileIDs,
+		Safety: contract.SafetySpec{
+			Effect: "write", Risk: "low",
+			Confirmation: "not_required", Idempotency: "idempotent",
+		},
+		Contract: LeafContract{
+			Identity: contract.ToolIdentitySpec{
+				ProductID:      "oa",
+				Name:           "auth_preview_attachment",
+				CanonicalPath:  "oa.auth_preview_attachment",
+				CLIPath:        "oa approval attachment authorize-preview",
+				PrimaryCLIPath: "oa approval attachment authorize-preview",
+			},
+			Description: "批量授权当前用户预览审批单中的附件",
+			Result: &contract.ResultSpec{
+				Outcomes:   []contract.ResultOutcome{contract.ResultOutcomeSuccess, contract.ResultOutcomeFailure},
+				DataSchema: json.RawMessage(`{"type":"object","description":"审批附件预览授权信息","properties":{"spaceId":{"type":"integer","description":"审批附件所在钉盘空间 ID"},"agentId":{"type":"integer","description":"审批应用 Agent ID"},"class":{"type":"string","description":"服务端响应类型标识"}},"required":["spaceId","agentId"],"additionalProperties":true}`),
+			},
+			Interface: &contract.InterfaceSpec{
+				Mode:         "mcp",
+				Availability: "available",
+				Ref:          &contract.InterfaceRefSpec{ProductID: "oa", RPCName: "auth_preview_attachment"},
+			},
+			Selection: contract.SelectionSpec{
+				AgentSummary: "按审批实例和附件 ID 列表授权当前用户预览附件",
+				UseWhen:      []string{"已有 processInstanceId 和附件 fileId 列表，需要在审批场景中批量取得预览权限时"},
+				AvoidWhen: []string{
+					"需要下载权限而不是预览权限时使用 attachment authorize-download",
+					"需要直接获得单个附件临时下载链接时使用 attachment download-url",
+				},
+				Examples: []string{"dws oa approval attachment authorize-preview --instance-id <processInstanceId> --file-ids <fileId1>,<fileId2>"},
+			},
+			Parameters: []contract.ParamDecl{
+				{Name: "instance-id", Property: "processInstanceId", InterfaceType: "string"},
+				{Name: "file-ids", Property: "fileIdList", InterfaceType: "array"},
+				{Name: "with-comment-attachment", Property: "withCommentAttachment", InterfaceType: "boolean"},
+			},
+		},
+	})
+
+	attachmentCmd.AddCommand(downloadURLCmd, authorizeDownloadCmd, authorizePreviewCmd)
+	return attachmentCmd
+}
+
 // ──────────────────────────────────────────────────────────
 // dws oa — OA 审批
 // MCP tools（tools/list）: list_pending_approvals, get_processInstance_detail,
@@ -49,7 +329,8 @@ func oaFormValues(raw string) ([]map[string]string, error) {
 // get_processInstance_records, list_initiated_instances, list_pending_tasks,
 // list_user_visible_process, append_task, search_form, oa_ding_user, revert_task,
 // get_inst_revert_activities, get_process_schema, forecast_process,
-// start_process_instance
+// start_process_instance, get_attachment_download_url, auth_download_file,
+// auth_preview_attachment
 // ──────────────────────────────────────────────────────────
 
 func newOaCommand() *cobra.Command {
@@ -58,9 +339,10 @@ func newOaCommand() *cobra.Command {
 	contract.RegisterProductDecl(contract.ProductDecl{
 		ID: "oa",
 		Selection: contract.ProductSelectionDecl{
-			AgentSummary: "查询和处理 OA 审批实例、任务、记录、抄送与评论",
+			AgentSummary: "查询和处理 OA 审批实例、任务、记录、抄送、评论与附件授权",
 			UseWhen: []string{
 				"查看待审、已办、已发起或抄送审批，并执行同意、拒绝、撤销、转交等审批动作时",
+				"获取审批附件下载链接，或为当前用户授权下载、预览审批附件时",
 			},
 			AvoidWhen: []string{
 				"不要用于普通待办任务或工作日志；需要实时监听未来的审批任务/实例事件时使用 event consume",
@@ -70,7 +352,7 @@ func newOaCommand() *cobra.Command {
 	root := &cobra.Command{
 		Use:   "oa",
 		Short: "OA 审批 / 同意 / 拒绝 / 撤销",
-		Long:  `管理钉钉 OA 审批：待办查询、审批详情、同意、拒绝、撤销、操作记录、已发起列表、表单列表。`,
+		Long:  `管理钉钉 OA 审批：待办查询、审批详情、同意、拒绝、撤销、操作记录、已发起列表、表单列表与附件授权。`,
 		RunE:  groupRunE,
 	}
 
@@ -1376,6 +1658,7 @@ func newOaCommand() *cobra.Command {
 		approvalForecastCmd,
 		approvalCreateCmd,
 	)
+	approvalCmd.AddCommand(newOAAttachmentCommand())
 	root.AddCommand(approvalCmd)
 
 	return root

internal/helpers/oa_attachment_test.go

@@ -0,0 +1,339 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+
+package helpers
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"io"
+	"os"
+	"reflect"
+	"strings"
+	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/output"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam"
+	"github.com/spf13/cobra"
+)
+
+func executeOAAttachmentCommandCapturingOutput(t *testing.T, caller *scriptedToolCaller, args ...string) (string, error) {
+	t.Helper()
+	testseam.Protect(t, &deps)
+	testseam.Swap(t, &os.Args, []string{"dws", "oa"})
+	InitDeps(caller)
+	var stdout bytes.Buffer
+	deps.Out.w = &stdout
+	deps.Out.errW = io.Discard
+
+	cmd := newOaCommand()
+	cmd.PersistentFlags().Bool("yes", false, "跳过确认")
+	cmd.PersistentFlags().String("format", caller.Format(), "输出格式")
+	ctx, _ := output.WithResultStore(context.Background())
+	cmd.SetContext(ctx)
+	cmd.PersistentPostRunE = func(executed *cobra.Command, _ []string) error {
+		_, _, err := output.EmitStoredResult(executed)
+		return err
+	}
+	cmd.SilenceErrors = true
+	cmd.SilenceUsage = true
+	cmd.SetOut(&stdout)
+	cmd.SetErr(io.Discard)
+	cmd.SetArgs(args)
+	err := cmd.Execute()
+	return stdout.String(), err
+}
+
+func TestCrossPlatformCoverageOAAttachmentDownloadURLPreservesSignedQuery(t *testing.T) {
+	const response = `{"result":{"downloadUri":"https://example.test/file?Expires=1&OSSAccessKeyId=2&Signature=3"},"success":true}`
+	commandArgs := []string{
+		"approval", "attachment", "download-url",
+		"--instance-id", "instance-1",
+		"--file-id", "file-1",
+	}
+	wantArgs := map[string]any{
+		"processInstanceId": "instance-1",
+		"fileId":            "file-1",
+	}
+
+	t.Run("json", func(t *testing.T) {
+		caller := &scriptedToolCaller{format: "json", steps: []scriptedToolStep{{text: response}}}
+		stdout, err := executeOAAttachmentCommandCapturingOutput(t, caller, commandArgs...)
+		if err != nil {
+			t.Fatalf("execute command: %v", err)
+		}
+		if caller.server != "oa" || caller.tool != "get_attachment_download_url" {
+			t.Fatalf("called %s/%s, want oa/get_attachment_download_url", caller.server, caller.tool)
+		}
+		if !reflect.DeepEqual(caller.args, wantArgs) {
+			t.Fatalf("args = %#v, want %#v", caller.args, wantArgs)
+		}
+		if !strings.Contains(stdout, "&OSSAccessKeyId=") || !strings.Contains(stdout, "&Signature=") {
+			t.Fatalf("stdout does not preserve signed query separators: %q", stdout)
+		}
+		if strings.Contains(stdout, `\u0026`) {
+			t.Fatalf("stdout contains escaped query separator: %q", stdout)
+		}
+		var envelope map[string]any
+		if err := json.Unmarshal([]byte(stdout), &envelope); err != nil {
+			t.Fatalf("decode unified output: %v", err)
+		}
+		if envelope["ok"] != true || envelope["outcome"] != "success" {
+			t.Fatalf("unified envelope = %#v", envelope)
+		}
+		data, ok := envelope["data"].(map[string]any)
+		if !ok || !strings.Contains(data["downloadUri"].(string), "&Signature=") {
+			t.Fatalf("unified data = %#v", envelope["data"])
+		}
+	})
+
+	t.Run("raw compatibility", func(t *testing.T) {
+		caller := &scriptedToolCaller{format: "raw", steps: []scriptedToolStep{{text: response}}}
+		stdout, err := executeOAAttachmentCommandCapturingOutput(t, caller, commandArgs...)
+		if err != nil {
+			t.Fatalf("execute command: %v", err)
+		}
+		const want = `{"downloadUri":"https://example.test/file?Expires=1&OSSAccessKeyId=2&Signature=3"}` + "\n"
+		if stdout != want {
+			t.Fatalf("stdout = %q, want %q", stdout, want)
+		}
+	})
+}
+
+func TestCrossPlatformCoverageOAAttachmentProjectsUnifiedBusinessData(t *testing.T) {
+	tests := []struct {
+		name     string
+		args     []string
+		response string
+		wantData any
+	}{
+		{
+			name:     "download authorization",
+			args:     []string{"approval", "attachment", "authorize-download", "--file-infos", `[{"spaceId":27827223951,"fileId":"file-1"}]`},
+			response: `{"result":true,"success":true,"dingOpenErrcode":0,"errorMsg":"ok"}`,
+			wantData: true,
+		},
+		{
+			name:     "preview authorization",
+			args:     []string{"approval", "attachment", "authorize-preview", "--instance-id", "instance-1", "--file-ids", "file-1"},
+			response: `{"result":{"spaceId":27827223951,"agentId":4115627346,"class":"com.dingtalk.bpms.oapi.vo.AppSpaceResponse"},"success":true,"dingOpenErrcode":0,"errorMsg":"ok"}`,
+			wantData: map[string]any{
+				"spaceId": float64(27827223951), "agentId": float64(4115627346),
+				"class": "com.dingtalk.bpms.oapi.vo.AppSpaceResponse",
+			},
+		},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			caller := &scriptedToolCaller{format: "json", steps: []scriptedToolStep{{text: test.response}}}
+			stdout, err := executeOAAttachmentCommandCapturingOutput(t, caller, test.args...)
+			if err != nil {
+				t.Fatalf("execute command: %v", err)
+			}
+			var envelope map[string]any
+			if err := json.Unmarshal([]byte(stdout), &envelope); err != nil {
+				t.Fatalf("decode unified output: %v", err)
+			}
+			if envelope["ok"] != true || envelope["outcome"] != "success" || !reflect.DeepEqual(envelope["data"], test.wantData) {
+				t.Fatalf("unified envelope = %#v, want data %#v", envelope, test.wantData)
+			}
+		})
+	}
+}
+
+func TestCrossPlatformCoverageOAAttachmentRejectsSuccessWithoutResult(t *testing.T) {
+	caller := &scriptedToolCaller{format: "json", steps: []scriptedToolStep{{text: `{"success":true,"dingOpenErrcode":0,"errorMsg":"ok"}`}}}
+	_, err := executeOAAttachmentCommandCapturingOutput(t, caller,
+		"approval", "attachment", "authorize-download",
+		"--file-infos", `[{"spaceId":27827223951,"fileId":"file-1"}]`,
+	)
+	if err == nil || !strings.Contains(err.Error(), "缺少 result") {
+		t.Fatalf("execute error = %v, want missing result", err)
+	}
+}
+
+func TestCrossPlatformCoverageOAAttachmentRejectsInvalidToolResult(t *testing.T) {
+	tests := []struct {
+		name string
+		step scriptedToolStep
+		want string
+	}{
+		{name: "non-object response", step: scriptedToolStep{text: `[]`}, want: "不是 JSON 对象"},
+		{name: "tool error", step: scriptedToolStep{err: errors.New("tool unavailable")}, want: "tool unavailable"},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			caller := &scriptedToolCaller{format: "json", steps: []scriptedToolStep{test.step}}
+			_, err := executeOAAttachmentCommandCapturingOutput(t, caller,
+				"approval", "attachment", "authorize-download",
+				"--file-infos", `[{"spaceId":27827223951,"fileId":"file-1"}]`,
+			)
+			if err == nil || !strings.Contains(err.Error(), test.want) {
+				t.Fatalf("execute error = %v, want %q", err, test.want)
+			}
+		})
+	}
+}
+
+func TestCrossPlatformCoverageOAAttachmentPayloads(t *testing.T) {
+	tests := []struct {
+		name     string
+		args     []string
+		wantTool string
+		check    func(*testing.T, map[string]any)
+	}{
+		{
+			name: "download URL",
+			args: []string{
+				"approval", "attachment", "download-url",
+				"--instance-id", "instance-1",
+				"--file-id", "file-1",
+				"--with-comment-attachment=false",
+			},
+			wantTool: "get_attachment_download_url",
+			check: func(t *testing.T, got map[string]any) {
+				t.Helper()
+				if got["processInstanceId"] != "instance-1" || got["fileId"] != "file-1" {
+					t.Fatalf("download identifiers = %#v", got)
+				}
+				if value, ok := got["withCommentAttachment"].(bool); !ok || value {
+					t.Fatalf("withCommentAttachment = %#v, want explicit false", got["withCommentAttachment"])
+				}
+			},
+		},
+		{
+			name: "download authorization",
+			args: []string{
+				"approval", "attachment", "authorize-download",
+				"--file-infos", `[{"spaceId":27827223951,"fileId":"file-2"}]`,
+			},
+			wantTool: "auth_download_file",
+			check: func(t *testing.T, got map[string]any) {
+				t.Helper()
+				infos, ok := got["fileInfos"].([]map[string]any)
+				if !ok || len(infos) != 1 {
+					t.Fatalf("fileInfos = %#v", got["fileInfos"])
+				}
+				if infos[0]["spaceId"] != json.Number("27827223951") || infos[0]["fileId"] != "file-2" {
+					t.Fatalf("fileInfos[0] = %#v", infos[0])
+				}
+			},
+		},
+		{
+			name: "preview authorization",
+			args: []string{
+				"approval", "attachment", "authorize-preview",
+				"--instance-id", "instance-2",
+				"--file-ids", "file-3,file-4",
+				"--with-comment-attachment",
+			},
+			wantTool: "auth_preview_attachment",
+			check: func(t *testing.T, got map[string]any) {
+				t.Helper()
+				if got["processInstanceId"] != "instance-2" || got["withCommentAttachment"] != true {
+					t.Fatalf("preview scalar payload = %#v", got)
+				}
+				ids, ok := got["fileIdList"].([]string)
+				if !ok || len(ids) != 2 || ids[0] != "file-3" || ids[1] != "file-4" {
+					t.Fatalf("fileIdList = %#v", got["fileIdList"])
+				}
+			},
+		},
+		{
+			name: "optional boolean omitted",
+			args: []string{
+				"approval", "attachment", "download-url",
+				"--instance-id", "instance-3",
+				"--file-id", "file-5",
+			},
+			wantTool: "get_attachment_download_url",
+			check: func(t *testing.T, got map[string]any) {
+				t.Helper()
+				if _, exists := got["withCommentAttachment"]; exists {
+					t.Fatalf("optional withCommentAttachment should be omitted: %#v", got)
+				}
+			},
+		},
+	}
+
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			caller := &scriptedToolCaller{steps: []scriptedToolStep{{text: `{"result":{},"success":true}`}}}
+			if _, err := executeOAAttachmentCommandCapturingOutput(t, caller, test.args...); err != nil {
+				t.Fatalf("execute command: %v", err)
+			}
+			if caller.server != "oa" || caller.tool != test.wantTool {
+				t.Fatalf("called %s/%s, want oa/%s", caller.server, caller.tool, test.wantTool)
+			}
+			test.check(t, caller.args)
+		})
+	}
+}
+
+func TestCrossPlatformCoverageOAAttachmentRejectsInvalidFileInfos(t *testing.T) {
+	valid := `{"spaceId":27827223951,"fileId":"file-1"}`
+	tests := []struct {
+		name string
+		raw  string
+	}{
+		{name: "malformed JSON", raw: `[{`},
+		{name: "null", raw: `null`},
+		{name: "not array", raw: `{}`},
+		{name: "empty array", raw: `[]`},
+		{name: "more than ten", raw: `[` + strings.Repeat(valid+`,`, 10) + valid + `]`},
+		{name: "missing space ID", raw: `[{"fileId":"file-1"}]`},
+		{name: "string space ID", raw: `[{"spaceId":"27827223951","fileId":"file-1"}]`},
+		{name: "missing file ID", raw: `[{"spaceId":27827223951}]`},
+		{name: "numeric file ID", raw: `[{"spaceId":27827223951,"fileId":232271651278}]`},
+		{name: "blank file ID", raw: `[{"spaceId":27827223951,"fileId":"  "}]`},
+		{name: "unknown property", raw: `[{"spaceId":27827223951,"fileId":"file-1","extra":true}]`},
+		{name: "trailing JSON", raw: `[` + valid + `] {}`},
+		{name: "malformed trailing JSON", raw: `[` + valid + `] {`},
+	}
+
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			caller := &scriptedToolCaller{}
+			err := executeOACommand(t, caller,
+				"approval", "attachment", "authorize-download",
+				"--file-infos", test.raw,
+			)
+			if err == nil {
+				t.Fatalf("fileInfos %q unexpectedly succeeded", test.raw)
+			}
+			if caller.calls != 0 {
+				t.Fatalf("invalid fileInfos made %d MCP call(s)", caller.calls)
+			}
+		})
+	}
+}
+
+func TestCrossPlatformCoverageOAAttachmentRejectsInvalidPreviewFileIDs(t *testing.T) {
+	tests := []struct {
+		name string
+		raw  string
+	}{
+		{name: "separator only", raw: `,`},
+		{name: "blank item", raw: `file-1, ,file-2`},
+		{name: "more than twenty", raw: strings.Repeat("file,", 20) + "file"},
+	}
+
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			caller := &scriptedToolCaller{}
+			err := executeOACommand(t, caller,
+				"approval", "attachment", "authorize-preview",
+				"--instance-id", "instance-1",
+				"--file-ids", test.raw,
+			)
+			if err == nil {
+				t.Fatalf("file IDs %q unexpectedly succeeded", test.raw)
+			}
+			if caller.calls != 0 {
+				t.Fatalf("invalid file IDs made %d MCP call(s)", caller.calls)
+			}
+		})
+	}
+}

internal/helpers/primary_param_native_compat_test.go

@@ -0,0 +1,499 @@
+// 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"
+	"encoding/json"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/runtimeannotate"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition"
+	"github.com/spf13/cobra"
+)
+
+type nativePrimaryParamCall struct {
+	server string
+	tool   string
+	args   map[string]any
+}
+
+type nativePrimaryParamCaller struct {
+	calls []nativePrimaryParamCall
+}
+
+func (c *nativePrimaryParamCaller) CallTool(_ context.Context, server, tool string, args map[string]any) (*edition.ToolResult, error) {
+	copied := make(map[string]any, len(args))
+	for key, value := range args {
+		copied[key] = value
+	}
+	c.calls = append(c.calls, nativePrimaryParamCall{server: server, tool: tool, args: copied})
+
+	switch tool {
+	case "init_conversation_file_upload", "init_todo_file_upload":
+		return textToolResult(`{"resourceUrl":"https://upload.invalid/file","uploadKey":"upload-key"}`), nil
+	case "commit_conversation_file_upload":
+		fileName, _ := args["fileName"].(string)
+		payload, _ := json.Marshal(map[string]any{
+			"dentryId":    123,
+			"spaceId":     456,
+			"downloadUrl": "https://download.invalid/" + fileName,
+		})
+		return textToolResult(string(payload)), nil
+	case "commit_todo_file_upload":
+		return textToolResult(`{"dentryId":123,"spaceId":456}`), nil
+	default:
+		return textToolResult(`{}`), nil
+	}
+}
+
+func (*nativePrimaryParamCaller) Format() string { return "json" }
+func (*nativePrimaryParamCaller) DryRun() bool   { return false }
+func (*nativePrimaryParamCaller) Fields() string { return "" }
+func (*nativePrimaryParamCaller) JQ() string     { return "" }
+
+func (c *nativePrimaryParamCaller) lastCall(t *testing.T, tool string) nativePrimaryParamCall {
+	t.Helper()
+	for i := len(c.calls) - 1; i >= 0; i-- {
+		if c.calls[i].tool == tool {
+			return c.calls[i]
+		}
+	}
+	t.Fatalf("tool %q not called; calls = %#v", tool, c.calls)
+	return nativePrimaryParamCall{}
+}
+
+func executeNativePrimaryTodo(t *testing.T, caller edition.ToolCaller, args ...string) error {
+	t.Helper()
+	previousDeps, previousArgs := deps, os.Args
+	os.Args = []string{"dws", "todo"}
+	InitDeps(caller)
+	deps.Out.w = io.Discard
+	deps.Out.errW = io.Discard
+	t.Cleanup(func() {
+		deps = previousDeps
+		os.Args = previousArgs
+	})
+
+	cmd := newTodoCommand()
+	if cmd.PersistentFlags().Lookup("yes") == nil {
+		cmd.PersistentFlags().Bool("yes", false, "confirm execution")
+	}
+	if cmd.PersistentFlags().Lookup("dry-run") == nil {
+		cmd.PersistentFlags().Bool("dry-run", false, "preview without executing")
+	}
+	cmd.SilenceErrors = true
+	cmd.SilenceUsage = true
+	cmd.SetOut(io.Discard)
+	cmd.SetErr(io.Discard)
+	cmd.SetArgs(args)
+	return cmd.ExecuteContext(context.Background())
+}
+
+func findNativePrimaryLeaf(t *testing.T, root *cobra.Command, path ...string) *cobra.Command {
+	t.Helper()
+	leaf, remaining, err := root.Find(path)
+	if err != nil {
+		t.Fatalf("find %v: %v", path, err)
+	}
+	if len(remaining) != 0 {
+		t.Fatalf("find %v left arguments %v", path, remaining)
+	}
+	return leaf
+}
+
+func assertNativePrimaryFlagPair(t *testing.T, cmd *cobra.Command, primary, legacy string) {
+	t.Helper()
+	primaryFlag := cmd.Flags().Lookup(primary)
+	if primaryFlag == nil || primaryFlag.Hidden {
+		t.Fatalf("%s --%s = %#v, want visible Primary", cmd.CommandPath(), primary, primaryFlag)
+	}
+	legacyFlag := cmd.Flags().Lookup(legacy)
+	if legacyFlag == nil || !legacyFlag.Hidden {
+		t.Fatalf("%s --%s = %#v, want hidden compatibility alias", cmd.CommandPath(), legacy, legacyFlag)
+	}
+	if got := legacyFlag.Annotations[runtimeannotate.AnnotationFlagAliasOf]; len(got) != 1 || got[0] != primary {
+		t.Fatalf("%s --%s alias_of = %#v, want %q", cmd.CommandPath(), legacy, got, primary)
+	}
+	if got := legacyFlag.Annotations[runtimeannotate.AnnotationFlagAliasOrigin]; len(got) != 1 || got[0] != runtimeannotate.FlagAliasOriginCorecmdV1 {
+		t.Fatalf("%s --%s alias_origin = %#v, want %q", cmd.CommandPath(), legacy, got, runtimeannotate.FlagAliasOriginCorecmdV1)
+	}
+}
+
+func TestNativePrimaryParamFlagSurfaces(t *testing.T) {
+	aisearch := newAisearchCommand()
+	assertNativePrimaryFlagPair(t, aisearch, "query", "keyword")
+	person := findNativePrimaryLeaf(t, aisearch, "person")
+	assertNativePrimaryFlagPair(t, person, "query", "keyword")
+	for _, cmd := range []*cobra.Command{aisearch, person} {
+		if got := cmd.Flags().Lookup("keyword").Shorthand; got != "w" {
+			t.Fatalf("%s --keyword shorthand = %q, want preserved -w", cmd.CommandPath(), got)
+		}
+		if got := cmd.Flags().Lookup("query").Shorthand; got != "" {
+			t.Fatalf("%s --query shorthand = %q, want none", cmd.CommandPath(), got)
+		}
+	}
+
+	chat := newChatCommand()
+	send := findNativePrimaryLeaf(t, chat, "message", "send")
+	assertNativePrimaryFlagPair(t, send, "content", "text")
+	assertNativePrimaryFlagPair(t, send, "file", "file-path")
+	sendByWebhook := findNativePrimaryLeaf(t, chat, "message", "send-by-webhook")
+	assertNativePrimaryFlagPair(t, sendByWebhook, "content", "text")
+	sendByBot := findNativePrimaryLeaf(t, chat, "message", "send-by-bot")
+	for _, name := range []string{"text", "file-path"} {
+		flag := sendByBot.Flags().Lookup(name)
+		if flag == nil || flag.Hidden {
+			t.Fatalf("%s --%s = %#v, want unchanged visible Primary", sendByBot.CommandPath(), name, flag)
+		}
+	}
+	for _, name := range []string{"content", "file"} {
+		if flag := sendByBot.Flags().Lookup(name); flag != nil && !flag.Hidden {
+			t.Fatalf("%s --%s = %#v, pending migration must not become visible", sendByBot.CommandPath(), name, flag)
+		}
+	}
+	reply := findNativePrimaryLeaf(t, chat, "message", "reply")
+	assertNativePrimaryFlagPair(t, reply, "group", "conversation-id")
+	assertNativePrimaryFlagPair(t, reply, "content", "text")
+
+	doc := newDocCommand()
+	assertNativePrimaryFlagPair(t, findNativePrimaryLeaf(t, doc, "block", "insert"), "content", "text")
+	assertNativePrimaryFlagPair(t, findNativePrimaryLeaf(t, doc, "block", "update"), "content", "text")
+
+	todo := newTodoCommand()
+	assertNativePrimaryFlagPair(t, findNativePrimaryLeaf(t, todo, "task", "add-attachment"), "file", "file-path")
+}
+
+type nativePrimaryParamSpelling struct {
+	name string
+	args []string
+	want string
+}
+
+func nativePrimaryParamSpellings(primary, legacy string) []nativePrimaryParamSpelling {
+	return []nativePrimaryParamSpelling{
+		{name: "legacy only", args: []string{"--" + legacy, "legacy-value"}, want: "legacy-value"},
+		{name: "primary only", args: []string{"--" + primary, "primary-value"}, want: "primary-value"},
+		{name: "both legacy wins", args: []string{"--" + primary, "primary-value", "--" + legacy, "legacy-value"}, want: "legacy-value"},
+	}
+}
+
+func nativePrimaryJSONField(t *testing.T, raw any, field string) string {
+	t.Helper()
+	encoded, ok := raw.(string)
+	if !ok {
+		t.Fatalf("payload = %#v, want JSON string", raw)
+	}
+	var payload map[string]any
+	if err := json.Unmarshal([]byte(encoded), &payload); err != nil {
+		t.Fatalf("decode payload %q: %v", encoded, err)
+	}
+	value, _ := payload[field].(string)
+	return value
+}
+
+func nativePrimaryParagraphText(t *testing.T, call nativePrimaryParamCall) string {
+	t.Helper()
+	element, ok := call.args["element"].(map[string]any)
+	if !ok {
+		t.Fatalf("%s element = %#v", call.tool, call.args["element"])
+	}
+	paragraph, ok := element["paragraph"].(map[string]any)
+	if !ok {
+		t.Fatalf("%s paragraph = %#v", call.tool, element["paragraph"])
+	}
+	text, _ := paragraph["text"].(string)
+	return text
+}
+
+func TestNativePrimaryParamTextPayloadCompatibility(t *testing.T) {
+	previousDeps, previousArgs := deps, os.Args
+	os.Args = []string{"dws", "chat"}
+	t.Cleanup(func() {
+		deps = previousDeps
+		os.Args = previousArgs
+	})
+
+	t.Run("chat message send text to content", func(t *testing.T) {
+		for _, spelling := range nativePrimaryParamSpellings("content", "text") {
+			t.Run(spelling.name, func(t *testing.T) {
+				caller := &nativePrimaryParamCaller{}
+				args := []string{"message", "send", "--group", "cid", "--title", "fixed-title"}
+				args = append(args, spelling.args...)
+				if err := runChatCoverageCommand(t, caller, args...); err != nil {
+					t.Fatal(err)
+				}
+				call := caller.lastCall(t, "send_personal_message")
+				if got := nativePrimaryJSONField(t, call.args["content"], "text"); got != spelling.want {
+					t.Fatalf("content.text = %q, want %q; payload = %#v", got, spelling.want, call.args)
+				}
+			})
+		}
+	})
+
+	t.Run("chat message send-by-webhook text to content", func(t *testing.T) {
+		for _, spelling := range nativePrimaryParamSpellings("content", "text") {
+			t.Run(spelling.name, func(t *testing.T) {
+				caller := &nativePrimaryParamCaller{}
+				args := []string{"message", "send-by-webhook", "--token", "token", "--title", "fixed-title"}
+				args = append(args, spelling.args...)
+				if err := runChatCoverageCommand(t, caller, args...); err != nil {
+					t.Fatal(err)
+				}
+				call := caller.lastCall(t, "send_message_by_custom_robot")
+				if got, _ := call.args["text"].(string); got != spelling.want {
+					t.Fatalf("text = %q, want %q; payload = %#v", got, spelling.want, call.args)
+				}
+			})
+		}
+	})
+
+	t.Run("chat message reply conversation-id to group", func(t *testing.T) {
+		for _, spelling := range nativePrimaryParamSpellings("group", "conversation-id") {
+			t.Run(spelling.name, func(t *testing.T) {
+				caller := &nativePrimaryParamCaller{}
+				args := []string{"message", "reply", "--ref-msg-id", "mid", "--ref-sender", helperCurrentDOpenID, "--content", "fixed-content"}
+				args = append(args, spelling.args...)
+				if err := runChatCoverageCommand(t, caller, args...); err != nil {
+					t.Fatal(err)
+				}
+				call := caller.lastCall(t, "send_personal_message")
+				if got, _ := call.args["openConversationId"].(string); got != spelling.want {
+					t.Fatalf("openConversationId = %q, want %q; payload = %#v", got, spelling.want, call.args)
+				}
+			})
+		}
+	})
+
+	t.Run("chat message reply text to content", func(t *testing.T) {
+		for _, spelling := range nativePrimaryParamSpellings("content", "text") {
+			t.Run(spelling.name, func(t *testing.T) {
+				caller := &nativePrimaryParamCaller{}
+				args := []string{"message", "reply", "--group", "cid", "--ref-msg-id", "mid", "--ref-sender", helperCurrentDOpenID}
+				args = append(args, spelling.args...)
+				if err := runChatCoverageCommand(t, caller, args...); err != nil {
+					t.Fatal(err)
+				}
+				call := caller.lastCall(t, "send_personal_message")
+				if got := nativePrimaryJSONField(t, call.args["content"], "content"); got != spelling.want {
+					t.Fatalf("reply content = %q, want %q; payload = %#v", got, spelling.want, call.args)
+				}
+			})
+		}
+	})
+
+	for _, command := range []struct {
+		name string
+		path []string
+		tool string
+	}{
+		{name: "doc block insert text to content", path: []string{"block", "insert", "--node", "node"}, tool: "insert_document_block"},
+		{name: "doc block update text to content", path: []string{"block", "update", "--node", "node", "--block-id", "block"}, tool: "update_document_block"},
+	} {
+		command := command
+		t.Run(command.name, func(t *testing.T) {
+			for _, spelling := range nativePrimaryParamSpellings("content", "text") {
+				t.Run(spelling.name, func(t *testing.T) {
+					caller := &nativePrimaryParamCaller{}
+					args := append(append([]string(nil), command.path...), spelling.args...)
+					if err := runDocCoverageCommand(t, caller, args...); err != nil {
+						t.Fatal(err)
+					}
+					call := caller.lastCall(t, command.tool)
+					if got := nativePrimaryParagraphText(t, call); got != spelling.want {
+						t.Fatalf("paragraph text = %q, want %q; payload = %#v", got, spelling.want, call.args)
+					}
+				})
+			}
+		})
+	}
+}
+
+func TestNativePrimaryParamFilePayloadCompatibility(t *testing.T) {
+	previousDeps, previousPut, previousArgs := deps, httpPutFile, os.Args
+	t.Cleanup(func() {
+		deps = previousDeps
+		httpPutFile = previousPut
+		os.Args = previousArgs
+	})
+	httpPutFile = func(context.Context, string, map[string]string, string, int64) error { return nil }
+
+	dir := t.TempDir()
+	legacyPath := filepath.Join(dir, "legacy-file.txt")
+	primaryPath := filepath.Join(dir, "primary-file.txt")
+	if err := os.WriteFile(legacyPath, []byte("legacy"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(primaryPath, []byte("primary"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	spellings := []nativePrimaryParamSpelling{
+		{name: "legacy only", args: []string{"--file-path", legacyPath}, want: filepath.Base(legacyPath)},
+		{name: "primary only", args: []string{"--file", primaryPath}, want: filepath.Base(primaryPath)},
+		{name: "both legacy wins", args: []string{"--file", primaryPath, "--file-path", legacyPath}, want: filepath.Base(legacyPath)},
+	}
+
+	t.Run("chat message send file-path to file", func(t *testing.T) {
+		os.Args = []string{"dws", "chat"}
+		for _, spelling := range spellings {
+			t.Run(spelling.name, func(t *testing.T) {
+				caller := &nativePrimaryParamCaller{}
+				args := []string{"message", "send", "--group", "cid", "--msg-type", "file"}
+				args = append(args, spelling.args...)
+				if err := runChatCoverageCommand(t, caller, args...); err != nil {
+					t.Fatal(err)
+				}
+				call := caller.lastCall(t, "send_personal_message")
+				if got := nativePrimaryJSONField(t, call.args["content"], "fileName"); got != spelling.want {
+					t.Fatalf("fileName = %q, want %q; payload = %#v", got, spelling.want, call.args)
+				}
+			})
+		}
+	})
+
+	t.Run("todo task add-attachment file-path to file", func(t *testing.T) {
+		os.Args = []string{"dws", "todo"}
+		for _, spelling := range spellings {
+			t.Run(spelling.name, func(t *testing.T) {
+				caller := &nativePrimaryParamCaller{}
+				args := []string{"task", "add-attachment", "--task-id", "42"}
+				args = append(args, spelling.args...)
+				if err := executeNativePrimaryTodo(t, caller, args...); err != nil {
+					t.Fatal(err)
+				}
+				call := caller.lastCall(t, "add_todo_attachment")
+				request, ok := call.args["todoAttachmentAddRequest"].(map[string]any)
+				if !ok {
+					t.Fatalf("request = %#v", call.args)
+				}
+				attachments, ok := request["attachmentList"].([]any)
+				if !ok || len(attachments) != 1 {
+					t.Fatalf("attachments = %#v", request["attachmentList"])
+				}
+				attachment, ok := attachments[0].(map[string]any)
+				if !ok {
+					t.Fatalf("attachment = %#v", attachments[0])
+				}
+				if got, _ := attachment["fileName"].(string); got != spelling.want {
+					t.Fatalf("fileName = %q, want %q; payload = %#v", got, spelling.want, call.args)
+				}
+			})
+		}
+	})
+}
+
+func nativePrimaryErrorMentionsFlag(message, name string) bool {
+	return strings.Contains(message, "--"+name) || strings.Contains(message, fmt.Sprintf("%q", name))
+}
+
+func assertNativePrimaryErrorHint(t *testing.T, err error, primary, legacy string) {
+	t.Helper()
+	if err == nil {
+		t.Fatalf("missing --%s returned nil", primary)
+	}
+	message := err.Error()
+	if !nativePrimaryErrorMentionsFlag(message, primary) {
+		t.Fatalf("error %q does not recommend --%s", message, primary)
+	}
+	if nativePrimaryErrorMentionsFlag(message, legacy) {
+		t.Fatalf("error %q still recommends legacy --%s", message, legacy)
+	}
+}
+
+func TestNativePrimaryParamMissingErrorsRecommendPrimaryOnly(t *testing.T) {
+	previousDeps, previousArgs := deps, os.Args
+	t.Cleanup(func() {
+		deps = previousDeps
+		os.Args = previousArgs
+	})
+
+	installScriptedCaller(t, &scriptedToolCaller{})
+	assertNativePrimaryErrorHint(t, executeFilterCoverage(t, newAisearchCommand(), "person"), "query", "keyword")
+
+	os.Args = []string{"dws", "chat"}
+	assertNativePrimaryErrorHint(t,
+		runChatCoverageCommand(t, &nativePrimaryParamCaller{}, "message", "send", "--group", "cid"),
+		"content", "text")
+	assertNativePrimaryErrorHint(t,
+		runChatCoverageCommand(t, &nativePrimaryParamCaller{}, "message", "send-by-webhook", "--token", "token", "--title", "title"),
+		"content", "text")
+	assertNativePrimaryErrorHint(t,
+		runChatCoverageCommand(t, &nativePrimaryParamCaller{}, "message", "reply", "--ref-msg-id", "mid", "--ref-sender", helperCurrentDOpenID, "--content", "body"),
+		"group", "conversation-id")
+	assertNativePrimaryErrorHint(t,
+		runChatCoverageCommand(t, &nativePrimaryParamCaller{}, "message", "reply", "--group", "cid", "--ref-msg-id", "mid", "--ref-sender", helperCurrentDOpenID),
+		"content", "text")
+
+	os.Args = []string{"dws", "doc"}
+	assertNativePrimaryErrorHint(t,
+		runDocCoverageCommand(t, &nativePrimaryParamCaller{}, "block", "insert", "--node", "node"),
+		"content", "text")
+	assertNativePrimaryErrorHint(t,
+		runDocCoverageCommand(t, &nativePrimaryParamCaller{}, "block", "update", "--node", "node", "--block-id", "block"),
+		"content", "text")
+
+	os.Args = []string{"dws", "todo"}
+	assertNativePrimaryErrorHint(t,
+		executeTodoEdge(t, &scriptedToolCaller{}, "task", "add-attachment", "--task-id", "42"),
+		"file", "file-path")
+}
+
+func TestNativePrimaryParamPromotionErrorsPropagate(t *testing.T) {
+	chat := newChatCommand()
+	assertPromotionError := func(t *testing.T, err error) {
+		t.Helper()
+		if err == nil || !strings.Contains(err.Error(), "trying to get string value of flag of type bool") {
+			t.Fatalf("promotion error = %v", err)
+		}
+	}
+
+	t.Run("webhook RunE", func(t *testing.T) {
+		target := findNativePrimaryLeaf(t, chat, "message", "send-by-webhook")
+		cmd := &cobra.Command{}
+		cmd.Flags().String("content", "", "")
+		cmd.Flags().Bool("text", false, "")
+		if err := cmd.Flags().Set("text", "true"); err != nil {
+			t.Fatal(err)
+		}
+		assertPromotionError(t, target.RunE(cmd, nil))
+	})
+
+	reply := findNativePrimaryLeaf(t, chat, "message", "reply")
+	newInvalidGroupCommand := func(t *testing.T) *cobra.Command {
+		t.Helper()
+		cmd := &cobra.Command{}
+		cmd.Flags().String("group", "", "")
+		cmd.Flags().Bool("conversation-id", false, "")
+		if err := cmd.Flags().Set("conversation-id", "true"); err != nil {
+			t.Fatal(err)
+		}
+		return cmd
+	}
+
+	t.Run("reply PreRunE group", func(t *testing.T) {
+		assertPromotionError(t, reply.PreRunE(newInvalidGroupCommand(t), nil))
+	})
+
+	t.Run("reply RunE group", func(t *testing.T) {
+		assertPromotionError(t, reply.RunE(newInvalidGroupCommand(t), nil))
+	})
+
+	t.Run("reply RunE content", func(t *testing.T) {
+		cmd := &cobra.Command{}
+		cmd.Flags().String("group", "cid", "")
+		cmd.Flags().String("conversation-id", "", "")
+		cmd.Flags().String("content", "", "")
+		cmd.Flags().Bool("text", false, "")
+		if err := cmd.Flags().Set("text", "true"); err != nil {
+			t.Fatal(err)
+		}
+		assertPromotionError(t, reply.RunE(cmd, nil))
+	})
+}

internal/helpers/sheet_batch.go

@@ -60,6 +60,11 @@ func translateBatchOp(op map[string]any) (map[string]any, error) {
 	if !ok {
 		return nil, fmt.Errorf("unsupported toolName %q: must be a CLI command name (e.g. \"range clear\", \"range update\", \"merge-cells\"). Run 'dws sheet batch-update --help' for the full list", toolName)
 	}
+	if toolName == "set-dropdown" {
+		if err := validateBatchSetDropdownInput(input); err != nil {
+			return nil, err
+		}
+	}
 
 	return map[string]any{
 		"toolName": mapping.mcpTool,
@@ -67,6 +72,33 @@ func translateBatchOp(op map[string]any) (map[string]any, error) {
 	}, nil
 }
 
+func validateBatchSetDropdownInput(input map[string]any) error {
+	if _, exists := input["source-colors"]; exists {
+		return fmt.Errorf("set-dropdown: 顶层 source-colors 不受支持；Inline 颜色请写入 options[].color，SourceRange 颜色写入暂不支持")
+	}
+	if _, exists := input["colors"]; exists {
+		return fmt.Errorf("set-dropdown: 顶层 colors 不受支持；Inline 颜色请写入 options[].color，SourceRange 颜色写入暂不支持")
+	}
+
+	options, hasOptions := input["options"]
+	hasOptions = hasOptions && options != nil
+	sourceRange := batchStr(input, "source-range")
+	sourceSheetID := batchStr(input, "source-sheet-id")
+	hasSourceRange := sourceRange != ""
+	if hasOptions == hasSourceRange {
+		return fmt.Errorf("set-dropdown: options 与 source-range 必须且只能指定一个")
+	}
+	if hasSourceRange != (sourceSheetID != "") {
+		return fmt.Errorf("set-dropdown: source-range 与 source-sheet-id 必须同时指定")
+	}
+	if hasSourceRange {
+		if err := validateDropdownSourceRangeInput(sourceSheetID, sourceRange); err != nil {
+			return fmt.Errorf("set-dropdown: %w", err)
+		}
+	}
+	return nil
+}
+
 // ── BuildXxxArgs: CLI flag → MCP param 转换函数 ──────────────────────────────────
 // 每个函数接收 CLI flag 名（kebab-case）的 map，输出 MCP 参数名（camelCase）的 map。
 // 目前集中放在此文件；后续拆分命令文件时可移到各命令所在文件。
@@ -215,7 +247,15 @@ func BuildSetDropdownArgs(input map[string]any) map[string]any {
 	args := map[string]any{
 		"sheetId": batchStr(input, "sheet-id"),
 		"range":   batchStr(input, "range"),
-		"options": input["options"],
+	}
+	if options, ok := input["options"]; ok && options != nil {
+		args["options"] = options
+	}
+	if sourceRange := batchStr(input, "source-range"); sourceRange != "" {
+		args["sourceRange"] = map[string]any{
+			"sheetId":    batchStr(input, "source-sheet-id"),
+			"a1Notation": sourceRange,
+		}
 	}
 	if v, ok := input["multi-select"]; ok {
 		args["enableMultiSelect"] = v
@@ -417,6 +457,8 @@ func newBatchUpdateCmd() *cobra.Command {
 
 toolName 使用 CLI 命令名（与原子命令一致），input 的键用 CLI flag 名去掉 --。
 CLI 层自动翻译为 MCP toolName + 参数名，无需记忆 MCP 参数名。
+source-range 的语义按 toolName 隔离：set-dropdown 中表示下拉候选项来源，
+range fill/copy-to/move-to 中表示待填充、复制或移动的数据源区域。
 
 支持的 CLI 命令名:
   range clear / range update / merge-cells / unmerge-cells / update-dimension
@@ -425,6 +467,8 @@ CLI 层自动翻译为 MCP toolName + 参数名，无需记忆 MCP 参数名。
   set-dropdown / delete-dropdown / csv-put / delete-float-image
 其中 csv-put 与独立命令语义一致：CSV 字段值以 = 开头时按公式解析，
 前加单引号（例如 "'=1+1"）时写入以 = 开头的字面文本。
+set-dropdown 不接受顶层 colors/source-colors；Inline 颜色应写在 options[].color，
+SourceRange 颜色写入暂不支持。
 
 注意：batch-update 中 group-dimension 适合默认展开分组；需要 --group-state fold 时请使用独立
 dws sheet group-dimension 命令。

internal/helpers/sheet_batch_test.go

@@ -23,7 +23,15 @@ func TestCrossPlatformCoverageSheetBatchOperationTranslationCoversEveryMapping(t
 		"group-state": "fold",
 	}
 	for name, mapping := range batchOpDispatch {
-		got, err := translateBatchOp(map[string]any{"toolName": name, "input": input})
+		opInput := input
+		if name == "set-dropdown" {
+			opInput = make(map[string]any, len(input))
+			for key, value := range input {
+				opInput[key] = value
+			}
+			delete(opInput, "source-range")
+		}
+		got, err := translateBatchOp(map[string]any{"toolName": name, "input": opInput})
 		if err != nil {
 			t.Errorf("translateBatchOp(%q): %v", name, err)
 			continue

internal/helpers/sheet_comment.go

@@ -304,5 +304,6 @@ func newSheetCommentCmd() *cobra.Command {
 	}
 
 	commentCmd.AddCommand(commentListCmd, commentCreateCmd, commentReplyCmd, commentUpdateCmd, commentDeleteCmd)
+	commentCmd.AddCommand(newCommentBaseCommands("sheet")...)
 	return commentCmd
 }

internal/helpers/sheet_data.go

@@ -388,7 +388,10 @@ range update 与合并区域冲突时返回 MERGED_CELLS_CONFLICT 的行为。
   csv            带 [row=N] 行号前缀的 CSV 文本
   colIndices     列字母映射数组（定位列用 colIndices[j]，禁止手数逗号）
   rowIndices     行号映射数组
-  hasMore        是否因 maxChars 截断
+  hasMore        目标范围是否还有未返回数据
+  truncationReasons  部分返回原因：max_cells / max_chars
+  resolvedRange  未传 --range 时底层解析出的完整目标范围
+  returnedRange  本次实际完整返回的范围
 
 取值模式（--value-render-option）：
   formatted_value  格式化后的展示值（默认），如 ¥1,000.00、2025-06-01
@@ -398,9 +401,14 @@ range update 与合并区域冲突时返回 MERGED_CELLS_CONFLICT 的行为。
 与 range read 的区别：
   - CSV 格式 token 消耗约为 JSON 的 1/3
   - 支持选择取值模式
-  - 自动防爆（max-chars 截断 + has_more 标志）
+  - 自动防爆（30,000 单元格 / max-chars 上限 + hasMore 标志）
   - [row=N] 前缀防止行号计算错误
 
+当 hasMore=true 时本命令不会自动续读；请结合目标范围和
+returnedRange 从下一行显式传 --range。max_cells 不能通过增大
+--max-chars 解决。收到 forbidden.document.sizeOverLimit 表示工作簿整体
+无法装载，应创建更小副本或拆分工作簿，缩小 --range 不能解决。
+
 注意：csv-get 不返回合并单元格结构。查看合并范围请使用
 dws sheet info --node NODE_ID --sheet-id SHEET_ID --format json，并读取 mergedRanges。`,
 		Example: `  dws sheet csv-get --node NODE_ID

internal/helpers/sheet_dimension.go

@@ -6,6 +6,7 @@ import (
 	"strconv"
 	"strings"
 
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/cli"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract"
 	"github.com/spf13/cobra"
 )
@@ -18,6 +19,23 @@ func sizeTypeEnumHint(dimension string) string {
 	return "pixel / standard"
 }
 
+func validateDropdownSourceRangeInput(sourceSheetID, sourceRange string) error {
+	if strings.TrimSpace(sourceSheetID) == "" {
+		return fmt.Errorf("--source-sheet-id 不能为空")
+	}
+	sourceRange = strings.TrimSpace(sourceRange)
+	if sourceRange == "" {
+		return fmt.Errorf("--source-range 不能为空")
+	}
+	if strings.Contains(sourceRange, "!") {
+		return fmt.Errorf("--source-range 不能包含工作表前缀；请通过 --source-sheet-id 指定来源工作表")
+	}
+	if strings.HasPrefix(sourceRange, "=") || strings.Contains(sourceRange, ",") {
+		return fmt.Errorf("--source-range 必须是单一连续区域，不能是公式、表达式或多区域引用")
+	}
+	return nil
+}
+
 // newDimensionCmds creates dimension-related commands: insert/delete/update/move/add-dimension,
 // merge-cells, unmerge-cells, and dropdown commands (set/get/delete-dropdown).
 func newDimensionCmds() []*cobra.Command {
@@ -775,15 +793,24 @@ sheetId 支持传入工作表 ID 或工作表名称，可通过 sheet list 获
 		Short: "设置下拉列表",
 		Long: `在钉钉表格的指定单元格范围内设置下拉列表。
 
-设置后，用户可以在这些单元格中从预定义的选项列表中选择值。
-支持自定义每个选项的颜色和是否允许多选。
+Inline 模式通过 --options 提供静态选项，支持选项颜色。
+SourceRange 模式通过 --source-sheet-id + --source-range 引用同一工作簿内的来源区域，
+支持跨工作表、整行和整列引用；读取配置时不会展开来源区域的当前值或颜色。
+两种模式都支持 --multi-select，并且 --options 与 --source-range 必须且只能指定一个。
 如果目标范围已存在下拉列表，会被新的配置覆盖。
 
 nodeId 支持传入文档链接 URL 或文档 ID（dentryUuid），系统自动识别。
 sheetId 支持传入工作表 ID 或工作表名称，可通过 sheet list 获取。
 
 --options 为 JSON 数组，每个元素包含 value（必填）和 color（可选）。
-选项值不能包含英文逗号。`,
+选项值不能包含英文逗号。
+
+--source-range 只接受不含工作表前缀的 A1 区域，例如 T1:T3、T:T 或 1:3；
+来源工作表由 --source-sheet-id 单独指定。SourceRange 颜色写入暂不支持。
+
+已验证行为：工作表重命名、在引用前插入行/列、删除引用前的行会自动调整引用并保持 valid；
+已验证的 move-dimension 场景会使引用变为 invalid。列删除、删除整个来源区域或来源工作表等未覆盖场景不能预设结果；
+结构操作后应先回读 sourceRangeStatus，只有 invalid 时才重新选择来源并写入。`,
 		Example: `  # 设置单选下拉列表
   dws sheet set-dropdown --node NODE_ID --sheet-id SHEET_ID --range "A2:A100" \
     --options '[{"value":"选项1"},{"value":"选项2"},{"value":"选项3"}]'
@@ -793,32 +820,63 @@ sheetId 支持传入工作表 ID 或工作表名称，可通过 sheet list 获
     --options '[{"value":"高","color":"#ff0000"},{"value":"中","color":"#ffaa00"},{"value":"低","color":"#00ff00"}]' \
     --multi-select
 
+  # 引用同一工作簿内另一工作表的区域作为候选项来源
+  dws sheet set-dropdown --node NODE_ID --sheet-id TARGET_SHEET_ID --range "C2:C100" \
+    --source-sheet-id SOURCE_SHEET_ID --source-range "T1:T3"
+
   # 使用文档链接 URL
   dws sheet set-dropdown --node "https://alidocs.dingtalk.com/i/nodes/<DOC_UUID>" \
     --sheet-id SHEET_ID --range "C1:C10" --options '[{"value":"是"},{"value":"否"}]'`,
 		RunE: func(cmd *cobra.Command, args []string) error {
+			if err := validateRequiredFlags(cmd, "node", "sheet-id", "range"); err != nil {
+				return err
+			}
 			optionsStr := mustGetFlag(cmd, "options")
-			var options []map[string]any
-			if err := json.Unmarshal([]byte(optionsStr), &options); err != nil {
-				return fmt.Errorf("--options JSON 解析失败: %w", err)
+			sourceSheetID := mustGetFlag(cmd, "source-sheet-id")
+			sourceRange := mustGetFlag(cmd, "source-range")
+			hasOptions := optionsStr != ""
+			hasSourceRange := sourceRange != ""
+			if hasOptions == hasSourceRange {
+				return fmt.Errorf("--options 与 --source-range 必须且只能指定一个")
 			}
-			if len(options) == 0 {
-				return fmt.Errorf("--options 至少包含 1 个选项")
+			if hasSourceRange && sourceSheetID == "" {
+				return fmt.Errorf("使用 --source-range 时必须同时指定 --source-sheet-id")
 			}
-			for i, opt := range options {
-				val, ok := opt["value"].(string)
-				if !ok || val == "" {
-					return fmt.Errorf("--options[%d] 缺少必填的 value 字段或 value 为空", i)
-				}
-				if strings.Contains(val, ",") {
-					return fmt.Errorf("--options[%d].value 不能包含英文逗号: %q", i, val)
-				}
+			if !hasSourceRange && sourceSheetID != "" {
+				return fmt.Errorf("使用 --source-sheet-id 时必须同时指定 --source-range")
 			}
+
 			toolArgs := map[string]any{
 				"nodeId":  mustGetFlag(cmd, "node"),
 				"sheetId": mustGetFlag(cmd, "sheet-id"),
 				"range":   mustGetFlag(cmd, "range"),
-				"options": options,
+			}
+			if hasOptions {
+				var options []map[string]any
+				if err := json.Unmarshal([]byte(optionsStr), &options); err != nil {
+					return fmt.Errorf("--options JSON 解析失败: %w", err)
+				}
+				if len(options) == 0 {
+					return fmt.Errorf("--options 至少包含 1 个选项")
+				}
+				for i, opt := range options {
+					val, ok := opt["value"].(string)
+					if !ok || val == "" {
+						return fmt.Errorf("--options[%d] 缺少必填的 value 字段或 value 为空", i)
+					}
+					if strings.Contains(val, ",") {
+						return fmt.Errorf("--options[%d].value 不能包含英文逗号: %q", i, val)
+					}
+				}
+				toolArgs["options"] = options
+			} else {
+				if err := validateDropdownSourceRangeInput(sourceSheetID, sourceRange); err != nil {
+					return err
+				}
+				toolArgs["sourceRange"] = map[string]any{
+					"sheetId":    sourceSheetID,
+					"a1Notation": sourceRange,
+				}
 			}
 			if multiSelect, _ := cmd.Flags().GetBool("multi-select"); multiSelect {
 				toolArgs["enableMultiSelect"] = true
@@ -839,36 +897,49 @@ sheetId 支持传入工作表 ID 或工作表名称，可通过 sheet list 获
 				CLIPath:        "sheet set-dropdown",
 				PrimaryCLIPath: "sheet set-dropdown",
 			},
-			Description: "为指定范围设置下拉列表（可多选、可带颜色）。",
+			Description: "为指定范围设置 Inline 或 SourceRange 下拉列表（可多选；颜色仅 Inline 支持）。",
 			Interface: &contract.InterfaceSpec{
 				Mode:         "mcp",
 				Availability: "available",
 				Ref:          &contract.InterfaceRefSpec{ProductID: "sheet", RPCName: "set_dropdown_lists"},
 			},
 			Selection: contract.SelectionSpec{
-				AgentSummary: "为指定范围设置下拉列表（可多选、可带颜色）。",
+				AgentSummary: "为指定范围设置 Inline 或 SourceRange 下拉列表；SourceRange 可跨同一工作簿内的工作表。",
 				UseWhen:      []string{"需要给单元格配置可选值下拉约束时"},
 				AvoidWhen:    []string{"查看已有下拉用 get-dropdown；移除下拉用 delete-dropdown"},
-				Examples:     []string{"dws sheet set-dropdown --node <NODE_ID> --sheet-id <SHEET_ID> --range \"A2:A100\" --options '[{\"value\":\"选项1\"},{\"value\":\"选项2\"}]'"},
+				Examples: []string{
+					"dws sheet set-dropdown --node <NODE_ID> --sheet-id <SHEET_ID> --range \"A2:A100\" --options '[{\"value\":\"选项1\"},{\"value\":\"选项2\"}]'",
+					"dws sheet set-dropdown --node <NODE_ID> --sheet-id <TARGET_SHEET_ID> --range \"B2:B100\" --source-sheet-id <SOURCE_SHEET_ID> --source-range \"T1:T3\"",
+				},
 			},
 			Parameters: []contract.ParamDecl{
 				{Name: "multi-select", Property: "enableMultiSelect"},
 				{Name: "node", Property: "nodeId"},
+				{Name: "source-sheet-id", Property: "sourceRange.sheetId", Required: boolPtr(false), RequiredWhen: "--source-range is provided"},
+				{Name: "source-range", Property: "sourceRange.a1Notation", Required: boolPtr(false), RequiredWhen: "exactly one of --options or --source-range must be provided"},
 			},
 		},
 	})
 	setDropdownCmd.Flags().String("node", "", "表格文档 ID 或 URL (必填)")
 	setDropdownCmd.Flags().String("sheet-id", "", "工作表 ID 或名称 (必填)")
 	setDropdownCmd.Flags().String("range", "", "目标单元格范围，A1 表示法，如 A2:A100 (必填)")
-	setDropdownCmd.Flags().String("options", "", `下拉选项 JSON 数组 (必填)，如 '[{"value":"选项1","color":"#ff0000"}]'`)
+	setDropdownCmd.Flags().String("options", "", `Inline 下拉选项 JSON 数组，与 --source-range 二选一，如 '[{"value":"选项1","color":"#ff0000"}]'`)
+	setDropdownCmd.Flags().String("source-sheet-id", "", "SourceRange 来源工作表 ID；使用 --source-range 时必填")
+	setDropdownCmd.Flags().String("source-range", "", "SourceRange 来源区域，与 --options 二选一；不含工作表前缀，如 T1:T3、T:T 或 1:3")
 	setDropdownCmd.Flags().Bool("multi-select", false, "是否允许多选（默认单选）")
+	cli.AnnotateRuntimeFlagFormat(setDropdownCmd, "source-range", "a1-range")
+	setDropdownCmd.MarkFlagsOneRequired("options", "source-range")
+	setDropdownCmd.MarkFlagsMutuallyExclusive("options", "source-range")
+	setDropdownCmd.MarkFlagsRequiredTogether("source-sheet-id", "source-range")
 
 	getDropdownCmd := &cobra.Command{
 		Use:   "get-dropdown",
 		Short: "获取下拉列表配置",
 		Long: `查询钉钉表格指定范围内的下拉列表配置。
 
-返回范围内所有单元格的下拉列表配置信息，包括选项值和颜色。
+Inline 配置返回 conditionValues 和 options；SourceRange 配置返回
+sourceType/sourceRangeStatus/enableMultiSelect，且仅在 sourceRangeStatus="valid" 时返回
+sourceRange。invalid 结果仍保留配置组，但省略 sourceRange；两种状态都不展开来源区域的候选值或颜色。
 如果范围内存在多个不同的下拉列表配置，会分别返回每组配置及其覆盖的单元格列表。
 如果范围内没有设置下拉列表，返回空。
 

internal/helpers/sheet_dropdown_source_range_test.go

@@ -0,0 +1,248 @@
+package helpers
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/runtimeannotate"
+)
+
+func TestCrossPlatformCoverageSetDropdownSourceRangeCommand(t *testing.T) {
+	caller := &scriptedToolCaller{steps: []scriptedToolStep{{text: `{"success":true}`}}}
+	installScriptedCaller(t, caller)
+	err := executeDimensionCoverage(t, "set-dropdown",
+		"--node", "node-1",
+		"--sheet-id", "target-sheet",
+		"--range", "B2:B100",
+		"--source-sheet-id", "source-sheet",
+		"--source-range", "$t$1:$t$3",
+		"--multi-select",
+	)
+	if err != nil {
+		t.Fatalf("set SourceRange dropdown: %v", err)
+	}
+	if caller.tool != "set_dropdown_lists" {
+		t.Fatalf("tool = %q, want set_dropdown_lists", caller.tool)
+	}
+	if _, exists := caller.args["options"]; exists {
+		t.Fatalf("SourceRange request must omit options: %#v", caller.args)
+	}
+	source, ok := caller.args["sourceRange"].(map[string]any)
+	if !ok {
+		t.Fatalf("sourceRange = %#v", caller.args["sourceRange"])
+	}
+	if source["sheetId"] != "source-sheet" || source["a1Notation"] != "$t$1:$t$3" {
+		t.Fatalf("sourceRange = %#v", source)
+	}
+	if caller.args["enableMultiSelect"] != true {
+		t.Fatalf("enableMultiSelect = %#v", caller.args["enableMultiSelect"])
+	}
+}
+
+func TestCrossPlatformCoverageSetDropdownInlineCommandStillOmitsSourceRange(t *testing.T) {
+	caller := &scriptedToolCaller{steps: []scriptedToolStep{{text: `{"success":true}`}}}
+	installScriptedCaller(t, caller)
+	err := executeDimensionCoverage(t, "set-dropdown",
+		"--node", "node-1",
+		"--sheet-id", "sheet-1",
+		"--range", "A1:A3",
+		"--options", `[{"value":"one","color":"#ff0000"}]`,
+	)
+	if err != nil {
+		t.Fatalf("set inline dropdown: %v", err)
+	}
+	if _, exists := caller.args["sourceRange"]; exists {
+		t.Fatalf("inline request must omit sourceRange: %#v", caller.args)
+	}
+	options, ok := caller.args["options"].([]map[string]any)
+	if !ok || len(options) != 1 || options[0]["value"] != "one" {
+		t.Fatalf("options = %#v", caller.args["options"])
+	}
+}
+
+func TestCrossPlatformCoverageSetDropdownModeConstraints(t *testing.T) {
+	base := []string{"--node", "node", "--sheet-id", "sheet", "--range", "A1"}
+	tests := []struct {
+		name string
+		args []string
+		want string
+	}{
+		{name: "neither", want: "one of the flags"},
+		{name: "both", args: []string{"--options", `[{"value":"one"}]`, "--source-sheet-id", "source", "--source-range", "A1:A3"}, want: "none of the others"},
+		{name: "source sheet without range", args: []string{"--options", `[{"value":"one"}]`, "--source-sheet-id", "source"}, want: "must all be set"},
+		{name: "range without source sheet", args: []string{"--source-range", "A1:A3"}, want: "must all be set"},
+		{name: "sheet prefix", args: []string{"--source-sheet-id", "source", "--source-range", "Sheet2!A1:A3"}, want: "不能包含工作表前缀"},
+		{name: "formula", args: []string{"--source-sheet-id", "source", "--source-range", "=A1:A3"}, want: "必须是单一连续区域"},
+		{name: "multi region", args: []string{"--source-sheet-id", "source", "--source-range", "A1:A3,C1:C3"}, want: "必须是单一连续区域"},
+		{name: "blank source range", args: []string{"--source-sheet-id", "source", "--source-range", " \t "}, want: "--source-range 不能为空"},
+		{name: "blank source sheet", args: []string{"--source-sheet-id", " \t ", "--source-range", "A1:A3"}, want: "--source-sheet-id 不能为空"},
+	}
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			caller := &scriptedToolCaller{}
+			installScriptedCaller(t, caller)
+			args := append(append([]string{}, base...), tc.args...)
+			err := executeDimensionCoverage(t, "set-dropdown", args...)
+			if err == nil || !strings.Contains(err.Error(), tc.want) {
+				t.Fatalf("error = %v, want contains %q", err, tc.want)
+			}
+			if caller.calls != 0 {
+				t.Fatalf("calls = %d, validation must fail before request", caller.calls)
+			}
+		})
+	}
+}
+
+func TestCrossPlatformCoverageSetDropdownRunEValidation(t *testing.T) {
+	tests := []struct {
+		name    string
+		options string
+		source  string
+		rangeID string
+		want    string
+	}{
+		{name: "neither mode", want: "必须且只能指定一个"},
+		{name: "source range without sheet", rangeID: "A1:A3", want: "必须同时指定 --source-sheet-id"},
+		{name: "source sheet without range", options: `[{"value":"one"}]`, source: "source", want: "必须同时指定 --source-range"},
+		{name: "invalid options JSON", options: "{", want: "JSON 解析失败"},
+		{name: "missing option value", options: `[{}]`, want: "value 为空"},
+	}
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			cmd := dimensionCoverageCommand(t, "set-dropdown")
+			for name, value := range map[string]string{
+				"node": "node", "sheet-id": "sheet", "range": "A1",
+				"options": tc.options, "source-sheet-id": tc.source, "source-range": tc.rangeID,
+			} {
+				if err := cmd.Flags().Set(name, value); err != nil {
+					t.Fatalf("set --%s: %v", name, err)
+				}
+			}
+			err := cmd.RunE(cmd, nil)
+			if err == nil || !strings.Contains(err.Error(), tc.want) {
+				t.Fatalf("error = %v, want contains %q", err, tc.want)
+			}
+		})
+	}
+}
+
+func TestCrossPlatformCoverageSetDropdownPreservesSchemaConstraints(t *testing.T) {
+	cmd := dimensionCoverageCommand(t, "set-dropdown")
+	if constraints := runtimeannotate.CommandConstraints(cmd); !runtimeannotate.ConstraintsEmpty(constraints) {
+		t.Fatalf("constraints = %#v, want no new schema-level constraints", constraints)
+	}
+}
+
+func TestCrossPlatformCoverageBatchSetDropdownSourceRange(t *testing.T) {
+	got, err := translateBatchOp(map[string]any{
+		"toolName": "set-dropdown",
+		"input": map[string]any{
+			"sheet-id":        "target-sheet",
+			"range":           "B2:B100",
+			"source-sheet-id": "source-sheet",
+			"source-range":    "T:T",
+			"multi-select":    true,
+		},
+	})
+	if err != nil {
+		t.Fatalf("translate SourceRange batch op: %v", err)
+	}
+	input := got["input"].(map[string]any)
+	if _, exists := input["options"]; exists {
+		t.Fatalf("SourceRange batch input must omit options: %#v", input)
+	}
+	source := input["sourceRange"].(map[string]any)
+	if source["sheetId"] != "source-sheet" || source["a1Notation"] != "T:T" {
+		t.Fatalf("sourceRange = %#v", source)
+	}
+
+	invalid := []map[string]any{
+		{},
+		{"options": []any{map[string]any{"value": "one"}}, "source-sheet-id": "source", "source-range": "A1:A3"},
+		{"source-range": "A1:A3"},
+		{"source-sheet-id": "source", "source-range": "A1:A3", "colors": []any{"#fff"}},
+		{"source-sheet-id": "source", "source-range": "A1:A3", "source-colors": []any{"#fff"}},
+		{"source-sheet-id": "source", "source-range": "Sheet2!A1:A3"},
+	}
+	for _, value := range invalid {
+		if _, err := translateBatchOp(map[string]any{"toolName": "set-dropdown", "input": value}); err == nil {
+			t.Errorf("invalid batch SourceRange input %#v returned nil", value)
+		}
+	}
+}
+
+func TestCrossPlatformCoverageBatchSetDropdownValidationGuidance(t *testing.T) {
+	tests := []struct {
+		name  string
+		input map[string]any
+		want  string
+	}{
+		{
+			name:  "inline top-level colors",
+			input: map[string]any{"options": []any{map[string]any{"value": "one"}}, "colors": []any{"#fff"}},
+			want:  "Inline 颜色请写入 options[].color",
+		},
+		{
+			name:  "source top-level colors",
+			input: map[string]any{"source-sheet-id": "source", "source-range": "A1:A3", "source-colors": []any{"#fff"}},
+			want:  "SourceRange 颜色写入暂不支持",
+		},
+		{
+			name:  "blank source range",
+			input: map[string]any{"source-sheet-id": "source", "source-range": " \t "},
+			want:  "--source-range 不能为空",
+		},
+		{
+			name:  "blank source sheet",
+			input: map[string]any{"source-sheet-id": " \t ", "source-range": "A1:A3"},
+			want:  "--source-sheet-id 不能为空",
+		},
+	}
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			_, err := translateBatchOp(map[string]any{"toolName": "set-dropdown", "input": tc.input})
+			if err == nil || !strings.Contains(err.Error(), tc.want) {
+				t.Fatalf("error = %v, want contains %q", err, tc.want)
+			}
+		})
+	}
+}
+
+func TestCrossPlatformCoverageDropdownHelpDescribesDynamicAndInvalidContracts(t *testing.T) {
+	setDropdown := dimensionCoverageCommand(t, "set-dropdown")
+	if !strings.Contains(setDropdown.Long, "会自动调整引用并保持 valid") ||
+		!strings.Contains(setDropdown.Long, "只有 invalid 时才重新选择来源并写入") {
+		t.Fatalf("set-dropdown help does not describe verified structural behavior:\n%s", setDropdown.Long)
+	}
+	getDropdown := dimensionCoverageCommand(t, "get-dropdown")
+	if !strings.Contains(getDropdown.Long, `仅在 sourceRangeStatus="valid" 时返回`) ||
+		!strings.Contains(getDropdown.Long, "invalid 结果仍保留配置组，但省略 sourceRange") {
+		t.Fatalf("get-dropdown help does not describe conditional sourceRange readback:\n%s", getDropdown.Long)
+	}
+}
+
+func TestCrossPlatformCoverageValidateSourceRangeDataValidation(t *testing.T) {
+	valid := []any{
+		map[string]any{"type": "dropdown", "sourceRange": map[string]any{"sheetId": "source", "a1Notation": "T1:T3"}},
+		map[string]any{"type": "dropdown", "sourceRange": map[string]any{"sheetId": "missing-sheet", "a1Notation": "not-validated-locally"}, "enableMultiSelect": true},
+	}
+	for _, value := range valid {
+		if err := validateDataValidation(value, "dv"); err != nil {
+			t.Errorf("valid SourceRange data validation %#v: %v", value, err)
+		}
+	}
+
+	invalid := []any{
+		map[string]any{"type": "dropdown", "options": []any{map[string]any{"value": "one"}}, "sourceRange": map[string]any{"sheetId": "source", "a1Notation": "T1:T3"}},
+		map[string]any{"type": "dropdown", "sourceRange": "T1:T3"},
+		map[string]any{"type": "dropdown", "sourceRange": map[string]any{"a1Notation": "T1:T3"}},
+		map[string]any{"type": "dropdown", "sourceRange": map[string]any{"sheetId": "source"}},
+		map[string]any{"type": "dropdown", "sourceRange": map[string]any{"sheetId": "source", "a1Notation": "T1:T3", "colors": []any{"#fff"}}},
+		map[string]any{"type": "dropdown", "sourceRange": map[string]any{"sheetId": "source", "a1Notation": "T1:T3"}, "enableMultiSelect": "yes"},
+	}
+	for _, value := range invalid {
+		if err := validateDataValidation(value, "dv"); err == nil {
+			t.Errorf("invalid SourceRange data validation %#v returned nil", value)
+		}
+	}
+}

internal/helpers/sheet_range_ops.go

@@ -26,6 +26,16 @@ func newRangeCmd() *cobra.Command {
   value           单元格值（内容由 --value-render-option 决定）
   dataValidation  数据验证配置（下拉列表/复选框），无则为 null
   hyperlink       单元格级超链接（path/sheet/range），无则省略
+顶层还会返回 rowIndices / colIndices 与完成度字段：
+  hasMore           目标范围是否还有未返回数据
+  truncationReasons 部分返回原因（max_cells）
+  resolvedRange     未传 --range 时底层解析出的完整目标范围
+  returnedRange     本次实际完整返回的范围
+
+单次最多返回 30,000 个单元格。hasMore=true 是部分成功，本命令
+不会自动续读；请结合目标范围和 returnedRange 从下一行显式传
+--range。收到 forbidden.document.sizeOverLimit 则表示工作簿整体无法装载，
+应创建更小副本或拆分工作簿，缩小 --range 不能解决。
 
 注意：range read/get 不返回合并单元格结构。查看合并范围请使用
 dws sheet info --node NODE_ID --sheet-id SHEET_ID --format json，并读取 mergedRanges。
@@ -157,7 +167,12 @@ dws sheet info --node NODE_ID --sheet-id SHEET_ID --format json，并读取 merg
   2) {"dataValidation":{"type":"none"}}             → 显式清除该单元格 DV
   3) {"dataValidation":{"type":"dropdown",...}}     → 写新 dropdown（覆盖）
      {"dataValidation":{"type":"checkbox",...}}    → 写新 checkbox（覆盖）
-  dropdown: {"dataValidation":{"type":"dropdown","options":[{"value":"选项1"}],"enableMultiSelect":false}}
+  Inline dropdown:
+    {"dataValidation":{"type":"dropdown","options":[{"value":"选项1"}],"enableMultiSelect":false}}
+  SourceRange dropdown（同一工作簿内可跨工作表；不展开来源 values，不支持 colors）：
+    {"dataValidation":{"type":"dropdown","sourceRange":{"sheetId":"SOURCE_SHEET_ID","a1Notation":"T1:T3"},"enableMultiSelect":false}}
+  dropdown 的 options 与 sourceRange 必须且只能传一个。SourceRange 支持普通区域、整行和整列；
+  a1Notation 不带工作表前缀，来源工作表单独写在 sheetId。
   checkbox: {"dataValidation":{"type":"checkbox","checked":true}}
   可与 text/richText 共存，也可单独使用（如 {dataValidation:{type:"none"}} 仅清除 DV 不写值）
 
@@ -169,6 +184,8 @@ dws sheet info --node NODE_ID --sheet-id SHEET_ID --format json，并读取 merg
   - 只设样式或批量刷整片区域样式请用 dws sheet range set-style；写值同时设置少量 cell 样式可用 cellStyles
   - 目标范围与已有合并区域冲突时，range update 会返回 MERGED_CELLS_CONFLICT；先用 sheet info 查看 mergedRanges，取消合并后写入，必要时再重新合并
   - csv-put 的合并处理不同：目标区域含合并单元格时会打散合并并写入 CSV 值或公式
+  - SourceRange 在已验证的重命名、引用前插入行/列、删除引用前行的场景会自动调整；move-dimension 及其他未覆盖的删除/移动场景后先回读 sourceRangeStatus，仅 invalid 时重新选源写入
+  - 同一 cell 的 value/style 已写入但 SourceRange 校验失败时，服务端可返回 success=true，并通过 message 明确下拉未创建；必须检查 message，必要时重新读取确认
   - 清空整片区域请用 dws sheet range clear`,
 		Example: `  # 写入文本
   dws sheet range update --node NODE_ID --sheet-id SHEET_ID --range "A1:B2" \

internal/helpers/sheet_read_completion_test.go

@@ -0,0 +1,202 @@
+package helpers
+
+import (
+	"bytes"
+	"encoding/json"
+	"errors"
+	"strings"
+	"testing"
+)
+
+func executeSheetReadCompletionCommand(t *testing.T, caller *scriptedToolCaller, args ...string) (*bytes.Buffer, error) {
+	t.Helper()
+	installScriptedCaller(t, caller)
+	installSheetProductArgs(t)
+
+	stdout := &bytes.Buffer{}
+	deps.Out.w = stdout
+
+	cmd := newSheetCommand()
+	cmd.SilenceErrors = true
+	cmd.SilenceUsage = true
+	cmd.SetArgs(args)
+	return stdout, cmd.Execute()
+}
+
+func decodeSheetReadOutput(t *testing.T, stdout *bytes.Buffer) map[string]any {
+	t.Helper()
+	var got map[string]any
+	if err := json.Unmarshal(stdout.Bytes(), &got); err != nil {
+		t.Fatalf("decode sheet read output %q: %v", stdout.String(), err)
+	}
+	return got
+}
+
+func assertSheetReadCompletionMetadata(t *testing.T, got map[string]any) {
+	t.Helper()
+	if hasMore, ok := got["hasMore"].(bool); !ok || !hasMore {
+		t.Fatalf("hasMore = %#v, want true", got["hasMore"])
+	}
+	if got["resolvedRange"] != "A1:A30001" {
+		t.Fatalf("resolvedRange = %#v", got["resolvedRange"])
+	}
+	if got["returnedRange"] != "A1:A30000" {
+		t.Fatalf("returnedRange = %#v", got["returnedRange"])
+	}
+	reasons, ok := got["truncationReasons"].([]any)
+	if !ok || len(reasons) == 0 || reasons[0] != "max_cells" {
+		t.Fatalf("truncationReasons = %#v", got["truncationReasons"])
+	}
+}
+
+// csv-get intentionally projects the MCP response rather than inventing a
+// client-side page model. Keep all completion metadata visible and make one
+// request only, even when the server reports a partial success.
+func TestSheetCSVGetPreservesCompletionMetadataWithoutAutoPagination(t *testing.T) {
+	const response = `{"csv":"[row=1]1\n","colIndices":["A"],"rowIndices":[1],"hasMore":true,"truncationReasons":["max_cells","max_chars"],"resolvedRange":"A1:A30001","returnedRange":"A1:A30000","message":"partial"}`
+	caller := &scriptedToolCaller{
+		format: "raw",
+		steps:  []scriptedToolStep{{text: response}},
+	}
+
+	stdout, err := executeSheetReadCompletionCommand(t, caller,
+		"csv-get", "--node", "NODE")
+	if err != nil {
+		t.Fatalf("csv-get: %v", err)
+	}
+	if caller.calls != 1 || caller.tool != "get_range_as_csv" {
+		t.Fatalf("calls/tool = %d/%q, want one get_range_as_csv call", caller.calls, caller.tool)
+	}
+	if _, exists := caller.args["range"]; exists {
+		t.Fatalf("omitted range was unexpectedly synthesized by the CLI: %#v", caller.args["range"])
+	}
+	if got := strings.TrimSpace(stdout.String()); got != response {
+		t.Fatalf("raw csv-get response changed:\n got: %s\nwant: %s", got, response)
+	}
+
+	got := decodeSheetReadOutput(t, stdout)
+	assertSheetReadCompletionMetadata(t, got)
+	reasons := got["truncationReasons"].([]any)
+	if len(reasons) != 2 || reasons[1] != "max_chars" {
+		t.Fatalf("truncationReasons = %#v, want max_cells and max_chars", reasons)
+	}
+}
+
+// range read parses the get_cell_infos envelope to remove empty per-cell
+// schema shells. That cleanup must not discard new top-level completion fields.
+func TestSheetRangeReadPreservesCompletionMetadataWithoutAutoPagination(t *testing.T) {
+	const response = `{"cells":[[{"value":"1","dataValidation":{"type":null},"hyperlink":{"url":null}}]],"colIndices":["A"],"rowIndices":[1],"hasMore":true,"truncationReasons":["max_cells"],"resolvedRange":"A1:A30001","returnedRange":"A1:A30000","message":"partial"}`
+	caller := &scriptedToolCaller{
+		format: "json",
+		steps:  []scriptedToolStep{{text: response}},
+	}
+
+	stdout, err := executeSheetReadCompletionCommand(t, caller,
+		"range", "read", "--node", "NODE")
+	if err != nil {
+		t.Fatalf("range read: %v", err)
+	}
+	if caller.calls != 1 || caller.tool != "get_cell_infos" {
+		t.Fatalf("calls/tool = %d/%q, want one get_cell_infos call", caller.calls, caller.tool)
+	}
+	if _, exists := caller.args["range"]; exists {
+		t.Fatalf("omitted range was unexpectedly synthesized by the CLI: %#v", caller.args["range"])
+	}
+
+	got := decodeSheetReadOutput(t, stdout)
+	assertSheetReadCompletionMetadata(t, got)
+	cells := got["cells"].([]any)
+	row := cells[0].([]any)
+	cell := row[0].(map[string]any)
+	if _, exists := cell["dataValidation"]; exists {
+		t.Fatalf("empty dataValidation shell was not removed: %#v", cell)
+	}
+	if _, exists := cell["hyperlink"]; exists {
+		t.Fatalf("empty hyperlink shell was not removed: %#v", cell)
+	}
+}
+
+// sheet +read calls get_cell_infos through this direct passthrough instead of
+// callMCPToolCellInfos. Lock that third read surface to the same raw envelope
+// contract and to one request only.
+func TestSheetCellInfosDirectPassthroughPreservesCompletionMetadata(t *testing.T) {
+	const response = `{"cells":[[{"value":"1"}]],"colIndices":["A"],"rowIndices":[1],"hasMore":true,"truncationReasons":["max_cells"],"resolvedRange":"A1:A30001","returnedRange":"A1:A30000","message":"partial"}`
+	caller := &scriptedToolCaller{
+		format: "raw",
+		steps:  []scriptedToolStep{{text: response}},
+	}
+	installScriptedCaller(t, caller)
+	stdout := &bytes.Buffer{}
+	deps.Out.w = stdout
+
+	if err := CallMCPToolOnServer("sheet", "get_cell_infos", map[string]any{"nodeId": "NODE"}); err != nil {
+		t.Fatalf("direct get_cell_infos: %v", err)
+	}
+	if caller.calls != 1 || caller.server != "sheet" || caller.tool != "get_cell_infos" {
+		t.Fatalf("calls/server/tool = %d/%q/%q", caller.calls, caller.server, caller.tool)
+	}
+	if got := strings.TrimSpace(stdout.String()); got != response {
+		t.Fatalf("raw get_cell_infos response changed:\n got: %s\nwant: %s", got, response)
+	}
+	assertSheetReadCompletionMetadata(t, decodeSheetReadOutput(t, stdout))
+}
+
+// Large-CP failure is not a pageable success. Both the raw csv-get path and
+// both get_cell_infos paths must retain the backend code and safe user message
+// exactly, matching the generic get_all_sheets error-classification path.
+func TestSheetReadPreservesWorkbookSizeOverLimitError(t *testing.T) {
+	const response = `{"success":false,"errorCode":"forbidden.document.sizeOverLimit","errorMessage":"The workbook data is too large to process. Use a smaller copy or split the workbook, then try again."}`
+	tests := []struct {
+		name   string
+		args   []string
+		tool   string
+		direct bool
+	}{
+		{name: "csv-get", args: []string{"csv-get", "--node", "NODE"}, tool: "get_range_as_csv"},
+		{name: "range-read", args: []string{"range", "read", "--node", "NODE"}, tool: "get_cell_infos"},
+		{name: "cell-infos-direct", tool: "get_cell_infos", direct: true},
+	}
+
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			caller := &scriptedToolCaller{
+				format: "json",
+				steps:  []scriptedToolStep{{text: response}},
+			}
+			var stdout *bytes.Buffer
+			var err error
+			if test.direct {
+				installScriptedCaller(t, caller)
+				stdout = &bytes.Buffer{}
+				deps.Out.w = stdout
+				err = CallMCPToolOnServer("sheet", test.tool, map[string]any{"nodeId": "NODE"})
+			} else {
+				stdout, err = executeSheetReadCompletionCommand(t, caller, test.args...)
+			}
+			if err == nil {
+				t.Fatal("large-CP response was accepted as success")
+			}
+			var cliErr *CLIError
+			if !errors.As(err, &cliErr) || cliErr.Code != CodeMCPToolError {
+				t.Fatalf("error = %T %v, want MCP tool error", err, err)
+			}
+			if cliErr.Message != response {
+				t.Fatalf("backend error payload changed:\n got: %s\nwant: %s", cliErr.Message, response)
+			}
+			for _, want := range []string{
+				"forbidden.document.sizeOverLimit",
+				"The workbook data is too large to process.",
+			} {
+				if !strings.Contains(err.Error(), want) {
+					t.Errorf("error %q does not preserve %q", err, want)
+				}
+			}
+			if stdout.Len() != 0 {
+				t.Fatalf("failure wrote a success body: %q", stdout.String())
+			}
+			if caller.calls != 1 || caller.tool != test.tool {
+				t.Fatalf("calls/tool = %d/%q, want one %s call", caller.calls, caller.tool, test.tool)
+			}
+		})
+	}
+}

internal/helpers/sheet_validate.go

@@ -239,22 +239,48 @@ func validateDataValidation(dvRaw any, path string) error {
 	}
 	switch dvType {
 	case "dropdown":
-		optionsRaw, ok := dv["options"]
-		if !ok {
-			return fmt.Errorf("%s: type=dropdown 必须包含 options 数组", path)
+		optionsRaw, hasOptions := dv["options"]
+		sourceRangeRaw, hasSourceRange := dv["sourceRange"]
+		hasOptions = hasOptions && optionsRaw != nil
+		hasSourceRange = hasSourceRange && sourceRangeRaw != nil
+		if hasOptions == hasSourceRange {
+			return fmt.Errorf("%s: type=dropdown 的 options 与 sourceRange 必须且只能包含一个", path)
 		}
-		options, ok := optionsRaw.([]any)
-		if !ok || len(options) == 0 {
-			return fmt.Errorf("%s.options 必须为非空数组", path)
-		}
-		for i, opt := range options {
-			optMap, ok := opt.(map[string]any)
-			if !ok {
-				return fmt.Errorf("%s.options[%d] 必须为 object（如 {\"value\":\"选项\"}）", path, i)
+		if hasOptions {
+			options, ok := optionsRaw.([]any)
+			if !ok || len(options) == 0 {
+				return fmt.Errorf("%s.options 必须为非空数组", path)
 			}
-			val, ok := optMap["value"].(string)
-			if !ok || val == "" {
-				return fmt.Errorf("%s.options[%d].value 必须为非空字符串", path, i)
+			for i, opt := range options {
+				optMap, ok := opt.(map[string]any)
+				if !ok {
+					return fmt.Errorf("%s.options[%d] 必须为 object（如 {\"value\":\"选项\"}）", path, i)
+				}
+				val, ok := optMap["value"].(string)
+				if !ok || val == "" {
+					return fmt.Errorf("%s.options[%d].value 必须为非空字符串", path, i)
+				}
+			}
+		} else {
+			sourceRange, ok := sourceRangeRaw.(map[string]any)
+			if !ok {
+				return fmt.Errorf("%s.sourceRange 必须为 object", path)
+			}
+			if _, exists := sourceRange["colors"]; exists {
+				return fmt.Errorf("%s.sourceRange.colors 暂不支持", path)
+			}
+			sheetID, ok := sourceRange["sheetId"].(string)
+			if !ok || strings.TrimSpace(sheetID) == "" {
+				return fmt.Errorf("%s.sourceRange.sheetId 必须为非空字符串", path)
+			}
+			a1Notation, ok := sourceRange["a1Notation"].(string)
+			if !ok || strings.TrimSpace(a1Notation) == "" {
+				return fmt.Errorf("%s.sourceRange.a1Notation 必须为非空字符串", path)
+			}
+		}
+		if multi, exists := dv["enableMultiSelect"]; exists {
+			if _, ok := multi.(bool); !ok {
+				return fmt.Errorf("%s.enableMultiSelect 必须为 boolean", path)
 			}
 		}
 	case "checkbox":

internal/helpers/shell_quote.go

@@ -2,7 +2,7 @@ package helpers
 
 import "strings"
 
-// shellQuoteArg 按 POSIX sh 规则把 s 引用成可安全放进可复制命令的单个 argv 元素。
+// ShellQuoteArg 按 POSIX sh 规则把 s 引用成可安全放进可复制命令的单个 argv 元素。
 //
 // 为什么需要它：错误提示里的恢复命令是给用户直接复制到 shell 执行的，其中的查询域取自用户
 // 输入（--workspace 的常见形态就是带查询串的 URL）。裸拼接下，合法 URL 里的 `&` 就会把命令
@@ -21,7 +21,7 @@ import "strings"
 //
 // 空串必须显式引用成一对空单引号，否则该参数会从 argv 里整个消失，后面的 token 会被前一个
 // flag 吞掉。
-func shellQuoteArg(s string) string {
+func ShellQuoteArg(s string) string {
 	if s == "" {
 		return "''"
 	}
@@ -41,7 +41,7 @@ func shellValueIsBare(s string) bool {
 // driveLatestPosixScopeValue 是 POSIX shell 下把用户值放进可复制命令的策略：单引号内 sh 不做
 // 任何展开，因此含元字符的值引用后即可安全内联。第二个返回值恒为 true。
 func driveLatestPosixScopeValue(value string) (string, bool) {
-	return shellQuoteArg(value), true
+	return ShellQuoteArg(value), true
 }
 
 // driveLatestWindowsScopeValue 是 Windows 构建下的策略：只内联本身就安全的值，其余一律不进

internal/helpers/shell_quote_roundtrip_unix_test.go

@@ -51,7 +51,7 @@ func TestCrossPlatformCoverageShellQuoteArgRoundTrip(t *testing.T) {
 
 	for _, want := range values {
 		t.Run(want, func(t *testing.T) {
-			quoted := shellQuoteArg(want)
+			quoted := ShellQuoteArg(want)
 
 			// 1) 未被拆参也未被吞掉：位置参数个数必须恰好为 1。
 			//    引用失效时 "sp 7" 会变 2 个、"" 会变 0 个、$(id) 会变 id 的输出词数。

internal/helpers/shell_quote_test.go

@@ -69,8 +69,8 @@ func TestCrossPlatformCoverageShellQuoteArg(t *testing.T) {
 	}
 	for _, tc := range cases {
 		t.Run(tc.name, func(t *testing.T) {
-			if got := shellQuoteArg(tc.in); got != tc.want {
-				t.Fatalf("shellQuoteArg(%q)\n got: %s\nwant: %s", tc.in, got, tc.want)
+			if got := ShellQuoteArg(tc.in); got != tc.want {
+				t.Fatalf("ShellQuoteArg(%q)\n got: %s\nwant: %s", tc.in, got, tc.want)
 			}
 		})
 	}

internal/helpers/todo.go

@@ -11,11 +11,11 @@ import (
 	"strings"
 	"time"
 
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract"
 	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
 	"github.com/fatih/color"
 	"github.com/spf13/cobra"
-
-	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract"
 )
 
 // ──────────────────────────────────────────────────────────
@@ -1017,14 +1017,20 @@ reset-reminder 写入的提醒规则。提醒写命令的成功响应只能作
 		Short: "上传待办附件",
 		Long: `上传待办附件
 ⚠️ 重要：该接口会上传文件到附件，不可用于测试或试探性调用。调用前必须确认待办存在。`,
-		Example: `  dws todo task add-attachment --task-id <taskId> --file-path <filePath>
+		Example: `  dws todo task add-attachment --task-id <taskId> --file <filePath>
   # 查询 taskId: dws todo task list`,
 		RunE: func(cmd *cobra.Command, args []string) error {
-			if err := validateRequiredFlags(cmd, "task-id", "file-path"); err != nil {
-				return err
+			filePath := flagOrFallback(cmd, "file-path", "file")
+			taskID := mustGetFlag(cmd, "task-id")
+			if taskID == "" && filePath == "" {
+				return validateRequiredFlags(cmd, "task-id", "file")
+			}
+			if taskID == "" {
+				return validateRequiredFlags(cmd, "task-id")
+			}
+			if filePath == "" {
+				return validateRequiredFlags(cmd, "file")
 			}
-
-			filePath, _ := cmd.Flags().GetString("file-path")
 			meta, err := buildTodoLocalFileMeta(filePath, "", "")
 			if err != nil {
 				return err
@@ -1092,8 +1098,8 @@ reset-reminder 写入的提醒规则。提醒写命令的成功响应只能作
 					"要添加执行人/参与人/提醒时改用对应 add 命令",
 				},
 				Examples: []string{
-					"dws todo task add-attachment --task-id <taskId> --file-path /path/to/file.pdf",
-					"dws todo task add-attachment --task-id <taskId> --file-path /path/to/file.pdf --format json",
+					"dws todo task add-attachment --task-id <taskId> --file /path/to/file.pdf",
+					"dws todo task add-attachment --task-id <taskId> --file /path/to/file.pdf --format json",
 				},
 			},
 			Parameters: []contract.ParamDecl{
@@ -1247,7 +1253,11 @@ reset-reminder 写入的提醒规则。提醒写命令的成功响应只能作
 	todoTaskListSubCmd.Flags().String("task-id", "", "待办任务 ID (必填)")
 	todoTaskListAttachmentCmd.Flags().String("task-id", "", "待办任务 ID (必填)")
 	todoTaskAddAttachment.Flags().String("task-id", "", "待办任务 ID (必填)")
-	todoTaskAddAttachment.Flags().String("file-path", "", "本地文件路径（必填）")
+	corecmd.RegisterFlags(todoTaskAddAttachment, []corecmd.FlagSpec{{
+		Name:    "file",
+		Usage:   "本地文件路径（必填）",
+		Aliases: []string{"file-path"},
+	}})
 	todoTaskRemoveAttachmentCmd.Flags().String("task-id", "", "待办任务 ID (必填)")
 	todoTaskRemoveAttachmentCmd.Flags().String("attachment-id", "", "待办附件 ID（必填）")
 

internal/shortcut/aitable/aitable.go

@@ -659,8 +659,8 @@ var RecordQuery = shortcut.Shortcut{
 	Service:     "aitable",
 	Command:     "+record-query",
 	Product:     serverMain,
-	Description: "查询表格记录（按 ID 取 / 条件筛选 / 关键词 / 分页）",
-	Intent:      "当你要读取表格里的行数据——按 recordId 精确取、按结构化条件筛选、按关键词全文搜索或分页遍历时使用；返回匹配记录及其单元格值。",
+	Description: "查询表格记录（按 ID / 条件 / 关键词，并支持字段投影和分页）",
+	Intent:      "读取表格行数据；可按 recordId 精确取、按条件筛选、按关键词搜索，并用 fieldIds 只返回用户要求的字段以避免无关数据和 token 消耗。",
 	Risk:        shortcut.RiskRead,
 	Safety: contract.SafetySpec{
 		Effect: "read", Risk: "low",
@@ -674,17 +674,20 @@ var RecordQuery = shortcut.Shortcut{
 			CLIPath:        "aitable +record-query",
 			PrimaryCLIPath: "aitable +record-query",
 		},
-		Description: "查询表格记录（按 ID 取 / 条件筛选 / 关键词 / 分页）",
+		Description: "查询表格记录（按 ID / 条件 / 关键词，并支持字段投影和分页）",
 		Interface: &contract.InterfaceSpec{
 			Mode:         "composite",
 			Availability: "available",
 			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.",
 		},
 		Selection: contract.SelectionSpec{
-			AgentSummary: "查询表格记录（按 ID 取 / 条件筛选 / 关键词 / 分页）",
-			UseWhen:      []string{"当你要读取表格里的行数据——按 recordId 精确取、按结构化条件筛选、按关键词全文搜索或分页遍历时使用；返回匹配记录及其单元格值。"},
+			AgentSummary: "查询表格记录（按 ID / 条件 / 关键词，并支持字段投影和分页）",
+			UseWhen:      []string{"读取表格行数据；可按 recordId 精确取、按条件筛选、按关键词搜索，并用 fieldIds 只返回用户要求的字段以避免无关数据和 token 消耗。"},
 			AvoidWhen:    []string{"需要该 Shortcut 未公开的底层参数、原始响应或不同执行语义时，改用对应原子命令"},
-			Examples:     []string{"dws aitable +record-query --base-id B --table-id T --query \"关键词\" --limit 50"},
+			Examples: []string{
+				"dws aitable +record-query --base-id B --table-id T --query \"关键词\" --limit 50",
+				"dws aitable +record-query --base-id B --table-id T --record-ids R1,R2 --field-ids F_NAME,F_STATUS",
+			},
 		},
 	},
 	Flags: []shortcut.Flag{
@@ -698,7 +701,10 @@ var RecordQuery = shortcut.Shortcut{
 		{Name: "limit", Type: shortcut.FlagInt, Desc: "单次最大记录数，默认 100（可选）"},
 		{Name: "cursor", Type: shortcut.FlagString, Desc: "分页游标（可选）"},
 	},
-	Tips: []string{`dws aitable +record-query --base-id B --table-id T --query "关键词" --limit 50`},
+	Tips: []string{
+		`dws aitable +record-query --base-id B --table-id T --query "关键词" --limit 50`,
+		`dws aitable +record-query --base-id B --table-id T --record-ids R1,R2 --field-ids F_NAME,F_STATUS`,
+	},
 	Execute: func(rt *shortcut.RuntimeContext) error {
 		params := map[string]any{
 			"baseId":  rt.Str("base-id"),
@@ -733,7 +739,7 @@ var RecordQuery = shortcut.Shortcut{
 		if rt.Changed("cursor") {
 			params["cursor"] = rt.Str("cursor")
 		}
-		return rt.CallMCP("query_records", params)
+		return executeRecordQuery(rt, params)
 	},
 }
 
@@ -3110,6 +3116,7 @@ func init() {
 		BaseSchemaSnapshot,
 		BaseBootstrap,
 		TableGet,
+		TableBootstrap,
 		TableCopy,
 		TableUpdate,
 		TableDelete,

internal/shortcut/aitable/base_composite.go

@@ -5,6 +5,7 @@ package aitable
 
 import (
 	"fmt"
+	"reflect"
 	"strings"
 
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract"
@@ -50,7 +51,7 @@ var BaseBootstrap = shortcut.Shortcut{
 		"+base-bootstrap",
 		"一次创建 Base、数据表和字段，逐层读回验证并在中断时报告已知副作用",
 		"当你已有声明式 tables JSON、想一次搭好一套 AI 表格结构时使用；表内字段自动按 15 个拆批，每次创建都读回验证。",
-		"已有 Base 只需新增一张表时用 table create；复制现有 Base 用 base copy；不要对失败请求盲目重试",
+		"已有 Base 只需新增一张表时用 +table-bootstrap；复制现有 Base 用 +base-copy；不要对失败请求盲目重试",
 		`dws aitable +base-bootstrap --name "项目管理" --tables '[{"name":"任务","fields":[]}]'`,
 	),
 	Flags: []shortcut.Flag{
@@ -73,25 +74,25 @@ type bootstrapTable struct {
 func parseBootstrapTables(raw string) ([]bootstrapTable, error) {
 	value, err := parseJSONAny("tables", raw)
 	if err != nil {
-		return nil, err
+		return nil, baseBootstrapValidation(fmt.Sprintf("--tables 不是合法 JSON 数组：%v", err))
 	}
 	items, ok := value.([]any)
 	if !ok || len(items) == 0 {
-		return nil, apperrors.NewValidation("--tables 必须是非空 JSON 数组")
+		return nil, baseBootstrapValidation("--tables 必须是非空 JSON 数组")
 	}
 	if len(items) > 100 {
-		return nil, apperrors.NewValidation("--tables 最多接受 100 张表")
+		return nil, baseBootstrapValidation("--tables 最多接受 100 张表")
 	}
 	seen := map[string]bool{}
 	out := make([]bootstrapTable, 0, len(items))
 	for index, item := range items {
 		object, ok := item.(map[string]any)
 		if !ok {
-			return nil, apperrors.NewValidation(fmt.Sprintf("--tables[%d] 必须是 JSON 对象", index))
+			return nil, baseBootstrapValidation(fmt.Sprintf("--tables[%d] 必须是 JSON 对象", index))
 		}
 		name := strings.TrimSpace(stringValue(object, "name"))
 		if name == "" || seen[name] {
-			return nil, apperrors.NewValidation(fmt.Sprintf("--tables[%d].name 必须非空且不能重复", index))
+			return nil, baseBootstrapValidation(fmt.Sprintf("--tables[%d].name 必须非空且不能重复", index))
 		}
 		seen[name] = true
 		fields := []any{}
@@ -99,13 +100,24 @@ func parseBootstrapTables(raw string) ([]bootstrapTable, error) {
 			var fieldsOK bool
 			fields, fieldsOK = rawFields.([]any)
 			if !fieldsOK {
-				return nil, apperrors.NewValidation(fmt.Sprintf("--tables[%d].fields 必须是 JSON 数组", index))
+				return nil, baseBootstrapValidation(fmt.Sprintf("--tables[%d].fields 必须是 JSON 数组", index))
 			}
 		}
+		fieldNames := map[string]bool{}
 		for fieldIndex, field := range fields {
 			object, ok := field.(map[string]any)
-			if !ok || strings.TrimSpace(stringValue(object, "fieldName", "name")) == "" || strings.TrimSpace(stringValue(object, "type")) == "" {
-				return nil, apperrors.NewValidation(fmt.Sprintf("--tables[%d].fields[%d] 必须包含 fieldName 和 type", index, fieldIndex))
+			fieldName := strings.TrimSpace(stringValue(object, "fieldName", "name"))
+			if !ok || fieldName == "" || strings.TrimSpace(stringValue(object, "type")) == "" {
+				return nil, baseBootstrapValidation(fmt.Sprintf("--tables[%d].fields[%d] 必须包含 fieldName 和 type", index, fieldIndex))
+			}
+			if fieldNames[fieldName] {
+				return nil, baseBootstrapValidation(fmt.Sprintf("--tables[%d].fields[%d].fieldName %q 不能重复", index, fieldIndex, fieldName))
+			}
+			fieldNames[fieldName] = true
+			if config, exists := object["config"]; exists {
+				if _, ok := config.(map[string]any); !ok {
+					return nil, baseBootstrapValidation(fmt.Sprintf("--tables[%d].fields[%d].config 必须是 JSON 对象", index, fieldIndex))
+				}
 			}
 		}
 		out = append(out, bootstrapTable{Name: name, Fields: fields})
@@ -113,6 +125,14 @@ func parseBootstrapTables(raw string) ([]bootstrapTable, error) {
 	return out, nil
 }
 
+func baseBootstrapValidation(message string) error {
+	return apperrors.NewValidation(message,
+		apperrors.WithHint("tables 使用 [{\"name\":\"任务\",\"fields\":[{\"fieldName\":\"标题\",\"type\":\"text\"}]}]；已知参数时不要先调用 --help"),
+		apperrors.WithActions(`dws aitable +base-bootstrap --name "项目管理" --tables '[{"name":"任务","fields":[{"fieldName":"标题","type":"text"}]}]'`),
+		apperrors.WithAvailableFlags("name", "folder-id", "template-id", "tables"),
+	)
+}
+
 func executeBaseSchemaSnapshot(rt *shortcut.RuntimeContext) error {
 	baseID := rt.Str("base-id")
 	base, err := rt.CallMCPData(serverMain, "get_base", map[string]any{"baseId": baseID})
@@ -195,17 +215,20 @@ func executeBaseBootstrap(rt *shortcut.RuntimeContext) error {
 	if err != nil {
 		result.Status = "unknown"
 		result.FailedCount = len(tables)
-		result.Checkpoint = map[string]any{"nextStep": "resolve whether base was created before retrying"}
+		result.Checkpoint = map[string]any{"nextStep": "resolve whether base was created before retrying", "name": rt.Str("name")}
+		result.NextCommand = aitableRecoveryCommand("dws", "aitable", "+base-search", "--query", rt.Str("name"), "--format", "json")
 		return compositeError(result, err, false)
 	}
 	baseID := findStringByKeys(baseData, "baseId")
 	if baseID == "" {
 		result.Status = "unknown"
 		result.Result = baseData
-		result.Checkpoint = map[string]any{"nextStep": "locate the created Base by exact name before retrying"}
+		result.Checkpoint = map[string]any{"nextStep": "locate the created Base by exact name before retrying", "name": rt.Str("name")}
+		result.NextCommand = aitableRecoveryCommand("dws", "aitable", "+base-search", "--query", rt.Str("name"), "--format", "json")
 		return compositeError(result, fmt.Errorf("create_base response is missing baseId"), false)
 	}
 	result.Resolved = map[string]any{"baseId": baseID}
+	result.NextCommand = aitableRecoveryCommand("dws", "aitable", "+base-get", "--base-id", baseID, "--format", "json")
 	result.KnownEffects = append(result.KnownEffects, map[string]any{"tool": "create_base", "baseId": baseID})
 	result.CompletedSteps = append(result.CompletedSteps, compositeStep{Index: 1, Name: "create base", Tool: "create_base", Status: "completed", Result: baseData})
 	baseRead, err := rt.CallMCPData(serverMain, "get_base", map[string]any{"baseId": baseID})
@@ -237,6 +260,7 @@ func executeBaseBootstrap(rt *shortcut.RuntimeContext) error {
 			return compositeError(result, createErr, false)
 		}
 		result.KnownEffects = append(result.KnownEffects, map[string]any{"tool": "create_table", "baseId": baseID, "tableId": tableID, "name": spec.Name})
+		result.NextCommand = aitableRecoveryCommand("dws", "aitable", "+table-get", "--base-id", baseID, "--table-id", tableID, "--format", "json")
 		for offset := initialEnd; offset < len(spec.Fields); offset += 15 {
 			end := minInt(offset+15, len(spec.Fields))
 			_, fieldErr := rt.CallMCPWriteDataStrict(serverMain, "create_fields", map[string]any{
@@ -259,10 +283,13 @@ func executeBaseBootstrap(rt *shortcut.RuntimeContext) error {
 		}
 		fieldsData, verifyErr := rt.CallMCPData(serverMain, "get_fields", map[string]any{"baseId": baseID, "tableId": tableID})
 		fields, found := findNamedObjectList(fieldsData, "fields", "fieldList")
-		if verifyErr != nil || !found || !containsAllFieldNames(fields, spec.Fields) {
-			if verifyErr == nil {
-				verifyErr = fmt.Errorf("field read-back for table %s does not contain the declared field set", tableID)
-			}
+		if verifyErr == nil && !found {
+			verifyErr = fmt.Errorf("field read-back for table %s is missing the fields collection", tableID)
+		}
+		if verifyErr == nil {
+			verifyErr = verifyDeclaredFieldStructures(fields, spec.Fields)
+		}
+		if verifyErr != nil {
 			result.Status = "partial_success"
 			result.CompletedCount = index
 			result.FailedCount = len(tables) - index
@@ -275,6 +302,7 @@ func executeBaseBootstrap(rt *shortcut.RuntimeContext) error {
 	}
 	result.Verification = map[string]any{"status": "verified", "baseId": baseID, "tableCount": len(createdTables)}
 	result.Result = map[string]any{"baseId": baseID, "tables": createdTables}
+	result.NextCommand = ""
 	return rt.Output(result)
 }
 
@@ -378,16 +406,73 @@ func deepContainsString(value any, expected string) bool {
 	return false
 }
 
-func containsAllFieldNames(actual []map[string]any, expected []any) bool {
-	names := map[string]bool{}
+func verifyDeclaredFieldStructures(actual []map[string]any, expected []any) error {
+	actualByName := map[string][]map[string]any{}
 	for _, field := range actual {
-		names[stringValue(field, "fieldName", "name")] = true
-	}
-	for _, raw := range expected {
-		field, _ := raw.(map[string]any)
-		if !names[stringValue(field, "fieldName", "name")] {
-			return false
+		name := strings.TrimSpace(stringValue(field, "fieldName", "name"))
+		if name != "" {
+			actualByName[name] = append(actualByName[name], field)
 		}
 	}
-	return true
+	for index, raw := range expected {
+		field, ok := raw.(map[string]any)
+		if !ok {
+			return fmt.Errorf("declared field at index %d is not an object", index)
+		}
+		name := strings.TrimSpace(stringValue(field, "fieldName", "name"))
+		matches := actualByName[name]
+		if len(matches) == 0 {
+			return fmt.Errorf("field read-back is missing declared field %q", name)
+		}
+		if len(matches) != 1 {
+			return fmt.Errorf("field read-back contains %d fields named %q", len(matches), name)
+		}
+		actualField := matches[0]
+		expectedType := strings.TrimSpace(stringValue(field, "type"))
+		actualType := strings.TrimSpace(stringValue(actualField, "type", "fieldType"))
+		if actualType != expectedType {
+			return fmt.Errorf("field %q type mismatch: got %q, want %q", name, actualType, expectedType)
+		}
+		for _, key := range []string{"config", "aiConfig"} {
+			expectedConfig, declared := field[key]
+			if !declared {
+				continue
+			}
+			actualConfig, found := actualField[key]
+			if !found || !declaredValueMatches(actualConfig, expectedConfig) {
+				return fmt.Errorf("field %q %s mismatch", name, key)
+			}
+		}
+	}
+	return nil
+}
+
+func declaredValueMatches(actual, expected any) bool {
+	switch expectedValue := expected.(type) {
+	case map[string]any:
+		actualValue, ok := actual.(map[string]any)
+		if !ok {
+			return false
+		}
+		for key, expectedChild := range expectedValue {
+			actualChild, found := actualValue[key]
+			if !found || !declaredValueMatches(actualChild, expectedChild) {
+				return false
+			}
+		}
+		return true
+	case []any:
+		actualValue, ok := actual.([]any)
+		if !ok || len(actualValue) != len(expectedValue) {
+			return false
+		}
+		for index := range expectedValue {
+			if !declaredValueMatches(actualValue[index], expectedValue[index]) {
+				return false
+			}
+		}
+		return true
+	default:
+		return reflect.DeepEqual(actual, expected)
+	}
 }