Merge branch 'main' into feat/help-feedback-entry

fix(ci): shard the focused test job instead of one long-lived run

.changes/1009-clitrack-telemetry.md

@@ -0,0 +1,5 @@
+---
+category: 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.

.changes/1019-help-feedback-entry.md

@@ -0,0 +1,5 @@
+---
+category: Added
+---
+
+- **Feedback survey entry in root help** (#1019) — `dws --help` now closes with a Feedback section linking the user-experience survey form.

.changes/954-chat-im-id-flags.md

@@ -0,0 +1,7 @@
+---
+category: 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.

.changes/chat-reference-card-verification.md

@@ -0,0 +1,6 @@
+---
+category: 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.

.changes/released/1.0.59-beta.1/899-drive-latest-incomplete-scan.md

@@ -0,0 +1,20 @@
+---
+category: Fixed
+---
+
+- **Drive `--latest` refuses incomplete Top-N** (#899) — `dws drive list --latest` used to
+  exit 0 with a "Top-N" computed over a partially scanned tree whenever a directory read
+  failed mid-recursion (permission denied, API error), letting an incomplete set pose as the
+  globally newest files. Truncation at the 2000-item scan cap and mid-recursion directory
+  failures now both fail closed (`LATEST_SCAN_TRUNCATED` / `LATEST_SCAN_INCOMPLETE`), report
+  the first failing folder with its depth and reason, and emit a recovery command that
+  reproduces the original candidate set — query domain, `--folder`, `--pattern`, `--type`,
+  `--start` and `--end` are all carried over. On POSIX shells each user-supplied value is
+  quoted so a URL query string or a shell metacharacter cannot change how the copied command
+  parses. On Windows no quoting form is safe for both `cmd.exe` and PowerShell, so values
+  containing metacharacters are not inlined at all: the command carries a placeholder and the
+  original value is shown on a separate line marked as data rather than an executable command.
+  Unrecoverable errors under `--latest` return the root cause instead of a partial result.
+  Remote-controlled folder names and server error text are stripped of ANSI escapes and
+  control characters before they reach the plain-text stderr message. The internal `sortTime`
+  sort key no longer leaks into `drive list --depth` output on any path.

.changes/released/1.0.59-beta.1/drive-folder-sync.md

@@ -0,0 +1,15 @@
+---
+category: Added
+---
+
+- **Drive folder synchronization** — adds `dws drive status`, `dws drive pull`,
+  `dws drive push`, and `dws drive sync` for file-level comparison and transfer
+  between a local folder and a Drive folder. Differences come from exact MD5 by
+  default or from modification time with `--quick`; `status` is read-only, `pull`
+  and `push` are one-directional with `--if-exists skip|smart|overwrite`, and
+  `sync` is bidirectional with `--on-conflict remote-wins|local-wins|keep-both|ask`.
+  Only regular files are transferred — online documents and shortcuts are skipped,
+  neither side deletes extra files, downloads are staged through a temporary file
+  and committed with an atomic rename, and remote names that would escape
+  `--local-folder` are reported as failures instead of being written. Every command
+  prints a structured summary on stdout and exits non-zero when any item fails.

.changes/released/1.0.59-beta.1/global-dingtalk-region.md

@@ -0,0 +1,5 @@
+---
+category: Added
+---
+
+- **International DingTalk region support** — adds `.io` login and MCP routing, pre-release endpoint overrides, and profile-aware gateway selection while preserving the existing `.com` flow.

.changes/wiki-shortcut-alignment.md

@@ -0,0 +1,9 @@
+---
+category: Added
+---
+
+- **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.

.github/workflows/ci.yml

@@ -151,6 +151,10 @@ jobs:
                 filename.startsWith('scripts/') ||
                 filename.startsWith('verify/') ||
                 filename.startsWith('internal/helpers/') ||
+                // Shortcut declarations feed the live command tree and Schema
+                // assembly. Their reverse dependencies include the expensive
+                // app and generator packages, which must run in separate shards.
+                filename.startsWith('internal/shortcut/') ||
                 filename.startsWith('internal/generator/') ||
                 filename.startsWith('internal/cli/schema') ||
                 // Parameter aliases are reduced against the live command tree.
@@ -509,11 +513,28 @@ jobs:
         run: node .github/reviewer-routing.test.js
 
   test-focused:
-    name: Test (changed packages)
+    name: "Test (focused: ${{ matrix.shard }})"
     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
+    # Each shard owns one bounded slice of the impacted set, so no single job
+    # carries internal/app together with every reverse dependency. The shard
+    # list and per-shard execution below mirror test-race, which runs the same
+    # 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.
     timeout-minutes: 20
+    strategy:
+      fail-fast: false
+      matrix:
+        shard:
+          - app
+          - generators
+          - helpers
+          - cli
+          - smoke
+          - remaining
+          - release-scripts
     steps:
       - name: Check out repository
         uses: actions/checkout@v4
@@ -542,23 +563,77 @@ jobs:
         with:
           go-version-file: go.mod
 
-      - name: Test changed packages and reverse dependencies
+      - name: Select impacted packages for shard
+        id: select
         shell: bash
         env:
-          DWS_PACKAGE_VERSION: 0.0.0-test
+          TEST_SHARD: ${{ matrix.shard }}
         run: |
           set -euo pipefail
           package_output="$(
             ./scripts/ci/changed-test-packages.sh \
-              list "$TEST_BASE_REF" "$TEST_HEAD_REF"
+              list-shard "$TEST_SHARD" "$TEST_BASE_REF" "$TEST_HEAD_REF"
           )"
           if [ -z "$package_output" ]; then
-            echo "No buildable Go package is affected by this revision." \
+            echo "No buildable Go package in shard $TEST_SHARD is affected by this revision." \
               >> "$GITHUB_STEP_SUMMARY"
+            echo "affected=false" >> "$GITHUB_OUTPUT"
             exit 0
           fi
-          mapfile -t packages <<< "$package_output"
-          go test -v -race -count=1 -timeout=15m "${packages[@]}"
+          # The package list travels through a file rather than a step output:
+          # reading it with `mapfile < file` has unambiguous line semantics,
+          # whereas a here-string over a multi-line output would append an extra
+          # empty element if the value ever carried a trailing newline, and an
+          # empty element would reach go test as an empty package argument.
+          printf '%s\n' "$package_output" > "$RUNNER_TEMP/focused-shard-packages.txt"
+          echo "affected=true" >> "$GITHUB_OUTPUT"
+
+      - name: Build
+        if: ${{ matrix.shard == 'remaining' && steps.select.outputs.affected == 'true' }}
+        run: make build
+
+      - name: Install archive tooling
+        if: ${{ matrix.shard == 'release-scripts' && steps.select.outputs.affected == 'true' }}
+        run: sudo apt-get update && sudo apt-get install -y zip unzip
+
+      - name: Test shard with Race Detection
+        if: ${{ steps.select.outputs.affected == 'true' }}
+        shell: bash
+        env:
+          DWS_PACKAGE_VERSION: 0.0.0-test
+          TEST_SHARD: ${{ matrix.shard }}
+        run: |
+          set -euo pipefail
+          mapfile -t packages < "$RUNNER_TEMP/focused-shard-packages.txt"
+          test "${#packages[@]}" -gt 0
+          for package in "${packages[@]}"; do
+            test -n "$package" || {
+              echo "shard package list contains an empty entry" >&2
+              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
+          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.
+            go test -v -count=1 -timeout=10m "${packages[@]}"
+            exit 0
+          fi
+          # cli/smoke own heavy NewRootCommand / Schema assembly under -race;
+          # give them a dedicated package timeout on slower hosted runners.
+          timeout_budget=12m
+          if [ "$TEST_SHARD" = "cli" ] ||
+             [ "$TEST_SHARD" = "smoke" ]; then
+            timeout_budget=15m
+          fi
+          go test -v -race -count=1 -timeout="$timeout_budget" "${packages[@]}"
 
   test-race:
     name: "Test (race: ${{ matrix.shard }})"
@@ -711,7 +786,7 @@ jobs:
           failed=0
           if [ "$CHANGELOG_ONLY" = true ] || [ "$DOCS_ONLY" = true ]; then
             for shard in \
-              "changed packages:$FOCUSED_RESULT" \
+              "focused shards:$FOCUSED_RESULT" \
               "race shards:$RACE_RESULT" \
               "release scripts:$RELEASE_SCRIPTS_RESULT" \
               "cross-platform compile:$CROSS_PLATFORM_RESULT" \
@@ -740,7 +815,7 @@ jobs:
             release_expected=success
           fi
           for shard in \
-            "changed packages:$FOCUSED_RESULT:$focused_expected" \
+            "focused shards:$FOCUSED_RESULT:$focused_expected" \
             "race shards:$RACE_RESULT:$race_expected" \
             "release scripts:$RELEASE_SCRIPTS_RESULT:$release_expected" \
             "cross-platform compile:$CROSS_PLATFORM_RESULT:success"
@@ -911,7 +986,7 @@ jobs:
   coverage-current:
     name: Coverage (current)
     needs: lint
-    if: ${{ needs.lint.outputs.changelog_only != 'true' && needs.lint.outputs.docs_only != 'true' }}
+    if: ${{ needs.lint.outputs.changelog_only != 'true' && needs.lint.outputs.docs_only != 'true' && needs.lint.outputs.full_suite != 'true' }}
     runs-on: ubuntu-latest
     timeout-minutes: 20
     steps:
@@ -926,10 +1001,6 @@ jobs:
         with:
           go-version-file: go.mod
 
-      - name: Install archive tooling
-        if: needs.lint.outputs.full_suite == 'true'
-        run: sudo apt-get update && sudo apt-get install -y zip unzip
-
       - name: Resolve authoritative coverage base
         env:
           PR_HEAD_SHA: ${{ github.event.pull_request.head.sha }}
@@ -951,41 +1022,33 @@ jobs:
       - name: Build
         run: make build
 
-      - name: Run current unit tests with coverage
+      - name: Run scoped unit tests with coverage
         shell: bash
         env:
           DWS_PACKAGE_VERSION: 0.0.0-test
-          FULL_SUITE: ${{ needs.lint.outputs.full_suite }}
         run: |
           set -euo pipefail
-          if [ "$FULL_SUITE" = true ]; then
+          changed_output="$(
+            ./scripts/ci/changed-test-packages.sh \
+              changed "$COVERAGE_BASE_REF" "$COVERAGE_HEAD_REF"
+          )"
+          impacted_output="$(
+            ./scripts/ci/changed-test-packages.sh \
+              list "$COVERAGE_BASE_REF" "$COVERAGE_HEAD_REF"
+          )"
+          if [ -z "$changed_output" ] || [ -z "$impacted_output" ]; then
+            printf 'mode: atomic\n' > coverage.txt
+            echo "No buildable Go package needs scoped coverage." \
+              >> "$GITHUB_STEP_SUMMARY"
+          else
+            mapfile -t changed_packages <<< "$changed_output"
+            mapfile -t impacted_packages <<< "$impacted_output"
+            coverpkg="$(IFS=,; echo "${changed_packages[*]}")"
             go test -count=1 -p 1 \
+              -coverpkg="$coverpkg" \
               -coverprofile=coverage.txt \
               -covermode=atomic \
-              ./ ./cmd/... ./internal/... ./skills/...
-          else
-            changed_output="$(
-              ./scripts/ci/changed-test-packages.sh \
-                changed "$COVERAGE_BASE_REF" "$COVERAGE_HEAD_REF"
-            )"
-            impacted_output="$(
-              ./scripts/ci/changed-test-packages.sh \
-                list "$COVERAGE_BASE_REF" "$COVERAGE_HEAD_REF"
-            )"
-            if [ -z "$changed_output" ] || [ -z "$impacted_output" ]; then
-              printf 'mode: atomic\n' > coverage.txt
-              echo "No buildable Go package needs scoped coverage." \
-                >> "$GITHUB_STEP_SUMMARY"
-            else
-              mapfile -t changed_packages <<< "$changed_output"
-              mapfile -t impacted_packages <<< "$impacted_output"
-              coverpkg="$(IFS=,; echo "${changed_packages[*]}")"
-              go test -count=1 -p 1 \
-                -coverpkg="$coverpkg" \
-                -coverprofile=coverage.txt \
-                -covermode=atomic \
-                "${impacted_packages[@]}"
-            fi
+              "${impacted_packages[@]}"
           fi
           if [ "$(wc -l < coverage.txt)" -gt 1 ]; then
             go tool cover -func=coverage.txt
@@ -998,6 +1061,66 @@ jobs:
           path: coverage.txt
           retention-days: 1
 
+  coverage-current-full:
+    name: "Coverage (current: ${{ matrix.shard }})"
+    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
+    timeout-minutes: 20
+    strategy:
+      fail-fast: false
+      matrix:
+        shard:
+          - app
+          - cli
+          - generators
+          - helpers
+          - remaining
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.sha || github.sha }}
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+
+      - name: Install archive tooling
+        run: sudo apt-get update && sudo apt-get install -y zip unzip
+
+      - name: Build
+        run: make build
+
+      # Each shard keeps -p 1 so the authoritative measurement stays serial
+      # inside one instrumented process group; shards run on isolated runners,
+      # and scripts/ci/test-packages.sh verify proves the shard union equals
+      # the previous single full-suite package set exactly once.
+      - name: Run current shard tests with coverage
+        shell: bash
+        env:
+          DWS_PACKAGE_VERSION: 0.0.0-test
+          COVERAGE_SHARD: ${{ matrix.shard }}
+        run: |
+          set -euo pipefail
+          package_output="$(./scripts/ci/test-packages.sh list-coverage "$COVERAGE_SHARD")"
+          test -n "$package_output"
+          mapfile -t packages <<< "$package_output"
+          test "${#packages[@]}" -gt 0
+          go test -count=1 -p 1 \
+            -coverprofile="coverage-shard-$COVERAGE_SHARD.txt" \
+            -covermode=atomic \
+            "${packages[@]}"
+          go tool cover -func="coverage-shard-$COVERAGE_SHARD.txt" | tail -n 1
+
+      - name: Upload current shard coverage profile
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-current-shard-${{ matrix.shard }}
+          path: coverage-shard-${{ matrix.shard }}.txt
+          retention-days: 1
+
   coverage-supporting:
     name: Coverage (supporting)
     needs: lint
@@ -1051,14 +1174,11 @@ jobs:
           ref: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.sha || github.sha }}
 
       - name: Set up Go
+        id: setup-go
         uses: actions/setup-go@v5
         with:
           go-version-file: go.mod
 
-      - name: Install archive tooling
-        if: needs.lint.outputs.full_suite == 'true'
-        run: sudo apt-get update && sudo apt-get install -y zip unzip
-
       - name: Resolve authoritative coverage base
         env:
           PR_HEAD_SHA: ${{ github.event.pull_request.head.sha }}
@@ -1076,7 +1196,34 @@ jobs:
           git rev-parse --verify "${base_ref}^{commit}" >/dev/null
           echo "COVERAGE_BASE_REF=$base_ref" >> "$GITHUB_ENV"
 
+      # The merge-base full-suite profile is a pure function of the base
+      # commit. Reuse the profile published by the last green push run of
+      # exactly that commit instead of re-running the whole suite; any key
+      # mismatch falls back to authoritative recomputation. Exact key only,
+      # never prefix fallback: a near-miss profile would compare the
+      # candidate against the wrong commit.
+      - name: Restore cached merge-base coverage profile
+        id: baseline-cache
+        if: needs.lint.outputs.full_suite == 'true'
+        uses: actions/cache/restore@v4
+        with:
+          path: coverage-cache.txt
+          key: dws-coverage-full-v2-${{ env.COVERAGE_BASE_REF }}-go${{ steps.setup-go.outputs.go-version }}
+
+      - name: Materialize cached merge-base coverage profile
+        if: needs.lint.outputs.full_suite == 'true' && steps.baseline-cache.outputs.cache-hit == 'true'
+        run: |
+          set -eu
+          test -s coverage-cache.txt
+          test "$(head -n 1 coverage-cache.txt)" = "mode: atomic"
+          cp coverage-cache.txt coverage-base.txt
+
+      - name: Install archive tooling
+        if: needs.lint.outputs.full_suite == 'true' && steps.baseline-cache.outputs.cache-hit != 'true'
+        run: sudo apt-get update && sudo apt-get install -y zip unzip
+
       - name: Run baseline unit tests with coverage
+        if: steps.baseline-cache.outputs.cache-hit != 'true'
         shell: bash
         env:
           DWS_PACKAGE_VERSION: 0.0.0-test
@@ -1125,6 +1272,21 @@ jobs:
             fi
           )
 
+      - name: Prepare merge-base coverage profile cache
+        if: needs.lint.outputs.full_suite == 'true' && steps.baseline-cache.outputs.cache-hit != 'true'
+        run: |
+          set -eu
+          test -s coverage-base.txt
+          test "$(head -n 1 coverage-base.txt)" = "mode: atomic"
+          cp coverage-base.txt coverage-cache.txt
+
+      - name: Save merge-base coverage profile cache
+        if: needs.lint.outputs.full_suite == 'true' && steps.baseline-cache.outputs.cache-hit != 'true'
+        uses: actions/cache/save@v4
+        with:
+          path: coverage-cache.txt
+          key: dws-coverage-full-v2-${{ env.COVERAGE_BASE_REF }}-go${{ steps.setup-go.outputs.go-version }}
+
       - name: Upload baseline coverage profile
         uses: actions/upload-artifact@v4
         with:
@@ -1137,6 +1299,7 @@ jobs:
     needs:
       - lint
       - coverage-current
+      - coverage-current-full
       - coverage-supporting
       - coverage-baseline
       - coverage-darwin
@@ -1152,6 +1315,7 @@ jobs:
           FULL_SUITE: ${{ needs.lint.outputs.full_suite }}
           PLATFORM_SENSITIVE: ${{ needs.lint.outputs.platform_sensitive }}
           CURRENT_RESULT: ${{ needs.coverage-current.result }}
+          CURRENT_FULL_RESULT: ${{ needs.coverage-current-full.result }}
           SUPPORTING_RESULT: ${{ needs.coverage-supporting.result }}
           BASELINE_RESULT: ${{ needs.coverage-baseline.result }}
           DARWIN_RESULT: ${{ needs.coverage-darwin.result }}
@@ -1159,6 +1323,7 @@ jobs:
         run: |
           failed=0
           current_expected=success
+          current_full_expected=skipped
           supporting_expected=skipped
           baseline_expected=success
           native_expected=skipped
@@ -1166,6 +1331,8 @@ jobs:
             current_expected=skipped
             baseline_expected=skipped
           elif [ "$FULL_SUITE" = true ]; then
+            current_expected=skipped
+            current_full_expected=success
             supporting_expected=success
           fi
           if [ "$CHANGELOG_ONLY" != true ] &&
@@ -1176,6 +1343,7 @@ jobs:
 
           for profile in \
             "current:$CURRENT_RESULT:$current_expected" \
+            "current shards:$CURRENT_FULL_RESULT:$current_full_expected" \
             "supporting:$SUPPORTING_RESULT:$supporting_expected" \
             "baseline:$BASELINE_RESULT:$baseline_expected"
           do
@@ -1211,6 +1379,7 @@ jobs:
           ref: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.sha || github.sha }}
 
       - name: Set up Go
+        id: setup-go
         if: needs.lint.outputs.changelog_only != 'true' && needs.lint.outputs.docs_only != 'true'
         uses: actions/setup-go@v5
         with:
@@ -1234,11 +1403,12 @@ jobs:
           git rev-parse --verify "${base_ref}^{commit}" >/dev/null
           echo "COVERAGE_BASE_REF=$base_ref" >> "$GITHUB_ENV"
 
-      - name: Download current coverage profile
+      - name: Download current coverage profiles
         if: needs.lint.outputs.changelog_only != 'true' && needs.lint.outputs.docs_only != 'true'
         uses: actions/download-artifact@v4
         with:
-          name: coverage-current-profile
+          pattern: coverage-current-*
+          merge-multiple: true
           path: .
 
       - name: Download supporting coverage profiles
@@ -1255,6 +1425,26 @@ jobs:
           name: coverage-baseline-profile
           path: .
 
+      # Shard profiles cover disjoint package sets, so their block-level
+      # concatenation is the same candidate profile one serial run produced.
+      # Every expected shard must be present; a missing shard would silently
+      # shrink the scope-matched overall comparison.
+      - name: Assemble full-suite coverage profile
+        if: needs.lint.outputs.changelog_only != 'true' && needs.lint.outputs.docs_only != 'true' && needs.lint.outputs.full_suite == 'true'
+        shell: bash
+        run: |
+          set -euo pipefail
+          test ! -f coverage.txt
+          for shard in app cli generators helpers remaining; do
+            profile="coverage-shard-$shard.txt"
+            test -f "$profile"
+            test "$(head -n 1 "$profile")" = "mode: atomic"
+          done
+          printf 'mode: atomic\n' > coverage.txt
+          for shard in app cli generators helpers remaining; do
+            tail -n +2 "coverage-shard-$shard.txt" >> coverage.txt
+          done
+
       - name: Enforce coverage gate
         if: needs.lint.outputs.changelog_only != 'true' && needs.lint.outputs.docs_only != 'true'
         env:
@@ -1275,6 +1465,26 @@ jobs:
           COVERAGE_ADDITIONAL_DIFF_PROFILE="$additional_profile" \
             make coverage-gate BASE_REF="$COVERAGE_BASE_REF"
 
+      # Publish this push's full-suite profile as the merge-base cache for
+      # future PRs whose merge-base is exactly this commit. Saved only after
+      # the gate passed so a broken run never becomes a baseline. Both producer
+      # and consumer use coverage-cache.txt because the cache version includes
+      # the configured path as well as the compression tool.
+      - name: Prepare push coverage profile as merge-base cache
+        if: github.event_name == 'push' && needs.lint.outputs.changelog_only != 'true' && needs.lint.outputs.docs_only != 'true' && needs.lint.outputs.full_suite == 'true'
+        run: |
+          set -eu
+          test -s coverage.txt
+          test "$(head -n 1 coverage.txt)" = "mode: atomic"
+          cp coverage.txt coverage-cache.txt
+
+      - name: Save push coverage profile as merge-base cache
+        if: github.event_name == 'push' && needs.lint.outputs.changelog_only != 'true' && needs.lint.outputs.docs_only != 'true' && needs.lint.outputs.full_suite == 'true'
+        uses: actions/cache/save@v4
+        with:
+          path: coverage-cache.txt
+          key: dws-coverage-full-v2-${{ github.sha }}-go${{ steps.setup-go.outputs.go-version }}
+
       - name: Generate coverage report
         if: needs.lint.outputs.changelog_only != 'true' && needs.lint.outputs.docs_only != 'true'
         run: |

.gitignore

@@ -20,6 +20,10 @@ test/cli_compat/testdata/
 .gitignore
 .worktrees/
 .qoder/
+_logs/
+_docs/
+_output/
+vendor/
 
 # Secrets & credentials
 .env

CHANGELOG.md

@@ -6,6 +6,70 @@ The format is inspired by [Keep a Changelog](https://keepachangelog.com/) and th
 
 ## [Unreleased]
 
+## [1.0.59-beta.1] - 2026-08-14
+
+### Added
+
+- **Drive list type/time filtering** (#942) — `dws drive list` gains `--type
+  file|folder`, `--start`, and `--end` for client-side filtering by node type
+  and modification time on both the pan and workspace routes. Filtering runs
+  a bounded full scan of the target directory (2000-entry cap, reported via
+  `truncated=true`), composes with `--latest`/`--pattern`/`--depth`, and is
+  mutually exclusive with `--versions`/`--cursor`/`--order-by`/`--order`/
+  `--limit`. Time values accept relative forms (`24h`/`7d`/`2w`), RFC 3339,
+  zone-less ISO 8601 (Asia/Shanghai), or a plain date.
+
+- **Drive folder synchronization** — adds `dws drive status`, `dws drive pull`,
+  `dws drive push`, and `dws drive sync` for file-level comparison and transfer
+  between a local folder and a Drive folder. Differences come from exact MD5 by
+  default or from modification time with `--quick`; `status` is read-only, `pull`
+  and `push` are one-directional with `--if-exists skip|smart|overwrite`, and
+  `sync` is bidirectional with `--on-conflict remote-wins|local-wins|keep-both|ask`.
+  Only regular files are transferred — online documents and shortcuts are skipped,
+  neither side deletes extra files, downloads are staged through a temporary file
+  and committed with an atomic rename, and remote names that would escape
+  `--local-folder` are reported as failures instead of being written. Every command
+  prints a structured summary on stdout and exits non-zero when any item fails.
+
+- **International DingTalk region support** — adds `.io` login and MCP routing, pre-release endpoint overrides, and profile-aware gateway selection while preserving the existing `.com` flow.
+
+### Changed
+
+- **Chat identity routing** — validates explicit `openDingTalkId` inputs and improves name, `userId`, and `openDingTalkId` routing for message shortcuts.
+
+### Fixed
+
+- **Drive `--latest` refuses incomplete Top-N** (#899) — `dws drive list --latest` used to
+  exit 0 with a "Top-N" computed over a partially scanned tree whenever a directory read
+  failed mid-recursion (permission denied, API error), letting an incomplete set pose as the
+  globally newest files. Truncation at the 2000-item scan cap and mid-recursion directory
+  failures now both fail closed (`LATEST_SCAN_TRUNCATED` / `LATEST_SCAN_INCOMPLETE`), report
+  the first failing folder with its depth and reason, and emit a recovery command that
+  reproduces the original candidate set — query domain, `--folder`, `--pattern`, `--type`,
+  `--start` and `--end` are all carried over. On POSIX shells each user-supplied value is
+  quoted so a URL query string or a shell metacharacter cannot change how the copied command
+  parses. On Windows no quoting form is safe for both `cmd.exe` and PowerShell, so values
+  containing metacharacters are not inlined at all: the command carries a placeholder and the
+  original value is shown on a separate line marked as data rather than an executable command.
+  Unrecoverable errors under `--latest` return the root cause instead of a partial result.
+  Remote-controlled folder names and server error text are stripped of ANSI escapes and
+  control characters before they reach the plain-text stderr message. The internal `sortTime`
+  sort key no longer leaks into `drive list --depth` output on any path.
+
+- **Drive list pattern filtering** (#942) — `dws drive list --pattern` on the
+  single-layer pan route now filters the returned page by name pattern; the
+  flag was previously accepted but silently ignored.
+
+- **Drive list `--type folder --latest` composition** (#942) — `--latest` now
+  ranks the filtered entries (folders included when `--type folder` is set)
+  instead of unconditionally dropping folders, so the documented combination
+  returns the most recently modified folders rather than an empty list.
+
+- **Chat message time defaults** (#973) — default omitted `chat message list-all` time bounds in `Asia/Shanghai` when emitting timezone-less `yyyy-MM-dd HH:mm:ss` values, matching parsing semantics and rejecting reversed windows.
+
+- **Doc and Drive parameter aliases** — normalizes reviewed identifier, pagination, path, version, and role synonyms while blocking ambiguous values before dispatch.
+
+
 ## [1.0.58] - 2026-08-13
 
 This release promotes the sealed `v1.0.58-beta.6` contents to stable.

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.58-beta.6"
+  version "1.0.59-beta.1"
   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.58-beta.6/dws-darwin-arm64.tar.gz"
-      sha256 "8f55497b84113f81b318e087c723016a02eded1cb5784cbd0811fe527d5852ca"
+      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.59-beta.1/dws-darwin-arm64.tar.gz"
+      sha256 "36a30f3496e0f759c15c0b09f67dbd23b8ecdfff2eebe572f88125b26485830f"
     else
-      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.58-beta.6/dws-darwin-amd64.tar.gz"
-      sha256 "b1762f1640310fb4100634fe54d9baace46384bb270c59148fe306275554d491"
+      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.59-beta.1/dws-darwin-amd64.tar.gz"
+      sha256 "e7a04906380efd8da88cd112e6a512bb6470a3956dc370150037ed6e314db445"
     end
   end
 
   on_linux do
     if Hardware::CPU.arm?
-      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.58-beta.6/dws-linux-arm64.tar.gz"
-      sha256 "55393310ef0e1f24ea2c0dc22f00c0eb3b343edc2deb18d0db7838cda65af25d"
+      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.59-beta.1/dws-linux-arm64.tar.gz"
+      sha256 "f59ab055f3e841e4cebc964ae3ef969668475548abaaf8bede44afdca9a3e28d"
     else
-      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.58-beta.6/dws-linux-amd64.tar.gz"
-      sha256 "3830f77d09b4da4aa39f0c08d772ff3fa1ffb837eb15bb417f97edbccb073b7d"
+      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.59-beta.1/dws-linux-amd64.tar.gz"
+      sha256 "2c8f919489d958c7d49262615e81faac70a9fbcae2d589ab54a0bb3c5700a057"
     end
   end
 
   resource "skills" do
-    url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.58-beta.6/dws-skills.zip"
-    sha256 "f304a883a4f9e938b26a44692cd5a8d3d8704ba70ee7f33ba7c288434da72b6f"
+    url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.59-beta.1/dws-skills.zip"
+    sha256 "25f4a7e1d01fa4d771d79201b34b11ee8a24182bdcdc94bfb98d2bd5845bed3b"
   end
 
   def install

Makefile

@@ -18,7 +18,7 @@ help:
 	@printf "Available targets:\n"
 	@printf "  make build         - Build the dws CLI binary\n"
 	@printf "  make test          - Run the Go test suite\n"
-	@printf "  make test-plan     - Verify every default Go package belongs to one CI test shard\n"
+	@printf "  make test-plan     - Verify CI test and full-suite coverage package plans cover their scopes exactly once\n"
 	@printf "  make test-auth-legacy-compat - Run stable legacy authentication compatibility regressions\n"
 	@printf "  make lint          - Run formatting checks, go vet, and staticcheck\n"
 	@printf "  make format-check  - Check all repository Go source files with gofmt\n"

README.md

@@ -786,6 +786,7 @@ See [`docs/robot-quickstart.md`](./docs/robot-quickstart.md) for the full 4-step
 
 ## Reference & Docs
 
+- [International DingTalk (`.io`) guide](./docs/international-region-guide.md) — international login, domestic/international profile switching, isolated testing, and troubleshooting
 - [Command Index](./docs/command-index.md) — every runtime command with description and when-to-use guidance
 - [Reference](./docs/reference.md) — environment variables, exit codes, output formats, shell completion
 - [Architecture](./docs/architecture.md) — static endpoint pipeline, command surface, transport layer

README_zh.md

@@ -777,6 +777,7 @@ dws dev connect --channel auto --robot-client-id <id> --robot-client-secret <sec
 
 ## 参考与文档
 
+- [国际版（`.io`）使用手册](./docs/international-region-guide.zh-CN.md) — 国际版登录、国内/国际 profile 切换、隔离验证与排障
 - [命令索引](./docs/command-index.md) — 全部运行时命令，带描述与使用场景
 - [参考手册](./docs/reference.md) — 环境变量、退出码、输出格式、Shell 补全
 - [架构设计](./docs/architecture.md) — 静态端点管道、命令面、Transport 层

cmd/main.go

@@ -15,12 +15,76 @@ package main
 
 import (
 	"os"
+	"strings"
 
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/app"
+	"gitlab.alibaba-inc.com/aes/aem-go-sdk/clitrack"
 )
 
-var exit = os.Exit
+var (
+	appExecute               = app.ExecuteWithTelemetry
+	resolveTelemetryIdentity = app.ResolveTelemetryIdentity
+	trackRun                 = func(cfg clitrack.Config, execute func() error, exitCode func(error) int) {
+		clitrack.New(cfg).Run(execute, exitCode)
+	}
+)
+
+// trackedExitError tells clitrack that the command failed without asking it to
+// print the error a second time. The already-rendered message is published via
+// ExtraFields c5, while app.Execute remains the sole owner of presentation.
+type trackedExitError struct{}
+
+func (trackedExitError) Error() string { return "" }
+
+func trackerConfig(identity app.TelemetryIdentity, commandPath, errorMessage *string) clitrack.Config {
+	return clitrack.Config{
+		PID:                   "wcCRwZ",
+		App:                   "dws",
+		Version:               app.RawVersion(),
+		UID:                   identity.UserID,
+		Username:              identity.UserName,
+		NoCommandLine:         true,
+		NoCwd:                 true,
+		NoAutomaticDimensions: true,
+		ExtraFields: func() map[string]string {
+			fields := map[string]string{"c9": *commandPath}
+			if identity.CorpID != "" {
+				fields["c10"] = identity.CorpID
+			}
+			if *errorMessage != "" {
+				fields["c5"] = *errorMessage
+			}
+			return fields
+		},
+	}
+}
+
+func telemetryOptedOut() bool {
+	return strings.TrimSpace(os.Getenv("DO_NOT_TRACK")) != ""
+}
 
 func main() {
-	exit(app.Execute())
+	optedOut := telemetryOptedOut()
+	identity := app.TelemetryIdentity{}
+	if !optedOut {
+		identity = resolveTelemetryIdentity(os.Args[1:])
+	}
+	exitCode := 0
+	commandPath := "dws"
+	errorMessage := ""
+	cfg := trackerConfig(identity, &commandPath, &errorMessage)
+	if optedOut {
+		cfg.PID = ""
+	}
+	trackRun(
+		cfg,
+		func() error {
+			exitCode, commandPath, errorMessage = appExecute()
+			if exitCode != 0 {
+				return trackedExitError{}
+			}
+			return nil
+		},
+		func(error) int { return exitCode },
+	)
 }

cmd/main_test.go

@@ -1,27 +1,220 @@
 package main
 
 import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
 	"os"
+	"slices"
+	"sort"
+	"strings"
 	"testing"
+	"time"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/app"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam"
+	"gitlab.alibaba-inc.com/aes/aem-go-sdk/clitrack"
 )
 
-func TestCrossPlatformCoverageMainExitsWithSuccessfulVersionCommand(t *testing.T) {
-	previousExit := exit
-	previousArgs := os.Args
-	t.Cleanup(func() {
-		exit = previousExit
-		os.Args = previousArgs
-	})
+func TestCrossPlatformCoverageMainRunsThroughCLITracker(t *testing.T) {
+	for _, wantCode := range []int{0, 1, 3, 5} {
+		t.Run(fmt.Sprintf("exit_%d", wantCode), func(t *testing.T) {
+			t.Setenv("DO_NOT_TRACK", "")
+			wantError := ""
+			if wantCode != 0 {
+				wantError = "synthetic failure"
+			}
+			testseam.Swap(t, &os.Args, []string{"dws", "sheet", "read", "--profile", "corp-a"})
+			testseam.Swap(t, &resolveTelemetryIdentity, func(args []string) app.TelemetryIdentity {
+				if strings.Join(args, " ") != "sheet read --profile corp-a" {
+					t.Fatalf("telemetry identity args = %#v", args)
+				}
+				return app.TelemetryIdentity{UserID: "user-1", UserName: "Alice", CorpID: "corp-1"}
+			})
+			testseam.Swap(t, &appExecute, func() (int, string, string) { return wantCode, "sheet read", wantError })
+			called := false
+			testseam.Swap(t, &trackRun, func(cfg clitrack.Config, execute func() error, exitCode func(error) int) {
+				called = true
+				if cfg.PID != "wcCRwZ" || cfg.App != "dws" {
+					t.Fatalf("tracker identity = PID %q App %q", cfg.PID, cfg.App)
+				}
+				if cfg.Version != app.RawVersion() {
+					t.Fatalf("tracker Version = %q, want %q", cfg.Version, app.RawVersion())
+				}
+				if !cfg.NoCommandLine || !cfg.NoCwd || !cfg.NoAutomaticDimensions || cfg.CaptureOutput {
+					t.Fatalf("tracker privacy config = NoCommandLine %v NoCwd %v NoAutomaticDimensions %v CaptureOutput %v", cfg.NoCommandLine, cfg.NoCwd, cfg.NoAutomaticDimensions, cfg.CaptureOutput)
+				}
+				if cfg.Env != "" || cfg.EventID != "" || cfg.Endpoint != "" || cfg.FlushTimeout != 0 || cfg.OutputMaxLen != 0 {
+					t.Fatalf("tracker SDK defaults were overridden: %#v", cfg)
+				}
+				if cfg.UID != "user-1" || cfg.Username != "Alice" || cfg.UserType != "" {
+					t.Fatalf("tracker user identity = UID %q Username %q UserType %q", cfg.UID, cfg.Username, cfg.UserType)
+				}
 
+				err := execute()
+				if wantCode == 0 && err != nil {
+					t.Fatalf("successful tracked execute error = %v", err)
+				}
+				if wantCode != 0 && (err == nil || err.Error() != "") {
+					t.Fatalf("failed tracked execute error = %#v, want empty sentinel", err)
+				}
+				if gotCode := exitCode(err); gotCode != wantCode {
+					t.Fatalf("tracked exit code = %d, want %d", gotCode, wantCode)
+				}
+				fields := cfg.ExtraFields()
+				if fields["c9"] != "sheet read" || fields["c10"] != "corp-1" || fields["c5"] != wantError {
+					t.Fatalf("tracker extra fields = %#v, want command path, corp ID, and error %q", fields, wantError)
+				}
+				if (wantError == "" && len(fields) != 2) || (wantError != "" && len(fields) != 3) {
+					t.Fatalf("tracker extra field count = %d for error %q", len(fields), wantError)
+				}
+			})
+
+			main()
+			if !called {
+				t.Fatalf("trackRun was not called for exit code %d", wantCode)
+			}
+		})
+	}
+}
+
+func TestCrossPlatformCoverageTrackerConfigOmitsEmptyOrganization(t *testing.T) {
+	commandPath := "version"
+	errorMessage := ""
+	cfg := trackerConfig(app.TelemetryIdentity{}, &commandPath, &errorMessage)
+	if cfg.UID != "" {
+		t.Fatalf("empty identity UID = %q", cfg.UID)
+	}
+	if cfg.Username != "" {
+		t.Fatalf("empty identity Username = %q", cfg.Username)
+	}
+	if fields := cfg.ExtraFields(); len(fields) != 1 || fields["c9"] != "version" {
+		t.Fatalf("empty organization fields = %#v", fields)
+	}
+}
+
+func TestCrossPlatformCoverageDefaultTrackRunNoopTracker(t *testing.T) {
 	called := false
-	code := -1
-	exit = func(value int) {
+	trackRun(clitrack.Config{}, func() error {
 		called = true
-		code = value
+		return nil
+	}, nil)
+	if !called {
+		t.Fatal("default tracker did not execute callback")
 	}
-	os.Args = []string{"dws", "version"}
+}
+
+func TestCrossPlatformCoverageMainRespectsDoNotTrack(t *testing.T) {
+	t.Setenv("DO_NOT_TRACK", "1")
+	testseam.Swap(t, &os.Args, []string{"dws", "version"})
+	testseam.Swap(t, &resolveTelemetryIdentity, func([]string) app.TelemetryIdentity {
+		t.Fatal("DO_NOT_TRACK must skip telemetry identity reads")
+		return app.TelemetryIdentity{}
+	})
+	testseam.Swap(t, &appExecute, func() (int, string, string) { return 0, "version", "" })
+	testseam.Swap(t, &trackRun, func(cfg clitrack.Config, execute func() error, exitCode func(error) int) {
+		if cfg.PID != "" || cfg.UID != "" || cfg.Username != "" {
+			t.Fatalf("opted-out tracker config = %#v", cfg)
+		}
+		if err := execute(); err != nil {
+			t.Fatalf("opted-out execution failed: %v", err)
+		}
+		if code := exitCode(nil); code != 0 {
+			t.Fatalf("opted-out exit code = %d, want 0", code)
+		}
+	})
+
 	main()
-	if !called || code != 0 {
-		t.Fatalf("main exit = called %v, code %d", called, code)
+}
+
+func TestCrossPlatformCoverageTrackerPayloadUsesReviewedFieldWhitelist(t *testing.T) {
+	testseam.Protect(t, &os.Args)
+	os.Args = []string{"dws", "sheet", "read", "--access-token", "must-not-leak"}
+	t.Setenv("SHELL", "/bin/zsh")
+	t.Setenv("TERM_SESSION_ID", "stable-session")
+	t.Setenv("TMUX_PANE", "%42")
+	t.Setenv("LANG", "zh_CN.UTF-8")
+	t.Setenv("LC_ALL", "zh_CN.UTF-8")
+	t.Chdir(t.TempDir())
+
+	requestBody := make(chan []byte, 1)
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) {
+		body, _ := io.ReadAll(req.Body)
+		requestBody <- body
+		w.WriteHeader(http.StatusNoContent)
+	}))
+	defer server.Close()
+
+	commandPath := "sheet read"
+	errorMessage := ""
+	cfg := trackerConfig(app.TelemetryIdentity{UserID: "user-1", UserName: "Alice", CorpID: "corp-1"}, &commandPath, &errorMessage)
+	cfg.Endpoint = server.URL
+	cfg.FlushTimeout = time.Second
+	clitrack.New(cfg).Run(func() error { return nil }, nil)
+
+	var body []byte
+	select {
+	case body = <-requestBody:
+	case <-time.After(time.Second):
+		t.Fatal("timed out waiting for telemetry request")
+	}
+	var envelope map[string]string
+	if err := json.Unmarshal(body, &envelope); err != nil {
+		t.Fatalf("decode telemetry request %q: %v", body, err)
+	}
+	decoded, err := url.QueryUnescape(envelope["gokey"])
+	if err != nil {
+		t.Fatalf("decode gokey: %v", err)
+	}
+	globalFields, err := url.ParseQuery(decoded)
+	if err != nil {
+		t.Fatalf("parse global telemetry fields: %v", err)
+	}
+	eventFields, err := url.ParseQuery(globalFields.Get("msg"))
+	if err != nil {
+		t.Fatalf("parse event telemetry fields: %v", err)
+	}
+
+	assertTelemetryKeys(t, globalFields, []string{"app_name", "app_version", "env", "msg", "pid", "platform", "uid", "username", "version"})
+	assertTelemetryKeys(t, eventFields, []string{"c1", "c10", "c3", "c4", "c9", "p1", "p4", "ts", "type"})
+	for key, want := range map[string]string{
+		"app_name": "dws", "app_version": app.RawVersion(), "env": "prod", "pid": "wcCRwZ",
+		"platform": "cli", "uid": "user-1", "username": "Alice", "version": app.RawVersion(),
+	} {
+		if got := globalFields.Get(key); got != want {
+			t.Fatalf("global telemetry field %s = %q, want %q", key, got, want)
+		}
+	}
+	for key, want := range map[string]string{
+		"type": "event", "p1": "cli.exec", "p4": "SYS", "c1": "dws", "c3": "0", "c9": "sheet read", "c10": "corp-1",
+	} {
+		if got := eventFields.Get(key); got != want {
+			t.Fatalf("event telemetry field %s = %q, want %q", key, got, want)
+		}
+	}
+	for _, key := range []string{"device_id", "ext", "os", "os_version", "pv_id", "sdk_version", "sid", "timezone_offset"} {
+		if globalFields.Has(key) {
+			t.Fatalf("global telemetry leaked %s: %q", key, decoded)
+		}
+	}
+	for _, key := range []string{"c2", "c5", "c6", "c7", "c8"} {
+		if eventFields.Has(key) {
+			t.Fatalf("event telemetry leaked %s: %q", key, globalFields.Get("msg"))
+		}
+	}
+}
+
+func assertTelemetryKeys(t *testing.T, fields url.Values, want []string) {
+	t.Helper()
+	got := make([]string, 0, len(fields))
+	for key := range fields {
+		got = append(got, key)
+	}
+	sort.Strings(got)
+	if !slices.Equal(got, want) {
+		t.Fatalf("telemetry keys = %v, want %v", got, want)
 	}
 }

docs/ci-pr-gates.md

@@ -201,8 +201,21 @@ base_ref=$(git merge-base HEAD origin/main)
 standard PR, CI derives changed packages and their reverse-dependency test
 closure, then generates candidate and merge-base profiles with the same test
 scope and `coverpkg`. High-risk and protected-main runs use the complete
-profiles. Supporting and (when platform-selected) native profiles are
-generated before the aggregate `Coverage` context evaluates them. The
+profiles. The complete candidate profile is produced by disjoint per-shard
+helper jobs (`scripts/ci/test-packages.sh list-coverage`, kept serial with
+`-p 1` inside each shard; `verify` proves the shard union equals the
+full-suite scope exactly once) and concatenated in the aggregate job before
+enforcement. The complete merge-base profile is restored from an exact-key
+cache written by the last green `main` push of that same commit (key:
+merge-base SHA plus resolved Go version); any miss falls back to recomputing
+it in a merge-base worktree. The trusted `main` producer and PR consumer use
+the same dedicated cache profile path because GitHub includes that path in the
+cache version; the runtime-facing candidate and baseline filenames remain
+separate. Near-miss reuse is forbidden — the caches carry no prefix restore
+keys, because a neighbouring commit's profile would compare the candidate
+against the wrong baseline. Supporting and (when
+platform-selected) native profiles are generated before the aggregate
+`Coverage` context evaluates them. The
 aggregate and native gates require 100% coverage for changed executable Go
 statements. Overall coverage remains an unrounded, zero-tolerance,
 scope-matched merge-base non-regression check. Candidate and baseline profiles

docs/flag-help-schema-homology.md

@@ -92,6 +92,7 @@ command/Leaf 不再写 `dws.schema.risk`；SafetySpec 走类型化 Final 载荷
 | `Required` / `MarkRequired` | 非空校验 / cobra 硬必填 | 是（`required`） |
 | `RequiredHint`, `Aliases`, `EnvVar` | 校验提示、隐藏别名、环境回退 | 否（执行细节；别名不上主 parameter 表） |
 | `ArgDefault`, `Bind`, `OmitEmpty`, `Trim`, `Transform` | toolArgs 装配语义 | 否（载荷细节；`Bind` 可进 property 映射，但不另造 flag） |
+| `Input` | 额外取值来源：`@path` 读文件 / `-` 读 stdin，在 required/enum/约束/`Validate` 之前原地解析 | 否（今日：能力由作者写进 `Usage` / `SchemaDescription` 文案，是已声明事实而非推断；不另造 flag。目标形态收敛为类型化投影字段，见 RFC §5.3） |
 
 #### 1.2.2 编排 / 执行字段（不算声明）
 

docs/international-region-guide.md

@@ -0,0 +1,154 @@
+# International DingTalk (`.io`) Guide
+
+This guide explains how to log in to the international DingTalk region and run DWS commands against `*.dingtalk.io` services.
+
+## Region behavior
+
+- `dws auth login --intl` creates or refreshes an international login using the `.io` login, OAuth, and MCP services.
+- Omitting `--intl` keeps the existing domestic `.com` behavior.
+- `--intl` is a login option, not a global option for business commands. After login, commands such as `contact`, `calendar`, and `doc` derive the region from the selected Token/profile.
+- Each new Token records its login region. Switching profiles therefore switches the official DingTalk gateway region automatically.
+- `--international` is a compatibility alias. Prefer `--intl` in new scripts.
+
+For the complete Chinese guide, see [DWS 国际版（DingTalk `.io`）使用手册](./international-region-guide.zh-CN.md).
+
+## Check availability
+
+```bash
+dws auth login --help
+```
+
+The help output must include `--intl` and `--international`.
+
+When validating a source checkout, build it first and use `./dws` so an older binary on `PATH` is not invoked accidentally:
+
+```bash
+make build
+./dws auth login --help
+```
+
+## Log in
+
+Browser login:
+
+```bash
+dws auth login --intl
+```
+
+Device flow for SSH, containers, and headless environments:
+
+```bash
+dws auth login --intl --device
+```
+
+User OAuth with custom application credentials:
+
+```bash
+dws auth login --intl \
+  --client-id <APP_KEY> \
+  --client-secret <APP_SECRET>
+```
+
+This mode still requires the user to complete OAuth authorization in a browser; it is not a userless `client_credentials` login. The application must be configured on the international developer platform with the required callback and permissions. Never commit an AppSecret to source control or include it in logs.
+
+## Verify the login
+
+```bash
+dws auth status --format json
+dws profile list --format json
+dws contact user get-self
+```
+
+The last command is a read-only smoke check. If the organization has not enabled CLI access, an organization administrator must enable it or approve the access request on the international developer platform.
+
+## Use domestic and international profiles together
+
+```bash
+# Domestic (.com)
+dws auth login
+
+# International (.io)
+dws auth login --intl
+
+# Find the stable profile selectors
+dws profile list --format json
+```
+
+Persistently switch profiles:
+
+```bash
+dws profile switch <corpId>:<userId>
+```
+
+Toggle back to the previous profile:
+
+```bash
+dws profile switch -
+```
+
+Select a profile for one command without changing the default:
+
+```bash
+dws --profile <corpId>:<userId> contact user get-self
+```
+
+Do not add `--intl` to business commands. DWS routes official endpoints from the selected profile's Token region.
+
+## Isolated smoke testing
+
+Use a separate configuration directory to avoid changing the normal `~/.dws` login state:
+
+```bash
+DWS_CONFIG_DIR=/tmp/dws-intl-smoke ./dws auth login --intl
+DWS_CONFIG_DIR=/tmp/dws-intl-smoke ./dws auth status --format json
+DWS_CONFIG_DIR=/tmp/dws-intl-smoke ./dws contact user get-self
+```
+
+Use the same `DWS_CONFIG_DIR` for every command. Use `./dws` for a source build and `dws` for an installed release.
+
+## Pre-release overrides (maintainers only)
+
+Normal international users need only `--intl`; they should not set `--pre-url` or `--mcp-url`.
+
+Maintainers can test the pre-release login/MCP pair with:
+
+```bash
+dws auth login --intl --pre-url https://pre-login.dingtalk.io
+```
+
+A corresponding `pre-mcp.*` URL is also accepted, and DWS derives the paired `pre-login.*` / `pre-mcp.*` bases. `--mcp-url` explicitly overrides the MCP base URL for that login.
+
+Pre-release services may require internal network access or allowlisted accounts. `--pre-url` is intended primarily for the MCP-managed credential flow. Do not combine it with direct custom `--client-id/--client-secret` mode unless the pre-release API contract explicitly supports that combination.
+
+## Troubleshooting
+
+### The browser still opens a `.com` page
+
+1. Run `dws auth login --help` and confirm `--intl` is present.
+2. For a source checkout, use `./dws` instead of an older installed binary.
+3. Confirm the executed command is `dws auth login --intl`.
+
+### A business command appears to use the wrong region
+
+Run `dws profile list --format json`, then switch with the exact `<corpId>:<userId>` selector or use the global `--profile` option. For a legacy Token created before region metadata existed, reauthorize it with `dws auth login --intl` for an international account or `dws auth login` for a domestic account.
+
+### Login succeeds but the command reports missing permission
+
+This normally means the organization has not enabled CLI access or the application lacks a required permission. It does not by itself indicate a region-routing failure.
+
+### Should I edit `~/.dws/mcp_url` manually?
+
+No. Normal users should establish the login with `dws auth login` or `dws auth login --intl`. DWS then routes official endpoints from the selected Token/profile. Manual configuration is reserved for maintainers who explicitly control the target environment.
+
+## Command reference
+
+| Scenario | Command |
+|---|---|
+| Domestic browser login | `dws auth login` |
+| International browser login | `dws auth login --intl` |
+| International device login | `dws auth login --intl --device` |
+| Check auth state | `dws auth status --format json` |
+| List profiles | `dws profile list --format json` |
+| Persistently switch profile | `dws profile switch <corpId>:<userId>` |
+| Toggle to previous profile | `dws profile switch -` |
+| Select a profile once | `dws --profile <corpId>:<userId> <command>` |

docs/international-region-guide.zh-CN.md

@@ -0,0 +1,185 @@
+# DWS 国际版（DingTalk `.io`）使用手册
+
+本手册适用于使用钉钉国际版账号登录并调用国际站服务的用户。
+
+## 核心规则
+
+- `dws auth login --intl` 创建或刷新国际版登录，使用 `*.dingtalk.io` 登录、鉴权和 MCP 服务。
+- 不传 `--intl` 时仍使用国内钉钉 `*.dingtalk.com`，原有链路保持不变。
+- `--intl` 只用于登录命令。登录完成后，`contact`、`calendar`、`doc` 等业务命令不需要再传该参数。
+- 每个 Token 会记录登录区域。执行业务命令时，DWS 根据当前或 `--profile` 指定的账号自动选择 `.com` 或 `.io` 网关。
+- `--international` 是 `--intl` 的兼容别名；新脚本推荐使用较短的 `--intl`。
+
+## 确认当前版本支持国际版
+
+运行：
+
+```bash
+dws auth login --help
+```
+
+帮助中应包含：
+
+```text
+--intl
+--international
+```
+
+从源码分支验证时，先在仓库根目录构建，并始终使用本次构建的 `./dws`，避免误用系统中已安装的旧版本：
+
+```bash
+make build
+./dws auth login --help
+```
+
+## 国际版登录
+
+### 浏览器登录
+
+```bash
+dws auth login --intl
+```
+
+DWS 会打开国际版登录页面。完成扫码或账号授权后，登录结果会保存为本机 profile。
+
+### 设备码登录
+
+适用于 SSH、容器或没有可用浏览器的环境：
+
+```bash
+dws auth login --intl --device
+```
+
+按照终端提示，在另一台可打开浏览器的设备上完成授权。
+
+### 使用自有应用凭证完成用户 OAuth
+
+```bash
+dws auth login --intl \
+  --client-id <APP_KEY> \
+  --client-secret <APP_SECRET>
+```
+
+该模式仍然需要用户在浏览器中完成 OAuth 授权，不是无用户授权的 `client_credentials` 登录。应用必须在国际版开放平台正确配置回调地址和所需权限。不要在命令历史、日志或 PR 中提交真实的 AppSecret。
+
+## 验证登录和业务调用
+
+查看当前登录状态：
+
+```bash
+dws auth status --format json
+```
+
+列出本机全部账号并找到当前 profile：
+
+```bash
+dws profile list --format json
+```
+
+执行一个只读命令验证国际链路，例如：
+
+```bash
+dws contact user get-self
+```
+
+登录状态正常但业务命令提示组织未开通 CLI 时，需要由国际版组织管理员在国际版开发者平台开启 CLI 访问或完成授权审批。
+
+## 国内版和国际版账号并存
+
+可以在同一台机器上分别登录国内版和国际版账号：
+
+```bash
+# 国内版（.com）
+dws auth login
+
+# 国际版（.io）
+dws auth login --intl
+
+# 查看稳定的 profile 选择器
+dws profile list --format json
+```
+
+持久切换账号：
+
+```bash
+dws profile switch <corpId>:<userId>
+```
+
+切回上一个账号：
+
+```bash
+dws profile switch -
+```
+
+只为单次命令指定账号，不修改默认账号：
+
+```bash
+dws --profile <corpId>:<userId> contact user get-self
+```
+
+DWS 会按照选中 profile 的 Token 区域自动选择 `.com` 或 `.io`，不需要在业务命令上追加 `--intl`。
+
+## 使用独立配置目录进行验证
+
+如果不希望测试登录影响日常使用的 `~/.dws`，可以指定独立配置目录：
+
+```bash
+DWS_CONFIG_DIR=/tmp/dws-intl-smoke ./dws auth login --intl
+DWS_CONFIG_DIR=/tmp/dws-intl-smoke ./dws auth status --format json
+DWS_CONFIG_DIR=/tmp/dws-intl-smoke ./dws contact user get-self
+```
+
+请在三条命令中使用同一个 `DWS_CONFIG_DIR`。验证源码分支时使用 `./dws`；验证已安装版本时可改为 `dws`。
+
+## 预发参数（仅维护者）
+
+普通国际版用户只需要 `--intl`，不要配置 `--pre-url` 或 `--mcp-url`。
+
+维护者验证预发登录/MCP 链路时可以使用：
+
+```bash
+dws auth login --intl --pre-url https://pre-login.dingtalk.io
+```
+
+也可以传入对应的 `pre-mcp.*` 地址；DWS 会推导配套的 `pre-login.*` / `pre-mcp.*` 地址。`--mcp-url` 用于显式覆盖本次登录的 MCP base URL。
+
+预发环境可能只对内网或特定测试账号开放。`--pre-url` 主要服务于 MCP 托管凭证登录流程；除非预发 API 契约已经明确支持，否则不要把它与自有 `--client-id/--client-secret` 直连模式组合使用。
+
+## 常见问题
+
+### 仍然打开 `.com` 登录页面
+
+1. 运行 `dws auth login --help`，确认当前二进制包含 `--intl`。
+2. 从源码验证时使用 `./dws`，不要误用 PATH 中的旧版本。
+3. 确认实际执行的是 `dws auth login --intl`，而不是普通 `dws auth login`。
+
+### 业务命令似乎使用了错误区域
+
+先检查当前账号：
+
+```bash
+dws profile list --format json
+```
+
+然后使用精确的 `<corpId>:<userId>` 切换或通过全局 `--profile` 单次指定。对于在区域字段引入前生成的历史 Token，建议使用正确的登录方式重新授权：国际账号执行 `dws auth login --intl`，国内账号执行 `dws auth login`。
+
+### 登录成功但提示没有权限
+
+这通常是组织 CLI 准入或应用授权问题，不代表区域路由失败。请确认目标组织已开启 CLI 访问，并且当前应用拥有命令所需权限。
+
+### 是否需要手工修改 `~/.dws/mcp_url`
+
+不需要。正常使用应通过 `dws auth login` 或 `dws auth login --intl` 建立登录态；业务命令会根据选中的 Token/profile 自动路由。手工修改配置只适用于明确了解目标环境的维护者调试场景。
+
+## 命令速查
+
+| 场景 | 命令 |
+|---|---|
+| 国内版浏览器登录 | `dws auth login` |
+| 国际版浏览器登录 | `dws auth login --intl` |
+| 国际版设备码登录 | `dws auth login --intl --device` |
+| 查看登录状态 | `dws auth status --format json` |
+| 查看所有账号 | `dws profile list --format json` |
+| 持久切换账号 | `dws profile switch <corpId>:<userId>` |
+| 切回上一个账号 | `dws profile switch -` |
+| 单次指定账号 | `dws --profile <corpId>:<userId> <command>` |

docs/rfc-command-framework-convergence.md

@@ -292,7 +292,7 @@ Definition（仅声明；不可编译）
 
 下列字段**是**框架声明面（经 `corecmd.New` 生效并嵌入 `dws.schema.*`）：
 
-- `Flags`（含 Name/Kind/Default/Required/MarkRequired/Usage 等注册面）
+- `Flags`（含 Name/Kind/Default/Required/MarkRequired/Usage 等注册面；`Input` 是取值来源声明，经 `corecmd.New` 生效但**不**嵌入 `dws.schema.*`，能力靠 `Usage` 文案声明，见 §5.3）
 - `Constraints`
 - **非空** `Risk`（空值 = 运行时当只读确认，且**不**嵌入 `dws.schema.risk`）
 - `ConstParams`（载荷声明；不上用户 flag 表）
@@ -673,6 +673,52 @@ func (k Key[T]) Declare(opts ...FlagOption[T]) FlagSpec
 - 构造时拒绝 `InputSourceInvalid`。
 - 当前没有任何 Shortcut 或 Leaf 声明 `Input`，因此 M1 增加能力且零上线表面变化。让现有命令采用它属于 §9 下的用户可见变更。
 
+`Input` 的框架能力今日已在 `corecmd` 落地（声明即执行的过渡形态，语义与上文目标一致），使用指南：
+
+**今日声明形态**：`FlagSpec.Input []string`，源常量 `corecmd.InputFile`（`"file"`）/ `corecmd.InputStdin`（`"stdin"`）。`helpers.LeafFlag` 是 `corecmd.FlagSpec` 别名，直接可用；`shortcut.Flag.Input` 同形声明，经 `FromShortcut` 映射到 `FlagSpec`。
+
+```go
+// LeafSpec / helpers
+Flags: []helpers.LeafFlag{
+    {
+        Name:  "content",
+        Usage: "文档内容（支持 @文件路径 或 - 读 stdin）",
+        Bind:  "content",
+        Input: []string{corecmd.InputFile, corecmd.InputStdin},
+    },
+}
+
+// shortcut
+Flags: []shortcut.Flag{
+    {Name: "markdown", Desc: "Markdown 内容（支持 @文件路径 或 -）",
+     Input: []string{"file", "stdin"}},
+}
+```
+
+**运行时语义**（`resolveInputFlags`，在 `runDeclaredPreflight` 内、required/enum/约束/Validate 之前执行，原地改写 cobra flag 值）：
+
+- `--flag @path`：文件内容替换取值；`--flag -`：stdin 内容替换取值。
+- `--flag @@value`：转义为字面 `@value`，不做来源解析。
+- 只解析显式 CLI token（主名或别名）；EnvVar 回落与注册默认值透传不解析。
+- 内容前置剥离 UTF-8 BOM；`Trim` 等既有语义照常作用于解析后的值。
+- 读取失败、源不支持、`@` 后空路径都是类型化校验错误（退出码 3）；同时声明两种源而文件读取失败时附 stdin 引导 hint。
+
+**作者守则**：
+
+- 声明即全部能力：required/enum/约束/Validate 校验的已是解析后的真实内容，`Execute`/`Invoke` 无需任何额外代码。
+- `Usage`/`Desc` 必须写明支持 `@路径`/`-`；框架不自动改写 help 文案，今日也不向 Schema 投影（新增投影字段须先过 homology 评审，避免 catalog drift）。
+- `user_required` 确认的写命令若声明 `InputStdin`：stdin 在校验阶段被消费，交互确认将 fail-closed 为 `confirmation_required`，此类调用必须显式 `--yes`（或 `--dry-run`）。
+- **声明前先确认取值空间不会被前缀吃掉**：声明 `InputFile` 后，任何以 `@` 开头的合法值都会被当成文件路径（本产品尤其常见的是 at 提及类取值，如 `--at-user @zhangsan` 会报读取文件失败），用户只能改用 `@@` 转义；声明 `InputStdin` 后字面值 `-` 不可达（与 curl 等约定一致）。若该 flag 的正常取值可能命中这两种形态，就不要声明对应来源。
+- 声明在构造期校验（fail-closed panic）：仅限 `KindString`；源值必须是 `file`/`stdin` 且不重复。
+
+**今日实现与目标形态的差异**（迁移到本节目标 `FlagSpec` 时收敛）：
+
+| 维度 | 今日 | 目标 |
+|---|---|---|
+| 源类型 | `[]string` 常量 | 类型化 `InputSource` |
+| 路径边界 | 直接本地文件 IO | 复用 §5.5.2 本地文件 effect 边界 |
+| Schema 投影 | 无（靠作者在 Usage 声明） | 声明即最终源，随 Catalog 透传 |
+
 核心 FlagSpec 故意没有：
 
 - `Bind`；

docs/shortcut-public-catalog.json

@@ -1,6 +1,6 @@
 {
-  "generated_at": "2026-08-12T00:10:44.511794",
-  "count": 399,
+  "generated_at": "2026-08-14T13:50:36.324505",
+  "count": 418,
   "results": [
     {
       "suite": "semantic",
@@ -3659,11 +3659,204 @@
       "status": "real-ok"
     },
     {
-      "suite": "read",
+      "suite": "semantic",
+      "service": "wiki",
+      "command": "+delete-space",
+      "risk": "high-risk-write",
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "删除前读取影响目标，经高风险确认后只接受 success=true 终态。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "wiki",
+      "command": "+feed-list",
+      "risk": "read",
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "补充知识库协作动态查询，严格验证 feeds 并保留游标。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "wiki",
+      "command": "+member-add",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "支持 1-30 个 userId 与四类角色；严格要求写接口终态，并明确后端无法提供精确成员读回。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "wiki",
+      "command": "+member-list",
+      "risk": "read",
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "严格验证成员数组并公开真实单次上限 50；后端无游标时不伪造 page-all。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "wiki",
+      "command": "+member-remove",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "支持批量 userId 移除；严格要求写接口终态，并明确后端无法提供精确成员读回。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "wiki",
+      "command": "+member-update",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "补充成员角色更新；严格要求写接口终态，并明确后端无法提供精确成员读回。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "wiki",
+      "command": "+move",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "同一入口覆盖 Wiki 内移动和我的文档在线节点入 Wiki，并校验目标 workspace/folder。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "wiki",
+      "command": "+move-to-drive",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "同步移动 Wiki 节点到我的文档并读回验证 workspace 变化，免去异步任务轮询。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "wiki",
+      "command": "+node-copy",
+      "risk": "high-risk-write",
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "高风险确认后复制，必须取得新 nodeId 并读回副本，避免空响应被当作成功。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "wiki",
+      "command": "+node-create",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "支持七种 Wiki 节点类型，创建后要求 nodeId 并读取元数据验证。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "wiki",
+      "command": "+node-delete",
+      "risk": "high-risk-write",
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "删除前读取并核对 workspace，经高风险确认后要求 success=true 终态证据。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "wiki",
+      "command": "+node-get",
+      "risk": "read",
+      "status": "reviewed_available",
+      "disposition": "schema_leaf",
+      "semantic_delta": "统一节点 ID 或在线文档 URL 的元数据读取，补充文档域属性视角。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "wiki",
+      "command": "+node-list",
+      "risk": "read",
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "严格区分显式空目录与假空成功，稳定投影节点并保留 nextCursor/hasMore。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "wiki",
+      "command": "+node-search",
+      "risk": "read",
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "补充库内关键词和扩展名搜索，并拒绝假空结果。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "wiki",
+      "command": "+resolve-space",
+      "risk": "read",
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "把关键词搜索收敛为唯一 workspaceId；零命中与多命中显式分流，绝不猜测。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "wiki",
+      "command": "+space-create",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "创建后要求 workspaceId 并通过空间详情读回验证真实落库。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "wiki",
+      "command": "+space-get",
+      "risk": "read",
+      "status": "reviewed_available",
+      "disposition": "schema_leaf",
+      "semantic_delta": "补充知识库详情入口，并要求 workspaceId 业务证据。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "wiki",
+      "command": "+space-list",
+      "risk": "read",
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "严格区分显式空知识库列表与缺失、畸形或内部错误响应，并保留真实分页证据。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
       "service": "wiki",
       "command": "+space-search",
       "risk": "read",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "按关键词搜索知识库并拒绝把缺失业务数组误报为零命中。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "wiki",
+      "command": "+wiki-new-doc",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "按空间名精确唯一解析、创建在线文档并读回验证；零命中和歧义均显式失败。",
+      "availability": "available"
     }
   ]
 }

docs/wiki-shortcut-business-review.html

@@ -0,0 +1,117 @@
+<!doctype html>
+<html lang="zh-CN">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width,initial-scale=1">
+  <title>DWS Wiki Shortcut 全景评审</title>
+  <style>
+    :root{--ink:#14213d;--muted:#5c677d;--line:#dbe4f0;--paper:#fff;--bg:#f3f7fb;--blue:#1769e0;--cyan:#00a6a6;--green:#178746;--amber:#a45b00;--red:#b42318;--shadow:0 14px 34px rgba(20,33,61,.08)}
+    *{box-sizing:border-box}body{margin:0;overflow-x:hidden;background:linear-gradient(150deg,#edf5ff 0,#f8fbff 45%,#eef8f5 100%);color:var(--ink);font:15px/1.65 -apple-system,BlinkMacSystemFont,"Segoe UI","PingFang SC",sans-serif}
+    main,.card,.two>*{min-width:0}main{width:min(1180px,calc(100% - 32px));margin:28px auto 72px}.hero,.card{background:rgba(255,255,255,.96);border:1px solid var(--line);border-radius:22px;box-shadow:var(--shadow)}
+    .hero{padding:38px;background:radial-gradient(circle at 95% 0,#dff8f3,transparent 36%),linear-gradient(135deg,#fff,#f5f9ff)}h1{font-size:34px;line-height:1.2;margin:0 0 10px}.lead{font-size:17px;color:var(--muted);max-width:900px}.meta{display:flex;gap:10px;flex-wrap:wrap;margin-top:20px}.pill{border:1px solid #cbd9ea;border-radius:999px;padding:5px 11px;background:#fff;font-size:13px}
+    .grid{display:grid;grid-template-columns:repeat(4,1fr);gap:14px;margin:18px 0}.metric{padding:20px}.metric b{display:block;font-size:31px;color:var(--blue)}.metric span{color:var(--muted)}
+    section{margin-top:22px}.card{padding:26px}h2{font-size:23px;margin:0 0 14px}h3{font-size:17px;margin:22px 0 8px}.callout{border-left:4px solid var(--blue);background:#f2f7ff;padding:14px 16px;border-radius:8px}.warn{border-color:var(--amber);background:#fff8eb}.ok{border-color:var(--green);background:#effbf4}
+    table{width:100%;border-collapse:collapse;font-size:14px}th,td{text-align:left;vertical-align:top;border-bottom:1px solid var(--line);padding:11px 9px}th{color:#41516b;background:#f7f9fc;position:sticky;top:0}code{background:#edf2f8;border-radius:5px;padding:2px 5px;color:#24466e}.tag{display:inline-block;border-radius:999px;padding:2px 8px;font-size:12px;font-weight:650;white-space:nowrap}.full{background:#e6f6ec;color:#116436}.partial{background:#fff0d5;color:#875000}.extra{background:#e8f1ff;color:#1854a5}.fixed{background:#f1eaff;color:#6338a5}
+    .toolbar{display:flex;flex-wrap:wrap;gap:10px;margin:12px 0}.toolbar input,.toolbar select{border:1px solid #bdcada;border-radius:10px;padding:9px 11px;background:#fff;min-width:min(220px,100%);max-width:100%;flex:1 1 220px}.matrix{max-height:620px;overflow:auto;border:1px solid var(--line);border-radius:12px}.two{display:grid;grid-template-columns:1fr 1fr;gap:18px}.small{color:var(--muted);font-size:13px}ul{padding-left:20px}.footer{color:var(--muted);text-align:center;margin-top:22px}@media(max-width:850px){.grid,.two{grid-template-columns:1fr 1fr}.hero{padding:25px}}@media(max-width:560px){.grid,.two{grid-template-columns:1fr}main{width:min(100% - 18px,1180px)}.card{padding:18px}h1{font-size:28px}}
+  </style>
+</head>
+<body><main>
+  <header class="hero">
+    <h1>DWS Wiki Shortcut 全景评审</h1>
+    <p class="lead">以 13 项成熟 Wiki 用户任务为基线，重新审视 DWS 的空间、成员、节点与动态能力。本次不是按命令名凑数：每个入口都要求真实业务证据，缺失数组、畸形响应、空确认或读回不一致一律失败。</p>
+    <div class="meta"><span class="pill">评审日期 2026-08-14</span><span class="pill">独立 worktree / 独立分支</span><span class="pill">真实组织数据 E2E 28/28</span><span class="pill">报告已去标识化</span></div>
+  </header>
+
+  <div class="grid">
+    <div class="card metric"><b>20</b><span>公开 Wiki Shortcuts</span></div>
+    <div class="card metric"><b>13/13</b><span>基线用户任务有对应路径</span></div>
+    <div class="card metric"><b>7</b><span>DWS 额外场景</span></div>
+    <div class="card metric"><b>20/20</b><span>真实数据能力已触达</span></div>
+  </div>
+
+  <section class="card">
+    <h2>结论先行</h2>
+    <div class="callout ok"><strong>DWS 已形成比“API 快捷别名”更完整的 Wiki 任务层。</strong> 基线中的 13 个用户任务均有对应入口；DWS 还提供空间搜索/详情/唯一解析、成员角色更新、库内节点搜索、协作动态和按空间名新建文档。创建、复制、移动等关键写能力从“请求发出”升级为“终态 + ID + 读回”成功标准。</div>
+    <div class="callout warn" style="margin-top:12px"><strong>能力边界必须诚实表达。</strong> DingTalk 成员接口不提供游标，单次真实上限是 50，因此不能实现成员 <code>--page-all</code>；成员身份只接受同组织可用的 userId，无法提供 email/open_id 等多种身份模式；节点创建也没有等价的 origin/shortcut 模式。这些差异保留为明确边界，而不是用本地循环或空结果伪装。</div>
+  </section>
+
+  <section class="card">
+    <h2>13 项基线任务逐条映射</h2>
+    <div class="matrix"><table><thead><tr><th>基线任务</th><th>DWS 主入口</th><th>结论</th><th>DWS 视角与边界</th></tr></thead><tbody>
+      <tr><td><code>+space-list</code></td><td><code>wiki +space-list</code></td><td><span class="tag full">完整对齐</span></td><td>严格空集合、游标续传、自动翻页、停滞检测；支持组织/我的知识库。</td></tr>
+      <tr><td><code>+space-create</code></td><td><code>wiki +space-create</code></td><td><span class="tag full">超过</span></td><td>公开真实 32 字符名称上限；创建后按 workspaceId 读回。</td></tr>
+      <tr><td><code>+delete-space</code></td><td><code>wiki +delete-space</code></td><td><span class="tag full">超过</span></td><td>预读目标、高风险确认、只接受 <code>success=true</code>；兼容 <code>+space-delete</code>。</td></tr>
+      <tr><td><code>+member-add</code></td><td><code>wiki +member-add</code></td><td><span class="tag partial">任务对齐</span></td><td>支持 1–30 个 userId 与四种角色；以写接口终态作为成功证据，不把最多 50 条的名单误作精确读回。</td></tr>
+      <tr><td><code>+member-list</code></td><td><code>wiki +member-list</code></td><td><span class="tag partial">任务对齐</span></td><td>严格成员数组、角色过滤、真实上限 50；后端无游标，不能提供诚实的 page-all。</td></tr>
+      <tr><td><code>+member-remove</code></td><td><code>wiki +member-remove</code></td><td><span class="tag partial">任务对齐</span></td><td>支持批量 userId；只接受写接口明确终态，并公开无法进行精确成员读回的边界。</td></tr>
+      <tr><td><code>+node-list</code></td><td><code>wiki +node-list</code></td><td><span class="tag full">完整对齐</span></td><td>正确跨域路由 doc/list_nodes，严格空目录、分页与自动翻页。</td></tr>
+      <tr><td><code>+node-get</code></td><td><code>wiki +node-get</code></td><td><span class="tag partial">任务对齐</span></td><td>支持 DingTalk 节点 ID/在线文档 URL 并返回文档域元数据；不接受跨平台专用的 token/type 组合。</td></tr>
+      <tr><td><code>+node-create</code></td><td><code>wiki +node-create</code></td><td><span class="tag partial">任务对齐</span></td><td>支持 adoc/axls/able/appt/adraw/amind/folder 并读回；无 origin/shortcut 等价接口。</td></tr>
+      <tr><td><code>+node-copy</code></td><td><code>wiki +node-copy</code></td><td><span class="tag full">超过</span></td><td>确认后要求新 nodeId 并读取副本；底层面向在线节点，不把 .dlink 当独立副本。</td></tr>
+      <tr><td><code>+move</code></td><td><code>wiki +move</code></td><td><span class="tag partial">任务对齐</span></td><td>同一入口支持 Wiki 内移动和“我的文档”在线节点入 Wiki，读回 workspace/folder；底层接口没有 apply 权限迁移开关。</td></tr>
+      <tr><td><code>+move-to-drive</code></td><td><code>wiki +move-to-drive</code></td><td><span class="tag full">超过</span></td><td>DWS 当前接口同步完成并读回 workspace 变化，无需暴露异步 task 轮询。</td></tr>
+      <tr><td><code>+node-delete</code></td><td><code>wiki +node-delete</code></td><td><span class="tag full">超过</span></td><td>预读并核对 workspace，高风险确认，要求删除终态。</td></tr>
+    </tbody></table></div>
+  </section>
+
+  <section class="card">
+    <h2>DWS 可挖掘的 7 个额外场景</h2>
+    <div class="two">
+      <div><h3>定位与创建链</h3><ul><li><code>+space-search</code>：严格关键词搜索。</li><li><code>+space-get</code>：空间详情与 workspaceId 证据。</li><li><code>+resolve-space</code>：唯一命中直出 ID，多命中拒绝猜测。</li><li><code>+wiki-new-doc</code>：空间名解析 → 创建 → 文档读回。</li></ul></div>
+      <div><h3>治理与巡检链</h3><ul><li><code>+member-update</code>：角色变更终态与不可精确读回声明。</li><li><code>+node-search</code>：库内关键词/扩展名搜索，严格零命中。</li><li><code>+feed-list</code>：知识库动态时间线与服务端 exclude-file 过滤。</li></ul></div>
+    </div>
+  </section>
+
+  <section class="card">
+    <h2>隐藏问题与修复</h2>
+    <table><thead><tr><th>原问题</th><th>错误风险</th><th>本次修复</th></tr></thead><tbody>
+      <tr><td>5 个旧 Wiki Shortcut 可直接执行，但只有 1 个进入公开目录。</td><td>Help、Schema、Skill 发现链与运行面漂移。</td><td><span class="tag fixed">20 项统一评审</span> 全部具备 Contract/Safety/Result 与语义目录记录。</td></tr>
+      <tr><td>列表投影找不到数组或遇到坏元素时返回空 slice。</td><td>把内部错误、字段漂移误报为“没有数据”。</td><td><span class="tag fixed">失败关闭</span> 只有响应中真实存在的 <code>[]</code> 才是合法空集合。</td></tr>
+      <tr><td>节点列表 Shortcut 调错 Wiki MCP 服务。</td><td>真实后端 <code>success=false</code>，Mock/静态检查看不出。</td><td><span class="tag fixed">跨域路由</span> 明确调用 doc/list_nodes，并纳入真实 E2E。</td></tr>
+      <tr><td>成员帮助宣称最大 200。</td><td>真实接口超过 50 直接参数错误。</td><td><span class="tag fixed">真实上限</span> Shortcut 与原子 Help 均改为 50，并在本地提前拒绝。</td></tr>
+      <tr><td>成员写操作从最多 50 条、不可分页的名单推断成员存在或缺失。</td><td>目标在截断部分时会误报写失败，或把未验证的移除报告为已读回。</td><td><span class="tag fixed">终态证据</span> 只接受写接口 <code>success=true</code>，并在结果中明确 <code>readbackAvailable=false</code>。</td></tr>
+      <tr><td>空间搜索的稳定工作流属性名与实际请求属性名不同。</td><td>直接改写已发布的 <code>query/limit</code> 会造成无版本 Schema 破坏；继续隐式转换又会让审计者误以为请求同名透传。</td><td><span class="tag fixed">显式复合适配</span> 最终 Schema 保留兼容属性并明确声明转换为 <code>keyword/pageSize</code>；回归测试同时锁定最终交付和精确请求参数。</td></tr>
+      <tr><td>知识库名称帮助宣称最大 100。</td><td>真实接口超过 32 失败。</td><td><span class="tag fixed">真实上限</span> Help 与 Shortcut 校验统一为 32。</td></tr>
+      <tr><td>复制/移动/创建只把无异常视为成功。</td><td>空确认、未知远端效果或移动未到目标仍可能被接受。</td><td><span class="tag fixed">读回证明</span> 在后端具备精确查询能力时检查 success、业务 ID、workspace/folder 等最终状态。</td></tr>
+    </tbody></table>
+  </section>
+
+  <section class="card">
+    <h2>真实数据 E2E 证据矩阵</h2>
+    <p class="small">28 项业务断言全部通过。测试使用一次性空知识库、临时在线文档与一名同组织内部测试成员；所有对象在 finally 清理。报告不保存对象 ID、成员身份、组织信息、URL、trace 或原始响应。</p>
+    <div class="toolbar"><input id="q" placeholder="筛选命令或证据"><select id="g"><option value="">全部分组</option><option>空间</option><option>成员</option><option>节点</option><option>动态</option></select></div>
+    <div class="matrix"><table id="catalog"><thead><tr><th>分组</th><th>Shortcut</th><th>实际业务断言</th><th>状态</th></tr></thead><tbody>
+      <tr><td>空间</td><td><code>+space-list</code></td><td>真实 count、hasMore、nextCursor；自动翻页返回两页结果。</td><td><span class="tag full">PASS</span></td></tr>
+      <tr><td>空间</td><td><code>+space-search</code></td><td>等待搜索索引后命中一次性 workspaceId。</td><td><span class="tag full">PASS</span></td></tr>
+      <tr><td>空间</td><td><code>+space-get</code></td><td>读回 workspaceId 与创建结果一致。</td><td><span class="tag full">PASS</span></td></tr>
+      <tr><td>空间</td><td><code>+resolve-space</code></td><td>唯一名称解析为同一 workspaceId。</td><td><span class="tag full">PASS</span></td></tr>
+      <tr><td>空间</td><td><code>+space-create</code></td><td>success=true、workspaceId 非空、详情读回一致。</td><td><span class="tag full">PASS</span></td></tr>
+      <tr><td>空间</td><td><code>+delete-space</code></td><td>目标预读、确认、success=true；兼容别名执行 finally 清理。</td><td><span class="tag full">PASS</span></td></tr>
+      <tr><td>成员</td><td><code>+member-list</code></td><td>真实 owner 条目与显式 members 数组，limit=50。</td><td><span class="tag full">PASS</span></td></tr>
+      <tr><td>成员</td><td><code>+member-add</code></td><td>命令只报告写终态；一次性小规模空间另行确认名单完整且角色为 READER。</td><td><span class="tag full">PASS</span></td></tr>
+      <tr><td>成员</td><td><code>+member-update</code></td><td>命令只报告写终态；一次性小规模空间另行确认角色变为 EDITOR。</td><td><span class="tag full">PASS</span></td></tr>
+      <tr><td>成员</td><td><code>+member-remove</code></td><td>命令只报告写终态；一次性小规模空间另行确认完整名单中不存在该 userId。</td><td><span class="tag full">PASS</span></td></tr>
+      <tr><td>节点</td><td><code>+node-list</code></td><td>空库返回真实 nodes:[]；有数据时验证游标与自动翻页。</td><td><span class="tag full">PASS</span></td></tr>
+      <tr><td>节点</td><td><code>+node-get</code></td><td>读回 nodeId 与请求一致。</td><td><span class="tag full">PASS</span></td></tr>
+      <tr><td>节点</td><td><code>+node-search</code></td><td>等待索引后按标题命中真实 nodeId。</td><td><span class="tag full">PASS</span></td></tr>
+      <tr><td>节点</td><td><code>+node-create</code></td><td>分别创建 folder/adoc，均取得 nodeId 和元数据读回。</td><td><span class="tag full">PASS</span></td></tr>
+      <tr><td>节点</td><td><code>+node-copy</code></td><td>取得不同的新 nodeId，副本元数据可读。</td><td><span class="tag full">PASS</span></td></tr>
+      <tr><td>节点</td><td><code>+move</code></td><td>读回 workspaceId 与 folderId 均等于目标；兼容 +node-move。</td><td><span class="tag full">PASS</span></td></tr>
+      <tr><td>节点</td><td><code>+move-to-drive</code></td><td>移动后读回 workspace 发生变化，再通过 +move 移回。</td><td><span class="tag full">PASS</span></td></tr>
+      <tr><td>节点</td><td><code>+node-delete</code></td><td>目标预读与 workspace 核对后收到 success=true。</td><td><span class="tag full">PASS</span></td></tr>
+      <tr><td>节点</td><td><code>+wiki-new-doc</code></td><td>按唯一空间名创建，nodeId 与文档详情读回一致。</td><td><span class="tag full">PASS</span></td></tr>
+      <tr><td>动态</td><td><code>+feed-list</code></td><td>创建/移动操作后返回真实 feeds 数组，缺字段不会被接受。</td><td><span class="tag full">PASS</span></td></tr>
+    </tbody></table></div>
+    <p class="small">可复跑入口：<code>make build</code> 后设置临时 <code>DWS_WIKI_E2E_MEMBER_ID</code>，在交互终端运行 <code>./scripts/dev/wiki-shortcut-e2e.py</code>。脚本只输出能力标签，不输出业务对象；受保护操作及最终清理均由命令逐项获取终端确认，非交互环境会在创建测试数据前拒绝运行。</p>
+  </section>
+
+  <section class="card">
+    <h2>成功判定与发布门</h2>
+    <div class="two"><div><h3>运行时证据层</h3><ol><li>传输/MCP 调用成功。</li><li>响应契约存在且类型正确。</li><li>写操作必须有 <code>success=true</code>；创建类操作还必须有业务 ID。</li><li>后端具备精确查询时必须读回；不具备时明确发布不可读回，而非从截断集合推断。</li><li>集合只有显式数组才允许为空。</li></ol></div><div><h3>交付门</h3><ol><li>20/20 语义目录与注册面精确覆盖。</li><li>Contract、Safety、Result、统一输出完整。</li><li>生成漂移、Schema、确认真值、全量 Go 测试。</li><li>独立真实数据 E2E 与 finally 清理。</li><li>diff PII/密钥/本地绝对路径扫描。</li></ol></div></div>
+  </section>
+  <p class="footer">DWS Wiki Shortcut business review · sanitized engineering artifact</p>
+</main>
+<script>
+  const q=document.querySelector('#q'),g=document.querySelector('#g'),rows=[...document.querySelectorAll('#catalog tbody tr')];
+  function filter(){const text=q.value.trim().toLowerCase(),group=g.value;rows.forEach(r=>{const okText=!text||r.textContent.toLowerCase().includes(text),okGroup=!group||r.children[0].textContent===group;r.style.display=okText&&okGroup?'':'none'})}q.addEventListener('input',filter);g.addEventListener('change',filter);
+</script></body></html>

go.mod

@@ -2,6 +2,8 @@ module github.com/DingTalk-Real-AI/dingtalk-workspace-cli
 
 go 1.25.9
 
+replace gitlab.alibaba-inc.com/aes/aem-go-sdk => ./third_party/aem-go-sdk
+
 require (
 	github.com/Microsoft/go-winio v0.6.2
 	github.com/RealAlexandreAI/json-repair v0.0.15
@@ -17,6 +19,7 @@ require (
 	github.com/open-dingtalk/dingtalk-stream-sdk-go v0.9.2-beta.1
 	github.com/spf13/cobra v1.10.2
 	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
 	golang.org/x/sys v0.42.0
 	golang.org/x/text v0.35.0

internal/app/access_token_manager_test.go

@@ -65,12 +65,16 @@ func TestCrossPlatformCoverageTokenManagerCachesUntilMarkerRevisionChanges(t *te
 	token := "token-a"
 	installTokenManagerFakes(t, func() (*authpkg.TokenData, error) {
 		calls.Add(1)
-		return &authpkg.TokenData{AccessToken: token, ExpiresAt: time.Now().Add(time.Hour)}, nil
+		return &authpkg.TokenData{
+			AccessToken: token,
+			ExpiresAt:   time.Now().Add(time.Hour),
+			LoginRegion: string(authpkg.LoginRegionInternational),
+		}, nil
 	})
 
 	manager := NewTokenManager()
 	first, err := manager.Get(context.Background(), configDir, "")
-	if err != nil || first.AccessToken != "token-a" {
+	if err != nil || first.AccessToken != "token-a" || first.LoginRegion != authpkg.LoginRegionInternational || !first.LoginRegionKnown {
 		t.Fatalf("first token = %#v, %v", first, err)
 	}
 	second, err := manager.Get(context.Background(), configDir, "")

internal/app/access_token_resolve.go

@@ -41,9 +41,11 @@ type accessTokenSnapshotGetter interface {
 // AccessTokenSnapshot is the minimal bearer view needed by the process cache.
 // Refresh-token material never leaves the auth package.
 type AccessTokenSnapshot struct {
-	AccessToken string
-	ExpiresAt   time.Time
-	Source      string
+	AccessToken      string
+	ExpiresAt        time.Time
+	Source           string
+	LoginRegion      authpkg.LoginRegion
+	LoginRegionKnown bool
 }
 
 type tokenManagerKey struct {
@@ -223,9 +225,11 @@ func resolveAccessTokenSnapshotFromDir(ctx context.Context, configDir, profile s
 		data, err := snapshotProvider.GetTokenSnapshot(ctx)
 		if err == nil && data != nil && strings.TrimSpace(data.AccessToken) != "" {
 			return AccessTokenSnapshot{
-				AccessToken: strings.TrimSpace(data.AccessToken),
-				ExpiresAt:   data.ExpiresAt,
-				Source:      "oauth",
+				AccessToken:      strings.TrimSpace(data.AccessToken),
+				ExpiresAt:        data.ExpiresAt,
+				Source:           "oauth",
+				LoginRegion:      authpkg.LoginRegion(strings.TrimSpace(data.LoginRegion)),
+				LoginRegionKnown: true,
 			}, nil
 		}
 		if err != nil && !errors.Is(err, authpkg.ErrTokenDataNotFound) {

internal/app/agent_metadata_test.go

@@ -712,9 +712,9 @@ func TestCrossPlatformCoverageAgentMetadataMCPAndPluginScoping(t *testing.T) {
 	// calls must fail before preflight or transport while anonymous plugins remain
 	// valid above.
 	resolveCalled := false
-	testseam.Swap(t, &runnerResolveAuthToken, func(*runtimeRunner, context.Context) (string, error) {
+	testseam.Swap(t, &runnerResolveAuthSnapshot, func(*runtimeRunner, context.Context) (AccessTokenSnapshot, error) {
 		resolveCalled = true
-		return "", nil
+		return AccessTokenSnapshot{}, nil
 	})
 	callsBefore := len(captured)
 	unauthenticated := &runtimeRunner{

internal/app/auth_command.go

@@ -20,6 +20,8 @@ import (
 	"encoding/json"
 	"fmt"
 	"io"
+	"net"
+	"net/url"
 	"os"
 	"path/filepath"
 	"runtime"
@@ -48,8 +50,24 @@ type authLoginConfig struct {
 	TargetCorpID                   string
 	HistoryProfileSelector         string
 	HistoryProfileSelectorExplicit bool
+	International                  bool
+	PreURL                         string
+	MCPURL                         string
 }
 
+type authLoginEndpointOverrides struct {
+	LoginURL string
+	MCPURL   string
+}
+
+type authLoginMCPPersistence uint8
+
+const (
+	authLoginMCPUseDefault authLoginMCPPersistence = iota
+	authLoginMCPUseManagedRegion
+	authLoginMCPUseExplicitOverride
+)
+
 type authLoginGuideAction string
 
 const (
@@ -103,12 +121,17 @@ func newAuthLoginCommand(patCaller edition.ToolCaller) *cobra.Command {
 支持的登录方式:
   - OAuth Loopback 流 (默认): 本机自动起 127.0.0.1 监听接收回调，浏览器授权后自动完成
   - OAuth 设备流 (--device): 显示 user_code + 短 URL，适合 SSH 远程 / 容器 / 无头环境
+  - 自有应用 OAuth (--client-id/--client-secret): 使用指定应用完成用户授权
   - 直接提供 Token (--token): 跳过授权，使用已有 token
 
 不支持的登录方式:
   - 邮箱/密码登录
   - 手机号/验证码登录
-  - 应用凭证 (AppKey/AppSecret) 直接登录
+  - 无用户授权的纯应用凭证 (client_credentials) 登录
+
+区域:
+  - 默认使用国内钉钉 .com 登录与服务端点
+  - --intl（或 --international）使用国际版 .io 登录；后续业务命令按所选 profile 自动路由
 
 注意: SSH 远程或无头环境（无本地浏览器可访问远端的 127.0.0.1）请使用 --device，
       否则 OAuth 回调会跳到本机不可达的 127.0.0.1 链接，授权完成后无法回写 token。
@@ -116,6 +139,9 @@ func newAuthLoginCommand(patCaller edition.ToolCaller) *cobra.Command {
 示例:
   dws auth login              # 本机登录并新增/刷新一个组织 profile
   dws auth login --profile <corpId>  # 指定本次授权目标组织，不持久切换当前组织
+  dws auth login --intl       # 使用钉钉国际版 .io 登录入口
+  dws auth login --intl --pre-url https://pre-login.dingtalk.io
+  dws auth login --intl --pre-url https://pre-mcp.dingtalk.io
   dws auth login --recommend  # 无交互批量授权服务端推荐权限
   dws auth login --device     # SSH 远程 / 无头环境登录 (设备流)
   dws auth login --force      # 兼容保留；login 默认已忽略缓存并进入授权流程
@@ -126,6 +152,22 @@ func newAuthLoginCommand(patCaller edition.ToolCaller) *cobra.Command {
 			if err != nil {
 				return err
 			}
+			var preOverrides authLoginEndpointOverrides
+			if cfg.PreURL != "" {
+				var err error
+				preOverrides, err = authLoginEndpointOverridesForPreURL(cfg.PreURL)
+				if err != nil {
+					return err
+				}
+				restoreLoginBaseURL := authpkg.PushLoginBaseURLOverride(preOverrides.LoginURL)
+				defer restoreLoginBaseURL()
+			}
+			mcpBaseURL, mcpPersistence, err := authLoginMCPBaseURLForConfig(cfg, preOverrides)
+			if err != nil {
+				return err
+			}
+			restoreMCPBaseURL := authpkg.PushMCPBaseURLOverride(mcpBaseURL)
+			defer restoreMCPBaseURL()
 			configDir := defaultConfigDir()
 			var tokenData *authpkg.TokenData
 			format, _ := cmd.Root().PersistentFlags().GetString("format")
@@ -139,6 +181,9 @@ func newAuthLoginCommand(patCaller edition.ToolCaller) *cobra.Command {
 					AccessToken: cfg.Token,
 					ExpiresAt:   time.Now().Add(config.ManualTokenExpiry),
 				}
+				if cfg.International {
+					tokenData.LoginRegion = string(authpkg.LoginRegionInternational)
+				}
 				if err := authSaveTokenData(configDir, tokenData); err != nil {
 					return apperrors.NewInternal(fmt.Sprintf("failed to persist auth token: %v", err))
 				}
@@ -149,6 +194,9 @@ func newAuthLoginCommand(patCaller edition.ToolCaller) *cobra.Command {
 				provider := authpkg.NewDeviceFlowProvider(configDir, nil)
 				provider.Output = cmd.ErrOrStderr()
 				provider.NoBrowser, _ = cmd.Flags().GetBool("no-browser")
+				if cfg.International {
+					provider.SetLoginRegion(authpkg.LoginRegionInternational)
+				}
 				provider.IdentityEnricher = func(ctx context.Context, data *authpkg.TokenData) error {
 					return enrichAuthLoginProfileFromContact(ctx, configDir, patCaller, data, authLoginHistoryHint{
 						Selector: cfg.HistoryProfileSelector,
@@ -167,6 +215,9 @@ func newAuthLoginCommand(patCaller edition.ToolCaller) *cobra.Command {
 				provider.Output = cmd.ErrOrStderr()
 				provider.NoBrowser, _ = cmd.Flags().GetBool("no-browser")
 				provider.TargetCorpID = cfg.TargetCorpID
+				if cfg.International {
+					provider.LoginRegion = authpkg.LoginRegionInternational
+				}
 				provider.IdentityEnricher = func(ctx context.Context, data *authpkg.TokenData) error {
 					return enrichAuthLoginProfileFromContact(ctx, configDir, patCaller, data, authLoginHistoryHint{
 						Selector: cfg.HistoryProfileSelector,
@@ -180,6 +231,11 @@ func newAuthLoginCommand(patCaller edition.ToolCaller) *cobra.Command {
 				}
 			}
 
+			if tokenData != nil {
+				if err := persistAuthLoginMCPBaseURL(configDir, mcpBaseURL, mcpPersistence); err != nil {
+					return apperrors.NewInternal(fmt.Sprintf("failed to persist MCP URL: %v", err))
+				}
+			}
 			ResetRuntimeTokenCache()
 			clearCompatCache()
 			w := cmd.OutOrStdout()
@@ -278,6 +334,10 @@ func newAuthLoginCommand(patCaller edition.ToolCaller) *cobra.Command {
 	}
 	cmd.Flags().String("token", "", "Access token")
 	cmd.Flags().Bool("device", false, "Use device authorization flow")
+	cmd.Flags().Bool("intl", false, "Use DingTalk international (.io) login and service endpoints")
+	cmd.Flags().Bool("international", false, "Use DingTalk international (.io) login and service endpoints")
+	cmd.Flags().String("pre-url", "", "Override pre-release login/MCP base URL for this login")
+	cmd.Flags().String("mcp-url", "", "Override MCP base URL for this login")
 	cmd.Flags().Bool("force", false, "兼容保留；login 默认已忽略缓存并进入授权流程")
 	cmd.Flags().Bool("recommend", false, "登录成功后无交互批量授权服务端推荐权限")
 	// Hidden compatibility flags
@@ -967,6 +1027,7 @@ func newAuthResetCommand() *cobra.Command {
 				return apperrors.NewInternal(fmt.Sprintf("failed to reset token data: %v", err))
 			}
 			_ = authRemove(filepath.Join(configDir, "mcp_url"))
+			_ = authRemove(filepath.Join(configDir, config.ManagedMCPURLRegionFileName))
 			_ = authRemove(filepath.Join(configDir, "token"))
 			_ = authDeleteAppConfig(configDir)
 			ResetRuntimeTokenCache()
@@ -1225,6 +1286,14 @@ func resolveAuthLoginConfig(cmd *cobra.Command) (authLoginConfig, error) {
 	if err != nil {
 		return authLoginConfig{}, apperrors.NewInternal("failed to read --device")
 	}
+	intl, err := cmd.Flags().GetBool("intl")
+	if err != nil {
+		return authLoginConfig{}, apperrors.NewInternal("failed to read --intl")
+	}
+	international, err := cmd.Flags().GetBool("international")
+	if err != nil {
+		return authLoginConfig{}, apperrors.NewInternal("failed to read --international")
+	}
 	force, err := cmd.Flags().GetBool("force")
 	if err != nil {
 		return authLoginConfig{}, apperrors.NewInternal("failed to read --force")
@@ -1233,6 +1302,14 @@ func resolveAuthLoginConfig(cmd *cobra.Command) (authLoginConfig, error) {
 	if err != nil {
 		return authLoginConfig{}, apperrors.NewInternal("failed to read --recommend")
 	}
+	preURL, err := cmd.Flags().GetString("pre-url")
+	if err != nil {
+		return authLoginConfig{}, apperrors.NewInternal("failed to read --pre-url")
+	}
+	mcpURL, err := cmd.Flags().GetString("mcp-url")
+	if err != nil {
+		return authLoginConfig{}, apperrors.NewInternal("failed to read --mcp-url")
+	}
 	yes := false
 	profileSelector := ""
 	if cmd.Root() != nil {
@@ -1266,9 +1343,172 @@ func resolveAuthLoginConfig(cmd *cobra.Command) (authLoginConfig, error) {
 		TargetCorpID:                   targetCorpID,
 		HistoryProfileSelector:         historyProfileSelector,
 		HistoryProfileSelectorExplicit: historyProfileSelectorExplicit,
+		International:                  intl || international,
+		PreURL:                         strings.TrimSpace(preURL),
+		MCPURL:                         strings.TrimSpace(mcpURL),
 	}, nil
 }
 
+func authLoginEndpointOverridesForPreURL(raw string) (authLoginEndpointOverrides, error) {
+	parsed, normalized, err := normalizeAuthLoginBaseURL(raw, "--pre-url")
+	if err != nil {
+		return authLoginEndpointOverrides{}, err
+	}
+	host := strings.ToLower(parsed.Hostname())
+	switch {
+	case strings.HasPrefix(host, "pre-login."):
+		return authLoginEndpointOverrides{
+			LoginURL: normalized,
+			MCPURL:   authLoginURLWithHost(parsed, "pre-mcp."+strings.TrimPrefix(host, "pre-login.")),
+		}, nil
+	case strings.HasPrefix(host, "pre-mcp."):
+		return authLoginEndpointOverrides{
+			LoginURL: authLoginURLWithHost(parsed, "pre-login."+strings.TrimPrefix(host, "pre-mcp.")),
+			MCPURL:   normalized,
+		}, nil
+	default:
+		return authLoginEndpointOverrides{}, apperrors.NewValidation("--pre-url must be a pre-login.* or pre-mcp.* URL")
+	}
+}
+
+func authLoginMCPBaseURLForConfig(cfg authLoginConfig, preOverrides authLoginEndpointOverrides) (string, authLoginMCPPersistence, error) {
+	if cfg.MCPURL != "" {
+		_, normalized, err := normalizeAuthLoginBaseURL(cfg.MCPURL, "--mcp-url")
+		if err != nil {
+			return "", authLoginMCPUseDefault, err
+		}
+		return normalized, authLoginMCPUseExplicitOverride, nil
+	}
+	if cfg.PreURL != "" {
+		if preOverrides.MCPURL == "" {
+			var err error
+			preOverrides, err = authLoginEndpointOverridesForPreURL(cfg.PreURL)
+			if err != nil {
+				return "", authLoginMCPUseDefault, err
+			}
+		}
+		return preOverrides.MCPURL, authLoginMCPUseExplicitOverride, nil
+	}
+	if cfg.International {
+		return authpkg.InternationalMCPBaseURL, authLoginMCPUseManagedRegion, nil
+	}
+	return authpkg.DefaultMCPBaseURL, authLoginMCPUseDefault, nil
+}
+
+func persistAuthLoginMCPBaseURL(configDir, mcpBaseURL string, persistence authLoginMCPPersistence) error {
+	mcpURLPath := filepath.Join(configDir, "mcp_url")
+	managedRegionPath := filepath.Join(configDir, config.ManagedMCPURLRegionFileName)
+
+	switch persistence {
+	case authLoginMCPUseExplicitOverride:
+		if err := removeAuthLoginManagedMCPRegion(managedRegionPath); err != nil {
+			return fmt.Errorf("clear managed MCP region: %w", err)
+		}
+		if err := authAtomicWrite(mcpURLPath, []byte(mcpBaseURL), config.FilePerm); err != nil {
+			return fmt.Errorf("save explicit MCP URL: %w", err)
+		}
+		return nil
+	case authLoginMCPUseManagedRegion:
+		managedURL, managedErr := authReadFile(managedRegionPath)
+		if managedErr != nil && !os.IsNotExist(managedErr) {
+			return fmt.Errorf("read managed MCP region: %w", managedErr)
+		}
+		currentURL, currentErr := authReadFile(mcpURLPath)
+		switch {
+		case currentErr == nil && os.IsNotExist(managedErr):
+			return nil
+		case currentErr == nil && strings.TrimSpace(string(currentURL)) != strings.TrimSpace(string(managedURL)):
+			return removeAuthLoginManagedMCPRegion(managedRegionPath)
+		case currentErr != nil && !os.IsNotExist(currentErr):
+			return fmt.Errorf("read MCP URL: %w", currentErr)
+		}
+		if err := authAtomicWrite(managedRegionPath, []byte(mcpBaseURL), config.FilePerm); err != nil {
+			return fmt.Errorf("save managed MCP region: %w", err)
+		}
+		if err := authAtomicWrite(mcpURLPath, []byte(mcpBaseURL), config.FilePerm); err != nil {
+			_ = authRemove(managedRegionPath)
+			return fmt.Errorf("save managed MCP URL: %w", err)
+		}
+		return nil
+	case authLoginMCPUseDefault:
+		managedURL, err := authReadFile(managedRegionPath)
+		if os.IsNotExist(err) {
+			return nil
+		}
+		if err != nil {
+			return fmt.Errorf("read managed MCP region: %w", err)
+		}
+		currentURL, err := authReadFile(mcpURLPath)
+		if os.IsNotExist(err) {
+			return removeAuthLoginManagedMCPRegion(managedRegionPath)
+		}
+		if err != nil {
+			return fmt.Errorf("read MCP URL: %w", err)
+		}
+		if strings.TrimSpace(string(currentURL)) != strings.TrimSpace(string(managedURL)) {
+			return removeAuthLoginManagedMCPRegion(managedRegionPath)
+		}
+		if err := authAtomicWrite(mcpURLPath, []byte(mcpBaseURL), config.FilePerm); err != nil {
+			return fmt.Errorf("restore default MCP URL: %w", err)
+		}
+		return removeAuthLoginManagedMCPRegion(managedRegionPath)
+	default:
+		return fmt.Errorf("unsupported MCP persistence mode %d", persistence)
+	}
+}
+
+func removeAuthLoginManagedMCPRegion(path string) error {
+	if err := authRemove(path); err != nil && !os.IsNotExist(err) {
+		return err
+	}
+	return nil
+}
+
+func normalizeAuthLoginBaseURL(raw, flagName string) (*url.URL, string, error) {
+	value := strings.TrimSpace(raw)
+	if value == "" {
+		return nil, "", apperrors.NewValidation(flagName + " cannot be empty")
+	}
+	if !strings.Contains(value, "://") {
+		value = "https://" + value
+	}
+	parsed, err := url.Parse(value)
+	if err != nil {
+		return nil, "", apperrors.NewValidation(fmt.Sprintf("invalid %s: %v", flagName, err))
+	}
+	if parsed.Scheme != "http" && parsed.Scheme != "https" {
+		return nil, "", apperrors.NewValidation(flagName + " must use http or https")
+	}
+	if parsed.Hostname() == "" {
+		return nil, "", apperrors.NewValidation(flagName + " must include a host")
+	}
+	if parsed.Scheme == "http" && !isAuthLoginLoopbackHost(parsed.Hostname()) {
+		return nil, "", apperrors.NewValidation(flagName + " must use HTTPS, except for a loopback HTTP test endpoint")
+	}
+	parsed.RawQuery = ""
+	parsed.Fragment = ""
+	parsed.Path = strings.TrimRight(parsed.Path, "/")
+	return parsed, strings.TrimRight(parsed.String(), "/"), nil
+}
+
+func isAuthLoginLoopbackHost(host string) bool {
+	if strings.EqualFold(strings.TrimSpace(host), "localhost") {
+		return true
+	}
+	ip := net.ParseIP(strings.TrimSpace(host))
+	return ip != nil && ip.IsLoopback()
+}
+
+func authLoginURLWithHost(parsed *url.URL, host string) string {
+	copyURL := *parsed
+	if port := parsed.Port(); port != "" {
+		copyURL.Host = net.JoinHostPort(host, port)
+	} else {
+		copyURL.Host = host
+	}
+	return strings.TrimRight(copyURL.String(), "/")
+}
+
 func authLoginForcesAuthorization(_ authLoginConfig) bool {
 	return true
 }

internal/app/auth_command_full_coverage_test.go

@@ -7,6 +7,7 @@ import (
 	"fmt"
 	"io"
 	"os"
+	"path/filepath"
 	"strings"
 	"testing"
 	"time"
@@ -214,7 +215,8 @@ func TestCrossPlatformCoverageAuthCoverageFormsParentAndTargets(t *testing.T) {
 }
 
 func TestCrossPlatformCoverageAuthCoverageLoginFlows(t *testing.T) {
-	t.Setenv("DWS_CONFIG_DIR", t.TempDir())
+	configDir := t.TempDir()
+	t.Setenv("DWS_CONFIG_DIR", configDir)
 	oldSave := authSaveTokenData
 	oldDevice := authDeviceLogin
 	oldOAuth := authOAuthLogin
@@ -255,6 +257,15 @@ func TestCrossPlatformCoverageAuthCoverageLoginFlows(t *testing.T) {
 	if out, _, err := authCoverageRunLogin(t, nil, "json", true, map[string]string{"token": "token"}); err != nil || !strings.Contains(out, `"token_valid": true`) {
 		t.Fatalf("json token login = %q, %v", out, err)
 	}
+	if _, _, err := authCoverageRunLogin(t, nil, "table", true, map[string]string{"token": "token", "pre-url": "https://example.com"}); err == nil {
+		t.Fatal("invalid pre-release host should fail")
+	}
+	if _, _, err := authCoverageRunLogin(t, nil, "table", true, map[string]string{"token": "token", "mcp-url": "http://remote.example.com"}); err == nil {
+		t.Fatal("remote plaintext MCP URL should fail")
+	}
+	if _, _, err := authCoverageRunLogin(t, nil, "table", true, map[string]string{"token": "token", "pre-url": "https://pre-login.dingtalk.io"}); err != nil {
+		t.Fatalf("pre-release token login = %v", err)
+	}
 
 	authDeviceLogin = func(*authpkg.DeviceFlowProvider, context.Context) (*authpkg.TokenData, error) {
 		return nil, errors.New("device")
@@ -271,6 +282,15 @@ func TestCrossPlatformCoverageAuthCoverageLoginFlows(t *testing.T) {
 	if _, _, err := authCoverageRunLogin(t, nil, "table", true, map[string]string{"device": "true", "no-browser": "true"}); err != nil {
 		t.Fatal(err)
 	}
+	authDeviceLogin = func(provider *authpkg.DeviceFlowProvider, _ context.Context) (*authpkg.TokenData, error) {
+		if provider.LoginRegion != authpkg.LoginRegionInternational {
+			t.Errorf("device login region = %q, want international", provider.LoginRegion)
+		}
+		return &authpkg.TokenData{AccessToken: "a", ExpiresAt: time.Now().Add(time.Hour)}, nil
+	}
+	if _, _, err := authCoverageRunLogin(t, nil, "table", true, map[string]string{"device": "true", "intl": "true"}); err != nil {
+		t.Fatalf("international device login = %v", err)
+	}
 
 	authOAuthLogin = func(*authpkg.OAuthProvider, context.Context, bool) (*authpkg.TokenData, error) {
 		return nil, errors.New("oauth")
@@ -291,6 +311,25 @@ func TestCrossPlatformCoverageAuthCoverageLoginFlows(t *testing.T) {
 	if out, _, err := authCoverageRunLogin(t, caller, "table", true, map[string]string{"no-browser": "true"}); err != nil || !strings.Contains(out, "Corp") {
 		t.Fatalf("oauth success = %q, %v", out, err)
 	}
+	authOAuthLogin = func(provider *authpkg.OAuthProvider, _ context.Context, _ bool) (*authpkg.TokenData, error) {
+		if provider.LoginRegion != authpkg.LoginRegionInternational {
+			t.Errorf("OAuth login region = %q, want international", provider.LoginRegion)
+		}
+		return &authpkg.TokenData{AccessToken: "a", ExpiresAt: time.Now().Add(time.Hour)}, nil
+	}
+	if _, _, err := authCoverageRunLogin(t, nil, "table", true, map[string]string{"intl": "true"}); err != nil {
+		t.Fatalf("international OAuth login = %v", err)
+	}
+
+	blockedConfigDir := t.TempDir()
+	if err := os.Mkdir(filepath.Join(blockedConfigDir, "mcp_url"), 0o700); err != nil {
+		t.Fatal(err)
+	}
+	t.Setenv("DWS_CONFIG_DIR", blockedConfigDir)
+	if _, _, err := authCoverageRunLogin(t, nil, "table", true, map[string]string{"token": "token", "intl": "true"}); err == nil || !strings.Contains(err.Error(), "failed to persist MCP URL") {
+		t.Fatalf("MCP URL persist failure = %v", err)
+	}
+	t.Setenv("DWS_CONFIG_DIR", configDir)
 
 	authRunLoginRecommend = func(context.Context, edition.ToolCaller, io.Writer, pat.LoginRecommendOptions) error {
 		return errors.New("recommend")
@@ -1418,7 +1457,7 @@ func TestCrossPlatformCoverageAuthCoveragePortableExchangeAndReset(t *testing.T)
 	authRemove = func(string) error { removed++; return errors.New("ignored") }
 	authDeleteAppConfig = func(string) error { removed++; return errors.New("ignored") }
 	edition.Override(&edition.Hooks{})
-	if err := reset.RunE(reset, nil); err != nil || removed != 3 || !strings.Contains(out.String(), "重新登录") {
+	if err := reset.RunE(reset, nil); err != nil || removed != 4 || !strings.Contains(out.String(), "重新登录") {
 		t.Fatalf("reset = %q, %v, removed=%d", out.String(), err, removed)
 	}
 	edition.Override(&edition.Hooks{IsEmbedded: true})

internal/app/auth_command_test.go

@@ -33,6 +33,8 @@ import (
 	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/keychain"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/pat"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/config"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition"
 	"github.com/spf13/cobra"
 )
@@ -1033,8 +1035,12 @@ func TestResolveAuthLoginConfigReadsInheritedYes(t *testing.T) {
 	login := &cobra.Command{Use: "login"}
 	login.Flags().String("token", "", "")
 	login.Flags().Bool("device", false, "")
+	login.Flags().Bool("intl", false, "")
+	login.Flags().Bool("international", false, "")
 	login.Flags().Bool("force", false, "")
 	login.Flags().Bool("recommend", false, "")
+	login.Flags().String("pre-url", "", "")
+	login.Flags().String("mcp-url", "", "")
 	root.AddCommand(login)
 
 	if err := root.PersistentFlags().Set("yes", "true"); err != nil {
@@ -1061,6 +1067,560 @@ func TestResolveAuthLoginConfigReadsInheritedYes(t *testing.T) {
 	}
 }
 
+func TestCrossPlatformCoverageResolveAuthLoginConfigReadsInternationalAliases(t *testing.T) {
+	for _, flag := range []string{"intl", "international"} {
+		t.Run(flag, func(t *testing.T) {
+			root := &cobra.Command{Use: "dws"}
+			root.PersistentFlags().Bool("yes", false, "")
+			login := &cobra.Command{Use: "login"}
+			login.Flags().String("token", "", "")
+			login.Flags().Bool("device", false, "")
+			login.Flags().Bool("intl", false, "")
+			login.Flags().Bool("international", false, "")
+			login.Flags().Bool("force", false, "")
+			login.Flags().Bool("recommend", false, "")
+			login.Flags().String("pre-url", "", "")
+			login.Flags().String("mcp-url", "", "")
+			root.AddCommand(login)
+
+			if err := login.Flags().Set(flag, "true"); err != nil {
+				t.Fatalf("set %s: %v", flag, err)
+			}
+
+			cfg, err := resolveAuthLoginConfig(login)
+			if err != nil {
+				t.Fatalf("resolveAuthLoginConfig error = %v", err)
+			}
+			if !cfg.International {
+				t.Fatalf("International = false for --%s, want true", flag)
+			}
+		})
+	}
+
+	for _, tc := range []struct {
+		name  string
+		setup func(*cobra.Command)
+	}{
+		{
+			name: "missing intl",
+			setup: func(cmd *cobra.Command) {
+				cmd.Flags().String("token", "", "")
+				cmd.Flags().Bool("device", false, "")
+			},
+		},
+		{
+			name: "missing international",
+			setup: func(cmd *cobra.Command) {
+				cmd.Flags().String("token", "", "")
+				cmd.Flags().Bool("device", false, "")
+				cmd.Flags().Bool("intl", false, "")
+			},
+		},
+		{
+			name: "missing pre url",
+			setup: func(cmd *cobra.Command) {
+				cmd.Flags().String("token", "", "")
+				cmd.Flags().Bool("device", false, "")
+				cmd.Flags().Bool("intl", false, "")
+				cmd.Flags().Bool("international", false, "")
+				cmd.Flags().Bool("force", false, "")
+				cmd.Flags().Bool("recommend", false, "")
+			},
+		},
+		{
+			name: "missing mcp url",
+			setup: func(cmd *cobra.Command) {
+				cmd.Flags().String("token", "", "")
+				cmd.Flags().Bool("device", false, "")
+				cmd.Flags().Bool("intl", false, "")
+				cmd.Flags().Bool("international", false, "")
+				cmd.Flags().Bool("force", false, "")
+				cmd.Flags().Bool("recommend", false, "")
+				cmd.Flags().String("pre-url", "", "")
+			},
+		},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			cmd := &cobra.Command{Use: "login"}
+			tc.setup(cmd)
+			if _, err := resolveAuthLoginConfig(cmd); err == nil {
+				t.Fatal("resolveAuthLoginConfig succeeded with an incomplete flag set")
+			}
+		})
+	}
+}
+
+func TestCrossPlatformCoverageResolveAuthLoginConfigReadsMCPURL(t *testing.T) {
+	root := &cobra.Command{Use: "dws"}
+	root.PersistentFlags().Bool("yes", false, "")
+	login := &cobra.Command{Use: "login"}
+	login.Flags().String("token", "", "")
+	login.Flags().Bool("device", false, "")
+	login.Flags().Bool("intl", false, "")
+	login.Flags().Bool("international", false, "")
+	login.Flags().Bool("force", false, "")
+	login.Flags().Bool("recommend", false, "")
+	login.Flags().String("pre-url", "", "")
+	login.Flags().String("mcp-url", "", "")
+	root.AddCommand(login)
+
+	if err := login.Flags().Set("mcp-url", " https://pre-mcp.dingtalk.io/ "); err != nil {
+		t.Fatalf("set mcp-url: %v", err)
+	}
+
+	cfg, err := resolveAuthLoginConfig(login)
+	if err != nil {
+		t.Fatalf("resolveAuthLoginConfig error = %v", err)
+	}
+	if cfg.MCPURL != "https://pre-mcp.dingtalk.io/" {
+		t.Fatalf("MCPURL = %q, want trimmed flag value", cfg.MCPURL)
+	}
+}
+
+func TestCrossPlatformCoverageResolveAuthLoginConfigReadsPreURL(t *testing.T) {
+	root := &cobra.Command{Use: "dws"}
+	root.PersistentFlags().Bool("yes", false, "")
+	login := &cobra.Command{Use: "login"}
+	login.Flags().String("token", "", "")
+	login.Flags().Bool("device", false, "")
+	login.Flags().Bool("intl", false, "")
+	login.Flags().Bool("international", false, "")
+	login.Flags().Bool("force", false, "")
+	login.Flags().Bool("recommend", false, "")
+	login.Flags().String("pre-url", "", "")
+	login.Flags().String("mcp-url", "", "")
+	root.AddCommand(login)
+
+	if err := login.Flags().Set("pre-url", " pre-login.dingtalk.io "); err != nil {
+		t.Fatalf("set pre-url: %v", err)
+	}
+
+	cfg, err := resolveAuthLoginConfig(login)
+	if err != nil {
+		t.Fatalf("resolveAuthLoginConfig error = %v", err)
+	}
+	if cfg.PreURL != "pre-login.dingtalk.io" {
+		t.Fatalf("PreURL = %q, want trimmed flag value", cfg.PreURL)
+	}
+}
+
+func TestCrossPlatformCoverageAuthLoginEndpointOverridesForPreURL(t *testing.T) {
+	tests := []struct {
+		name      string
+		raw       string
+		wantLogin string
+		wantMCP   string
+	}{
+		{
+			name:      "pre login",
+			raw:       "https://pre-login.dingtalk.io/",
+			wantLogin: "https://pre-login.dingtalk.io",
+			wantMCP:   "https://pre-mcp.dingtalk.io",
+		},
+		{
+			name:      "pre mcp",
+			raw:       "pre-mcp.dingtalk.io",
+			wantLogin: "https://pre-login.dingtalk.io",
+			wantMCP:   "https://pre-mcp.dingtalk.io",
+		},
+		{
+			name:      "pre login with port",
+			raw:       "https://pre-login.dingtalk.io:8443/path/",
+			wantLogin: "https://pre-login.dingtalk.io:8443/path",
+			wantMCP:   "https://pre-mcp.dingtalk.io:8443/path",
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			got, err := authLoginEndpointOverridesForPreURL(tc.raw)
+			if err != nil {
+				t.Fatalf("authLoginEndpointOverridesForPreURL error = %v", err)
+			}
+			if got.LoginURL != tc.wantLogin || got.MCPURL != tc.wantMCP {
+				t.Fatalf("overrides = %#v, want login %q mcp %q", got, tc.wantLogin, tc.wantMCP)
+			}
+		})
+	}
+
+	for _, raw := range []string{"https://example.com", "http://pre-login.example.com"} {
+		if _, err := authLoginEndpointOverridesForPreURL(raw); err == nil {
+			t.Fatalf("authLoginEndpointOverridesForPreURL(%q) succeeded", raw)
+		}
+	}
+}
+
+func TestCrossPlatformCoverageAuthLoginMCPBaseURLForConfig(t *testing.T) {
+	tests := []struct {
+		name            string
+		cfg             authLoginConfig
+		preOverride     authLoginEndpointOverrides
+		wantURL         string
+		wantPersistence authLoginMCPPersistence
+	}{
+		{
+			name:            "default center login uses com and resets only managed region",
+			cfg:             authLoginConfig{},
+			wantURL:         authpkg.DefaultMCPBaseURL,
+			wantPersistence: authLoginMCPUseDefault,
+		},
+		{
+			name:            "international login persists managed io",
+			cfg:             authLoginConfig{International: true},
+			wantURL:         authpkg.InternationalMCPBaseURL,
+			wantPersistence: authLoginMCPUseManagedRegion,
+		},
+		{
+			name: "pre login persists mapped pre mcp",
+			cfg:  authLoginConfig{PreURL: "pre-login.dingtalk.io"},
+			preOverride: authLoginEndpointOverrides{
+				LoginURL: "https://pre-login.dingtalk.io",
+				MCPURL:   "https://pre-mcp.dingtalk.io",
+			},
+			wantURL:         "https://pre-mcp.dingtalk.io",
+			wantPersistence: authLoginMCPUseExplicitOverride,
+		},
+		{
+			name: "explicit mcp url wins over pre url",
+			cfg: authLoginConfig{
+				PreURL: "pre-login.dingtalk.io",
+				MCPURL: " https://custom-mcp.example.com/ ",
+			},
+			preOverride: authLoginEndpointOverrides{
+				LoginURL: "https://pre-login.dingtalk.io",
+				MCPURL:   "https://pre-mcp.dingtalk.io",
+			},
+			wantURL:         "https://custom-mcp.example.com",
+			wantPersistence: authLoginMCPUseExplicitOverride,
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			gotURL, gotPersistence, err := authLoginMCPBaseURLForConfig(tc.cfg, tc.preOverride)
+			if err != nil {
+				t.Fatalf("authLoginMCPBaseURLForConfig error = %v", err)
+			}
+			if gotURL != tc.wantURL || gotPersistence != tc.wantPersistence {
+				t.Fatalf("got url=%q persistence=%v, want url=%q persistence=%v", gotURL, gotPersistence, tc.wantURL, tc.wantPersistence)
+			}
+		})
+	}
+
+	for _, cfg := range []authLoginConfig{
+		{MCPURL: "http://remote.example.com"},
+		{PreURL: "https://example.com"},
+	} {
+		if _, _, err := authLoginMCPBaseURLForConfig(cfg, authLoginEndpointOverrides{}); err == nil {
+			t.Fatalf("authLoginMCPBaseURLForConfig(%#v) succeeded", cfg)
+		}
+	}
+}
+
+func TestCrossPlatformCoveragePersistAuthLoginMCPBaseURL(t *testing.T) {
+	t.Run("persists selected io mcp url", func(t *testing.T) {
+		configDir := t.TempDir()
+		if err := persistAuthLoginMCPBaseURL(configDir, authpkg.InternationalMCPBaseURL, authLoginMCPUseManagedRegion); err != nil {
+			t.Fatalf("persistAuthLoginMCPBaseURL error = %v", err)
+		}
+		data, err := os.ReadFile(filepath.Join(configDir, "mcp_url"))
+		if err != nil {
+			t.Fatalf("ReadFile(mcp_url) error = %v", err)
+		}
+		if string(data) != authpkg.InternationalMCPBaseURL {
+			t.Fatalf("mcp_url = %q, want %q", string(data), authpkg.InternationalMCPBaseURL)
+		}
+		managed, err := os.ReadFile(filepath.Join(configDir, config.ManagedMCPURLRegionFileName))
+		if err != nil || string(managed) != authpkg.InternationalMCPBaseURL {
+			t.Fatalf("managed MCP region = %q, %v", string(managed), err)
+		}
+	})
+
+	t.Run("center login preserves previous persisted override", func(t *testing.T) {
+		configDir := t.TempDir()
+		mcpURLPath := filepath.Join(configDir, "mcp_url")
+		const customURL = "https://custom-mcp.example.com"
+		if err := os.WriteFile(mcpURLPath, []byte(customURL), 0o600); err != nil {
+			t.Fatalf("WriteFile(mcp_url) error = %v", err)
+		}
+		if err := persistAuthLoginMCPBaseURL(configDir, authpkg.DefaultMCPBaseURL, authLoginMCPUseDefault); err != nil {
+			t.Fatalf("persistAuthLoginMCPBaseURL error = %v", err)
+		}
+		data, err := os.ReadFile(mcpURLPath)
+		if err != nil {
+			t.Fatalf("ReadFile(mcp_url) error = %v", err)
+		}
+		if string(data) != customURL {
+			t.Fatalf("mcp_url = %q, want preserved override %q", string(data), customURL)
+		}
+	})
+
+	t.Run("international login preserves an unmanaged explicit override", func(t *testing.T) {
+		configDir := t.TempDir()
+		mcpURLPath := filepath.Join(configDir, "mcp_url")
+		const customURL = "https://private-mcp.example.com"
+		if err := os.WriteFile(mcpURLPath, []byte(customURL), config.FilePerm); err != nil {
+			t.Fatal(err)
+		}
+		if err := persistAuthLoginMCPBaseURL(configDir, authpkg.InternationalMCPBaseURL, authLoginMCPUseManagedRegion); err != nil {
+			t.Fatal(err)
+		}
+		data, err := os.ReadFile(mcpURLPath)
+		if err != nil || string(data) != customURL {
+			t.Fatalf("explicit mcp_url = %q, %v; want preserved custom URL", string(data), err)
+		}
+		if _, err := os.Stat(filepath.Join(configDir, config.ManagedMCPURLRegionFileName)); !os.IsNotExist(err) {
+			t.Fatalf("unmanaged override acquired a managed marker: %v", err)
+		}
+	})
+
+	t.Run("center login resets a managed international URL", func(t *testing.T) {
+		configDir := t.TempDir()
+		if err := persistAuthLoginMCPBaseURL(configDir, authpkg.InternationalMCPBaseURL, authLoginMCPUseManagedRegion); err != nil {
+			t.Fatal(err)
+		}
+		if err := persistAuthLoginMCPBaseURL(configDir, authpkg.DefaultMCPBaseURL, authLoginMCPUseDefault); err != nil {
+			t.Fatal(err)
+		}
+		data, err := os.ReadFile(filepath.Join(configDir, "mcp_url"))
+		if err != nil || string(data) != authpkg.DefaultMCPBaseURL {
+			t.Fatalf("mcp_url = %q, %v; want domestic default", string(data), err)
+		}
+		if _, err := os.Stat(filepath.Join(configDir, config.ManagedMCPURLRegionFileName)); !os.IsNotExist(err) {
+			t.Fatalf("managed region marker remains after domestic login: %v", err)
+		}
+	})
+
+	t.Run("explicit override clears region ownership", func(t *testing.T) {
+		configDir := t.TempDir()
+		if err := persistAuthLoginMCPBaseURL(configDir, authpkg.InternationalMCPBaseURL, authLoginMCPUseManagedRegion); err != nil {
+			t.Fatal(err)
+		}
+		const customURL = "https://custom-mcp.example.com"
+		if err := persistAuthLoginMCPBaseURL(configDir, customURL, authLoginMCPUseExplicitOverride); err != nil {
+			t.Fatal(err)
+		}
+		if err := persistAuthLoginMCPBaseURL(configDir, authpkg.DefaultMCPBaseURL, authLoginMCPUseDefault); err != nil {
+			t.Fatal(err)
+		}
+		data, err := os.ReadFile(filepath.Join(configDir, "mcp_url"))
+		if err != nil || string(data) != customURL {
+			t.Fatalf("explicit mcp_url = %q, %v; want preserved custom URL", string(data), err)
+		}
+	})
+
+	t.Run("stale marker never deletes a different custom URL", func(t *testing.T) {
+		configDir := t.TempDir()
+		if err := os.WriteFile(filepath.Join(configDir, "mcp_url"), []byte("https://custom.example.com"), config.FilePerm); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(filepath.Join(configDir, config.ManagedMCPURLRegionFileName), []byte(authpkg.InternationalMCPBaseURL), config.FilePerm); err != nil {
+			t.Fatal(err)
+		}
+		if err := persistAuthLoginMCPBaseURL(configDir, authpkg.DefaultMCPBaseURL, authLoginMCPUseDefault); err != nil {
+			t.Fatal(err)
+		}
+		data, err := os.ReadFile(filepath.Join(configDir, "mcp_url"))
+		if err != nil || string(data) != "https://custom.example.com" {
+			t.Fatalf("custom mcp_url = %q, %v", string(data), err)
+		}
+	})
+
+	t.Run("international login clears a stale marker without changing a custom URL", func(t *testing.T) {
+		configDir := t.TempDir()
+		mcpURLPath := filepath.Join(configDir, "mcp_url")
+		managedRegionPath := filepath.Join(configDir, config.ManagedMCPURLRegionFileName)
+		const customURL = "https://private-mcp.example.com"
+		if err := os.WriteFile(mcpURLPath, []byte(customURL), config.FilePerm); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(managedRegionPath, []byte(authpkg.DefaultMCPBaseURL), config.FilePerm); err != nil {
+			t.Fatal(err)
+		}
+		if err := persistAuthLoginMCPBaseURL(configDir, authpkg.InternationalMCPBaseURL, authLoginMCPUseManagedRegion); err != nil {
+			t.Fatal(err)
+		}
+		data, err := os.ReadFile(mcpURLPath)
+		if err != nil || string(data) != customURL {
+			t.Fatalf("custom mcp_url = %q, %v", string(data), err)
+		}
+		if _, err := os.Stat(managedRegionPath); !os.IsNotExist(err) {
+			t.Fatalf("stale managed marker remains: %v", err)
+		}
+	})
+}
+
+func TestCrossPlatformCoveragePersistAuthLoginMCPBaseURLErrors(t *testing.T) {
+	fail := errors.New("persist failure")
+
+	t.Run("explicit marker cleanup", func(t *testing.T) {
+		testseam.Swap(t, &authRemove, func(string) error { return fail })
+		if err := persistAuthLoginMCPBaseURL(t.TempDir(), "https://custom.example.com", authLoginMCPUseExplicitOverride); !errors.Is(err, fail) {
+			t.Fatalf("explicit marker cleanup error = %v", err)
+		}
+	})
+
+	t.Run("explicit URL write", func(t *testing.T) {
+		testseam.Swap(t, &authAtomicWrite, func(string, []byte, os.FileMode) error { return fail })
+		if err := persistAuthLoginMCPBaseURL(t.TempDir(), "https://custom.example.com", authLoginMCPUseExplicitOverride); !errors.Is(err, fail) {
+			t.Fatalf("explicit URL write error = %v", err)
+		}
+	})
+
+	t.Run("managed marker write", func(t *testing.T) {
+		testseam.Swap(t, &authAtomicWrite, func(string, []byte, os.FileMode) error { return fail })
+		if err := persistAuthLoginMCPBaseURL(t.TempDir(), authpkg.InternationalMCPBaseURL, authLoginMCPUseManagedRegion); !errors.Is(err, fail) {
+			t.Fatalf("managed marker write error = %v", err)
+		}
+	})
+
+	t.Run("managed marker read", func(t *testing.T) {
+		testseam.Swap(t, &authReadFile, func(string) ([]byte, error) { return nil, fail })
+		if err := persistAuthLoginMCPBaseURL(t.TempDir(), authpkg.InternationalMCPBaseURL, authLoginMCPUseManagedRegion); !errors.Is(err, fail) {
+			t.Fatalf("managed marker read error = %v", err)
+		}
+	})
+
+	t.Run("managed MCP URL read", func(t *testing.T) {
+		reads := 0
+		testseam.Swap(t, &authReadFile, func(string) ([]byte, error) {
+			reads++
+			if reads == 1 {
+				return nil, os.ErrNotExist
+			}
+			return nil, fail
+		})
+		if err := persistAuthLoginMCPBaseURL(t.TempDir(), authpkg.InternationalMCPBaseURL, authLoginMCPUseManagedRegion); !errors.Is(err, fail) {
+			t.Fatalf("managed MCP URL read error = %v", err)
+		}
+	})
+
+	t.Run("managed stale marker cleanup", func(t *testing.T) {
+		reads := 0
+		testseam.Swap(t, &authReadFile, func(string) ([]byte, error) {
+			reads++
+			if reads == 1 {
+				return []byte(authpkg.DefaultMCPBaseURL), nil
+			}
+			return []byte("https://private-mcp.example.com"), nil
+		})
+		testseam.Swap(t, &authRemove, func(string) error { return fail })
+		if err := persistAuthLoginMCPBaseURL(t.TempDir(), authpkg.InternationalMCPBaseURL, authLoginMCPUseManagedRegion); !errors.Is(err, fail) {
+			t.Fatalf("managed stale marker cleanup error = %v", err)
+		}
+	})
+
+	t.Run("managed URL write cleans marker", func(t *testing.T) {
+		writes := 0
+		removed := false
+		testseam.Swap(t, &authAtomicWrite, func(string, []byte, os.FileMode) error {
+			writes++
+			if writes == 2 {
+				return fail
+			}
+			return nil
+		})
+		testseam.Swap(t, &authRemove, func(string) error { removed = true; return nil })
+		if err := persistAuthLoginMCPBaseURL(t.TempDir(), authpkg.InternationalMCPBaseURL, authLoginMCPUseManagedRegion); !errors.Is(err, fail) || !removed {
+			t.Fatalf("managed URL write error = %v, marker removed=%v", err, removed)
+		}
+	})
+
+	t.Run("default managed marker read", func(t *testing.T) {
+		testseam.Swap(t, &authReadFile, func(string) ([]byte, error) { return nil, fail })
+		if err := persistAuthLoginMCPBaseURL(t.TempDir(), authpkg.DefaultMCPBaseURL, authLoginMCPUseDefault); !errors.Is(err, fail) {
+			t.Fatalf("managed marker read error = %v", err)
+		}
+	})
+
+	t.Run("missing MCP URL cleans marker", func(t *testing.T) {
+		reads := 0
+		testseam.Swap(t, &authReadFile, func(string) ([]byte, error) {
+			reads++
+			if reads == 1 {
+				return []byte(authpkg.InternationalMCPBaseURL), nil
+			}
+			return nil, os.ErrNotExist
+		})
+		testseam.Swap(t, &authRemove, func(string) error { return nil })
+		if err := persistAuthLoginMCPBaseURL(t.TempDir(), authpkg.DefaultMCPBaseURL, authLoginMCPUseDefault); err != nil {
+			t.Fatalf("missing MCP URL cleanup error = %v", err)
+		}
+	})
+
+	t.Run("MCP URL read", func(t *testing.T) {
+		reads := 0
+		testseam.Swap(t, &authReadFile, func(string) ([]byte, error) {
+			reads++
+			if reads == 1 {
+				return []byte(authpkg.InternationalMCPBaseURL), nil
+			}
+			return nil, fail
+		})
+		if err := persistAuthLoginMCPBaseURL(t.TempDir(), authpkg.DefaultMCPBaseURL, authLoginMCPUseDefault); !errors.Is(err, fail) {
+			t.Fatalf("MCP URL read error = %v", err)
+		}
+	})
+
+	t.Run("default URL write", func(t *testing.T) {
+		testseam.Swap(t, &authReadFile, func(string) ([]byte, error) { return []byte(authpkg.InternationalMCPBaseURL), nil })
+		testseam.Swap(t, &authAtomicWrite, func(string, []byte, os.FileMode) error { return fail })
+		if err := persistAuthLoginMCPBaseURL(t.TempDir(), authpkg.DefaultMCPBaseURL, authLoginMCPUseDefault); !errors.Is(err, fail) {
+			t.Fatalf("default URL write error = %v", err)
+		}
+	})
+
+	t.Run("final marker cleanup", func(t *testing.T) {
+		testseam.Swap(t, &authReadFile, func(string) ([]byte, error) { return []byte(authpkg.InternationalMCPBaseURL), nil })
+		testseam.Swap(t, &authAtomicWrite, func(string, []byte, os.FileMode) error { return nil })
+		testseam.Swap(t, &authRemove, func(string) error { return fail })
+		if err := persistAuthLoginMCPBaseURL(t.TempDir(), authpkg.DefaultMCPBaseURL, authLoginMCPUseDefault); !errors.Is(err, fail) {
+			t.Fatalf("final marker cleanup error = %v", err)
+		}
+	})
+
+	if err := persistAuthLoginMCPBaseURL(t.TempDir(), authpkg.DefaultMCPBaseURL, authLoginMCPPersistence(255)); err == nil {
+		t.Fatal("unsupported MCP persistence mode succeeded")
+	}
+}
+
+func TestCrossPlatformCoverageNormalizeAuthLoginBaseURLTransportSecurity(t *testing.T) {
+	tests := []struct {
+		name    string
+		raw     string
+		wantURL string
+		wantErr string
+	}{
+		{name: "https remote", raw: "https://pre-mcp.example.com/path/?secret=drop#fragment", wantURL: "https://pre-mcp.example.com/path"},
+		{name: "http localhost", raw: "http://localhost:8080/", wantURL: "http://localhost:8080"},
+		{name: "http IPv4 loopback", raw: "http://127.0.0.1:8080", wantURL: "http://127.0.0.1:8080"},
+		{name: "http IPv6 loopback", raw: "http://[::1]:8080", wantURL: "http://[::1]:8080"},
+		{name: "http remote", raw: "http://pre-mcp.example.com", wantErr: "must use HTTPS"},
+		{name: "empty", raw: " ", wantErr: "cannot be empty"},
+		{name: "invalid URL", raw: "https://%", wantErr: "invalid --mcp-url"},
+		{name: "invalid scheme", raw: "ftp://pre-mcp.example.com", wantErr: "must use http or https"},
+		{name: "missing host", raw: "https:///path", wantErr: "must include a host"},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			_, got, err := normalizeAuthLoginBaseURL(tc.raw, "--mcp-url")
+			if tc.wantErr != "" {
+				if err == nil || !strings.Contains(err.Error(), tc.wantErr) {
+					t.Fatalf("normalizeAuthLoginBaseURL error = %v, want containing %q", err, tc.wantErr)
+				}
+				return
+			}
+			if err != nil {
+				t.Fatalf("normalizeAuthLoginBaseURL error = %v", err)
+			}
+			if got != tc.wantURL {
+				t.Fatalf("normalized URL = %q, want %q", got, tc.wantURL)
+			}
+		})
+	}
+}
+
 func TestAuthLoginForcesAuthorizationByDefault(t *testing.T) {
 	if !authLoginForcesAuthorization(authLoginConfig{}) {
 		t.Fatal("auth login should force authorization by default so each login can add an organization profile")

internal/app/coverage_edges_test.go

@@ -36,6 +36,7 @@ import (
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/skillstate"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/transport"
 	upgradepkg "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/upgrade"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/config"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/mcptypes"
 	tea "github.com/charmbracelet/bubbletea"
@@ -326,6 +327,29 @@ func TestCrossPlatformCoverageSmallAppRegistryAndRootCoverage(t *testing.T) {
 func TestCrossPlatformCoverageDirectRuntimeCoverage(t *testing.T) {
 	oldEdition := edition.Get()
 	t.Cleanup(func() { edition.Override(oldEdition); SetDynamicServers(nil) })
+	for _, tc := range []struct {
+		raw    string
+		region authpkg.LoginRegion
+		want   string
+	}{
+		{raw: "%", want: "%"},
+		{raw: "https://dingtalk.io/path", want: "https://dingtalk.com/path"},
+		{raw: "https://mcp.dingtalk.com:8443/path", region: authpkg.LoginRegionInternational, want: "https://mcp.dingtalk.io:8443/path"},
+	} {
+		if got := mcpBaseURLForLoginRegion(tc.raw, tc.region); got != tc.want {
+			t.Fatalf("mcpBaseURLForLoginRegion(%q, %q) = %q, want %q", tc.raw, tc.region, got, tc.want)
+		}
+	}
+	if hasDirectRuntimeEndpointOverride("") {
+		t.Fatal("blank product unexpectedly has an endpoint override")
+	}
+	t.Setenv("DINGTALK_COVERAGE_PRODUCT_MCP_URL", "https://override.test")
+	if !hasDirectRuntimeEndpointOverride("coverage-product") {
+		t.Fatal("configured product endpoint override was not detected")
+	}
+	if got := activeDingTalkGatewayEndpointWithBase("https://mcp-gw.dingtalk.com/server/contact", "%"); got != "https://mcp-gw.dingtalk.com/server/contact" {
+		t.Fatalf("invalid gateway base rewrote endpoint to %q", got)
+	}
 	server := mcptypes.ServerDescriptor{
 		Endpoint: "https://one.test",
 		CLI: mcptypes.CLIOverlay{
@@ -913,12 +937,21 @@ func TestCrossPlatformCoverageAuthCommandPureCoverage(t *testing.T) {
 }
 
 func TestCrossPlatformCoverageAuthLoginTokenCommandCoverage(t *testing.T) {
+	t.Setenv(keychain.DisableKeychainEnv, "1")
+	t.Setenv(keychain.StorageDirEnv, t.TempDir())
 	oldInteractive := authLoginInteractiveTerminal
 	authLoginInteractiveTerminal = func() bool { return false }
 	t.Cleanup(func() { authLoginInteractiveTerminal = oldInteractive; authpkg.SetRuntimeProfile("") })
-	for _, format := range []string{"table", "json"} {
-		t.Run(format, func(t *testing.T) {
-			t.Setenv("DWS_CONFIG_DIR", t.TempDir())
+	for _, tc := range []struct {
+		format        string
+		international bool
+	}{
+		{format: "table"},
+		{format: "json", international: true},
+	} {
+		t.Run(tc.format, func(t *testing.T) {
+			configDir := t.TempDir()
+			t.Setenv("DWS_CONFIG_DIR", configDir)
 			root := &cobra.Command{Use: "dws"}
 			root.PersistentFlags().String("format", "table", "")
 			root.PersistentFlags().Bool("yes", false, "")
@@ -929,16 +962,90 @@ func TestCrossPlatformCoverageAuthLoginTokenCommandCoverage(t *testing.T) {
 			root.SetOut(&output)
 			root.SetErr(io.Discard)
 			args := []string{"login", "--token", "manual-token", "--yes"}
-			if format == "json" {
+			if tc.international {
+				args = append(args, "--intl")
+			}
+			if tc.format == "json" {
 				args = append(args, "--format", "json")
 			}
 			root.SetArgs(args)
 			if err := root.Execute(); err != nil || output.Len() == 0 {
 				t.Fatalf("token login = %q %v", output.String(), err)
 			}
+			data, err := authpkg.LoadTokenData(configDir)
+			if err != nil {
+				t.Fatalf("LoadTokenData error = %v", err)
+			}
+			wantRegion := ""
+			if tc.international {
+				wantRegion = string(authpkg.LoginRegionInternational)
+			}
+			if data.LoginRegion != wantRegion {
+				t.Fatalf("LoginRegion = %q, want %q", data.LoginRegion, wantRegion)
+			}
+			if tc.international {
+				snapshot, err := resolveAccessTokenSnapshotFromDir(context.Background(), configDir, "")
+				if err != nil {
+					t.Fatalf("resolveAccessTokenSnapshotFromDir error = %v", err)
+				}
+				gotEndpoint := activeDingTalkGatewayEndpointForLoginRegion(
+					"https://mcp-gw.dingtalk.com/server/contact",
+					snapshot.LoginRegion,
+				)
+				if wantEndpoint := "https://mcp-gw.dingtalk.io/server/contact"; gotEndpoint != wantEndpoint {
+					t.Fatalf("international manual-token endpoint = %q, want %q", gotEndpoint, wantEndpoint)
+				}
+			}
 		})
 	}
 
+	t.Run("international then domestic login restores domestic MCP URL", func(t *testing.T) {
+		configDir := t.TempDir()
+		t.Setenv("DWS_CONFIG_DIR", configDir)
+		runLogin := func(international bool) {
+			t.Helper()
+			root := &cobra.Command{Use: "dws"}
+			root.PersistentFlags().String("format", "table", "")
+			root.PersistentFlags().Bool("yes", false, "")
+			root.PersistentFlags().String("profile", "", "")
+			root.AddCommand(newAuthLoginCommand(nil))
+			args := []string{"login", "--token", "manual-token", "--yes"}
+			if international {
+				args = append(args, "--intl")
+			}
+			root.SetArgs(args)
+			root.SetOut(io.Discard)
+			root.SetErr(io.Discard)
+			if err := root.Execute(); err != nil {
+				t.Fatalf("international=%v login error = %v", international, err)
+			}
+		}
+
+		runLogin(true)
+		if data, err := os.ReadFile(filepath.Join(configDir, "mcp_url")); err != nil || string(data) != authpkg.InternationalMCPBaseURL {
+			t.Fatalf("international mcp_url = %q, %v", string(data), err)
+		}
+		runLogin(false)
+		if data, err := os.ReadFile(filepath.Join(configDir, "mcp_url")); err != nil || string(data) != authpkg.DefaultMCPBaseURL {
+			t.Fatalf("domestic mcp_url = %q, %v", string(data), err)
+		}
+		if _, err := os.Stat(filepath.Join(configDir, config.ManagedMCPURLRegionFileName)); !os.IsNotExist(err) {
+			t.Fatalf("managed MCP region marker remains: %v", err)
+		}
+
+		const customURL = "https://private-mcp.example.com"
+		if err := os.WriteFile(filepath.Join(configDir, "mcp_url"), []byte(customURL), config.FilePerm); err != nil {
+			t.Fatal(err)
+		}
+		runLogin(true)
+		if data, err := os.ReadFile(filepath.Join(configDir, "mcp_url")); err != nil || string(data) != customURL {
+			t.Fatalf("explicit mcp_url after international login = %q, %v; want preserved custom URL", string(data), err)
+		}
+		if _, err := os.Stat(filepath.Join(configDir, config.ManagedMCPURLRegionFileName)); !os.IsNotExist(err) {
+			t.Fatalf("explicit mcp_url acquired a managed marker: %v", err)
+		}
+	})
+
 	for _, hidden := range []bool{false, true} {
 		old := edition.Get()
 		edition.Override(&edition.Hooks{HideAuthLogin: hidden})

internal/app/direct_runtime.go

@@ -74,6 +74,20 @@ func defaultPATMCPEndpoint() string {
 
 func defaultPATGatewayBaseURL() string {
 	raw := strings.TrimSpace(authpkg.GetMCPBaseURL())
+	return mcpGatewayBaseURL(raw)
+}
+
+func defaultPATGatewayBaseURLForLoginRegion(region authpkg.LoginRegion) string {
+	raw := strings.TrimSpace(authpkg.GetMCPBaseURL())
+	if override := authpkg.MCPBaseURLOverride(); override != "" {
+		raw = override
+	} else {
+		raw = mcpBaseURLForLoginRegion(raw, region)
+	}
+	return mcpGatewayBaseURL(raw)
+}
+
+func mcpGatewayBaseURL(raw string) string {
 	parsed, err := url.Parse(raw)
 	if err != nil || parsed.Scheme == "" || parsed.Host == "" {
 		return strings.TrimRight(raw, "/")
@@ -100,6 +114,33 @@ func defaultPATGatewayBaseURL() string {
 	return strings.TrimRight(parsed.String(), "/")
 }
 
+func mcpBaseURLForLoginRegion(raw string, region authpkg.LoginRegion) string {
+	parsed, err := url.Parse(strings.TrimSpace(raw))
+	if err != nil || parsed.Scheme == "" || parsed.Host == "" {
+		return raw
+	}
+	host := strings.ToLower(parsed.Hostname())
+	fromSuffix, toSuffix := ".dingtalk.io", ".dingtalk.com"
+	if region.IsInternational() {
+		fromSuffix, toSuffix = toSuffix, fromSuffix
+	}
+	bareFrom := strings.TrimPrefix(fromSuffix, ".")
+	if host != bareFrom && !strings.HasSuffix(host, fromSuffix) {
+		return raw
+	}
+	if host == bareFrom {
+		host = strings.TrimPrefix(toSuffix, ".")
+	} else {
+		host = strings.TrimSuffix(host, fromSuffix) + toSuffix
+	}
+	if port := parsed.Port(); port != "" {
+		parsed.Host = net.JoinHostPort(host, port)
+	} else {
+		parsed.Host = host
+	}
+	return parsed.String()
+}
+
 // SetDynamicServers injects server data discovered from servers.json.
 // All product endpoints are resolved dynamically from this data.
 func SetDynamicServers(servers []mcptypes.ServerDescriptor) {
@@ -131,7 +172,7 @@ func registerDynamicServer(server mcptypes.ServerDescriptor, endpoints map[strin
 		return
 	}
 	id := strings.TrimSpace(server.CLI.ID)
-	endpoint := strings.TrimSpace(server.Endpoint)
+	endpoint := activeDingTalkGatewayEndpoint(server.Endpoint)
 	if id != "" && endpoint != "" {
 		endpoints[id] = endpoint
 		products[id] = true
@@ -262,6 +303,19 @@ func directRuntimeEndpoint(productID, toolName string) (string, bool) {
 	return "", false
 }
 
+func hasDirectRuntimeEndpointOverride(productID string) bool {
+	normalized := normalizeDirectRuntimeProductID(productID)
+	for _, candidate := range []string{strings.TrimSpace(productID), normalized} {
+		if candidate == "" {
+			continue
+		}
+		if _, ok := productEndpointOverride(candidate); ok {
+			return true
+		}
+	}
+	return false
+}
+
 func editionServerEndpoint(productID string) (string, bool) {
 	productID = strings.TrimSpace(productID)
 	if productID == "" {
@@ -282,7 +336,7 @@ func endpointFromEditionServers(productID string, fn func() []edition.ServerInfo
 		return "", false
 	}
 	for _, server := range fn() {
-		endpoint := strings.TrimSpace(server.Endpoint)
+		endpoint := activeDingTalkGatewayEndpoint(server.Endpoint)
 		if endpoint == "" {
 			continue
 		}
@@ -298,6 +352,46 @@ func endpointFromEditionServers(productID string, fn func() []edition.ServerInfo
 	return "", false
 }
 
+func activeDingTalkGatewayEndpoint(endpoint string) string {
+	return activeDingTalkGatewayEndpointWithBase(endpoint, defaultPATGatewayBaseURL())
+}
+
+func activeDingTalkGatewayEndpointForLoginRegion(endpoint string, region authpkg.LoginRegion) string {
+	return activeDingTalkGatewayEndpointWithBase(endpoint, defaultPATGatewayBaseURLForLoginRegion(region))
+}
+
+func activeDingTalkGatewayEndpointWithBase(endpoint, gatewayBaseURL string) string {
+	endpoint = strings.TrimSpace(endpoint)
+	parsed, err := url.Parse(endpoint)
+	if err != nil || parsed.Scheme == "" || parsed.Host == "" {
+		return endpoint
+	}
+	if !isDingTalkMCPGatewayHost(parsed.Hostname()) {
+		return endpoint
+	}
+	base, err := url.Parse(gatewayBaseURL)
+	if err != nil || base.Scheme == "" || base.Host == "" {
+		return endpoint
+	}
+	parsed.Scheme = base.Scheme
+	parsed.Host = base.Host
+	return strings.TrimRight(parsed.String(), "/")
+}
+
+func isDingTalkMCPGatewayHost(host string) bool {
+	switch strings.ToLower(strings.TrimSpace(host)) {
+	case "mcp-gw.dingtalk.com", "pre-mcp-gw.dingtalk.com", "mcp-gw.dingtalk.io", "pre-mcp-gw.dingtalk.io":
+		return true
+	default:
+		return false
+	}
+}
+
+func isDingTalkMCPGatewayEndpoint(endpoint string) bool {
+	parsed, err := url.Parse(strings.TrimSpace(endpoint))
+	return err == nil && isDingTalkMCPGatewayHost(parsed.Hostname())
+}
+
 // DirectRuntimeProductIDs returns product IDs that should stay visible for
 // direct runtime execution. Dynamic products come from MCP discovery/plugin
 // registration; built-in helper products such as devapp resolve their endpoint

internal/app/flag_error_test.go

@@ -82,6 +82,46 @@ func TestFlagErrorWithSuggestions_unknownFlagHintAndFlags(t *testing.T) {
 	}
 }
 
+func TestFlagErrorWithSuggestionsChatFromExplainsBothMeanings(t *testing.T) {
+	t.Parallel()
+	root := &cobra.Command{Use: "dws"}
+	chat := &cobra.Command{Use: "chat"}
+	search := &cobra.Command{Use: "+search-msg", Run: func(*cobra.Command, []string) {}}
+	search.Flags().String("sender", "", "sender target")
+	search.Flags().String("start", "", "start time")
+	root.AddCommand(chat)
+	chat.AddCommand(search)
+
+	orig := fmt.Errorf("unknown flag: --from")
+	err := flagErrorWithSuggestions(search, orig)
+	var ae *apperrors.Error
+	if !stderrors.As(err, &ae) {
+		t.Fatalf("want *apperrors.Error, got %T", err)
+	}
+	if ae.Reason != "ambiguous_flag" || !strings.Contains(ae.Hint, "--sender") || !strings.Contains(ae.Hint, "--start") {
+		t.Fatalf("structured error = reason %q hint %q", ae.Reason, ae.Hint)
+	}
+	if !strings.HasSuffix(ae.Message, "See 'dws chat +search-msg --help' for usage.") {
+		t.Fatalf("Message = %q", ae.Message)
+	}
+
+	for _, flag := range []string{"from-file", "from-user"} {
+		t.Run(flag, func(t *testing.T) {
+			err := flagErrorWithSuggestions(search, fmt.Errorf("unknown flag: --%s", flag))
+			var structured *apperrors.Error
+			if stderrors.As(err, &structured) && structured.Reason == "ambiguous_flag" {
+				t.Fatalf("--%s incorrectly used --from ambiguity handling: %#v", flag, structured)
+			}
+			if strings.Contains(err.Error(), "--from 在消息查询中含义不明确") {
+				t.Fatalf("--%s incorrectly received --from ambiguity hint: %v", flag, err)
+			}
+			if !strings.Contains(err.Error(), "unknown flag: --"+flag) {
+				t.Fatalf("error = %q, want original flag --%s", err, flag)
+			}
+		})
+	}
+}
+
 // TestFlagErrorWithSuggestions_fallbackTailHint 验证 fallback 路径（非 unknown flag 类错误，
 // 如 missing required flag / ambiguous shorthand）也带尾部 See '<cmd> --help' for usage.
 // 这是 wukong / docker / kubectl 的通用 UX——任何 flag 解析错误都给用户一条 help 入口。

internal/app/framework_coverage_test.go

@@ -268,7 +268,7 @@ type frameworkFailWriter struct{}
 
 func (frameworkFailWriter) Write([]byte) (int, error) { return 0, errors.New("write failed") }
 
-func TestFrameworkExecutePanicBeforeEmissionUsesUnifiedFailure(t *testing.T) {
+func TestCrossPlatformCoverageFrameworkExecutePanicBeforeEmissionUsesUnifiedFailure(t *testing.T) {
 	for _, failWriter := range []bool{false, true} {
 		t.Run(map[bool]string{false: "emits", true: "fallback"}[failWriter], func(t *testing.T) {
 			testseam.Protect(t, &os.Args)
@@ -470,6 +470,118 @@ func TestCrossPlatformCoverageFrameworkExecuteRareOutcomeBranches(t *testing.T)
 	})
 }
 
+func TestCrossPlatformCoverageExecuteDeterministicInterruptionBranches(t *testing.T) {
+	install := func(t *testing.T, state *processSignalState, stdout, stderr io.Writer) {
+		t.Helper()
+		testseam.Protect(t, &os.Args)
+		os.Args = []string{"dws"}
+		testseam.Swap(t, &rootNormalizeProcessProfileArgs, func() func() { return func() {} })
+		testseam.Swap(t, &rootStopAllStdioClients, func() {})
+		testseam.Swap(t, &rootInstallProcessSignalContext, func(ctx context.Context, _ *output.ResultStore) (context.Context, *processSignalState, func()) {
+			return ctx, state, func() {}
+		})
+		testseam.Swap(t, &rootNewRootCommandWithEngine, func(ctx context.Context, _ *pipeline.Engine) *cobra.Command {
+			cmd := &cobra.Command{Use: "dws", SilenceErrors: true, SilenceUsage: true}
+			output.SetCommandRollout(cmd, output.RolloutUnifiedActive)
+			cmd.SetContext(ctx)
+			cmd.SetOut(stdout)
+			cmd.SetErr(stderr)
+			return cmd
+		})
+	}
+	interrupted := func(primaryCompleted bool) *processSignalState {
+		return &processSignalState{
+			interruption:             &processInterruption{signal: os.Interrupt},
+			primaryCompletedAtSignal: primaryCompleted,
+		}
+	}
+
+	t.Run("preparse interruption emits unified failure", func(t *testing.T) {
+		var stdout bytes.Buffer
+		install(t, interrupted(false), &stdout, io.Discard)
+		testseam.Swap(t, &rootRunPreParse, func(*cobra.Command, *pipeline.Engine) error { return errors.New("preparse failed") })
+		testseam.Swap(t, &rootExecuteCommand, func(*cobra.Command) (*cobra.Command, error) {
+			t.Fatal("preparse failure reached command execution")
+			return nil, nil
+		})
+		if code, _, summary := ExecuteWithTelemetry(); code != 130 || summary == "" || !strings.Contains(stdout.String(), `"outcome": "failure"`) {
+			t.Fatalf("preparse interruption = code %d summary %q stdout %q", code, summary, stdout.String())
+		}
+	})
+
+	t.Run("interruption before emission becomes primary error", func(t *testing.T) {
+		var stdout bytes.Buffer
+		install(t, interrupted(false), &stdout, io.Discard)
+		testseam.Swap(t, &rootRunPreParse, func(*cobra.Command, *pipeline.Engine) error { return nil })
+		testseam.Swap(t, &rootExecuteCommand, func(cmd *cobra.Command) (*cobra.Command, error) { return cmd, nil })
+		if code, _, summary := ExecuteWithTelemetry(); code != 130 || summary == "" || !strings.Contains(stdout.String(), `"outcome": "failure"`) {
+			t.Fatalf("pre-emission interruption = code %d summary %q stdout %q", code, summary, stdout.String())
+		}
+	})
+
+	t.Run("late hook error preserves emitted result", func(t *testing.T) {
+		install(t, interrupted(true), io.Discard, io.Discard)
+		testseam.Swap(t, &rootRunPreParse, func(*cobra.Command, *pipeline.Engine) error { return nil })
+		testseam.Swap(t, &rootExecuteCommand, func(cmd *cobra.Command) (*cobra.Command, error) {
+			if err := output.StoreResult(cmd.Context(), output.Success(map[string]any{"ok": true})); err != nil {
+				t.Fatal(err)
+			}
+			if _, _, err := output.EmitStoredResult(cmd); err != nil {
+				t.Fatal(err)
+			}
+			return cmd, errors.New("late hook failed")
+		})
+		if code, _, summary := ExecuteWithTelemetry(); code != 0 || summary != "late hook failed" {
+			t.Fatalf("late hook result = code %d summary %q", code, summary)
+		}
+	})
+
+	t.Run("interruption after emission preserves emitted result", func(t *testing.T) {
+		install(t, interrupted(false), io.Discard, io.Discard)
+		testseam.Swap(t, &rootRunPreParse, func(*cobra.Command, *pipeline.Engine) error { return nil })
+		testseam.Swap(t, &rootExecuteCommand, func(cmd *cobra.Command) (*cobra.Command, error) {
+			if err := output.StoreResult(cmd.Context(), output.Success(map[string]any{"ok": true})); err != nil {
+				t.Fatal(err)
+			}
+			if _, _, err := output.EmitStoredResult(cmd); err != nil {
+				t.Fatal(err)
+			}
+			return cmd, nil
+		})
+		if code, _, summary := ExecuteWithTelemetry(); code != 0 || summary == "" {
+			t.Fatalf("post-emission interruption = code %d summary %q", code, summary)
+		}
+	})
+
+	t.Run("publication failure replaces unobservable result", func(t *testing.T) {
+		var original bytes.Buffer
+		install(t, interrupted(false), io.Discard, io.Discard)
+		testseam.Swap(t, &rootRunPreParse, func(*cobra.Command, *pipeline.Engine) error { return nil })
+		testseam.Swap(t, &rootExecuteCommand, func(cmd *cobra.Command) (*cobra.Command, error) {
+			if err := output.StoreResult(cmd.Context(), output.Success(map[string]any{"ok": true})); err != nil {
+				t.Fatal(err)
+			}
+			if _, _, err := output.EmitStoredResult(cmd); err != nil {
+				t.Fatal(err)
+			}
+			file, err := os.CreateTemp(t.TempDir(), "finished-output-*")
+			if err != nil {
+				t.Fatal(err)
+			}
+			t.Cleanup(func() { _ = file.Close() })
+			cmd.SetContext(context.WithValue(cmd.Context(), outputFileContextKey{}, &outputSinkState{file: file, original: &original, finished: true}))
+			publicationErr := newOutputPublicationError("publish", errors.New("rename failed"))
+			if _, handled, emitErr := emitOutputPublicationFailure(cmd, publicationErr); !handled || emitErr != nil {
+				t.Fatalf("precondition publication failure = handled %v error %v unified %v state %v", handled, emitErr, output.UsesUnifiedResult(cmd), outputSinkForCommand(cmd) != nil)
+			}
+			return cmd, publicationErr
+		})
+		if code, _, summary := ExecuteWithTelemetry(); code != 5 || summary == "" {
+			t.Fatalf("publication failure = code %d summary %q output %q", code, summary, original.String())
+		}
+	})
+}
+
 type frameworkPanicWriter struct{}
 
 func (frameworkPanicWriter) Write([]byte) (int, error) { panic("writer panic") }

internal/app/param_alias_e2e_test.go

@@ -479,7 +479,11 @@ func TestCrossPlatformCoverageChatReactionConversationAliasesReachCanonicalPaylo
 					if err != nil {
 						t.Fatalf("alias execution failed: %v", err)
 					}
-					if ctx == nil || len(ctx.Corrections) != 1 || ctx.Corrections[0].Original != "--"+alias || ctx.Corrections[0].Corrected != "--conversation-id" {
+					if alias == "open-conversation-id" {
+						if ctx == nil || len(ctx.Corrections) != 0 {
+							t.Fatalf("alias corrections = %#v", ctx)
+						}
+					} else if ctx == nil || len(ctx.Corrections) != 1 || ctx.Corrections[0].Original != "--"+alias || ctx.Corrections[0].Corrected != "--conversation-id" {
 						t.Fatalf("alias corrections = %#v", ctx)
 					}
 					if !reflect.DeepEqual(aliasCaller.calls, canonicalCaller.calls) {

internal/app/profile_args_test.go

@@ -66,6 +66,32 @@ func TestPreparseProfileFlagUsesNormalizedProfileArgs(t *testing.T) {
 	}
 }
 
+func TestCrossPlatformCoveragePreparseProfileFlagUsesLastOccurrence(t *testing.T) {
+	for _, tc := range []struct {
+		name  string
+		args  []string
+		want  string
+		valid bool
+	}{
+		{name: "space then equals", args: []string{"--profile", "corp-a", "version", "--profile=corp-b"}, want: "corp-b", valid: true},
+		{name: "equals then space", args: []string{"--profile=corp-a", "version", "--profile", "corp-b"}, want: "corp-b", valid: true},
+		{name: "last multi", args: []string{"--profile=corp-a", "--profile", "corp-b,", "corp-c", "version"}, want: "corp-b,corp-c", valid: true},
+		{name: "empty equals clears earlier", args: []string{"--profile=corp-a", "version", "--profile="}},
+		{name: "missing value clears earlier", args: []string{"--profile=corp-a", "version", "--profile"}},
+		{name: "next flag is not profile value", args: []string{"--profile=corp-a", "--profile", "--debug", "version"}},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			if got := preparseProfileFlag(tc.args); got != tc.want {
+				t.Fatalf("preparseProfileFlag(%#v) = %q, want %q", tc.args, got, tc.want)
+			}
+			_, specified, valid := preparseProfileSelection(tc.args)
+			if !specified || valid != tc.valid {
+				t.Fatalf("preparseProfileSelection(%#v) = specified %v valid %v, want true/%v", tc.args, specified, valid, tc.valid)
+			}
+		})
+	}
+}
+
 func TestNormalizeProcessProfileArgsRestoresOriginalArgv(t *testing.T) {
 	oldArgs := os.Args
 	t.Cleanup(func() { os.Args = oldArgs })

internal/app/root.go

@@ -80,10 +80,19 @@ var (
 	rootAuthLoadTokenData           = authpkg.LoadTokenData
 	rootNewCommandRunnerWithFlags   = newCommandRunnerWithFlags
 	rootEmitResult                  = output.EmitResult
+	rootInstallProcessSignalContext = installProcessSignalContext
 )
 
 // Execute runs the root command and returns the process exit code.
-func Execute() (exitCode int) {
+func Execute() int {
+	exitCode, _, _ := ExecuteWithTelemetry()
+	return exitCode
+}
+
+// ExecuteWithTelemetry runs the root command and additionally returns a
+// privacy-safe command path and error summary for the official CLI entrypoint.
+func ExecuteWithTelemetry() (exitCode int, commandPath string, errorMessage string) {
+	commandPath = "dws"
 	var (
 		root        *cobra.Command
 		executed    *cobra.Command
@@ -91,12 +100,16 @@ func Execute() (exitCode int) {
 	)
 	defer func() {
 		if r := recover(); r != nil {
+			errorMessage = "internal panic"
 			target := executed
 			if target == nil && root != nil {
 				if found, _, err := root.Find(os.Args[1:]); err == nil {
 					target = found
 				}
 			}
+			if target != nil {
+				commandPath = telemetryCommandPath(target)
+			}
 			if code, attempted, _, _ := output.StoredEmissionState(resultStore); attempted {
 				exitCode = code
 				if target != nil {
@@ -121,6 +134,7 @@ func Execute() (exitCode int) {
 		CloseFileLogger()
 		if executed != nil {
 			if err := closeOutputSink(executed); err != nil {
+				errorMessage = telemetryErrorSummary(err)
 				if code, handled, emitErr := emitOutputPublicationFailure(executed, err); handled && emitErr == nil {
 					exitCode = code
 				} else {
@@ -144,7 +158,9 @@ func Execute() (exitCode int) {
 	agentMetadata := readAgentMetadataSnapshot()
 	if err := agentMetadata.validationError(); err != nil {
 		emitEarlyAgentMetadataValidationError(err, os.Args[1:])
-		return apperrors.ExitCode(err)
+		errorMessage = telemetryErrorSummary(err)
+		exitCode = apperrors.ExitCode(err)
+		return
 	}
 
 	timing := NewTimingCollector()
@@ -162,12 +178,13 @@ func Execute() (exitCode int) {
 	ctx, resultStore = output.WithResultStore(ctx)
 	var signalState *processSignalState
 	var stopSignals func()
-	ctx, signalState, stopSignals = installProcessSignalContext(ctx, resultStore)
+	ctx, signalState, stopSignals = rootInstallProcessSignalContext(ctx, resultStore)
 	defer stopSignals()
 
 	initStart := time.Now()
 	engine := newPipelineEngine()
 	root = rootNewRootCommandWithEngine(ctx, engine)
+	commandPath = telemetryCommandPath(root)
 	timing.Record("cmd_init", time.Since(initStart))
 
 	// Run PreParse handlers on raw argv before Cobra parses flags.
@@ -182,15 +199,23 @@ func Execute() (exitCode int) {
 			result := output.FailureWithExitCode(errorInfoFromExecutionError(err), apperrors.ExitCode(err))
 			code, emitErr := output.EmitResult(target, result)
 			if emitErr == nil {
-				return code
+				errorMessage = telemetryErrorSummary(err)
+				exitCode = code
+				return
 			}
 		}
 		_ = printExecutionError(root, os.Stdout, os.Stderr, err)
-		return apperrors.ExitCode(err)
+		errorMessage = telemetryErrorSummary(err)
+		exitCode = apperrors.ExitCode(err)
+		return
 	}
+	commandPath = telemetryCommandPathForArgs(root, os.Args[1:])
 
 	var err error
 	executed, err = rootExecuteCommand(root)
+	if executed != nil {
+		commandPath = telemetryCommandPath(executed)
+	}
 	// PersistentPostRunE normally commits or aborts the transactional output
 	// sink. Finalize once more at the process boundary so custom execution
 	// seams, embedding callers, or future hook changes cannot leave publication
@@ -222,7 +247,9 @@ func Execute() (exitCode int) {
 				// successfully emitted result into a contradictory 130/143 process
 				// status; likewise, a failed publication must retain its internal
 				// error code instead of being relabelled as cancellation.
-				return code
+				errorMessage = telemetryErrorSummary(interrupted)
+				exitCode = code
+				return
 			}
 		}
 		var publicationErr *outputPublicationError
@@ -233,20 +260,26 @@ func Execute() (exitCode int) {
 	if err != nil {
 		if executed == nil {
 			executed = root
+			commandPath = telemetryCommandPath(root)
 		}
 		if code, attempted, _, _ := output.StoredEmissionState(resultStore); attempted {
 			var publicationErr *outputPublicationError
 			if stderrors.As(err, &publicationErr) {
+				errorMessage = telemetryErrorSummary(publicationErr)
 				if failureCode, handled, emitErr := emitOutputPublicationFailure(executed, publicationErr); handled {
 					if emitErr == nil {
-						return failureCode
+						exitCode = failureCode
+						return
 					}
 					fmt.Fprintf(executed.ErrOrStderr(), "Warning: emit output publication failure: %v\n", emitErr)
 				}
-				return apperrors.ExitCode(publicationErr)
+				exitCode = apperrors.ExitCode(publicationErr)
+				return
 			}
 			fmt.Fprintf(executed.ErrOrStderr(), "Warning: command hook failed after result emission: %v\n", err)
-			return code
+			errorMessage = telemetryErrorSummary(err)
+			exitCode = code
+			return
 		}
 		err = rewordRequiredFlagError(err)
 		var raw apperrors.RawStderrError
@@ -254,7 +287,9 @@ func Execute() (exitCode int) {
 			result := output.FailureWithExitCode(errorInfoFromExecutionError(err), apperrors.ExitCode(err))
 			code, emitErr := output.EmitResult(executed, result)
 			if emitErr == nil {
-				return code
+				errorMessage = telemetryErrorSummary(err)
+				exitCode = code
+				return
 			}
 			err = apperrors.NewInternal("emit failure result: "+emitErr.Error(), apperrors.WithCause(emitErr))
 		}
@@ -264,12 +299,42 @@ func Execute() (exitCode int) {
 			_, _ = fmt.Fprintln(os.Stderr)
 		}
 		_ = printExecutionError(executed, os.Stdout, os.Stderr, err)
-		return apperrors.ExitCode(err)
+		errorMessage = telemetryErrorSummary(err)
+		exitCode = apperrors.ExitCode(err)
+		return
 	}
 	if code, emitted := output.StoredExitCode(resultStore); emitted {
-		return code
+		exitCode = code
+		return
 	}
-	return 0
+	return
+}
+
+func telemetryCommandPath(command *cobra.Command) string {
+	if command == nil {
+		return "dws"
+	}
+	path := strings.TrimSpace(command.CommandPath())
+	root := command.Root()
+	rootName := strings.TrimSpace(root.Name())
+	if path == rootName {
+		return rootName
+	}
+	if rootName != "" {
+		path = strings.TrimSpace(strings.TrimPrefix(path, rootName+" "))
+	}
+	return path
+}
+
+func telemetryCommandPathForArgs(root *cobra.Command, args []string) string {
+	if root == nil {
+		return "dws"
+	}
+	command, _, err := root.Find(args)
+	if err != nil || command == nil {
+		return telemetryCommandPath(root)
+	}
+	return telemetryCommandPath(command)
 }
 
 // emitEarlyAgentMetadataValidationError preserves each built-in command's
@@ -511,6 +576,22 @@ func flagErrorWithSuggestions(cmd *cobra.Command, err error) error {
 	// 无论哪种格式，子串 "--help' for usage." 都可被检索到。
 	tail := fmt.Sprintf("\nSee '%s --help' for usage.", cmd.CommandPath())
 	msgWithTail := errMsg + tail
+	if flag, ok := unknownFlagName(errMsg); ok && flag == "from" {
+		switch cmd.CommandPath() {
+		case "dws chat +search-msg", "dws chat +chat-messages":
+			return apperrors.NewValidation(
+				msgWithTail,
+				apperrors.WithHint("--from 在消息查询中含义不明确：按发送者过滤请使用 --sender <姓名|userId|openDingTalkId>；指定时间起点请使用 --start <RFC3339>"),
+				apperrors.WithReason("ambiguous_flag"),
+				apperrors.WithCause(err),
+				apperrors.WithActions(
+					"Use --sender <姓名|userId|openDingTalkId> to filter by sender",
+					"Use --start <RFC3339> together with --end <RFC3339> to set a time range",
+				),
+				apperrors.WithAvailableFlags(cmdutil.VisibleFlagNames(cmd)...),
+			)
+		}
+	}
 	if flag, protection, ok := reviewedFlagProtection(cmd, errMsg); ok {
 		hint := fmt.Sprintf("Parameter --%s is blocked from automatic normalization on %q; choose an explicit flag from --help.", flag, cmd.CommandPath())
 		reason := "blocked_flag"
@@ -579,15 +660,10 @@ func reviewedFlagProtection(cmd *cobra.Command, errMsg string) (string, pipeline
 	if cmd == nil {
 		return "", "", false
 	}
-	const prefix = "unknown flag: --"
-	idx := strings.Index(errMsg, prefix)
-	if idx < 0 {
+	flag, ok := unknownFlagName(errMsg)
+	if !ok {
 		return "", "", false
 	}
-	flag := strings.TrimSpace(errMsg[idx+len(prefix):])
-	if i := strings.IndexAny(flag, " =\n\t"); i >= 0 {
-		flag = flag[:i]
-	}
 	entry, ok := cli.LookupParamAlias(cmd.CommandPath())
 	if !ok {
 		return "", "", false
@@ -602,6 +678,19 @@ func reviewedFlagProtection(cmd *cobra.Command, errMsg string) (string, pipeline
 	return "", "", false
 }
 
+func unknownFlagName(errMsg string) (string, bool) {
+	const prefix = "unknown flag: --"
+	idx := strings.Index(errMsg, prefix)
+	if idx < 0 {
+		return "", false
+	}
+	flag := strings.TrimSpace(errMsg[idx+len(prefix):])
+	if i := strings.IndexAny(flag, " =\n\t"); i >= 0 {
+		flag = flag[:i]
+	}
+	return flag, flag != ""
+}
+
 func printExecutionError(root *cobra.Command, stdout, stderr io.Writer, err error) error {
 	var raw apperrors.RawStderrError
 	if stderrors.As(err, &raw) {
@@ -935,17 +1024,36 @@ func installReviewedFlagProtectionHandlers(root *cobra.Command) {
 }
 
 func preparseProfileFlag(args []string) string {
+	profile, _, valid := preparseProfileSelection(args)
+	if !valid {
+		return ""
+	}
+	return profile
+}
+
+func preparseProfileSelection(args []string) (profile string, specified, valid bool) {
 	args, _ = normalizeProfileFlagArgs(args)
+	valid = true
 	for i := 0; i < len(args); i++ {
 		arg := strings.TrimSpace(args[i])
 		switch {
-		case arg == "--profile" && i+1 < len(args):
-			return strings.TrimSpace(args[i+1])
+		case arg == "--profile":
+			specified = true
+			if i+1 >= len(args) || strings.HasPrefix(strings.TrimSpace(args[i+1]), "-") {
+				profile = ""
+				valid = false
+				continue
+			}
+			profile = strings.TrimSpace(args[i+1])
+			valid = profile != ""
+			i++
 		case strings.HasPrefix(arg, "--profile="):
-			return strings.TrimSpace(strings.TrimPrefix(arg, "--profile="))
+			specified = true
+			profile = strings.TrimSpace(strings.TrimPrefix(arg, "--profile="))
+			valid = profile != ""
 		}
 	}
-	return ""
+	return profile, specified, valid
 }
 
 func normalizeProcessProfileArgs() func() {

internal/app/root_full_coverage_test.go

@@ -37,29 +37,64 @@ func TestCrossPlatformCoverageRootExecuteAllBranchesCoverage(t *testing.T) {
 	rootNormalizeProcessProfileArgs = func() func() { return func() {} }
 	rootRunPreParse = func(*cobra.Command, *pipeline.Engine) error { return nil }
 	rootStopAllStdioClients = func() {}
+	var executedLeaf *cobra.Command
 	rootNewRootCommandWithEngine = func(context.Context, *pipeline.Engine) *cobra.Command {
-		return &cobra.Command{Use: "dws", SilenceErrors: true, SilenceUsage: true}
+		root := &cobra.Command{Use: "dws", SilenceErrors: true, SilenceUsage: true}
+		sheet := &cobra.Command{Use: "sheet"}
+		executedLeaf = &cobra.Command{Use: "read", Run: func(*cobra.Command, []string) {}}
+		sheet.AddCommand(executedLeaf)
+		root.AddCommand(sheet)
+		return root
 	}
-	rootExecuteCommand = func(cmd *cobra.Command) (*cobra.Command, error) { return cmd, nil }
-	if code := Execute(); code != 0 {
-		t.Fatalf("successful Execute code = %d", code)
+	rootExecuteCommand = func(*cobra.Command) (*cobra.Command, error) { return executedLeaf, nil }
+	if code, commandPath, errorMessage := ExecuteWithTelemetry(); code != 0 || commandPath != "sheet read" || errorMessage != "" {
+		t.Fatalf("successful ExecuteWithTelemetry = code %d path %q error %q", code, commandPath, errorMessage)
 	}
 
 	rootRunPreParse = func(*cobra.Command, *pipeline.Engine) error { return errors.New("alias/canonical conflict") }
-	if code := Execute(); code == 0 {
-		t.Fatal("pre-parse conflict returned zero")
+	if code, _, errorMessage := ExecuteWithTelemetry(); code == 0 || errorMessage != "alias/canonical conflict" {
+		t.Fatalf("pre-parse conflict = code %d error %q", code, errorMessage)
 	}
 	rootRunPreParse = func(*cobra.Command, *pipeline.Engine) error { return nil }
 
 	wantErr := errors.New("unknown command missing")
 	rootExecuteCommand = func(*cobra.Command) (*cobra.Command, error) { return nil, wantErr }
-	if code := Execute(); code == 0 {
-		t.Fatal("failed Execute returned zero")
+	if code, _, errorMessage := ExecuteWithTelemetry(); code == 0 || errorMessage != "unknown command" {
+		t.Fatalf("failed ExecuteWithTelemetry = code %d error %q", code, errorMessage)
 	}
 
 	rootExecuteCommand = func(*cobra.Command) (*cobra.Command, error) { panic("boom") }
-	if code := Execute(); code != 5 {
-		t.Fatalf("panic Execute code = %d", code)
+	os.Args = []string{"dws", "sheet", "read"}
+	if code, commandPath, errorMessage := ExecuteWithTelemetry(); code != 5 || commandPath != "sheet read" || errorMessage != "internal panic" {
+		t.Fatalf("panic ExecuteWithTelemetry = code %d path %q error %q", code, commandPath, errorMessage)
+	}
+}
+
+func TestCrossPlatformCoverageTelemetryCommandPath(t *testing.T) {
+	if got := telemetryCommandPath(nil); got != "dws" {
+		t.Fatalf("nil command path = %q, want dws", got)
+	}
+	if got := telemetryCommandPathForArgs(nil, nil); got != "dws" {
+		t.Fatalf("nil root command path = %q, want dws", got)
+	}
+	root := &cobra.Command{Use: "dws"}
+	sheet := &cobra.Command{Use: "sheet"}
+	read := &cobra.Command{Use: "read <range>"}
+	sheet.AddCommand(read)
+	root.AddCommand(sheet)
+	if got := telemetryCommandPath(root); got != "dws" {
+		t.Fatalf("root command path = %q, want dws", got)
+	}
+	if got := telemetryCommandPath(read); got != "sheet read" {
+		t.Fatalf("leaf command path = %q, want sheet read", got)
+	}
+	root.PersistentFlags().String("profile", "", "")
+	read.Aliases = []string{"get"}
+	if got := telemetryCommandPathForArgs(root, []string{"--profile", "corp-a", "sheet", "get", "A1:B2"}); got != "sheet read" {
+		t.Fatalf("pre-execution command path = %q, want sheet read", got)
+	}
+	if got := telemetryCommandPathForArgs(root, []string{"missing"}); got != "dws" {
+		t.Fatalf("unknown pre-execution command path = %q, want dws", got)
 	}
 }
 

internal/app/root_help.go

@@ -2,6 +2,7 @@ package app
 
 import (
 	"fmt"
+	"io"
 	"strings"
 	"text/tabwriter"
 
@@ -13,6 +14,12 @@ import (
 	"github.com/spf13/pflag"
 )
 
+// feedbackFormURL points at the DingTalk Notable form collecting dws CLI
+// user-experience feedback. The source parameter tags submissions that
+// originated from the CLI help output so they can be told apart from
+// responses arriving through other channels.
+const feedbackFormURL = "https://alidocs.dingtalk.com/notable/share/form/v01eLbnj1bw1ELb0laN_dv19yqvsgs3oebp3pcjys_1qX0QQ0?source=dws-cli"
+
 func configureRootHelp(root *cobra.Command) {
 	if root == nil {
 		return
@@ -101,6 +108,29 @@ func renderRootHelp(root *cobra.Command) {
 		_, _ = fmt.Fprintln(w)
 		_, _ = fmt.Fprintln(w, tui.Dim(long))
 	}
+
+	// Keep the feedback entry last: everything above it is operational guidance
+	// an agent acts on, while the survey is addressed to human readers who
+	// scroll to the end.
+	_, _ = fmt.Fprintln(w)
+	renderRootFeedback(w)
+}
+
+// renderRootFeedback prints the user-experience survey entry. The URL occupies
+// its own line and is never wrapped or padded through a tabwriter: it is longer
+// than the help rule width, and breaking it would stop terminals from
+// recognizing it as a clickable hyperlink. Soft wrapping performed by the
+// terminal itself keeps the link intact.
+//
+// The label is intentionally not routed through i18n. Everything surrounding it
+// in this listing — service descriptions, utility descriptions, global flag
+// usage — is hardcoded Chinese, so translating this one line would render it in
+// English on any host whose LANG is not zh_*, leaving a single English line
+// inside an otherwise Chinese screen.
+func renderRootFeedback(w io.Writer) {
+	_, _ = fmt.Fprintln(w, tui.Section("Feedback:"))
+	_, _ = fmt.Fprintf(w, "  %s %s\n", tui.Bullet(), tui.Dim("使用体验反馈问卷（1 分钟）"))
+	_, _ = fmt.Fprintf(w, "    %s\n", tui.Cyan(feedbackFormURL))
 }
 
 func renderRootGlobalFlags(root *cobra.Command) {

internal/app/root_help_test.go

@@ -22,6 +22,7 @@ import (
 	"strings"
 	"testing"
 
+	authpkg "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/auth"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/runtimeannotate"
 	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam"
@@ -52,6 +53,49 @@ func TestRootHelpHidesCompatibilityOnlyCommands(t *testing.T) {
 	}
 }
 
+func TestRootHelpShowsFeedbackEntry(t *testing.T) {
+	cmd := NewRootCommand()
+	var out bytes.Buffer
+	cmd.SetOut(&out)
+	cmd.SetErr(&out)
+	cmd.SetArgs([]string{"--help"})
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("root help: %v\n%s", err, out.String())
+	}
+	help := out.String()
+	// The label stays Chinese regardless of the host locale: the rest of this
+	// listing is hardcoded Chinese, so a translated label would show up as a
+	// lone English line on any host whose LANG is not zh_*.
+	for _, want := range []string{"Feedback:", "使用体验反馈问卷", feedbackFormURL} {
+		if !strings.Contains(help, want) {
+			t.Fatalf("root help missing %q:\n%s", want, help)
+		}
+	}
+	// The form URL is longer than the help rule width; it must stay on a
+	// single unbroken line so terminals keep recognizing it as a hyperlink.
+	if !strings.Contains(help, "\n    "+feedbackFormURL+"\n") {
+		t.Fatalf("feedback URL must occupy one unwrapped line:\n%s", help)
+	}
+}
+
+// The feedback entry is deliberately root-only: this CLI is driven mostly by
+// AI agents, and repeating a survey link in every subcommand help would be
+// pure context noise. Guard the boundary so a future refactor cannot move the
+// rendering into the shared subcommand help path unnoticed.
+func TestSubcommandHelpOmitsFeedbackEntry(t *testing.T) {
+	cmd := NewRootCommand()
+	var out bytes.Buffer
+	cmd.SetOut(&out)
+	cmd.SetErr(&out)
+	cmd.SetArgs([]string{"chat", "--help"})
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("chat help: %v\n%s", err, out.String())
+	}
+	if help := out.String(); strings.Contains(help, feedbackFormURL) {
+		t.Fatalf("subcommand help must not carry the feedback URL:\n%s", help)
+	}
+}
+
 func TestCalendarEventCreateHelpKeepsRoomsStringMetavar(t *testing.T) {
 	cmd := NewRootCommand()
 	var out bytes.Buffer
@@ -93,8 +137,8 @@ func TestRootKeepsMainBranchChatCompatibilityCommands(t *testing.T) {
 	}{
 		{args: []string{"chat", "send", "--group", "cid-stable", "--text", "hello"}, hint: "dws chat message send"},
 		{args: []string{"im", "send", "--group", "cid-stable", "--text", "hello"}, hint: "dws chat message send"},
-		{args: []string{"chat", "history", "--group", "cid-stable", "--limit", "20"}, hint: "dws chat message list --group <GROUP_OPEN_CONVERSATION_ID>"},
-		{args: []string{"im", "history", "--group", "cid-stable", "--limit", "20"}, hint: "dws chat message list --group <GROUP_OPEN_CONVERSATION_ID>"},
+		{args: []string{"chat", "history", "--group", "cid-stable", "--limit", "20"}, hint: "dws chat message list --conversation-id <GROUP_OPEN_CONVERSATION_ID>"},
+		{args: []string{"im", "history", "--group", "cid-stable", "--limit", "20"}, hint: "dws chat message list --conversation-id <GROUP_OPEN_CONVERSATION_ID>"},
 	} {
 		command := NewRootCommand()
 		command.SilenceErrors = true
@@ -488,6 +532,80 @@ func TestInjectStaticServersMergesStaticAndSupplementServers(t *testing.T) {
 	}
 }
 
+func TestCrossPlatformCoverageStaticDingTalkEndpointsFollowConfiguredMCPBaseURL(t *testing.T) {
+	previous := edition.Get()
+	defer edition.Override(previous)
+	defer SetDynamicServers(nil)
+
+	configDir := t.TempDir()
+	t.Setenv("DWS_CONFIG_DIR", configDir)
+	if err := os.WriteFile(filepath.Join(configDir, "mcp_url"), []byte("https://pre-mcp.dingtalk.io\n"), 0o600); err != nil {
+		t.Fatalf("WriteFile(mcp_url) error = %v", err)
+	}
+
+	edition.Override(&edition.Hooks{
+		Name: "test",
+		StaticServers: func() []edition.ServerInfo {
+			return []edition.ServerInfo{{
+				ID:       "contact",
+				Name:     "Contact",
+				Endpoint: "https://mcp-gw.dingtalk.com/server/contact?key=abc",
+				Prefixes: []string{"user"},
+			}}
+		},
+	})
+
+	injectStaticServers()
+
+	for _, productID := range []string{"contact", "user"} {
+		got, ok := directRuntimeEndpoint(productID, "")
+		want := "https://pre-mcp-gw.dingtalk.io/server/contact?key=abc"
+		if !ok || got != want {
+			t.Fatalf("directRuntimeEndpoint(%q) = %q, %v; want %q, true", productID, got, ok, want)
+		}
+	}
+}
+
+func TestCrossPlatformCoverageDingTalkEndpointsFollowSelectedTokenRegion(t *testing.T) {
+	configDir := t.TempDir()
+	t.Setenv("DWS_CONFIG_DIR", configDir)
+	mcpURLPath := filepath.Join(configDir, "mcp_url")
+
+	if err := os.WriteFile(mcpURLPath, []byte("https://pre-mcp.dingtalk.io\n"), 0o600); err != nil {
+		t.Fatalf("WriteFile(mcp_url) error = %v", err)
+	}
+	endpoint := "https://pre-mcp-gw.dingtalk.io/server/contact?key=abc"
+	if got, want := activeDingTalkGatewayEndpointForLoginRegion(endpoint, authpkg.LoginRegionDefault), "https://pre-mcp-gw.dingtalk.com/server/contact?key=abc"; got != want {
+		t.Fatalf("domestic profile endpoint = %q, want %q", got, want)
+	}
+	if got := activeDingTalkGatewayEndpointForLoginRegion(endpoint, authpkg.LoginRegionInternational); got != endpoint {
+		t.Fatalf("international profile endpoint = %q, want %q", got, endpoint)
+	}
+
+	if err := os.WriteFile(mcpURLPath, []byte("https://mcp.dingtalk.com\n"), 0o600); err != nil {
+		t.Fatalf("WriteFile(mcp_url) error = %v", err)
+	}
+	if got, want := activeDingTalkGatewayEndpointForLoginRegion("https://mcp-gw.dingtalk.com/server/contact", authpkg.LoginRegionInternational), "https://mcp-gw.dingtalk.io/server/contact"; got != want {
+		t.Fatalf("international profile endpoint from domestic config = %q, want %q", got, want)
+	}
+}
+
+func TestCrossPlatformCoverageDingTalkEndpointUsesLoginScopedMCPOverride(t *testing.T) {
+	configDir := t.TempDir()
+	t.Setenv("DWS_CONFIG_DIR", configDir)
+	restore := authpkg.PushMCPBaseURLOverride("https://pre-mcp.dingtalk.io")
+	defer restore()
+
+	got := activeDingTalkGatewayEndpointForLoginRegion(
+		"https://mcp-gw.dingtalk.com/server/contact",
+		authpkg.LoginRegionDefault,
+	)
+	want := "https://pre-mcp-gw.dingtalk.io/server/contact"
+	if got != want {
+		t.Fatalf("login-scoped endpoint = %q, want %q", got, want)
+	}
+}
+
 func mustFindCommand(t *testing.T, root *cobra.Command, path ...string) *cobra.Command {
 	t.Helper()
 	cmd := root

internal/app/root_lifecycle_regression_test.go

@@ -181,7 +181,7 @@ func TestPublicRootDirectExecuteClosesSinkOnHandlerError(t *testing.T) {
 	}
 }
 
-func TestExecutePanicAfterEmissionPreservesSingleResultAndExitCode(t *testing.T) {
+func TestCrossPlatformCoverageExecutePanicAfterEmissionPreservesSingleResultAndExitCode(t *testing.T) {
 	oldNormalize := rootNormalizeProcessProfileArgs
 	oldExecute := rootExecuteCommand
 	oldNewRoot := rootNewRootCommandWithEngine

internal/app/root_output_atomic_test.go

@@ -230,13 +230,20 @@ func TestOutputSinkUnifiedPublicationFailureFailsAndLeavesNoFinalFile(t *testing
 	assertNoOutputTemps(t, target)
 }
 
-func TestExecuteUnifiedPublicationFailureEmitsFailureOnOriginalStdout(t *testing.T) {
+func TestCrossPlatformCoverageExecuteUnifiedPublicationFailureEmitsFailureOnOriginalStdout(t *testing.T) {
 	testseam.Protect(t, &os.Args)
 	dir := t.TempDir()
-	target := filepath.Join(dir, "result.json")
+	t.Chdir(dir)
+	// Keep argv portable: an absolute Windows path contains a volume colon,
+	// which the CLI intentionally rejects as unsafe user-supplied output.
+	target := "result.json"
 	if err := os.WriteFile(target, []byte("original"), 0o640); err != nil {
 		t.Fatal(err)
 	}
+	originalInfo, err := os.Stat(target)
+	if err != nil {
+		t.Fatal(err)
+	}
 	os.Args = []string{"dws", "atomic-output-unified-publication", "--output", target, "--format", "json"}
 	testseam.Swap(t, &rootRenameFile, func(string, string) error { return errors.New("rename failed") })
 	testseam.Swap(t, &rootNormalizeProcessProfileArgs, func() func() { return func() {} })
@@ -277,7 +284,7 @@ func TestExecuteUnifiedPublicationFailureEmitsFailureOnOriginalStdout(t *testing
 	if got := bytes.Count(stdout.Bytes(), []byte(`"outcome": "success"`)); got != 0 {
 		t.Fatalf("rolled-back success leaked to stdout: %s", stdout.String())
 	}
-	assertOutputFile(t, target, "original", 0o640)
+	assertOutputFile(t, target, "original", originalInfo.Mode().Perm())
 	assertNoOutputTemps(t, target)
 }
 

internal/app/root_unified_output_test.go

@@ -27,7 +27,7 @@ import (
 	"github.com/spf13/cobra"
 )
 
-func TestExecuteEmitsStoredUnifiedResultAtSingleRootExit(t *testing.T) {
+func TestCrossPlatformCoverageExecuteEmitsStoredUnifiedResultAtSingleRootExit(t *testing.T) {
 	oldNormalize := rootNormalizeProcessProfileArgs
 	oldExecute := rootExecuteCommand
 	oldNewRoot := rootNewRootCommandWithEngine

internal/app/runner.go

@@ -162,7 +162,7 @@ var (
 	runnerResolveMultiProfileSelections = resolveMultiProfileSelections
 	runnerResolveProfile                = authpkg.ResolveProfile
 	runnerGetCachedRuntimeToken         = getCachedRuntimeToken
-	runnerResolveAuthToken              = (*runtimeRunner).resolveAuthToken
+	runnerResolveAuthSnapshot           = (*runtimeRunner).resolveAuthSnapshot
 	runnerPreflightDocDownload          = (*runtimeRunner).preflightDocDownload
 	runnerCallTool                      = (*transport.Client).CallTool
 	runnerStdioEnsureInitialized        = (*transport.StdioClient).EnsureInitialized
@@ -552,11 +552,16 @@ func (r *runtimeRunner) executeInvocation(ctx context.Context, endpoint string,
 	if hasPluginAuth {
 		authToken = pluginAuth.Token
 	} else if !invocation.DryRun && (r.globalFlags == nil || !r.globalFlags.Mock) {
-		var tokenErr error
-		authToken, tokenErr = runnerResolveAuthToken(r, ctx)
+		snapshot, tokenErr := runnerResolveAuthSnapshot(r, ctx)
 		if tokenErr != nil {
 			return executor.Result{}, tokenResolutionError(tokenErr)
 		}
+		authToken = snapshot.AccessToken
+		if !hasDirectRuntimeEndpointOverride(invocation.CanonicalProduct) &&
+			isDingTalkMCPGatewayEndpoint(endpoint) &&
+			(snapshot.LoginRegionKnown || authpkg.MCPBaseURLOverride() != "") {
+			endpoint = activeDingTalkGatewayEndpointForLoginRegion(endpoint, snapshot.LoginRegion)
+		}
 	}
 
 	var timeoutSec int
@@ -877,21 +882,33 @@ func (r *runtimeRunner) executeStdioInvocationAtEndpoint(
 }
 
 func (r *runtimeRunner) resolveAuthToken(ctx context.Context) (string, error) {
-	explicitToken := ""
-	if r != nil && r.globalFlags != nil {
-		explicitToken = r.globalFlags.Token
-	}
-	return resolveRuntimeAuthToken(ctx, explicitToken)
-}
-
-func resolveRuntimeAuthToken(ctx context.Context, explicitToken string) (string, error) {
-	snapshot, err := runtimeTokenManager.Get(ctx, defaultConfigDir(), explicitToken)
+	snapshot, err := r.resolveAuthSnapshot(ctx)
 	if err != nil {
 		return "", err
 	}
 	return snapshot.AccessToken, nil
 }
 
+func (r *runtimeRunner) resolveAuthSnapshot(ctx context.Context) (AccessTokenSnapshot, error) {
+	explicitToken := ""
+	if r != nil && r.globalFlags != nil {
+		explicitToken = r.globalFlags.Token
+	}
+	return resolveRuntimeAuthSnapshot(ctx, explicitToken)
+}
+
+func resolveRuntimeAuthToken(ctx context.Context, explicitToken string) (string, error) {
+	snapshot, err := resolveRuntimeAuthSnapshot(ctx, explicitToken)
+	if err != nil {
+		return "", err
+	}
+	return snapshot.AccessToken, nil
+}
+
+func resolveRuntimeAuthSnapshot(ctx context.Context, explicitToken string) (AccessTokenSnapshot, error) {
+	return runtimeTokenManager.Get(ctx, defaultConfigDir(), explicitToken)
+}
+
 // getCachedRuntimeToken is kept as the prefetch seam used by runner tests. The
 // cache itself lives exclusively in TokenManager.
 func getCachedRuntimeToken(ctx context.Context) (string, error) {

internal/app/runner_full_coverage_test.go

@@ -127,12 +127,14 @@ func TestCrossPlatformCoverageRunnerRemainingRoutingCoverage(t *testing.T) {
 }
 
 func TestCrossPlatformCoverageRunnerRemainingExecutionCoverage(t *testing.T) {
+	t.Setenv("DWS_CONFIG_DIR", t.TempDir())
 	oldEdition := edition.Get()
 	oldPreflight := runnerPreflightDocDownload
 	oldCall := runnerCallTool
 	oldHandle := runnerHandlePatAuthCheck
 	oldRetry := runnerRetryWithPatAuthRetry
 	oldCapture := runnerCaptureRuntimeFailure
+	oldResolveSnapshot := runnerResolveAuthSnapshot
 	t.Cleanup(func() {
 		edition.Override(oldEdition)
 		runnerPreflightDocDownload = oldPreflight
@@ -140,6 +142,7 @@ func TestCrossPlatformCoverageRunnerRemainingExecutionCoverage(t *testing.T) {
 		runnerHandlePatAuthCheck = oldHandle
 		runnerRetryWithPatAuthRetry = oldRetry
 		runnerCaptureRuntimeFailure = oldCapture
+		runnerResolveAuthSnapshot = oldResolveSnapshot
 	})
 
 	pluginAuthMu.Lock()
@@ -168,6 +171,27 @@ func TestCrossPlatformCoverageRunnerRemainingExecutionCoverage(t *testing.T) {
 	if got, err := r.executeInvocation(context.Background(), "https://example.test", inv); err != nil || !got.Invocation.Implemented {
 		t.Fatalf("default auth execution = %#v, %v", got, err)
 	}
+	runnerResolveAuthSnapshot = func(*runtimeRunner, context.Context) (AccessTokenSnapshot, error) {
+		return AccessTokenSnapshot{
+			AccessToken:      "international-token",
+			LoginRegion:      authpkg.LoginRegionInternational,
+			LoginRegionKnown: true,
+		}, nil
+	}
+	successfulCall := runnerCallTool
+	routedEndpoint := ""
+	runnerCallTool = func(_ *transport.Client, _ context.Context, endpoint, _ string, _ map[string]any) (transport.ToolCallResult, error) {
+		routedEndpoint = endpoint
+		return transport.ToolCallResult{Content: map[string]any{"value": 1}}, nil
+	}
+	if _, err := r.executeInvocation(context.Background(), "https://mcp-gw.dingtalk.com/server/contact", inv); err != nil {
+		t.Fatalf("international auth execution = %v", err)
+	}
+	if routedEndpoint != "https://mcp-gw.dingtalk.io/server/contact" {
+		t.Fatalf("international routed endpoint = %q", routedEndpoint)
+	}
+	runnerResolveAuthSnapshot = oldResolveSnapshot
+	runnerCallTool = successfulCall
 
 	wantErr := errors.New("preflight")
 	runnerPreflightDocDownload = func(*runtimeRunner, context.Context, *transport.Client, string, executor.Invocation) error {
@@ -362,6 +386,12 @@ func TestCrossPlatformCoverageRunnerRemainingStdioAuthAndHeadersCoverage(t *test
 	if got, err := resolveRuntimeAuthToken(context.Background(), " runtime "); err != nil || got != "runtime" {
 		t.Fatalf("runtime explicit token = %q, %v", got, err)
 	}
+	edition.Override(&edition.Hooks{TokenProvider: func(context.Context, func() (string, error)) (string, error) {
+		return "", errors.New("snapshot failed")
+	}})
+	if _, err := r.resolveAuthToken(context.Background()); err == nil || !strings.Contains(err.Error(), "snapshot failed") {
+		t.Fatalf("resolveAuthToken error = %v", err)
+	}
 
 	t.Setenv(envDWSChannel, "channel")
 	edition.Override(&edition.Hooks{

internal/app/schema_shortcut_contract_test.go

@@ -16,12 +16,12 @@ import (
 )
 
 const (
-	publicShortcutCount = 399
+	publicShortcutCount = 418
 	// schemaPublishedShortcutCount counts every delivered *.shortcut_* tool,
 	// including the hidden historical minutes.shortcut_minutes_search contract.
-	schemaPublishedShortcutCount = 401
+	schemaPublishedShortcutCount = 420
 	// publiclyDeliveredShortcutCount is the public-catalog subset of that surface.
-	publiclyDeliveredShortcutCount = 399
+	publiclyDeliveredShortcutCount = 418
 )
 
 func TestDeliverySchemaCoversOrExactlyExcludesEveryPublicShortcutContract(t *testing.T) {
@@ -140,6 +140,78 @@ func TestDeliveryShortcutProgressiveQueriesReturnCompleteContracts(t *testing.T)
 	assertChatCatalogCompleteLeafContracts(t)
 }
 
+func TestDeliveryWikiSpaceSearchDeclaresCompatibilityAdapter(t *testing.T) {
+	leaf := executeShortcutSchemaQuery(t, "--cli-path", "wiki +space-search")
+	if got := schemaContractString(leaf["interface_mode"]); got != "composite" {
+		t.Fatalf("wiki +space-search interface_mode = %q, want composite", got)
+	}
+	reason := schemaContractString(leaf["interface_reason"])
+	for _, fragment := range []string{"query/limit", "search_wikiSpaces.keyword/pageSize", "versioned Schema migration"} {
+		if !strings.Contains(reason, fragment) {
+			t.Fatalf("wiki +space-search interface_reason = %q, want fragment %q", reason, fragment)
+		}
+	}
+	parameters := schemaContractMap(leaf["parameters"])
+	for name, want := range map[string]string{"query": "query", "limit": "limit"} {
+		parameter := parameters[name]
+		if parameter == nil {
+			t.Fatalf("wiki +space-search missing --%s parameter: %#v", name, parameters)
+		}
+		if got := schemaContractString(parameter["property"]); got != want {
+			t.Fatalf("wiki +space-search --%s property = %q, want compatibility value %q", name, got, want)
+		}
+	}
+}
+
+func TestAllShortcutsWikiSchemaExamplesIncludeRequiredParameters(t *testing.T) {
+	tools := deliverySchemaAllToolsForHelpFlagTest(t, NewRootCommand())
+	checked := 0
+	for _, declared := range shortcut.All() {
+		if declared.Service != "wiki" || declared.UserDefined || !shortcut.InPublicCatalog(declared.Service, declared.Command) {
+			continue
+		}
+		checked++
+		canonical := shortcutSchemaCanonical(declared)
+		tool := tools[canonical]
+		if tool == nil {
+			t.Fatalf("delivery schema --all is missing %s", canonical)
+		}
+		examples := schemaContractStringSlice(tool["examples"])
+		if len(examples) == 0 {
+			t.Fatalf("%s has no delivered examples", canonical)
+		}
+		for _, example := range examples {
+			argv, err := cli.ParseAgentExampleArgv(example)
+			if err != nil {
+				t.Fatalf("%s example %q is not valid argv: %v", canonical, example, err)
+			}
+			for _, flag := range declared.Flags {
+				if !flag.Required {
+					continue
+				}
+				names := append([]string{flag.Name}, flag.Aliases...)
+				if !schemaExampleHasLongFlag(argv, names...) {
+					t.Errorf("%s example %q is missing required --%s", canonical, example, flag.Name)
+				}
+			}
+		}
+	}
+	if checked != 20 {
+		t.Fatalf("checked Wiki shortcut examples = %d, want 20", checked)
+	}
+}
+
+func schemaExampleHasLongFlag(argv []string, names ...string) bool {
+	for _, argument := range argv {
+		for _, name := range names {
+			if argument == "--"+name || strings.HasPrefix(argument, "--"+name+"=") {
+				return true
+			}
+		}
+	}
+	return false
+}
+
 func assertSchemaSummarySafety(
 	t testing.TB,
 	summaries map[string]map[string]any,
@@ -207,7 +279,11 @@ func assertChatCatalogCompleteLeafContracts(t testing.TB) {
 	})
 
 	auditJoin := executeShortcutSchemaQuery(t, "--cli-path", "chat group audit-join-validation")
+	assertSchemaLeafParameterRequired(t, auditJoin, "chat group audit-join-validation", "conversation-id", true)
 	assertSchemaLeafParameterEnum(t, auditJoin, "chat group audit-join-validation", "status", []string{"AuditApprove", "AuditDelete"})
+	if parameters := schemaContractMap(auditJoin["parameters"]); parameters["group"] != nil {
+		t.Fatalf("chat group audit-join-validation publishes hidden --group alias: %#v", parameters["group"])
+	}
 }
 
 func assertSchemaLeafParameterRequired(t testing.TB, leaf map[string]any, cliPath, name string, want bool) {

internal/app/signal_test.go

@@ -103,7 +103,7 @@ func installSignalExecuteSeams(t *testing.T, unified bool, stdout, stderr io.Wri
 	})
 }
 
-func TestExecuteSignalEmitsOneTypedUnifiedFailure(t *testing.T) {
+func TestCrossPlatformCoverageExecuteSignalEmitsOneTypedUnifiedFailure(t *testing.T) {
 	for _, tc := range []struct {
 		name    string
 		signal  syscall.Signal
@@ -197,7 +197,7 @@ func TestSignalAfterFailedEmissionAttemptPreservesPublicationExitCode(t *testing
 	}
 }
 
-func TestSignalBeforeEmissionAttemptPreservesPublishedOutcome(t *testing.T) {
+func TestCrossPlatformCoverageSignalBeforeEmissionAttemptPreservesPublishedOutcome(t *testing.T) {
 	var stdout bytes.Buffer
 	installSignalExecuteSeams(t, true, &stdout, io.Discard)
 	testseam.Swap(t, &rootExecuteCommand, func(cmd *cobra.Command) (*cobra.Command, error) {
@@ -229,7 +229,7 @@ func TestSignalBeforeEmissionAttemptPreservesPublishedOutcome(t *testing.T) {
 	}
 }
 
-func TestSignalAfterCompletedPrimaryPreservesEstablishedOutcome(t *testing.T) {
+func TestCrossPlatformCoverageSignalAfterCompletedPrimaryPreservesEstablishedOutcome(t *testing.T) {
 	var stdout bytes.Buffer
 	installSignalExecuteSeams(t, true, &stdout, io.Discard)
 	testseam.Swap(t, &rootExecuteCommand, func(cmd *cobra.Command) (*cobra.Command, error) {

internal/app/telemetry_error.go

@@ -0,0 +1,143 @@
+// 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 app
+
+import (
+	stderrors "errors"
+	"fmt"
+	"regexp"
+	"strings"
+	"unicode"
+
+	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/output"
+)
+
+const maxTelemetryErrorRunes = 200
+
+var (
+	telemetryUnknownFlagPattern  = regexp.MustCompile(`(?i)unknown flag:\s*(--[a-z0-9][a-z0-9-]*)`)
+	telemetryAuthPattern         = regexp.MustCompile(`(?i)\b(?:bearer|basic)\s+[a-z0-9._~+/=-]+`)
+	telemetrySensitiveFlag       = regexp.MustCompile(`(?i)(--(?:access-token|refresh-token|token|client-secret|client-id|password|api-key|authorization|cookie|credential|secret))(?:=|\s+)\S+`)
+	telemetrySensitiveValue      = regexp.MustCompile(`(?i)\b(authorization|client[-_]?secret|client[-_]?id|access[-_]?token|refresh[-_]?token|api[-_]?key|password|cookie|credential|secret|token)\b\s*[:=]\s*[^\s,;]+`)
+	telemetryURLPattern          = regexp.MustCompile(`(?i)\b(?:https?|wss?)://[^\s]+`)
+	telemetryJSONPattern         = regexp.MustCompile(`(?s)[\[{].*[\]}]`)
+	telemetryUnixPathPattern     = regexp.MustCompile(`(^|[\s=:])(?:~/|/)[^\s]+`)
+	telemetryWindowsPathPattern  = regexp.MustCompile(`(?i)(^|[\s=])[a-z]:[\\/][^\s]+`)
+	telemetryRelativePathPattern = regexp.MustCompile(`(^|[\s=:])\.\.?/[^\s]+`)
+	telemetryEmailPattern        = regexp.MustCompile(`(?i)\b[a-z0-9._%+-]+@[a-z0-9.-]+\.[a-z]{2,}\b`)
+	telemetryPhonePattern        = regexp.MustCompile(`\b\+?\d[\d -]{7,}\d\b`)
+	telemetryOpaqueTokenPattern  = regexp.MustCompile(`\b[a-zA-Z0-9_-]{16,}\b`)
+)
+
+func telemetryErrorSummary(err error) string {
+	if err == nil {
+		return ""
+	}
+	var patError *apperrors.PATError
+	if stderrors.As(err, &patError) {
+		return "permission error"
+	}
+	var rawError apperrors.RawStderrError
+	if stderrors.As(err, &rawError) {
+		return "raw stderr error"
+	}
+	if isUnknownCommandError(err) {
+		return "unknown command"
+	}
+	if match := telemetryUnknownFlagPattern.FindStringSubmatch(err.Error()); len(match) == 2 {
+		return "unknown flag: " + match[1]
+	}
+	return sanitizeTelemetryErrorText(err.Error())
+}
+
+func telemetryPanicMessages(value any) (display, summary string) {
+	return fmt.Sprintf("internal panic: %v", value), "internal panic"
+}
+
+func sanitizeTelemetryErrorText(message string) string {
+	message = output.SanitizeForTerminal(message)
+	message = telemetryAuthPattern.ReplaceAllString(message, "<credential>")
+	message = telemetrySensitiveFlag.ReplaceAllString(message, "$1=<redacted>")
+	message = telemetrySensitiveValue.ReplaceAllString(message, "$1=<redacted>")
+	message = telemetryURLPattern.ReplaceAllString(message, "<url>")
+	message = telemetryJSONPattern.ReplaceAllString(message, "<payload>")
+	message = redactTelemetryQuotedText(message)
+	message = telemetryUnixPathPattern.ReplaceAllString(message, "$1<path>")
+	message = telemetryWindowsPathPattern.ReplaceAllString(message, "$1<path>")
+	message = telemetryRelativePathPattern.ReplaceAllString(message, "$1<path>")
+	message = telemetryEmailPattern.ReplaceAllString(message, "<email>")
+	message = telemetryPhonePattern.ReplaceAllString(message, "<phone>")
+	message = telemetryOpaqueTokenPattern.ReplaceAllStringFunc(message, func(value string) string {
+		var hasLetter, hasDigit bool
+		for _, r := range value {
+			hasLetter = hasLetter || unicode.IsLetter(r)
+			hasDigit = hasDigit || unicode.IsDigit(r)
+		}
+		if hasLetter && hasDigit {
+			return "<id>"
+		}
+		return value
+	})
+	message = strings.Join(strings.Fields(message), " ")
+	return truncateTelemetryText(message, maxTelemetryErrorRunes)
+}
+
+func redactTelemetryQuotedText(message string) string {
+	var result strings.Builder
+	runes := []rune(message)
+	for index := 0; index < len(runes); {
+		quote := runes[index]
+		if quote != '\'' && quote != '"' && quote != '`' {
+			result.WriteRune(quote)
+			index++
+			continue
+		}
+		result.WriteRune(quote)
+		result.WriteString("<redacted>")
+		index++
+		escaped := false
+		for index < len(runes) {
+			current := runes[index]
+			index++
+			if escaped {
+				escaped = false
+				continue
+			}
+			if current == '\\' && quote != '`' {
+				escaped = true
+				continue
+			}
+			if current == quote {
+				result.WriteRune(quote)
+				break
+			}
+		}
+	}
+	return result.String()
+}
+
+func truncateTelemetryText(message string, maxRunes int) string {
+	if maxRunes <= 0 {
+		return ""
+	}
+	runes := []rune(message)
+	if len(runes) <= maxRunes {
+		return message
+	}
+	if maxRunes <= 3 {
+		return string(runes[:maxRunes])
+	}
+	return string(runes[:maxRunes-3]) + "..."
+}

internal/app/telemetry_error_test.go

@@ -0,0 +1,99 @@
+// 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 app
+
+import (
+	"errors"
+	"strings"
+	"testing"
+
+	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
+)
+
+type telemetryRawError string
+
+func (e telemetryRawError) Error() string     { return string(e) }
+func (e telemetryRawError) RawStderr() string { return string(e) }
+
+func TestCrossPlatformCoverageTelemetryErrorSummaryFixedFamilies(t *testing.T) {
+	for _, tc := range []struct {
+		name string
+		err  error
+		want string
+	}{
+		{name: "nil", want: ""},
+		{name: "PAT", err: &apperrors.PATError{RawJSON: `{"token":"secret"}`}, want: "permission error"},
+		{name: "raw stderr", err: telemetryRawError("raw secret"), want: "raw stderr error"},
+		{name: "unknown command", err: errors.New(`unknown command "secret-value" for "dws"`), want: "unknown command"},
+		{name: "unknown flag", err: errors.New("unknown flag: --token=secret-value"), want: "unknown flag: --token"},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			if got := telemetryErrorSummary(tc.err); got != tc.want {
+				t.Fatalf("telemetryErrorSummary() = %q, want %q", got, tc.want)
+			}
+		})
+	}
+}
+
+func TestCrossPlatformCoverageSanitizeTelemetryErrorText(t *testing.T) {
+	message := "\x1b[31mfailed\x1b[0m " +
+		"--client-secret very-secret " +
+		"--access-token access-secret " +
+		"Authorization: Bearer abcdefghijklmnop1234 " +
+		"url=https://example.test/path?token=secret " +
+		`body={"access_token":"secret"} ` +
+		`user="Alice" email=alice@example.test phone=13800138000 ` +
+		"path=/Users/alice/private.txt relative=./private/secrets.txt id=abcDEF1234567890XYZ"
+	got := sanitizeTelemetryErrorText(message)
+	for _, secret := range []string{
+		"very-secret", "access-secret", "abcdefghijklmnop1234", "example.test", "access_token",
+		"Alice", "alice@example.test", "13800138000", "/Users/alice", "abcDEF1234567890XYZ", "\x1b",
+		"./private/secrets.txt",
+	} {
+		if strings.Contains(got, secret) {
+			t.Fatalf("sanitized telemetry error leaked %q: %q", secret, got)
+		}
+	}
+	for _, marker := range []string{"failed", "<redacted>", "<url>", "<payload>", "<path>", "<id>"} {
+		if !strings.Contains(got, marker) {
+			t.Fatalf("sanitized telemetry error missing %q: %q", marker, got)
+		}
+	}
+}
+
+func TestCrossPlatformCoverageTelemetryErrorTruncationAndPanic(t *testing.T) {
+	message := strings.Repeat("错", maxTelemetryErrorRunes+1)
+	got := sanitizeTelemetryErrorText(message)
+	if len([]rune(got)) != maxTelemetryErrorRunes || !strings.HasSuffix(got, "...") {
+		t.Fatalf("truncated telemetry error rune length = %d suffix = %q", len([]rune(got)), got[len(got)-3:])
+	}
+	display, summary := telemetryPanicMessages("token-secret")
+	if display != "internal panic: token-secret" || summary != "internal panic" || strings.Contains(summary, "token-secret") {
+		t.Fatalf("panic messages = display %q summary %q", display, summary)
+	}
+	if got := truncateTelemetryText("value", 0); got != "" {
+		t.Fatalf("zero-limit truncation = %q", got)
+	}
+	if got := truncateTelemetryText("value", 3); got != "val" {
+		t.Fatalf("short-limit truncation = %q", got)
+	}
+}
+
+func TestCrossPlatformCoverageTelemetryErrorEscapesAndOpaqueWords(t *testing.T) {
+	const opaqueWord = "abcdefghijklmnop"
+	got := sanitizeTelemetryErrorText(`failed "quoted \"value" ` + opaqueWord)
+	if strings.Contains(got, "value") || !strings.Contains(got, opaqueWord) {
+		t.Fatalf("escaped quote sanitization = %q", got)
+	}
+}

internal/app/telemetry_identity.go

@@ -0,0 +1,86 @@
+// 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 app
+
+import (
+	"fmt"
+	"strings"
+
+	authpkg "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/auth"
+)
+
+// TelemetryIdentity is the privacy-reviewed subset of the local authentication
+// record that may be attached to a CLI execution event.
+type TelemetryIdentity struct {
+	UserID   string
+	UserName string
+	CorpID   string
+}
+
+var telemetryResolveProfileMetadata = authpkg.ResolveProfileMetadataReadOnly
+
+// ResolveTelemetryIdentity returns a pre-execution snapshot of the identity
+// selected by args. Multi-profile executions are attributed to the current
+// default profile. Resolution is deliberately best-effort: telemetry must not
+// refresh credentials or change command behavior when local auth data is
+// missing, invalid, or unreadable.
+func ResolveTelemetryIdentity(args []string) (identity TelemetryIdentity) {
+	defer func() {
+		if recover() != nil {
+			identity = TelemetryIdentity{}
+		}
+	}()
+
+	selector, specified, valid := preparseProfileSelection(args)
+	if specified && !valid {
+		return TelemetryIdentity{}
+	}
+	profile, err := resolveTelemetryProfileMetadata(defaultConfigDir(), selector)
+	if err != nil || profile == nil {
+		return TelemetryIdentity{}
+	}
+	return TelemetryIdentity{
+		UserID:   strings.TrimSpace(profile.UserID),
+		UserName: strings.TrimSpace(profile.UserName),
+		CorpID:   strings.TrimSpace(profile.CorpID),
+	}
+}
+
+func resolveTelemetryProfileMetadata(configDir, selector string) (*authpkg.ProfileMetadata, error) {
+	selector = strings.TrimSpace(selector)
+	if selector == "" || !strings.Contains(selector, ",") {
+		return telemetryResolveProfileMetadata(configDir, selector)
+	}
+
+	// A local profile name may itself contain a comma. Match the runtime
+	// resolver by trying the full selector before interpreting it as CSV.
+	if profile, err := telemetryResolveProfileMetadata(configDir, selector); err == nil && profile != nil {
+		return profile, nil
+	}
+
+	for _, part := range strings.Split(selector, ",") {
+		part = strings.TrimSpace(part)
+		if part == "" {
+			return nil, fmt.Errorf("--profile contains an empty profile selector: %q", selector)
+		}
+		profile, err := telemetryResolveProfileMetadata(configDir, part)
+		if err != nil {
+			return nil, err
+		}
+		if profile == nil {
+			return nil, fmt.Errorf("profile %q not found", part)
+		}
+	}
+	return telemetryResolveProfileMetadata(configDir, "")
+}

internal/app/telemetry_identity_test.go

@@ -0,0 +1,147 @@
+// 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 app
+
+import (
+	"errors"
+	"reflect"
+	"strings"
+	"testing"
+
+	authpkg "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/auth"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam"
+)
+
+func TestCrossPlatformCoverageResolveTelemetryIdentityProfileSelection(t *testing.T) {
+	t.Setenv("DWS_CONFIG_DIR", "/telemetry-config")
+	profiles := map[string]*authpkg.ProfileMetadata{
+		"":           {UserID: " default-user ", UserName: " Default User ", CorpID: " default-corp "},
+		"corp-a":     {UserID: "user-a", UserName: "Alice", CorpID: "corp-a"},
+		"corp-b":     {UserID: "user-b", UserName: "Bob", CorpID: "corp-b"},
+		"alpha,beta": {UserID: "comma-user", UserName: "Comma User", CorpID: "comma-corp"},
+	}
+
+	for _, tc := range []struct {
+		name      string
+		args      []string
+		profiles  map[string]*authpkg.ProfileMetadata
+		wantCalls []string
+		want      TelemetryIdentity
+	}{
+		{name: "default profile", args: []string{"version"}, profiles: profiles, wantCalls: []string{""}, want: TelemetryIdentity{UserID: "default-user", UserName: "Default User", CorpID: "default-corp"}},
+		{name: "single profile", args: []string{"--profile", "corp-a", "version"}, profiles: profiles, wantCalls: []string{"corp-a"}, want: TelemetryIdentity{UserID: "user-a", UserName: "Alice", CorpID: "corp-a"}},
+		{name: "equals form after command", args: []string{"version", "--profile=corp-b"}, profiles: profiles, wantCalls: []string{"corp-b"}, want: TelemetryIdentity{UserID: "user-b", UserName: "Bob", CorpID: "corp-b"}},
+		{name: "last repeated profile", args: []string{"--profile", "corp-a", "version", "--profile=corp-b"}, profiles: profiles, wantCalls: []string{"corp-b"}, want: TelemetryIdentity{UserID: "user-b", UserName: "Bob", CorpID: "corp-b"}},
+		{name: "comma profile name", args: []string{"--profile", "alpha,beta", "version"}, profiles: profiles, wantCalls: []string{"alpha,beta"}, want: TelemetryIdentity{UserID: "comma-user", UserName: "Comma User", CorpID: "comma-corp"}},
+		{name: "multi profile uses default", args: []string{"--profile", "corp-a,corp-b", "version"}, profiles: profiles, wantCalls: []string{"corp-a,corp-b", "corp-a", "corp-b", ""}, want: TelemetryIdentity{UserID: "default-user", UserName: "Default User", CorpID: "default-corp"}},
+		{name: "unquoted multi profile", args: []string{"--profile", "corp-a,", "corp-b", "version"}, profiles: profiles, wantCalls: []string{"corp-a,corp-b", "corp-a", "corp-b", ""}, want: TelemetryIdentity{UserID: "default-user", UserName: "Default User", CorpID: "default-corp"}},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			var calls []string
+			testseam.Swap(t, &telemetryResolveProfileMetadata, func(configDir, selector string) (*authpkg.ProfileMetadata, error) {
+				if configDir != "/telemetry-config" {
+					t.Fatalf("resolver config dir = %q", configDir)
+				}
+				calls = append(calls, selector)
+				profile := tc.profiles[selector]
+				if profile == nil {
+					return nil, errors.New("profile not found")
+				}
+				clone := *profile
+				return &clone, nil
+			})
+
+			if got := ResolveTelemetryIdentity(tc.args); got != tc.want {
+				t.Fatalf("ResolveTelemetryIdentity() = %#v, want %#v", got, tc.want)
+			}
+			if !reflect.DeepEqual(calls, tc.wantCalls) {
+				t.Fatalf("metadata selectors = %#v, want %#v", calls, tc.wantCalls)
+			}
+		})
+	}
+}
+
+func TestCrossPlatformCoverageResolveTelemetryIdentityRejectsMissingProfileValue(t *testing.T) {
+	for _, args := range [][]string{
+		{"version", "--profile"},
+		{"--profile=corp-a", "version", "--profile="},
+		{"--profile", "--debug", "version"},
+	} {
+		t.Run(strings.Join(args, "_"), func(t *testing.T) {
+			testseam.Swap(t, &telemetryResolveProfileMetadata, func(string, string) (*authpkg.ProfileMetadata, error) {
+				t.Fatal("invalid profile syntax attempted metadata resolution")
+				return nil, nil
+			})
+			if got := ResolveTelemetryIdentity(args); got != (TelemetryIdentity{}) {
+				t.Fatalf("invalid profile identity = %#v", got)
+			}
+		})
+	}
+}
+
+func TestCrossPlatformCoverageResolveTelemetryIdentityFailsClosed(t *testing.T) {
+	t.Setenv("DWS_CONFIG_DIR", "/telemetry-config")
+	fail := errors.New("metadata unavailable")
+
+	for _, tc := range []struct {
+		name    string
+		resolve func(string, string) (*authpkg.ProfileMetadata, error)
+	}{
+		{name: "read error", resolve: func(string, string) (*authpkg.ProfileMetadata, error) { return nil, fail }},
+		{name: "missing profile", resolve: func(string, string) (*authpkg.ProfileMetadata, error) { return nil, nil }},
+		{name: "empty fields", resolve: func(string, string) (*authpkg.ProfileMetadata, error) { return &authpkg.ProfileMetadata{}, nil }},
+		{name: "resolver panic", resolve: func(string, string) (*authpkg.ProfileMetadata, error) { panic("metadata failure") }},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			testseam.Swap(t, &telemetryResolveProfileMetadata, tc.resolve)
+			if got := ResolveTelemetryIdentity(nil); got != (TelemetryIdentity{}) {
+				t.Fatalf("failed-closed identity = %#v", got)
+			}
+		})
+	}
+}
+
+func TestCrossPlatformCoverageResolveTelemetryIdentityRejectsInvalidMultiProfile(t *testing.T) {
+	t.Setenv("DWS_CONFIG_DIR", "/telemetry-config")
+	testseam.Swap(t, &telemetryResolveProfileMetadata, func(_ string, selector string) (*authpkg.ProfileMetadata, error) {
+		if selector == "corp-a" {
+			return &authpkg.ProfileMetadata{UserID: "user-a", CorpID: "corp-a"}, nil
+		}
+		return nil, errors.New("profile not found")
+	})
+	if got := ResolveTelemetryIdentity([]string{"--profile", "corp-a,missing", "version"}); got != (TelemetryIdentity{}) {
+		t.Fatalf("invalid multi-profile identity = %#v", got)
+	}
+}
+
+func TestCrossPlatformCoverageResolveTelemetryProfileMetadataRejectsMalformedMulti(t *testing.T) {
+	testseam.Swap(t, &telemetryResolveProfileMetadata, func(_ string, selector string) (*authpkg.ProfileMetadata, error) {
+		switch selector {
+		case "corp-a,,corp-b":
+			return nil, errors.New("not a literal profile")
+		case "corp-a":
+			return &authpkg.ProfileMetadata{UserID: "user-a"}, nil
+		case "missing":
+			return nil, nil
+		default:
+			return nil, errors.New("unexpected selector")
+		}
+	})
+	if _, err := resolveTelemetryProfileMetadata("/config", "corp-a,,corp-b"); err == nil || !strings.Contains(err.Error(), "empty profile selector") {
+		t.Fatalf("empty multi-profile selector error = %v", err)
+	}
+	if _, err := resolveTelemetryProfileMetadata("/config", "corp-a,missing"); err == nil || !strings.Contains(err.Error(), "not found") {
+		t.Fatalf("missing multi-profile selector error = %v", err)
+	}
+}

internal/auth/auth_extra_test.go

@@ -424,6 +424,87 @@ func TestBuildAuthURLIncludesTargetCorpID(t *testing.T) {
 	}
 }
 
+func TestCrossPlatformCoverageBuildAuthURLForInternationalRegion(t *testing.T) {
+	authURL := buildAuthURLForRegion("client-id", "http://127.0.0.1:1234/callback", "", LoginRegionInternational)
+	if !strings.HasPrefix(authURL, InternationalAuthorizeURL+"?") {
+		t.Fatalf("auth URL = %s, want international authorize host", authURL)
+	}
+}
+
+func TestCrossPlatformCoverageNotEnabledHTMLUsesRegionAwareAuthorizeURL(t *testing.T) {
+	if !strings.Contains(notEnabledHTML, "status.authorizeUrl") {
+		t.Fatal("not-enabled page must read the authorize URL from the regional login status")
+	}
+	if strings.Contains(notEnabledHTML, `"https://login.dingtalk.com/oauth2/auth?client_id="`) {
+		t.Fatal("not-enabled page must not hard-code the domestic authorize URL")
+	}
+}
+
+func TestCrossPlatformCoverageLoginRegionEndpointDefaults(t *testing.T) {
+	if got := AuthorizeURLForLoginRegion(LoginRegionDefault); got != AuthorizeURL {
+		t.Fatalf("default authorize URL = %q, want %q", got, AuthorizeURL)
+	}
+	if got := DeviceBaseURLForLoginRegion(LoginRegionDefault); got != DefaultDeviceBaseURL {
+		t.Fatalf("default device base URL = %q, want %q", got, DefaultDeviceBaseURL)
+	}
+	if got := UserAccessTokenURLForLoginRegion(LoginRegionInternational); got != InternationalUserAccessTokenURL {
+		t.Fatalf("international user access token URL = %q, want %q", got, InternationalUserAccessTokenURL)
+	}
+	if got := MCPBaseURLForLoginRegion(LoginRegionInternational); got != InternationalMCPBaseURL {
+		t.Fatalf("international MCP base URL = %q, want %q", got, InternationalMCPBaseURL)
+	}
+	if got := DeviceBaseURLForLoginRegion(LoginRegionInternational); got != InternationalDeviceBaseURL {
+		t.Fatalf("international device base URL = %q, want %q", got, InternationalDeviceBaseURL)
+	}
+}
+
+func TestCrossPlatformCoverageOAuthProviderLoginRegionHelpers(t *testing.T) {
+	var nilProvider *OAuthProvider
+	if got := nilProvider.loginRegion(); got != LoginRegionDefault {
+		t.Fatalf("nil provider login region = %q", got)
+	}
+	nilProvider.useTokenLoginRegion(&TokenData{LoginRegion: string(LoginRegionInternational)})
+	nilProvider.applyLoginRegionToToken(&TokenData{})
+
+	provider := &OAuthProvider{}
+	provider.useTokenLoginRegion(nil)
+	provider.useTokenLoginRegion(&TokenData{LoginRegion: string(LoginRegionInternational)})
+	if provider.LoginRegion != LoginRegionInternational {
+		t.Fatalf("provider login region = %q, want international", provider.LoginRegion)
+	}
+	provider.useTokenLoginRegion(&TokenData{LoginRegion: string(LoginRegionDefault)})
+	provider.applyLoginRegionToToken(nil)
+	token := &TokenData{}
+	provider.applyLoginRegionToToken(token)
+	if token.LoginRegion != string(LoginRegionInternational) {
+		t.Fatalf("token login region = %q, want international", token.LoginRegion)
+	}
+}
+
+func TestCrossPlatformCoverageMCPBaseURLOverrideAffectsInternationalRegion(t *testing.T) {
+	restore := PushMCPBaseURLOverride("https://pre-mcp.dingtalk.io/")
+	defer restore()
+
+	if got := MCPBaseURLForLoginRegion(LoginRegionInternational); got != "https://pre-mcp.dingtalk.io" {
+		t.Fatalf("international MCP base URL = %q, want override", got)
+	}
+}
+
+func TestCrossPlatformCoverageLoginBaseURLOverrideAffectsInternationalRegion(t *testing.T) {
+	restore := PushLoginBaseURLOverride("https://pre-login.dingtalk.io/")
+	defer restore()
+
+	if got := DeviceBaseURLForLoginRegion(LoginRegionInternational); got != "https://pre-login.dingtalk.io" {
+		t.Fatalf("international device base URL = %q, want override", got)
+	}
+	if got := AuthorizeURLForLoginRegion(LoginRegionInternational); got != "https://pre-login.dingtalk.io/oauth2/auth" {
+		t.Fatalf("international authorize URL = %q, want override", got)
+	}
+	if got := UserAccessTokenURLForLoginRegion(LoginRegionInternational); got != "https://pre-login.dingtalk.io/v1.0/oauth2/userAccessToken" {
+		t.Fatalf("international user access token URL = %q, want override", got)
+	}
+}
+
 func buildTokenDataFromResponse(resp tokenResponse) *TokenData {
 	if resp.AccessToken == "" {
 		return nil

internal/auth/cli_auth_check_test.go

@@ -14,10 +14,12 @@
 package auth
 
 import (
+	"bytes"
 	"context"
 	"encoding/json"
 	"fmt"
 	"io"
+	"log/slog"
 	"net/http"
 	"net/http/httptest"
 	"os"
@@ -206,6 +208,105 @@ func TestCheckCLIAuthEnabled_Enabled(t *testing.T) {
 	t.Logf("✅ Normal enabled response: success=%v, enabled=%v", status.Success, status.Result.CLIAuthEnabled)
 }
 
+func TestCrossPlatformCoverageCheckCLIAuthEnabledTraceHeadersAndDebugLog(t *testing.T) {
+	t.Setenv("DINGTALK_TRACE_ID", "trace-for-cli-auth-test")
+	applyCLIAuthTraceHeaders(nil, "trace-for-cli-auth-test")
+	applyCLIAuthTraceHeaders(httptest.NewRequest(http.MethodGet, "https://example.com", nil), "")
+
+	var logBuf bytes.Buffer
+	previousLogger := slog.Default()
+	slog.SetDefault(slog.New(slog.NewTextHandler(&logBuf, &slog.HandlerOptions{Level: slog.LevelDebug})))
+	defer slog.SetDefault(previousLogger)
+
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if got := r.Header.Get("EagleEye-TraceId"); got != "trace-for-cli-auth-test" {
+			t.Errorf("EagleEye-TraceId = %q, want trace-for-cli-auth-test", got)
+		}
+		if got := r.Header.Get("X-Dingtalk-Trace-Id"); got != "trace-for-cli-auth-test" {
+			t.Errorf("X-Dingtalk-Trace-Id = %q, want trace-for-cli-auth-test", got)
+		}
+		w.Header().Set("EagleEye-TraceId", "server-trace-001")
+		w.Header().Set("EagleEye-RpcId", "rpc-001")
+		w.Header().Set("Content-Type", "application/json")
+		json.NewEncoder(w).Encode(CLIAuthStatus{
+			Success: true,
+			Result:  &CLIAuthResult{CLIAuthEnabled: true},
+		})
+	}))
+	defer srv.Close()
+
+	configDir := setupMCPConfigDir(t, srv.URL)
+	p := &OAuthProvider{configDir: configDir, httpClient: srv.Client()}
+
+	status, err := p.CheckCLIAuthEnabled(context.Background(), "sensitive-token")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if status.Result == nil || !status.Result.CLIAuthEnabled {
+		t.Fatal("expected CLIAuthEnabled=true")
+	}
+
+	logs := logBuf.String()
+	for _, want := range []string{
+		"auth.cli_auth_enabled.request",
+		"auth.cli_auth_enabled.response",
+		"trace-for-cli-auth-test",
+		"server-trace-001",
+		"rpc-001",
+	} {
+		if !strings.Contains(logs, want) {
+			t.Fatalf("debug logs missing %q, got: %s", want, logs)
+		}
+	}
+	if strings.Contains(logs, "sensitive-token") {
+		t.Fatalf("debug logs leaked access token: %s", logs)
+	}
+}
+
+func TestCrossPlatformCoverageInternationalLoginRegionRequestWrappers(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		switch r.URL.Path {
+		case ClientIDPath:
+			_ = json.NewEncoder(w).Encode(ClientIDResponse{Success: true, Result: "international-client"})
+		case SuperAdminPath:
+			_ = json.NewEncoder(w).Encode(SuperAdminResponse{Success: true, Result: []SuperAdmin{{StaffID: "admin"}}})
+		case SendCliAuthApplyPath:
+			_ = json.NewEncoder(w).Encode(SendApplyResponse{Success: true, Result: true})
+		default:
+			http.NotFound(w, r)
+		}
+	}))
+	defer server.Close()
+
+	oldClient := oauthHTTPClient
+	oauthHTTPClient = server.Client()
+	restoreBaseURL := PushMCPBaseURLOverride(server.URL)
+	t.Cleanup(func() {
+		restoreBaseURL()
+		oauthHTTPClient = oldClient
+	})
+
+	ctx := context.Background()
+	for name, fetch := range map[string]func() (string, error){
+		"device": func() (string, error) { return deviceFetchClientIDForLoginRegion(ctx, LoginRegionInternational) },
+		"oauth":  func() (string, error) { return oauthFetchClientIDForLoginRegion(ctx, LoginRegionInternational) },
+	} {
+		if got, err := fetch(); err != nil || got != "international-client" {
+			t.Fatalf("%s client ID = %q, %v", name, got, err)
+		}
+	}
+	if got, err := deviceGetAdminsForLoginRegion(ctx, "token", LoginRegionInternational); err != nil || !got.Success {
+		t.Fatalf("device admins = %#v, %v", got, err)
+	}
+	if got, err := oauthGetAdminsForLoginRegion(ctx, "token", LoginRegionInternational); err != nil || !got.Success {
+		t.Fatalf("OAuth admins = %#v, %v", got, err)
+	}
+	if got, err := oauthSendApplyForLoginRegion(ctx, "token", "admin", LoginRegionInternational); err != nil || !got.Success {
+		t.Fatalf("OAuth apply = %#v, %v", got, err)
+	}
+}
+
 func TestCheckCLIAuthEnabled_Disabled(t *testing.T) {
 	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		w.Header().Set("Content-Type", "application/json")

internal/auth/coverage_edges_test.go

@@ -22,6 +22,7 @@ import (
 	"time"
 
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/keychain"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/config"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition"
 )
 
@@ -1211,7 +1212,13 @@ func TestCrossPlatformCoveragePortableAuthBundleCoverageEdges(t *testing.T) {
 		if err := os.Symlink(filepath.Join(keyDir, "dek"), filepath.Join(keyDir, "link")); err != nil {
 			t.Fatal(err)
 		}
-		for name, value := range map[string]string{"app.json": "{}", profilesJSONFile: "{}", "mcp_url": "https://mcp.test", "terminal_url": "https://terminal.test"} {
+		for name, value := range map[string]string{
+			"app.json":                         "{}",
+			profilesJSONFile:                   "{}",
+			"mcp_url":                          "https://mcp.test",
+			config.ManagedMCPURLRegionFileName: "https://mcp.test",
+			"terminal_url":                     "https://terminal.test",
+		} {
 			if err := os.WriteFile(filepath.Join(configDir, name), []byte(value), 0o600); err != nil {
 				t.Fatal(err)
 			}
@@ -1234,6 +1241,9 @@ func TestCrossPlatformCoveragePortableAuthBundleCoverageEdges(t *testing.T) {
 		if _, err := os.Stat(filepath.Join(importDir, "app.json")); err != nil {
 			t.Fatal("config file was not imported")
 		}
+		if _, err := os.Stat(filepath.Join(importDir, config.ManagedMCPURLRegionFileName)); err != nil {
+			t.Fatal("managed MCP region marker was not imported")
+		}
 		if _, err := os.Stat(filepath.Join(keychain.StorageDir(keychain.Service), keychain.AccountToken+".enc")); err != nil {
 			t.Fatal("encrypted token was not imported")
 		}

internal/auth/device_flow.go

@@ -74,6 +74,20 @@ var (
 	}
 )
 
+func deviceFetchClientIDForLoginRegion(ctx context.Context, region LoginRegion) (string, error) {
+	if region.IsInternational() {
+		return FetchClientIDFromMCPForLoginRegion(ctx, region)
+	}
+	return deviceFetchClientID(ctx)
+}
+
+func deviceGetAdminsForLoginRegion(ctx context.Context, accessToken string, region LoginRegion) (*SuperAdminResponse, error) {
+	if region.IsInternational() {
+		return GetSuperAdminsForLoginRegion(ctx, accessToken, region)
+	}
+	return deviceGetAdmins(ctx, accessToken)
+}
+
 type DeviceFlowProvider struct {
 	configDir        string
 	clientID         string
@@ -85,6 +99,7 @@ type DeviceFlowProvider struct {
 	httpClient       *http.Client
 	NoBrowser        bool
 	IdentityEnricher func(context.Context, *TokenData) error
+	LoginRegion      LoginRegion
 }
 
 func NewDeviceFlowProvider(configDir string, logger *slog.Logger) *DeviceFlowProvider {
@@ -104,6 +119,12 @@ func (p *DeviceFlowProvider) SetBaseURL(baseURL string) {
 	p.baseURL = strings.TrimRight(baseURL, "/")
 }
 
+func (p *DeviceFlowProvider) SetLoginRegion(region LoginRegion) {
+	p.LoginRegion = region
+	p.baseURL = DeviceBaseURLForLoginRegion(region)
+	p.terminalBaseURL = MCPBaseURLForLoginRegion(region)
+}
+
 // SetTerminalBaseURL sets the terminal API base URL for device flow polling.
 func (p *DeviceFlowProvider) SetTerminalBaseURL(baseURL string) {
 	p.terminalBaseURL = strings.TrimRight(baseURL, "/")
@@ -213,7 +234,7 @@ func (p *DeviceFlowProvider) Login(ctx context.Context) (*TokenData, error) {
 		if p.logger != nil {
 			p.logger.Debug("fetching client ID from MCP server (device flow always re-fetches)")
 		}
-		mcpClientID, mcpErr := deviceFetchClientID(ctx)
+		mcpClientID, mcpErr := deviceFetchClientIDForLoginRegion(ctx, p.LoginRegion)
 		if mcpErr != nil {
 			return nil, fmt.Errorf("%s: %w", i18n.T("获取 Client ID 失败"), mcpErr)
 		}
@@ -272,6 +293,7 @@ func (p *DeviceFlowProvider) loginOnce(ctx context.Context, attempt int) (*Token
 		clientID:         p.clientID,
 		logger:           p.logger,
 		IdentityEnricher: p.IdentityEnricher,
+		LoginRegion:      p.LoginRegion,
 	}
 	tokenData, err := deviceExchangeCode(oauthProvider, ctx, tokenResult.AuthCode)
 	if err != nil {
@@ -331,7 +353,7 @@ func (p *DeviceFlowProvider) loginOnce(ctx context.Context, attempt int) (*Token
 			_, _ = fmt.Fprintln(p.output(), i18n.T("   你所选择的组织管理员尚未开启「允许成员通过 CLI 访问其个人数据」的权限。"))
 			_, _ = fmt.Fprintln(p.output(), "")
 
-			admins, adminErr := deviceGetAdmins(ctx, tokenData.AccessToken)
+			admins, adminErr := deviceGetAdminsForLoginRegion(ctx, tokenData.AccessToken, p.LoginRegion)
 			if adminErr == nil && admins.Success && len(admins.Result) > 0 {
 				maxAdmins := 3
 				if len(admins.Result) < maxAdmins {

internal/auth/device_flow_test.go

@@ -90,6 +90,17 @@ func TestRequestDeviceCodeSuccess(t *testing.T) {
 	}
 }
 
+func TestCrossPlatformCoverageDeviceFlowSetLoginRegionUsesInternationalBaseURL(t *testing.T) {
+	provider := NewDeviceFlowProvider(t.TempDir(), newDeviceFlowTestLogger())
+	provider.SetLoginRegion(LoginRegionInternational)
+	if provider.baseURL != InternationalDeviceBaseURL {
+		t.Fatalf("baseURL = %q, want %q", provider.baseURL, InternationalDeviceBaseURL)
+	}
+	if provider.terminalBaseURL != InternationalMCPBaseURL {
+		t.Fatalf("terminalBaseURL = %q, want %q", provider.terminalBaseURL, InternationalMCPBaseURL)
+	}
+}
+
 func TestWaitForAuthorizationSucceedsAfterPending(t *testing.T) {
 	t.Parallel()
 

internal/auth/endpoints.go

@@ -50,9 +50,15 @@ const (
 	// AuthorizeURL is the DingTalk OAuth authorization page.
 	AuthorizeURL = "https://login.dingtalk.com/oauth2/auth"
 
+	// InternationalAuthorizeURL is the DingTalk international OAuth authorization page.
+	InternationalAuthorizeURL = "https://login.dingtalk.io/oauth2/auth"
+
 	// UserAccessTokenURL exchanges an authorization code for user tokens.
 	UserAccessTokenURL = "https://api.dingtalk.com/v1.0/oauth2/userAccessToken"
 
+	// InternationalUserAccessTokenURL exchanges authorization codes for international user tokens.
+	InternationalUserAccessTokenURL = "https://api.dingtalk.io/v1.0/oauth2/userAccessToken"
+
 	// UserInfoURL fetches the authenticated user's profile.
 	UserInfoURL = "https://api.dingtalk.com/v1.0/contact/users/me"
 
@@ -75,6 +81,9 @@ const (
 	// DefaultDeviceBaseURL is the login server base URL for device flow.
 	DefaultDeviceBaseURL = "https://login.dingtalk.com"
 
+	// InternationalDeviceBaseURL is the international login server base URL for device flow.
+	InternationalDeviceBaseURL = "https://login.dingtalk.io"
+
 	// DeviceCodePath requests a device_code and user_code.
 	DeviceCodePath = "/oauth2/device/code.json"
 
@@ -96,11 +105,12 @@ const (
 	LogoutContinueURL = "https://login.dingtalk.com"
 
 	// MCP API endpoints for CLI authorization management.
-	DefaultMCPBaseURL    = config.DefaultMCPBaseURL
-	CLIAuthEnabledPath   = "/cli/cliAuthEnabled"
-	SuperAdminPath       = "/cli/superAdmin"
-	SendCliAuthApplyPath = "/cli/sendCliAuthApply"
-	ClientIDPath         = "/cli/clientId"
+	DefaultMCPBaseURL       = config.DefaultMCPBaseURL
+	InternationalMCPBaseURL = "https://mcp.dingtalk.io"
+	CLIAuthEnabledPath      = "/cli/cliAuthEnabled"
+	SuperAdminPath          = "/cli/superAdmin"
+	SendCliAuthApplyPath    = "/cli/sendCliAuthApply"
+	ClientIDPath            = "/cli/clientId"
 
 	// MCP OAuth endpoints (used when clientId is fetched from MCP).
 	MCPOAuthTokenPath   = "/oauth2/getToken"
@@ -114,6 +124,57 @@ const (
 	AppAccessTokenURL = "https://api.dingtalk.com/v1.0/oauth2/accessToken"
 )
 
+type LoginRegion string
+
+const (
+	LoginRegionDefault       LoginRegion = ""
+	LoginRegionInternational LoginRegion = "international"
+)
+
+func (r LoginRegion) IsInternational() bool {
+	return r == LoginRegionInternational
+}
+
+func AuthorizeURLForLoginRegion(region LoginRegion) string {
+	if override := LoginBaseURLOverride(); override != "" {
+		return override + "/oauth2/auth"
+	}
+	if region.IsInternational() {
+		return InternationalAuthorizeURL
+	}
+	return AuthorizeURL
+}
+
+func DeviceBaseURLForLoginRegion(region LoginRegion) string {
+	if override := LoginBaseURLOverride(); override != "" {
+		return override
+	}
+	if region.IsInternational() {
+		return InternationalDeviceBaseURL
+	}
+	return DefaultDeviceBaseURL
+}
+
+func MCPBaseURLForLoginRegion(region LoginRegion) string {
+	if override := MCPBaseURLOverride(); override != "" {
+		return override
+	}
+	if region.IsInternational() {
+		return InternationalMCPBaseURL
+	}
+	return GetMCPBaseURL()
+}
+
+func UserAccessTokenURLForLoginRegion(region LoginRegion) string {
+	if override := LoginBaseURLOverride(); override != "" {
+		return override + "/v1.0/oauth2/userAccessToken"
+	}
+	if region.IsInternational() {
+		return InternationalUserAccessTokenURL
+	}
+	return UserAccessTokenURL
+}
+
 // GetTerminalBaseURL returns the terminal base URL with priority:
 // 1. ~/.dws/terminal_url file content (for pre-release environment)
 // 2. Default value (https://open-dev.dingtalk.com)
@@ -146,8 +207,54 @@ var (
 	// clientIDFromMCP indicates whether the clientID was fetched from MCP server.
 	// When true, MCP OAuth endpoints should be used instead of direct DingTalk API.
 	clientIDFromMCP bool
+
+	loginBaseURLMu       sync.RWMutex
+	loginBaseURLOverride string
+	mcpBaseURLMu         sync.RWMutex
+	mcpBaseURLOverride   string
 )
 
+// PushLoginBaseURLOverride sets a process-local DingTalk login base URL
+// override and returns a restore function.
+func PushLoginBaseURLOverride(baseURL string) func() {
+	loginBaseURLMu.Lock()
+	previous := loginBaseURLOverride
+	loginBaseURLOverride = strings.TrimRight(strings.TrimSpace(baseURL), "/")
+	loginBaseURLMu.Unlock()
+	return func() {
+		loginBaseURLMu.Lock()
+		loginBaseURLOverride = previous
+		loginBaseURLMu.Unlock()
+	}
+}
+
+func LoginBaseURLOverride() string {
+	loginBaseURLMu.RLock()
+	defer loginBaseURLMu.RUnlock()
+	return loginBaseURLOverride
+}
+
+// PushMCPBaseURLOverride sets a process-local MCP base URL override and returns
+// a restore function. It is intended for one command invocation, such as
+// pre-release smoke testing.
+func PushMCPBaseURLOverride(baseURL string) func() {
+	mcpBaseURLMu.Lock()
+	previous := mcpBaseURLOverride
+	mcpBaseURLOverride = strings.TrimRight(strings.TrimSpace(baseURL), "/")
+	mcpBaseURLMu.Unlock()
+	return func() {
+		mcpBaseURLMu.Lock()
+		mcpBaseURLOverride = previous
+		mcpBaseURLMu.Unlock()
+	}
+}
+
+func MCPBaseURLOverride() string {
+	mcpBaseURLMu.RLock()
+	defer mcpBaseURLMu.RUnlock()
+	return mcpBaseURLOverride
+}
+
 // SetClientIDFromMCP sets the clientID fetched from MCP server and marks it as MCP-sourced.
 func SetClientIDFromMCP(id string) {
 	clientMu.Lock()

internal/auth/oauth_helpers.go

@@ -20,6 +20,7 @@ import (
 	"fmt"
 	"html"
 	"io"
+	"log/slog"
 	"net/http"
 	"net/url"
 	"os"
@@ -28,6 +29,7 @@ import (
 	"time"
 
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/config"
+	"github.com/google/uuid"
 )
 
 var (
@@ -51,7 +53,7 @@ func (p *OAuthProvider) exchangeCode(ctx context.Context, code string) (*TokenDa
 		"code":         code,
 		"grantType":    "authorization_code",
 	}
-	resp, err := p.postJSON(ctx, UserAccessTokenURL, body)
+	resp, err := p.postJSON(ctx, UserAccessTokenURLForLoginRegion(p.loginRegion()), body)
 	if err != nil {
 		return nil, err
 	}
@@ -62,6 +64,7 @@ func (p *OAuthProvider) exchangeCode(ctx context.Context, code string) (*TokenDa
 	// Snapshot credentials used for this token (for refresh)
 	data.ClientID = clientID
 	data.Source = resolveCredentialSource()
+	p.applyLoginRegionToToken(data)
 	// Save clientSecret for future refresh (even if env changes)
 	if err := oauthSaveClientSecret(clientID, clientSecret); err != nil {
 		// Log warning but don't fail login
@@ -91,11 +94,36 @@ func ExchangeCodeForToken(ctx context.Context, configDir, code string) (*TokenDa
 	return data, nil
 }
 
+func (p *OAuthProvider) loginRegion() LoginRegion {
+	if p == nil {
+		return LoginRegionDefault
+	}
+	return p.LoginRegion
+}
+
+func (p *OAuthProvider) useTokenLoginRegion(data *TokenData) {
+	if p == nil || p.LoginRegion != LoginRegionDefault || data == nil {
+		return
+	}
+	if region := LoginRegion(strings.TrimSpace(data.LoginRegion)); region != LoginRegionDefault {
+		p.LoginRegion = region
+	}
+}
+
+func (p *OAuthProvider) applyLoginRegionToToken(data *TokenData) {
+	if data == nil {
+		return
+	}
+	if region := p.loginRegion(); region != LoginRegionDefault {
+		data.LoginRegion = string(region)
+	}
+}
+
 // exchangeCodeViaMCP exchanges auth code for token via MCP proxy.
 // This is used when client secret is not available (server-side secret management).
 func (p *OAuthProvider) exchangeCodeViaMCP(ctx context.Context, code string) (*TokenData, error) {
 	clientID := ClientID()
-	url := GetMCPBaseURL() + MCPOAuthTokenPath
+	url := MCPBaseURLForLoginRegion(p.loginRegion()) + MCPOAuthTokenPath
 	body := map[string]string{
 		"clientId":  clientID,
 		"authCode":  code,
@@ -112,6 +140,7 @@ func (p *OAuthProvider) exchangeCodeViaMCP(ctx context.Context, code string) (*T
 	// Snapshot credentials used for this token (for refresh)
 	data.ClientID = clientID
 	data.Source = "mcp"
+	p.applyLoginRegionToToken(data)
 	// MCP mode doesn't need to save clientSecret (server-side managed)
 	return data, nil
 }
@@ -120,8 +149,10 @@ func (p *OAuthProvider) refreshWithRefreshToken(ctx context.Context, data *Token
 	// Use stored Source to determine refresh path (not current runtime state)
 	// This ensures refresh works even if environment variables changed since login
 	if data.Source == "mcp" {
+		p.useTokenLoginRegion(data)
 		return p.refreshViaMCP(ctx, data)
 	}
+	p.useTokenLoginRegion(data)
 
 	// Direct mode: use stored clientId and load saved clientSecret
 	clientID := data.ClientID
@@ -145,7 +176,7 @@ func (p *OAuthProvider) refreshWithRefreshToken(ctx context.Context, data *Token
 		"refreshToken": data.RefreshToken,
 		"grantType":    "refresh_token",
 	}
-	resp, err := p.postJSON(ctx, UserAccessTokenURL, body)
+	resp, err := p.postJSON(ctx, UserAccessTokenURLForLoginRegion(p.loginRegion()), body)
 	if err != nil {
 		return nil, err
 	}
@@ -156,6 +187,7 @@ func (p *OAuthProvider) refreshWithRefreshToken(ctx context.Context, data *Token
 	// Preserve original credentials info
 	updated.ClientID = data.ClientID
 	updated.Source = data.Source
+	updated.LoginRegion = data.LoginRegion
 	updated.PersistentCode = data.PersistentCode
 	updated.CorpID = data.CorpID
 	updated.UserID = data.UserID
@@ -185,7 +217,7 @@ func (p *OAuthProvider) refreshViaMCP(ctx context.Context, data *TokenData) (*To
 		return nil, fmt.Errorf("无法刷新 token: 缺少 clientId，请重新登录")
 	}
 
-	url := GetMCPBaseURL() + MCPRefreshTokenPath
+	url := MCPBaseURLForLoginRegion(p.loginRegion()) + MCPRefreshTokenPath
 	body := map[string]string{
 		"clientId":     clientID,
 		"refreshToken": data.RefreshToken,
@@ -202,6 +234,7 @@ func (p *OAuthProvider) refreshViaMCP(ctx context.Context, data *TokenData) (*To
 	// Preserve original credentials info
 	updated.ClientID = data.ClientID
 	updated.Source = data.Source
+	updated.LoginRegion = data.LoginRegion
 	updated.PersistentCode = data.PersistentCode
 	updated.CorpID = data.CorpID
 	updated.UserID = data.UserID
@@ -371,6 +404,10 @@ func firstNonEmpty(values ...string) string {
 }
 
 func buildAuthURL(clientID, redirectURI, targetCorpID string) string {
+	return buildAuthURLForRegion(clientID, redirectURI, targetCorpID, LoginRegionDefault)
+}
+
+func buildAuthURLForRegion(clientID, redirectURI, targetCorpID string, region LoginRegion) string {
 	params := url.Values{
 		"client_id":     {clientID},
 		"redirect_uri":  {redirectURI},
@@ -381,7 +418,7 @@ func buildAuthURL(clientID, redirectURI, targetCorpID string) string {
 	if targetCorpID = strings.TrimSpace(targetCorpID); targetCorpID != "" {
 		params.Set("corpId", targetCorpID)
 	}
-	return AuthorizeURL + "?" + params.Encode()
+	return AuthorizeURLForLoginRegion(region) + "?" + params.Encode()
 }
 
 const successHTML = `<!doctype html>
@@ -937,14 +974,15 @@ const notEnabledHTML = `<!doctype html>
           clientId = status.clientId || "";
           applySent = status.applySent || false;
           selectedAdminId = status.selectedAdminId || "";
+          const authorizeUrl = status.authorizeUrl || "";
 
-          if (clientId) {
+          if (clientId && authorizeUrl) {
             const port = location.port;
             const redirectUri = encodeURIComponent(
               "http://127.0.0.1:" + port + "/callback"
             );
             backLink.href =
-              "https://login.dingtalk.com/oauth2/auth?client_id=" +
+              authorizeUrl + "?client_id=" +
               clientId +
               "&prompt=consent&redirect_uri=" +
               redirectUri +
@@ -1398,6 +1436,7 @@ const mcpRequestMaxRetries = 3
 // false negatives caused by momentary network issues.
 func (p *OAuthProvider) CheckCLIAuthEnabled(ctx context.Context, accessToken string) (*CLIAuthStatus, error) {
 	var lastErr error
+	traceID := cliAuthTraceID()
 	for attempt := 0; attempt < mcpRequestMaxRetries; attempt++ {
 		if attempt > 0 {
 			select {
@@ -1406,7 +1445,7 @@ func (p *OAuthProvider) CheckCLIAuthEnabled(ctx context.Context, accessToken str
 			case <-oauthRetryAfter(time.Duration(attempt) * time.Second):
 			}
 		}
-		status, err := p.doCheckCLIAuthEnabled(ctx, accessToken)
+		status, err := p.doCheckCLIAuthEnabledAttempt(ctx, accessToken, attempt+1, traceID)
 		if err == nil {
 			return status, nil
 		}
@@ -1416,16 +1455,27 @@ func (p *OAuthProvider) CheckCLIAuthEnabled(ctx context.Context, accessToken str
 }
 
 func (p *OAuthProvider) doCheckCLIAuthEnabled(ctx context.Context, accessToken string) (*CLIAuthStatus, error) {
-	url := GetMCPBaseURL() + CLIAuthEnabledPath
+	return p.doCheckCLIAuthEnabledAttempt(ctx, accessToken, 1, cliAuthTraceID())
+}
+
+func (p *OAuthProvider) doCheckCLIAuthEnabledAttempt(ctx context.Context, accessToken string, attempt int, traceID string) (*CLIAuthStatus, error) {
+	url := MCPBaseURLForLoginRegion(p.loginRegion()) + CLIAuthEnabledPath
 	req, err := oauthNewRequest(ctx, http.MethodGet, url, nil)
 	if err != nil {
 		return nil, fmt.Errorf("creating request: %w", err)
 	}
 	req.Header.Set("x-user-access-token", accessToken)
+	applyCLIAuthTraceHeaders(req, traceID)
 	if ch := os.Getenv("DWS_CHANNEL"); ch != "" {
 		req.Header.Set("x-dws-channel", ch)
 	}
 	applyEditionEnterpriseCredentialHeaders(req)
+	slog.Debug("auth.cli_auth_enabled.request",
+		"attempt", attempt,
+		"url", url,
+		"trace_id", traceID,
+		"channel", os.Getenv("DWS_CHANNEL"),
+	)
 
 	client := p.httpClient
 	if client == nil {
@@ -1433,9 +1483,23 @@ func (p *OAuthProvider) doCheckCLIAuthEnabled(ctx context.Context, accessToken s
 	}
 	resp, err := client.Do(req)
 	if err != nil {
+		slog.Debug("auth.cli_auth_enabled.error",
+			"attempt", attempt,
+			"url", url,
+			"trace_id", traceID,
+			"error", err,
+		)
 		return nil, fmt.Errorf("sending request: %w", err)
 	}
 	defer resp.Body.Close()
+	slog.Debug("auth.cli_auth_enabled.response",
+		"attempt", attempt,
+		"url", url,
+		"status", resp.StatusCode,
+		"trace_id", traceID,
+		"response_trace_id", cliAuthResponseTraceID(resp.Header),
+		"eagleeye_rpc_id", resp.Header.Get("EagleEye-RpcId"),
+	)
 
 	data, err := io.ReadAll(io.LimitReader(resp.Body, config.MaxResponseBodySize))
 	if err != nil {
@@ -1449,9 +1513,42 @@ func (p *OAuthProvider) doCheckCLIAuthEnabled(ctx context.Context, accessToken s
 	return &status, nil
 }
 
+func cliAuthTraceID() string {
+	if traceID := strings.TrimSpace(os.Getenv("DINGTALK_TRACE_ID")); traceID != "" {
+		return traceID
+	}
+	return strings.ReplaceAll(uuid.NewString(), "-", "")
+}
+
+func applyCLIAuthTraceHeaders(req *http.Request, traceID string) {
+	if req == nil || traceID == "" {
+		return
+	}
+	req.Header.Set("EagleEye-TraceId", traceID)
+	req.Header.Set("X-Dingtalk-Trace-Id", traceID)
+}
+
+func cliAuthResponseTraceID(headers http.Header) string {
+	for _, key := range []string{
+		"EagleEye-TraceId",
+		"X-Trace-Id",
+		"X-Request-Id",
+		"X-Dingtalk-Trace-Id",
+	} {
+		if value := strings.TrimSpace(headers.Get(key)); value != "" {
+			return value
+		}
+	}
+	return ""
+}
+
 // GetSuperAdmins fetches the list of corp super admins.
 // It retries up to mcpRequestMaxRetries times on transient errors.
 func GetSuperAdmins(ctx context.Context, accessToken string) (*SuperAdminResponse, error) {
+	return GetSuperAdminsForLoginRegion(ctx, accessToken, LoginRegionDefault)
+}
+
+func GetSuperAdminsForLoginRegion(ctx context.Context, accessToken string, region LoginRegion) (*SuperAdminResponse, error) {
 	var lastErr error
 	for attempt := 0; attempt < mcpRequestMaxRetries; attempt++ {
 		if attempt > 0 {
@@ -1461,7 +1558,7 @@ func GetSuperAdmins(ctx context.Context, accessToken string) (*SuperAdminRespons
 			case <-oauthRetryAfter(time.Duration(attempt) * time.Second):
 			}
 		}
-		result, err := doGetSuperAdmins(ctx, accessToken)
+		result, err := doGetSuperAdminsForLoginRegion(ctx, accessToken, region)
 		if err == nil {
 			return result, nil
 		}
@@ -1471,7 +1568,11 @@ func GetSuperAdmins(ctx context.Context, accessToken string) (*SuperAdminRespons
 }
 
 func doGetSuperAdmins(ctx context.Context, accessToken string) (*SuperAdminResponse, error) {
-	url := GetMCPBaseURL() + SuperAdminPath
+	return doGetSuperAdminsForLoginRegion(ctx, accessToken, LoginRegionDefault)
+}
+
+func doGetSuperAdminsForLoginRegion(ctx context.Context, accessToken string, region LoginRegion) (*SuperAdminResponse, error) {
+	url := MCPBaseURLForLoginRegion(region) + SuperAdminPath
 	req, err := oauthNewRequest(ctx, http.MethodGet, url, nil)
 	if err != nil {
 		return nil, fmt.Errorf("creating request: %w", err)
@@ -1500,6 +1601,10 @@ func doGetSuperAdmins(ctx context.Context, accessToken string) (*SuperAdminRespo
 // SendCliAuthApply sends a CLI auth apply request to the specified admin.
 // It retries up to mcpRequestMaxRetries times on transient errors.
 func SendCliAuthApply(ctx context.Context, accessToken, adminStaffID string) (*SendApplyResponse, error) {
+	return SendCliAuthApplyForLoginRegion(ctx, accessToken, adminStaffID, LoginRegionDefault)
+}
+
+func SendCliAuthApplyForLoginRegion(ctx context.Context, accessToken, adminStaffID string, region LoginRegion) (*SendApplyResponse, error) {
 	var lastErr error
 	for attempt := 0; attempt < mcpRequestMaxRetries; attempt++ {
 		if attempt > 0 {
@@ -1509,7 +1614,7 @@ func SendCliAuthApply(ctx context.Context, accessToken, adminStaffID string) (*S
 			case <-oauthRetryAfter(time.Duration(attempt) * time.Second):
 			}
 		}
-		result, err := doSendCliAuthApply(ctx, accessToken, adminStaffID)
+		result, err := doSendCliAuthApplyForLoginRegion(ctx, accessToken, adminStaffID, region)
 		if err == nil {
 			return result, nil
 		}
@@ -1519,7 +1624,11 @@ func SendCliAuthApply(ctx context.Context, accessToken, adminStaffID string) (*S
 }
 
 func doSendCliAuthApply(ctx context.Context, accessToken, adminStaffID string) (*SendApplyResponse, error) {
-	url := GetMCPBaseURL() + SendCliAuthApplyPath + "?adminStaffId=" + adminStaffID
+	return doSendCliAuthApplyForLoginRegion(ctx, accessToken, adminStaffID, LoginRegionDefault)
+}
+
+func doSendCliAuthApplyForLoginRegion(ctx context.Context, accessToken, adminStaffID string, region LoginRegion) (*SendApplyResponse, error) {
+	url := MCPBaseURLForLoginRegion(region) + SendCliAuthApplyPath + "?adminStaffId=" + adminStaffID
 	req, err := oauthNewRequest(ctx, http.MethodGet, url, nil)
 	if err != nil {
 		return nil, fmt.Errorf("creating request: %w", err)
@@ -1557,6 +1666,10 @@ type ClientIDResponse struct {
 // This is used when no client ID is provided via flags, config, or env vars.
 // It retries up to mcpRequestMaxRetries times on transient errors.
 func FetchClientIDFromMCP(ctx context.Context) (string, error) {
+	return FetchClientIDFromMCPForLoginRegion(ctx, LoginRegionDefault)
+}
+
+func FetchClientIDFromMCPForLoginRegion(ctx context.Context, region LoginRegion) (string, error) {
 	var lastErr error
 	for attempt := 0; attempt < mcpRequestMaxRetries; attempt++ {
 		if attempt > 0 {
@@ -1566,7 +1679,7 @@ func FetchClientIDFromMCP(ctx context.Context) (string, error) {
 			case <-oauthRetryAfter(time.Duration(attempt) * time.Second):
 			}
 		}
-		id, err := doFetchClientIDFromMCP(ctx)
+		id, err := doFetchClientIDFromMCPForLoginRegion(ctx, region)
 		if err == nil {
 			return id, nil
 		}
@@ -1576,7 +1689,11 @@ func FetchClientIDFromMCP(ctx context.Context) (string, error) {
 }
 
 func doFetchClientIDFromMCP(ctx context.Context) (string, error) {
-	url := GetMCPBaseURL() + ClientIDPath
+	return doFetchClientIDFromMCPForLoginRegion(ctx, LoginRegionDefault)
+}
+
+func doFetchClientIDFromMCPForLoginRegion(ctx context.Context, region LoginRegion) (string, error) {
+	url := MCPBaseURLForLoginRegion(region) + ClientIDPath
 	req, err := oauthNewRequest(ctx, http.MethodGet, url, nil)
 	if err != nil {
 		return "", fmt.Errorf("creating request: %w", err)

internal/auth/oauth_provider.go

@@ -68,6 +68,27 @@ var (
 	oauthSleep = time.Sleep
 )
 
+func oauthFetchClientIDForLoginRegion(ctx context.Context, region LoginRegion) (string, error) {
+	if region.IsInternational() {
+		return FetchClientIDFromMCPForLoginRegion(ctx, region)
+	}
+	return oauthFetchClientID(ctx)
+}
+
+func oauthGetAdminsForLoginRegion(ctx context.Context, accessToken string, region LoginRegion) (*SuperAdminResponse, error) {
+	if region.IsInternational() {
+		return GetSuperAdminsForLoginRegion(ctx, accessToken, region)
+	}
+	return oauthGetAdmins(ctx, accessToken)
+}
+
+func oauthSendApplyForLoginRegion(ctx context.Context, accessToken, adminStaffID string, region LoginRegion) (*SendApplyResponse, error) {
+	if region.IsInternational() {
+		return SendCliAuthApplyForLoginRegion(ctx, accessToken, adminStaffID, region)
+	}
+	return oauthSendApply(ctx, accessToken, adminStaffID)
+}
+
 // OAuthProvider handles the DingTalk OAuth 2.0 authorization code flow.
 type OAuthProvider struct {
 	configDir    string
@@ -80,6 +101,7 @@ type OAuthProvider struct {
 	// IdentityEnricher resolves userId/userName/corpName while the freshly
 	// exchanged access token is still only in memory.
 	IdentityEnricher func(context.Context, *TokenData) error
+	LoginRegion      LoginRegion
 }
 
 // NewOAuthProvider creates a new OAuth provider.
@@ -173,7 +195,7 @@ func (p *OAuthProvider) Login(ctx context.Context, force bool) (*TokenData, erro
 		if p.logger != nil {
 			p.logger.Debug("fetching client ID from MCP server (OAuth flow always re-fetches)")
 		}
-		mcpClientID, mcpErr := oauthFetchClientID(ctx)
+		mcpClientID, mcpErr := oauthFetchClientIDForLoginRegion(ctx, p.LoginRegion)
 		if mcpErr != nil {
 			return nil, fmt.Errorf("%s: %w", i18n.T("获取 Client ID 失败"), mcpErr)
 		}
@@ -401,7 +423,7 @@ func (p *OAuthProvider) Login(ctx context.Context, force bool) (*TokenData, erro
 			_, _ = w.Write([]byte(`{"success":false,"errorMsg":"授权尚未完成"}`))
 			return
 		}
-		result, err := oauthGetAdmins(ctx, token.AccessToken)
+		result, err := oauthGetAdminsForLoginRegion(ctx, token.AccessToken, p.LoginRegion)
 		if err != nil {
 			_, _ = fmt.Fprintf(w, `{"success":false,"errorMsg":"%s"}`, err.Error())
 			return
@@ -425,7 +447,7 @@ func (p *OAuthProvider) Login(ctx context.Context, force bool) (*TokenData, erro
 			_, _ = w.Write([]byte(`{"success":false,"errorMsg":"授权尚未完成"}`))
 			return
 		}
-		result, err := oauthSendApply(ctx, token.AccessToken, adminStaffID)
+		result, err := oauthSendApplyForLoginRegion(ctx, token.AccessToken, adminStaffID, p.LoginRegion)
 		if err != nil {
 			_, _ = fmt.Fprintf(w, `{"success":false,"errorMsg":"%s"}`, err.Error())
 			return
@@ -448,7 +470,13 @@ func (p *OAuthProvider) Login(ctx context.Context, force bool) (*TokenData, erro
 		applySent := callbackApplySent
 		selectedAdminId := callbackSelectedAdminId
 		callbackTokenMu.Unlock()
-		_, _ = fmt.Fprintf(w, `{"clientId":"%s","applySent":%t,"selectedAdminId":"%s"}`, p.clientID, applySent, selectedAdminId)
+		data, _ := json.Marshal(map[string]any{
+			"clientId":        p.clientID,
+			"authorizeUrl":    AuthorizeURLForLoginRegion(p.LoginRegion),
+			"applySent":       applySent,
+			"selectedAdminId": selectedAdminId,
+		})
+		_, _ = w.Write(data)
 	})
 
 	// API endpoint: check CLI auth enabled status
@@ -491,7 +519,7 @@ func (p *OAuthProvider) Login(ctx context.Context, force bool) (*TokenData, erro
 		_ = server.Shutdown(shutCtx)
 	}()
 
-	authURL := buildAuthURL(p.clientID, redirectURI, p.TargetCorpID)
+	authURL := buildAuthURLForRegion(p.clientID, redirectURI, p.TargetCorpID, p.LoginRegion)
 	if p.logger != nil {
 		p.logger.Debug("authorization URL", "url", authURL)
 	}

internal/auth/portable_store.go

@@ -272,7 +272,7 @@ func ImportPortableAuthBundle(configDir string, r io.Reader) (PortableImportRepo
 
 func portableConfigFiles(configDir string) ([]string, error) {
 	var files []string
-	patterns := []string{"app*.json", profilesJSONFile, "mcp_url", "terminal_url"}
+	patterns := []string{"app*.json", profilesJSONFile, "mcp_url", config.ManagedMCPURLRegionFileName, "terminal_url"}
 	for _, pattern := range patterns {
 		matches, err := portableGlob(filepath.Join(configDir, pattern))
 		if err != nil {

internal/auth/profile_metadata_readonly.go

@@ -0,0 +1,70 @@
+// 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 auth
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"strings"
+)
+
+// ProfileMetadata is the minimal, non-sensitive identity projection exposed to
+// telemetry callers. It intentionally excludes profile names, client IDs,
+// organization names, token material, and credential status.
+type ProfileMetadata struct {
+	UserID   string
+	UserName string
+	CorpID   string
+}
+
+// ResolveProfileMetadataReadOnly resolves one identity exclusively from the
+// non-sensitive profiles.json metadata. It deliberately avoids auth locks,
+// token stores, Keychain access, migrations, quarantine renames, and writes.
+// A missing metadata file or an empty current profile returns (nil, nil).
+func ResolveProfileMetadataReadOnly(configDir, selector string) (*ProfileMetadata, error) {
+	data, err := profilesReadFile(ProfilesPath(configDir))
+	if err != nil {
+		if os.IsNotExist(err) {
+			return nil, nil
+		}
+		return nil, fmt.Errorf("read profile metadata: %w", err)
+	}
+
+	var cfg ProfilesConfig
+	if err := json.Unmarshal(data, &cfg); err != nil {
+		return nil, fmt.Errorf("parse profile metadata: %w", err)
+	}
+	if cfg.Version > profilesMaxVersion {
+		return nil, fmt.Errorf("profile metadata version %d is newer than supported version %d", cfg.Version, profilesMaxVersion)
+	}
+	normalizeProfilesConfig(&cfg)
+
+	selector = strings.TrimSpace(selector)
+	if selector == "" {
+		selector = strings.TrimSpace(cfg.CurrentProfile)
+		if selector == "" {
+			return nil, nil
+		}
+	}
+	profile, _, err := resolveProfileSelection("", &cfg, selector)
+	if err != nil {
+		return nil, err
+	}
+	return &ProfileMetadata{
+		UserID:   profile.UserID,
+		UserName: profile.UserName,
+		CorpID:   profile.CorpID,
+	}, nil
+}

internal/auth/profile_metadata_readonly_test.go

@@ -0,0 +1,97 @@
+// 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 auth
+
+import (
+	"errors"
+	"os"
+	"strings"
+	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam"
+)
+
+func TestCrossPlatformCoverageResolveProfileMetadataReadOnly(t *testing.T) {
+	const metadata = `{
+  "version": 3,
+  "currentProfile": "corp-a:user-a",
+  "profiles": [
+    {"name":"alpha","corpId":"corp-a","userId":"user-a","userName":"Alice"},
+    {"name":"beta","corpId":"corp-b","userId":"user-b","userName":"Bob"}
+  ]
+}`
+	reads := 0
+	testseam.Swap(t, &profilesReadFile, func(path string) ([]byte, error) {
+		reads++
+		if !strings.HasSuffix(path, profilesJSONFile) {
+			t.Fatalf("metadata path = %q", path)
+		}
+		return []byte(metadata), nil
+	})
+
+	current, err := ResolveProfileMetadataReadOnly("/config", "")
+	if err != nil || current == nil || current.UserID != "user-a" || current.UserName != "Alice" || current.CorpID != "corp-a" {
+		t.Fatalf("current metadata profile = %#v, %v", current, err)
+	}
+	explicit, err := ResolveProfileMetadataReadOnly("/config", "beta")
+	if err != nil || explicit == nil || explicit.UserID != "user-b" || explicit.CorpID != "corp-b" {
+		t.Fatalf("explicit metadata profile = %#v, %v", explicit, err)
+	}
+	if reads != 2 {
+		t.Fatalf("profile metadata reads = %d, want 2", reads)
+	}
+}
+
+func TestCrossPlatformCoverageResolveProfileMetadataReadOnlyFailsClosed(t *testing.T) {
+	fail := errors.New("read failed")
+	for _, tc := range []struct {
+		name    string
+		read    func(string) ([]byte, error)
+		wantErr string
+	}{
+		{name: "missing", read: func(string) ([]byte, error) { return nil, os.ErrNotExist }},
+		{name: "read error", read: func(string) ([]byte, error) { return nil, fail }, wantErr: "read profile metadata"},
+		{name: "corrupt", read: func(string) ([]byte, error) { return []byte("{"), nil }, wantErr: "parse profile metadata"},
+		{name: "forward version", read: func(string) ([]byte, error) { return []byte(`{"version":999}`), nil }, wantErr: "newer than supported"},
+		{name: "no current", read: func(string) ([]byte, error) { return []byte(`{"version":3,"profiles":[]}`), nil }},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			testseam.Swap(t, &profilesReadFile, tc.read)
+			testseam.Swap(t, &profilesRename, func(string, string) error {
+				t.Fatal("read-only metadata resolution attempted a quarantine rename")
+				return nil
+			})
+			got, err := ResolveProfileMetadataReadOnly("/config", "")
+			if tc.wantErr == "" {
+				if err != nil || got != nil {
+					t.Fatalf("read-only metadata = %#v, %v", got, err)
+				}
+				return
+			}
+			if err == nil || !strings.Contains(err.Error(), tc.wantErr) || got != nil {
+				t.Fatalf("read-only metadata = %#v, %v; want %q", got, err, tc.wantErr)
+			}
+		})
+	}
+}
+
+func TestCrossPlatformCoverageResolveProfileMetadataReadOnlyRejectsUnknownSelector(t *testing.T) {
+	testseam.Swap(t, &profilesReadFile, func(string) ([]byte, error) {
+		return []byte(`{"version":3,"currentProfile":"corp-a:user-a","profiles":[{"name":"alpha","corpId":"corp-a","userId":"user-a"}]}`), nil
+	})
+	profile, err := ResolveProfileMetadataReadOnly("/config", "missing")
+	if err == nil || profile != nil || !strings.Contains(err.Error(), "not found") {
+		t.Fatalf("unknown read-only profile = %#v, %v", profile, err)
+	}
+}

internal/auth/token.go

@@ -97,6 +97,7 @@ type TokenData struct {
 	ClientID       string    `json:"client_id,omitempty"` // Associated app client ID for refresh
 	UpdatedAt      string    `json:"updated_at,omitempty"`
 	Source         string    `json:"source,omitempty"`
+	LoginRegion    string    `json:"login_region,omitempty"`
 	// LegacyOrgScopedProfile is an in-memory destination for an explicitly
 	// matched historical profile whose userId was never resolved. It is never
 	// persisted as token material.

internal/cli/param_aliases.go

@@ -177,6 +177,7 @@ func reduceLeafParamAliases(path string, realByMorph map[string][]realFlag, conc
 	aliasMap := make(map[string]string)
 	blockedSet := make(map[string]bool)
 	excludedSet := make(map[string]bool)
+	claimedRealSet := make(map[string]bool)
 	pendingReview := ov.Confirm || ov.Investigate
 
 	for boundFlag, conceptID := range ov.Bind {
@@ -218,6 +219,14 @@ func reduceLeafParamAliases(path string, realByMorph map[string][]realFlag, conc
 		if len(candidates) == 0 {
 			continue
 		}
+		for m := range eff {
+			if _, isReal := realByMorph[m]; isReal {
+				claimedRealSet[m] = true
+			}
+		}
+		for _, exclude := range concept.Excludes {
+			excludedSet[cmdutil.Morph(exclude)] = true
+		}
 		visible := distinctRealNames(candidates, true)
 		var canon string
 		switch len(visible) {
@@ -267,21 +276,18 @@ func reduceLeafParamAliases(path string, realByMorph map[string][]realFlag, conc
 			}
 			aliasMap[m] = canon
 		}
-		// Excludes are not passive prose: once this concept is active on a
-		// reviewed command, a non-real excluded spelling is protected from
-		// downstream fuzzy correction. A real flag is left alone because it
-		// already has an independently valid command-local meaning.
-		for _, exclude := range concept.Excludes {
-			morphed := cmdutil.Morph(exclude)
-			if _, isReal := realByMorph[morphed]; !isReal {
-				excludedSet[morphed] = true
-			}
-		}
 	}
 	for excluded := range excludedSet {
-		if _, isAlias := aliasMap[excluded]; !isAlias {
-			blockedSet[excluded] = true
+		if _, isAlias := aliasMap[excluded]; isAlias {
+			continue
 		}
+		if claimedRealSet[excluded] {
+			continue
+		}
+		if _, isReal := realByMorph[excluded]; isReal {
+			continue
+		}
+		blockedSet[excluded] = true
 	}
 
 	// (b) Command scoped aliases override concept reductions.

internal/cli/param_aliases_generated.go

@@ -889,13 +889,9 @@ var generatedParamAliases = []ParamAliasEntry{
 		Blocked: []string{"cursor"},
 	},
 	{
-		CLIPath: "chat category add-conv",
-		Aliases: map[string]string{
-			"chat":                 "group",
-			"chat-id":              "group",
-			"open-conversation-id": "group",
-		},
-		Blocked: []string{"category-id", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"},
+		CLIPath:   "chat category add-conv",
+		Blocked:   []string{"category-id", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"},
+		Ambiguous: []string{"chat", "chat-id", "open-conversation-id"},
 	},
 	{
 		CLIPath: "chat category create",
@@ -920,13 +916,9 @@ var generatedParamAliases = []ParamAliasEntry{
 		Blocked: []string{"category-ids"},
 	},
 	{
-		CLIPath: "chat category remove-conv",
-		Aliases: map[string]string{
-			"chat":                 "group",
-			"chat-id":              "group",
-			"open-conversation-id": "group",
-		},
-		Blocked: []string{"category-id", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"},
+		CLIPath:   "chat category remove-conv",
+		Blocked:   []string{"category-id", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"},
+		Ambiguous: []string{"chat", "chat-id", "open-conversation-id"},
 	},
 	{
 		CLIPath: "chat category rename",
@@ -970,23 +962,19 @@ var generatedParamAliases = []ParamAliasEntry{
 	{
 		CLIPath: "chat conversation-info",
 		Aliases: map[string]string{
-			"chat-id":              "group",
-			"open-conversation-id": "group",
-			"staff-id":             "user",
-			"uid":                  "user",
-			"userid":               "user",
+			"staff-id": "user",
+			"uid":      "user",
+			"userid":   "user",
 		},
-		Blocked: []string{"at-user-ids", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target", "to-user", "user-ids", "users"},
+		Blocked:   []string{"at-user-ids", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target", "to-user", "user-ids", "users"},
+		Ambiguous: []string{"chat-id", "open-conversation-id"},
 	},
 	{
 		CLIPath: "chat group audit-join-validation",
 		Aliases: map[string]string{
-			"chat":                 "group",
-			"chat-id":              "group",
-			"conversation-id":      "group",
-			"open-conversation-id": "group",
+			"chat-id": "conversation-id",
 		},
-		Blocked:   []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target"},
+		Blocked:   []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"},
 		Ambiguous: []string{"staff-id", "uid", "user", "user-id", "userid"},
 	},
 	{
@@ -1006,12 +994,9 @@ var generatedParamAliases = []ParamAliasEntry{
 	{
 		CLIPath: "chat group dismiss",
 		Aliases: map[string]string{
-			"chat":                 "group",
-			"chat-id":              "group",
-			"conversation-id":      "group",
-			"open-conversation-id": "group",
+			"chat-id": "conversation-id",
 		},
-		Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target"},
+		Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"},
 	},
 	{
 		CLIPath: "chat group get-by-group-id",
@@ -1020,12 +1005,9 @@ var generatedParamAliases = []ParamAliasEntry{
 	{
 		CLIPath: "chat group invite-url",
 		Aliases: map[string]string{
-			"chat":                 "group",
-			"chat-id":              "group",
-			"conversation-id":      "group",
-			"open-conversation-id": "group",
+			"chat-id": "conversation-id",
 		},
-		Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target"},
+		Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"},
 	},
 	{
 		CLIPath: "chat group members",
@@ -1100,52 +1082,37 @@ var generatedParamAliases = []ParamAliasEntry{
 	{
 		CLIPath: "chat group notice create",
 		Aliases: map[string]string{
-			"chat":                 "group",
-			"chat-id":              "group",
-			"conversation-id":      "group",
-			"open-conversation-id": "group",
+			"chat-id": "conversation-id",
 		},
-		Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target"},
+		Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"},
 	},
 	{
 		CLIPath: "chat group notice edit",
 		Aliases: map[string]string{
-			"chat":                 "group",
-			"chat-id":              "group",
-			"conversation-id":      "group",
-			"open-conversation-id": "group",
+			"chat-id": "conversation-id",
 		},
-		Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target"},
+		Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"},
 	},
 	{
 		CLIPath: "chat group notice get",
 		Aliases: map[string]string{
-			"chat":                 "group",
-			"chat-id":              "group",
-			"conversation-id":      "group",
-			"open-conversation-id": "group",
+			"chat-id": "conversation-id",
 		},
-		Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target"},
+		Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"},
 	},
 	{
 		CLIPath: "chat group notice list",
 		Aliases: map[string]string{
-			"chat":                 "group",
-			"chat-id":              "group",
-			"conversation-id":      "group",
-			"open-conversation-id": "group",
+			"chat-id": "conversation-id",
 		},
-		Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target"},
+		Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"},
 	},
 	{
 		CLIPath: "chat group quit",
 		Aliases: map[string]string{
-			"chat":                 "group",
-			"chat-id":              "group",
-			"conversation-id":      "group",
-			"open-conversation-id": "group",
+			"chat-id": "conversation-id",
 		},
-		Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target"},
+		Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"},
 	},
 	{
 		CLIPath: "chat group rename",
@@ -1161,23 +1128,17 @@ var generatedParamAliases = []ParamAliasEntry{
 	{
 		CLIPath: "chat group set-admin",
 		Aliases: map[string]string{
-			"chat":                 "group",
-			"chat-id":              "group",
-			"conversation-id":      "group",
-			"open-conversation-id": "group",
-			"user-ids":             "users",
+			"chat-id":  "conversation-id",
+			"user-ids": "users",
 		},
-		Blocked: []string{"at-user-ids", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "staff-id", "target", "uid", "userid"},
+		Blocked: []string{"at-user-ids", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "staff-id", "target", "uid", "userid"},
 	},
 	{
 		CLIPath: "chat group set-history",
 		Aliases: map[string]string{
-			"chat":                 "group",
-			"chat-id":              "group",
-			"conversation-id":      "group",
-			"open-conversation-id": "group",
+			"chat-id": "conversation-id",
 		},
-		Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target"},
+		Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"},
 	},
 	{
 		CLIPath: "chat group share-invite",
@@ -1191,151 +1152,111 @@ var generatedParamAliases = []ParamAliasEntry{
 	{
 		CLIPath: "chat group transfer-owner",
 		Aliases: map[string]string{
-			"chat":                 "group",
-			"chat-id":              "group",
-			"conversation-id":      "group",
-			"open-conversation-id": "group",
-			"staff-id":             "user",
-			"uid":                  "user",
-			"userid":               "user",
+			"chat-id":  "conversation-id",
+			"staff-id": "user",
+			"uid":      "user",
+			"userid":   "user",
 		},
-		Blocked: []string{"at-user-ids", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target", "to-user", "user-ids", "users"},
+		Blocked: []string{"at-user-ids", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target", "to-user", "user-ids", "users"},
 	},
 	{
 		CLIPath: "chat group update-alias",
 		Aliases: map[string]string{
-			"chat":                 "group",
-			"chat-id":              "group",
-			"conversation-id":      "group",
-			"open-conversation-id": "group",
-		},
-		Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target"},
-	},
-	{
-		CLIPath: "chat group update-icon",
-		Aliases: map[string]string{
-			"chat":                 "group",
-			"chat-id":              "group",
-			"conversation-id":      "group",
-			"open-conversation-id": "group",
-		},
-		Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target"},
-	},
-	{
-		CLIPath: "chat group update-nick",
-		Aliases: map[string]string{
-			"chat":                 "group",
-			"chat-id":              "group",
-			"conversation-id":      "group",
-			"open-conversation-id": "group",
-		},
-		Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target"},
-	},
-	{
-		CLIPath: "chat group update-settings",
-		Aliases: map[string]string{
-			"chat":                 "group",
-			"chat-id":              "group",
-			"conversation-id":      "group",
-			"open-conversation-id": "group",
-		},
-		Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target"},
-	},
-	{
-		CLIPath: "chat group-mute",
-		Aliases: map[string]string{
-			"chat-id":              "group",
-			"open-conversation-id": "group",
+			"chat-id": "conversation-id",
 		},
 		Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"},
 	},
+	{
+		CLIPath: "chat group update-icon",
+		Aliases: map[string]string{
+			"chat-id": "conversation-id",
+		},
+		Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"},
+	},
+	{
+		CLIPath: "chat group update-nick",
+		Aliases: map[string]string{
+			"chat-id": "conversation-id",
+		},
+		Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"},
+	},
+	{
+		CLIPath: "chat group update-settings",
+		Aliases: map[string]string{
+			"chat-id": "conversation-id",
+		},
+		Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"},
+	},
+	{
+		CLIPath:   "chat group-mute",
+		Blocked:   []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"},
+		Ambiguous: []string{"chat-id", "open-conversation-id"},
+	},
 	{
 		CLIPath: "chat group-mute-member",
 		Aliases: map[string]string{
-			"chat-id":              "group",
-			"open-conversation-id": "group",
-			"user-ids":             "users",
+			"user-ids": "users",
 		},
-		Blocked: []string{"at-user-ids", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "staff-id", "target", "uid", "userid"},
+		Blocked:   []string{"at-user-ids", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "staff-id", "target", "uid", "userid"},
+		Ambiguous: []string{"chat-id", "open-conversation-id"},
 	},
 	{
 		CLIPath: "chat group-role add",
 		Aliases: map[string]string{
-			"chat":                 "group",
-			"chat-id":              "group",
-			"conversation-id":      "group",
-			"open-conversation-id": "group",
+			"chat-id": "conversation-id",
 		},
-		Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "open-conversation-ids", "source", "src-conversation-id", "target"},
+		Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "open-conversation-ids", "source", "src-conversation-id", "target"},
 	},
 	{
 		CLIPath: "chat group-role list",
 		Aliases: map[string]string{
-			"chat":                 "group",
-			"chat-id":              "group",
-			"conversation-id":      "group",
-			"open-conversation-id": "group",
+			"chat-id": "conversation-id",
 		},
-		Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target"},
+		Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"},
 	},
 	{
 		CLIPath: "chat group-role query-user",
 		Aliases: map[string]string{
-			"chat":                 "group",
-			"chat-id":              "group",
-			"conversation-id":      "group",
-			"open-conversation-id": "group",
-			"staff-id":             "user",
-			"uid":                  "user",
-			"userid":               "user",
+			"chat-id":  "conversation-id",
+			"staff-id": "user",
+			"uid":      "user",
+			"userid":   "user",
 		},
-		Blocked: []string{"at-user-ids", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target", "to-user", "user-ids", "users"},
+		Blocked: []string{"at-user-ids", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target", "to-user", "user-ids", "users"},
 	},
 	{
 		CLIPath: "chat group-role remove",
 		Aliases: map[string]string{
-			"chat":                 "group",
-			"chat-id":              "group",
-			"conversation-id":      "group",
-			"open-conversation-id": "group",
+			"chat-id": "conversation-id",
 		},
-		Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "role-ids", "source", "src-conversation-id", "target"},
+		Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "role-ids", "source", "src-conversation-id", "target"},
 	},
 	{
 		CLIPath: "chat group-role remove-user",
 		Aliases: map[string]string{
-			"chat":                 "group",
-			"chat-id":              "group",
-			"conversation-id":      "group",
-			"open-conversation-id": "group",
-			"staff-id":             "user",
-			"uid":                  "user",
-			"userid":               "user",
+			"chat-id":  "conversation-id",
+			"staff-id": "user",
+			"uid":      "user",
+			"userid":   "user",
 		},
-		Blocked: []string{"at-user-ids", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "role-id", "source", "src-conversation-id", "target", "to-user", "user-ids", "users"},
+		Blocked: []string{"at-user-ids", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "role-id", "source", "src-conversation-id", "target", "to-user", "user-ids", "users"},
 	},
 	{
 		CLIPath: "chat group-role set-user",
 		Aliases: map[string]string{
-			"chat":                 "group",
-			"chat-id":              "group",
-			"conversation-id":      "group",
-			"open-conversation-id": "group",
-			"staff-id":             "user",
-			"uid":                  "user",
-			"userid":               "user",
+			"chat-id":  "conversation-id",
+			"staff-id": "user",
+			"uid":      "user",
+			"userid":   "user",
 		},
-		Blocked: []string{"at-user-ids", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "role-id", "source", "src-conversation-id", "target", "to-user", "user-ids", "users"},
+		Blocked: []string{"at-user-ids", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "role-id", "source", "src-conversation-id", "target", "to-user", "user-ids", "users"},
 	},
 	{
 		CLIPath: "chat group-role update",
 		Aliases: map[string]string{
-			"chat":                 "group",
-			"chat-id":              "group",
-			"conversation-id":      "group",
-			"open-conversation-id": "group",
+			"chat-id": "conversation-id",
 		},
-		Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "open-conversation-ids", "role-ids", "source", "src-conversation-id", "target"},
+		Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "open-conversation-ids", "role-ids", "source", "src-conversation-id", "target"},
 	},
 	{
 		CLIPath: "chat hide",
@@ -1369,12 +1290,10 @@ var generatedParamAliases = []ParamAliasEntry{
 	{
 		CLIPath: "chat message add-emoji",
 		Aliases: map[string]string{
-			"chat-id":              "conversation-id",
-			"message-id":           "msg-id",
-			"open-conversation-id": "conversation-id",
-			"open-message-id":      "msg-id",
+			"chat-id": "conversation-id",
 		},
-		Blocked: []string{"conversation-ids", "group-id", "group-ids", "message-ids", "msg-ids", "open-conversation-ids", "open-message-ids", "open-task-id", "ref-msg-id", "resource-id", "src-msg-id", "topic-id"},
+		Blocked:   []string{"conversation-ids", "group-id", "group-ids", "message-ids", "msg-ids", "open-conversation-ids", "open-message-ids", "open-task-id", "ref-msg-id", "resource-id", "src-msg-id", "topic-id"},
+		Ambiguous: []string{"open-message-id"},
 	},
 	{
 		CLIPath: "chat message add-favorite",
@@ -1391,12 +1310,10 @@ var generatedParamAliases = []ParamAliasEntry{
 	{
 		CLIPath: "chat message add-text-emotion",
 		Aliases: map[string]string{
-			"chat-id":              "conversation-id",
-			"message-id":           "msg-id",
-			"open-conversation-id": "conversation-id",
-			"open-message-id":      "msg-id",
+			"chat-id": "conversation-id",
 		},
-		Blocked: []string{"conversation-ids", "group-id", "group-ids", "message-ids", "msg-ids", "open-conversation-ids", "open-message-ids", "open-task-id", "ref-msg-id", "resource-id", "src-msg-id", "topic-id"},
+		Blocked:   []string{"conversation-ids", "group-id", "group-ids", "message-ids", "msg-ids", "open-conversation-ids", "open-message-ids", "open-task-id", "ref-msg-id", "resource-id", "src-msg-id", "topic-id"},
+		Ambiguous: []string{"open-message-id"},
 	},
 	{
 		CLIPath: "chat message combine-forward",
@@ -1427,8 +1344,6 @@ var generatedParamAliases = []ParamAliasEntry{
 		Aliases: map[string]string{
 			"dest-open-cid":               "dest-conversation-id",
 			"destination-conversation-id": "dest-conversation-id",
-			"message-id":                  "msg-id",
-			"open-message-id":             "msg-id",
 			"source-conversation-id":      "src-conversation-id",
 			"src-open-cid":                "src-conversation-id",
 			"target-conversation-id":      "dest-conversation-id",
@@ -1453,21 +1368,20 @@ var generatedParamAliases = []ParamAliasEntry{
 	{
 		CLIPath: "chat message list",
 		Aliases: map[string]string{
-			"chat-id":              "group",
-			"max-result":           "limit",
-			"max-results":          "limit",
-			"open-conversation-id": "group",
-			"page-size":            "limit",
-			"per-page":             "limit",
-			"staff-id":             "user",
-			"start":                "time",
-			"take":                 "limit",
-			"top":                  "limit",
-			"uid":                  "user",
-			"user-id":              "user",
-			"userid":               "user",
+			"max-result":  "limit",
+			"max-results": "limit",
+			"page-size":   "limit",
+			"per-page":    "limit",
+			"staff-id":    "user",
+			"start":       "time",
+			"take":        "limit",
+			"top":         "limit",
+			"uid":         "user",
+			"user-id":     "user",
+			"userid":      "user",
 		},
-		Blocked: []string{"at-user-ids", "conversation-ids", "count", "cursor", "dest-conversation-id", "end", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "page", "source", "src-conversation-id", "target", "to-user", "user-ids", "users"},
+		Blocked:   []string{"at-user-ids", "conversation-ids", "count", "cursor", "dest-conversation-id", "end", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "page", "source", "src-conversation-id", "target", "to-user", "user-ids", "users"},
+		Ambiguous: []string{"chat-id", "open-conversation-id"},
 	},
 	{
 		CLIPath: "chat message list-all",
@@ -1514,12 +1428,9 @@ var generatedParamAliases = []ParamAliasEntry{
 		},
 	},
 	{
-		CLIPath: "chat message list-mentions",
-		Aliases: map[string]string{
-			"chat-id":              "group",
-			"open-conversation-id": "group",
-		},
-		Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"},
+		CLIPath:   "chat message list-mentions",
+		Blocked:   []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"},
+		Ambiguous: []string{"chat-id", "open-conversation-id"},
 	},
 	{
 		CLIPath: "chat message list-pin-msg",
@@ -1534,8 +1445,7 @@ var generatedParamAliases = []ParamAliasEntry{
 	{
 		CLIPath: "chat message list-topic-replies",
 		Aliases: map[string]string{
-			"chat-id":              "group",
-			"open-conversation-id": "group",
+			"chat-id": "conversation-id",
 		},
 		Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"},
 	},
@@ -1549,11 +1459,10 @@ var generatedParamAliases = []ParamAliasEntry{
 	{
 		CLIPath: "chat message read-status",
 		Aliases: map[string]string{
-			"chat-id":              "conversation-id",
-			"msg-id":               "message-id",
-			"open-conversation-id": "conversation-id",
-			"open-message-id":      "message-id",
-			"user-ids":             "users",
+			"chat-id":         "conversation-id",
+			"msg-id":          "message-id",
+			"open-message-id": "message-id",
+			"user-ids":        "users",
 		},
 		Blocked: []string{"at-user-ids", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "message-ids", "msg-ids", "name", "open-conversation-ids", "open-message-ids", "open-task-id", "ref-msg-id", "resource-id", "source", "src-conversation-id", "src-msg-id", "staff-id", "target", "topic-id", "uid", "userid"},
 	},
@@ -1561,30 +1470,25 @@ var generatedParamAliases = []ParamAliasEntry{
 		CLIPath: "chat message recall",
 		Aliases: map[string]string{
 			"chat-id":              "conversation-id",
-			"message-id":           "msg-id",
 			"open-conversation-id": "conversation-id",
-			"open-message-id":      "msg-id",
 		},
 		Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "message-ids", "msg-ids", "name", "open-conversation-ids", "open-message-ids", "open-task-id", "ref-msg-id", "resource-id", "source", "src-conversation-id", "src-msg-id", "target", "topic-id"},
 	},
 	{
 		CLIPath: "chat message recall-by-bot",
 		Aliases: map[string]string{
-			"chat-id":              "group",
-			"open-conversation-id": "group",
-			"robot":                "robot-code",
+			"robot": "robot-code",
 		},
-		Blocked: []string{"bot-code", "bot-id", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-bot-id", "open-conversation-ids", "robot-id", "source", "src-conversation-id", "target"},
+		Blocked:   []string{"bot-code", "bot-id", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-bot-id", "open-conversation-ids", "robot-id", "source", "src-conversation-id", "target"},
+		Ambiguous: []string{"chat-id", "open-conversation-id"},
 	},
 	{
 		CLIPath: "chat message remove-emoji",
 		Aliases: map[string]string{
-			"chat-id":              "conversation-id",
-			"message-id":           "msg-id",
-			"open-conversation-id": "conversation-id",
-			"open-message-id":      "msg-id",
+			"chat-id": "conversation-id",
 		},
-		Blocked: []string{"conversation-ids", "group-id", "group-ids", "message-ids", "msg-ids", "open-conversation-ids", "open-message-ids", "open-task-id", "ref-msg-id", "resource-id", "src-msg-id", "topic-id"},
+		Blocked:   []string{"conversation-ids", "group-id", "group-ids", "message-ids", "msg-ids", "open-conversation-ids", "open-message-ids", "open-task-id", "ref-msg-id", "resource-id", "src-msg-id", "topic-id"},
+		Ambiguous: []string{"open-message-id"},
 	},
 	{
 		CLIPath: "chat message remove-favorite",
@@ -1601,12 +1505,10 @@ var generatedParamAliases = []ParamAliasEntry{
 	{
 		CLIPath: "chat message remove-text-emotion",
 		Aliases: map[string]string{
-			"chat-id":              "conversation-id",
-			"message-id":           "msg-id",
-			"open-conversation-id": "conversation-id",
-			"open-message-id":      "msg-id",
+			"chat-id": "conversation-id",
 		},
-		Blocked: []string{"conversation-ids", "group-id", "group-ids", "message-ids", "msg-ids", "open-conversation-ids", "open-message-ids", "open-task-id", "ref-msg-id", "resource-id", "src-msg-id", "topic-id"},
+		Blocked:   []string{"conversation-ids", "group-id", "group-ids", "message-ids", "msg-ids", "open-conversation-ids", "open-message-ids", "open-task-id", "ref-msg-id", "resource-id", "src-msg-id", "topic-id"},
+		Ambiguous: []string{"open-message-id"},
 	},
 	{
 		CLIPath: "chat message reply",
@@ -1620,12 +1522,9 @@ var generatedParamAliases = []ParamAliasEntry{
 		Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "message-id", "msg-id", "msg-ids", "name", "open-conversation-ids", "open-message-id", "source", "src-conversation-id", "src-msg-id", "staff-id", "target", "uid", "user", "user-id", "userid"},
 	},
 	{
-		CLIPath: "chat message search",
-		Aliases: map[string]string{
-			"chat-id":              "group",
-			"open-conversation-id": "group",
-		},
-		Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"},
+		CLIPath:   "chat message search",
+		Blocked:   []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"},
+		Ambiguous: []string{"chat-id", "open-conversation-id"},
 	},
 	{
 		CLIPath: "chat message search-advanced",
@@ -1638,28 +1537,25 @@ var generatedParamAliases = []ParamAliasEntry{
 	{
 		CLIPath: "chat message send",
 		Aliases: map[string]string{
-			"chat-id":              "group",
-			"file":                 "file-path",
-			"open-conversation-id": "group",
-			"staff-id":             "user",
-			"to-user":              "user",
-			"uid":                  "user",
-			"user-id":              "user",
-			"userid":               "user",
+			"file":     "file-path",
+			"staff-id": "user",
+			"to-user":  "user",
+			"uid":      "user",
+			"user-id":  "user",
+			"userid":   "user",
 		},
-		Blocked: []string{"at-user-ids", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target", "user-ids", "users"},
+		Blocked:   []string{"at-user-ids", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target", "user-ids", "users"},
+		Ambiguous: []string{"chat-id", "open-conversation-id"},
 	},
 	{
 		CLIPath: "chat message send-by-bot",
 		Aliases: map[string]string{
-			"at-users":             "at-user-ids",
-			"chat-id":              "group",
-			"open-conversation-id": "group",
-			"robot":                "robot-code",
-			"user-ids":             "users",
+			"at-users": "at-user-ids",
+			"robot":    "robot-code",
+			"user-ids": "users",
 		},
 		Blocked:   []string{"bot-code", "bot-id", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-bot-id", "open-conversation-ids", "robot-id", "source", "src-conversation-id", "staff-id", "target", "to-user-id", "uid", "user", "user-id", "userid"},
-		Ambiguous: []string{"at-ids"},
+		Ambiguous: []string{"at-ids", "chat-id", "open-conversation-id"},
 	},
 	{
 		CLIPath: "chat message send-by-webhook",
@@ -1668,14 +1564,9 @@ var generatedParamAliases = []ParamAliasEntry{
 		},
 	},
 	{
-		CLIPath: "chat message send-card",
-		Aliases: map[string]string{
-			"chat":                 "group",
-			"chat-id":              "group",
-			"conversation-id":      "group",
-			"open-conversation-id": "group",
-		},
-		Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "staff-id", "target", "uid", "user", "user-id", "userid"},
+		CLIPath:   "chat message send-card",
+		Blocked:   []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "staff-id", "target", "uid", "user", "user-id", "userid"},
+		Ambiguous: []string{"chat", "chat-id", "open-conversation-id"},
 	},
 	{
 		CLIPath: "chat message set-pin-msg",
@@ -1684,8 +1575,6 @@ var generatedParamAliases = []ParamAliasEntry{
 			"chat-id":         "open-conversation-id",
 			"conversation-id": "open-conversation-id",
 			"group":           "open-conversation-id",
-			"message-id":      "msg-id",
-			"open-message-id": "msg-id",
 		},
 		Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "message-ids", "msg-ids", "name", "open-conversation-ids", "open-message-ids", "open-task-id", "ref-msg-id", "resource-id", "source", "src-conversation-id", "src-msg-id", "target", "topic-id"},
 	},
@@ -1696,8 +1585,6 @@ var generatedParamAliases = []ParamAliasEntry{
 			"chat-id":         "open-conversation-id",
 			"conversation-id": "open-conversation-id",
 			"group":           "open-conversation-id",
-			"message-id":      "msg-id",
-			"open-message-id": "msg-id",
 		},
 		Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "message-ids", "msg-ids", "name", "open-conversation-ids", "open-message-ids", "open-task-id", "ref-msg-id", "resource-id", "source", "src-conversation-id", "src-msg-id", "target", "topic-id"},
 	},
@@ -1708,8 +1595,6 @@ var generatedParamAliases = []ParamAliasEntry{
 			"chat-id":         "open-conversation-id",
 			"conversation-id": "open-conversation-id",
 			"group":           "open-conversation-id",
-			"message-id":      "msg-id",
-			"open-message-id": "msg-id",
 		},
 		Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "message-ids", "msg-ids", "name", "open-conversation-ids", "open-message-ids", "open-task-id", "ref-msg-id", "resource-id", "source", "src-conversation-id", "src-msg-id", "target", "topic-id"},
 	},
@@ -1720,17 +1605,13 @@ var generatedParamAliases = []ParamAliasEntry{
 			"chat-id":         "open-conversation-id",
 			"conversation-id": "open-conversation-id",
 			"group":           "open-conversation-id",
-			"message-id":      "msg-id",
-			"open-message-id": "msg-id",
 		},
 		Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "message-ids", "msg-ids", "name", "open-conversation-ids", "open-message-ids", "open-task-id", "ref-msg-id", "resource-id", "source", "src-conversation-id", "src-msg-id", "target", "topic-id"},
 	},
 	{
 		CLIPath: "chat mute",
 		Aliases: map[string]string{
-			"chat-id":              "conversation-id",
-			"group":                "conversation-id",
-			"open-conversation-id": "conversation-id",
+			"chat-id": "conversation-id",
 		},
 		Blocked: []string{"conversation-ids", "group-id", "group-ids", "open-conversation-ids"},
 	},
@@ -2548,7 +2429,7 @@ var generatedParamAliases = []ParamAliasEntry{
 			"node-id":     "node",
 			"url":         "node",
 		},
-		Blocked:   []string{"block-id", "comment-id", "comment-key", "dentry-id", "folder", "folder-id", "id", "job-id", "name", "parent-id", "revision", "role", "space-id", "task-id", "template-id", "version", "workspace", "workspace-id"},
+		Blocked:   []string{"block-id", "comment-id", "comment-key", "count", "dentry-id", "folder", "folder-id", "id", "job-id", "name", "offset", "page", "parent-id", "revision", "role", "space-id", "task-id", "template-id", "version", "workspace", "workspace-id"},
 		Ambiguous: []string{"max-result", "max-results", "next-cursor", "next-page-token", "next-token", "per-page", "size", "take", "top"},
 	},
 	{

internal/cli/param_aliases_test.go

@@ -237,6 +237,42 @@ func TestReduceLeafParamAliasesRemainingEdges(t *testing.T) {
 	})
 }
 
+func TestCrossPlatformCoverageReduceLeafParamAliasesBindExcludesRealFlags(t *testing.T) {
+	entry, problems := reduceLeafParamAliases(
+		"demo cmd",
+		realMap(realFlag{name: "id"}, realFlag{name: "name"}, realFlag{name: "query"}),
+		[]Concept{
+			{ID: "base_id", Members: []string{"base-id", "base-token"}, Excludes: []string{"keyword", "name", "query", "unsafe"}},
+			{ID: "query", Members: []string{"query", "keyword"}},
+		},
+		CommandOverride{Bind: map[string]string{"id": "base_id"}},
+	)
+	if len(problems) != 0 {
+		t.Fatalf("reduceLeafParamAliases() problems = %v", problems)
+	}
+	if entry == nil {
+		t.Fatal("reduceLeafParamAliases() entry = nil")
+	}
+	if entry.Aliases["base-id"] != "id" || entry.Aliases["base-token"] != "id" {
+		t.Fatalf("bound aliases = %#v, want base-id/base-token -> id", entry.Aliases)
+	}
+	if entry.Aliases["keyword"] != "query" {
+		t.Fatalf("query alias = %#v, want keyword -> query", entry.Aliases)
+	}
+	if containsParamAlias(entry.Blocked, "keyword") {
+		t.Fatalf("excluded alias entered blocked list: %#v", entry.Blocked)
+	}
+	if containsParamAlias(entry.Blocked, "name") {
+		t.Fatalf("real excluded flag entered blocked list: %#v", entry.Blocked)
+	}
+	if containsParamAlias(entry.Blocked, "query") {
+		t.Fatalf("claimed real excluded flag entered blocked list: %#v", entry.Blocked)
+	}
+	if !containsParamAlias(entry.Blocked, "unsafe") {
+		t.Fatalf("non-real excluded flag was not blocked: %#v", entry.Blocked)
+	}
+}
+
 func TestParamAliasEntryLookupMethods(t *testing.T) {
 	entry := ParamAliasEntry{
 		Aliases:   map[string]string{"uid": "user"},
@@ -457,6 +493,22 @@ func TestReduceLeafParamAliasesExcludesProtectFuzzyButDoNotOverrideAnotherConcep
 	}
 }
 
+func TestReduceLeafParamAliasesExcludesDoNotBlockRealFlag(t *testing.T) {
+	concepts := []Concept{
+		{ID: "single_id", Members: []string{"id", "item-id"}, Excludes: []string{"item-ids"}},
+	}
+	entry, problems := reduceLeafParamAliases("demo cmd", realMap(realFlag{name: "id"}, realFlag{name: "item-ids"}), concepts, CommandOverride{})
+	if len(problems) != 0 {
+		t.Fatalf("unexpected problems: %v", problems)
+	}
+	if entry == nil {
+		t.Fatal("expected a reduced entry")
+	}
+	if containsParamAlias(entry.Blocked, "item-ids") {
+		t.Fatalf("real exclude was blocked: %#v", entry)
+	}
+}
+
 func TestReduceLeafParamAliasesRejectsProtectionOrScopedAliasOnRealFlag(t *testing.T) {
 	real := realMap(realFlag{name: "user-id"}, realFlag{name: "user"})
 	for name, override := range map[string]CommandOverride{
@@ -472,6 +524,58 @@ func TestReduceLeafParamAliasesRejectsProtectionOrScopedAliasOnRealFlag(t *testi
 	}
 }
 
+func TestGeneratedParamAliasesBlockPluralListSpellingsOnSingleIDCommands(t *testing.T) {
+	entries := make(map[string]ParamAliasEntry, len(generatedParamAliases))
+	for _, entry := range generatedParamAliases {
+		entries[entry.CLIPath] = entry
+	}
+	assertBlocked := func(path string, names ...string) {
+		t.Helper()
+		entry, ok := entries[path]
+		if !ok {
+			t.Fatalf("missing generated alias entry for %q", path)
+		}
+		for _, name := range names {
+			if !entry.IsBlocked(cmdutil.Morph(name)) {
+				t.Fatalf("%s: %q not blocked; entry = %#v", path, name, entry)
+			}
+		}
+	}
+
+	for _, path := range []string{
+		"chat message add-emoji",
+		"chat message remove-emoji",
+		"chat message add-text-emotion",
+		"chat message remove-text-emotion",
+	} {
+		assertBlocked(path, "msg-ids", "message-ids")
+	}
+	for _, path := range []string{
+		"chat message send",
+		"chat conversation-info",
+		"chat category add-conv",
+		"chat category remove-conv",
+		"chat message list",
+		"chat message list-mentions",
+		"chat message recall-by-bot",
+		"chat message search",
+	} {
+		assertBlocked(path, "conversation-ids")
+	}
+}
+
+func TestGeneratedParamAliasesKeepAuditJoinUserRoleAmbiguous(t *testing.T) {
+	entry, ok := LookupParamAlias("chat group audit-join-validation")
+	if !ok {
+		t.Fatal("missing generated alias entry for chat group audit-join-validation")
+	}
+	for _, name := range []string{"user", "user-id", "userid", "uid", "staff-id"} {
+		if !entry.IsAmbiguous(cmdutil.Morph(name)) {
+			t.Fatalf("%q not ambiguous; entry = %#v", name, entry)
+		}
+	}
+}
+
 // TestGeneratedParamAliasesAreWellFormed guards the committed generated table
 // at the Go level, complementing the byte-identity drift gate.
 func TestGeneratedParamAliasesAreWellFormed(t *testing.T) {

internal/cli/param_concepts.json

@@ -60,11 +60,17 @@
     "chat group members": {"bind": {"id": "open_conversation_id"}},
     "chat group members add": {"bind": {"id": "open_conversation_id"}, "block": ["user-id", "open-dingtalk-id"], "note": "The real --users is a list and may contain mixed userId/openDingTalkId values; singular inputs are not promoted automatically."},
     "chat group members remove": {"bind": {"id": "open_conversation_id"}},
-    "chat message add-emoji": {"scoped_aliases": {"chat-id": "conversation-id", "open-conversation-id": "conversation-id"}, "block": ["group-id", "group-ids", "conversation-ids", "open-conversation-ids"], "note": "Native --chat/--group/--id/--conversation-id stay native; numeric groupId and list spellings are rejected."},
-    "chat message add-text-emotion": {"scoped_aliases": {"chat-id": "conversation-id", "open-conversation-id": "conversation-id"}, "block": ["group-id", "group-ids", "conversation-ids", "open-conversation-ids"], "note": "Native --chat/--group/--id/--conversation-id stay native; numeric groupId and list spellings are rejected."},
-    "chat message remove-emoji": {"scoped_aliases": {"chat-id": "conversation-id", "open-conversation-id": "conversation-id"}, "block": ["group-id", "group-ids", "conversation-ids", "open-conversation-ids"], "note": "Native --chat/--group/--id/--conversation-id stay native; numeric groupId and list spellings are rejected."},
-    "chat message remove-text-emotion": {"scoped_aliases": {"chat-id": "conversation-id", "open-conversation-id": "conversation-id"}, "block": ["group-id", "group-ids", "conversation-ids", "open-conversation-ids"], "note": "Native --chat/--group/--id/--conversation-id stay native; numeric groupId and list spellings are rejected."},
-    "chat mute": {"scoped_aliases": {"group": "conversation-id", "chat-id": "conversation-id", "open-conversation-id": "conversation-id"}, "block": ["group-id", "group-ids", "conversation-ids", "open-conversation-ids"], "note": "Native --conversation-id/--id/--chat remain unchanged; other reviewed openConversationId spellings reduce to --conversation-id."},
+    "chat conversation-info": {"ambiguous": ["chat-id", "open-conversation-id"], "note": "Visible --conversation-id and legacy --group both remain executable outside the approved hidden-alias migration set."},
+    "chat group-mute": {"ambiguous": ["chat-id", "open-conversation-id"], "note": "Visible --conversation-id and legacy --group both remain executable outside the approved hidden-alias migration set."},
+    "chat group-mute-member": {"ambiguous": ["chat-id", "open-conversation-id"], "note": "Visible --conversation-id and legacy --group both remain executable outside the approved hidden-alias migration set."},
+    "chat message add-emoji": {"scoped_aliases": {"chat-id": "conversation-id"}, "block": ["group-id", "group-ids", "conversation-ids", "open-conversation-ids"], "ambiguous": ["open-message-id"], "note": "Native --chat/--group/--id/--conversation-id/--open-conversation-id and visible --message-id/--msg-id stay executable; numeric/list spellings are rejected."},
+    "chat message add-text-emotion": {"scoped_aliases": {"chat-id": "conversation-id"}, "block": ["group-id", "group-ids", "conversation-ids", "open-conversation-ids"], "ambiguous": ["open-message-id"], "note": "Native --chat/--group/--id/--conversation-id/--open-conversation-id and visible --message-id/--msg-id stay executable; numeric/list spellings are rejected."},
+    "chat message list-mentions": {"ambiguous": ["chat-id", "open-conversation-id"], "note": "Visible --conversation-id and legacy --group both remain executable outside the approved hidden-alias migration set."},
+    "chat message recall-by-bot": {"ambiguous": ["chat-id", "open-conversation-id"], "note": "Visible --conversation-id and legacy --group both remain executable outside the approved hidden-alias migration set."},
+    "chat message remove-emoji": {"scoped_aliases": {"chat-id": "conversation-id"}, "block": ["group-id", "group-ids", "conversation-ids", "open-conversation-ids"], "ambiguous": ["open-message-id"], "note": "Native --chat/--group/--id/--conversation-id/--open-conversation-id and visible --message-id/--msg-id stay executable; numeric/list spellings are rejected."},
+    "chat message remove-text-emotion": {"scoped_aliases": {"chat-id": "conversation-id"}, "block": ["group-id", "group-ids", "conversation-ids", "open-conversation-ids"], "ambiguous": ["open-message-id"], "note": "Native --chat/--group/--id/--conversation-id/--open-conversation-id and visible --message-id/--msg-id stay executable; numeric/list spellings are rejected."},
+    "chat message search": {"ambiguous": ["chat-id", "open-conversation-id"], "note": "Visible --conversation-id and legacy --group both remain executable outside the approved hidden-alias migration set."},
+    "chat mute": {"scoped_aliases": {"chat-id": "conversation-id"}, "block": ["group-id", "group-ids", "conversation-ids", "open-conversation-ids"], "note": "Native --conversation-id and hidden compatibility --group/--id/--chat/--open-conversation-id remain unchanged; reviewed chat-id reduces to --conversation-id."},
     "drive list": {"ambiguous": ["root-id", "space"], "note": "Numeric --space-id and knowledge-base --workspace are distinct routes; bare --space/--root-id cannot select a domain or folder.", "scoped_aliases": {"document-id": "node", "dentry-uuid": "node", "directory-id": "folder", "order-field": "order-by", "sort-by": "order-by", "sort-field": "order-by"}, "scope_strict": true, "block": ["dentry-id"]},
     "drive upload": {"ambiguous": ["destination-id", "space", "target-id"], "note": "Local file, display name, MIME, overwrite node, folder, storage space, and knowledge-base workspace remain distinct roles.", "scoped_aliases": {"dentry-uuid": "node", "directory-id": "folder", "overwrite-node-id": "node", "target-folder-id": "folder", "target-workspace-id": "workspace", "source-file": "file", "content-type": "mime-type", "filename": "file-name", "name": "file-name", "display-name": "file-name", "upload-name": "file-name"}, "block": ["dentry-id", "document-url", "output-path"], "scope_strict": true},
     "ding +receiver-status": {"scoped_aliases": {"id": "ding-id"}, "note": "generic id reduces to ding-id"},
@@ -84,12 +90,12 @@
     "chat +unread-chats": {"scoped_aliases": {"limit": "count", "size": "count"}, "scope_strict": true, "note": "On this exact command, limit and size both denote the returned unread-conversation count."},
     "chat message list-unread-conversations": {"scoped_aliases": {"limit": "count", "size": "count"}, "scope_strict": true, "note": "On this exact command, limit and size both denote the returned unread-conversation count."},
     "chat +messages-list-direct": {"scoped_aliases": {"start": "time"}, "block": ["end"], "scope_strict": true, "note": "This exact command accepts one start boundary in yyyy-MM-dd HH:mm:ss; an end-only input cannot be represented."},
-    "chat message list": {"scoped_aliases": {"start": "time"}, "block": ["end"], "scope_strict": true, "note": "This exact command accepts one start boundary in yyyy-MM-dd HH:mm:ss; an end-only input cannot be represented."},
+    "chat message list": {"scoped_aliases": {"start": "time"}, "block": ["end"], "ambiguous": ["chat-id", "open-conversation-id"], "scope_strict": true, "note": "This exact command accepts one start boundary in yyyy-MM-dd HH:mm:ss; an end-only input cannot be represented. Visible --conversation-id and legacy --group both remain executable outside the approved hidden-alias migration set."},
     "chat message list-by-sender": {"scoped_aliases": {"user-id": "sender-user-id", "open-dingtalk-id": "sender-open-dingtalk-id"}, "block": ["time"], "scope_strict": true, "note": "Only same-role sender identifiers are mapped; --time cannot supply the required RFC3339 start/end range."},
     "contact +resolve-dept": {"bind": {"name": "search_query"}, "note": "The real --name is a department-name search keyword and carries the search_query concept on this shortcut."},
     "contact +list-sub-depts": {"block": ["name", "query"], "note": "--dept is an integer department id; names and search queries require a separate resolution command"},
     "contact +dept-members": {"bind": {"dept": "search_query"}, "scoped_aliases": {"name": "dept"}, "note": "The real --dept is a department-name search keyword; search spellings come from search_query, while --name remains command-scoped."},
-    "chat message send": {"scoped_aliases": {"to-user": "user", "file": "file-path"}, "note": "Recipient and local-file-path aliases are exact to this command; obsolete file metadata flags remain unsupported."},
+    "chat message send": {"scoped_aliases": {"to-user": "user", "file": "file-path"}, "ambiguous": ["chat-id", "open-conversation-id"], "note": "Recipient and local-file-path aliases are exact to this command; obsolete file metadata flags remain unsupported. Visible --conversation-id and legacy --group both remain executable outside the approved hidden-alias migration set."},
     "chat +group-members": {"bind": {"group": "group_name"}, "note": "The real --group is a group-name search keyword on this shortcut, not an identifier."},
     "chat +category-create": {"scoped_aliases": {"name": "title"}, "scope_strict": true, "note": "The reviewed name/title mapping preserves the category display-name value on this exact shortcut."},
     "chat category create": {"scoped_aliases": {"name": "title"}, "scope_strict": true, "note": "The reviewed name/title mapping preserves the category display-name value on this exact command."},
@@ -98,8 +104,8 @@
     "chat +category-delete": {"block": ["category-ids"], "note": "This command requires one category id; list cardinality is not reduced automatically."},
     "chat category delete": {"block": ["category-ids"], "note": "This command requires one category id; list cardinality is not reduced automatically."},
     "chat category list-conversations": {"block": ["category-ids"], "note": "This command requires one category id; list cardinality is not reduced automatically."},
-    "chat category add-conv": {"block": ["category-id"], "note": "This command requires a category-id list; one id is not promoted into a batch input."},
-    "chat category remove-conv": {"block": ["category-id"], "note": "This command requires a category-id list; one id is not promoted into a batch input."},
+    "chat category add-conv": {"block": ["category-id"], "ambiguous": ["chat", "chat-id", "open-conversation-id"], "note": "This command requires a category-id list; one id is not promoted into a batch input. Visible --conversation-id and legacy --group both remain executable outside the approved hidden-alias migration set."},
+    "chat category remove-conv": {"block": ["category-id"], "ambiguous": ["chat", "chat-id", "open-conversation-id"], "note": "This command requires a category-id list; one id is not promoted into a batch input. Visible --conversation-id and legacy --group both remain executable outside the approved hidden-alias migration set."},
     "chat +chat-role-update": {"block": ["role-ids"], "note": "This command requires one role id; list cardinality is not reduced automatically."},
     "chat group-role remove": {"block": ["role-ids"], "note": "This command requires one role id; list cardinality is not reduced automatically."},
     "chat group-role update": {"block": ["role-ids"], "note": "This command requires one role id; list cardinality is not reduced automatically."},
@@ -109,7 +115,7 @@
     "chat +messages-send-by-webhook": {"scoped_aliases": {"at-user-ids": "at-users"}, "scope_strict": true, "note": "Both names denote the same userId list used for @ mentions on this exact shortcut."},
     "chat message send-by-webhook": {"scoped_aliases": {"at-user-ids": "at-users"}, "scope_strict": true, "note": "Both names denote the same userId list used for @ mentions on this exact command."},
     "doc block insert": {"block": ["before-block-id"], "note": "Parent and reference roles remain distinct. --before-block-id needs both --ref-block and --where before, while role-free --block-id cannot choose parent versus reference.", "scoped_aliases": {"parent-block-id": "parent-block", "ref-block-id": "ref-block", "reference-block-id": "ref-block"}, "ambiguous": ["block-id"], "scope_strict": true},
-    "chat message send-by-bot": {"scoped_aliases": {"at-users": "at-user-ids"}, "block": ["user-id", "to-user-id"], "ambiguous": ["at-ids"], "note": "The reviewed @ userId-list alias is exact; singular recipients are not promoted, and bare --at-ids cannot choose an identifier domain."},
+    "chat message send-by-bot": {"scoped_aliases": {"at-users": "at-user-ids"}, "block": ["user-id", "to-user-id"], "ambiguous": ["at-ids", "chat-id", "open-conversation-id"], "note": "The reviewed @ userId-list alias is exact; singular recipients are not promoted, and bare --at-ids cannot choose an identifier domain. Visible --conversation-id and legacy --group both remain executable outside the approved hidden-alias migration set."},
     "doc +export-get": {"block": ["doc-id", "document-id", "file-id", "node", "node-id", "task-id", "url"], "note": "This command queries one export jobId. Document node identifiers and import taskId spellings are different entities and are rejected.", "scoped_aliases": {"export-job-id": "job-id"}, "scope_strict": true},
     "doc block delete": {"block": ["index"], "note": "index (position) vs node (node id) are different"},
     "doc +copy": {"scoped_aliases": {"folder-id": "folder", "parent-folder": "folder", "parent-folder-id": "folder", "parent-node-id": "folder", "space": "workspace", "space-id": "workspace"}, "block": ["parent-id"], "scope_strict": true, "note": "This exact Doc command expects a Doc folder nodeId/dentryUuid/URL. Reviewed folder spellings preserve that value; generic --parent-id stays blocked because it may carry a numeric Drive dentryId. The command-scoped --space/--space-id aliases preserve the compatibility published before workspace and numeric DingDrive storage-space concepts were split; they do not make those value domains globally equivalent."},
@@ -142,7 +148,7 @@
     "chat category create-smart": {"bind": {"members": "open_dingtalk_ids"}, "scoped_aliases": {"title": "name"}, "note": "The real --members is an openDingTalkId list; the reviewed title/name alias is exact to the category display name."},
     "chat group audit-join-validation": {"ambiguous": ["user", "user-id", "userid", "uid", "staff-id"], "note": "A role-free user identifier cannot choose between the required --applicant and --inviter roles."},
     "chat message reply": {"block": ["user", "user-id", "userid", "uid", "staff-id"], "note": "The required --ref-sender is a role-specific openDingTalkId and must not accept generic userId spellings."},
-    "chat message send-card": {"block": ["user", "user-id", "userid", "uid", "staff-id"], "note": "The real --receiver is a role-specific openDingTalkId and must not accept generic userId spellings."},
+    "chat message send-card": {"block": ["user", "user-id", "userid", "uid", "staff-id"], "ambiguous": ["chat", "chat-id", "open-conversation-id"], "note": "The real --receiver is a role-specific openDingTalkId and must not accept generic userId spellings. Visible --conversation-id and legacy --group both remain executable outside the approved hidden-alias migration set."},
     "chat +category-add-conversation": {"block": ["category-id"], "note": "The real --category-ids is a list; a singular category ID is not promoted automatically."},
     "chat +category-list-conversations": {"block": ["category-ids"], "note": "The real --category-id is singular; list cardinality is not reduced automatically."},
     "chat +category-remove-conversation": {"block": ["category-id"], "note": "The real --category-ids is a list; a singular category ID is not promoted automatically."},
@@ -328,7 +334,7 @@
       {"command": "chat group rename", "emitted": "conversation-id", "expect": "id", "via": "concept:open_conversation_id+bind"},
       {"command": "chat group rename", "emitted": "group-id", "expect": "did-you-mean:blocked", "via": "guard:group-id-vs-open-conversation-id"},
       {"command": "chat message send", "emitted": "conversation-id", "expect": "group", "via": "concept:open_conversation_id"},
-      {"command": "chat message add-emoji", "emitted": "open-conversation-id", "expect": "conversation-id", "via": "override:scoped"},
+      {"command": "chat message add-emoji", "emitted": "open-conversation-id", "expect": "conversation-id", "via": "concept:open_conversation_id"},
       {"command": "chat message add-emoji", "emitted": "group-id", "expect": "did-you-mean:blocked", "via": "guard:group-id-vs-open-conversation-id"},
       {"command": "chat +group-members", "emitted": "conversation-id", "expect": "did-you-mean:blocked", "via": "guard:group-name-vs-open-conversation-id"},
       {"command": "chat +send-to-group", "emitted": "group-name", "expect": "group", "via": "concept:group_name+bind"},
@@ -466,6 +472,7 @@
       {"command": "chat +flag-create", "emitted": "group", "expect": "conversation-id", "via": "concept:open_conversation_id"},
       {"command": "chat +chat-add-bot", "emitted": "conversation-id", "expect": "id", "via": "concept:open_conversation_id+bind"},
       {"command": "chat +chat-add-bot", "emitted": "robot", "expect": "robot-code", "via": "concept:robot_code"},
+      {"command": "chat group audit-join-validation", "emitted": "user", "expect": "did-you-mean:ambiguous", "via": "guard:applicant-vs-inviter-role"},
       {"command": "chat +chat-audit-join", "emitted": "applicant-user-id", "expect": "applicant", "via": "override:scoped-user-role"},
       {"command": "chat +chat-audit-join", "emitted": "user-id", "expect": "did-you-mean:ambiguous", "via": "guard:applicant-vs-inviter-role"},
       {"command": "chat +chat-create", "emitted": "user-id", "expect": "did-you-mean:blocked", "via": "guard:single-vs-list"},

internal/cli/schema_catalog_test.go

@@ -1354,16 +1354,16 @@ func TestDeliveryCatalogChatParamDeclsFrom87910880Reviewed(t *testing.T) {
 		interfaceType string
 	}{
 		{"chat message edit", "conversation-id", "openConversationId", true, ""},
-		{"chat message edit", "msg-id", "openMessageId", true, ""},
+		{"chat message edit", "message-id", "openMessageId", true, ""},
 		{"chat message edit", "at-open-dingtalk-ids", "atOpenDingTalkIds", false, "array"},
+		{"chat message update-text-emotion", "message-id", "openMsgId", true, ""},
 		{"chat message send", "idempotency-key", "uuid", false, ""},
 		{"chat message send-card", "at-all", "atAll", false, ""},
 		{"chat message send-card", "at-open-dingtalk-ids", "atOpenDingTalkIds", false, "array"},
-		{"chat message update-text-emotion", "msg-id", "openMsgId", true, ""},
 		{"chat message update-text-emotion", "old-emotion-id", "oldEmotionId", true, ""},
 		{"chat category batch-info", "category-ids", "categoryIds", true, "array"},
-		{"chat category list-by-conv", "group", "openConversationId", true, ""},
-		{"chat group update-nick", "group", "openConversationId", true, ""},
+		{"chat category list-by-conv", "conversation-id", "openConversationId", true, ""},
+		{"chat group update-nick", "conversation-id", "", true, ""},
 		{"chat group upgrade-to-external", "extension", "extension", false, "object"},
 		{"chat +messages-send-card", "receiver-open-dingtalk-id", "receiverOpenDingTalkId", false, ""},
 		{"chat message list-favorites", "size", "", false, "string"},
@@ -1397,7 +1397,8 @@ func TestDeliveryCatalogChatParamDeclsFrom87910880Reviewed(t *testing.T) {
 		}
 	}
 
-	// Hidden conversation aliases must stay unpublished (merge-base parity).
+	// Manifest-covered migrations hide legacy aliases; manifest-external
+	// commands keep their existing visible flags for compatibility.
 	editLeaf, err := queryDeliverySchemaPayload([]string{"chat message edit"})
 	if err != nil {
 		t.Fatal(err)
@@ -1421,9 +1422,52 @@ func TestDeliveryCatalogChatParamDeclsFrom87910880Reviewed(t *testing.T) {
 		t.Fatal(err)
 	}
 	listParams := schemaMap(listByConv["parameters"])
-	for _, hidden := range []string{"conversation-id", "id"} {
-		if _, ok := listParams[hidden]; ok {
-			t.Fatalf("chat category list-by-conv unexpectedly publishes hidden alias --%s", hidden)
+	if _, ok := listParams["conversation-id"]; !ok {
+		t.Fatalf("chat category list-by-conv missing public canonical --conversation-id")
+	}
+	if _, ok := listParams["group"]; !ok {
+		t.Fatalf("chat category list-by-conv unexpectedly hides manifest-external --group")
+	}
+	if _, ok := listParams["id"]; ok {
+		t.Fatalf("chat category list-by-conv unexpectedly publishes hidden alias --id")
+	}
+
+	for _, path := range []string{
+		"chat message add-emoji",
+		"chat message remove-emoji",
+		"chat message add-text-emotion",
+		"chat message remove-text-emotion",
+	} {
+		leaf, err := queryDeliverySchemaPayload([]string{path})
+		if err != nil {
+			t.Fatal(err)
+		}
+		params := schemaMap(leaf["parameters"])
+		if _, ok := params["conversation-id"]; !ok {
+			t.Fatalf("%s missing public canonical --conversation-id", path)
+		}
+		for _, visible := range []string{"group", "id", "chat"} {
+			if _, ok := params[visible]; !ok {
+				t.Fatalf("%s unexpectedly hides manifest-external --%s", path, visible)
+			}
+		}
+	}
+
+	groupBots, err := queryDeliverySchemaPayload([]string{"chat group bots"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	groupBotsParams := schemaMap(groupBots["parameters"])
+	group := groupBotsParams["group"]
+	if group == nil {
+		t.Fatal("chat group bots missing public legacy --group")
+	}
+	if group["property"] != "openConversationId" {
+		t.Fatalf("chat group bots --group property = %#v, want openConversationId", group["property"])
+	}
+	for _, migrated := range []string{"conversation-id", "group-name"} {
+		if _, ok := groupBotsParams[migrated]; ok {
+			t.Fatalf("chat group bots unexpectedly publishes migrated --%s", migrated)
 		}
 	}
 }

internal/cli/schema_constraints_runtime.go

@@ -43,19 +43,14 @@ func init() {
 		RequireOneOf:      [][]string{{"conversation-id", "open-dingtalk-id", "user", "permParam"}},
 	})
 	registerExclusiveOneOf("chat.chat_permission_grant_cross_org_data", "target-org-id", "all")
-	registerRequireOneOf("chat.add_emoji_reaction", "conversation-id", "group", "id", "chat")
-	registerRequireOneOf("chat.add_text_emotion", "conversation-id", "group", "id", "chat")
 	registerExclusiveOneOf("chat.clear_conversation_messages", "conversation-id", "id", "chat")
 	registerExclusiveOneOf("chat.clear_conversation_red_point", "conversation-id", "id", "chat")
-	registerRequireOneOf("chat.update_text_emotion", "conversation-id", "group", "id", "chat")
 	registerExclusiveOneOf("chat.get_conversation_info", "group", "user", "open-dingtalk-id")
 	registerExclusiveOneOf("chat.hide_conversation", "conversation-id", "id", "chat")
 	registerExclusiveOneOf("chat.list_conversation_message_v2", "group", "user", "open-dingtalk-id")
 	registerExclusiveOneOf("chat.list_individual_chat_message", "user", "open-dingtalk-id")
 	registerExclusiveOneOf("chat.mark_conversation_unread", "conversation-id", "id", "chat")
 	registerExclusiveOneOf("chat.mark_message_read", "conversation-id", "id", "chat")
-	registerRequireOneOf("chat.remove_emoji_reaction", "conversation-id", "group", "id", "chat")
-	registerRequireOneOf("chat.remove_text_emotion", "conversation-id", "group", "id", "chat")
 	registerRequireOneOf("chat.send_personal_message", "text", "content", "msg-type")
 	registerExclusiveOneOf("chat.send_robot_message", "group", "users")
 	registerRequireOneOf("chat.set_group_member_mute_list", "users", "user")

internal/cli/schema_parameter_mapping_ledger.go

@@ -252,7 +252,8 @@ var reviewedSchemaParameterMappingExclusions = map[string]string{
 	"chat.batch_query_group_chat_settings --groups":                      "Reviewed unpinned adapter: chat.batch_query_group_chat_settings has no singular pinned interface_ref; --groups is a CLI wrapper input and does not publish a direct interface property.",
 	"chat.batch_update_group_chat_settings --items":                      "Reviewed unpinned adapter: chat.batch_update_group_chat_settings has no singular pinned interface_ref; --items is a CLI wrapper input and does not publish a direct interface property.",
 	"chat.create_text_emotion --background-id":                           "Runtime extension: the executable helper forwards backgroundId to im/create_text_emotion, but the pinned source-revision metadata does not declare that optional property; preserve the compatibility flag without advertising it as a pinned RPC field.",
-	"chat.get_group_mute_config --group":                                 "Reviewed unpinned adapter: chat.get_group_mute_config has no singular pinned interface_ref; --group is a CLI wrapper input and does not publish a direct interface property.",
+	"chat.get_group_mute_config --conversation-id":                       "Reviewed unpinned adapter: chat.get_group_mute_config has no singular pinned interface_ref; --conversation-id is a CLI wrapper input and does not publish a direct interface property.",
+	"chat.get_group_mute_config --group":                                 "Reviewed legacy Schema compatibility: the historical visible --group wrapper input was required but did not publish a direct interface property.",
 	"chat.list_conversation_message_v2 --open-dingtalk-id":               "selects the alternate list_individual_chat_message branch",
 	"chat.list_conversation_message_v2 --user":                           "selects the alternate list_individual_chat_message branch",
 	"chat.list_message_favorites --cursor":                               "Reviewed unpinned adapter: chat.list_message_favorites has no singular pinned interface_ref; --cursor is a CLI wrapper input and does not publish a direct interface property.",
@@ -265,6 +266,7 @@ var reviewedSchemaParameterMappingExclusions = map[string]string{
 	"chat.query_msg_read_status --users":                                 "conditional wrapper/alias of --user: parseCSVValues + appendChatIDArgs routes each supplied identifier to targetUserIds or targetOpenDingTalkIds according to its runtime ID shape; there is no single RPC property for this flag",
 	"chat.remove_message_favorite --open-conversation-id":                "Reviewed unpinned adapter: chat.remove_message_favorite has no singular pinned interface_ref; --open-conversation-id is a CLI wrapper input and does not publish a direct interface property.",
 	"chat.remove_message_favorite --open-message-id":                     "Reviewed unpinned adapter: chat.remove_message_favorite has no singular pinned interface_ref; --open-message-id is a CLI wrapper input and does not publish a direct interface property.",
+	"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",

internal/corecmd/corecmd.go

@@ -145,6 +145,15 @@ type FlagSpec struct {
 	// alike) and makes a whitespace-only value count as empty in required checks.
 	Trim bool
 
+	// Input declares extra input sources for a KindString flag beyond the
+	// literal command-line value: InputFile enables @path (value replaced by
+	// the file content), InputStdin enables - (value replaced by stdin).
+	// "@@value" always escapes to the literal "@value". Only explicit CLI
+	// tokens are resolved; EnvVar fallback and registration defaults pass
+	// through unchanged. Resolution runs before required/enum/constraint/
+	// Validate checks, so they see the payload content. Empty = flag value only.
+	Input []string
+
 	// Schema parameter final facts (embedded to dws.schema.*; assembly pass-through).
 	Enum              []string // accepted values
 	Format            string   // machine-readable format (e.g. uri)
@@ -365,6 +374,7 @@ func New(spec Spec) *cobra.Command {
 	validateDispatchDecl(spec)
 	validateSafetySpec(spec)
 	validateContractDecl(spec)
+	validateInputSpecs(spec.Use, spec.Flags)
 	// Help prose inherits the declaration when not authored separately:
 	// Selection.Examples (already contract-validated against the real flags)
 	// double as the --help Example block, keeping one authored source.
@@ -476,6 +486,11 @@ func runDeclaredPreflight(cmd *cobra.Command, args []string, spec Spec) error {
 			return err
 		}
 	}
+	// Input resolution rewrites explicit @file / stdin values in place so the
+	// required/enum/constraint/Validate stages below check the payload content.
+	if err := resolveInputFlags(cmd, spec.Flags); err != nil {
+		return err
+	}
 	if err := ValidateRequired(cmd, spec.Flags); err != nil {
 		return err
 	}
@@ -578,18 +593,7 @@ func RegisterFlags(cmd *cobra.Command, flags []FlagSpec) {
 		for _, alias := range flag.Aliases {
 			RegisterFlag(cmd, flag.Kind, alias, "", flag.Usage+" (alias)")
 			_ = cmd.Flags().MarkHidden(alias)
-			if registered := cmd.Flags().Lookup(alias); registered != nil {
-				runtimeannotate.SetFlagAnnotation(
-					registered,
-					runtimeannotate.AnnotationFlagAliasOf,
-					flag.Name,
-				)
-				runtimeannotate.SetFlagAnnotation(
-					registered,
-					runtimeannotate.AnnotationFlagAliasOrigin,
-					runtimeannotate.FlagAliasOriginCorecmdV1,
-				)
-			}
+			AnnotateFlagAlias(cmd, alias, flag.Name)
 		}
 		if flag.MarkRequired {
 			_ = cmd.MarkFlagRequired(flag.Name)
@@ -600,6 +604,30 @@ func RegisterFlags(cmd *cobra.Command, flags []FlagSpec) {
 	}
 }
 
+// AnnotateFlagAlias records framework-owned evidence that aliasName is a hidden
+// compatibility alias for canonicalName. It is for commands that already own
+// their Cobra flag registration outside FlagSpec but still need the same
+// interface-snapshot alias contract as FlagSpec.Aliases.
+func AnnotateFlagAlias(cmd *cobra.Command, aliasName, canonicalName string) {
+	if cmd == nil {
+		return
+	}
+	registered := cmd.Flags().Lookup(aliasName)
+	if registered == nil {
+		return
+	}
+	runtimeannotate.SetFlagAnnotation(
+		registered,
+		runtimeannotate.AnnotationFlagAliasOf,
+		canonicalName,
+	)
+	runtimeannotate.SetFlagAnnotation(
+		registered,
+		runtimeannotate.AnnotationFlagAliasOrigin,
+		runtimeannotate.FlagAliasOriginCorecmdV1,
+	)
+}
+
 // RegisterFlag registers one flag by Kind. Default is applied at registration
 // for every kind so --help DefValue matches the declared fallback.
 // Malformed KindInt / KindBool Default values panic at registration (fail-closed)

internal/corecmd/corecmd_test.go

@@ -116,6 +116,16 @@ func TestCrossPlatformCoverageRegisterFlagsAllKinds(t *testing.T) {
 	}
 }
 
+func TestCrossPlatformCoverageAnnotateFlagAliasIgnoresMissingInputs(t *testing.T) {
+	AnnotateFlagAlias(nil, "alias", "canonical")
+
+	cmd := newTestCommand()
+	AnnotateFlagAlias(cmd, "missing", "canonical")
+	if flag := cmd.Flags().Lookup("missing"); flag != nil {
+		t.Fatalf("unexpected missing flag registered: %#v", flag)
+	}
+}
+
 // ── effective value fallback chain ─────────────────────────────────
 
 func TestCrossPlatformCoverageEffectiveValueFallbackChain(t *testing.T) {

internal/corecmd/input.go

@@ -0,0 +1,191 @@
+// 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 corecmd
+
+import (
+	"fmt"
+	"io"
+	"os"
+	"strings"
+
+	"github.com/spf13/cobra"
+
+	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/cmdutil"
+)
+
+// FlagSpec.Input source constants. They declare extra input sources for a
+// KindString flag beyond the literal command-line value, mirroring the
+// lark-cli Flag.Input capability so large payloads (markdown, JSON, CSV)
+// never need shell quoting.
+const (
+	// InputFile allows the flag value @path to be replaced by the file content.
+	InputFile = "file"
+	// InputStdin allows the flag value - to be replaced by the stdin content.
+	InputStdin = "stdin"
+)
+
+// utf8BOM is stripped from file/stdin content so a Windows-edited payload
+// cannot corrupt the first CSV cell or break JSON parsing downstream.
+const utf8BOM = "\ufeff"
+
+// validateInputSpecs rejects malformed Input declarations at build time. Like
+// the other declaration checks this panics: a bad Input spec is a programming
+// error every test and startup path should trip immediately.
+func validateInputSpecs(use string, flags []FlagSpec) {
+	for _, flag := range flags {
+		if len(flag.Input) == 0 {
+			continue
+		}
+		if flag.Kind != KindString {
+			panic(fmt.Sprintf(
+				"command %q flag %q: Input is only supported on KindString flags",
+				use, flag.Name))
+		}
+		seen := map[string]bool{}
+		for _, source := range flag.Input {
+			if source != InputFile && source != InputStdin {
+				panic(fmt.Sprintf(
+					"command %q flag %q: unknown Input source %q (allowed: %s, %s)",
+					use, flag.Name, source, InputFile, InputStdin))
+			}
+			if seen[source] {
+				panic(fmt.Sprintf(
+					"command %q flag %q: duplicate Input source %q",
+					use, flag.Name, source))
+			}
+			seen[source] = true
+		}
+	}
+}
+
+// inputSupports reports whether the flag declared the given input source.
+func inputSupports(flag FlagSpec, source string) bool {
+	for _, s := range flag.Input {
+		if s == source {
+			return true
+		}
+	}
+	return false
+}
+
+// explicitInputFlagName picks the declared name that carries the user's
+// explicit token, mirroring rawValue's order and usability judgement exactly:
+// the main flag wins only when changed and usable (trim-judged only when
+// Trim is set), then declared aliases in order. Diverging here could rewrite
+// an alias that rawValue would shadow (or vice versa). EnvVar fallback and
+// registration defaults are never input-resolved — @file only applies to what
+// the user literally typed.
+func explicitInputFlagName(cmd *cobra.Command, flag FlagSpec) string {
+	usable := func(v string) bool {
+		if flag.Trim {
+			v = strings.TrimSpace(v)
+		}
+		return v != ""
+	}
+	for _, name := range append([]string{flag.Name}, flag.Aliases...) {
+		if cmd.Flags().Changed(name) && usable(cmdutil.MustGetFlag(cmd, name)) {
+			return name
+		}
+	}
+	return ""
+}
+
+// resolveInputFlags rewrites the explicit values of Input-declaring flags
+// before required/enum/constraint/Validate checks, so every downstream stage
+// sees the real payload content. Semantics:
+//
+//   - "-" reads stdin; a process has a single stdin, so a second Input flag
+//     using "-" in the same invocation is rejected.
+//   - "@path" reads the named file (leading/trailing whitespace trimmed).
+//   - "@@value" escapes to the literal "@value" and is not source-resolved.
+//
+// Resolution runs once per invocation inside runDeclaredPreflight. It
+// rewrites the cobra flag value in place (Set keeps Changed=true), so
+// fallback-chain readers (EffectiveValue/BuildArgs) observe the content.
+//
+// Interaction with confirmation: stdin is consumed here, before the Safety
+// prompt of a user_required write would read it; such an interactive prompt
+// then sees EOF and fails closed with confirmation_required. Write commands
+// declaring InputStdin must be invoked with --yes (or --dry-run).
+func resolveInputFlags(cmd *cobra.Command, flags []FlagSpec) error {
+	stdinConsumed := false
+	for _, flag := range flags {
+		if len(flag.Input) == 0 {
+			continue
+		}
+		name := explicitInputFlagName(cmd, flag)
+		if name == "" {
+			continue
+		}
+		raw := cmdutil.MustGetFlag(cmd, name)
+		// Trim flags judge usability on the trimmed value (rawValue), so the
+		// prefix check must agree or " @path" would slip through unresolved.
+		if flag.Trim {
+			raw = strings.TrimSpace(raw)
+		}
+
+		switch {
+		case raw == "-":
+			if !inputSupports(flag, InputStdin) {
+				return apperrors.NewValidation(
+					fmt.Sprintf("参数 --%s 不支持 stdin 输入（-）", flag.Name))
+			}
+			if stdinConsumed {
+				return apperrors.NewValidation(
+					fmt.Sprintf("参数 --%s：stdin（-）只能被一个参数使用", flag.Name),
+					apperrors.WithHint(fmt.Sprintf(
+						"一个进程只有一份 stdin，其余参数请内联传值或用 @文件路径（如 --%s @./payload.json）",
+						flag.Name)))
+			}
+			stdinConsumed = true
+			data, err := io.ReadAll(cmd.InOrStdin())
+			if err != nil {
+				return apperrors.NewValidation(
+					fmt.Sprintf("参数 --%s 读取 stdin 失败：%v", flag.Name, err))
+			}
+			// Setting a registered string flag cannot fail.
+			_ = cmd.Flags().Set(name, strings.TrimPrefix(string(data), utf8BOM))
+
+		case strings.HasPrefix(raw, "@@"):
+			// Escape: strip the first @, keep the rest as a literal inline value.
+			_ = cmd.Flags().Set(name, raw[1:])
+
+		case strings.HasPrefix(raw, "@"):
+			if !inputSupports(flag, InputFile) {
+				return apperrors.NewValidation(
+					fmt.Sprintf("参数 --%s 不支持文件输入（@路径）", flag.Name))
+			}
+			path := strings.TrimSpace(raw[1:])
+			if path == "" {
+				return apperrors.NewValidation(
+					fmt.Sprintf("参数 --%s：@ 后的文件路径不能为空", flag.Name))
+			}
+			data, err := os.ReadFile(path)
+			if err != nil {
+				var opts []apperrors.Option
+				if inputSupports(flag, InputStdin) {
+					// Rejected @file paths are usually absolute (temp files).
+					// Steer toward stdin rather than copying the file around.
+					opts = append(opts, apperrors.WithHint(fmt.Sprintf(
+						"该参数也支持 stdin：把文件内容管道进命令并传 --%s -", flag.Name)))
+				}
+				return apperrors.NewValidation(
+					fmt.Sprintf("参数 --%s 读取文件 %q 失败：%v", flag.Name, path, err), opts...)
+			}
+			_ = cmd.Flags().Set(name, strings.TrimPrefix(string(data), utf8BOM))
+		}
+	}
+	return nil
+}

internal/corecmd/input_test.go

@@ -0,0 +1,334 @@
+// 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 corecmd
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/spf13/cobra"
+)
+
+// newInputCommand builds a Spec whose Invoke captures toolArgs, so tests can
+// assert what the full pipeline (resolution → validation → BuildArgs) ships.
+func newInputCommand(flags []FlagSpec, captured *map[string]any) *cobra.Command {
+	return New(Spec{
+		Use:   "t",
+		Short: "t",
+		Flags: flags,
+		Invoke: func(c *Ctx, toolArgs map[string]any) error {
+			*captured = toolArgs
+			return nil
+		},
+	})
+}
+
+func runInputCommand(t *testing.T, cmd *cobra.Command, args ...string) error {
+	t.Helper()
+	cmd.SetArgs(args)
+	return cmd.Execute()
+}
+
+func writeInputFile(t *testing.T, content string) string {
+	t.Helper()
+	path := filepath.Join(t.TempDir(), "payload.txt")
+	if err := os.WriteFile(path, []byte(content), 0o600); err != nil {
+		t.Fatalf("write fixture: %v", err)
+	}
+	return path
+}
+
+func TestCrossPlatformCoverageResolveInputFlagsFile(t *testing.T) {
+	var got map[string]any
+	cmd := newInputCommand([]FlagSpec{
+		{Name: "content", Usage: "C", Bind: "content", Input: []string{InputFile, InputStdin}},
+	}, &got)
+	path := writeInputFile(t, "# hello\nworld")
+
+	if err := runInputCommand(t, cmd, "--content", "@"+path); err != nil {
+		t.Fatalf("execute: %v", err)
+	}
+	if got["content"] != "# hello\nworld" {
+		t.Fatalf("toolArgs[content] = %q", got["content"])
+	}
+}
+
+func TestCrossPlatformCoverageResolveInputFlagsStdin(t *testing.T) {
+	var got map[string]any
+	cmd := newInputCommand([]FlagSpec{
+		{Name: "content", Usage: "C", Bind: "content", Input: []string{InputStdin}},
+	}, &got)
+	cmd.SetIn(strings.NewReader("piped payload"))
+
+	if err := runInputCommand(t, cmd, "--content", "-"); err != nil {
+		t.Fatalf("execute: %v", err)
+	}
+	if got["content"] != "piped payload" {
+		t.Fatalf("toolArgs[content] = %q", got["content"])
+	}
+}
+
+// The @@ escape keeps a literal leading @ inline and must not be treated as a
+// source reference even when Input is declared.
+func TestCrossPlatformCoverageResolveInputFlagsEscapedAtStaysInline(t *testing.T) {
+	var got map[string]any
+	cmd := newInputCommand([]FlagSpec{
+		{Name: "content", Usage: "C", Bind: "content", Input: []string{InputFile, InputStdin}},
+	}, &got)
+
+	if err := runInputCommand(t, cmd, "--content", "@@literal@x"); err != nil {
+		t.Fatalf("execute: %v", err)
+	}
+	if got["content"] != "@literal@x" {
+		t.Fatalf("toolArgs[content] = %q", got["content"])
+	}
+}
+
+func TestCrossPlatformCoverageResolveInputFlagsBOMStripped(t *testing.T) {
+	var got map[string]any
+	cmd := newInputCommand([]FlagSpec{
+		{Name: "content", Usage: "C", Bind: "content", Input: []string{InputFile}},
+	}, &got)
+	path := writeInputFile(t, "\ufeff{\"a\":1}")
+
+	if err := runInputCommand(t, cmd, "--content", "@"+path); err != nil {
+		t.Fatalf("execute: %v", err)
+	}
+	if got["content"] != "{\"a\":1}" {
+		t.Fatalf("toolArgs[content] = %q", got["content"])
+	}
+}
+
+// Required must be satisfied by the resolved payload, proving resolution runs
+// before the required stage.
+func TestCrossPlatformCoverageResolveInputFlagsSatisfiesRequired(t *testing.T) {
+	var got map[string]any
+	cmd := newInputCommand([]FlagSpec{
+		{Name: "content", Usage: "C", Bind: "content", Required: true, Input: []string{InputFile}},
+	}, &got)
+	path := writeInputFile(t, "payload")
+
+	if err := runInputCommand(t, cmd, "--content", "@"+path); err != nil {
+		t.Fatalf("execute: %v", err)
+	}
+	if got["content"] != "payload" {
+		t.Fatalf("toolArgs[content] = %q", got["content"])
+	}
+}
+
+// Enum validation sees the resolved content, not the "@path" token.
+func TestCrossPlatformCoverageResolveInputFlagsEnumValidatesResolvedContent(t *testing.T) {
+	var got map[string]any
+	cmd := newInputCommand([]FlagSpec{
+		{Name: "mode", Usage: "M", Bind: "mode", Enum: []string{"asc", "desc"}, Input: []string{InputFile}},
+	}, &got)
+	path := writeInputFile(t, "sideways")
+
+	err := runInputCommand(t, cmd, "--mode", "@"+path)
+	if err == nil || !strings.Contains(err.Error(), "不合法") {
+		t.Fatalf("expected enum rejection on resolved content, got %v", err)
+	}
+}
+
+// A value passed through a declared alias is resolved exactly like the main
+// name (fallback-chain parity).
+func TestCrossPlatformCoverageResolveInputFlagsAliasResolved(t *testing.T) {
+	var got map[string]any
+	cmd := newInputCommand([]FlagSpec{
+		{Name: "content", Usage: "C", Bind: "content", Aliases: []string{"body"}, Input: []string{InputFile}},
+	}, &got)
+	path := writeInputFile(t, "via alias")
+
+	if err := runInputCommand(t, cmd, "--body", "@"+path); err != nil {
+		t.Fatalf("execute: %v", err)
+	}
+	if got["content"] != "via alias" {
+		t.Fatalf("toolArgs[content] = %q", got["content"])
+	}
+}
+
+// When the main flag shadows a changed alias (rawValue usability order), the
+// shadowed alias must not be input-resolved: resolution targets exactly the
+// name the fallback chain will read. The whitespace main value is usable for
+// a non-Trim flag, and the alias path does not exist on purpose — a resolver
+// that wrongly picked the alias would fail the read instead of shipping "   ".
+func TestCrossPlatformCoverageResolveInputFlagsShadowedAliasNotResolved(t *testing.T) {
+	var got map[string]any
+	cmd := newInputCommand([]FlagSpec{
+		{Name: "content", Usage: "C", Bind: "content", Aliases: []string{"body"}, Input: []string{InputFile}},
+	}, &got)
+	missing := filepath.Join(t.TempDir(), "missing.txt")
+
+	if err := runInputCommand(t, cmd, "--content", "   ", "--body", "@"+missing); err != nil {
+		t.Fatalf("execute: %v", err)
+	}
+	if got["content"] != "   " {
+		t.Fatalf("toolArgs[content] = %q", got["content"])
+	}
+}
+
+func TestCrossPlatformCoverageResolveInputFlagsFileNotSupported(t *testing.T) {
+	var got map[string]any
+	cmd := newInputCommand([]FlagSpec{
+		{Name: "content", Usage: "C", Bind: "content", Input: []string{InputStdin}},
+	}, &got)
+
+	err := runInputCommand(t, cmd, "--content", "@/tmp/whatever.txt")
+	if err == nil || !strings.Contains(err.Error(), "不支持文件输入") {
+		t.Fatalf("expected file-input rejection, got %v", err)
+	}
+}
+
+func TestCrossPlatformCoverageResolveInputFlagsStdinNotSupported(t *testing.T) {
+	var got map[string]any
+	cmd := newInputCommand([]FlagSpec{
+		{Name: "content", Usage: "C", Bind: "content", Input: []string{InputFile}},
+	}, &got)
+	cmd.SetIn(strings.NewReader("x"))
+
+	err := runInputCommand(t, cmd, "--content", "-")
+	if err == nil || !strings.Contains(err.Error(), "不支持 stdin") {
+		t.Fatalf("expected stdin rejection, got %v", err)
+	}
+}
+
+func TestCrossPlatformCoverageResolveInputFlagsSingleStdinConsumer(t *testing.T) {
+	var got map[string]any
+	cmd := newInputCommand([]FlagSpec{
+		{Name: "first", Usage: "F", Bind: "first", Input: []string{InputStdin}},
+		{Name: "second", Usage: "S", Bind: "second", Input: []string{InputStdin}},
+	}, &got)
+	cmd.SetIn(strings.NewReader("x"))
+
+	err := runInputCommand(t, cmd, "--first", "-", "--second", "-")
+	if err == nil || !strings.Contains(err.Error(), "只能被一个参数使用") {
+		t.Fatalf("expected single-stdin rejection, got %v", err)
+	}
+}
+
+// failingReader (corecmd_test.go) fails every read, making the stdin error
+// branch reachable.
+func TestCrossPlatformCoverageResolveInputFlagsStdinReadFailure(t *testing.T) {
+	var got map[string]any
+	cmd := newInputCommand([]FlagSpec{
+		{Name: "content", Usage: "C", Bind: "content", Input: []string{InputStdin}},
+	}, &got)
+	cmd.SetIn(failingReader{})
+
+	err := runInputCommand(t, cmd, "--content", "-")
+	if err == nil || !strings.Contains(err.Error(), "读取 stdin 失败") {
+		t.Fatalf("expected stdin read failure, got %v", err)
+	}
+}
+
+func TestCrossPlatformCoverageResolveInputFlagsFileNotFound(t *testing.T) {
+	var got map[string]any
+	cmd := newInputCommand([]FlagSpec{
+		{Name: "content", Usage: "C", Bind: "content", Input: []string{InputFile, InputStdin}},
+	}, &got)
+
+	err := runInputCommand(t, cmd, "--content", "@"+filepath.Join(t.TempDir(), "missing.txt"))
+	if err == nil || !strings.Contains(err.Error(), "读取文件") {
+		t.Fatalf("expected read failure, got %v", err)
+	}
+}
+
+func TestCrossPlatformCoverageResolveInputFlagsEmptyPathAfterAt(t *testing.T) {
+	var got map[string]any
+	cmd := newInputCommand([]FlagSpec{
+		{Name: "content", Usage: "C", Bind: "content", Input: []string{InputFile}},
+	}, &got)
+
+	err := runInputCommand(t, cmd, "--content", "@   ")
+	if err == nil || !strings.Contains(err.Error(), "文件路径不能为空") {
+		t.Fatalf("expected empty-path rejection, got %v", err)
+	}
+}
+
+// A flag without Input keeps its literal value even when it looks like a
+// source reference — resolution is strictly opt-in per declaration.
+func TestCrossPlatformCoverageResolveInputFlagsNoInputSpecPassthrough(t *testing.T) {
+	var got map[string]any
+	cmd := newInputCommand([]FlagSpec{
+		{Name: "token", Usage: "T", Bind: "token"},
+	}, &got)
+
+	if err := runInputCommand(t, cmd, "--token", "@not-a-file"); err != nil {
+		t.Fatalf("execute: %v", err)
+	}
+	if got["token"] != "@not-a-file" {
+		t.Fatalf("toolArgs[token] = %q", got["token"])
+	}
+}
+
+// Registration defaults and env fallback are never input-resolved: @file only
+// applies to what the user literally typed on the command line.
+func TestCrossPlatformCoverageResolveInputFlagsDefaultNotResolved(t *testing.T) {
+	var got map[string]any
+	cmd := newInputCommand([]FlagSpec{
+		{Name: "content", Usage: "C", Bind: "content", Default: "@not-a-file", Input: []string{InputFile}},
+	}, &got)
+
+	if err := runInputCommand(t, cmd); err != nil {
+		t.Fatalf("execute: %v", err)
+	}
+	if got["content"] != "@not-a-file" {
+		t.Fatalf("toolArgs[content] = %q", got["content"])
+	}
+}
+
+// Trim flags judge usability on the trimmed value (rawValue), so a leading
+// whitespace before @ must still resolve instead of shipping as a literal.
+func TestCrossPlatformCoverageResolveInputFlagsTrimmedLeadingSpace(t *testing.T) {
+	var got map[string]any
+	cmd := newInputCommand([]FlagSpec{
+		{Name: "content", Usage: "C", Bind: "content", Trim: true, Input: []string{InputFile}},
+	}, &got)
+	path := writeInputFile(t, "trimmed payload")
+
+	if err := runInputCommand(t, cmd, "--content", " @"+path); err != nil {
+		t.Fatalf("execute: %v", err)
+	}
+	if got["content"] != "trimmed payload" {
+		t.Fatalf("toolArgs[content] = %q", got["content"])
+	}
+}
+
+func TestCrossPlatformCoverageValidateInputSpecsPanics(t *testing.T) {
+	cases := []struct {
+		name string
+		flag FlagSpec
+	}{
+		{"non-string kind", FlagSpec{Name: "n", Kind: KindInt, Input: []string{InputFile}}},
+		{"unknown source", FlagSpec{Name: "s", Input: []string{"url"}}},
+		{"duplicate source", FlagSpec{Name: "s", Input: []string{InputFile, InputFile}}},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			defer func() {
+				if recover() == nil {
+					t.Fatal("expected panic")
+				}
+			}()
+			New(Spec{
+				Use:    "t",
+				Short:  "t",
+				Flags:  []FlagSpec{tc.flag},
+				Invoke: func(c *Ctx, toolArgs map[string]any) error { return nil },
+			})
+		})
+	}
+}

internal/errors/errors_test.go

@@ -15,9 +15,13 @@ package errors
 
 import (
 	stderrors "errors"
+	"os"
+	"path/filepath"
 	"strings"
 	"testing"
 	"time"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/config"
 )
 
 func TestCrossPlatformCoverageExitCodeByCategory(t *testing.T) {
@@ -382,6 +386,27 @@ func TestCrossPlatformCoverageServerGuidanceSuppressesUnsafeActionURL(t *testing
 	}
 }
 
+func TestCrossPlatformCoveragePrintJSONCLIOrgNotAuthorizedUsesInternationalActionURL(t *testing.T) {
+	dir := t.TempDir()
+	t.Setenv("DWS_CONFIG_DIR", dir)
+	if err := os.WriteFile(filepath.Join(dir, "mcp_url"), []byte("https://mcp.dingtalk.io\n"), config.FilePerm); err != nil {
+		t.Fatalf("WriteFile(mcp_url) error = %v", err)
+	}
+
+	var b strings.Builder
+	if err := PrintJSON(&b, NewAPI(
+		"business error",
+		WithServerDiag(ServerDiagnostics{ServerErrorCode: "CLI_ORG_NOT_AUTHORIZED"}),
+	)); err != nil {
+		t.Fatalf("PrintJSON() error = %v", err)
+	}
+
+	want := `"action_url": "https://open-dev.dingtalk.io/fe/old#/developerSettings"`
+	if got := b.String(); !strings.Contains(got, want) {
+		t.Fatalf("expected international action_url %q, got %q", want, got)
+	}
+}
+
 func TestCrossPlatformCoveragePrintJSONIncludesRPCCodeAndData(t *testing.T) {
 	t.Parallel()
 

internal/helpers/chat_command_edges_test.go

@@ -3,6 +3,7 @@ package helpers
 import (
 	"context"
 	"errors"
+	"fmt"
 	"io"
 	"os"
 	"path/filepath"
@@ -11,6 +12,7 @@ import (
 	"testing"
 
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition"
+	"github.com/spf13/cobra"
 )
 
 func runChatCoverageCommand(t *testing.T, caller edition.ToolCaller, args ...string) error {
@@ -32,14 +34,26 @@ func runChatCoverageCommand(t *testing.T, caller edition.ToolCaller, args ...str
 
 func runChatCoverageDirect(t *testing.T, path []string, flags map[string]string) error {
 	t.Helper()
-	command, _, err := newChatCommand().Find(path)
+	InitDeps(&scriptedToolCaller{})
+	deps.Out.w = io.Discard
+	deps.Out.errW = io.Discard
+	root := newChatCommand()
+	installExampleGlobalFlags(root)
+	root.PersistentFlags().Bool("debug", false, "")
+	root.PersistentFlags().Bool("verbose", false, "")
+	command, _, err := root.Find(path)
 	if err != nil {
 		return err
 	}
 	for name, value := range flags {
-		if err := command.Flags().Set(name, value); err != nil {
+		flag := command.Flag(name)
+		if flag == nil {
+			return fmt.Errorf("no such flag -%s", name)
+		}
+		if err := flag.Value.Set(value); err != nil {
 			return err
 		}
+		flag.Changed = true
 	}
 	return command.RunE(command, nil)
 }
@@ -93,7 +107,7 @@ func TestCrossPlatformCoverageChatStableCompatibilityHintsRemainAvailable(t *tes
 		hint string
 	}{
 		{path: "send", args: []string{"send", "--group", "cid-stable", "--text", "hello"}, hint: "dws chat message send"},
-		{path: "history", args: []string{"history", "--group", "cid-stable", "--limit", "20"}, hint: "dws chat message list --group <GROUP_OPEN_CONVERSATION_ID>"},
+		{path: "history", args: []string{"history", "--group", "cid-stable", "--limit", "20"}, hint: "dws chat message list --conversation-id <GROUP_OPEN_CONVERSATION_ID>"},
 	} {
 		command, remaining, err := root.Find([]string{tc.path})
 		if err != nil {
@@ -113,6 +127,80 @@ func TestCrossPlatformCoverageChatStableCompatibilityHintsRemainAvailable(t *tes
 	}
 }
 
+func TestCrossPlatformCoverageChatAliasInstallerRemainingEdges(t *testing.T) {
+	restoreChatManifestExternalVisibleFlags(nil)
+
+	mismatchedRoot := &cobra.Command{Use: "chat"}
+	mismatchedRoot.AddCommand(&cobra.Command{Use: "other"})
+	restoreChatManifestExternalVisibleFlags(mismatchedRoot)
+
+	missingPrimary := &cobra.Command{Use: "leaf"}
+	installChatFlagAliases(missingPrimary, "conversation-id", []string{"group"}, requireChatConversationID)
+	if flag := missingPrimary.Flags().Lookup("group"); flag != nil {
+		t.Fatalf("alias registered without canonical flag: %#v", flag)
+	}
+
+	skipGroup := &cobra.Command{Use: "leaf", RunE: func(cmd *cobra.Command, args []string) error { return nil }}
+	skipGroup.Flags().String("conversation-id", "", "")
+	skipGroup.Flags().String("group-name", "", "")
+	installChatFlagAliases(skipGroup, "conversation-id", []string{"group", "chat"}, requireChatConversationID)
+	if flag := skipGroup.Flags().Lookup("group"); flag != nil {
+		t.Fatalf("group alias registered beside group-name: %#v", flag)
+	}
+	if flag := skipGroup.Flags().Lookup("chat"); flag == nil {
+		t.Fatal("non-group alias was not registered")
+	}
+
+	preRunCalled := false
+	withPreRun := &cobra.Command{
+		Use: "leaf",
+		PreRunE: func(cmd *cobra.Command, args []string) error {
+			preRunCalled = true
+			return nil
+		},
+		RunE: func(cmd *cobra.Command, args []string) error { return nil },
+	}
+	withPreRun.Flags().String("conversation-id", "", "")
+	installChatFlagAliases(withPreRun, "conversation-id", []string{"group"}, requireChatConversationID)
+	withPreRun.SetArgs([]string{"--group", "cid"})
+	if err := withPreRun.ExecuteContext(context.Background()); err != nil {
+		t.Fatalf("execute with alias and previous PreRunE: %v", err)
+	}
+	if !preRunCalled {
+		t.Fatal("previous PreRunE was not called")
+	}
+}
+
+func TestCrossPlatformCoverageChatMessageForwardRequiresMessageID(t *testing.T) {
+	caller := &productExampleCaller{}
+	InitDeps(caller)
+	deps.Out.w = io.Discard
+	deps.Out.errW = io.Discard
+	root := newChatCommand()
+	command, _, err := root.Find([]string{"message", "forward"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, name := range []string{"message-id", "msg-id"} {
+		if flag := command.Flags().Lookup(name); flag != nil && flag.Annotations != nil {
+			delete(flag.Annotations, cobra.BashCompOneRequiredFlag)
+		}
+	}
+	if err := command.Flags().Set("src-conversation-id", "src"); err != nil {
+		t.Fatal(err)
+	}
+	if err := command.Flags().Set("dest-conversation-id", "dest"); err != nil {
+		t.Fatal(err)
+	}
+	err = command.RunE(command, nil)
+	if err == nil || !strings.Contains(err.Error(), "missing required flag: --message-id") {
+		t.Fatalf("forward missing message id error = %v", err)
+	}
+	if caller.calls != 0 {
+		t.Fatalf("tool calls = %d, want 0", caller.calls)
+	}
+}
+
 func TestCrossPlatformCoverageChatGroupUpdateIconAcceptsUploadedMediaIDPrefixes(t *testing.T) {
 	previousDeps, previousArgs := deps, os.Args
 	os.Args = []string{"dws", "chat"}
@@ -199,9 +287,10 @@ func TestCrossPlatformCoverageChatCommandValidationAndSuccessEdges(t *testing.T)
 		{"category", "remove-conv", "--group=cid", "--category-ids=1,2"},
 		{"message", "list-by-ids", "--msg-ids=" + strings.Repeat("id,", 51) + "last"},
 		{"group", "transfer-owner", "--group=cid", "--new-owner=D-owner"},
+		{"group", "transfer-owner", "--group=cid", "--new-owner=DAAAAAAAAAAAiE"},
 		{"group", "update-icon", "--group=cid", "--icon-media-id=@valid"},
 		{"group", "set-history", "--group=cid", "--option=ALL"},
-		{"group", "audit-join-validation", "--group=cid", "--record-id=1", "--applicant=D1", "--inviter=D2", "--status=AuditApprove", "--description=ok"},
+		{"group", "audit-join-validation", "--conversation-id=cid", "--record-id=1", "--applicant=D1", "--inviter=D2", "--status=AuditApprove", "--description=ok"},
 		{"mark-read", "--conversation-id=cid", "--message-id=mid"},
 		{"text", "translate", "--query=hello", "--to=zh_CN"},
 		{"group-role", "set-user", "--group=cid", "--user=D1", "--role-ids=r1"},
@@ -293,7 +382,7 @@ func TestCrossPlatformCoverageChatNativeSendCardMentions(t *testing.T) {
 		caller := &scriptedToolCaller{}
 		err := runChatCoverageCommand(t, caller,
 			"message", "send-card",
-			"--group=cid",
+			"--conversation-id=cid",
 			"--at-open-dingtalk-ids=D1,D2,D1",
 			"--at-all",
 		)
@@ -314,13 +403,13 @@ func TestCrossPlatformCoverageChatNativeSendCardMentions(t *testing.T) {
 		name string
 		args []string
 	}{
-		{name: "member mention rejects direct message", args: []string{"--receiver=D1", "--at-open-dingtalk-ids=D2"}},
-		{name: "at all rejects direct message", args: []string{"--receiver=D1", "--at-all"}},
+		{name: "member mention rejects direct message", args: []string{"--open-dingtalk-id=D1", "--at-open-dingtalk-ids=D2"}},
+		{name: "at all rejects direct message", args: []string{"--open-dingtalk-id=D1", "--at-all"}},
 	} {
 		t.Run(tc.name, func(t *testing.T) {
 			caller := &scriptedToolCaller{}
 			err := runChatCoverageCommand(t, caller, append([]string{"message", "send-card"}, tc.args...)...)
-			if err == nil || !strings.Contains(err.Error(), "only supported with --group") {
+			if err == nil || !strings.Contains(err.Error(), "only supported with --conversation-id") {
 				t.Fatalf("error = %v, want group-only mention validation", err)
 			}
 			if caller.calls != 0 {
@@ -330,6 +419,168 @@ func TestCrossPlatformCoverageChatNativeSendCardMentions(t *testing.T) {
 	}
 }
 
+func TestCrossPlatformCoverageChatSendCardHiddenAliasesMapToCanonicalPayload(t *testing.T) {
+	previousDeps, previousArgs := deps, os.Args
+	os.Args = []string{"dws", "chat"}
+	t.Cleanup(func() { deps, os.Args = previousDeps, previousArgs })
+
+	for _, tc := range []struct {
+		name string
+		args []string
+		want map[string]any
+	}{
+		{
+			name: "group alias",
+			args: []string{"--group=cid"},
+			want: map[string]any{"openConversationId": "cid"},
+		},
+		{
+			name: "receiver alias",
+			args: []string{"--receiver=DAAAAAAAAAAAiE"},
+			want: map[string]any{"receiverOpenDingTalkId": "DAAAAAAAAAAAiE"},
+		},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			caller := &scriptedToolCaller{}
+			err := runChatCoverageCommand(t, caller, append([]string{"message", "send-card"}, tc.args...)...)
+			if err != nil {
+				t.Fatal(err)
+			}
+			if caller.calls != 1 || caller.server != "im" || caller.tool != "create_and_send_card" || !reflect.DeepEqual(caller.args, tc.want) {
+				t.Fatalf("call = count:%d server:%q tool:%q args:%#v, want %#v", caller.calls, caller.server, caller.tool, caller.args, tc.want)
+			}
+		})
+	}
+}
+
+func TestCrossPlatformCoverageChatGroupAuditJoinValidationUsesCanonicalAndAliasPayload(t *testing.T) {
+	previousDeps, previousArgs := deps, os.Args
+	os.Args = []string{"dws", "chat"}
+	t.Cleanup(func() { deps, os.Args = previousDeps, previousArgs })
+
+	for _, tc := range []struct {
+		name string
+		flag string
+	}{
+		{name: "canonical conversation-id", flag: "--conversation-id=cid"},
+		{name: "hidden group alias", flag: "--group=cid"},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			caller := &scriptedToolCaller{}
+			err := runChatCoverageCommand(t, caller,
+				"group", "audit-join-validation",
+				tc.flag,
+				"--record-id=123",
+				"--applicant=D-applicant",
+				"--inviter=D-inviter",
+				"--status=AuditDelete",
+				"--description=deny",
+			)
+			if err != nil {
+				t.Fatal(err)
+			}
+			want := map[string]any{
+				"openConversationId": "cid",
+				"applyRecordId":      int64(123),
+				"applicantUid":       "D-applicant",
+				"inviterUid":         "D-inviter",
+				"status":             "AuditDelete",
+				"auditDescription":   "deny",
+			}
+			if caller.calls != 1 || caller.server != "im" || caller.tool != "audit_join_group" || !reflect.DeepEqual(caller.args, want) {
+				t.Fatalf("call = count:%d server:%q tool:%q args:%#v, want %#v", caller.calls, caller.server, caller.tool, caller.args, want)
+			}
+		})
+	}
+}
+
+func TestCrossPlatformCoverageChatIMIDMigrationRequiredFlagErrors(t *testing.T) {
+	previousDeps, previousArgs := deps, os.Args
+	os.Args = []string{"dws", "chat"}
+	t.Cleanup(func() { deps, os.Args = previousDeps, previousArgs })
+
+	tests := []struct {
+		name string
+		path []string
+		flag map[string]string
+		want string
+	}{
+		{name: "message list mutually exclusive targets", path: []string{"message", "list"}, flag: map[string]string{"conversation-id": "cid", "user": "u1", "time": "2026-01-01"}, want: "mutually exclusive"},
+		{name: "message list missing target", path: []string{"message", "list"}, flag: map[string]string{"time": "2026-01-01"}, want: "--conversation-id, --user or --open-dingtalk-id is required"},
+		{name: "topic replies missing conversation", path: []string{"message", "list-topic-replies"}, flag: map[string]string{"topic-id": "t1"}, want: "conversation-id"},
+		{name: "read status missing conversation", path: []string{"message", "read-status"}, flag: map[string]string{"message-id": "m1"}, want: "conversation-id"},
+		{name: "read status conflicting aliases", path: []string{"message", "read-status"}, flag: map[string]string{"conversation-id": "cid1", "group": "cid2", "message-id": "m1"}, want: "conflicts"},
+		{name: "read status missing message", path: []string{"message", "read-status"}, flag: map[string]string{"conversation-id": "cid"}, want: "message-id"},
+		{name: "update text emotion missing message", path: []string{"message", "update-text-emotion"}, flag: map[string]string{"conversation-id": "cid", "old-emotion-id": "e1", "emotion-id": "e2", "emotion-name": "n", "text": "t", "background-id": "b"}, want: "message-id"},
+		{name: "update text emotion missing detail flag", path: []string{"message", "update-text-emotion"}, flag: map[string]string{"conversation-id": "cid", "message-id": "m1", "old-emotion-id": "e1", "emotion-id": "e2", "emotion-name": "n", "text": "t"}, want: "background-id"},
+		{name: "transfer owner missing conversation", path: []string{"group", "transfer-owner"}, flag: map[string]string{"new-owner": "D1"}, want: "conversation-id"},
+		{name: "invite url missing conversation", path: []string{"group", "invite-url"}, want: "conversation-id"},
+		{name: "quit missing conversation", path: []string{"group", "quit"}, want: "conversation-id"},
+		{name: "update icon missing conversation", path: []string{"group", "update-icon"}, flag: map[string]string{"icon-media-id": "@media"}, want: "conversation-id"},
+		{name: "update settings missing conversation", path: []string{"group", "update-settings"}, flag: map[string]string{"setting-key": "searchable"}, want: "conversation-id"},
+		{name: "set admin missing conversation", path: []string{"group", "set-admin"}, flag: map[string]string{"users": "D1"}, want: "conversation-id"},
+		{name: "role list missing conversation", path: []string{"group-role", "list"}, want: "group"},
+		{name: "role add missing conversation", path: []string{"group-role", "add"}, flag: map[string]string{"name": "role"}, want: "conversation-id"},
+		{name: "role update missing conversation", path: []string{"group-role", "update"}, flag: map[string]string{"role-id": "r1", "name": "role"}, want: "conversation-id"},
+		{name: "role remove missing conversation", path: []string{"group-role", "remove"}, flag: map[string]string{"role-id": "r1"}, want: "conversation-id"},
+		{name: "role set user missing conversation", path: []string{"group-role", "set-user"}, flag: map[string]string{"user": "D1", "role-ids": "r1"}, want: "conversation-id"},
+		{name: "role remove user missing conversation", path: []string{"group-role", "remove-user"}, flag: map[string]string{"user": "D1", "role-ids": "r1"}, want: "conversation-id"},
+		{name: "role query user missing conversation", path: []string{"group-role", "query-user"}, flag: map[string]string{"user": "D1"}, want: "conversation-id"},
+		{name: "bots missing legacy group", path: []string{"group", "bots"}, want: "group"},
+		{name: "bots rejects migrated conversation id", path: []string{"group", "bots"}, flag: map[string]string{"conversation-id": "cid"}, want: "no such flag"},
+		{name: "dismiss missing conversation", path: []string{"group", "dismiss"}, flag: map[string]string{"yes": "true"}, want: "conversation-id"},
+		{name: "set history missing conversation", path: []string{"group", "set-history"}, flag: map[string]string{"option": "ALL"}, want: "conversation-id"},
+		{name: "set pin missing message", path: []string{"message", "set-pin-msg"}, flag: map[string]string{"open-conversation-id": "cid"}, want: "message-id"},
+		{name: "unset pin missing message", path: []string{"message", "unset-pin-msg"}, flag: map[string]string{"open-conversation-id": "cid"}, want: "message-id"},
+		{name: "audit join missing conversation", path: []string{"group", "audit-join-validation"}, flag: map[string]string{"record-id": "1", "applicant": "D1", "inviter": "D2", "status": "AuditApprove"}, want: "conversation-id"},
+		{name: "set top missing message", path: []string{"message", "set-top-msg"}, flag: map[string]string{"open-conversation-id": "cid"}, want: "message-id"},
+		{name: "unset top missing message", path: []string{"message", "unset-top-msg"}, flag: map[string]string{"open-conversation-id": "cid"}, want: "message-id"},
+		{name: "update alias missing conversation", path: []string{"group", "update-alias"}, flag: map[string]string{"alias-title": "alias"}, want: "conversation-id"},
+		{name: "notice create missing conversation", path: []string{"group", "notice", "create"}, flag: map[string]string{"content": "hello"}, want: "conversation-id"},
+		{name: "notice edit missing conversation", path: []string{"group", "notice", "edit"}, flag: map[string]string{"notice-id": "n1", "content": "hello"}, want: "conversation-id"},
+		{name: "notice get missing conversation", path: []string{"group", "notice", "get"}, flag: map[string]string{"notice-id": "n1"}, want: "conversation-id"},
+		{name: "notice list missing conversation", path: []string{"group", "notice", "list"}, want: "conversation-id"},
+	}
+
+	probe := newChatCommand()
+	messageList, _, err := probe.Find([]string{"message", "list"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got, err := chatConversationID(messageList); err != nil || got != "" {
+		t.Fatalf("empty chatConversationID = %q, %v", got, err)
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			err := runChatCoverageDirect(t, tc.path, tc.flag)
+			if err == nil || !strings.Contains(err.Error(), tc.want) {
+				t.Fatalf("error = %v, want containing %q", err, tc.want)
+			}
+		})
+	}
+}
+
+func TestCrossPlatformCoverageChatMessageReadStatusConversationAliasesExecute(t *testing.T) {
+	for _, alias := range []string{"group", "id", "chat", "open-conversation-id"} {
+		t.Run(alias, func(t *testing.T) {
+			caller := &scriptedToolCaller{}
+			if err := runChatCoverageCommand(t, caller, "message", "read-status", "--"+alias, "cid-1", "--message-id", "msg-1"); err != nil {
+				t.Fatal(err)
+			}
+			if caller.server != "im" || caller.tool != "query_msg_read_status" {
+				t.Fatalf("call = %s/%s, want im/query_msg_read_status", caller.server, caller.tool)
+			}
+			if got := caller.args["openConversationId"]; got != "cid-1" {
+				t.Fatalf("openConversationId = %#v, want cid-1", got)
+			}
+			if got := caller.args["openMessageId"]; got != "msg-1" {
+				t.Fatalf("openMessageId = %#v, want msg-1", got)
+			}
+		})
+	}
+}
+
 func TestCrossPlatformCoverageChatWebhookReplyConversationAndDownloadEdges(t *testing.T) {
 	previousDeps, previousArgs := deps, os.Args
 	os.Args = []string{"dws", "chat"}
@@ -343,6 +594,7 @@ func TestCrossPlatformCoverageChatWebhookReplyConversationAndDownloadEdges(t *te
 	_ = runChatCoverageCommand(t, &scriptedToolCaller{}, "conversation-info", "--open-dingtalk-id=D1")
 	_ = runChatCoverageCommand(t, &scriptedToolCaller{}, "conversation-info", "--user=D1")
 	_ = runChatCoverageCommand(t, &scriptedToolCaller{steps: []scriptedToolStep{{text: `{"result":[{"userId":"u1","openDingTalkId":"D1"}]}`}, {text: `{}`}}}, "conversation-info", "--user=u1")
+	_ = runChatCoverageCommand(t, &scriptedToolCaller{}, "message", "send-card", "--open-dingtalk-id=D1")
 	_ = runChatCoverageCommand(t, &scriptedToolCaller{}, "message", "send-card", "--receiver=D1")
 
 	oldGet := httpGetFile

internal/helpers/chat_message_help_test.go

@@ -17,8 +17,88 @@ import (
 	"bytes"
 	"strings"
 	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/runtimeannotate"
+	"github.com/spf13/cobra"
 )
 
+func TestCrossPlatformCoverageChatGroupAuditJoinValidationAliasContract(t *testing.T) {
+	cmd := newChatCommand()
+	leaf, _, err := cmd.Find([]string{"group", "audit-join-validation"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	canonical := leaf.Flags().Lookup("conversation-id")
+	if canonical == nil || canonical.Hidden {
+		t.Fatalf("conversation-id flag = %#v, want visible canonical", canonical)
+	}
+	legacy := leaf.Flags().Lookup("group")
+	if legacy == nil || !legacy.Hidden {
+		t.Fatalf("group flag = %#v, want hidden compatibility alias", legacy)
+	}
+	if got := legacy.Annotations[runtimeannotate.AnnotationFlagAliasOf]; len(got) != 1 || got[0] != "conversation-id" {
+		t.Fatalf("group alias_of annotation = %#v", got)
+	}
+	if got := legacy.Annotations[runtimeannotate.AnnotationFlagAliasOrigin]; len(got) != 1 || got[0] != runtimeannotate.FlagAliasOriginCorecmdV1 {
+		t.Fatalf("group alias_origin annotation = %#v", got)
+	}
+	if got := legacy.Annotations[cobra.BashCompOneRequiredFlag]; len(got) != 0 {
+		t.Fatalf("hidden group alias kept required annotation: %#v", got)
+	}
+}
+
+func TestCrossPlatformCoverageChatGroupAuditJoinValidationRestoreRequiredNoop(t *testing.T) {
+	restoreChatGroupBotsLegacyRequired(nil)
+	restoreChatPendingMigrationCanonicalRequired(nil)
+	root := &cobra.Command{Use: "chat"}
+	root.AddCommand(&cobra.Command{Use: "other"})
+	restoreChatGroupBotsLegacyRequired(root)
+	restoreChatPendingMigrationCanonicalRequired(root)
+}
+
+func TestCrossPlatformCoverageChatGroupBotsKeepsLegacyGroupFlag(t *testing.T) {
+	cmd := newChatCommand()
+	leaf, _, err := cmd.Find([]string{"group", "bots"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	group := leaf.Flags().Lookup("group")
+	if group == nil || group.Hidden {
+		t.Fatalf("group flag = %#v, want visible legacy flag", group)
+	}
+	if got := group.Annotations[cobra.BashCompOneRequiredFlag]; len(got) == 0 || got[0] != "true" {
+		t.Fatalf("group required annotation = %#v, want true", got)
+	}
+	if leaf.Flags().Lookup("conversation-id") != nil {
+		t.Fatalf("chat group bots still exposes migrated --conversation-id")
+	}
+	if leaf.Flags().Lookup("group-name") != nil {
+		t.Fatalf("chat group bots still exposes migrated --group-name")
+	}
+}
+
+func TestCrossPlatformCoverageChatPendingMigrationAliasesMatchManifest(t *testing.T) {
+	cmd := newChatCommand()
+	leaf, _, err := cmd.Find([]string{"group", "dismiss"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	canonical := leaf.Flags().Lookup("conversation-id")
+	if canonical == nil {
+		t.Fatal("missing conversation-id flag")
+	}
+	if got := canonical.Annotations[cobra.BashCompOneRequiredFlag]; len(got) == 0 || got[0] != "true" {
+		t.Fatalf("conversation-id required annotation = %#v, want true", got)
+	}
+	legacy := leaf.Flags().Lookup("group")
+	if legacy == nil || !legacy.Hidden {
+		t.Fatalf("group flag = %#v, want hidden legacy alias", legacy)
+	}
+	if got := legacy.Annotations[runtimeannotate.AnnotationFlagAliasOf]; len(got) != 1 || got[0] != "conversation-id" {
+		t.Fatalf("group alias_of annotation = %#v", got)
+	}
+}
+
 func TestCrossPlatformCoverageChatMessageHelpDocumentsPostSendIDChain(t *testing.T) {
 	tests := []struct {
 		name       string
@@ -51,7 +131,7 @@ func TestCrossPlatformCoverageChatMessageHelpDocumentsPostSendIDChain(t *testing
 			contains: []string{
 				"send -> query-send-status -> edit",
 				"query-send-status --open-task-id <上一步返回的openTaskId>",
-				"edit --conversation-id <上一步返回的openConversationId> --msg-id <上一步返回的openMessageId>",
+				"edit --conversation-id <上一步返回的openConversationId> --message-id <上一步返回的openMessageId>",
 			},
 			notContain: "chat message list",
 		},
@@ -61,7 +141,7 @@ func TestCrossPlatformCoverageChatMessageHelpDocumentsPostSendIDChain(t *testing
 			contains: []string{
 				"send -> query-send-status -> recall",
 				"query-send-status --open-task-id <上一步返回的openTaskId>",
-				"recall --conversation-id <上一步返回的openConversationId> --msg-id <上一步返回的openMessageId>",
+				"recall --conversation-id <上一步返回的openConversationId> --message-id <上一步返回的openMessageId>",
 			},
 			notContain: "chat message list",
 		},
@@ -183,3 +263,91 @@ func TestCrossPlatformCoverageChatMessageHelpDocumentsOptionalTimeDefaults(t *te
 		})
 	}
 }
+
+func TestCrossPlatformCoverageChatReactionHelpKeepsManifestExternalAliasesVisible(t *testing.T) {
+	for _, command := range []string{"add-emoji", "remove-emoji", "add-text-emotion", "remove-text-emotion"} {
+		t.Run(command, func(t *testing.T) {
+			cmd := newChatCommand()
+			var output bytes.Buffer
+			cmd.SetOut(&output)
+			cmd.SetErr(&output)
+			cmd.SetArgs([]string{"message", command, "--help"})
+			if err := cmd.Execute(); err != nil {
+				t.Fatalf("chat message %s --help: %v\n%s", command, err, output.String())
+			}
+
+			help := output.String()
+			if !strings.Contains(help, "--conversation-id") {
+				t.Fatalf("chat message %s help missing --conversation-id:\n%s", command, help)
+			}
+			for _, visible := range []string{"--group", "--id", "--chat"} {
+				if !strings.Contains(help, visible+" string") {
+					t.Fatalf("chat message %s help hides manifest-external alias %s:\n%s", command, visible, help)
+				}
+			}
+		})
+	}
+}
+
+func TestCrossPlatformCoverageChatGroupBotsHelpKeepsLegacyGroup(t *testing.T) {
+	cmd := newChatCommand()
+	var output bytes.Buffer
+	cmd.SetOut(&output)
+	cmd.SetErr(&output)
+	cmd.SetArgs([]string{"group", "bots", "--help"})
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("chat group bots --help: %v\n%s", err, output.String())
+	}
+
+	help := output.String()
+	if !strings.Contains(help, "--group string") {
+		t.Fatalf("chat group bots help missing visible --group:\n%s", help)
+	}
+	for _, hidden := range []string{"--conversation-id", "--group-name"} {
+		if strings.Contains(help, hidden) {
+			t.Fatalf("chat group bots help exposes migrated flag %s:\n%s", hidden, help)
+		}
+	}
+}
+
+func TestCrossPlatformCoverageChatSendCardHelpUsesCanonicalIDFlags(t *testing.T) {
+	cmd := newChatCommand()
+	var output bytes.Buffer
+	cmd.SetOut(&output)
+	cmd.SetErr(&output)
+	cmd.SetArgs([]string{"message", "send-card", "--help"})
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("chat message send-card --help: %v\n%s", err, output.String())
+	}
+
+	help := output.String()
+	for _, visible := range []string{"--conversation-id", "--open-dingtalk-id"} {
+		if !strings.Contains(help, visible) {
+			t.Fatalf("send-card help missing %s:\n%s", visible, help)
+		}
+	}
+	for _, visible := range []string{"--group", "--receiver"} {
+		if !strings.Contains(help, visible+" string") {
+			t.Fatalf("send-card help hides manifest-external alias %s:\n%s", visible, help)
+		}
+	}
+}
+
+func TestCrossPlatformCoverageChatGroupAuditJoinValidationHelpUsesCanonicalConversationID(t *testing.T) {
+	cmd := newChatCommand()
+	var output bytes.Buffer
+	cmd.SetOut(&output)
+	cmd.SetErr(&output)
+	cmd.SetArgs([]string{"group", "audit-join-validation", "--help"})
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("chat group audit-join-validation --help: %v\n%s", err, output.String())
+	}
+
+	help := output.String()
+	if !strings.Contains(help, "--conversation-id") {
+		t.Fatalf("audit-join-validation help missing --conversation-id:\n%s", help)
+	}
+	if strings.Contains(help, "--group string") {
+		t.Fatalf("audit-join-validation help exposes hidden --group alias:\n%s", help)
+	}
+}

internal/helpers/chat_ports_coverage_test.go

@@ -81,6 +81,32 @@ func TestCrossPlatformCoverageChatUpdateTextEmotion(t *testing.T) {
 				},
 			},
 		},
+		{
+			name: "open-conversation-id alias",
+			args: []string{
+				"message", "update-text-emotion",
+				"--open-conversation-id", "conv-3",
+				"--message-id", "msg-3",
+				"--old-emotion-id", "old-3",
+				"--emotion-id", "new-3",
+				"--emotion-name", "smile",
+				"--text", "done",
+				"--background-id", "im_bg_2",
+			},
+			want: guardedMutationCall{
+				productID: "im",
+				toolName:  "update_text_emotion",
+				args: map[string]any{
+					"openConversationId": "conv-3",
+					"openMsgId":          "msg-3",
+					"oldEmotionId":       "old-3",
+					"emotionId":          "new-3",
+					"emotionName":        "smile",
+					"text":               "done",
+					"backgroundId":       "im_bg_2",
+				},
+			},
+		},
 	}
 	for _, test := range tests {
 		test := test
@@ -127,7 +153,7 @@ func TestCrossPlatformCoverageChatUpdateTextEmotionRequiredFlags(t *testing.T) {
 		{
 			name:    "missing conversation-id and aliases",
 			args:    dropFlag("--conversation-id"),
-			wantErr: "at least one of the flags in the group [conversation-id group id chat] is required",
+			wantErr: "missing required flag: --conversation-id (or --group / --id / --chat / --open-conversation-id)",
 		},
 		{
 			name:    "missing old-emotion-id",
@@ -135,7 +161,7 @@ func TestCrossPlatformCoverageChatUpdateTextEmotionRequiredFlags(t *testing.T) {
 			wantErr: `required flag(s) "old-emotion-id" not set`,
 		},
 		{
-			name: "missing msg-id and background-id",
+			name: "missing message-id and background-id",
 			args: []string{
 				"message", "update-text-emotion",
 				"--conversation-id", "conv-1",
@@ -144,7 +170,7 @@ func TestCrossPlatformCoverageChatUpdateTextEmotionRequiredFlags(t *testing.T) {
 				"--emotion-name", "like",
 				"--text", "nice",
 			},
-			wantErr: `required flag(s) "background-id", "msg-id" not set`,
+			wantErr: "missing required flag: --message-id (or --msg-id / --open-message-id)",
 		},
 	}
 	for _, test := range tests {
@@ -163,19 +189,41 @@ func TestCrossPlatformCoverageChatUpdateTextEmotionRequiredFlags(t *testing.T) {
 }
 
 func TestCrossPlatformCoverageChatGroupGetMuteConfig(t *testing.T) {
-	caller := &guardedMutationCaller{}
-	err := executeGuardedMutationCommand(t, caller, newChatCommand,
-		"group", "get-mute-config", "--group", "conv-1")
-	if err != nil {
-		t.Fatalf("get-mute-config returned error: %v", err)
-	}
-	want := guardedMutationCall{
-		productID: "im",
-		toolName:  "get_group_mute_config",
-		args:      map[string]any{"openConversationId": "conv-1"},
-	}
-	if len(caller.calls) != 1 || !reflect.DeepEqual(caller.calls[0], want) {
-		t.Fatalf("tool calls = %#v, want %#v", caller.calls, want)
+	for _, test := range []struct {
+		name string
+		args []string
+		want guardedMutationCall
+	}{
+		{
+			name: "legacy group alias",
+			args: []string{"group", "get-mute-config", "--group", "conv-1"},
+			want: guardedMutationCall{
+				productID: "im",
+				toolName:  "get_group_mute_config",
+				args:      map[string]any{"openConversationId": "conv-1"},
+			},
+		},
+		{
+			name: "canonical conversation id",
+			args: []string{"group", "get-mute-config", "--conversation-id", "conv-2"},
+			want: guardedMutationCall{
+				productID: "im",
+				toolName:  "get_group_mute_config",
+				args:      map[string]any{"openConversationId": "conv-2"},
+			},
+		},
+	} {
+		test := test
+		t.Run(test.name, func(t *testing.T) {
+			caller := &guardedMutationCaller{}
+			err := executeGuardedMutationCommand(t, caller, newChatCommand, test.args...)
+			if err != nil {
+				t.Fatalf("get-mute-config returned error: %v", err)
+			}
+			if len(caller.calls) != 1 || !reflect.DeepEqual(caller.calls[0], test.want) {
+				t.Fatalf("tool calls = %#v, want %#v", caller.calls, test.want)
+			}
+		})
 	}
 }
 
@@ -196,12 +244,12 @@ func TestCrossPlatformCoverageChatGroupGetMuteConfigRecordsRawArgs(t *testing.T)
 	}
 }
 
-func TestCrossPlatformCoverageChatGroupGetMuteConfigRequiresGroup(t *testing.T) {
+func TestCrossPlatformCoverageChatGroupGetMuteConfigRequiresConversationID(t *testing.T) {
 	caller := &guardedMutationCaller{}
 	err := executeGuardedMutationCommand(t, caller, newChatCommand,
 		"group", "get-mute-config")
-	if err == nil || !strings.Contains(err.Error(), "--group") {
-		t.Fatalf("err = %v, want message containing --group", err)
+	if err == nil || !strings.Contains(err.Error(), "--conversation-id") {
+		t.Fatalf("err = %v, want message containing --conversation-id", err)
 	}
 	if len(caller.calls) != 0 {
 		t.Fatalf("tool calls = %#v, want none", caller.calls)

internal/helpers/drive.go

@@ -1226,7 +1226,7 @@ func newDriveCommand() *cobra.Command {
 	driveListCmd.Flags().String("node", "", "文件 ID (dentryUuid) 或 URL (--versions 模式下必填)")
 	driveListCmd.Flags().String("pattern", "", "按名称通配过滤结果，如 \"*日报*\" (客户端过滤) (可选)")
 	driveListCmd.Flags().Int("depth", 1, "递归列出子目录层级，默认 1(仅当前层)，最大 5；与 --cursor/--limit 互斥；与 --workspace 组合时走知识库递归 (可选)")
-	driveListCmd.Flags().Int("latest", 0, "按修改时间取最新 N 个文件（1~50）；与 --pattern 组合时表示名称匹配的文件中最新 N 个；可与 --workspace/--depth 组合；与 --order-by/--order/--limit/--cursor 互斥 (可选)")
+	driveListCmd.Flags().Int("latest", 0, "按修改时间取最新 N 个文件（1~50）；与 --pattern 组合时表示名称匹配的文件中最新 N 个；可与 --workspace/--depth 组合；与 --order-by/--order/--limit/--cursor 互斥；扫描触发 2000 条上限或途中目录读取失败时报错，不产出不完整的 Top-N (可选)")
 	driveListCmd.Flags().Bool("quiet", false, "关闭递归进度输出(stderr)，不影响 stdout JSON (--depth>1 或 --latest 多页扫描时有效) (可选)")
 	driveListCmd.Flags().String("type", "", "按节点类型过滤: file|folder（客户端过滤：全量扫描后筛，钉盘/知识库均可用；与 --versions/--cursor/--order-by/--order/--limit 互斥）(可选)")
 	driveListCmd.Flags().String("start", "", "按修改时间过滤·起始: 相对时间如 24h/7d/2w、RFC3339、YYYY-MM-DD（客户端过滤，互斥同 --type）(可选)")
@@ -3299,6 +3299,274 @@ func newDriveCommand() *cobra.Command {
 		RegisterCrossProductAliases(child)
 	}
 
+	driveStatusCmd := &cobra.Command{
+		Use:   "status",
+		Short: "比较本地文件夹与钉盘文件夹的差异",
+		Long: `比较本地文件夹与钉盘文件夹的差异：本地取 --local-folder（绝对路径），钉盘取
+--remote-folder（文件夹 dentryUuid）指向的文件夹，按精确 MD5（默认）或快速
+modified_time（--quick）逐文件比对。两侧各自递归遍历，rel_path 相对各自根目录。
+
+输出五类差异：
+  new_local   仅本地存在
+  new_remote  仅钉盘存在
+  modified    两侧都存在且本次检测判定为已变更
+  unchanged   两侧都存在且本次检测判定为未变更
+  unknown     两侧都存在，但 exact 模式下远端无可靠 MD5、无法核对内容（不判 unchanged/modified）
+
+只比对钉盘 type=file 的二进制文件（跳过在线文档与快捷方式）；本地只比对常规文件。`,
+		Example: `  dws drive status --local-folder /abs/path/repo --remote-folder <dentryUuid>
+  dws drive status --local-folder /abs/path/repo --remote-folder <dentryUuid> --space-id xxxx
+  dws drive status --local-folder /abs/path/repo --remote-folder <dentryUuid> --quick`,
+		RunE: runDriveStatus,
+	}
+	driveStatusCmd.Flags().String("local-folder", "", "本地文件夹绝对路径 (必填)")
+	driveStatusCmd.Flags().String("remote-folder", "", "钉盘文件夹 ID (dentryUuid) (必填)")
+	driveStatusCmd.Flags().String("space-id", "", "钉盘空间 ID，不传则使用「我的文件」(可选)")
+	driveStatusCmd.Flags().Bool("quick", false, "快速模式：只比较 modified_time，不计算 MD5 (可选)")
+
+	drivePullCmd := &cobra.Command{
+		Use:   "pull",
+		Short: "把钉盘文件夹单向镜像到本地（Drive → 本地）",
+		Long: `递归下载钉盘 --remote-folder 文件夹下所有 type=file 的文件到本地
+--local-folder 对应路径（子目录自动创建），单向、文件级镜像。
+
+已存在的本地文件按 --if-exists 处理：
+  skip       默认，安全：本地已存在则保持不动，只新增
+  smart      推荐增量同步：本地 modified_time 已 ≥ 远端时则跳过下载
+  overwrite  总是下载覆盖（Drive 作为权威源）
+
+该命令会写入本地文件系统，执行前需要用户确认；非交互环境先用 --dry-run
+预览，确认后以相同参数追加 --yes 执行。
+
+输出 summary（downloaded/skipped/failed）与逐文件 items。
+若有文件下载失败，命令以非零退出码退出，结构化结果仍在 stdout。`,
+		Example: `  dws drive pull --local-folder /abs/path/repo --remote-folder <dentryUuid>
+  dws drive pull --local-folder /abs/path/repo --remote-folder <dentryUuid> --if-exists smart
+  dws drive pull --local-folder /abs/path/repo --remote-folder <dentryUuid> --space-id xxxx`,
+		RunE: runDrivePull,
+	}
+	drivePullCmd.Flags().String("local-folder", "", "本地文件夹绝对路径 (必填)")
+	drivePullCmd.Flags().String("remote-folder", "", "钉盘文件夹 ID (dentryUuid) (必填)")
+	drivePullCmd.Flags().String("space-id", "", "钉盘空间 ID，不传则使用「我的文件」(可选)")
+	drivePullCmd.Flags().String("if-exists", "skip", "本地文件已存在时的策略: skip|smart|overwrite；命令会写本地，执行需确认 (可选)")
+
+	drivePushCmd := &cobra.Command{
+		Use:   "push",
+		Short: "把本地文件夹单向镜像到钉盘（本地 → Drive）",
+		Long: `递归把本地 --local-folder 下的文件与子目录（含空目录）镜像到钉盘
+--remote-folder 文件夹：缺失的目录按需创建（已存在则复用，不重建），文件按
+--if-exists 处理。文件级镜像——只新增/覆盖，不删除远端多余文件。
+
+已存在的远端文件按 --if-exists 处理：
+  skip       默认，安全：已存在则保持不动，只新增
+  smart      增量同步：远端 modified_time 已 ≥ 本地时跳过，否则走覆盖路径
+  overwrite  覆盖远端同名文件
+
+该命令会写入钉盘，执行前需要用户确认；非交互环境先用 --dry-run 预览，
+确认后以相同参数追加 --yes 执行。
+
+输出 summary（uploaded/skipped/failed，uploaded 含新建与覆盖）与逐条 items
+（含 folder_created）。若有文件失败，命令以非零退出码退出，结构化结果仍在 stdout。`,
+		Example: `  dws drive push --local-folder /abs/path/repo --remote-folder <dentryUuid>
+  dws drive push --local-folder /abs/path/repo --remote-folder <dentryUuid> --if-exists smart
+  dws drive push --local-folder /abs/path/repo --remote-folder <dentryUuid> --if-exists overwrite`,
+		RunE: runDrivePush,
+	}
+	drivePushCmd.Flags().String("local-folder", "", "本地文件夹绝对路径 (必填)")
+	drivePushCmd.Flags().String("remote-folder", "", "钉盘目标文件夹 ID (dentryUuid) (必填)")
+	drivePushCmd.Flags().String("space-id", "", "钉盘空间 ID，不传则使用「我的文件」(可选)")
+	drivePushCmd.Flags().String("if-exists", "skip", "远端文件已存在时的策略: skip|smart|overwrite；命令会写钉盘，执行需确认 (可选)")
+
+	driveSyncCmd := &cobra.Command{
+		Use:   "sync",
+		Short: "本地文件夹与钉盘文件夹双向同步（本地 ⇄ Drive）",
+		Long: `把本地 --local-folder 与钉盘 --remote-folder 做文件级双向同步：先按精确 MD5
+（默认）或快速 modified_time（--quick）算出差异，再按方向执行：
+  new_local   仅本地存在  → 上传到钉盘（缺失的远端目录按需创建）
+  new_remote  仅钉盘存在  → 下载到本地
+  modified    两侧都变更  → 按 --on-conflict 解决
+  unchanged   两侧一致    → 不动
+
+两侧都变更时的 --on-conflict 策略：
+  skip         默认，两侧都不动并保留两边内容
+  remote-wins  拉取远端覆盖本地
+  local-wins   上传本地覆盖远端
+  keep-both    本地文件改名保留，再拉取远端到原路径
+  ask          交互式逐个询问
+
+exact 模式下远端无可靠 MD5、内容无法核对的文件归入 unknown 并跳过（可改用 --quick）。
+文件级同步——只新增/覆盖，不删除任何一侧的多余文件。输出 summary（pulled/pushed/
+skipped/failed）、diff 与逐条 items；有失败则以非零退出码退出，结构化结果仍在 stdout。
+
+该命令会同时写入本地与钉盘，执行前需要用户确认；非交互环境先用 --dry-run
+预览，确认后以相同参数追加 --yes 执行。`,
+		Example: `  dws drive sync --local-folder /abs/path/repo --remote-folder <dentryUuid>
+  dws drive sync --local-folder /abs/path/repo --remote-folder <dentryUuid> --on-conflict local-wins
+  dws drive sync --local-folder /abs/path/repo --remote-folder <dentryUuid> --quick --on-conflict keep-both`,
+		RunE: runDriveSync,
+	}
+	driveSyncCmd.Flags().String("local-folder", "", "本地文件夹绝对路径 (必填)")
+	driveSyncCmd.Flags().String("remote-folder", "", "钉盘文件夹 ID (dentryUuid) (必填)")
+	driveSyncCmd.Flags().String("space-id", "", "钉盘空间 ID，不传则使用「我的文件」(可选)")
+	driveSyncCmd.Flags().String("on-conflict", "skip", "两侧都变更时的策略: skip|remote-wins|local-wins|keep-both|ask；命令会写双端，执行需确认 (可选)")
+	driveSyncCmd.Flags().Bool("quick", false, "快速模式：只比较 modified_time，不计算 MD5 (可选)")
+
+	DeclareLeafMetadata(driveStatusCmd, LeafSpec{
+		Safety: contract.SafetySpec{
+			Effect: "read", Risk: "low",
+			Confirmation: "not_required", Idempotency: "unknown",
+		},
+		Contract: LeafContract{
+			Identity: contract.ToolIdentitySpec{
+				ProductID:      "drive",
+				Name:           "folder_status",
+				CanonicalPath:  "drive.folder_status",
+				CLIPath:        "drive status",
+				PrimaryCLIPath: "drive status",
+			},
+			Description: "比较本地文件夹与钉盘文件夹的差异，只读不落盘。",
+			Result:      driveFolderStatusResultSpec(),
+			Interface: &contract.InterfaceSpec{
+				Mode:         "composite",
+				Availability: "available",
+				Reason:       "Reviewed composite workflow: the command recursively lists the remote folder through drive/list_files, walks the local tree, and compares both sides by MD5 or modification time; no single pinned RPC represents the diff.",
+			},
+			Selection: contract.SelectionSpec{
+				AgentSummary: "比较本地文件夹与钉盘文件夹的差异，只读不落盘。",
+				UseWhen:      []string{"需要先看清本地与钉盘之间哪些文件新增、变更或一致，再决定拉取还是推送时"},
+				AvoidWhen:    []string{"只要单个文件的元数据用 drive info；要真正传输文件用 drive pull / push / sync"},
+				Examples: []string{
+					"dws drive status --local-folder /abs/path/repo --remote-folder <dentryUuid>",
+					"dws drive status --local-folder /abs/path/repo --remote-folder <dentryUuid> --quick",
+				},
+			},
+			Parameters: []contract.ParamDecl{
+				{Name: "local-folder", Required: boolPtr(true)},
+				{Name: "remote-folder", Required: boolPtr(true)},
+			},
+		},
+	})
+	DeclareLeafMetadata(drivePullCmd, LeafSpec{
+		Safety: contract.SafetySpec{
+			Effect: "write", Risk: "high",
+			Confirmation: "user_required", Idempotency: "unknown",
+		},
+		Contract: LeafContract{
+			Identity: contract.ToolIdentitySpec{
+				ProductID:      "drive",
+				Name:           "folder_pull",
+				CanonicalPath:  "drive.folder_pull",
+				CLIPath:        "drive pull",
+				PrimaryCLIPath: "drive pull",
+			},
+			Description: "把钉盘文件夹单向镜像到本地；写操作需确认，默认跳过本地既有文件。",
+			DryRun: &contract.DryRunSpec{
+				PreviewKind: contract.DryRunPreviewPlan,
+				RemoteReads: true,
+			},
+			Result: driveFolderPullResultSpec(),
+			Interface: &contract.InterfaceSpec{
+				Mode:         "composite",
+				Availability: "available",
+				Reason:       "Reviewed composite workflow: the command recursively lists the remote folder through drive/list_files and then downloads each file through drive/download_file plus an HTTP GET into a temporary file committed by an atomic rename; no single pinned RPC represents the mirror.",
+			},
+			Selection: contract.SelectionSpec{
+				AgentSummary: "把钉盘文件夹单向镜像到本地；写操作需确认，默认跳过本地既有文件。",
+				UseWhen:      []string{"需要把整个钉盘文件夹拉到本地目录时"},
+				AvoidWhen:    []string{"只下载单个文件用 drive download；要把本地推到钉盘用 drive push；要双向对齐用 drive sync"},
+				Examples: []string{
+					"dws drive pull --local-folder /abs/path/repo --remote-folder <dentryUuid>",
+					"dws drive pull --local-folder /abs/path/repo --remote-folder <dentryUuid> --if-exists smart --dry-run",
+				},
+				ExampleDispositions: driveFolderStatefulExampleDispositions(),
+			},
+			Parameters: []contract.ParamDecl{
+				{Name: "local-folder", Required: boolPtr(true)},
+				{Name: "remote-folder", Required: boolPtr(true)},
+			},
+		},
+	})
+	DeclareLeafMetadata(drivePushCmd, LeafSpec{
+		Safety: contract.SafetySpec{
+			Effect: "write", Risk: "high",
+			Confirmation: "user_required", Idempotency: "unknown",
+		},
+		Contract: LeafContract{
+			Identity: contract.ToolIdentitySpec{
+				ProductID:      "drive",
+				Name:           "folder_push",
+				CanonicalPath:  "drive.folder_push",
+				CLIPath:        "drive push",
+				PrimaryCLIPath: "drive push",
+			},
+			Description: "把本地文件夹单向镜像到钉盘；写操作需确认，默认跳过远端既有文件。",
+			DryRun: &contract.DryRunSpec{
+				PreviewKind: contract.DryRunPreviewPlan,
+				RemoteReads: true,
+			},
+			Result: driveFolderPushResultSpec(),
+			Interface: &contract.InterfaceSpec{
+				Mode:         "composite",
+				Availability: "available",
+				Reason:       "Reviewed composite workflow: the command recursively lists the remote folder through drive/list_files, creates missing folders through drive/create_folder, and uploads each file through drive/get_upload_info plus an HTTP PUT and drive/commit_upload; no single pinned RPC represents the mirror.",
+			},
+			Selection: contract.SelectionSpec{
+				AgentSummary: "把本地文件夹单向镜像到钉盘；写操作需确认，默认跳过远端既有文件。",
+				UseWhen:      []string{"需要把整个本地目录推送到钉盘文件夹时"},
+				AvoidWhen:    []string{"只上传单个文件用 drive upload；要把钉盘拉到本地用 drive pull；要双向对齐用 drive sync"},
+				Examples: []string{
+					"dws drive push --local-folder /abs/path/repo --remote-folder <dentryUuid>",
+					"dws drive push --local-folder /abs/path/repo --remote-folder <dentryUuid> --if-exists smart --dry-run",
+				},
+				ExampleDispositions: driveFolderStatefulExampleDispositions(),
+			},
+			Parameters: []contract.ParamDecl{
+				{Name: "local-folder", Required: boolPtr(true)},
+				{Name: "remote-folder", Required: boolPtr(true)},
+			},
+		},
+	})
+	DeclareLeafMetadata(driveSyncCmd, LeafSpec{
+		Safety: contract.SafetySpec{
+			Effect: "write", Risk: "high",
+			Confirmation: "user_required", Idempotency: "unknown",
+		},
+		Contract: LeafContract{
+			Identity: contract.ToolIdentitySpec{
+				ProductID:      "drive",
+				Name:           "folder_sync",
+				CanonicalPath:  "drive.folder_sync",
+				CLIPath:        "drive sync",
+				PrimaryCLIPath: "drive sync",
+			},
+			Description: "本地与钉盘文件夹双向同步；写操作需确认，默认跳过双端冲突。",
+			DryRun: &contract.DryRunSpec{
+				PreviewKind: contract.DryRunPreviewPlan,
+				RemoteReads: true,
+			},
+			Result: driveFolderSyncResultSpec(),
+			Interface: &contract.InterfaceSpec{
+				Mode:         "composite",
+				Availability: "available",
+				Reason:       "Reviewed composite workflow: the command computes the same diff as drive status and then resolves it in both directions through drive/download_file, drive/create_folder, drive/get_upload_info and drive/commit_upload according to --on-conflict; no single pinned RPC represents the bidirectional sync.",
+			},
+			Selection: contract.SelectionSpec{
+				AgentSummary: "本地与钉盘文件夹双向同步；写操作需确认，默认跳过双端冲突。",
+				UseWhen:      []string{"需要让本地目录与钉盘文件夹互相补齐时"},
+				AvoidWhen:    []string{"只需单方向镜像用 drive pull / push；只想看差异用 drive status"},
+				Examples: []string{
+					"dws drive sync --local-folder /abs/path/repo --remote-folder <dentryUuid>",
+					"dws drive sync --local-folder /abs/path/repo --remote-folder <dentryUuid> --on-conflict remote-wins --dry-run",
+				},
+				ExampleDispositions: driveFolderStatefulExampleDispositions(),
+			},
+			Parameters: []contract.ParamDecl{
+				{Name: "local-folder", Required: boolPtr(true)},
+				{Name: "remote-folder", Required: boolPtr(true)},
+			},
+		},
+	})
+
 	driveCmd.AddCommand(
 		driveListCmd,
 		driveListSpacesCmd,
@@ -3322,6 +3590,11 @@ func newDriveCommand() *cobra.Command {
 		drivePermissionCmd,
 		drivePublishCmd,
 		recycleCmd,
+		// 同步命令：status / pull / push / sync
+		driveStatusCmd,
+		drivePullCmd,
+		drivePushCmd,
+		driveSyncCmd,
 		driveStarCmd,
 		driveCoverCmd,
 		driveRevertCmd,

internal/helpers/drive_depth.go

@@ -10,11 +10,14 @@ import (
 	"os/signal"
 	"path/filepath"
 	"sort"
+	"strconv"
 	"strings"
 	"time"
 
 	"github.com/fatih/color"
 	"github.com/spf13/cobra"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/output"
 )
 
 // ──────────────────────────────────────────────────────────
@@ -296,6 +299,11 @@ bfs:
 
 		if folderErr != nil {
 			if driveDepthUnrecoverable(folderErr) {
+				if latest > 0 {
+					// 不完整集合上的 Top-N 会被误读为全局最新：latest 下不吐 partial，
+					// 直接回根因错误（auth 过期 / 网络不可达比通用 token 更可操作）。
+					return folderErr
+				}
 				// partial 照吐 stdout，错误详情走 stderr，非零退出
 				errs = append(errs, newDriveDepthError(folder, folderErr))
 				if emitErr := emitDriveDepthResult(collected, errs, truncated, pattern, latest, maxDepth, route, filter); emitErr != nil {
@@ -331,17 +339,206 @@ bfs:
 		}
 	}
 
-	if truncated && latest > 0 {
-		return &CLIError{
-			Code:       CodeContentTruncated,
-			Message:    fmt.Sprintf("LATEST_SCAN_TRUNCATED: 扫描在全局上限 %d 条处截断，未扫描区域可能含更新文件，拒绝输出不完整的 Top-%d", driveDepthMaxItems, latest),
-			Suggestion: fmt.Sprintf("缩小扫描范围后重试：--folder 指定子目录，或降低 --depth 层数，如 dws drive list --folder <子目录ID> --latest %d", latest),
-		}
+	// BFS 序与修改时间无关：截断与递归途中目录失败都让未扫区域可能含更新文件，
+	// 此时的 Top-N 不是全局最新，两者同属一条防线——拒绝以成功状态产出。
+	if latest > 0 && (truncated || len(errs) > 0) {
+		return driveLatestIncompleteError(latest, truncated, errs, driveLatestScopeFromCmd(cmd, maxDepth, rootFolderID))
 	}
 
 	return emitDriveDepthResult(collected, errs, truncated, pattern, latest, maxDepth, route, filter)
 }
 
+// driveLatestScope 是原调用的完整候选集快照，用于生成不改变候选集的恢复命令。
+//
+// 恢复命令若丢掉任何一项，用户照抄后都会在**另一个集合**上拿到一份「看起来对」的 Top-N ——
+// 比直接报错更难发现：丢 --workspace/--space-id 会从知识库切到普通钉盘（或反之）；丢 --folder
+// 会从子树跳到空间根；丢 --pattern/--type/--start/--end 会把全部条目纳入排序基。
+type driveLatestScope struct {
+	// domain 是查询域 flag 串（如 "--workspace ws-1" / "--space-id sp-1"），无则空串。
+	domain string
+	// filters 是决定候选集的过滤 flag 串（--pattern/--type/--start/--end），无则空串。
+	filters string
+	// folder 是原调用实际使用的扫描根（已解析的 ID，非用户原始 URL），空则为空间根。
+	folder string
+	// depth 是原调用的 --depth 层数，让「去掉 --latest 重跑」的恢复命令给出确切层数。
+	depth int
+	// notes 收集无法安全内联进可执行命令的原值展示行。POSIX 构建下恒为空（单引号足够）；
+	// Windows 构建下含元字符的值走这里，命令里只留占位符。
+	notes []string
+	// 以上 domain/filters/folder 里的值全部经 driveLatestScopeValue 渲染：恢复命令是给用户
+	// 直接复制到 shell 执行的，而 workspace 的常见形态就是带 & 查询串的 URL，pattern 又天然
+	// 含 * 与中文，裸拼接会改变命令解析。
+}
+
+// driveLatestValueRenderer 把用户值渲染成可内联的命令片段；ok 为 false 表示该值在目标 shell
+// 下无法安全内联。取成参数而非直接调用平台绑定函数，是为了让任一平台的测试都能驱动另一平台
+// 的降级分支 —— 否则「Windows 上降级为占位符」这条路在 POSIX 机器上永不可达、无法验证。
+type driveLatestValueRenderer func(string) (string, bool)
+
+// value 渲染单个用户值供内联。值在目标 shell 下无法安全内联时，登记一条展示行并返回占位符
+// —— 宁可让用户手动粘一次，也不能给出一条粘贴即执行额外命令的「恢复命令」。
+// 展示行用 strconv.Quote 包裹并显式声明非可执行，与 internal/auth 侧展示 profile 标识一致。
+func (s *driveLatestScope) value(render driveLatestValueRenderer, label, v string) string {
+	if inline, ok := render(v); ok {
+		return inline
+	}
+	s.notes = append(s.notes, fmt.Sprintf("%s 原值（仅作数据展示，不是可执行命令）%s", label, strconv.Quote(v)))
+	return driveLatestUnsafeValuePlaceholder
+}
+
+// driveLatestUnsafeValuePlaceholder 是不可内联值在命令中的占位符。
+const driveLatestUnsafeValuePlaceholder = "<见下方原值>"
+
+// driveLatestScopeFromCmd 从原命令抽完整候选集。--workspace 决定路由（知识库 vs 钉盘），判定与
+// drive list 里的路由分支同源（同一个 flagOrFallback(cmd, "workspace", "workspace-id")）；
+// 钉盘侧的 --space-id 同样必须保留。目录 flag 名无需按路由切换：--folder 两条路由都接受。
+//
+// rootFolder 取 runDriveListDepth 实际使用的扫描根而非重新读 flag：用户可能传的是 URL，
+// 解析后的 ID 才是真正被扫描的目标，也是照抄时更精确的形态。
+func driveLatestScopeFromCmd(cmd *cobra.Command, depth int, rootFolder string) driveLatestScope {
+	return driveLatestScopeFrom(cmd, depth, rootFolder, driveLatestScopeValue)
+}
+
+// driveLatestScopeFrom 是 driveLatestScopeFromCmd 的可注入本体：render 决定用户值以何种形态
+// 进入恢复命令。生产路径固定传平台绑定的 driveLatestScopeValue；测试可传另一平台的策略，
+// 从而在单一平台上覆盖两种形态。
+func driveLatestScopeFrom(cmd *cobra.Command, depth int, rootFolder string, render driveLatestValueRenderer) driveLatestScope {
+	scope := driveLatestScope{depth: depth}
+	if workspaceID := flagOrFallback(cmd, "workspace", "workspace-id"); workspaceID != "" {
+		scope.domain = "--workspace " + scope.value(render, "--workspace", workspaceID)
+	} else if spaceID, _ := cmd.Flags().GetString("space-id"); spaceID != "" {
+		scope.domain = "--space-id " + scope.value(render, "--space-id", spaceID)
+	}
+	if rootFolder != "" {
+		scope.folder = scope.value(render, "--folder", rootFolder)
+	}
+	// 顺序固定为注册顺序，保证同一组入参每次给出同一条恢复命令（便于用户比对与测试断言）。
+	filters := make([]string, 0, 4)
+	for _, name := range []string{"pattern", "type", "start", "end"} {
+		if v, _ := cmd.Flags().GetString(name); v != "" {
+			filters = append(filters, "--"+name+" "+scope.value(render, "--"+name, v))
+		}
+	}
+	scope.filters = strings.Join(filters, " ")
+	return scope
+}
+
+// command 拼一条保留原候选集的恢复命令：查询域 + 指定的 --folder + 原过滤条件。
+// folderArg 传 "" 表示该条命令不带 --folder（原调用就在空间根时不应凭空塞一个）。
+func (s driveLatestScope) command(folderArg string) string {
+	parts := make([]string, 0, 4)
+	parts = append(parts, "dws drive list")
+	if s.domain != "" {
+		parts = append(parts, s.domain)
+	}
+	if folderArg != "" {
+		parts = append(parts, "--folder "+folderArg)
+	}
+	if s.filters != "" {
+		parts = append(parts, s.filters)
+	}
+	return strings.Join(parts, " ")
+}
+
+// driveLatestIncompleteError 是排序基不完整时的拒绝产出错误。截断与目录失败共用
+// CodeContentTruncated（→ ExitAPI），但 token 分开，便于消费方区分「范围太大」与「读不到」；
+// 二者同真时两个 token 都带。拒绝产出后 errors[] 不再进 stdout，失败详情必须落在错误消息里，
+// 否则用户完全瞎。调用点已保证 truncated 与 len(errs)>0 至少一真。
+func driveLatestIncompleteError(latest int, truncated bool, errs []driveDepthError, scope driveLatestScope) error {
+	// 目录失败详情排在截断之前：BFS 可以先记下可恢复目录错误、再在别的目录撞上 2000 上限，
+	// 此时 permission_denied 这类 reason 是用户唯一能动手修的线索，不能被截断提示吞掉。
+	causes := make([]string, 0, 2)
+	if len(errs) > 0 {
+		causes = append(causes, driveLatestFolderFailureCause(errs))
+	}
+	if truncated {
+		causes = append(causes, fmt.Sprintf("LATEST_SCAN_TRUNCATED: 扫描在全局上限 %d 条处截断", driveDepthMaxItems))
+	}
+	return &CLIError{
+		Code: CodeContentTruncated,
+		Message: fmt.Sprintf("%s，未扫描区域可能含更新文件，拒绝输出不完整的 Top-%d",
+			strings.Join(causes, "；同时 "), latest),
+		Suggestion: driveLatestIncompleteSuggestion(latest, truncated, len(errs) > 0, scope),
+	}
+}
+
+// driveLatestFolderFailureCause 组装目录失败详情，含首个失败的 folder/depth/reason。
+// folderName 空回落 folderID，两者都空回落 <root>。
+//
+// folderName / folderID / message 三项都是远端可控内容（目录名由共享目录的创建者决定，
+// message 是服务端错误文本），必须过 driveLatestSafeRemoteText。Reason 不用过：它是
+// classifyDriveDepthReason 的固定三值映射，与服务端字符串无关。
+func driveLatestFolderFailureCause(errs []driveDepthError) string {
+	first := errs[0]
+	folder := first.FolderName
+	if folder == "" {
+		folder = first.FolderID
+	}
+	if folder == "" {
+		folder = "<root>"
+	}
+	return fmt.Sprintf("LATEST_SCAN_INCOMPLETE: %d 个目录未读全（首个失败 folder=%s depth=%d reason=%s: %s）",
+		len(errs), driveLatestSafeRemoteText(folder), first.Depth, first.Reason,
+		driveLatestSafeRemoteText(first.Message))
+}
+
+// driveLatestSafeRemoteText 把远端可控文本压成可安全嵌进单行 stderr 错误消息的形式。
+//
+// 拒绝产出后 errors[] 不再进 stdout，失败详情改走纯文本错误消息 —— 而 JSON 编码会转义的
+// 控制字符在纯文本里会被终端直接执行：ANSI/OSC 序列可以伪造提示、清屏、隐藏后续内容、改窗口
+// 标题，在 AI Agent 场景还会污染上下文窗口。latest=0 的既有路径仍把原值放进 errors[] JSON，
+// 不受影响，也不该受影响（消费方需要原始数据）。
+//
+// output.SanitizeForTerminal 负责剥 ANSI/OSC、C0 控制字符与危险 Unicode，但按设计保留 \n 与
+// \t；本错误消息是单行叙述，故再把这两者折成空格，避免远端换行把一条错误拆成多行伪造输出。
+func driveLatestSafeRemoteText(s string) string {
+	s = output.SanitizeForTerminal(s)
+	s = strings.ReplaceAll(s, "\n", " ")
+	s = strings.ReplaceAll(s, "\t", " ")
+	return strings.TrimSpace(s)
+}
+
+// driveLatestIncompleteSuggestion 按实际触发的成因给恢复指引。约束两条：
+//  1. 每条示例命令都带原查询域（scope.base()），照抄不会切换查询域；
+//  2. 每个子句的示例命令与该子句正文一致——「去掉 --latest」的子句示例不带 --latest，
+//     否则照抄复现同一错误。
+func driveLatestIncompleteSuggestion(latest int, truncated, folderFailed bool, scope driveLatestScope) string {
+	// 「缩小范围」类命令要求用户换一个目录，故 --folder 给占位符；查询域与原过滤条件由
+	// command 一并带上，否则照抄后候选集就变了（例如丢掉 --pattern 会对全部条目取 Top-N）。
+	narrowed := scope.command("<可读子目录ID>")
+	clauses := make([]string, 0, 3)
+	if folderFailed {
+		clauses = append(clauses, "确认目录权限后重试")
+	}
+	switch {
+	case folderFailed && truncated:
+		// 两个成因都要解：既要换到可读目录，也要把范围缩到 2000 条以内。
+		clauses = append(clauses, fmt.Sprintf("或用 --folder 缩小到可读子目录、并降低 --depth 层数后重取 Top-%d：%s --latest %d", latest, narrowed, latest))
+	case folderFailed:
+		clauses = append(clauses, fmt.Sprintf("或用 --folder 缩小到可读子目录后重取 Top-%d：%s --latest %d", latest, narrowed, latest))
+	default:
+		clauses = append(clauses, fmt.Sprintf("缩小扫描范围后重试：--folder 指定子目录，或降低 --depth 层数，如 %s --latest %d", narrowed, latest))
+	}
+	// partial+errors[] 承诺限定 --depth>1：单层去掉 --latest 会路由回普通单层 list，本就无
+	// errors[] 契约，故该子句只在多层时给出，并直接带上原层数。这是唯一一条「按原范围」命令，
+	// 必须原样带回原 --folder（原调用在空间根时则不带），照抄即复现同一候选集、只是不取 Top-N。
+	if folderFailed && scope.depth > 1 {
+		clauses = append(clauses, fmt.Sprintf("需要看失败明细请去掉 --latest 按原范围重跑（同时输出已扫到的 partial 与 errors[] 明细）：%s --depth %d", scope.command(scope.folder), scope.depth))
+	}
+	// Windows 构建下无法安全引用的值不会进入命令（cmd.exe 不把单引号当引号），原值改在此处以
+	// 数据行给出，由用户手动替换占位符 —— 少一次复制粘贴的便利，换掉一条粘贴即执行的命令。
+	if len(scope.notes) > 0 {
+		clauses = append(clauses, fmt.Sprintf("命令中的 %s 请手动替换为 —— %s",
+			driveLatestUnsafeValuePlaceholder, strings.Join(scope.notes, "、")))
+	}
+	return strings.Join(clauses, "；")
+}
+
+// emitDriveDepthCancelled 处理 SIGINT 取消：吐已扫到的 partial（truncated=true）后回退出码 130。
+//
+// 这里刻意**不**套用 latest 的拒绝产出防线（只有 BFS 尾部 guard 与 unrecoverable 分支走）：
+// 取消是用户主动发起的，退出码 130 本身已明确告知结果不完整，此时 partial 是用户的预期产物而
+// 非冒充全局最新的误导。sortTime 仍由 emitDriveDepthResult 统一剥除，取消路径不例外。
 func emitDriveDepthCancelled(items []map[string]any, errs []driveDepthError, pattern string, latest, reqDepth int, route driveDepthRoute, filter driveListFilter) error {
 	if err := emitDriveDepthResult(items, errs, true, pattern, latest, reqDepth, route, filter); err != nil {
 		return err
@@ -389,6 +586,14 @@ func emitDriveDepthResult(items []map[string]any, errs []driveDepthError, trunca
 			maxDepth = d
 		}
 	}
+	// sortTime 是内部排序字段（applyDriveListLatest 排 Top-N、applyDriveListFilter 筛时间区间
+	// 时都已用完），任何输出路径都不得泄露进契约。放在这里一处覆盖三条 emit 路径：正常 emit、
+	// SIGINT 取消、unrecoverable partial。
+	// depth/parentId/rel_path 不在此处删——它们是 depth>1 的既有输出契约，
+	// stripDriveDepthDecorations 仅在单层（reqDepth==1）把这套装饰整体剥掉。
+	for _, item := range items {
+		delete(item, "sortTime")
+	}
 	if (latest > 0 || filter.active()) && reqDepth == 1 {
 		stripDriveDepthDecorations(items)
 	}

internal/helpers/drive_folder_contract.go

@@ -0,0 +1,146 @@
+// 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"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract"
+)
+
+// driveFolderStatefulExampleDispositions 明确记录文件夹镜像示例为什么只做契约校验：
+// 预览必须读取用户指定的本地目录与真实钉盘目录，无法在隔离的 Agent 示例环境中伪造。
+// DryRun 能力仍由 ContractFinal 正式发布，命令级测试负责执行并验证零写入预览。
+func driveFolderStatefulExampleDispositions() []contract.ExampleDisposition {
+	first, second := 0, 1
+	return []contract.ExampleDisposition{
+		{
+			Index:      &first,
+			Mode:       contract.ExampleDispositionModeContractOnly,
+			ReasonCode: contract.ExampleDispositionReasonStatefulPreflight,
+			Reason:     "预览需要读取用户指定的真实钉盘目录和本地文件系统状态",
+			Reviewed:   true,
+		},
+		{
+			Index:      &second,
+			Mode:       contract.ExampleDispositionModeContractOnly,
+			ReasonCode: contract.ExampleDispositionReasonStatefulPreflight,
+			Reason:     "预览需要读取用户指定的真实钉盘目录和本地文件系统状态",
+			Reviewed:   true,
+		},
+	}
+}
+
+func driveFolderStatusResultSpec() *contract.ResultSpec {
+	return &contract.ResultSpec{
+		Outcomes: []contract.ResultOutcome{
+			contract.ResultOutcomeSuccess,
+			contract.ResultOutcomeFailure,
+		},
+		DataSchema: json.RawMessage(`{
+  "type":"object",
+  "description":"本地文件夹与钉盘文件夹的差异",
+  "properties":{
+    "detection":{"type":"string","description":"差异检测模式","enum":["exact","quick"]},
+    "new_local":{"type":"array","description":"仅本地存在的文件","items":{"type":"object","properties":{"rel_path":{"type":"string","description":"相对文件路径"}},"required":["rel_path"],"additionalProperties":false}},
+    "new_remote":{"type":"array","description":"仅钉盘存在的文件","items":{"type":"object","properties":{"rel_path":{"type":"string","description":"相对文件路径"}},"required":["rel_path"],"additionalProperties":false}},
+    "modified":{"type":"array","description":"双端都存在但内容或时间不同的文件","items":{"type":"object","properties":{"rel_path":{"type":"string","description":"相对文件路径"}},"required":["rel_path"],"additionalProperties":false}},
+    "unchanged":{"type":"array","description":"双端一致的文件","items":{"type":"object","properties":{"rel_path":{"type":"string","description":"相对文件路径"}},"required":["rel_path"],"additionalProperties":false}},
+    "unknown":{"type":"array","description":"exact 模式下因缺少可靠远端哈希而无法判定的文件","items":{"type":"object","properties":{"rel_path":{"type":"string","description":"相对文件路径"}},"required":["rel_path"],"additionalProperties":false}}
+  },
+  "required":["detection","new_local","new_remote","modified","unchanged","unknown"],
+  "additionalProperties":false
+}`),
+	}
+}
+
+func driveFolderPullResultSpec() *contract.ResultSpec {
+	return &contract.ResultSpec{
+		Outcomes: []contract.ResultOutcome{
+			contract.ResultOutcomeSuccess,
+			contract.ResultOutcomePartialFailure,
+			contract.ResultOutcomeFailure,
+		},
+		DataSchema: json.RawMessage(`{
+  "type":"object",
+  "description":"钉盘文件夹拉取的执行结果或预览计划",
+  "properties":{
+    "summary":{"type":"object","description":"真实执行的动作计数","properties":{"downloaded":{"type":"integer","description":"成功下载的文件数"},"skipped":{"type":"integer","description":"按策略跳过的文件数"},"failed":{"type":"integer","description":"失败的文件数"}},"required":["downloaded","skipped","failed"],"additionalProperties":false},
+    "items":{"type":"array","description":"真实执行的逐文件结果","items":{"type":"object","properties":{"rel_path":{"type":"string","description":"相对文件路径"},"action":{"type":"string","description":"执行动作"},"error":{"type":"string","description":"失败原因"}},"required":["rel_path","action"],"additionalProperties":false}},
+    "dry_run":{"type":"boolean","description":"是否为只读预览"},
+    "executed":{"type":"boolean","description":"是否执行了写操作"},
+    "preview_kind":{"type":"string","description":"预览类型","enum":["plan"]},
+    "operation":{"type":"string","description":"预览的命令"},
+    "if_exists":{"type":"string","description":"本地同名文件处理策略"},
+    "plan":{"type":"object","description":"预览的拉取计划","properties":{"summary":{"type":"object","description":"计划动作计数","properties":{"downloaded":{"type":"integer","description":"计划下载的文件数"},"skipped":{"type":"integer","description":"计划跳过的文件数"},"failed":{"type":"integer","description":"预检失败的文件数"}},"required":["downloaded","skipped","failed"],"additionalProperties":false},"items":{"type":"array","description":"计划中的逐文件动作","items":{"type":"object","properties":{"rel_path":{"type":"string","description":"相对文件路径"},"action":{"type":"string","description":"计划动作"},"error":{"type":"string","description":"预检失败原因"}},"required":["rel_path","action"],"additionalProperties":false}}},"required":["summary","items"],"additionalProperties":false}
+  },
+  "additionalProperties":false
+}`),
+	}
+}
+
+func driveFolderPushResultSpec() *contract.ResultSpec {
+	return &contract.ResultSpec{
+		Outcomes: []contract.ResultOutcome{
+			contract.ResultOutcomeSuccess,
+			contract.ResultOutcomePartialFailure,
+			contract.ResultOutcomeFailure,
+		},
+		DataSchema: json.RawMessage(`{
+  "type":"object",
+  "description":"本地文件夹推送的执行结果或预览计划",
+  "properties":{
+    "summary":{"type":"object","description":"真实执行的动作计数","properties":{"uploaded":{"type":"integer","description":"成功上传或覆盖的文件数"},"skipped":{"type":"integer","description":"按策略跳过的文件数"},"failed":{"type":"integer","description":"失败的条目数"},"aborted":{"type":"boolean","description":"是否因失败中止后续上传"}},"required":["uploaded","skipped","failed","aborted"],"additionalProperties":false},
+    "items":{"type":"array","description":"真实执行的逐条目结果","items":{"type":"object","properties":{"rel_path":{"type":"string","description":"相对文件或目录路径"},"action":{"type":"string","description":"执行动作"},"size_bytes":{"type":"integer","description":"文件字节数"},"error":{"type":"string","description":"失败原因"}},"required":["rel_path","action"],"additionalProperties":false}},
+    "dry_run":{"type":"boolean","description":"是否为只读预览"},
+    "executed":{"type":"boolean","description":"是否执行了写操作"},
+    "preview_kind":{"type":"string","description":"预览类型","enum":["plan"]},
+    "operation":{"type":"string","description":"预览的命令"},
+    "if_exists":{"type":"string","description":"远端同名文件处理策略"},
+    "plan":{"type":"object","description":"预览的推送计划","properties":{"summary":{"type":"object","description":"计划动作计数","properties":{"uploaded":{"type":"integer","description":"计划上传或覆盖的文件数"},"skipped":{"type":"integer","description":"计划跳过的文件数"},"failed":{"type":"integer","description":"预检失败的条目数"},"aborted":{"type":"boolean","description":"计划是否会中止"}},"required":["uploaded","skipped","failed","aborted"],"additionalProperties":false},"items":{"type":"array","description":"计划中的逐条目动作","items":{"type":"object","properties":{"rel_path":{"type":"string","description":"相对文件或目录路径"},"action":{"type":"string","description":"计划动作"},"size_bytes":{"type":"integer","description":"文件字节数"},"error":{"type":"string","description":"预检失败原因"}},"required":["rel_path","action"],"additionalProperties":false}}},"required":["summary","items"],"additionalProperties":false}
+  },
+  "additionalProperties":false
+}`),
+	}
+}
+
+func driveFolderSyncResultSpec() *contract.ResultSpec {
+	return &contract.ResultSpec{
+		Outcomes: []contract.ResultOutcome{
+			contract.ResultOutcomeSuccess,
+			contract.ResultOutcomePartialFailure,
+			contract.ResultOutcomeFailure,
+		},
+		DataSchema: json.RawMessage(`{
+  "type":"object",
+  "description":"本地与钉盘双向同步的执行结果或预览计划",
+  "properties":{
+    "detection":{"type":"string","description":"差异检测模式","enum":["exact","quick"]},
+    "diff":{"type":"object","description":"同步前的双端差异","properties":{"new_local":{"type":"array","description":"仅本地存在的文件","items":{"type":"object","properties":{"rel_path":{"type":"string","description":"相对文件路径"}},"required":["rel_path"],"additionalProperties":false}},"new_remote":{"type":"array","description":"仅钉盘存在的文件","items":{"type":"object","properties":{"rel_path":{"type":"string","description":"相对文件路径"}},"required":["rel_path"],"additionalProperties":false}},"modified":{"type":"array","description":"双端都存在但内容或时间不同的文件","items":{"type":"object","properties":{"rel_path":{"type":"string","description":"相对文件路径"}},"required":["rel_path"],"additionalProperties":false}},"unchanged":{"type":"array","description":"双端一致的文件","items":{"type":"object","properties":{"rel_path":{"type":"string","description":"相对文件路径"}},"required":["rel_path"],"additionalProperties":false}},"unknown":{"type":"array","description":"exact 模式下因缺少可靠远端哈希而无法判定的文件","items":{"type":"object","properties":{"rel_path":{"type":"string","description":"相对文件路径"}},"required":["rel_path"],"additionalProperties":false}}},"required":["new_local","new_remote","modified","unchanged","unknown"],"additionalProperties":false},
+    "summary":{"type":"object","description":"真实执行的动作计数","properties":{"pulled":{"type":"integer","description":"成功拉取的条目数"},"pushed":{"type":"integer","description":"成功推送的条目数"},"skipped":{"type":"integer","description":"跳过的条目数"},"failed":{"type":"integer","description":"失败的条目数"}},"required":["pulled","pushed","skipped","failed"],"additionalProperties":false},
+    "items":{"type":"array","description":"真实执行的逐条目结果","items":{"type":"object","properties":{"rel_path":{"type":"string","description":"相对文件或目录路径"},"action":{"type":"string","description":"执行动作"},"direction":{"type":"string","description":"同步方向"},"error":{"type":"string","description":"失败或跳过原因"}},"required":["rel_path","action"],"additionalProperties":false}},
+    "dry_run":{"type":"boolean","description":"是否为只读预览","const":true},
+    "executed":{"type":"boolean","description":"是否执行了写操作","const":false},
+    "preview_kind":{"type":"string","description":"预览类型","enum":["plan"]},
+    "operation":{"type":"string","description":"预览的命令","const":"drive sync"},
+    "plan":{"type":"object","description":"预览的同步计划","properties":{"detection":{"type":"string","description":"计划使用的差异检测模式","enum":["exact","quick"]},"diff":{"type":"object","description":"计划执行前的双端差异","properties":{"new_local":{"type":"array","description":"仅本地存在的文件","items":{"type":"object","properties":{"rel_path":{"type":"string","description":"相对文件路径"}},"required":["rel_path"],"additionalProperties":false}},"new_remote":{"type":"array","description":"仅钉盘存在的文件","items":{"type":"object","properties":{"rel_path":{"type":"string","description":"相对文件路径"}},"required":["rel_path"],"additionalProperties":false}},"modified":{"type":"array","description":"双端都存在但内容或时间不同的文件","items":{"type":"object","properties":{"rel_path":{"type":"string","description":"相对文件路径"}},"required":["rel_path"],"additionalProperties":false}},"unchanged":{"type":"array","description":"双端一致的文件","items":{"type":"object","properties":{"rel_path":{"type":"string","description":"相对文件路径"}},"required":["rel_path"],"additionalProperties":false}},"unknown":{"type":"array","description":"exact 模式下因缺少可靠远端哈希而无法判定的文件","items":{"type":"object","properties":{"rel_path":{"type":"string","description":"相对文件路径"}},"required":["rel_path"],"additionalProperties":false}}},"required":["new_local","new_remote","modified","unchanged","unknown"],"additionalProperties":false},"summary":{"type":"object","description":"计划动作计数","properties":{"pulled":{"type":"integer","description":"计划拉取的条目数"},"pushed":{"type":"integer","description":"计划推送的条目数"},"skipped":{"type":"integer","description":"计划跳过的条目数"},"failed":{"type":"integer","description":"预检失败的条目数"}},"required":["pulled","pushed","skipped","failed"],"additionalProperties":false},"items":{"type":"array","description":"计划中的逐条目动作","items":{"type":"object","properties":{"rel_path":{"type":"string","description":"相对文件或目录路径"},"action":{"type":"string","description":"计划动作"},"direction":{"type":"string","description":"同步方向"},"error":{"type":"string","description":"失败或跳过原因"}},"required":["rel_path","action"],"additionalProperties":false}}},"required":["detection","diff","summary","items"],"additionalProperties":false}
+  },
+  "oneOf":[
+    {"required":["detection","diff","summary","items"]},
+    {"required":["dry_run","executed","preview_kind","operation","plan"]}
+  ],
+  "additionalProperties":false
+}`),
+	}
+}

internal/helpers/drive_folder_contract_test.go

@@ -0,0 +1,182 @@
+// 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"
+	"reflect"
+	"sort"
+	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contractfinal"
+)
+
+func TestCrossPlatformCoverageDriveFolderContractsPublishResultAndDryRun(t *testing.T) {
+	drive := newDriveCommand()
+	want := map[string]struct {
+		canonical  string
+		dryRun     bool
+		outcomes   []contract.ResultOutcome
+		properties []string
+	}{
+		"status": {
+			canonical:  "drive.folder_status",
+			outcomes:   []contract.ResultOutcome{contract.ResultOutcomeSuccess, contract.ResultOutcomeFailure},
+			properties: []string{"detection", "modified", "new_local", "new_remote", "unchanged", "unknown"},
+		},
+		"pull": {
+			canonical:  "drive.folder_pull",
+			dryRun:     true,
+			outcomes:   []contract.ResultOutcome{contract.ResultOutcomeSuccess, contract.ResultOutcomePartialFailure, contract.ResultOutcomeFailure},
+			properties: []string{"dry_run", "executed", "if_exists", "items", "operation", "plan", "preview_kind", "summary"},
+		},
+		"push": {
+			canonical:  "drive.folder_push",
+			dryRun:     true,
+			outcomes:   []contract.ResultOutcome{contract.ResultOutcomeSuccess, contract.ResultOutcomePartialFailure, contract.ResultOutcomeFailure},
+			properties: []string{"dry_run", "executed", "if_exists", "items", "operation", "plan", "preview_kind", "summary"},
+		},
+		"sync": {
+			canonical:  "drive.folder_sync",
+			dryRun:     true,
+			outcomes:   []contract.ResultOutcome{contract.ResultOutcomeSuccess, contract.ResultOutcomePartialFailure, contract.ResultOutcomeFailure},
+			properties: []string{"detection", "diff", "dry_run", "executed", "items", "operation", "plan", "preview_kind", "summary"},
+		},
+	}
+
+	for name, expectation := range want {
+		t.Run(name, func(t *testing.T) {
+			leaf, _, err := drive.Find([]string{name})
+			if err != nil || leaf == nil {
+				t.Fatalf("find drive %s: command=%v err=%v", name, leaf, err)
+			}
+			final, ok := contractfinal.RuntimeContractFinal(leaf)
+			if !ok || final.Identity == nil || final.Identity.CanonicalPath != expectation.canonical {
+				t.Fatalf("drive %s ContractFinal identity = %#v", name, final.Identity)
+			}
+			if final.Result == nil || !reflect.DeepEqual(final.Result.Outcomes, expectation.outcomes) {
+				t.Fatalf("drive %s result = %#v, want outcomes %#v", name, final.Result, expectation.outcomes)
+			}
+			properties := resultSchemaProperties(t, final.Result.DataSchema)
+			if got := sortedContractSchemaKeys(properties); !reflect.DeepEqual(got, expectation.properties) {
+				t.Fatalf("drive %s result properties = %#v, want %#v", name, got, expectation.properties)
+			}
+			if expectation.dryRun {
+				if final.DryRun == nil || final.DryRun.PreviewKind != contract.DryRunPreviewPlan || !final.DryRun.RemoteReads {
+					t.Fatalf("drive %s dry_run = %#v, want remote-reading plan", name, final.DryRun)
+				}
+				if final.Selection == nil || len(final.Selection.ExampleDispositions) != len(final.Selection.Examples) {
+					t.Fatalf("drive %s stateful example dispositions = %#v", name, final.Selection)
+				}
+				for _, disposition := range final.Selection.ExampleDispositions {
+					if disposition.Mode != contract.ExampleDispositionModeContractOnly ||
+						disposition.ReasonCode != contract.ExampleDispositionReasonStatefulPreflight || !disposition.Reviewed {
+						t.Fatalf("drive %s invalid example disposition: %#v", name, disposition)
+					}
+				}
+			} else if final.DryRun != nil {
+				t.Fatalf("drive %s unexpectedly publishes dry_run: %#v", name, final.DryRun)
+			}
+
+			if name == "sync" {
+				assertDriveSyncResultSchema(t, final.Result.DataSchema)
+			}
+		})
+	}
+}
+
+func resultSchemaProperties(t *testing.T, raw json.RawMessage) map[string]any {
+	t.Helper()
+	var schema map[string]any
+	if err := json.Unmarshal(raw, &schema); err != nil {
+		t.Fatalf("result data_schema is not JSON: %v\n%s", err, raw)
+	}
+	properties, ok := schema["properties"].(map[string]any)
+	if !ok {
+		t.Fatalf("result data_schema.properties = %#v, want object", schema["properties"])
+	}
+	return properties
+}
+
+func sortedContractSchemaKeys(values map[string]any) []string {
+	keys := make([]string, 0, len(values))
+	for key := range values {
+		keys = append(keys, key)
+	}
+	sort.Strings(keys)
+	return keys
+}
+
+func assertDriveSyncResultSchema(t *testing.T, raw json.RawMessage) {
+	t.Helper()
+	properties := resultSchemaProperties(t, raw)
+	diff := schemaObjectProperty(t, properties, "diff")
+	assertSchemaRequired(t, diff, "new_local", "new_remote", "modified", "unchanged", "unknown")
+	if got := sortedContractSchemaKeys(schemaProperties(t, diff)); !reflect.DeepEqual(got, []string{"modified", "new_local", "new_remote", "unchanged", "unknown"}) {
+		t.Fatalf("sync diff properties = %#v", got)
+	}
+
+	plan := schemaObjectProperty(t, properties, "plan")
+	assertSchemaRequired(t, plan, "detection", "diff", "summary", "items")
+	planProperties := schemaProperties(t, plan)
+	planDiff := schemaObjectProperty(t, planProperties, "diff")
+	assertSchemaRequired(t, planDiff, "new_local", "new_remote", "modified", "unchanged", "unknown")
+
+	var schema map[string]any
+	if err := json.Unmarshal(raw, &schema); err != nil {
+		t.Fatal(err)
+	}
+	oneOf, ok := schema["oneOf"].([]any)
+	if !ok || len(oneOf) != 2 {
+		t.Fatalf("sync result oneOf = %#v, want execution/dry-run alternatives", schema["oneOf"])
+	}
+}
+
+func schemaObjectProperty(t *testing.T, properties map[string]any, name string) map[string]any {
+	t.Helper()
+	property, ok := properties[name].(map[string]any)
+	if !ok || property["type"] != "object" {
+		t.Fatalf("schema property %s = %#v, want object", name, properties[name])
+	}
+	return property
+}
+
+func schemaProperties(t *testing.T, schema map[string]any) map[string]any {
+	t.Helper()
+	properties, ok := schema["properties"].(map[string]any)
+	if !ok {
+		t.Fatalf("schema properties = %#v, want object", schema["properties"])
+	}
+	return properties
+}
+
+func assertSchemaRequired(t *testing.T, schema map[string]any, want ...string) {
+	t.Helper()
+	raw, ok := schema["required"].([]any)
+	if !ok {
+		t.Fatalf("schema required = %#v", schema["required"])
+	}
+	got := make([]string, 0, len(raw))
+	for _, value := range raw {
+		text, ok := value.(string)
+		if !ok {
+			t.Fatalf("schema required value = %#v, want string", value)
+		}
+		got = append(got, text)
+	}
+	if !reflect.DeepEqual(got, want) {
+		t.Fatalf("schema required = %#v, want %#v", got, want)
+	}
+}

internal/helpers/drive_latest_incomplete_test.go

@@ -0,0 +1,731 @@
+package helpers
+
+import (
+	"errors"
+	"fmt"
+	"strconv"
+	"strings"
+	"testing"
+
+	"github.com/spf13/cobra"
+)
+
+// 本文件锁定 drive list --latest 的两个 P1 行为，独立于 pr868_*_test.go / drive_depth_test.go：
+//
+//	P1-a：sortTime 是内部排序字段，任何输出路径都不得泄露进契约；
+//	P1-b：递归途中目录读取失败时，Top-N 建立在不完整集合上，必须拒绝产出而非吐 partial。
+//
+// 改代码前这些断言对 origin/main 应为红：main 采集端无条件写 sortTime、emit 仅在单层
+// latest/filter 才剥；main 尾部拒绝 guard 只拦截断、不拦目录失败。
+//
+// 另锁定评审反馈的三个边界：
+//
+//	截断与目录失败同真时，失败详情（permission_denied 等）不得被截断提示吞掉；
+//	拒绝产出时给的恢复命令必须保留原查询域（--workspace / --space-id），照抄不会切换查询域；
+//	恢复命令里的用户值必须过 argv 引用，URL 查询串与 shell 元字符都不能改变命令解析。
+//
+// 关于 TestCrossPlatformCoverage 前缀：这是门禁约定，不是命名风格。平台覆盖率门禁
+// scripts/policy/run-platform-coverage-gate.sh 只跑
+// -run '^(TestAllShortcuts|TestCrossPlatformCoverage)'，本包新增的生产代码若没有带该前缀的
+// 测试覆盖，Coverage (macOS) / (Windows) 会以「changed code coverage 低于 100%」失败
+// （本 PR 改名前实测 69.0476%，84 条可执行语句）。改名务必保留前缀。
+
+// assertNoSortTime 断言 stdout 每个 item 都不含内部排序字段 sortTime。
+func assertNoSortTime(t *testing.T, result map[string]any) {
+	t.Helper()
+	items, ok := result["items"].([]any)
+	if !ok {
+		t.Fatalf("items missing or wrong type: %#v", result["items"])
+	}
+	for i, raw := range items {
+		item, ok := raw.(map[string]any)
+		if !ok {
+			t.Fatalf("item[%d] not an object: %#v", i, raw)
+		}
+		if _, leaked := item["sortTime"]; leaked {
+			t.Fatalf("item[%d] leaked internal sortTime into output contract: %#v", i, item)
+		}
+	}
+}
+
+// TestCrossPlatformCoverageDriveLatestNoSortTimeLeak 覆盖 main 的覆盖漏洞：main 的
+// TestCrossPlatformCoverageDriveDepthLatestTruncatedAndSortTime 名字带 SortTime，
+// 却只断言 TRUNCATED、从不检查输出无 sortTime。这里把三条泄露路径都钉住。
+func TestCrossPlatformCoverageDriveLatestNoSortTimeLeak(t *testing.T) {
+	twoFiles := `{"items":[{"fileId":"f1","name":"a.txt","type":"FILE","modifiedTime":1000},{"fileId":"f2","name":"b.txt","type":"FILE","modifiedTime":2000}]}`
+
+	// 场景 A：depth>1 --latest —— 走 applyDriveListLatest（只读 sortTime、不剥），reqDepth>1 不触发 strip。
+	t.Run("depth_latest", func(t *testing.T) {
+		useDriveDepthArgs(t)
+		caller := &scriptedToolCaller{steps: []scriptedToolStep{{text: twoFiles}}}
+		out := installDepthCaller(t, caller)
+		cmd := &cobra.Command{Use: "list"}
+		if err := runDriveListDepth(cmd, newDrivePanDepthRoute(), map[string]any{}, "", 3, "", true, 5, driveListFilter{}); err != nil {
+			t.Fatalf("runDriveListDepth: %v", err)
+		}
+		assertNoSortTime(t, decodeDepthResult(t, out))
+	})
+
+	// 场景 B：--depth 2 无 latest 无 filter —— 走 else 分支树序排序，同样不触发 strip。
+	t.Run("depth_no_latest", func(t *testing.T) {
+		useDriveDepthArgs(t)
+		caller := &scriptedToolCaller{steps: []scriptedToolStep{{text: twoFiles}}}
+		out := installDepthCaller(t, caller)
+		cmd := &cobra.Command{Use: "list"}
+		if err := runDriveListDepth(cmd, newDrivePanDepthRoute(), map[string]any{}, "", 2, "", true, 0, driveListFilter{}); err != nil {
+			t.Fatalf("runDriveListDepth: %v", err)
+		}
+		assertNoSortTime(t, decodeDepthResult(t, out))
+	})
+
+	// 场景 C：--depth 2 --type file —— #971 引入的 filter 也读 sortTime（applyDriveListFilter），
+	// strip 条件 (latest>0||filter.active()) && reqDepth==1 在多层下依旧不成立，泄露面因此变大。
+	t.Run("depth_filter_no_latest", func(t *testing.T) {
+		useDriveDepthArgs(t)
+		caller := &scriptedToolCaller{steps: []scriptedToolStep{{text: twoFiles}}}
+		out := installDepthCaller(t, caller)
+		cmd := &cobra.Command{Use: "list"}
+		if err := runDriveListDepth(cmd, newDrivePanDepthRoute(), map[string]any{}, "", 2, "", true, 0, driveListFilter{nodeType: "file"}); err != nil {
+			t.Fatalf("runDriveListDepth: %v", err)
+		}
+		result := decodeDepthResult(t, out)
+		if len(result["items"].([]any)) != 2 {
+			t.Fatalf("filter 应保留两个 FILE: %#v", result["items"])
+		}
+		assertNoSortTime(t, result)
+	})
+}
+
+// TestCrossPlatformCoverageDriveLatestSigintStillEmitsPartialWithoutSortTime 同时承担两件事：
+//  1. P1-a 的第四条路径 —— SIGINT 取消也走 emitDriveDepthResult，同样不得泄露 sortTime；
+//  2. SIGINT 契约锁 —— 本次 P1-b 只在 BFS 尾部 guard 与 unrecoverable 分支生效，**不改**
+//     取消路径：SIGINT 是用户主动中断、退出码 130 已明确告知不完整，partial 是明确预期。
+//     这条测试防止后续误把 fail-closed 扩到取消路径，也为外部评测用例
+//     test_sigint_exits_130_with_partial 提供本地对照。
+func TestCrossPlatformCoverageDriveLatestSigintStillEmitsPartialWithoutSortTime(t *testing.T) {
+	caller := &scriptedToolCaller{}
+	out := installDepthCaller(t, caller)
+	items := []map[string]any{
+		{"fileId": "f1", "name": "a.txt", "type": "FILE", "sortTime": int64(2000), "rel_path": "a.txt", "depth": 2},
+	}
+	errs := []driveDepthError{
+		{Depth: 1, FolderID: "fid-1", FolderName: "半路目录", Reason: "permission_denied", Message: "denied"},
+	}
+	// latest>0 且 reqDepth>1：main 在此不 strip，sortTime 泄露。
+	err := emitDriveDepthCancelled(items, errs, "", 5, 3, newDrivePanDepthRoute(), driveListFilter{})
+	var cancelErr *driveDepthCancelledError
+	if !errors.As(err, &cancelErr) {
+		t.Fatalf("err = %T %v, want driveDepthCancelledError", err, err)
+	}
+	if cancelErr.ExitCode() != 130 {
+		t.Fatalf("exit code = %d, want 130", cancelErr.ExitCode())
+	}
+	result := decodeDepthResult(t, out)
+	// partial 契约不变：items 与 errors 都照吐，truncated 标记为真。
+	if len(result["items"].([]any)) != 1 {
+		t.Fatalf("取消路径应保留 partial items: %#v", result["items"])
+	}
+	if len(result["errors"].([]any)) != 1 {
+		t.Fatalf("取消路径应保留 errors[]: %#v", result["errors"])
+	}
+	if result["truncated"] != true {
+		t.Fatalf("取消结果 truncated = %#v, want true", result["truncated"])
+	}
+	assertNoSortTime(t, result)
+}
+
+// TestCrossPlatformCoverageDriveLatestRefusesOnFolderFailure 覆盖 P1-b：递归途中一个可恢复目录失败（403/business，
+// 非 auth 非限流 → 记 errs[] 跳过），Top-N 落在不完整集合上，必须拒绝产出。
+// 构造：根目录成功产出 FOLDER+FILE（collected>0 且 dirA 入队），子目录返回 forbidden.* →
+// recoverable → errs=[1]。旧代码尾部 `if truncated && latest>0` 不触发 → emit 吐 partial（err=nil）；
+// 新代码 `len(errs)>0` → LATEST_SCAN_INCOMPLETE 且 stdout 无 items。
+func TestCrossPlatformCoverageDriveLatestRefusesOnFolderFailure(t *testing.T) {
+	useDriveDepthArgs(t)
+	caller := &scriptedToolCaller{steps: []scriptedToolStep{
+		{text: `{"items":[{"fileId":"dirA","name":"dirA","type":"FOLDER"},{"fileId":"fX","name":"x.txt","type":"FILE","modifiedTime":1000}]}`},
+		{text: `{"errorCode":"forbidden.noPermission","errorMsg":"denied"}`},
+	}}
+	out := installDepthCaller(t, caller)
+	cmd := &cobra.Command{Use: "list"}
+	err := runDriveListDepth(cmd, newDrivePanDepthRoute(), map[string]any{}, "", 3, "", true, 5, driveListFilter{})
+	if err == nil || !strings.Contains(err.Error(), "LATEST_SCAN_INCOMPLETE") {
+		t.Fatalf("err = %v, want LATEST_SCAN_INCOMPLETE", err)
+	}
+	// 拒绝产出：stdout 必须没有 items（不是 partial）。旧代码此处会吐 partial，断言随之失败。
+	if out.Len() != 0 {
+		t.Fatalf("expected no stdout on refusal, got: %s", out.String())
+	}
+}
+
+// TestCrossPlatformCoverageDriveLatestRefusesOnTruncationWithFolderFailure 端到端证明「截断 + 目录失败」组合确实可达：
+// 根目录出 dirA/dirB 两个子目录 → dirA 权限失败记 errs[] → dirB 返回 2000 条触发全局截断，
+// 尾部 guard 拿到 truncated=true 且 len(errs)=1。旧实现在此让 truncated 短路，permission_denied
+// 详情整块丢失（评审反馈的阻塞点）；现在两个 token 与失败详情都必须在。
+func TestCrossPlatformCoverageDriveLatestRefusesOnTruncationWithFolderFailure(t *testing.T) {
+	useDriveDepthArgs(t)
+	var bulk strings.Builder
+	bulk.WriteString(`{"items":[`)
+	for i := 0; i < driveDepthMaxItems; i++ {
+		if i > 0 {
+			bulk.WriteString(",")
+		}
+		fmt.Fprintf(&bulk, `{"fileId":"f%d","name":"file-%d.txt","type":"FILE","modifiedTime":%d}`, i, i, 1000+i)
+	}
+	bulk.WriteString(`]}`)
+	caller := &scriptedToolCaller{steps: []scriptedToolStep{
+		{text: `{"items":[{"fileId":"dirA","name":"报表","type":"FOLDER"},{"fileId":"dirB","name":"dirB","type":"FOLDER"}]}`},
+		{text: `{"errorCode":"forbidden.noPermission","errorMsg":"denied"}`}, // dirA：可恢复 → 记 errs[]
+		{text: bulk.String()}, // dirB：撞 2000 上限 → truncated
+	}}
+	out := installDepthCaller(t, caller)
+	cmd := &cobra.Command{Use: "list"}
+	err := runDriveListDepth(cmd, newDrivePanDepthRoute(), map[string]any{}, "", 3, "", true, 5, driveListFilter{})
+	var cliErr *CLIError
+	if !errors.As(err, &cliErr) || cliErr.Code != CodeContentTruncated {
+		t.Fatalf("err = %T %v, want CodeContentTruncated", err, err)
+	}
+	msg := cliErr.Message
+	if !strings.Contains(msg, "LATEST_SCAN_TRUNCATED") {
+		t.Fatalf("组合场景缺 TRUNCATED token: %q", msg)
+	}
+	// 旧实现在这里丢掉整段目录失败详情。
+	if !strings.Contains(msg, "LATEST_SCAN_INCOMPLETE") ||
+		!strings.Contains(msg, "folder=报表") ||
+		!strings.Contains(msg, "permission_denied") {
+		t.Fatalf("组合场景丢失目录失败详情: %q", msg)
+	}
+	if out.Len() != 0 {
+		t.Fatalf("expected no stdout on refusal, got: %s", out.String())
+	}
+}
+
+// TestCrossPlatformCoverageDriveLatestScopeWiredFromCommand 端到端验证查询域从原命令一路带到恢复命令：单测构造器
+// 拿不到的是 runDriveListDepth 里的接线（driveLatestScopeFromCmd(cmd, maxDepth, rootFolderID)），这里补上。
+func TestCrossPlatformCoverageDriveLatestScopeWiredFromCommand(t *testing.T) {
+	useDriveDepthArgs(t)
+	caller := &scriptedToolCaller{steps: []scriptedToolStep{
+		{text: `{"items":[{"fileId":"dirA","name":"dirA","type":"FOLDER"},{"fileId":"fX","name":"x.txt","type":"FILE","modifiedTime":1000}]}`},
+		{text: `{"errorCode":"forbidden.noPermission","errorMsg":"denied"}`},
+	}}
+	installDepthCaller(t, caller)
+	cmd := newDriveListScopeCmd(t, map[string]string{"space-id": "sp-7"})
+	err := runDriveListDepth(cmd, newDrivePanDepthRoute(), map[string]any{"spaceId": "sp-7"}, "", 4, "", true, 5, driveListFilter{})
+	var cliErr *CLIError
+	if !errors.As(err, &cliErr) {
+		t.Fatalf("err = %T %v", err, err)
+	}
+	// 恢复命令必须带原 --space-id，且给出原 --depth 层数。
+	assertDriveLatestSuggestion(t, cliErr.Suggestion, "--space-id sp-7")
+	if !strings.Contains(cliErr.Suggestion, "--depth 4") {
+		t.Fatalf("恢复命令应保留原层数: %q", cliErr.Suggestion)
+	}
+}
+
+// TestCrossPlatformCoverageDriveLatestRefusesOnUnrecoverableFailure 覆盖 P1-b 的另一半：递归途中遇不可恢复错误
+// （auth 过期 / 网络不可达）且 latest>0 时，不吐 partial，直接回根因错误。
+// 与 latest=0 的既有行为（TestCrossPlatformCoverageRunDriveListDepthUnrecoverable：partial
+// + errors[] 进 stdout 后非零退出）对照——latest 下 partial 的 Top-N 会被误读为全局最新，
+// 故必须拒绝产出；回根因错误而非 INCOMPLETE token，因为 auth/网络比通用截断提示更可操作。
+func TestCrossPlatformCoverageDriveLatestRefusesOnUnrecoverableFailure(t *testing.T) {
+	useDriveDepthArgs(t)
+	caller := &scriptedToolCaller{steps: []scriptedToolStep{
+		{text: `{"items":[{"fileId":"dirA","name":"dirA","type":"FOLDER"},{"fileId":"fX","name":"x.txt","type":"FILE","modifiedTime":1000}]}`},
+		{text: `{"errorCode":"DWS_SERVICE_UNAUTHORIZED"}`},
+	}}
+	out := installDepthCaller(t, caller)
+	cmd := &cobra.Command{Use: "list"}
+	err := runDriveListDepth(cmd, newDrivePanDepthRoute(), map[string]any{}, "", 3, "", true, 5, driveListFilter{})
+	// 回根因错误：Code 仍是 auth 过期，不被包装成 LATEST_SCAN_INCOMPLETE。
+	var cliErr *CLIError
+	if !errors.As(err, &cliErr) || cliErr.Code != CodeAuthTokenExpired {
+		t.Fatalf("err = %T %v, want CodeAuthTokenExpired", err, err)
+	}
+	if strings.Contains(cliErr.Message, "LATEST_SCAN_INCOMPLETE") {
+		t.Fatalf("unrecoverable 应回根因错误而非 INCOMPLETE 包装: %q", cliErr.Message)
+	}
+	// 拒绝产出：不吐 partial（对照 latest=0 时会输出 2 条 items + 1 条 errors）。
+	if out.Len() != 0 {
+		t.Fatalf("expected no stdout on refusal, got: %s", out.String())
+	}
+}
+
+// TestCrossPlatformCoverageDriveLatestIncompleteErrorBranches 直接单测构造器的各条分支。
+func TestCrossPlatformCoverageDriveLatestIncompleteErrorBranches(t *testing.T) {
+	// 纯截断分支：errs 为空 → 只有 TRUNCATED。
+	t.Run("truncated_only", func(t *testing.T) {
+		err := driveLatestIncompleteError(5, true, nil, driveLatestScope{depth: 3})
+		var cliErr *CLIError
+		if !errors.As(err, &cliErr) || cliErr.Code != CodeContentTruncated {
+			t.Fatalf("err = %T %v, want CodeContentTruncated", err, err)
+		}
+		if !strings.Contains(cliErr.Message, "LATEST_SCAN_TRUNCATED") {
+			t.Fatalf("message = %q", cliErr.Message)
+		}
+		if strings.Contains(cliErr.Message, "LATEST_SCAN_INCOMPLETE") {
+			t.Fatalf("无目录失败时不应出现 INCOMPLETE: %q", cliErr.Message)
+		}
+		assertDriveLatestSuggestion(t, cliErr.Suggestion, "")
+	})
+
+	// 纯目录失败分支：未截断 → 只有 INCOMPLETE，Message 含首个失败的 folder/depth/reason。
+	t.Run("folder_failure_only", func(t *testing.T) {
+		err := driveLatestIncompleteError(3, false, twoDriveDepthErrors(), driveLatestScope{depth: 3})
+		var cliErr *CLIError
+		if !errors.As(err, &cliErr) || cliErr.Code != CodeContentTruncated {
+			t.Fatalf("err = %T %v, want CodeContentTruncated", err, err)
+		}
+		msg := cliErr.Message
+		if !strings.Contains(msg, "LATEST_SCAN_INCOMPLETE") ||
+			!strings.Contains(msg, "报表") ||
+			!strings.Contains(msg, "depth=2") ||
+			!strings.Contains(msg, "permission_denied") ||
+			!strings.Contains(msg, "2 个目录未读全") {
+			t.Fatalf("message = %q", msg)
+		}
+		if strings.Contains(msg, "LATEST_SCAN_TRUNCATED") {
+			t.Fatalf("未截断时不应出现 TRUNCATED: %q", msg)
+		}
+		assertDriveLatestSuggestion(t, cliErr.Suggestion, "")
+	})
+
+	// 组合分支（评审反馈的阻塞点）：截断与目录失败同真时，旧实现让 truncated 短路、
+	// permission_denied 这类目录失败详情整块丢失。现在两个 token 都必须在，且失败详情不得被吞。
+	t.Run("truncated_with_folder_failures", func(t *testing.T) {
+		err := driveLatestIncompleteError(4, true, twoDriveDepthErrors(), driveLatestScope{depth: 3})
+		var cliErr *CLIError
+		if !errors.As(err, &cliErr) || cliErr.Code != CodeContentTruncated {
+			t.Fatalf("err = %T %v, want CodeContentTruncated", err, err)
+		}
+		msg := cliErr.Message
+		// 两个成因都要可被消费方 token 匹配到。
+		if !strings.Contains(msg, "LATEST_SCAN_INCOMPLETE") || !strings.Contains(msg, "LATEST_SCAN_TRUNCATED") {
+			t.Fatalf("组合场景需同时带两个 token: %q", msg)
+		}
+		// 目录失败详情必须完整保留——这是用户唯一能动手修的线索。
+		if !strings.Contains(msg, "报表") ||
+			!strings.Contains(msg, "depth=2") ||
+			!strings.Contains(msg, "permission_denied") ||
+			!strings.Contains(msg, "2 个目录未读全") {
+			t.Fatalf("组合场景丢失目录失败详情: %q", msg)
+		}
+		if !strings.Contains(msg, "拒绝输出不完整的 Top-4") {
+			t.Fatalf("message 缺少拒绝产出结论: %q", msg)
+		}
+		assertDriveLatestSuggestion(t, cliErr.Suggestion, "")
+		// 组合场景的指引要同时覆盖两条补救：换可读目录 + 降层数。
+		if !strings.Contains(cliErr.Suggestion, "确认目录权限") || !strings.Contains(cliErr.Suggestion, "--depth") {
+			t.Fatalf("组合场景 suggestion 需同时给出权限与降层数补救: %q", cliErr.Suggestion)
+		}
+	})
+
+	// folderName 为空回落 folderID；folderID 也空回落 <root>。
+	t.Run("folder_fallback", func(t *testing.T) {
+		byID := driveLatestIncompleteError(1, false, []driveDepthError{{FolderID: "fid-x"}}, driveLatestScope{depth: 2})
+		if !strings.Contains(byID.Error(), "folder=fid-x") {
+			t.Fatalf("fallback to folderID: %v", byID)
+		}
+		byRoot := driveLatestIncompleteError(1, false, []driveDepthError{{}}, driveLatestScope{depth: 2})
+		if !strings.Contains(byRoot.Error(), "folder=<root>") {
+			t.Fatalf("fallback to <root>: %v", byRoot)
+		}
+	})
+}
+
+// twoDriveDepthErrors 是两条目录失败样本，首条用于断言「首个失败」详情。
+func twoDriveDepthErrors() []driveDepthError {
+	return []driveDepthError{
+		{Depth: 2, FolderID: "fid-9", FolderName: "报表", Reason: "permission_denied", Message: "denied"},
+		{Depth: 1, FolderID: "fid-3", FolderName: "归档", Reason: "api_error", Message: "boom"},
+	}
+}
+
+// TestCrossPlatformCoverageDriveLatestScopePreservedInSuggestion 覆盖评审反馈的第二个阻塞点：恢复命令此前固定
+// 生成 `dws drive list --folder ...`，把原调用的 --workspace / --space-id 丢掉。用户照抄后
+// 会从知识库切到普通钉盘（或从指定钉盘空间切到「我的文件」），在另一个查询域里拿到一份
+// 「看起来对」的 Top-N —— 比直接报错更难发现。
+func TestCrossPlatformCoverageDriveLatestScopePreservedInSuggestion(t *testing.T) {
+	cases := []struct {
+		name  string
+		flags map[string]string
+		want  string
+	}{
+		// 知识库路由：--workspace 决定路由，丢了就切到普通钉盘。
+		{name: "workspace", flags: map[string]string{"workspace": "ws-1"}, want: "--workspace ws-1"},
+		// 别名路径：--workspace-id 与 --workspace 同源（flagOrFallback）。
+		{name: "workspace_id_alias", flags: map[string]string{"workspace-id": "ws-alias"}, want: "--workspace ws-alias"},
+		// 钉盘路由：--space-id 丢了就退回「我的文件」。
+		{name: "space_id", flags: map[string]string{"space-id": "sp-7"}, want: "--space-id sp-7"},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			scope := driveLatestScopeFromCmd(newDriveListScopeCmd(t, tc.flags), 3, "")
+			// 三条成因组合下的恢复命令都必须带原查询域。
+			for _, variant := range []struct {
+				label     string
+				truncated bool
+				errs      []driveDepthError
+			}{
+				{"truncated_only", true, nil},
+				{"folder_failure_only", false, twoDriveDepthErrors()},
+				{"both", true, twoDriveDepthErrors()},
+			} {
+				err := driveLatestIncompleteError(5, variant.truncated, variant.errs, scope)
+				var cliErr *CLIError
+				if !errors.As(err, &cliErr) {
+					t.Fatalf("%s: err = %T %v", variant.label, err, err)
+				}
+				assertDriveLatestSuggestion(t, cliErr.Suggestion, tc.want)
+			}
+		})
+	}
+
+	// --workspace 优先于 --space-id：与 drive list 的路由判定同序（先看 workspace 再看 space-id），
+	// 否则恢复命令会把知识库查询写成钉盘查询。
+	t.Run("workspace_wins_over_space_id", func(t *testing.T) {
+		scope := driveLatestScopeFromCmd(newDriveListScopeCmd(t, map[string]string{
+			"workspace": "ws-1", "space-id": "sp-7",
+		}), 3, "")
+		err := driveLatestIncompleteError(5, false, twoDriveDepthErrors(), scope)
+		suggestion := err.(*CLIError).Suggestion
+		if !strings.Contains(suggestion, "--workspace ws-1") || strings.Contains(suggestion, "--space-id") {
+			t.Fatalf("workspace 应优先且不混入 space-id: %q", suggestion)
+		}
+	})
+
+	// 无查询域时不得凭空造 flag（原调用就是「我的文件」根，硬塞 scope 同样是改查询域）。
+	t.Run("no_scope_adds_nothing", func(t *testing.T) {
+		scope := driveLatestScopeFromCmd(newDriveListScopeCmd(t, nil), 3, "")
+		err := driveLatestIncompleteError(5, false, twoDriveDepthErrors(), scope)
+		suggestion := err.(*CLIError).Suggestion
+		if strings.Contains(suggestion, "--workspace") || strings.Contains(suggestion, "--space-id") {
+			t.Fatalf("无 scope 时不应凭空造查询域 flag: %q", suggestion)
+		}
+		assertDriveLatestSuggestion(t, suggestion, "")
+	})
+
+	// depth==1（知识库 --latest 单层）时不给 --depth 1：partial+errors[] 契约只在多层成立，
+	// 硬塞 --depth 1 会让「去掉 --latest 看明细」的子句自相矛盾。
+	t.Run("single_depth_omits_depth_flag", func(t *testing.T) {
+		err := driveLatestIncompleteError(5, false, twoDriveDepthErrors(), driveLatestScope{domain: "--workspace ws-1", depth: 1})
+		suggestion := err.(*CLIError).Suggestion
+		if strings.Contains(suggestion, "--depth") {
+			t.Fatalf("单层不应出现 --depth: %q", suggestion)
+		}
+	})
+
+	// 多层时给出确切层数，用户无需把 <原层数> 换成数字。
+	t.Run("multi_depth_emits_actual_depth", func(t *testing.T) {
+		err := driveLatestIncompleteError(5, false, twoDriveDepthErrors(), driveLatestScope{domain: "--space-id sp-7", depth: 4})
+		suggestion := err.(*CLIError).Suggestion
+		if !strings.Contains(suggestion, "--depth 4") {
+			t.Fatalf("应给出原层数 --depth 4: %q", suggestion)
+		}
+		if strings.Contains(suggestion, "<原层数>") {
+			t.Fatalf("不应残留占位符: %q", suggestion)
+		}
+	})
+}
+
+// TestCrossPlatformCoverageDriveLatestScopeQuotesHostileValues 覆盖评审的 P1 阻断项：恢复命令是给用户直接复制到
+// shell 里执行的，查询域的值来自用户输入（workspace 常见形态就是带查询串的 URL）。未引用时
+// 一个 `&` 就把命令拆成后台任务，`;` / `$()` 更能执行额外内容。
+// 断言落在「值被完整包在单引号里」而不只是「出现过」——后者对裸拼接也成立，抓不住缺陷。
+func TestCrossPlatformCoverageDriveLatestScopeQuotesHostileValues(t *testing.T) {
+	cases := []struct {
+		name  string
+		flag  string
+		value string
+		want  string
+	}{
+		// 合法 workspace URL：& 在裸拼接下直接改变 shell 解析（前半段被丢进后台）。
+		{name: "workspace_url", flag: "workspace", value: "https://alidocs.dingtalk.com/i/nodes/abc?spaceId=1&type=doc",
+			want: `--workspace 'https://alidocs.dingtalk.com/i/nodes/abc?spaceId=1&type=doc'`},
+		// 命令替换：裸拼接会在用户复制执行时真的跑起来。
+		{name: "command_substitution", flag: "workspace", value: "$(id)", want: `--workspace '$(id)'`},
+		// 分号拆语句。
+		{name: "semicolon", flag: "space-id", value: "sp-7;id", want: `--space-id 'sp-7;id'`},
+		// 空格拆参：裸拼接会让 --folder 收到错误的值。
+		{name: "space", flag: "space-id", value: "sp 7", want: `--space-id 'sp 7'`},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			// 显式注入 POSIX 策略：本测试断言的是「危险值被单引号正确包住」这一 POSIX 形态。
+			// Windows 策略下这些值根本不内联（见 ...SuggestionNeverInlinesHostileValue），
+			// 若走平台绑定，这里在 Windows runner 上会因形态不同而误报。
+			scope := driveLatestScopeFrom(newDriveListScopeCmd(t, map[string]string{tc.flag: tc.value}), 3, "", driveLatestPosixScopeValue)
+			err := driveLatestIncompleteError(5, true, twoDriveDepthErrors(), scope)
+			suggestion := err.(*CLIError).Suggestion
+			if !strings.Contains(suggestion, tc.want) {
+				t.Fatalf("查询域未安全引用\n want substring: %s\n got suggestion: %s", tc.want, suggestion)
+			}
+		})
+	}
+}
+
+// TestCrossPlatformCoverageDriveLatestScopePreservesFiltersAndFolder 覆盖自动 CR 的 P2：
+// --pattern/--type/--start/--end 与 --folder 同样决定 --latest 的候选集合。恢复命令丢掉任一项，
+// 用户照抄后就是在**另一个集合**上取 Top-N —— 原调用带 --pattern 时，缺了它的重试命令会对全部
+// 条目排序，结果「看起来成功」却答非所问，比直接报错更难发现。
+func TestCrossPlatformCoverageDriveLatestScopePreservesFiltersAndFolder(t *testing.T) {
+	cmd := newDriveListScopeCmd(t, map[string]string{
+		"workspace": "ws-1",
+		"pattern":   "*日报*",
+		"type":      "file",
+		"start":     "7d",
+		"end":       "2026-08-01",
+	})
+	// 注入 POSIX 策略：`--pattern '*日报*'` 这种引用形态是 POSIX 专属，Windows 下该值会降级为
+	// 占位符 + 展示行（见 ...SuggestionNeverInlinesHostileValue）。走平台绑定会在 Windows 误报。
+	scope := driveLatestScopeFrom(cmd, 4, "folder-root", driveLatestPosixScopeValue)
+	err := driveLatestIncompleteError(5, false, twoDriveDepthErrors(), scope)
+	suggestion := err.(*CLIError).Suggestion
+
+	// 每条示例命令都要带齐查询域与全部过滤条件；pattern 含 * 与中文，必须是引用后的形态。
+	for _, want := range []string{
+		"--workspace ws-1",
+		"--pattern '*日报*'",
+		"--type file",
+		"--start 7d",
+		"--end 2026-08-01",
+	} {
+		for _, clause := range strings.Split(suggestion, "；") {
+			cmdText := extractTrailingDwsCommand(clause)
+			if cmdText == "" {
+				continue
+			}
+			if !strings.Contains(cmdText, want) {
+				t.Fatalf("恢复命令丢失候选集条件 %q:\n  clause: %s", want, cmdText)
+			}
+		}
+	}
+
+	// 「去掉 --latest 按原范围重跑」是唯一的原范围命令，必须原样带回原 --folder 而非占位符，
+	// 否则它就不是「原范围」。
+	var origin string
+	for _, clause := range strings.Split(suggestion, "；") {
+		if strings.Contains(clause, "去掉 --latest") {
+			origin = extractTrailingDwsCommand(clause)
+		}
+	}
+	if origin == "" {
+		t.Fatalf("多层场景应给出「去掉 --latest 按原范围重跑」子句: %q", suggestion)
+	}
+	if !strings.Contains(origin, "--folder folder-root") {
+		t.Fatalf("原范围命令应保留原 --folder: %q", origin)
+	}
+	if strings.Contains(origin, "<可读子目录ID>") {
+		t.Fatalf("原范围命令不应把原 --folder 换成占位符: %q", origin)
+	}
+}
+
+// TestCrossPlatformCoverageDriveLatestScopeOmitsFolderAtSpaceRoot 原调用就在空间根时不得凭空
+// 造 --folder：硬塞一个目录同样是改候选集。
+func TestCrossPlatformCoverageDriveLatestScopeOmitsFolderAtSpaceRoot(t *testing.T) {
+	scope := driveLatestScopeFromCmd(newDriveListScopeCmd(t, map[string]string{"space-id": "sp-7"}), 3, "")
+	err := driveLatestIncompleteError(2, false, twoDriveDepthErrors(), scope)
+	suggestion := err.(*CLIError).Suggestion
+	for _, clause := range strings.Split(suggestion, "；") {
+		if !strings.Contains(clause, "去掉 --latest") {
+			continue
+		}
+		if strings.Contains(extractTrailingDwsCommand(clause), "--folder") {
+			t.Fatalf("空间根扫描的原范围命令不应带 --folder: %q", clause)
+		}
+	}
+}
+
+// TestCrossPlatformCoverageDriveLatestErrorStripsRemoteControlChars 覆盖自动 CR 的 P2 安全项：
+// 拒绝产出后，目录名与服务端错误文本从 JSON（编码时会被转义）挪进了纯文本 stderr。若原样透传，
+// 其中的 ANSI/OSC 序列会被终端直接执行 —— 可清屏、伪造彩色「成功」、隐藏后续输出、改窗口标题，
+// 在 AI Agent 场景还会污染上下文窗口。目录名对共享目录而言是他人可控输入。
+func TestCrossPlatformCoverageDriveLatestErrorStripsRemoteControlChars(t *testing.T) {
+	assertNoControlChars := func(t *testing.T, msg string) {
+		t.Helper()
+		for name, r := range map[string]rune{"ESC": 0x1b, "BEL": 0x07, "CR": '\r', "LF": '\n', "TAB": '\t'} {
+			if strings.ContainsRune(msg, r) {
+				t.Fatalf("错误消息残留 %s 控制字符: %q", name, msg)
+			}
+		}
+	}
+
+	// folderName 路径：CSI 清屏 + 变色，外加 OSC 改标题。
+	t.Run("folder_name", func(t *testing.T) {
+		err := driveLatestIncompleteError(3, false, []driveDepthError{{
+			Depth:      2,
+			FolderName: "报表\x1b[2J\x1b[31m看起来成功\x1b[0m",
+			Reason:     "permission_denied",
+			Message:    "denied\r\n\x1b]0;pwned\x07次行",
+		}}, driveLatestScope{depth: 2})
+		msg := err.(*CLIError).Message
+		assertNoControlChars(t, msg)
+		// 清理不能把诊断信息一起抹掉：可读部分必须留下。
+		if !strings.Contains(msg, "报表") || !strings.Contains(msg, "denied") || !strings.Contains(msg, "次行") {
+			t.Fatalf("清理后应保留可读文本: %q", msg)
+		}
+	})
+
+	// folderName 为空时回落到 folderID，该字段同样来自服务端。
+	t.Run("folder_id_fallback", func(t *testing.T) {
+		err := driveLatestIncompleteError(1, true, []driveDepthError{{
+			FolderID: "fid\x1b[1m-x",
+			Reason:   "api_error",
+			Message:  "boom",
+		}}, driveLatestScope{depth: 1})
+		msg := err.(*CLIError).Message
+		assertNoControlChars(t, msg)
+		if !strings.Contains(msg, "fid-x") {
+			t.Fatalf("剥离控制序列后 folderID 应连成 fid-x: %q", msg)
+		}
+	})
+}
+
+// TestCrossPlatformCoverageDriveLatestSafeRemoteText 直接钉住清理函数的各条分支：换行/制表符
+// 折成空格（SanitizeForTerminal 按设计保留这两者，但单行错误消息里它们会拆出伪造行），
+// 首尾空白收掉，可打印内容与中文原样保留。
+func TestCrossPlatformCoverageDriveLatestSafeRemoteText(t *testing.T) {
+	cases := []struct {
+		name string
+		in   string
+		want string
+	}{
+		{name: "plain", in: "denied", want: "denied"},
+		{name: "cjk", in: "报表目录", want: "报表目录"},
+		{name: "csi", in: "a\x1b[31mb", want: "ab"},
+		{name: "osc", in: "a\x1b]0;t\x07b", want: "ab"},
+		{name: "newline_to_space", in: "a\nb", want: "a b"},
+		{name: "tab_to_space", in: "a\tb", want: "a b"},
+		{name: "carriage_return_dropped", in: "a\rb", want: "ab"},
+		{name: "trim_outer", in: "\n denied \t", want: "denied"},
+		{name: "empty", in: "", want: ""},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			if got := driveLatestSafeRemoteText(tc.in); got != tc.want {
+				t.Fatalf("driveLatestSafeRemoteText(%q) = %q, want %q", tc.in, got, tc.want)
+			}
+		})
+	}
+}
+
+// TestCrossPlatformCoverageDriveLatestSuggestionNeverInlinesHostileValue 端到端锁定评审提出的
+// Windows 注入阻断项：`--space-id sp-7&whoami` 这种值，在 POSIX 下靠单引号关停，但 cmd.exe
+// 不把单引号当引号，粘贴后 `&whoami` 仍会执行。因此不变量必须是「恢复命令里不存在能被目标
+// shell 解释的裸元字符」，两个平台分别用各自的手段满足：POSIX 引用内联，Windows 不内联。
+//
+// 两种形态都通过注入渲染策略在本机验证，不依赖当前 GOOS —— 否则「Windows 上降级为占位符」
+// 这条路在 POSIX 机器上永不可达，就成了只有 Windows runner 才跑到的盲区（平台覆盖率门禁也会
+// 因此报未覆盖）。平台绑定本身由 TestCrossPlatformCoverageDriveLatestScopeValueBinding 覆盖。
+func TestCrossPlatformCoverageDriveLatestSuggestionNeverInlinesHostileValue(t *testing.T) {
+	const hostile = "sp-7&whoami"
+	newSuggestion := func(t *testing.T, render driveLatestValueRenderer) string {
+		t.Helper()
+		scope := driveLatestScopeFrom(newDriveListScopeCmd(t, map[string]string{"space-id": hostile}), 3, "", render)
+		return driveLatestIncompleteError(5, true, twoDriveDepthErrors(), scope).(*CLIError).Suggestion
+	}
+
+	t.Run("windows_never_inlines", func(t *testing.T) {
+		suggestion := newSuggestion(t, driveLatestWindowsScopeValue)
+		for _, clause := range strings.Split(suggestion, "；") {
+			cmdText := extractTrailingDwsCommand(clause)
+			if cmdText == "" {
+				continue
+			}
+			// cmd.exe 里 & 分隔命令，且单引号不是引号，故它压根不能进命令。
+			if strings.Contains(cmdText, "&") {
+				t.Fatalf("windows 形态的命令不得含 &: %s", cmdText)
+			}
+			if strings.Contains(cmdText, hostile) {
+				t.Fatalf("windows 形态的命令不得内联原值: %s", cmdText)
+			}
+		}
+		if !strings.Contains(suggestion, driveLatestUnsafeValuePlaceholder) {
+			t.Fatalf("应降级为占位符: %s", suggestion)
+		}
+		if !strings.Contains(suggestion, strconv.Quote(hostile)) {
+			t.Fatalf("应在展示行给出原值: %s", suggestion)
+		}
+		if !strings.Contains(suggestion, "不是可执行命令") {
+			t.Fatalf("展示行须显式声明非可执行: %s", suggestion)
+		}
+	})
+
+	t.Run("posix_quotes_inline", func(t *testing.T) {
+		suggestion := newSuggestion(t, driveLatestPosixScopeValue)
+		if !strings.Contains(suggestion, "'"+hostile+"'") {
+			t.Fatalf("posix 形态应单引号内联原值: %s", suggestion)
+		}
+		// POSIX 下不该无谓降级 —— 那会白白损失可复制体验。
+		if strings.Contains(suggestion, driveLatestUnsafeValuePlaceholder) {
+			t.Fatalf("posix 形态不应降级为占位符: %s", suggestion)
+		}
+		for _, clause := range strings.Split(suggestion, "；") {
+			cmdText := extractTrailingDwsCommand(clause)
+			if cmdText == "" {
+				continue
+			}
+			if strings.Contains(cmdText, "&") && !strings.Contains(cmdText, "'"+hostile+"'") {
+				t.Fatalf("posix 形态出现未引用的元字符: %s", cmdText)
+			}
+		}
+	})
+}
+
+// newDriveListScopeCmd 造一个带 drive list 查询域与过滤 flag 的命令。flag 名与 newDriveCommand
+// 里 driveListCmd 的注册保持一致；workspace-id 是 cross-product 别名，此处显式注册以覆盖别名路径。
+func newDriveListScopeCmd(t *testing.T, flags map[string]string) *cobra.Command {
+	t.Helper()
+	cmd := &cobra.Command{Use: "list"}
+	for _, name := range []string{
+		"workspace", "workspace-id", "space-id", // 查询域
+		"folder",                          // 扫描根（scope 从 rootFolder 参数取，注册仅为对齐真实命令）
+		"pattern", "type", "start", "end", // 决定候选集的过滤条件
+	} {
+		cmd.Flags().String(name, "", "")
+	}
+	for name, value := range flags {
+		if err := cmd.Flags().Set(name, value); err != nil {
+			t.Fatalf("set --%s=%s: %v", name, value, err)
+		}
+	}
+	return cmd
+}
+
+// assertDriveLatestSuggestion 钉住 Suggestion 的三条约束：
+//  1. 每条示例命令都带原查询域 wantScope（空串表示原调用无查询域，此时只跳过该项检查）；
+//  2. 含 --latest 的引导子句存在；
+//  3. 「去掉 --latest」子句给出的示例命令本身不带 --latest（否则照抄复现同一错误）。
+func assertDriveLatestSuggestion(t *testing.T, suggestion, wantScope string) {
+	t.Helper()
+	clauses := strings.Split(suggestion, "；")
+	sawLatestGuide := false
+	for _, clause := range clauses {
+		cmd := extractTrailingDwsCommand(clause)
+		if cmd == "" {
+			continue
+		}
+		if wantScope != "" && !strings.Contains(cmd, wantScope) {
+			t.Fatalf("示例命令丢失原查询域 %q（照抄会切换查询域）: %q", wantScope, cmd)
+		}
+		if strings.Contains(clause, "去掉 --latest") {
+			if strings.Contains(cmd, "--latest") {
+				t.Fatalf("「去掉 --latest」子句的示例命令仍含 --latest: %q", cmd)
+			}
+			continue
+		}
+		if strings.Contains(cmd, "--latest") {
+			sawLatestGuide = true
+		}
+	}
+	if !sawLatestGuide {
+		t.Fatalf("no --latest-bearing guidance clause in suggestion: %q", suggestion)
+	}
+}
+
+// extractTrailingDwsCommand 抽子句里以 "dws " 开头的尾部命令片段（到子句末），无则空串。
+func extractTrailingDwsCommand(clause string) string {
+	idx := strings.LastIndex(clause, "dws ")
+	if idx < 0 {
+		return ""
+	}
+	return clause[idx:]
+}

internal/helpers/drive_latest_scope_posix.go

@@ -0,0 +1,13 @@
+//go:build !windows
+
+package helpers
+
+// driveLatestScopeValue 按**本次构建的目标 shell** 渲染恢复命令里的用户值：返回可内联的片段，
+// 第二个返回值为 false 时表示该值不能安全进入可执行命令，调用方须改用占位符。
+//
+// 非 Windows 构建面向 POSIX shell，单引号可靠地关闭所有展开，故含元字符的值引用后内联即安全。
+// Windows 构建见 drive_latest_scope_windows.go —— 两个平台的策略本体都是
+// shell_quote.go 里的纯函数，可在任意平台被测试直接调用；本文件只做编译期绑定。
+func driveLatestScopeValue(value string) (string, bool) {
+	return driveLatestPosixScopeValue(value)
+}

internal/helpers/drive_latest_scope_windows.go

@@ -0,0 +1,13 @@
+//go:build windows
+
+package helpers
+
+// driveLatestScopeValue 按**本次构建的目标 shell** 渲染恢复命令里的用户值：返回可内联的片段，
+// 第二个返回值为 false 时表示该值不能安全进入可执行命令，调用方须改用占位符。
+//
+// Windows 构建下没有对 cmd.exe 与 PowerShell 同时成立的引用形式（cmd.exe 不认单引号，双引号
+// 又挡不住 %VAR% 展开），故只内联本身就安全的值；理由与取舍详见
+// driveLatestWindowsScopeValue 的注释。POSIX 构建见 drive_latest_scope_posix.go。
+func driveLatestScopeValue(value string) (string, bool) {
+	return driveLatestWindowsScopeValue(value)
+}

internal/helpers/drive_mirror_coverage_gaps_test.go

@@ -0,0 +1,163 @@
+package helpers
+
+import (
+	"context"
+	"io"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam"
+)
+
+// TestCrossPlatformCoverageDriveMirrorCoverageGaps 覆盖镜像整批 preflight 引入的
+// 输出失败和防御式解析分支。测试只调用命名 helper，不依赖真实 Drive 或网络。
+func TestCrossPlatformCoverageDriveMirrorCoverageGaps(t *testing.T) {
+	t.Run("preflight output failures", func(t *testing.T) {
+		root := t.TempDir()
+		mustWrite(t, filepath.Join(root, "a.txt"), "local")
+		caller := syncCaller(map[string]string{
+			"ROOT": `{"result":{"items":[{"name":"A.txt","type":"file","fileId":"REMOTE"}],"nextToken":""}}`,
+		})
+		testseam.Swap(t, &deps, &Deps{Caller: caller, Out: &Formatter{w: failingWriter{}}})
+		testseam.Swap(t, &os.Args, []string{"dws", "drive"})
+
+		pull := findDriveSubcommand(t, "pull")
+		mustSetFlags(t, pull, map[string]string{"local-folder": root, "remote-folder": "ROOT"})
+		if err := runDrivePull(pull, nil); err == nil || !strings.Contains(err.Error(), "write failed") {
+			t.Fatalf("pull preflight output error = %v", err)
+		}
+
+		push := findDriveSubcommand(t, "push")
+		mustSetFlags(t, push, map[string]string{"local-folder": root, "remote-folder": "ROOT"})
+		if err := runDrivePush(push, nil); err == nil || !strings.Contains(err.Error(), "write failed") {
+			t.Fatalf("push preflight output error = %v", err)
+		}
+
+		sync := findDriveSubcommand(t, "sync")
+		mustSetFlags(t, sync, map[string]string{"local-folder": root, "remote-folder": "ROOT", "quick": "true"})
+		if err := runDriveSync(sync, nil); err == nil || !strings.Contains(err.Error(), "write failed") {
+			t.Fatalf("sync preflight output error = %v", err)
+		}
+	})
+
+	t.Run("pull remote-only preflight output failure", func(t *testing.T) {
+		root := t.TempDir()
+		caller := syncCaller(map[string]string{
+			"ROOT": `{"result":{"items":[{"name":"A.txt","type":"file","fileId":"UP"},{"name":"a.txt","type":"file","fileId":"LOW"}],"nextToken":""}}`,
+		})
+		testseam.Swap(t, &deps, &Deps{Caller: caller, Out: &Formatter{w: failingWriter{}}})
+		testseam.Swap(t, &os.Args, []string{"dws", "drive"})
+		pull := findDriveSubcommand(t, "pull")
+		mustSetFlags(t, pull, map[string]string{"local-folder": root, "remote-folder": "ROOT"})
+		if err := runDrivePull(pull, nil); err == nil || !strings.Contains(err.Error(), "write failed") {
+			t.Fatalf("pull remote-only preflight output error = %v", err)
+		}
+	})
+
+	t.Run("dry run preflight output failures", func(t *testing.T) {
+		root := t.TempDir()
+		remote := map[string]*remoteFile{"A.txt": {RelPath: "A.txt"}, "a.txt": {RelPath: "a.txt"}}
+		testseam.Swap(t, &deps, &Deps{Out: &Formatter{w: failingWriter{}}})
+		if err := printDrivePullDryRun(root, ifExistsSkip, remote, []string{"A.txt", "a.txt"}, true); err == nil {
+			t.Fatal("pull dry-run preflight must propagate output failure")
+		}
+		local := []localPushFile{{RelPath: "a.txt"}}
+		if err := printDrivePushDryRun(ifExistsSkip,
+			map[string]*remoteFile{"A.txt": {RelPath: "A.txt"}}, map[string]string{"": "ROOT"}, nil, local); err == nil {
+			t.Fatal("push dry-run preflight must propagate output failure")
+		}
+	})
+
+	t.Run("parser errors", func(t *testing.T) {
+		for _, body := range []string{
+			`{"result":`,
+			`{"result":{"items":[],"hasMore":"bad"}}`,
+			`{"result":{"items":null}}`,
+			`{"result":{"items":"bad"}}`,
+			`{"result":[`,
+			`{"result":[true]}`,
+			`{"result":[{}]}`,
+			`{"result":true}`,
+		} {
+			if _, _, err := parseDriveList(body); err == nil {
+				t.Errorf("parseDriveList(%q) unexpectedly succeeded", body)
+			}
+		}
+	})
+
+	t.Run("pull dry-run existing-file policies", func(t *testing.T) {
+		root := t.TempDir()
+		skipPath := filepath.Join(root, "skip.txt")
+		smartPath := filepath.Join(root, "smart.txt")
+		mustWrite(t, skipPath, "skip")
+		mustWrite(t, smartPath, "smart")
+		smartMTime := readFileMTimeMillis(t, smartPath)
+		remote := map[string]*remoteFile{
+			"skip.txt":  {RelPath: "skip.txt"},
+			"smart.txt": {RelPath: "smart.txt", ModifiedTime: smartMTime - 1, ModifiedTimeValid: true},
+		}
+		testseam.Swap(t, &deps, &Deps{Out: &Formatter{w: io.Discard}})
+		if err := printDrivePullDryRunWithPreflight(root, ifExistsSkip, remote, []string{"skip.txt"}, false, nil); err != nil {
+			t.Fatal(err)
+		}
+		if err := printDrivePullDryRunWithPreflight(root, ifExistsSmart, remote, []string{"smart.txt"}, false, nil); err != nil {
+			t.Fatal(err)
+		}
+		remote["smart.txt"] = &remoteFile{RelPath: "smart.txt"}
+		if err := printDrivePullDryRunWithPreflight(root, ifExistsSmart, remote, []string{"smart.txt"}, false, nil); err != nil {
+			t.Fatal(err)
+		}
+	})
+
+	t.Run("pull mkdir and replace errors", func(t *testing.T) {
+		root := t.TempDir()
+		caller := pullListingCaller("")
+		testseam.Swap(t, &deps, &Deps{Caller: caller, Out: &Formatter{w: io.Discard}})
+		testseam.Swap(t, &os.Args, []string{"dws", "drive"})
+		testseam.Swap(t, &pullMkdirAll, func(string, os.FileMode) error { return errTestDownload })
+		if action, err := pullOneFile(context.Background(), "", &remoteFile{FileID: "F"},
+			filepath.Join(root, "blocked", "x.txt"), ifExistsOverwrite); action != pullActionFailed || err == nil {
+			t.Fatalf("mkdir failure = (%q, %v)", action, err)
+		}
+
+		targetDir := t.TempDir()
+		mustWrite(t, filepath.Join(targetDir, "target.txt"), "local")
+		testseam.Swap(t, &pullMkdirAll, os.MkdirAll)
+		testseam.Swap(t, &pullRename, func(*os.Root, string, string) error { return errTestDownload })
+		swapPullDownloadPath(t, func(_ context.Context, _ string, _ map[string]string, dest string) error {
+			return os.WriteFile(dest, []byte("remote"), 0o644)
+		})
+		if action, err := pullOneFile(context.Background(), "", &remoteFile{FileID: "F"},
+			filepath.Join(targetDir, "target.txt"), ifExistsOverwrite); action != pullActionFailed || err == nil {
+			t.Fatalf("replace failure = (%q, %v)", action, err)
+		}
+	})
+
+	t.Run("sync pull defensive failures", func(t *testing.T) {
+		root := t.TempDir()
+		outside := t.TempDir()
+		if err := os.Symlink(outside, filepath.Join(root, "sub")); err != nil {
+			t.Skipf("symlink unsupported: %v", err)
+		}
+		res := &driveSyncResult{}
+		syncPullFile(res, context.Background(), "", &remoteFile{FileID: "F"}, root, "sub/a.txt", syncDirectionPull)
+		if res.Summary.Failed != 1 {
+			t.Fatalf("escape failed = %d", res.Summary.Failed)
+		}
+	})
+
+	t.Run("pull remote file rechecks symlink escape", func(t *testing.T) {
+		root := t.TempDir()
+		outside := t.TempDir()
+		if err := os.Symlink(outside, filepath.Join(root, "sub")); err != nil {
+			t.Skipf("symlink unsupported: %v", err)
+		}
+		action, err := pullRemoteFile(context.Background(), "", &remoteFile{FileID: "F"}, root,
+			"sub/a.txt", ifExistsOverwrite)
+		if action != pullActionFailed || err == nil {
+			t.Fatalf("pull remote TOCTOU guard = (%q, %v)", action, err)
+		}
+	})
+}

internal/helpers/drive_mirror_preflight_test.go

@@ -0,0 +1,376 @@
+package helpers
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam"
+	"github.com/spf13/cobra"
+)
+
+func runDriveMirrorCommand(t *testing.T, caller *driveScriptCaller, dryRun bool, args ...string) ([]byte, error) {
+	t.Helper()
+	caller.dryRun = dryRun
+	var out bytes.Buffer
+	testseam.Swap(t, &deps, &Deps{Caller: caller, Out: &Formatter{w: &out}})
+
+	root := &cobra.Command{Use: "dws"}
+	root.PersistentFlags().BoolP("yes", "y", false, "")
+	root.PersistentFlags().Bool("dry-run", false, "")
+	root.AddCommand(newDriveCommand())
+	full := append(append([]string{}, args...), "--yes")
+	testseam.Swap(t, &os.Args, append([]string{"dws", "drive"}, full...))
+	root.SetArgs(append([]string{"drive"}, full...))
+	err := root.Execute()
+	return append([]byte(nil), out.Bytes()...), err
+}
+
+func captureMirrorHTTP(t *testing.T) (getCalls, putCalls *int) {
+	t.Helper()
+	gets, puts := 0, 0
+	swapPullDownloadPath(t, func(context.Context, string, map[string]string, string) error {
+		gets++
+		return nil
+	})
+	testseam.Swap(t, &pushPutOpenedFile, func(context.Context, string, map[string]string, *os.File, int64) error {
+		puts++
+		return nil
+	})
+	return &gets, &puts
+}
+
+func assertMirrorPreflightNoWrites(t *testing.T, caller *driveScriptCaller, getCalls, putCalls int) {
+	t.Helper()
+	for _, tool := range []string{"create_folder", "download_file", "get_upload_info", "commit_upload"} {
+		if calls := caller.callsFor(tool); len(calls) != 0 {
+			t.Errorf("mirror preflight must not call %s: %v", tool, calls)
+		}
+	}
+	if getCalls != 0 || putCalls != 0 {
+		t.Errorf("mirror preflight must not transfer content: GET=%d PUT=%d", getCalls, putCalls)
+	}
+}
+
+func TestCrossPlatformCoverageDrivePull_nonRegularTargetFailsBeforeDownload(t *testing.T) {
+	for _, dryRun := range []bool{false, true} {
+		name := "execute"
+		if dryRun {
+			name = "dry-run"
+		}
+		t.Run(name, func(t *testing.T) {
+			root := t.TempDir()
+			if err := os.Mkdir(filepath.Join(root, "blocked.txt"), 0o755); err != nil {
+				t.Fatal(err)
+			}
+			caller := syncCaller(map[string]string{
+				"ROOT": `{"result":{"items":[{"name":"blocked.txt","type":"file","fileId":"REMOTE"}],"nextToken":""}}`,
+			})
+			gets, puts := captureMirrorHTTP(t)
+			out, err := runDriveMirrorCommand(t, caller, dryRun, "pull", "--local-folder", root, "--remote-folder", "ROOT")
+			if dryRun {
+				if err != nil {
+					t.Fatalf("pull dry-run: %v", err)
+				}
+				var got drivePullDryRunResult
+				if jsonErr := json.Unmarshal(out, &got); jsonErr != nil {
+					t.Fatalf("pull dry-run output is not JSON: %v\n%s", jsonErr, out)
+				}
+				if got.Plan.Summary.Failed != 1 || len(got.Plan.Items) != 1 || !strings.Contains(got.Plan.Items[0].Error, "不是常规文件") {
+					t.Fatalf("pull dry-run plan = %+v, want one non-regular target failure", got.Plan)
+				}
+			} else {
+				var failure *drivePartialFailure
+				if !errors.As(err, &failure) || failure.failed != 1 {
+					t.Fatalf("pull error = %v, want one failed item", err)
+				}
+			}
+			assertMirrorPreflightNoWrites(t, caller, *gets, *puts)
+		})
+	}
+}
+
+func TestCrossPlatformCoverageDrivePull_nonRegularTargetAbortsWholeBatchBeforeDownload(t *testing.T) {
+	for _, command := range []string{"pull", "sync"} {
+		for _, dryRun := range []bool{false, true} {
+			name := command + "/execute"
+			if dryRun {
+				name = command + "/dry-run"
+			}
+			t.Run(name, func(t *testing.T) {
+				root := t.TempDir()
+				if err := os.Mkdir(filepath.Join(root, "z-blocked.txt"), 0o755); err != nil {
+					t.Fatal(err)
+				}
+				caller := syncCaller(map[string]string{
+					"ROOT": `{"result":{"items":[{"name":"a-first.txt","type":"file","fileId":"FIRST"},{"name":"z-blocked.txt","type":"file","fileId":"BLOCKED"}],"nextToken":""}}`,
+				})
+				gets, puts := captureMirrorHTTP(t)
+				args := []string{command, "--local-folder", root, "--remote-folder", "ROOT"}
+				if command == "sync" {
+					args = append(args, "--quick")
+				}
+				out, err := runDriveMirrorCommand(t, caller, dryRun, args...)
+				if dryRun {
+					if err != nil {
+						t.Fatalf("%s dry-run: %v", command, err)
+					}
+					if command == "pull" {
+						var got drivePullDryRunResult
+						if jsonErr := json.Unmarshal(out, &got); jsonErr != nil || got.Plan.Summary.Failed != 2 {
+							t.Fatalf("pull dry-run preflight = %+v, json error %v", got, jsonErr)
+						}
+					} else {
+						assertMirrorDryRunFailureJSON(t, command, out)
+					}
+				} else if err == nil {
+					t.Fatalf("%s must abort the whole batch", command)
+				}
+				if _, statErr := os.Stat(filepath.Join(root, "a-first.txt")); !os.IsNotExist(statErr) {
+					t.Fatalf("%s wrote an earlier file before discovering the conflict: %v", command, statErr)
+				}
+				assertMirrorPreflightNoWrites(t, caller, *gets, *puts)
+			})
+		}
+	}
+}
+
+func TestCrossPlatformCoverageDrivePull_remoteEquivalentTreeFailsBeforeDownload(t *testing.T) {
+	tests := []struct {
+		name     string
+		listings map[string]string
+		wantFail int
+	}{
+		{
+			name: "equivalent files",
+			listings: map[string]string{
+				"ROOT": `{"result":{"items":[{"name":"A.txt","type":"file","fileId":"UP"},{"name":"a.txt","type":"file","fileId":"LOW"}],"nextToken":""}}`,
+			},
+			wantFail: 2,
+		},
+		{
+			name: "equivalent folder prefixes",
+			listings: map[string]string{
+				"ROOT":    `{"result":{"items":[{"name":"Folder","type":"folder","fileId":"UP_DIR"},{"name":"folder","type":"folder","fileId":"LOW_DIR"}],"nextToken":""}}`,
+				"UP_DIR":  `{"result":{"items":[{"name":"up.txt","type":"file","fileId":"UP"}],"nextToken":""}}`,
+				"LOW_DIR": `{"result":{"items":[{"name":"low.txt","type":"file","fileId":"LOW"}],"nextToken":""}}`,
+			},
+			wantFail: 2,
+		},
+	}
+	for _, tt := range tests {
+		for _, dryRun := range []bool{false, true} {
+			name := tt.name + "/execute"
+			if dryRun {
+				name = tt.name + "/dry-run"
+			}
+			t.Run(name, func(t *testing.T) {
+				root := t.TempDir()
+				caller := syncCaller(tt.listings)
+				gets, puts := captureMirrorHTTP(t)
+				out, err := runDriveMirrorCommand(t, caller, dryRun, "pull", "--local-folder", root, "--remote-folder", "ROOT")
+				if dryRun {
+					if err != nil {
+						t.Fatalf("pull dry-run: %v", err)
+					}
+					var got drivePullDryRunResult
+					if jsonErr := json.Unmarshal(out, &got); jsonErr != nil {
+						t.Fatalf("pull dry-run output is not JSON: %v\n%s", jsonErr, out)
+					}
+					if got.Plan.Summary.Failed != tt.wantFail || got.Plan.Summary.Downloaded != 0 {
+						t.Fatalf("pull dry-run plan = %+v", got.Plan)
+					}
+				} else {
+					var failure *drivePartialFailure
+					if !errors.As(err, &failure) || failure.failed != tt.wantFail {
+						t.Fatalf("pull error = %v, want %d failed items", err, tt.wantFail)
+					}
+				}
+				if !strings.Contains(string(out), "等价路径") {
+					t.Fatalf("pull output must explain equivalent path ambiguity: %s", out)
+				}
+				assertMirrorPreflightNoWrites(t, caller, *gets, *puts)
+			})
+		}
+	}
+}
+
+func TestCrossPlatformCoverageDriveMirror_unsafeLocalNamesFailClosed(t *testing.T) {
+	if os.PathSeparator == '\\' {
+		t.Skip("current platform cannot create a local name containing a backslash")
+	}
+	for _, command := range []string{"push", "sync"} {
+		for _, dryRun := range []bool{false, true} {
+			name := command + "/execute"
+			if dryRun {
+				name = command + "/dry-run"
+			}
+			t.Run(name, func(t *testing.T) {
+				root := t.TempDir()
+				mustWrite(t, filepath.Join(root, `unsafe\name.txt`), "local")
+				caller := syncCaller(nil)
+				gets, puts := captureMirrorHTTP(t)
+				args := []string{command, "--local-folder", root, "--remote-folder", "ROOT"}
+				if command == "sync" {
+					args = append(args, "--quick")
+				}
+				out, err := runDriveMirrorCommand(t, caller, dryRun, args...)
+				if dryRun {
+					if err != nil {
+						t.Fatalf("%s dry-run: %v", command, err)
+					}
+					assertMirrorDryRunFailureJSON(t, command, out)
+				} else if err == nil {
+					t.Fatalf("%s must fail an unsafe local name", command)
+				}
+				if !strings.Contains(string(out), "无法安全映射到远端") {
+					t.Fatalf("%s output must explain unsafe local name: %s", command, out)
+				}
+				assertMirrorPreflightNoWrites(t, caller, *gets, *puts)
+			})
+		}
+	}
+
+	// NUL 不能由真实文件系统创建，直接覆盖契约 helper，避免该分支成为死角。
+	preflight := buildMirrorPreflight(nil, []localPushFile{{RelPath: "bad\x00name.txt"}}, nil, map[string]string{"": "ROOT"})
+	if !strings.Contains(preflight["bad\x00name.txt"], "无法安全映射到远端") {
+		t.Fatalf("NUL name preflight = %v", preflight)
+	}
+	if err := rejectNonRegularLocalTarget("bad\x00target"); err == nil || !strings.Contains(err.Error(), "检查本地目标失败") {
+		t.Fatalf("invalid local target error = %v", err)
+	}
+
+	localCollision := buildMirrorPreflight(nil, []localPushFile{{RelPath: "A.txt"}, {RelPath: "a.txt"}}, nil, map[string]string{"": "ROOT"})
+	for _, rel := range []string{"A.txt", "a.txt"} {
+		if !strings.Contains(localCollision[rel], "等价路径") {
+			t.Fatalf("local equivalent collision %q = %q", rel, localCollision[rel])
+		}
+	}
+	prefixCollision := buildMirrorPreflight(nil, []localPushFile{{RelPath: "A/x.txt"}},
+		map[string]*remoteFile{"a/y.txt": {RelPath: "a/y.txt"}}, map[string]string{"": "ROOT"})
+	for _, rel := range []string{"A", "a"} {
+		if !strings.Contains(prefixCollision[rel], "等价路径") {
+			t.Fatalf("equivalent ancestor collision %q = %q", rel, prefixCollision[rel])
+		}
+	}
+}
+
+func TestCrossPlatformCoverageDriveMirror_crossSideEquivalentPathsFailBeforeWrites(t *testing.T) {
+	tests := []struct {
+		name     string
+		prepare  func(*testing.T, string)
+		listings map[string]string
+	}{
+		{
+			name:    "case-equivalent files",
+			prepare: func(t *testing.T, root string) { mustWrite(t, filepath.Join(root, "a.txt"), "local") },
+			listings: map[string]string{
+				"ROOT": `{"result":{"items":[{"name":"A.txt","type":"file","fileId":"REMOTE"}],"nextToken":""}}`,
+			},
+		},
+		{
+			name: "case-equivalent folder prefixes",
+			prepare: func(t *testing.T, root string) {
+				mustWrite(t, filepath.Join(root, "Folder", "local.txt"), "local")
+			},
+			listings: map[string]string{
+				"ROOT":       `{"result":{"items":[{"name":"folder","type":"folder","fileId":"REMOTE_DIR"}],"nextToken":""}}`,
+				"REMOTE_DIR": `{"result":{"items":[{"name":"remote.txt","type":"file","fileId":"REMOTE_FILE"}],"nextToken":""}}`,
+			},
+		},
+		{
+			name:    "unicode-equivalent files",
+			prepare: func(t *testing.T, root string) { mustWrite(t, filepath.Join(root, "caf\u00e9.txt"), "local") },
+			listings: map[string]string{
+				"ROOT": `{"result":{"items":[{"name":"cafe\u0301.txt","type":"file","fileId":"REMOTE"}],"nextToken":""}}`,
+			},
+		},
+		{
+			name:    "equivalent path type ambiguity",
+			prepare: func(t *testing.T, root string) { mustWrite(t, filepath.Join(root, "item"), "local") },
+			listings: map[string]string{
+				"ROOT":       `{"result":{"items":[{"name":"ITEM","type":"folder","fileId":"REMOTE_DIR"}],"nextToken":""}}`,
+				"REMOTE_DIR": `{"result":{"items":[],"nextToken":""}}`,
+			},
+		},
+		{
+			name:    "remote-only equivalent files",
+			prepare: func(t *testing.T, root string) { mustWrite(t, filepath.Join(root, "safe-local.txt"), "local") },
+			listings: map[string]string{
+				"ROOT": `{"result":{"items":[{"name":"A.txt","type":"file","fileId":"UP"},{"name":"a.txt","type":"file","fileId":"LOW"}],"nextToken":""}}`,
+			},
+		},
+		{
+			name:    "remote-only equivalent folders",
+			prepare: func(t *testing.T, root string) { mustWrite(t, filepath.Join(root, "safe-local.txt"), "local") },
+			listings: map[string]string{
+				"ROOT":    `{"result":{"items":[{"name":"Folder","type":"folder","fileId":"UP_DIR"},{"name":"folder","type":"folder","fileId":"LOW_DIR"}],"nextToken":""}}`,
+				"UP_DIR":  `{"result":{"items":[],"nextToken":""}}`,
+				"LOW_DIR": `{"result":{"items":[],"nextToken":""}}`,
+			},
+		},
+	}
+
+	for _, tt := range tests {
+		for _, command := range []string{"push", "sync"} {
+			for _, dryRun := range []bool{false, true} {
+				name := tt.name + "/" + command + "/execute"
+				if dryRun {
+					name = tt.name + "/" + command + "/dry-run"
+				}
+				t.Run(name, func(t *testing.T) {
+					root := t.TempDir()
+					tt.prepare(t, root)
+					caller := syncCaller(tt.listings)
+					gets, puts := captureMirrorHTTP(t)
+					args := []string{command, "--local-folder", root, "--remote-folder", "ROOT"}
+					if command == "sync" {
+						args = append(args, "--quick")
+					}
+					out, err := runDriveMirrorCommand(t, caller, dryRun, args...)
+					if dryRun {
+						if err != nil {
+							t.Fatalf("%s dry-run: %v", command, err)
+						}
+						assertMirrorDryRunFailureJSON(t, command, out)
+					} else if err == nil {
+						t.Fatalf("%s must reject an equivalent cross-side path", command)
+					}
+					if !strings.Contains(string(out), "等价路径") {
+						t.Fatalf("%s output must explain equivalent path ambiguity: %s", command, out)
+					}
+					assertMirrorPreflightNoWrites(t, caller, *gets, *puts)
+				})
+			}
+		}
+	}
+}
+
+func assertMirrorDryRunFailureJSON(t *testing.T, command string, out []byte) {
+	t.Helper()
+	switch command {
+	case "push":
+		var got drivePushDryRunResult
+		if err := json.Unmarshal(out, &got); err != nil {
+			t.Fatalf("push dry-run output is not JSON: %v\n%s", err, out)
+		}
+		if !got.DryRun || got.Executed || got.Operation != "drive push" || got.Plan.Summary.Failed == 0 || !got.Plan.Summary.Aborted {
+			t.Fatalf("push dry-run result = %+v", got)
+		}
+	case "sync":
+		var got driveSyncDryRunResult
+		if err := json.Unmarshal(out, &got); err != nil {
+			t.Fatalf("sync dry-run output is not standalone JSON: %v\n%s", err, out)
+		}
+		if !got.DryRun || got.Executed || got.PreviewKind != "plan" || got.Operation != "drive sync" || got.Plan.Summary.Failed == 0 {
+			t.Fatalf("sync dry-run result = %+v", got)
+		}
+	default:
+		t.Fatalf("unsupported command %q", command)
+	}
+}

internal/helpers/drive_pinned_root_identity_test.go

@@ -0,0 +1,77 @@
+package helpers
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam"
+)
+
+// Windows 会用已打开的目录句柄锁住目录，把「固定后目录被移走／换成软链」这类
+// TOCTOU 在该平台变成物理不可达：os.Rename 直接 ERROR_SHARING_VIOLATION。
+// 但被测的 fail-closed 分支必须在所有平台都覆盖，所以这里提供与真实替换等价的
+// 身份注入：pinnedPullRoot.verify() 与 verifyParent() 都只通过 pullPathStat /
+// pullRootLstat 读取当前身份，让这两个 seam 指向另一个目录即可命中同一分支。
+
+// forcePinnedFallbackForTest 打开后，「移走固定目录」的复现手法一律走身份注入降级。
+// 默认 false：Unix 上用真实移动，验证更强。只有 Windows 才会真的走降级分支，所以
+// 下面的注入回归测试会打开它，让那条路径在任何平台都能被验证。
+var forcePinnedFallbackForTest = false
+
+// swapPinnedRootIdentity 让 absDir 的根身份读数指向另一个目录，使随后的
+// pinnedPullRoot.verify() 判定「本地根目录在同步期间被替换」。
+func swapPinnedRootIdentity(t *testing.T, absDir string) {
+	t.Helper()
+	decoy, err := os.Stat(t.TempDir())
+	if err != nil {
+		t.Fatal(err)
+	}
+	want := filepath.Clean(absDir)
+	testseam.Swap(t, &pullPathStat, func(path string) (os.FileInfo, error) {
+		if filepath.Clean(path) == want {
+			return decoy, nil
+		}
+		return os.Stat(path)
+	})
+}
+
+// 降级注入只有 Windows 会真的走到（Unix 的 rename 成功）。这里强制打开开关，
+// 确保注入手段本身在任何平台都可回归：不移动目录，但固定根的校验必须随之失败，
+// 且原有目录树不得被动过。
+func TestCrossPlatformCoveragePinnedRootFallbackInjectionFailsVerification(t *testing.T) {
+	testseam.Swap(t, &forcePinnedFallbackForTest, true)
+	dir := t.TempDir()
+	mustWrite(t, filepath.Join(dir, "a.txt"), "pinned-original")
+	root := newPinnedPullRootForCoverage(t, dir)
+	if err := root.verify(); err != nil {
+		t.Fatalf("baseline verify: %v", err)
+	}
+
+	if moved := replacePinnedMirrorRoot(t, dir, filepath.Join(t.TempDir(), "moved")); moved {
+		t.Fatal("降级路径不应真的移动目录")
+	}
+	if err := root.verify(); err == nil || !strings.Contains(err.Error(), "本地根目录在同步期间被替换") {
+		t.Fatalf("身份注入后校验必须失败，got %v", err)
+	}
+	if b, err := os.ReadFile(filepath.Join(dir, "a.txt")); err != nil || string(b) != "pinned-original" {
+		t.Fatalf("降级必须保持原目录树不变: %q err=%v", string(b), err)
+	}
+}
+
+// swapPinnedParentIdentity 让固定根下名为 rel 的父目录身份读数指向另一个目录，
+// 使随后的 verifyParent() 判定「本地目标目录在下载期间被替换」。
+func swapPinnedParentIdentity(t *testing.T, rel string) {
+	t.Helper()
+	decoy, err := os.Lstat(t.TempDir())
+	if err != nil {
+		t.Fatal(err)
+	}
+	testseam.Swap(t, &pullRootLstat, func(parent *os.Root, name string) (os.FileInfo, error) {
+		if filepath.ToSlash(filepath.Clean(name)) == rel {
+			return decoy, nil
+		}
+		return parent.Lstat(name)
+	})
+}

internal/helpers/drive_pull.go

@@ -0,0 +1,974 @@
+package helpers
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"net/http"
+	"os"
+	"path/filepath"
+	"runtime"
+	"sort"
+	"strings"
+	"time"
+
+	"github.com/google/uuid"
+	"github.com/spf13/cobra"
+	"golang.org/x/text/unicode/norm"
+)
+
+// ==========================================================
+// drive pull — 把钉盘文件夹镜像到本地（Drive → 本地）
+// ==========================================================
+// ──────────────────────────────────────────────────────────
+// dws drive pull — 把钉盘文件夹单向、文件级镜像到本地（Drive → 本地）
+//
+// 递归列出 --remote-folder 指向的钉盘文件夹下所有 type=FILE 的文件，逐一下载到
+// --local-folder 对应的相对路径。已存在的本地文件按 --if-exists 决定
+// overwrite / smart / skip。结构化 summary + items 始终打印到 stdout；
+// summary.failed > 0 时额外以非零退出码退出。
+// ──────────────────────────────────────────────────────────
+
+// --if-exists 的三种策略。
+const (
+	ifExistsOverwrite = "overwrite" // 总是下载覆盖（Drive 为权威源）
+	ifExistsSmart     = "smart"     // 推荐增量：本地 mtime 已 ≥ 远端 modified_time 则跳过
+	ifExistsSkip      = "skip"      // 默认：本地已存在则保持不动
+)
+
+// pull 下载路径使用 os.Root 固定根目录和目标父目录。以下 seam 只用于
+// 确定性覆盖文件系统与传输失败分支；测试必须通过 testseam.Swap 替换。
+var (
+	pullMkdirAll    = os.MkdirAll
+	pullOpenRoot    = os.OpenRoot
+	pullRelPath     = filepath.Rel
+	pullPathStat    = os.Stat
+	pullPathLstat   = os.Lstat
+	pullTargetLstat = os.Lstat
+	pullRootMkdir   = func(root *os.Root, name string, mode os.FileMode) error {
+		return root.Mkdir(name, mode)
+	}
+	pullOpenParentRoot = func(root *os.Root, name string) (*os.Root, error) {
+		return root.OpenRoot(name)
+	}
+	pullRootStat   = func(root *os.Root, name string) (os.FileInfo, error) { return root.Stat(name) }
+	pullRootLstat  = func(root *os.Root, name string) (os.FileInfo, error) { return root.Lstat(name) }
+	pullCreateTemp = createPinnedPullTemp
+	pullTempName   = uuid.NewString
+	pullSyncTemp   = func(file *os.File) error { return file.Sync() }
+	pullCloseTemp  = func(file *os.File) error { return file.Close() }
+	pullRename     = func(root *os.Root, oldName, newName string) error {
+		return root.Rename(oldName, newName)
+	}
+	pullLink         = func(root *os.Root, oldName, newName string) error { return root.Link(oldName, newName) }
+	pullRemove       = func(root *os.Root, name string) error { return root.Remove(name) }
+	pullDownloadFile = defaultPullDownloadFile
+	pullHTTPDo       = func(request *http.Request) (*http.Response, error) {
+		return (&http.Client{Timeout: 10 * time.Minute}).Do(request)
+	}
+)
+
+// pull 动作分类。
+const (
+	pullActionDownloaded = "downloaded"
+	pullActionSkipped    = "skipped"
+	pullActionFailed     = "failed"
+)
+
+// drivePullItem 是输出 items[] 中每个文件的明细。
+type drivePullItem struct {
+	RelPath string `json:"rel_path"`
+	Action  string `json:"action"`
+	Error   string `json:"error,omitempty"`
+}
+
+// drivePullSummary 是各动作的计数汇总。
+type drivePullSummary struct {
+	Downloaded int `json:"downloaded"`
+	Skipped    int `json:"skipped"`
+	Failed     int `json:"failed"`
+}
+
+// drivePullResult 是 pull 命令的输出 schema。
+type drivePullResult struct {
+	Summary drivePullSummary `json:"summary"`
+	Items   []drivePullItem  `json:"items"`
+}
+
+type drivePullDryRunResult struct {
+	DryRun      bool            `json:"dry_run"`
+	Executed    bool            `json:"executed"`
+	PreviewKind string          `json:"preview_kind"`
+	Operation   string          `json:"operation"`
+	IfExists    string          `json:"if_exists"`
+	Plan        drivePullResult `json:"plan"`
+}
+
+// drivePartialFailure 在 summary.failed > 0 时返回：结构化结果已打印到 stdout，
+// 这里只负责以 exit=1 退出并向 stderr 输出一行简短说明（与 push/sync 一致）。
+type drivePartialFailure struct{ failed int }
+
+func (e *drivePartialFailure) Error() string {
+	return fmt.Sprintf("drive pull: %d file(s) failed", e.failed)
+}
+func (e *drivePartialFailure) RawStderr() string { return e.Error() }
+func (e *drivePartialFailure) ExitCode() int     { return 1 }
+
+// pathCollisionKey 把本地目标路径归一化成「目标文件系统下的等价键」，用于探测多个
+// 远端条目是否会落到同一个本地文件。caseInsensitive 为真时（Windows / 默认 macOS）
+// 折叠大小写并做 Unicode NFC 规范化，从而把 A.txt/a.txt、NFC/NFD 记法视为同一目标；
+// 大小写敏感文件系统（如 Linux ext4）则按精确路径区分，避免误判合法的异名文件。
+func pathCollisionKey(target string, caseInsensitive bool) string {
+	p := filepath.Clean(target)
+	if caseInsensitive {
+		p = norm.NFC.String(strings.ToLower(p))
+	}
+	return p
+}
+
+// isCaseInsensitiveFS 是大小写探测的注入点（与 httpGetFile / httpPutFile 同样的 seam）：
+// 生产路径始终是 detectCaseInsensitiveFS，测试可替换它，以便在大小写敏感的 CI 文件系统上
+// 也能走到「等价路径冲突」分支。
+var isCaseInsensitiveFS = detectCaseInsensitiveFS
+
+// caseProbePattern 是探针文件名模板。抽成变量只为可测：纯数字模板的大写与原名相同，
+// 可覆盖「名称无大小写差异、无法据此判定」的回退分支。
+var caseProbePattern = "dws-caseprobe-*"
+
+// detectCaseInsensitiveFS 探测 dir 所在文件系统是否大小写不敏感：在 dir 下创建一个随机
+// 小写名探针文件，再用其大写名 stat；命中同一文件即为不敏感。dir 必须已存在。
+// 探测失败时回退到平台默认（Windows / macOS 视为不敏感，其它敏感）。
+func detectCaseInsensitiveFS(dir string) bool {
+	platformDefault := runtime.GOOS == "windows" || runtime.GOOS == "darwin"
+	f, err := os.CreateTemp(dir, caseProbePattern)
+	if err != nil {
+		return platformDefault
+	}
+	name := f.Name()
+	_ = f.Close()
+	defer os.Remove(name)
+	base := filepath.Base(name)
+	upper := strings.ToUpper(base)
+	if upper == base {
+		return platformDefault // 名称无大小写差异，无法据此判定
+	}
+	_, statErr := os.Stat(filepath.Join(dir, upper))
+	return statErr == nil
+}
+
+// detectTargetCollisions 按 caseInsensitive 指定的等价规则，找出会映射到同一本地目标
+// 的多个远端 rel_path，返回被判定冲突的 rel_path 集合（其中每个都不应落盘）。
+func detectTargetCollisions(absDir string, rels []string, caseInsensitive bool) map[string]bool {
+	groups := make(map[string][]string, len(rels))
+	for _, rel := range rels {
+		target := filepath.Join(absDir, filepath.FromSlash(rel))
+		key := pathCollisionKey(target, caseInsensitive)
+		groups[key] = append(groups[key], rel)
+	}
+	collided := make(map[string]bool)
+	for _, g := range groups {
+		if len(g) > 1 {
+			for _, r := range g {
+				collided[r] = true
+			}
+		}
+	}
+	return collided
+}
+
+func runDrivePull(cmd *cobra.Command, _ []string) error {
+	if err := validateRequiredFlags(cmd, "local-folder", "remote-folder"); err != nil {
+		return err
+	}
+	localDir := mustGetFlag(cmd, "local-folder")
+	remoteDirID := mustGetFlag(cmd, "remote-folder")
+	// space-id 可选：不传则由 fetchRemoteDriveTree 使用「我的文件」对应的空间。
+	spaceID := mustGetFlag(cmd, "space-id")
+
+	ifExists, _ := cmd.Flags().GetString("if-exists")
+	if ifExists == "" {
+		// 安全默认：不自动覆盖本地既有文件。
+		ifExists = ifExistsSkip
+	}
+	switch ifExists {
+	case ifExistsOverwrite, ifExistsSmart, ifExistsSkip:
+	default:
+		return fmt.Errorf("--if-exists 取值非法: %s（可选 overwrite|smart|skip）", ifExists)
+	}
+
+	absDir, err := validateLocalDirAbs(localDir)
+	if err != nil {
+		return err
+	}
+	// 在任何远端读取之前固定本地根计划：既有根立即持有 os.Root；不存在的根只固定
+	// 最近既存祖先并记录尚缺的逐层后缀。远端清单不完整或预检失败时不得创建本地根。
+	rootPlan, err := planPinnedPullRoot(absDir)
+	if err != nil {
+		return err
+	}
+	defer rootPlan.close()
+
+	ctx := cmd.Context()
+	// 复用 status 的远端遍历：按 parentId 递归拿到所有 type=FILE 的文件（key 为 rel_path）。
+	remote, err := fetchRemoteDriveTree(ctx, spaceID, remoteDirID, false)
+	if err != nil {
+		return err
+	}
+
+	// 稳定顺序输出（rel_path 升序）。
+	relPaths := make([]string, 0, len(remote))
+	for rel := range remote {
+		relPaths = append(relPaths, rel)
+	}
+	sort.Strings(relPaths)
+	preflight, localInfo, err := buildDrivePullPreflightFromPlan(rootPlan, remote)
+	if err != nil {
+		return err
+	}
+	if deps.Caller.DryRun() {
+		return printDrivePullDryRunWithLocalInfo(ifExists, remote, relPaths, preflight, localInfo)
+	}
+	// 镜像契约独立于当前主机文件系统：远端 A/a 或 NFC/NFD 异写（包括目录
+	// 前缀）在任何落盘前整批拒绝，避免同一远端树在不同平台得到不同镜像。
+	if len(preflight) > 0 {
+		res := drivePullPreflightFailureResult(relPaths, preflight)
+		if perr := deps.Out.PrintJSON(res); perr != nil {
+			return perr
+		}
+		return &drivePartialFailure{failed: res.Summary.Failed}
+	}
+	pinnedRoot, err := rootPlan.materialize()
+	if err != nil {
+		return err
+	}
+	defer pinnedRoot.close()
+
+	res := drivePullResult{Items: make([]drivePullItem, 0, len(relPaths))}
+	for _, rel := range relPaths {
+		rf := remote[rel]
+		// preflight 与真正下载之间仍需二次解析，挡住祖先目录被并发替换为软链的
+		// TOCTOU 逃逸；pullRemoteFile 将该检查收口在写入入口前。
+		action, perr := pullRemoteFilePinned(ctx, spaceID, rf, pinnedRoot, rel, ifExists)
+		item := drivePullItem{RelPath: rel, Action: action}
+		switch action {
+		case pullActionDownloaded:
+			res.Summary.Downloaded++
+		case pullActionSkipped:
+			res.Summary.Skipped++
+		case pullActionFailed:
+			res.Summary.Failed++
+			if perr != nil {
+				item.Error = perr.Error()
+			}
+		}
+		res.Items = append(res.Items, item)
+	}
+
+	// 结构化结果始终打印到 stdout；有失败则额外以非零退出码退出。
+	if perr := deps.Out.PrintJSON(res); perr != nil {
+		return perr
+	}
+	if res.Summary.Failed > 0 {
+		return &drivePartialFailure{failed: res.Summary.Failed}
+	}
+	return nil
+}
+
+func printDrivePullDryRun(absDir, ifExists string, remote map[string]*remoteFile, relPaths []string, caseInsensitive bool) error {
+	return printDrivePullDryRunWithPreflight(absDir, ifExists, remote, relPaths, caseInsensitive,
+		buildDrivePullPreflight(absDir, remote))
+}
+
+func printDrivePullDryRunWithPreflight(absDir, ifExists string, remote map[string]*remoteFile, relPaths []string, caseInsensitive bool, preflight map[string]string) error {
+	localInfo := make(map[string]os.FileInfo, len(relPaths))
+	for _, rel := range relPaths {
+		localPath, err := resolveLocalTarget(absDir, rel)
+		if err != nil {
+			continue
+		}
+		if info, statErr := os.Stat(localPath); statErr == nil && info.Mode().IsRegular() {
+			localInfo[rel] = info
+		}
+	}
+	_ = caseInsensitive // 保留 helper 的平台预览参数兼容性。
+	return printDrivePullDryRunWithLocalInfo(ifExists, remote, relPaths, preflight, localInfo)
+}
+
+func printDrivePullDryRunWithLocalInfo(ifExists string, remote map[string]*remoteFile, relPaths []string, preflight map[string]string, localInfo map[string]os.FileInfo) error {
+	plan := drivePullResult{Items: make([]drivePullItem, 0, len(relPaths))}
+	if len(preflight) > 0 {
+		plan = drivePullPreflightFailureResult(relPaths, preflight)
+		return deps.Out.PrintJSON(drivePullDryRunResult{
+			DryRun: true, Executed: false, PreviewKind: "plan", Operation: "drive pull",
+			IfExists: ifExists, Plan: plan,
+		})
+	}
+	for _, rel := range relPaths {
+		action := pullActionDownloaded
+		if fi := localInfo[rel]; fi != nil {
+			switch ifExists {
+			case ifExistsSkip:
+				action = pullActionSkipped
+			case ifExistsSmart:
+				rf := remote[rel]
+				if rf.ModifiedTimeValid && fi.ModTime().UnixMilli() >= rf.ModifiedTime {
+					action = pullActionSkipped
+				}
+			}
+		}
+		if action == pullActionSkipped {
+			plan.Summary.Skipped++
+		} else {
+			plan.Summary.Downloaded++
+		}
+		plan.Items = append(plan.Items, drivePullItem{RelPath: rel, Action: action})
+	}
+	return deps.Out.PrintJSON(drivePullDryRunResult{
+		DryRun: true, Executed: false, PreviewKind: "plan", Operation: "drive pull",
+		IfExists: ifExists, Plan: plan,
+	})
+}
+
+// buildDrivePullPreflight 在创建本地根目录、探测文件系统或下载任一文件之前，
+// 一次性验证完整远端树及每个本地落盘目标。任一目标是目录、符号链接、设备文件，
+// 或经既有符号链接逃逸时，整批 pull 都必须零写入中止。
+func buildDrivePullPreflight(absDir string, remote map[string]*remoteFile) map[string]string {
+	failures := buildMirrorPreflight(nil, nil, remote, nil)
+	addLocalTargetPreflightFailures(absDir, remote, failures)
+	return failures
+}
+
+// buildDrivePullPreflightFromPlan 只从 list_files 前已固定的根计划读取本地状态。
+// existing 根不再按 absDir 重开路径；missing 根在 ancestor Root 下仍必须完整缺失。
+func buildDrivePullPreflightFromPlan(plan *pinnedPullRootPlan, remote map[string]*remoteFile) (map[string]string, map[string]os.FileInfo, error) {
+	failures := buildMirrorPreflight(nil, nil, remote, nil)
+	localInfo := make(map[string]os.FileInfo, len(remote))
+	if err := plan.verify(); err != nil {
+		return nil, nil, err
+	}
+	if plan.existing != nil {
+		addPinnedLocalTargetPreflightFailures(plan.existing, remote, failures)
+		for rel := range remote {
+			if mirrorPreflightFailureForRel(rel, failures) != "" {
+				continue
+			}
+			info, err := pullRootLstat(plan.existing.root, filepath.FromSlash(rel))
+			if err == nil && info.Mode().IsRegular() {
+				localInfo[rel] = info
+			}
+		}
+	}
+	if err := plan.verify(); err != nil {
+		return nil, nil, err
+	}
+	return failures, localInfo, nil
+}
+
+func addLocalTargetPreflightFailures(absDir string, remote map[string]*remoteFile, failures map[string]string) {
+	for rel := range remote {
+		// 已被名称/类型冲突根屏蔽的后代不重复计错；一个冲突根只报告一次。
+		if mirrorPreflightFailureForRel(rel, failures) != "" {
+			continue
+		}
+		localPath, err := resolveLocalTarget(absDir, rel)
+		if err == nil {
+			err = rejectNonRegularLocalTarget(localPath)
+		}
+		if err != nil {
+			failures[rel] = err.Error()
+		}
+	}
+}
+
+func drivePullPreflightFailureResult(relPaths []string, preflight map[string]string) drivePullResult {
+	res := drivePullResult{Items: make([]drivePullItem, 0, len(relPaths))}
+	for _, rel := range relPaths {
+		msg := mirrorPreflightFailureForRel(rel, preflight)
+		if msg == "" {
+			msg = "另一镜像条目未通过预检，整批拉取已中止"
+		}
+		res.Summary.Failed++
+		res.Items = append(res.Items, drivePullItem{RelPath: rel, Action: pullActionFailed, Error: msg})
+	}
+	return res
+}
+
+func mirrorPreflightFailureForRel(rel string, preflight map[string]string) string {
+	for rel != "" {
+		if msg := preflight[rel]; msg != "" {
+			return msg
+		}
+		rel, _ = splitRel(rel)
+	}
+	return ""
+}
+
+func pullRemoteFile(ctx context.Context, spaceID string, rf *remoteFile, absDir, rel, ifExists string) (string, error) {
+	return pullOneFileAtRoot(ctx, spaceID, rf, absDir, rel, ifExists)
+}
+
+func pullRemoteFilePinned(ctx context.Context, spaceID string, rf *remoteFile, root *pinnedPullRoot, rel, ifExists string) (string, error) {
+	target, err := root.openTarget(rel)
+	if err != nil {
+		return pullActionFailed, err
+	}
+	defer target.close()
+	return pullOneFilePinned(ctx, spaceID, rf, target, ifExists)
+}
+
+// pullOneFile 处理单个远端文件：按 --if-exists 决定是否跳过，否则下载到 localPath。
+// 返回动作分类（downloaded / skipped / failed）及失败时的 error。
+func pullOneFile(ctx context.Context, spaceID string, rf *remoteFile, localPath, ifExists string) (string, error) {
+	return pullOneFileAtRoot(ctx, spaceID, rf, filepath.Dir(localPath), filepath.Base(localPath), ifExists)
+}
+
+func pullOneFileAtRoot(ctx context.Context, spaceID string, rf *remoteFile, absDir, rel, ifExists string) (string, error) {
+	root, err := openPinnedPullRoot(absDir)
+	if err != nil {
+		return pullActionFailed, err
+	}
+	defer root.close()
+	target, err := root.openTarget(rel)
+	if err != nil {
+		return pullActionFailed, err
+	}
+	defer target.close()
+	return pullOneFilePinned(ctx, spaceID, rf, target, ifExists)
+}
+
+func pullOneFilePinned(ctx context.Context, spaceID string, rf *remoteFile, target *pinnedPullTarget, ifExists string) (string, error) {
+	// 镜像文件的目标若已存在，必须是常规文件。目录、设备、FIFO 等都不能交给
+	// download_file / 临时文件写入流程，否则 dry-run 与执行结论会分叉，且目录目标
+	// 会在发出远端读请求后才失败。
+	initialInfo, err := target.regularTargetInfo()
+	if err != nil {
+		return pullActionFailed, err
+	}
+	// 本地已存在常规文件时，按策略判断是否跳过下载。
+	if initialInfo != nil {
+		switch ifExists {
+		case ifExistsSkip:
+			return pullActionSkipped, nil
+		case ifExistsSmart:
+			// 远端时间可信且本地 mtime 已 ≥ 远端 → 视为已对齐，跳过；
+			// 时间缺失/非法时不盲跳，退回继续下载。
+			if rf.ModifiedTimeValid && initialInfo.ModTime().UnixMilli() >= rf.ModifiedTime {
+				return pullActionSkipped, nil
+			}
+		case ifExistsOverwrite:
+			// 总是下载覆盖。
+		}
+	}
+
+	// download_file → 拿到带签名的下载 URL 与请求头，再 HTTP GET 落盘。
+	args := map[string]any{"fileId": rf.FileID}
+	if spaceID != "" {
+		args["spaceId"] = spaceID
+	}
+	text, err := callMCPToolReturnText(ctx, "download_file", args)
+	if err != nil {
+		return pullActionFailed, err
+	}
+	resourceURL, headers, err := parseDriveDownloadInfo(text)
+	if err != nil {
+		return pullActionFailed, err
+	}
+
+	// download_file 可执行任意时长的远端读。在任何 HTTP GET 或临时文件写入前，
+	// 必须确认目标父目录仍是最初固定在本地根下的同一目录。
+	if err := target.verifyParent(); err != nil {
+		return pullActionFailed, err
+	}
+
+	// 临时文件通过已固定的 os.Root 直接打开，下载直接写已打开的句柄；
+	// 生产路径不会再按可被换链的绝对路径重新打开临时文件。
+	tmp, tmpName, err := pullCreateTemp(target.parentRoot)
+	if err != nil {
+		return pullActionFailed, fmt.Errorf("创建临时文件失败: %w", err)
+	}
+	// 除非成功 rename，否则始终清理临时文件，不留半成品。
+	committed := false
+	tmpInfo, err := tmp.Stat()
+	if err != nil {
+		_ = tmp.Close()
+		_ = target.parentRoot.Remove(tmpName)
+		return pullActionFailed, fmt.Errorf("读取临时文件身份失败: %w", err)
+	}
+	defer func() {
+		_ = tmp.Close()
+		if !committed {
+			_ = target.parentRoot.Remove(tmpName)
+		}
+	}()
+
+	if err := pullDownloadFile(ctx, resourceURL, headers, tmp); err != nil {
+		return pullActionFailed, err
+	}
+	// 通过仍打开的文件句柄设置 mtime，避免按 tmpName 重新解析路径产生 symlink TOCTOU。
+	// 时间对齐延续既有 best-effort 语义，失败不影响已完整下载内容的发布。
+	if rf.ModifiedTimeValid {
+		_ = setPullFileTimes(tmp, time.UnixMilli(rf.ModifiedTime))
+	}
+	if err := pullSyncTemp(tmp); err != nil {
+		return pullActionFailed, fmt.Errorf("同步临时文件失败: %w", err)
+	}
+	if err := pullCloseTemp(tmp); err != nil {
+		return pullActionFailed, fmt.Errorf("关闭临时文件失败: %w", err)
+	}
+	currentTmp, err := pullRootLstat(target.parentRoot, tmpName)
+	if err != nil || !os.SameFile(tmpInfo, currentTmp) {
+		return pullActionFailed, fmt.Errorf("临时文件在下载期间被替换，已中止发布")
+	}
+	// 网络传输期间父目录仍可能被移走或替换。发布前再核对父目录身份和
+	// 目标类型；不一致时只删除固定目录内的临时文件，绝不发布。
+	if err := target.verifyParent(); err != nil {
+		return pullActionFailed, err
+	}
+	currentTarget, err := target.regularTargetInfo()
+	if err != nil {
+		return pullActionFailed, err
+	}
+	if ifExists != ifExistsOverwrite {
+		if currentTarget != nil && (initialInfo == nil || !os.SameFile(initialInfo, currentTarget)) {
+			return pullActionSkipped, nil
+		}
+		if ifExists == ifExistsSmart && currentTarget != nil && rf.ModifiedTimeValid && currentTarget.ModTime().UnixMilli() >= rf.ModifiedTime {
+			return pullActionSkipped, nil
+		}
+	}
+	if currentTarget == nil && ifExists != ifExistsOverwrite {
+		if err := pullLink(target.parentRoot, tmpName, target.name); err != nil {
+			if concurrent, statErr := target.regularTargetInfo(); statErr == nil && concurrent != nil {
+				return pullActionSkipped, nil
+			}
+			return pullActionFailed, fmt.Errorf("发布目标文件失败: %w", err)
+		}
+		if err := pullRemove(target.parentRoot, tmpName); err != nil {
+			return pullActionFailed, fmt.Errorf("清理临时文件失败: %w", err)
+		}
+	} else if err := pullRename(target.parentRoot, tmpName, target.name); err != nil {
+		return pullActionFailed, fmt.Errorf("替换目标文件失败: %w", err)
+	}
+	finalInfo, err := pullRootLstat(target.parentRoot, target.name)
+	if err != nil || !os.SameFile(tmpInfo, finalInfo) {
+		// 身份不匹配意味着发布后 terminal entry 可能已被并发替换；保留未知对象并报错，
+		// 不做 Lstat→Remove 的第二次 check/use，以免误删用户并发创建的文件。
+		return pullActionFailed, fmt.Errorf("发布后的目标文件身份不一致")
+	}
+	if err := target.verifyParent(); err != nil {
+		// 固定目录已从命令根路径移走时，保留句柄内已完成的结果并报失败；不能无条件
+		// Remove，因为发布后同名 terminal entry 仍可能被并发替换。
+		return pullActionFailed, err
+	}
+	committed = true
+	return pullActionDownloaded, nil
+}
+
+type pinnedPullRoot struct {
+	absDir   string
+	root     *os.Root
+	rootInfo os.FileInfo
+	pathInfo os.FileInfo
+}
+
+// pinnedPullRootPlan 在远端清单读取前固定 pull 的本地根状态。existing 非空表示
+// absDir 当时已存在；否则 ancestor 固定最近既存祖先，missing 保存从祖先到 absDir
+// 的逐层目录名。missing 只有在完整远端清单和本地预检通过后才允许物化。
+type pinnedPullRootPlan struct {
+	absDir   string
+	existing *pinnedPullRoot
+	ancestor *pinnedPullRoot
+	missing  []string
+}
+
+type pinnedPullTarget struct {
+	base        *pinnedPullRoot
+	parentRoot  *os.Root
+	parentChain []pinnedPullDirIdentity
+	name        string
+	ownsBase    bool
+}
+
+type pinnedPullDirIdentity struct {
+	rel  string
+	info os.FileInfo
+}
+
+func planPinnedPullRoot(absDir string) (*pinnedPullRootPlan, error) {
+	info, err := pullPathStat(absDir)
+	if err == nil {
+		if !info.IsDir() {
+			return nil, fmt.Errorf("创建本地目录失败: %s 已存在且不是目录", absDir)
+		}
+		root, openErr := openExistingPinnedPullRoot(absDir)
+		if openErr != nil {
+			return nil, openErr
+		}
+		return &pinnedPullRootPlan{absDir: absDir, existing: root}, nil
+	}
+	if !os.IsNotExist(err) {
+		return nil, fmt.Errorf("检查本地目录失败: %w", err)
+	}
+
+	ancestorPath := absDir
+	missing := make([]string, 0, 4)
+	for {
+		parent := filepath.Dir(ancestorPath)
+		// absDir 已是验证过的绝对路径；文件系统根目录始终存在，
+		// 因此循环必然在到达 parent == ancestorPath 之前以 Stat 成功结束。
+		name := filepath.Base(ancestorPath)
+		missing = append([]string{name}, missing...)
+		ancestorPath = parent
+		info, statErr := pullPathStat(ancestorPath)
+		if statErr == nil {
+			if !info.IsDir() {
+				return nil, fmt.Errorf("创建本地目录失败: %s 已存在且不是目录", ancestorPath)
+			}
+			break
+		}
+		if !os.IsNotExist(statErr) {
+			return nil, fmt.Errorf("检查本地目录失败: %w", statErr)
+		}
+	}
+	ancestor, openErr := openExistingPinnedPullRoot(ancestorPath)
+	if openErr != nil {
+		return nil, openErr
+	}
+	plan := &pinnedPullRootPlan{absDir: absDir, ancestor: ancestor, missing: missing}
+	if verifyErr := plan.verify(); verifyErr != nil {
+		plan.close()
+		return nil, verifyErr
+	}
+	return plan, nil
+}
+
+func (plan *pinnedPullRootPlan) verify() error {
+	if plan.existing != nil {
+		return plan.existing.verify()
+	}
+	if plan.ancestor == nil {
+		return fmt.Errorf("本地根目录计划无效")
+	}
+	if err := plan.ancestor.verify(); err != nil {
+		return err
+	}
+	prefix := ""
+	for _, segment := range plan.missing {
+		prefix = filepath.Join(prefix, segment)
+		_, err := pullRootLstat(plan.ancestor.root, prefix)
+		if err == nil {
+			return fmt.Errorf("本地根目录 %q 在远端读取期间被占用，已中止写入", plan.absDir)
+		}
+		if !os.IsNotExist(err) {
+			return fmt.Errorf("检查本地根目录计划失败: %w", err)
+		}
+		// 第一层缺失后更深的路径不可能存在；物化时每层 Mkdir 仍以 no-clobber
+		// 语义拒绝 verify 与创建之间的并发抢占。
+		break
+	}
+	return nil
+}
+
+func (plan *pinnedPullRootPlan) materialize() (*pinnedPullRoot, error) {
+	if err := plan.verify(); err != nil {
+		return nil, err
+	}
+	if plan.existing != nil {
+		root := plan.existing
+		plan.existing = nil
+		return root, nil
+	}
+
+	current, err := pullOpenParentRoot(plan.ancestor.root, ".")
+	if err != nil {
+		return nil, fmt.Errorf("固定本地根祖先失败: %w", err)
+	}
+	for _, segment := range plan.missing {
+		if err := pullRootMkdir(current, segment, 0o755); err != nil {
+			_ = current.Close()
+			return nil, fmt.Errorf("创建本地目录失败: %w", err)
+		}
+		createdInfo, err := pullRootLstat(current, segment)
+		if err != nil || !createdInfo.IsDir() {
+			_ = current.Close()
+			return nil, fmt.Errorf("读取新建本地目录身份失败")
+		}
+		next, err := pullOpenParentRoot(current, segment)
+		if err != nil {
+			_ = current.Close()
+			return nil, fmt.Errorf("固定新建本地目录失败: %w", err)
+		}
+		nextInfo, statErr := pullRootStat(next, ".")
+		if statErr != nil || !os.SameFile(createdInfo, nextInfo) {
+			_ = next.Close()
+			_ = current.Close()
+			return nil, fmt.Errorf("新建本地目录在固定期间被替换，已中止写入")
+		}
+		_ = current.Close()
+		current = next
+	}
+	rootInfo, err := pullRootStat(current, ".")
+	if err != nil {
+		_ = current.Close()
+		return nil, fmt.Errorf("读取本地根目录身份失败: %w", err)
+	}
+	pathInfo, err := pullPathLstat(plan.absDir)
+	if err != nil {
+		_ = current.Close()
+		return nil, fmt.Errorf("读取本地根目录路径身份失败: %w", err)
+	}
+	root := &pinnedPullRoot{absDir: plan.absDir, root: current, rootInfo: rootInfo, pathInfo: pathInfo}
+	if err := root.verify(); err != nil {
+		root.close()
+		return nil, err
+	}
+	return root, nil
+}
+
+func (plan *pinnedPullRootPlan) close() {
+	if plan.existing != nil {
+		plan.existing.close()
+		plan.existing = nil
+	}
+	if plan.ancestor != nil {
+		plan.ancestor.close()
+		plan.ancestor = nil
+	}
+}
+
+func openPinnedPullRoot(absDir string) (*pinnedPullRoot, error) {
+	if err := pullMkdirAll(absDir, 0o755); err != nil {
+		return nil, fmt.Errorf("创建本地目录失败: %w", err)
+	}
+	return openExistingPinnedPullRoot(absDir)
+}
+
+// openExistingPinnedPullRoot 只固定已经存在的本地目录。push/sync 必须用这一入口：
+// 本地源根不存在时直接失败，不能为了扫描或上传隐式创建一个空源目录。
+func openExistingPinnedPullRoot(absDir string) (*pinnedPullRoot, error) {
+	baseRoot, err := pullOpenRoot(absDir)
+	if err != nil {
+		return nil, fmt.Errorf("打开本地根目录失败: %w", err)
+	}
+	rootInfo, err := pullRootStat(baseRoot, ".")
+	if err != nil {
+		_ = baseRoot.Close()
+		return nil, fmt.Errorf("读取本地根目录身份失败: %w", err)
+	}
+	pathInfo, err := pullPathLstat(absDir)
+	if err != nil {
+		_ = baseRoot.Close()
+		return nil, fmt.Errorf("读取本地根目录路径身份失败: %w", err)
+	}
+	root := &pinnedPullRoot{absDir: absDir, root: baseRoot, rootInfo: rootInfo, pathInfo: pathInfo}
+	if err := root.verify(); err != nil {
+		root.close()
+		return nil, err
+	}
+	return root, nil
+}
+
+func openPinnedPullTarget(absDir, rel string) (*pinnedPullTarget, error) {
+	root, err := openPinnedPullRoot(absDir)
+	if err != nil {
+		return nil, err
+	}
+	target, err := root.openTarget(rel)
+	if err != nil {
+		root.close()
+		return nil, err
+	}
+	target.ownsBase = true
+	return target, nil
+}
+
+func (root *pinnedPullRoot) openTarget(rel string) (*pinnedPullTarget, error) {
+	if err := root.verify(); err != nil {
+		return nil, err
+	}
+	localPath := filepath.Join(root.absDir, filepath.FromSlash(rel))
+	localRel, err := pullRelPath(root.absDir, localPath)
+	if err != nil || localRel == ".." || strings.HasPrefix(localRel, ".."+string(filepath.Separator)) {
+		return nil, fmt.Errorf("远端路径 %q 逃逸出本地根目录", rel)
+	}
+	parentRel := filepath.Dir(localRel)
+	parentRoot, parentChain, err := root.openTargetParent(parentRel)
+	if err != nil {
+		return nil, err
+	}
+	target := &pinnedPullTarget{
+		base: root, parentRoot: parentRoot, parentChain: parentChain,
+		name: filepath.Base(localRel),
+	}
+	if err := target.verifyParent(); err != nil {
+		target.close()
+		return nil, err
+	}
+	return target, nil
+}
+
+// openTargetParent 从固定根开始逐层创建并打开目标父目录。os.Root 会安全地阻止
+// 软链接逃逸根外，但允许跟随仍指向根内的相对软链接；镜像语义不能接受这种重定向，
+// 否则 remote sub/a.txt 可能覆盖同一根下 victim/a.txt。因此每一层都必须：
+//
+//  1. 以 Lstat 拒绝软链接 / junction 及非目录；
+//  2. 通过上一层已固定的 Root 打开下一层；
+//  3. 再以 Lstat + SameFile 证明打开的就是目录项本身，而不是竞态中换入的链接目标。
+//
+// parentChain 保存每一层目录项身份，后续每次 verifyParent 都从命令根重新复核。
+func (root *pinnedPullRoot) openTargetParent(parentRel string) (*os.Root, []pinnedPullDirIdentity, error) {
+	current, err := pullOpenParentRoot(root.root, ".")
+	if err != nil {
+		return nil, nil, fmt.Errorf("固定本地目标目录失败: %w", err)
+	}
+	chain := make([]pinnedPullDirIdentity, 0, 4)
+	if parentRel == "." {
+		info, err := pullRootLstat(root.root, ".")
+		if err != nil || !info.IsDir() || info.Mode()&os.ModeSymlink != 0 {
+			_ = current.Close()
+			return nil, nil, fmt.Errorf("本地目标目录不是可固定的真实目录")
+		}
+		openedInfo, statErr := pullRootStat(current, ".")
+		if statErr != nil || !os.SameFile(info, openedInfo) {
+			_ = current.Close()
+			return nil, nil, fmt.Errorf("本地目标目录在固定期间被替换，已中止写入")
+		}
+		chain = append(chain, pinnedPullDirIdentity{rel: ".", info: info})
+		return current, chain, nil
+	}
+
+	prefix := ""
+	for _, segment := range strings.Split(parentRel, string(filepath.Separator)) {
+		info, lstatErr := pullRootLstat(current, segment)
+		if os.IsNotExist(lstatErr) {
+			if mkdirErr := pullRootMkdir(current, segment, 0o755); mkdirErr != nil {
+				_ = current.Close()
+				return nil, nil, fmt.Errorf("创建本地目录失败: %w", mkdirErr)
+			}
+			info, lstatErr = pullRootLstat(current, segment)
+		}
+		if lstatErr != nil {
+			_ = current.Close()
+			return nil, nil, fmt.Errorf("检查本地目标目录失败: %w", lstatErr)
+		}
+		if !info.IsDir() || info.Mode()&os.ModeSymlink != 0 {
+			_ = current.Close()
+			return nil, nil, fmt.Errorf("本地目标目录 %q 已存在且不是可固定的真实目录，已拒绝镜像", filepath.Join(prefix, segment))
+		}
+
+		next, openErr := pullOpenParentRoot(current, segment)
+		if openErr != nil {
+			_ = current.Close()
+			return nil, nil, fmt.Errorf("固定本地目标目录失败: %w", openErr)
+		}
+		openedInfo, statErr := pullRootStat(next, ".")
+		currentInfo, currentErr := pullRootLstat(current, segment)
+		if statErr != nil || currentErr != nil || !currentInfo.IsDir() || currentInfo.Mode()&os.ModeSymlink != 0 ||
+			!os.SameFile(info, currentInfo) || !os.SameFile(currentInfo, openedInfo) {
+			_ = next.Close()
+			_ = current.Close()
+			return nil, nil, fmt.Errorf("本地目标目录在固定期间被替换，已中止写入")
+		}
+		prefix = filepath.Join(prefix, segment)
+		chain = append(chain, pinnedPullDirIdentity{rel: prefix, info: currentInfo})
+		_ = current.Close()
+		current = next
+	}
+	return current, chain, nil
+}
+
+func (root *pinnedPullRoot) verify() error {
+	current, err := pullPathStat(root.absDir)
+	currentPath, pathErr := pullPathLstat(root.absDir)
+	if err != nil || pathErr != nil || !os.SameFile(root.rootInfo, current) || !os.SameFile(root.pathInfo, currentPath) {
+		return fmt.Errorf("本地根目录在同步期间被替换，已中止写入")
+	}
+	return nil
+}
+
+func (root *pinnedPullRoot) close() { _ = root.root.Close() }
+
+func (target *pinnedPullTarget) close() {
+	_ = target.parentRoot.Close()
+	if target.ownsBase {
+		target.base.close()
+	}
+}
+
+func (target *pinnedPullTarget) verifyParent() error {
+	if err := target.base.verify(); err != nil {
+		return err
+	}
+	for _, expected := range target.parentChain {
+		current, err := pullRootLstat(target.base.root, expected.rel)
+		if err != nil || !current.IsDir() || current.Mode()&os.ModeSymlink != 0 || !os.SameFile(expected.info, current) {
+			return fmt.Errorf("本地目标目录在下载期间被替换，已中止写入")
+		}
+	}
+	return nil
+}
+
+func (target *pinnedPullTarget) regularTargetInfo() (os.FileInfo, error) {
+	info, err := pullRootLstat(target.parentRoot, target.name)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return nil, nil
+		}
+		return nil, fmt.Errorf("检查本地目标失败: %w", err)
+	}
+	if !info.Mode().IsRegular() {
+		return nil, fmt.Errorf("本地目标 %q 已存在且不是常规文件，已拒绝覆盖", target.name)
+	}
+	return info, nil
+}
+
+func createPinnedPullTemp(root *os.Root) (*os.File, string, error) {
+	for i := 0; i < 100; i++ {
+		name := ".dws-pull-" + pullTempName()
+		file, err := root.OpenFile(name, os.O_RDWR|os.O_CREATE|os.O_EXCL, 0o600)
+		if err == nil {
+			return file, name, nil
+		}
+		if !os.IsExist(err) {
+			return nil, "", err
+		}
+	}
+	return nil, "", fmt.Errorf("创建不重名临时文件失败")
+}
+
+func defaultPullDownloadFile(ctx context.Context, url string, headers map[string]string, destination *os.File) error {
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
+	if err != nil {
+		return err
+	}
+	for key, value := range headers {
+		req.Header.Set(key, value)
+	}
+	resp, err := pullHTTPDo(req)
+	if err != nil {
+		return err
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode != http.StatusOK {
+		body, _ := io.ReadAll(resp.Body)
+		return &httpStatusError{StatusCode: resp.StatusCode, Body: string(body)}
+	}
+	_, err = io.Copy(destination, resp.Body)
+	return err
+}
+
+// rejectNonRegularLocalTarget 在任何下载工具调用或临时文件创建之前，拒绝已存在但
+// 不是常规文件的镜像目标。不存在的目标可由后续流程安全创建。
+func rejectNonRegularLocalTarget(localPath string) error {
+	info, err := pullTargetLstat(localPath)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return nil
+		}
+		return fmt.Errorf("检查本地目标失败: %w", err)
+	}
+	if !info.Mode().IsRegular() {
+		return fmt.Errorf("本地目标 %q 已存在且不是常规文件，已拒绝覆盖", localPath)
+	}
+	return nil
+}

internal/helpers/drive_pull_coverage_test.go

@@ -0,0 +1,259 @@
+package helpers
+
+import (
+	"context"
+	"errors"
+	"io"
+	"os"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam"
+)
+
+// ──────────────────────────────────────────────────────────
+// runDrivePull — 端到端：远端树 → 本地落盘
+// ──────────────────────────────────────────────────────────
+
+// pullListingCaller 返回固定的单层远端清单，download_file 给出预签名链接。
+func pullListingCaller(items string) *driveScriptCaller {
+	return &driveScriptCaller{reply: func(tool string, _ map[string]any, nth int) (string, error) {
+		switch tool {
+		case "list_files":
+			if nth > 0 {
+				return `{"result":{"items":[],"nextToken":""}}`, nil
+			}
+			return `{"result":{"items":[` + items + `],"nextToken":""}}`, nil
+		case "download_file":
+			return `{"result":{"downloadUrl":"https://oss.example.com/get","headers":{}}}`, nil
+		}
+		return `{"result":{},"success":true}`, nil
+	}}
+}
+
+// 端到端 pull：远端两个文件都下载到本地，并自动创建缺失的本地根目录。
+func TestCrossPlatformCoverageDrivePull_endToEndDownloadsAll(t *testing.T) {
+	root := filepath.Join(t.TempDir(), "created-by-pull")
+	caller := pullListingCaller(
+		`{"name":"a.txt","type":"file","fileId":"A","modifyTime":1000},` +
+			`{"name":"b.txt","type":"file","fileId":"B","modifyTime":2000}`)
+
+	swapPullDownloadPath(t, func(_ context.Context, _ string, _ map[string]string, dest string) error {
+		return os.WriteFile(dest, []byte("remote"), 0o644)
+	})
+
+	if err := runDriveCmd(t, caller, "pull", "--local-folder", root, "--remote-folder", "ROOT"); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	for _, name := range []string{"a.txt", "b.txt"} {
+		if b, err := os.ReadFile(filepath.Join(root, name)); err != nil || string(b) != "remote" {
+			t.Errorf("%s not written: %v / %q", name, err, string(b))
+		}
+	}
+}
+
+// --if-exists skip：本地已存在则不下载。
+func TestCrossPlatformCoverageDrivePull_ifExistsSkipKeepsLocal(t *testing.T) {
+	root := t.TempDir()
+	mustWrite(t, filepath.Join(root, "a.txt"), "local-original")
+	caller := pullListingCaller(`{"name":"a.txt","type":"file","fileId":"A","modifyTime":9000}`)
+
+	swapPullDownloadPath(t, func(context.Context, string, map[string]string, string) error {
+		t.Error("skip must not download")
+		return nil
+	})
+
+	if err := runDriveCmd(t, caller, "pull", "--local-folder", root, "--remote-folder", "ROOT", "--if-exists", "skip"); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if b, _ := os.ReadFile(filepath.Join(root, "a.txt")); string(b) != "local-original" {
+		t.Errorf("local file changed: %q", string(b))
+	}
+}
+
+// --if-exists smart：本地 mtime 已 ≥ 远端 → 跳过；远端更新 → 下载。
+func TestCrossPlatformCoverageDrivePull_ifExistsSmart(t *testing.T) {
+	t.Run("local newer skips", func(t *testing.T) {
+		root := t.TempDir()
+		p := filepath.Join(root, "a.txt")
+		mustWrite(t, p, "local")
+		local := readFileMTimeMillis(t, p)
+		caller := pullListingCaller(`{"name":"a.txt","type":"file","fileId":"A","modifyTime":` + strconv.FormatInt(local-5000, 10) + `}`)
+
+		swapPullDownloadPath(t, func(context.Context, string, map[string]string, string) error {
+			t.Error("smart must not download when local is newer")
+			return nil
+		})
+
+		if err := runDriveCmd(t, caller, "pull", "--local-folder", root, "--remote-folder", "ROOT", "--if-exists", "smart"); err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if b, _ := os.ReadFile(p); string(b) != "local" {
+			t.Errorf("local file changed: %q", string(b))
+		}
+	})
+
+	t.Run("remote newer downloads", func(t *testing.T) {
+		root := t.TempDir()
+		p := filepath.Join(root, "a.txt")
+		mustWrite(t, p, "local")
+		local := readFileMTimeMillis(t, p)
+		caller := pullListingCaller(`{"name":"a.txt","type":"file","fileId":"A","modifyTime":` + strconv.FormatInt(local+60000, 10) + `}`)
+
+		swapPullDownloadPath(t, func(_ context.Context, _ string, _ map[string]string, dest string) error {
+			return os.WriteFile(dest, []byte("fresh"), 0o644)
+		})
+
+		if err := runDriveCmd(t, caller, "pull", "--local-folder", root, "--remote-folder", "ROOT", "--if-exists", "smart"); err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if b, _ := os.ReadFile(p); string(b) != "fresh" {
+			t.Errorf("expected download, got %q", string(b))
+		}
+	})
+}
+
+// --if-exists 非法值直接拒绝。
+func TestCrossPlatformCoverageDrivePull_invalidIfExistsRejected(t *testing.T) {
+	caller := pullListingCaller("")
+	err := runDriveCmd(t, caller, "pull", "--local-folder", t.TempDir(), "--remote-folder", "ROOT", "--if-exists", "bogus")
+	if err == nil || !strings.Contains(err.Error(), "--if-exists") {
+		t.Fatalf("expected --if-exists rejection, got %v", err)
+	}
+}
+
+// space-id 透传到 download_file。
+func TestCrossPlatformCoverageDrivePull_passesSpaceIDToDownload(t *testing.T) {
+	root := t.TempDir()
+	caller := pullListingCaller(`{"name":"a.txt","type":"file","fileId":"A","modifyTime":1}`)
+	swapPullDownloadPath(t, func(_ context.Context, _ string, _ map[string]string, dest string) error {
+		return os.WriteFile(dest, []byte("x"), 0o644)
+	})
+
+	if err := runDriveCmd(t, caller, "pull", "--local-folder", root, "--remote-folder", "ROOT", "--space-id", "SP9"); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if got := caller.callsFor("download_file")[0].args["spaceId"]; got != "SP9" {
+		t.Errorf("download_file spaceId = %v, want SP9", got)
+	}
+}
+
+// 下载失败 → 该项记 failed，命令以 partial_failure 非零退出。
+func TestCrossPlatformCoverageDrivePull_downloadFailureIsPartialFailure(t *testing.T) {
+	root := t.TempDir()
+	caller := pullListingCaller(`{"name":"a.txt","type":"file","fileId":"A","modifyTime":1}`)
+	swapPullDownloadPath(t, func(context.Context, string, map[string]string, string) error { return errTestDownload })
+
+	var out strings.Builder
+	testseam.Swap(t, &deps, &Deps{Caller: caller, Out: &Formatter{w: &out}})
+	testseam.Swap(t, &os.Args, []string{"dws", "drive", "pull"})
+
+	cmd := findDriveSubcommand(t, "pull")
+	mustSetFlags(t, cmd, map[string]string{"local-folder": root, "remote-folder": "ROOT"})
+	err := runDrivePull(cmd, nil)
+	var pf *drivePartialFailure
+	if !errors.As(err, &pf) {
+		t.Fatalf("expected drivePartialFailure, got %T %v", err, err)
+	}
+	if pf.failed != 1 || pf.RawStderr() != "drive pull: 1 file(s) failed" {
+		t.Errorf("partial failure = %#v, stderr = %q", pf, pf.RawStderr())
+	}
+	stdout := out.String()
+	if !strings.Contains(stdout, `"failed": 1`) || !strings.Contains(stdout, `"rel_path": "a.txt"`) {
+		t.Errorf("stdout must retain the structured partial result: %s", stdout)
+	}
+}
+
+// download_file 未返回下载链接 → failed（不是 panic，也不落盘）。
+func TestCrossPlatformCoverageDrivePull_missingDownloadURLFails(t *testing.T) {
+	root := t.TempDir()
+	caller := &driveScriptCaller{reply: func(tool string, _ map[string]any, nth int) (string, error) {
+		if tool == "list_files" {
+			if nth > 0 {
+				return `{"result":{"items":[],"nextToken":""}}`, nil
+			}
+			return `{"result":{"items":[{"name":"a.txt","type":"file","fileId":"A"}],"nextToken":""}}`, nil
+		}
+		return `{"result":{"fileId":"A"},"success":true}`, nil // 无 downloadUrl
+	}}
+	if err := runDriveCmd(t, caller, "pull", "--local-folder", root, "--remote-folder", "ROOT"); err == nil {
+		t.Fatal("expected failure when download_file returns no URL")
+	}
+	if _, err := os.Stat(filepath.Join(root, "a.txt")); !os.IsNotExist(err) {
+		t.Error("nothing must be written when the download URL is missing")
+	}
+}
+
+// download_file 的 MCP 调用本身失败 → failed。
+func TestCrossPlatformCoverageDrivePull_downloadToolErrorFails(t *testing.T) {
+	root := t.TempDir()
+	caller := &driveScriptCaller{reply: func(tool string, _ map[string]any, nth int) (string, error) {
+		if tool == "list_files" {
+			if nth > 0 {
+				return `{"result":{"items":[],"nextToken":""}}`, nil
+			}
+			return `{"result":{"items":[{"name":"a.txt","type":"file","fileId":"A"}],"nextToken":""}}`, nil
+		}
+		return "", errTestDownload
+	}}
+	if err := runDriveCmd(t, caller, "pull", "--local-folder", root, "--remote-folder", "ROOT"); err == nil {
+		t.Fatal("expected failure when download_file errors")
+	}
+}
+
+// 远端名称逃逸出本地根 → 记 failed，不落盘（resolveLocalTarget 二次确认）。
+func TestCrossPlatformCoverageDrivePull_escapingRelPathIsFailed(t *testing.T) {
+	root := t.TempDir()
+	// 远端目录名合法，但目录内的软链把落盘点指到根目录外。
+	outside := t.TempDir()
+	if err := os.Symlink(outside, filepath.Join(root, "sub")); err != nil {
+		t.Skipf("symlink unsupported: %v", err)
+	}
+	caller := &driveScriptCaller{reply: func(tool string, args map[string]any, _ int) (string, error) {
+		if tool != "list_files" {
+			return `{"result":{"downloadUrl":"https://oss.example.com/get"}}`, nil
+		}
+		switch args["parentId"] {
+		case "ROOT":
+			return `{"result":{"items":[{"name":"sub","type":"folder","fileId":"SUB"}],"nextToken":""}}`, nil
+		case "SUB":
+			return `{"result":{"items":[{"name":"leaked.txt","type":"file","fileId":"L"}],"nextToken":""}}`, nil
+		}
+		return `{"result":{"items":[],"nextToken":""}}`, nil
+	}}
+	swapPullDownloadPath(t, func(_ context.Context, _ string, _ map[string]string, dest string) error {
+		return os.WriteFile(dest, []byte("leak"), 0o644)
+	})
+
+	if err := runDriveCmd(t, caller, "pull", "--local-folder", root, "--remote-folder", "ROOT"); err == nil {
+		t.Fatal("expected symlink escape to be reported as failure")
+	}
+	if _, err := os.Stat(filepath.Join(outside, "leaked.txt")); !os.IsNotExist(err) {
+		t.Error("file escaped the local root")
+	}
+}
+
+// 目标父目录不可创建（同名常规文件占位）→ failed，不 panic。
+func TestCrossPlatformCoveragePullOneFile_mkdirFailureIsFailed(t *testing.T) {
+	root := t.TempDir()
+	// "sub" 是普通文件，MkdirAll("sub") 必然失败。
+	mustWrite(t, filepath.Join(root, "sub"), "occupied")
+
+	testseam.Swap(t, &deps, &Deps{Caller: pullListingCaller(""), Out: &Formatter{w: io.Discard}})
+	testseam.Swap(t, &os.Args, []string{"dws", "drive"})
+
+	rf := &remoteFile{RelPath: "sub/x.txt", FileID: "X"}
+	action, err := pullOneFile(context.Background(), "", rf, filepath.Join(root, "sub", "x.txt"), ifExistsOverwrite)
+	if action != pullActionFailed || err == nil {
+		t.Fatalf("action=%q err=%v, want failed + error", action, err)
+	}
+}
+
+// 探测目录不存在时 isCaseInsensitiveFS 回退平台默认，不 panic。
+func TestCrossPlatformCoverageIsCaseInsensitiveFS_missingDirFallsBackToPlatformDefault(t *testing.T) {
+	missing := filepath.Join(t.TempDir(), "absent")
+	// 只断言不 panic 且返回布尔（具体值取决于平台默认）。
+	_ = isCaseInsensitiveFS(missing)
+}

internal/helpers/drive_pull_plan_coverage_test.go

@@ -0,0 +1,512 @@
+package helpers
+
+import (
+	"context"
+	"errors"
+	"io"
+	"net/http"
+	"os"
+	"path/filepath"
+	"runtime"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam"
+)
+
+func newPinnedPullRootForCoverage(t *testing.T, path string) *pinnedPullRoot {
+	t.Helper()
+	root, err := openExistingPinnedPullRoot(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(root.close)
+	return root
+}
+
+func newMissingPinnedPullPlanForCoverage(t *testing.T) *pinnedPullRootPlan {
+	t.Helper()
+	root := filepath.Join(t.TempDir(), "missing", "mirror")
+	plan, err := planPinnedPullRoot(root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(plan.close)
+	return plan
+}
+
+func TestCrossPlatformCoverageDrivePullRootPlanFailures(t *testing.T) {
+	t.Run("existing root open", func(t *testing.T) {
+		testseam.Swap(t, &pullOpenRoot, func(string) (*os.Root, error) { return nil, errTestDownload })
+		if _, err := planPinnedPullRoot(t.TempDir()); err == nil {
+			t.Fatal("expected existing-root open failure")
+		}
+	})
+
+	t.Run("ancestor is a file", func(t *testing.T) {
+		parent := t.TempDir()
+		file := filepath.Join(parent, "file")
+		mustWrite(t, file, "x")
+		if _, err := planPinnedPullRoot(filepath.Join(file, "child")); err == nil ||
+			(!strings.Contains(err.Error(), "不是目录") && !strings.Contains(err.Error(), "not a directory")) {
+			t.Fatalf("error = %v", err)
+		}
+	})
+
+	t.Run("ancestor discovered as file", func(t *testing.T) {
+		file := filepath.Join(t.TempDir(), "file")
+		mustWrite(t, file, "x")
+		calls := 0
+		testseam.Swap(t, &pullPathStat, func(string) (os.FileInfo, error) {
+			calls++
+			if calls == 1 {
+				return nil, os.ErrNotExist
+			}
+			return os.Stat(file)
+		})
+		if _, err := planPinnedPullRoot(filepath.Join(t.TempDir(), "missing")); err == nil || !strings.Contains(err.Error(), "不是目录") {
+			t.Fatalf("error = %v", err)
+		}
+	})
+
+	t.Run("ancestor open", func(t *testing.T) {
+		testseam.Swap(t, &pullOpenRoot, func(string) (*os.Root, error) { return nil, errTestDownload })
+		if _, err := planPinnedPullRoot(filepath.Join(t.TempDir(), "missing")); err == nil {
+			t.Fatal("expected ancestor open failure")
+		}
+	})
+
+	t.Run("path stat errors", func(t *testing.T) {
+		for _, initial := range []bool{true, false} {
+			t.Run(map[bool]string{true: "initial", false: "ancestor"}[initial], func(t *testing.T) {
+				calls := 0
+				testseam.Swap(t, &pullPathStat, func(path string) (os.FileInfo, error) {
+					calls++
+					if initial || calls > 1 {
+						return nil, errTestDownload
+					}
+					return nil, os.ErrNotExist
+				})
+				if _, err := planPinnedPullRoot(filepath.Join(t.TempDir(), "missing")); err == nil {
+					t.Fatal("expected path stat failure")
+				}
+			})
+		}
+	})
+
+	t.Run("initial verification", func(t *testing.T) {
+		calls := 0
+		testseam.Swap(t, &pullRootLstat, func(root *os.Root, name string) (os.FileInfo, error) {
+			calls++
+			if calls == 1 {
+				return nil, errTestDownload
+			}
+			return root.Lstat(name)
+		})
+		if _, err := planPinnedPullRoot(filepath.Join(t.TempDir(), "missing")); err == nil {
+			t.Fatal("expected initial plan verification failure")
+		}
+	})
+
+	t.Run("invalid and changed plan", func(t *testing.T) {
+		if err := (&pinnedPullRootPlan{}).verify(); err == nil {
+			t.Fatal("expected invalid plan failure")
+		}
+		root := newPinnedPullRootForCoverage(t, t.TempDir())
+		bad := *root
+		bad.absDir = filepath.Join(t.TempDir(), "gone")
+		if err := (&pinnedPullRootPlan{ancestor: &bad}).verify(); err == nil {
+			t.Fatal("expected changed ancestor failure")
+		}
+	})
+
+	t.Run("unexpected missing-path lstat", func(t *testing.T) {
+		plan := newMissingPinnedPullPlanForCoverage(t)
+		testseam.Swap(t, &pullRootLstat, func(*os.Root, string) (os.FileInfo, error) { return nil, errTestDownload })
+		if err := plan.verify(); err == nil {
+			t.Fatal("expected missing-path lstat failure")
+		}
+	})
+}
+
+func TestCrossPlatformCoverageDrivePullRootMaterializeFailures(t *testing.T) {
+	t.Run("verification", func(t *testing.T) {
+		if _, err := (&pinnedPullRootPlan{}).materialize(); err == nil {
+			t.Fatal("expected materialize verification failure")
+		}
+	})
+
+	for _, tc := range []struct {
+		name string
+		stub func(*testing.T)
+	}{
+		{"open ancestor", func(t *testing.T) {
+			testseam.Swap(t, &pullOpenParentRoot, func(*os.Root, string) (*os.Root, error) { return nil, errTestDownload })
+		}},
+		{"mkdir", func(t *testing.T) {
+			testseam.Swap(t, &pullRootMkdir, func(*os.Root, string, os.FileMode) error { return errTestDownload })
+		}},
+		{"created lstat", func(t *testing.T) {
+			testseam.Swap(t, &pullRootLstat, func(*os.Root, string) (os.FileInfo, error) { return nil, errTestDownload })
+		}},
+		{"created not directory", func(t *testing.T) {
+			file := filepath.Join(t.TempDir(), "file")
+			mustWrite(t, file, "x")
+			info, err := os.Lstat(file)
+			if err != nil {
+				t.Fatal(err)
+			}
+			testseam.Swap(t, &pullRootLstat, func(*os.Root, string) (os.FileInfo, error) { return info, nil })
+		}},
+		{"created changes before root identity", func(t *testing.T) {
+			calls := 0
+			testseam.Swap(t, &pullRootLstat, func(root *os.Root, name string) (os.FileInfo, error) {
+				calls++
+				if calls == 2 {
+					return nil, errTestDownload
+				}
+				return root.Lstat(name)
+			})
+		}},
+		{"open created", func(t *testing.T) {
+			calls := 0
+			testseam.Swap(t, &pullOpenParentRoot, func(root *os.Root, name string) (*os.Root, error) {
+				calls++
+				if calls > 1 {
+					return nil, errTestDownload
+				}
+				return root.OpenRoot(name)
+			})
+		}},
+		{"created identity", func(t *testing.T) {
+			calls := 0
+			testseam.Swap(t, &pullRootStat, func(root *os.Root, name string) (os.FileInfo, error) {
+				calls++
+				if calls == 1 {
+					return nil, errTestDownload
+				}
+				return root.Stat(name)
+			})
+		}},
+		{"final root stat", func(t *testing.T) {
+			calls := 0
+			testseam.Swap(t, &pullRootStat, func(root *os.Root, name string) (os.FileInfo, error) {
+				calls++
+				if calls == 3 {
+					return nil, errTestDownload
+				}
+				return root.Stat(name)
+			})
+		}},
+		{"final verification", func(t *testing.T) {
+			calls := 0
+			testseam.Swap(t, &pullPathLstat, func(path string) (os.FileInfo, error) {
+				calls++
+				if calls >= 2 {
+					return nil, errTestDownload
+				}
+				return os.Lstat(path)
+			})
+		}},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			plan := newMissingPinnedPullPlanForCoverage(t)
+			tc.stub(t)
+			if root, err := plan.materialize(); err == nil {
+				root.close()
+				t.Fatal("expected materialize failure")
+			}
+		})
+	}
+
+	t.Run("final lstat and verify", func(t *testing.T) {
+		for _, failAt := range []int{1, 2} {
+			t.Run(string(rune('0'+failAt)), func(t *testing.T) {
+				plan := newMissingPinnedPullPlanForCoverage(t)
+				calls := 0
+				if failAt == 1 {
+					testseam.Swap(t, &pullPathLstat, func(string) (os.FileInfo, error) { return nil, errTestDownload })
+				} else {
+					testseam.Swap(t, &pullPathStat, func(path string) (os.FileInfo, error) {
+						calls++
+						if calls >= 2 {
+							return nil, errTestDownload
+						}
+						return os.Stat(path)
+					})
+				}
+				if root, err := plan.materialize(); err == nil {
+					root.close()
+					t.Fatal("expected final materialize failure")
+				}
+			})
+		}
+	})
+
+	t.Run("open existing path identity and verification", func(t *testing.T) {
+		for _, fail := range []string{"lstat", "verify"} {
+			t.Run(fail, func(t *testing.T) {
+				dir := t.TempDir()
+				if fail == "lstat" {
+					testseam.Swap(t, &pullPathLstat, func(string) (os.FileInfo, error) { return nil, errTestDownload })
+				} else {
+					pathCalls := 0
+					testseam.Swap(t, &pullPathLstat, func(path string) (os.FileInfo, error) {
+						pathCalls++
+						if pathCalls >= 2 {
+							return nil, errTestDownload
+						}
+						return os.Lstat(path)
+					})
+				}
+				if _, err := openExistingPinnedPullRoot(dir); err == nil {
+					t.Fatal("expected existing-root identity failure")
+				}
+			})
+		}
+	})
+}
+
+func TestCrossPlatformCoverageDrivePullPublishRaces(t *testing.T) {
+	t.Run("smart concurrent target", func(t *testing.T) {
+		root := t.TempDir()
+		installPinnedPullSuccess(t)
+		mustWrite(t, filepath.Join(root, "a.txt"), "older")
+		testseam.Swap(t, &pullDownloadFile, func(_ context.Context, _ string, _ map[string]string, destination *os.File) error {
+			if _, err := destination.WriteString("remote"); err != nil {
+				return err
+			}
+			return os.Chtimes(filepath.Join(root, "a.txt"), time.Now(), time.Now().Add(time.Hour))
+		})
+		action, err := pullOneFileAtRoot(context.Background(), "", &remoteFile{FileID: "F", ModifiedTimeValid: true}, root, "a.txt", ifExistsSmart)
+		if err != nil || action != pullActionSkipped {
+			t.Fatalf("action=%q err=%v", action, err)
+		}
+	})
+
+	t.Run("link loses to regular target", func(t *testing.T) {
+		root := t.TempDir()
+		installPinnedPullSuccess(t)
+		testseam.Swap(t, &pullLink, func(parent *os.Root, _, target string) error {
+			file, err := parent.OpenFile(target, os.O_CREATE|os.O_WRONLY, 0o600)
+			if err == nil {
+				_ = file.Close()
+			}
+			return os.ErrExist
+		})
+		action, err := pullOneFileAtRoot(context.Background(), "", &remoteFile{FileID: "F"}, root, "a.txt", ifExistsSkip)
+		if err != nil || action != pullActionSkipped {
+			t.Fatalf("action=%q err=%v", action, err)
+		}
+	})
+
+	t.Run("link cleanup", func(t *testing.T) {
+		root := t.TempDir()
+		installPinnedPullSuccess(t)
+		testseam.Swap(t, &pullRemove, func(*os.Root, string) error { return errTestDownload })
+		action, err := pullOneFileAtRoot(context.Background(), "", &remoteFile{FileID: "F"}, root, "a.txt", ifExistsSkip)
+		if err == nil || action != pullActionFailed || !strings.Contains(err.Error(), "清理临时文件") {
+			t.Fatalf("action=%q err=%v", action, err)
+		}
+	})
+
+	t.Run("post publish parent", func(t *testing.T) {
+		root := t.TempDir()
+		installPinnedPullSuccess(t)
+		statCalls := 0
+		testseam.Swap(t, &pullPathStat, func(path string) (os.FileInfo, error) {
+			statCalls++
+			if statCalls >= 5 {
+				return nil, errTestDownload
+			}
+			return os.Stat(path)
+		})
+		action, err := pullOneFileAtRoot(context.Background(), "", &remoteFile{FileID: "F"}, root, "a.txt", ifExistsOverwrite)
+		if err == nil || action != pullActionFailed {
+			t.Fatalf("action=%q err=%v", action, err)
+		}
+	})
+
+	t.Run("overwrite rename", func(t *testing.T) {
+		root := t.TempDir()
+		installPinnedPullSuccess(t)
+		testseam.Swap(t, &pullRename, func(*os.Root, string, string) error { return errTestDownload })
+		action, err := pullOneFileAtRoot(context.Background(), "", &remoteFile{FileID: "F"}, root, "a.txt", ifExistsOverwrite)
+		if err == nil || action != pullActionFailed {
+			t.Fatalf("action=%q err=%v", action, err)
+		}
+	})
+}
+
+func TestCrossPlatformCoverageDrivePullPlanCallers(t *testing.T) {
+	t.Run("second preflight verification", func(t *testing.T) {
+		dir := t.TempDir()
+		mustWrite(t, filepath.Join(dir, "a.txt"), "local")
+		root := newPinnedPullRootForCoverage(t, dir)
+		plan := &pinnedPullRootPlan{absDir: root.absDir, existing: root}
+		moved := false
+		testseam.Swap(t, &pullRootLstat, func(parent *os.Root, name string) (os.FileInfo, error) {
+			info, err := parent.Lstat(name)
+			if name == "a.txt" && !moved {
+				moved = true
+				if renameErr := os.Rename(dir, dir+"-pinned"); renameErr != nil {
+					// Windows 在固定目录上持有句柄时会锁住它，移走于该平台物理
+					// 不可达；注入等价的根身份变化，命中同一条二次校验分支。
+					if runtime.GOOS != "windows" {
+						t.Fatal(renameErr)
+					}
+					swapPinnedRootIdentity(t, dir)
+				} else if mkdirErr := os.Mkdir(dir, 0o755); mkdirErr != nil {
+					t.Fatal(mkdirErr)
+				}
+			}
+			return info, err
+		})
+		if _, _, err := buildDrivePullPreflightFromPlan(plan, map[string]*remoteFile{"a.txt": {RelPath: "a.txt"}}); err == nil {
+			t.Fatal("expected second verification failure")
+		}
+	})
+
+	t.Run("command materialize", func(t *testing.T) {
+		root := filepath.Join(t.TempDir(), "missing")
+		caller := pullListingCaller(`{"name":"a.txt","type":"file","fileId":"A"}`)
+		testseam.Swap(t, &deps, &Deps{Caller: caller, Out: &Formatter{w: io.Discard}})
+		testseam.Swap(t, &os.Args, []string{"dws", "drive"})
+		testseam.Swap(t, &pullOpenParentRoot, func(*os.Root, string) (*os.Root, error) { return nil, errTestDownload })
+		cmd := findDriveSubcommand(t, "pull")
+		mustSetFlags(t, cmd, map[string]string{"local-folder": root, "remote-folder": "ROOT"})
+		if err := runDrivePull(cmd, nil); err == nil || !errors.Is(err, errTestDownload) {
+			t.Fatalf("error = %v", err)
+		}
+	})
+
+	t.Run("preflight output", func(t *testing.T) {
+		root := t.TempDir()
+		caller := pullListingCaller(`{"name":"A.txt","type":"file","fileId":"A"},{"name":"a.txt","type":"file","fileId":"B"}`)
+		testseam.Swap(t, &deps, &Deps{Caller: caller, Out: &Formatter{w: failingWriter{}}})
+		testseam.Swap(t, &os.Args, []string{"dws", "drive"})
+		cmd := findDriveSubcommand(t, "pull")
+		mustSetFlags(t, cmd, map[string]string{"local-folder": root, "remote-folder": "ROOT"})
+		if err := runDrivePull(cmd, nil); err == nil {
+			t.Fatal("expected preflight output failure")
+		}
+	})
+
+	t.Run("remote helper", func(t *testing.T) {
+		root := t.TempDir()
+		installPinnedPullSuccess(t)
+		action, err := pullRemoteFile(context.Background(), "", &remoteFile{FileID: "F"}, root, "a.txt", ifExistsOverwrite)
+		if err != nil || action != pullActionDownloaded {
+			t.Fatalf("action=%q err=%v", action, err)
+		}
+	})
+
+	t.Run("target construction final verification", func(t *testing.T) {
+		root := newPinnedPullRootForCoverage(t, t.TempDir())
+		calls := 0
+		testseam.Swap(t, &pullRootLstat, func(parent *os.Root, name string) (os.FileInfo, error) {
+			calls++
+			if calls >= 2 && name == "." {
+				return nil, errTestDownload
+			}
+			return parent.Lstat(name)
+		})
+		if _, err := root.openTarget("a.txt"); err == nil {
+			t.Fatal("expected target verification failure")
+		}
+	})
+}
+
+func TestCrossPlatformCoverageDrivePullDefaultTransportWithoutListener(t *testing.T) {
+	destination, err := os.Create(filepath.Join(t.TempDir(), "payload"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer destination.Close()
+
+	if err := defaultPullDownloadFile(context.Background(), ":", nil, destination); err == nil {
+		t.Fatal("expected invalid request URL")
+	}
+
+	t.Run("transport error", func(t *testing.T) {
+		testseam.Swap(t, &pullHTTPDo, func(*http.Request) (*http.Response, error) { return nil, errTestDownload })
+		if err := defaultPullDownloadFile(context.Background(), "https://example.invalid", nil, destination); !errors.Is(err, errTestDownload) {
+			t.Fatalf("error = %v", err)
+		}
+	})
+
+	t.Run("status", func(t *testing.T) {
+		testseam.Swap(t, &pullHTTPDo, func(request *http.Request) (*http.Response, error) {
+			if request.Header.Get("X-Test") != "yes" {
+				t.Fatalf("header = %q", request.Header.Get("X-Test"))
+			}
+			return &http.Response{StatusCode: http.StatusTeapot, Body: io.NopCloser(strings.NewReader("denied"))}, nil
+		})
+		if err := defaultPullDownloadFile(context.Background(), "https://example.invalid", map[string]string{"X-Test": "yes"}, destination); err == nil {
+			t.Fatal("expected status failure")
+		}
+	})
+
+	t.Run("success and copy", func(t *testing.T) {
+		testseam.Swap(t, &pullHTTPDo, func(*http.Request) (*http.Response, error) {
+			return &http.Response{StatusCode: http.StatusOK, Body: io.NopCloser(strings.NewReader("payload"))}, nil
+		})
+		if err := defaultPullDownloadFile(context.Background(), "https://example.invalid", nil, destination); err != nil {
+			t.Fatal(err)
+		}
+		closed, createErr := os.Create(filepath.Join(t.TempDir(), "closed"))
+		if createErr != nil {
+			t.Fatal(createErr)
+		}
+		_ = closed.Close()
+		if err := defaultPullDownloadFile(context.Background(), "https://example.invalid", nil, closed); err == nil {
+			t.Fatal("expected copy failure")
+		}
+	})
+}
+
+func TestCrossPlatformCoverageDrivePullMTimeHandle(t *testing.T) {
+	file, err := os.Create(filepath.Join(t.TempDir(), "mtime"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer file.Close()
+	if err := setPullFileTimes(file, time.Unix(123, 0)); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestCrossPlatformCoverageDrivePullDryRunLocalPolicies(t *testing.T) {
+	root := t.TempDir()
+	path := filepath.Join(root, "a.txt")
+	mustWrite(t, path, "local")
+	info, err := os.Stat(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	testseam.Swap(t, &deps, &Deps{Out: &Formatter{w: io.Discard}})
+	remote := map[string]*remoteFile{"a.txt": {RelPath: "a.txt", ModifiedTimeValid: true, ModifiedTime: info.ModTime().UnixMilli()}}
+	for _, policy := range []string{ifExistsSkip, ifExistsSmart, ifExistsOverwrite} {
+		if err := printDrivePullDryRunWithLocalInfo(policy, remote, []string{"a.txt"}, nil, map[string]os.FileInfo{"a.txt": info}); err != nil {
+			t.Fatalf("policy %s: %v", policy, err)
+		}
+	}
+	if err := printDrivePullDryRunWithLocalInfo(ifExistsSkip, remote, []string{"missing.txt"}, nil, nil); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestCrossPlatformCoverageDrivePullRejectNonRegular(t *testing.T) {
+	if err := rejectNonRegularLocalTarget(filepath.Join(t.TempDir(), "missing")); err != nil {
+		t.Fatal(err)
+	}
+	dir := t.TempDir()
+	if err := rejectNonRegularLocalTarget(dir); err == nil {
+		t.Fatal("expected directory rejection")
+	}
+	testseam.Swap(t, &pullTargetLstat, func(string) (os.FileInfo, error) { return nil, errTestDownload })
+	if err := rejectNonRegularLocalTarget("target"); err == nil {
+		t.Fatal("expected lstat failure")
+	}
+}

internal/helpers/drive_pull_publish_recheck_test.go

@@ -0,0 +1,91 @@
+package helpers
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam"
+)
+
+// smart 策略在入口按固定的 initialInfo 判定「本地落后、需要下载」，但远端读与落盘
+// 期间同一 inode 的 mtime 仍可能被并发写者推到 ≥ 远端时间。此时发布会用旧的远端版本
+// 覆盖更新的本地内容，因此必须在发布前按当前状态二次判定并跳过。
+func TestCrossPlatformCoverageDrivePullSmartSkipsWhenTargetCatchesUpDuringDownload(t *testing.T) {
+	root := t.TempDir()
+	target := filepath.Join(root, "a.txt")
+	const remoteMillis int64 = 2_000_000
+	if err := os.WriteFile(target, []byte("local"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	// 入口处的 mtime 必须严格早于远端，否则在发出远端读之前就已跳过。
+	stale := time.UnixMilli(remoteMillis - 60_000)
+	if err := os.Chtimes(target, stale, stale); err != nil {
+		t.Fatal(err)
+	}
+	installPinnedPullSuccess(t)
+	testseam.Swap(t, &pullDownloadFile, func(_ context.Context, _ string, _ map[string]string, destination *os.File) error {
+		if _, err := destination.WriteString("remote"); err != nil {
+			return err
+		}
+		// 就地改时间：inode 不变，所以身份比较仍然成立，只有时间判定能拦下发布。
+		fresh := time.UnixMilli(remoteMillis + 60_000)
+		return os.Chtimes(target, fresh, fresh)
+	})
+
+	action, err := pullOneFileAtRoot(context.Background(), "", &remoteFile{
+		FileID:            "F",
+		ModifiedTime:      remoteMillis,
+		ModifiedTimeValid: true,
+	}, root, "a.txt", ifExistsSmart)
+	if err != nil {
+		t.Fatalf("pull = %v", err)
+	}
+	if action != pullActionSkipped {
+		t.Fatalf("action = %q, want %q", action, pullActionSkipped)
+	}
+	if got, err := os.ReadFile(target); err != nil || string(got) != "local" {
+		t.Fatalf("target = %q, err=%v; 追平后的本地内容必须保留", got, err)
+	}
+}
+
+// 发布成功后固定目录仍可能被移走。此时结果已经落盘，门禁只能报失败而不能回删——
+// 同名 terminal entry 可能已被并发替换，二次 Lstat→Remove 会误删他人的文件。
+func TestCrossPlatformCoverageDrivePullFailsWhenPinnedRootMovesAfterPublish(t *testing.T) {
+	root := t.TempDir()
+	installPinnedPullSuccess(t)
+	decoy := t.TempDir()
+	decoyInfo, err := os.Stat(decoy)
+	if err != nil {
+		t.Fatal(err)
+	}
+	published := false
+	testseam.Swap(t, &pullRename, func(parent *os.Root, oldName, newName string) error {
+		if err := parent.Rename(oldName, newName); err != nil {
+			return err
+		}
+		published = true
+		return nil
+	})
+	// 只在发布之后让根目录身份不匹配：下载前与发布前的两次核对都必须先通过。
+	testseam.Swap(t, &pullPathStat, func(path string) (os.FileInfo, error) {
+		if published {
+			return decoyInfo, nil
+		}
+		return os.Stat(path)
+	})
+
+	action, err := pullOneFileAtRoot(context.Background(), "", &remoteFile{FileID: "F"}, root, "a.txt", ifExistsOverwrite)
+	if err == nil || !strings.Contains(err.Error(), "本地根目录在同步期间被替换") {
+		t.Fatalf("error = %v", err)
+	}
+	if action != pullActionFailed {
+		t.Fatalf("action = %q, want %q", action, pullActionFailed)
+	}
+	if got, err := os.ReadFile(filepath.Join(root, "a.txt")); err != nil || string(got) != "remote" {
+		t.Fatalf("published target = %q, err=%v; 已发布的结果不得被回删", got, err)
+	}
+}

internal/helpers/drive_pull_test.go

@@ -0,0 +1,366 @@
+package helpers
+
+import (
+	"context"
+	"errors"
+	"io"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition"
+	"github.com/spf13/cobra"
+)
+
+// drivePullMockCaller 按工具名分发：list_files 返回可配置的树，download_file 返回预签名 URL。
+type drivePullMockCaller struct{ listJSON string }
+
+func (m *drivePullMockCaller) CallTool(_ context.Context, _ string, tool string, _ map[string]any) (*edition.ToolResult, error) {
+	text := `{"result":{"downloadUrl":"https://oss.example.com/dl"}}`
+	if tool == "list_files" {
+		text = m.listJSON
+	}
+	return &edition.ToolResult{Content: []edition.ContentBlock{{Type: "text", Text: text}}}, nil
+}
+func (m *drivePullMockCaller) Format() string { return "raw" }
+func (m *drivePullMockCaller) DryRun() bool   { return false }
+func (m *drivePullMockCaller) Fields() string { return "" }
+func (m *drivePullMockCaller) JQ() string     { return "" }
+
+// ──────────────────────────────────────────────────────────
+// isSafeRemoteSegment — 远端名称逐段安全校验（拒绝逃逸成分）
+// ──────────────────────────────────────────────────────────
+
+func TestCrossPlatformCoverageIsSafeRemoteSegment(t *testing.T) {
+	cases := []struct {
+		name string
+		ok   bool
+	}{
+		{"report.pdf", true},
+		{"报告 2024.xlsx", true},
+		{"a.b.c", true},
+		{"", false},
+		{".", false},
+		{"..", false},
+		{"a/b", false},    // 正斜杠分隔符
+		{`a\b`, false},    // 反斜杠分隔符（Windows）
+		{"../etc", false}, // 相对上跳
+		{"foo/../bar", false},
+		{"/abs", false}, // 绝对路径成分
+	}
+	for _, c := range cases {
+		if got := isSafeRemoteSegment(c.name); got != c.ok {
+			t.Errorf("isSafeRemoteSegment(%q) = %v, want %v", c.name, got, c.ok)
+		}
+	}
+}
+
+// ──────────────────────────────────────────────────────────
+// resolveLocalTarget — 拼接后必须仍位于本地根目录内
+// ──────────────────────────────────────────────────────────
+
+func TestCrossPlatformCoverageResolveLocalTarget_withinRoot(t *testing.T) {
+	root := filepath.Clean(t.TempDir())
+	got, err := resolveLocalTarget(root, "sub/a.txt")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	want := filepath.Join(root, "sub", "a.txt")
+	if got != want {
+		t.Errorf("target = %q, want %q", got, want)
+	}
+}
+
+// 即便 isSafeRemoteSegment 被绕过，逐段拼出的逃逸路径也必须被 resolveLocalTarget 兜住。
+func TestCrossPlatformCoverageResolveLocalTarget_escapeRejected(t *testing.T) {
+	root := filepath.Clean(t.TempDir())
+	for _, rel := range []string{"../evil.txt", "../../etc/passwd", "sub/../../out.txt"} {
+		if _, err := resolveLocalTarget(root, rel); err == nil {
+			t.Errorf("resolveLocalTarget(%q) should reject escaping path", rel)
+		}
+	}
+}
+
+// 根目录内的目录符号链接指向外部时，词法检查会放过（root/sub 仍在 root 下），
+// 必须靠符号链接解析挡住：sub -> /outside 时 sub/a.txt 应被拒绝。
+func TestCrossPlatformCoverageResolveLocalTarget_dirSymlinkEscapeRejected(t *testing.T) {
+	root := filepath.Clean(t.TempDir())
+	outside := filepath.Clean(t.TempDir())
+
+	link := filepath.Join(root, "sub")
+	if err := os.Symlink(outside, link); err != nil {
+		t.Skipf("平台不支持创建符号链接: %v", err)
+	}
+
+	if _, err := resolveLocalTarget(root, "sub/a.txt"); err == nil {
+		t.Fatal("root/sub -> 外部目录时，sub/a.txt 应被拒绝（防符号链接逃逸）")
+	}
+
+	// 对照：根目录内的真实子目录不应被误伤。
+	if err := os.MkdirAll(filepath.Join(root, "real"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := resolveLocalTarget(root, "real/a.txt"); err != nil {
+		t.Errorf("真实子目录不应被拒绝: %v", err)
+	}
+}
+
+// 不存在的本地根目录必须放行（不误判逃逸），由后续 MkdirAll 创建。
+func TestCrossPlatformCoverageResolveLocalTarget_nonexistentRootAllowed(t *testing.T) {
+	parent := filepath.Clean(t.TempDir())
+	absDir := filepath.Join(parent, "not", "created", "yet") // 尚不存在
+	got, err := resolveLocalTarget(absDir, "sub/a.txt")
+	if err != nil {
+		t.Fatalf("不存在的根目录不应被误判为逃逸: %v", err)
+	}
+	if want := filepath.Join(absDir, "sub", "a.txt"); got != want {
+		t.Errorf("target = %q, want %q", got, want)
+	}
+}
+
+// 回归：--local-folder 指向尚不存在的绝对路径时，pull 应自动创建目录并下载，
+// 而不是把每个远端文件都误判为符号链接逃逸而 failed。
+func TestCrossPlatformCoverageDrivePull_nonexistentLocalRoot(t *testing.T) {
+	parent := t.TempDir()
+	absDir := filepath.Join(parent, "new", "repo") // 尚不存在
+
+	caller := &drivePullMockCaller{
+		listJSON: `{"result":{"items":[{"name":"a.txt","type":"file","fileId":"F1","modifyTime":1000}],"nextToken":""}}`,
+	}
+
+	testseam.Swap(t, &deps, &Deps{Caller: caller, Out: &Formatter{w: io.Discard}})
+	swapPullDownloadPath(t, func(_ context.Context, _ string, _ map[string]string, dest string) error {
+		return os.WriteFile(dest, []byte("REMOTE"), 0o644)
+	})
+
+	root := &cobra.Command{Use: "dws"}
+	root.PersistentFlags().BoolP("yes", "y", false, "")
+	root.PersistentFlags().Bool("dry-run", false, "")
+	root.AddCommand(newDriveCommand())
+
+	// pull/push 是 user_required 叶子，非交互环境需 --yes 才能越过统一确认门。
+	full := []string{"pull", "--local-folder", absDir, "--remote-folder", "ROOT", "--yes"}
+	testseam.Swap(t, &os.Args, append([]string{"dws", "drive"}, full...))
+	root.SetArgs(append([]string{"drive"}, full...))
+
+	// 全部下载成功时 runDrivePull 返回 nil；若误判逃逸则会有 failed 并返回 partial_failure。
+	if err := root.Execute(); err != nil {
+		t.Fatalf("pull 到不存在的本地根目录不应失败: %v", err)
+	}
+	got, rerr := os.ReadFile(filepath.Join(absDir, "a.txt"))
+	if rerr != nil {
+		t.Fatalf("目标文件应被创建: %v", rerr)
+	}
+	if string(got) != "REMOTE" {
+		t.Errorf("目标内容 = %q, want REMOTE", got)
+	}
+}
+
+// ──────────────────────────────────────────────────────────
+// detectTargetCollisions — 多个远端条目映射到同一本地目标
+// ──────────────────────────────────────────────────────────
+
+// 大小写不敏感 FS：A.txt 与 a.txt 落到同一目标 → 两者都判冲突；无关文件不受影响。
+func TestCrossPlatformCoverageDetectTargetCollisions_caseInsensitive(t *testing.T) {
+	root := filepath.Clean(t.TempDir())
+	rels := []string{"A.txt", "a.txt", "b.txt", "sub/C.md", "sub/c.md"}
+	collided := detectTargetCollisions(root, rels, true)
+
+	for _, r := range []string{"A.txt", "a.txt", "sub/C.md", "sub/c.md"} {
+		if !collided[r] {
+			t.Errorf("%q 应被判为大小写冲突", r)
+		}
+	}
+	if collided["b.txt"] {
+		t.Error("b.txt 无冲突，不应被标记")
+	}
+}
+
+// 大小写敏感 FS：A.txt 与 a.txt 是两个合法文件 → 不应误判冲突。
+func TestCrossPlatformCoverageDetectTargetCollisions_caseSensitive(t *testing.T) {
+	root := filepath.Clean(t.TempDir())
+	rels := []string{"A.txt", "a.txt", "b.txt"}
+	collided := detectTargetCollisions(root, rels, false)
+	if len(collided) != 0 {
+		t.Errorf("大小写敏感 FS 不应有冲突, got %v", collided)
+	}
+}
+
+// 平台名称规范化冲突：同名的 NFC 与 NFD 记法在不敏感 FS 上落到同一目标 → 冲突。
+func TestCrossPlatformCoverageDetectTargetCollisions_unicodeNormalization(t *testing.T) {
+	root := filepath.Clean(t.TempDir())
+	nfc := "café.txt"  // café（预组合 é）
+	nfd := "café.txt" // café（e + 组合尖音符）
+	if nfc == nfd {
+		t.Fatal("测试数据应为不同字节序列")
+	}
+
+	ci := detectTargetCollisions(root, []string{nfc, nfd}, true)
+	if !ci[nfc] || !ci[nfd] {
+		t.Errorf("NFC/NFD 异写在大小写不敏感 FS 上应判冲突, got %v", ci)
+	}
+	// 大小写/规范化敏感 FS 上视为两个不同文件，不冲突。
+	cs := detectTargetCollisions(root, []string{nfc, nfd}, false)
+	if len(cs) != 0 {
+		t.Errorf("敏感 FS 上 NFC/NFD 不应冲突, got %v", cs)
+	}
+}
+
+// isCaseInsensitiveFS 应能对临时目录给出与实际探针一致的判定（本机自洽）。
+func TestCrossPlatformCoverageIsCaseInsensitiveFS_selfConsistent(t *testing.T) {
+	dir := t.TempDir()
+	got := isCaseInsensitiveFS(dir)
+	// 实测：写一个小写名，再用大写名 stat。
+	lower := filepath.Join(dir, "probe_case_xyz.txt")
+	if err := os.WriteFile(lower, []byte("x"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	_, err := os.Stat(filepath.Join(dir, "PROBE_CASE_XYZ.TXT"))
+	actualInsensitive := err == nil
+	if got != actualInsensitive {
+		t.Errorf("isCaseInsensitiveFS=%v，但实测大写名可 stat=%v", got, actualInsensitive)
+	}
+}
+
+// ──────────────────────────────────────────────────────────
+// pullOneFile — 覆盖下载中断不得破坏原文件（原子替换）
+// ──────────────────────────────────────────────────────────
+
+// 下载中途失败时：命令报告 failed，原有本地文件内容必须原封不动，且不留临时残file。
+func TestCrossPlatformCoveragePullOneFile_downloadFailureKeepsOriginal(t *testing.T) {
+	root := t.TempDir()
+	target := filepath.Join(root, "a.txt")
+	const original = "ORIGINAL-CONTENT-DO-NOT-LOSE"
+	mustWrite(t, target, original)
+
+	// download_file 的 MCP 调用走 mock；httpGetFile 注入为“写入部分内容后报错”。
+	testseam.Swap(t, &deps, &Deps{Caller: &drivePullMockCaller{}, Out: &Formatter{w: io.Discard}})
+	testseam.Swap(t, &os.Args, []string{"dws", "drive"})
+	swapPullDownloadPath(t, func(_ context.Context, _ string, _ map[string]string, dest string) error {
+		// 模拟传输中断：先截断/写半截，再返回错误。
+		_ = os.WriteFile(dest, []byte("HALF"), 0o644)
+		return errors.New("connection reset")
+	})
+
+	rf := &remoteFile{RelPath: "a.txt", FileID: "F1"}
+	action, err := pullOneFile(context.Background(), "", rf, target, ifExistsOverwrite)
+	if action != pullActionFailed || err == nil {
+		t.Fatalf("expected failed action with error, got action=%q err=%v", action, err)
+	}
+
+	// 原文件必须保持原内容。
+	got, rerr := os.ReadFile(target)
+	if rerr != nil {
+		t.Fatalf("原文件应仍存在: %v", rerr)
+	}
+	if string(got) != original {
+		t.Errorf("原文件被破坏: got %q, want %q", got, original)
+	}
+
+	// 不应残留临时文件。
+	entries, _ := os.ReadDir(root)
+	for _, e := range entries {
+		if e.Name() != "a.txt" {
+			t.Errorf("下载失败后残留了临时文件: %s", e.Name())
+		}
+	}
+}
+
+// 下载成功时：临时文件被原子重命名为目标，内容与远端一致。
+func TestCrossPlatformCoveragePullOneFile_downloadSuccessReplacesTarget(t *testing.T) {
+	root := t.TempDir()
+	target := filepath.Join(root, "a.txt")
+	mustWrite(t, target, "OLD")
+
+	testseam.Swap(t, &deps, &Deps{Caller: &drivePullMockCaller{}, Out: &Formatter{w: io.Discard}})
+	testseam.Swap(t, &os.Args, []string{"dws", "drive"})
+	swapPullDownloadPath(t, func(_ context.Context, _ string, _ map[string]string, dest string) error {
+		return os.WriteFile(dest, []byte("NEW-CONTENT"), 0o644)
+	})
+
+	rf := &remoteFile{RelPath: "a.txt", FileID: "F1"}
+	action, err := pullOneFile(context.Background(), "", rf, target, ifExistsOverwrite)
+	if err != nil || action != pullActionDownloaded {
+		t.Fatalf("expected downloaded, got action=%q err=%v", action, err)
+	}
+	got, _ := os.ReadFile(target)
+	if string(got) != "NEW-CONTENT" {
+		t.Errorf("目标未被替换为新内容: got %q", got)
+	}
+	entries, _ := os.ReadDir(root)
+	if len(entries) != 1 {
+		t.Errorf("成功后目录应只有目标文件，got %d 项", len(entries))
+	}
+}
+
+// ──────────────────────────────────────────────────────────
+// parseDriveDownloadInfo — drive download_file 返回解析
+// ──────────────────────────────────────────────────────────
+
+// drive 的正常返回：result.downloadUrl 是预签名 URL，无需额外 header。
+func TestCrossPlatformCoverageParseDriveDownloadInfo_downloadUrl(t *testing.T) {
+	text := `{"result":{"downloadType":"urlPreSignature","downloadUrl":"https://oss.example.com/f.file?Expires=1&Signature=xyz","fileName":"a.txt"},"success":true}`
+	url, headers, err := parseDriveDownloadInfo(text)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if url != "https://oss.example.com/f.file?Expires=1&Signature=xyz" {
+		t.Errorf("url = %q", url)
+	}
+	if len(headers) != 0 {
+		t.Errorf("预签名 URL 不应带 header, got %v", headers)
+	}
+}
+
+// 兼容 flat resourceUrl 字段。
+func TestCrossPlatformCoverageParseDriveDownloadInfo_resourceUrlFallback(t *testing.T) {
+	text := `{"resourceUrl":"https://flat.example.com/dl"}`
+	url, _, err := parseDriveDownloadInfo(text)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if url != "https://flat.example.com/dl" {
+		t.Errorf("url = %q", url)
+	}
+}
+
+// 兼容 resourceUrls[].url 数组格式（在 result 包裹下）。
+func TestCrossPlatformCoverageParseDriveDownloadInfo_resourceUrlsArrayFallback(t *testing.T) {
+	text := `{"result":{"resourceUrls":[{"url":"https://arr.example.com/dl","headers":{}}]}}`
+	url, _, err := parseDriveDownloadInfo(text)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if url != "https://arr.example.com/dl" {
+		t.Errorf("url = %q", url)
+	}
+}
+
+func TestCrossPlatformCoverageParseDriveDownloadInfo_missingURL(t *testing.T) {
+	text := `{"result":{"fileName":"a.txt"}}`
+	if _, _, err := parseDriveDownloadInfo(text); err == nil {
+		t.Fatal("expected error when downloadUrl is empty")
+	}
+}
+
+func TestCrossPlatformCoverageParseDriveDownloadInfo_invalidJSON(t *testing.T) {
+	if _, _, err := parseDriveDownloadInfo("not json"); err == nil {
+		t.Fatal("expected error for invalid JSON")
+	}
+}
+
+// ──────────────────────────────────────────────────────────
+// drivePartialFailure — pull 部分失败错误：exit=1，stderr 仅保留简短说明
+// ──────────────────────────────────────────────────────────
+
+func TestCrossPlatformCoverageDrivePartialFailure(t *testing.T) {
+	e := &drivePartialFailure{failed: 2}
+	if e.ExitCode() != 1 {
+		t.Errorf("ExitCode() = %d, want 1", e.ExitCode())
+	}
+	want := "drive pull: 2 file(s) failed"
+	if e.Error() != want || e.RawStderr() != want {
+		t.Errorf("Error()/RawStderr() = %q / %q, want %q", e.Error(), e.RawStderr(), want)
+	}
+}