test(drive): cover walkLocalTree's WalkDir error path via a seam

The new root-type guard shifted `filepath.WalkDir`'s outer error branch into
the diff, and neither the macOS nor the Windows runner reaches it naturally —
raising Windows coverage to 99.9365% and blocking the gate. Add a
`statusWalkDir` seam and a `TestCrossPlatformCoverage` regression that swaps
in a WalkDir returning a sentinel error, asserting it is surfaced unchanged.

Verified locally: changed code coverage back to 100.0000%.

.changes/942-drive-list-filter.md

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

.changes/942-drive-list-pattern-fix.md

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

.changes/973-chat-message-time-defaults.md

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

.changes/doc-drive-param-aliases.md

@@ -0,0 +1,5 @@
+---
+category: Fixed
+---
+
+- **Doc and Drive parameter aliases** — normalizes reviewed identifier, pagination, path, version, and role synonyms while blocking ambiguous values before dispatch.

.changes/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/open-dingtalk-id-format-routing.md

@@ -0,0 +1,5 @@
+---
+category: Changed
+---
+
+- **Chat identity routing** — validates explicit `openDingTalkId` inputs and improves name, `userId`, and `openDingTalkId` routing for message shortcuts.

.changes/released/1.0.58-beta.5/85384225-agent-version-ext.md

@@ -0,0 +1,8 @@
+---
+category: Added
+---
+
+- **Agent version and extended context passthrough** (Aone 85384225) — adds
+  validated `DWS_AGENT_VER` and sensitive JSON `DWS_AGENT_EXT` metadata to
+  ordinary non-plugin MCP requests without forwarding it to A2A, OAuth,
+  Discovery, or third-party plugins.

.changes/released/1.0.58-beta.5/970-chat-auto-pagination.md

@@ -0,0 +1,5 @@
+---
+category: Added
+---
+
+- **Chat automatic pagination controls** (#970) — adds bounded `--max-items` and cancellable `--page-delay` support to the core IM list shortcuts, with safe continuation metadata and truncation reporting.

.env.example

@@ -19,3 +19,12 @@
 
 # Cache directory (optional, defaults to ~/.dws/cache)
 # DWS_CACHE_DIR=
+
+# Agent integration metadata (optional; ordinary non-plugin MCP requests only)
+# DWS_AGENT_PRODUCT=example-agent
+# DWS_AGENT_HOST=cloud
+# DWS_AGENT_VER=0.1.5
+# DWS_AGENT_EXT='{"umt":"example-redacted","miniwua":"example-redacted","ua":"ExampleAgent/0.1.5"}'
+# The outer single quotes above are shell syntax and are not part of the value.
+# DWS_AGENT_EXT is sensitive caller-declared JSON (max 8 KiB); never put real
+# tokens in committed files or use this metadata alone for authentication.

.github/workflows/ci.yml

@@ -24,6 +24,7 @@ jobs:
       pull-requests: read
     outputs:
       changelog_only: ${{ steps.classify.outputs.changelog_only }}
+      release_seal_only: ${{ steps.classify.outputs.release_seal_only }}
       changelog_changed: ${{ steps.classify.outputs.changelog_changed }}
       docs_only: ${{ steps.classify.outputs.docs_only }}
       full_suite: ${{ steps.classify.outputs.full_suite }}
@@ -39,6 +40,7 @@ jobs:
         with:
           script: |
             let changelogOnly = false;
+            let releaseSealOnly = false;
             let changelogChanged = false;
             let docsOnly = false;
             let fullSuite = context.eventName === 'push';
@@ -151,6 +153,12 @@ jobs:
                 filename.startsWith('internal/helpers/') ||
                 filename.startsWith('internal/generator/') ||
                 filename.startsWith('internal/cli/schema') ||
+                // Parameter aliases are reduced against the live command tree.
+                // Their reverse-dependency set is too large for one focused
+                // race job, so use the existing full-suite shards.
+                filename === 'internal/cli/param_concepts.json' ||
+                filename === 'internal/cli/param_concepts.schema.json' ||
+                filename === 'internal/cli/param_aliases_generated.go' ||
                 filename.startsWith('internal/interfacesnapshot/') ||
                 filename.startsWith('internal/app/upgrade') ||
                 filename.startsWith('internal/transport/') ||
@@ -162,6 +170,43 @@ jobs:
                 filename === 'go.mod' ||
                 filename === 'go.sum'
               );
+            const isExactReleaseSeal = (candidates) => {
+              const changelog = candidates.filter(
+                ({ filename, status, previous_filename }) =>
+                  filename === 'CHANGELOG.md' &&
+                  status === 'modified' &&
+                  !previous_filename
+              );
+              if (changelog.length !== 1 || candidates.length < 2) {
+                return false;
+              }
+              let version = '';
+              return candidates.every((file) => {
+                if (file.filename === 'CHANGELOG.md') {
+                  return file.status === 'modified' && !file.previous_filename;
+                }
+                if (
+                  file.status !== 'renamed' ||
+                  typeof file.filename !== 'string' ||
+                  typeof file.previous_filename !== 'string' ||
+                  file.additions !== 0 ||
+                  file.deletions !== 0
+                ) {
+                  return false;
+                }
+                const target = file.filename.match(
+                  /^\.changes\/released\/([0-9]+\.[0-9]+\.[0-9]+(?:-beta\.[1-9][0-9]*)?)\/([a-z0-9][a-z0-9._-]*\.md)$/
+                );
+                if (!target || file.previous_filename !== `.changes/${target[2]}`) {
+                  return false;
+                }
+                if (version && version !== target[1]) {
+                  return false;
+                }
+                version = target[1];
+                return true;
+              });
+            };
             const classifyFiles = (complete) => {
               const paths = files.flatMap(({ filename, previous_filename }) =>
                 [filename, previous_filename].filter(
@@ -248,19 +293,26 @@ jobs:
                 );
               }
 
-              changelogOnly =
+              const exactChangelogDiff =
                 files.length === 1 &&
                 files[0].filename === 'CHANGELOG.md' &&
                 files[0].status === 'modified' &&
                 !files[0].previous_filename;
+              releaseSealOnly = isExactReleaseSeal(files);
+              changelogOnly = exactChangelogDiff || releaseSealOnly;
               changelogChanged = files.some(
                 ({ filename, previous_filename }) =>
                   filename === 'CHANGELOG.md' ||
                   previous_filename === 'CHANGELOG.md'
               );
               classifyFiles(true);
+              if (releaseSealOnly) {
+                fullSuite = false;
+              }
               fastPathTrust = changelogOnly
-                ? 'exact pull-request revision and synthetic merge policy'
+                ? releaseSealOnly
+                  ? 'exact release-seal fragment archival and synthetic merge policy'
+                  : 'exact CHANGELOG-only revision and synthetic merge policy'
                 : docsOnly
                   ? 'documentation-only focused admission'
                   : fullSuite
@@ -295,7 +347,8 @@ jobs:
                     per_page: 100,
                   });
                 files = Array.isArray(comparison.files) ? comparison.files : [];
-                classifyFiles(files.length < 300);
+                const pushFilesComplete = files.length < 300;
+                classifyFiles(pushFilesComplete);
                 const linearFromValidatedTip =
                   comparison.status === 'ahead' &&
                   comparison.merge_base_commit?.sha === expectedBefore &&
@@ -307,8 +360,10 @@ jobs:
                   files[0].filename === 'CHANGELOG.md' &&
                   files[0].status === 'modified' &&
                   !files[0].previous_filename;
+                const exactReleaseSealDiff =
+                  pushFilesComplete && isExactReleaseSeal(files);
 
-                if (linearFromValidatedTip && exactChangelogDiff) {
+                if (linearFromValidatedTip && (exactChangelogDiff || exactReleaseSealDiff)) {
                   const requiredContexts = [
                     'Lint',
                     'Test',
@@ -359,9 +414,15 @@ jobs:
 
                   if (missing.length === 0 && nonSuccess.length === 0) {
                     changelogOnly = true;
+                    releaseSealOnly = exactReleaseSealDiff;
                     changelogChanged = true;
+                    if (releaseSealOnly) {
+                      fullSuite = false;
+                    }
                     fastPathTrust =
-                      `exact CHANGELOG-only successor of validated ${expectedBefore}`;
+                      releaseSealOnly
+                        ? `exact release-seal successor of validated ${expectedBefore}`
+                        : `exact CHANGELOG-only successor of validated ${expectedBefore}`;
                   } else {
                     fastPathTrust =
                       'predecessor Code Admission is not fully successful; ' +
@@ -376,6 +437,7 @@ jobs:
             }
 
             core.setOutput('changelog_only', String(changelogOnly));
+            core.setOutput('release_seal_only', String(releaseSealOnly));
             core.setOutput('changelog_changed', String(changelogChanged));
             core.setOutput('docs_only', String(docsOnly));
             core.setOutput('full_suite', String(fullSuite));
@@ -387,7 +449,8 @@ jobs:
             await core.summary
               .addHeading('Code Admission scope')
               .addRaw(`- Event: \`${context.eventName}\`\n`)
-              .addRaw(`- Exact modified CHANGELOG only: \`${changelogOnly}\`\n`)
+              .addRaw(`- Metadata-only fast path: \`${changelogOnly}\`\n`)
+              .addRaw(`- Release-seal fragments only: \`${releaseSealOnly}\`\n`)
               .addRaw(`- CHANGELOG touched: \`${changelogChanged}\`\n`)
               .addRaw(`- Documentation-only: \`${docsOnly}\`\n`)
               .addRaw(`- Full suite: \`${fullSuite}\`\n`)
@@ -402,7 +465,14 @@ jobs:
 
       - name: Record CHANGELOG-only fast path
         if: steps.classify.outputs.changelog_only == 'true'
-        run: echo "Lint is satisfied by the trusted CHANGELOG-only Policy path." >> "$GITHUB_STEP_SUMMARY"
+        env:
+          RELEASE_SEAL_ONLY: ${{ steps.classify.outputs.release_seal_only }}
+        run: |
+          if [ "$RELEASE_SEAL_ONLY" = true ]; then
+            echo "Lint is satisfied by the trusted release-seal fragment Policy path." >> "$GITHUB_STEP_SUMMARY"
+          else
+            echo "Lint is satisfied by the trusted CHANGELOG-only Policy path." >> "$GITHUB_STEP_SUMMARY"
+          fi
 
       - name: Record documentation-only fast path
         if: steps.classify.outputs.changelog_only != 'true' && steps.classify.outputs.docs_only == 'true'
@@ -495,7 +565,8 @@ jobs:
     needs: lint
     if: ${{ needs.lint.outputs.changelog_only != 'true' && needs.lint.outputs.docs_only != 'true' && needs.lint.outputs.full_suite == 'true' }}
     runs-on: ubuntu-latest
-    # cli/smoke shards need headroom beyond go test -timeout for setup + assembly.
+    # app runs several independently bounded processes; cli/smoke need headroom
+    # beyond go test -timeout for setup + assembly.
     timeout-minutes: 20
     strategy:
       fail-fast: false
@@ -531,10 +602,19 @@ jobs:
           test -n "$package_output"
           mapfile -t packages <<< "$package_output"
           test "${#packages[@]}" -gt 0
-          # cli/smoke own heavy NewRootCommand / Schema assembly under -race; give
-          # them a dedicated budget so remaining is not SIGTERM'd by OOM/timeout.
+          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
+          # 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
+          if [ "$TEST_SHARD" = "cli" ] ||
+             [ "$TEST_SHARD" = "smoke" ]; then
             timeout_budget=15m
           fi
           go test -v -race -count=1 -timeout="$timeout_budget" "${packages[@]}"
@@ -1256,6 +1336,7 @@ jobs:
         env:
           CLASSIFIED_CHANGELOG_CHANGED: ${{ needs.lint.outputs.changelog_changed }}
           CHANGELOG_ONLY: ${{ needs.lint.outputs.changelog_only }}
+          RELEASE_SEAL_ONLY: ${{ needs.lint.outputs.release_seal_only }}
           PR_BASE_SHA: ${{ github.event.pull_request.base.sha }}
         run: |
           set -eu
@@ -1282,7 +1363,7 @@ jobs:
           fi
 
           mode=--content-only
-          if [ "$CHANGELOG_ONLY" = true ]; then
+          if [ "$CHANGELOG_ONLY" = true ] && [ "$RELEASE_SEAL_ONLY" != true ]; then
             mode=--fast-path
           fi
           ./scripts/policy/check-changelog-pr.sh \
@@ -1294,25 +1375,41 @@ jobs:
           PR_BASE_SHA: ${{ github.event.pull_request.base.sha }}
         run: ./scripts/policy/check-release-fragments.sh "$PR_BASE_SHA" HEAD
 
-      - name: Validate trusted main CHANGELOG-only push
+      - name: Validate trusted main metadata-only push
         if: github.event_name == 'push' && needs.lint.outputs.changelog_only == 'true'
         env:
           PUSH_BEFORE_SHA: ${{ github.event.before }}
           PUSH_AFTER_SHA: ${{ github.event.after }}
+          RELEASE_SEAL_ONLY: ${{ needs.lint.outputs.release_seal_only }}
         run: |
           set -eu
           test "$(git rev-parse HEAD)" = "$PUSH_AFTER_SHA" || {
             echo "checked-out push revision does not match event after SHA" >&2
             exit 1
           }
+          mode=--fast-path
+          if [ "$RELEASE_SEAL_ONLY" = true ]; then
+            mode=--content-only
+          fi
           ./scripts/policy/check-changelog-pr.sh \
-            --fast-path "$PUSH_BEFORE_SHA" "$PUSH_AFTER_SHA"
+            "$mode" "$PUSH_BEFORE_SHA" "$PUSH_AFTER_SHA"
+          if [ "$RELEASE_SEAL_ONLY" = true ]; then
+            ./scripts/policy/check-release-fragments.sh \
+              "$PUSH_BEFORE_SHA" "$PUSH_AFTER_SHA"
+          fi
 
       - name: Record CHANGELOG-only fast path
         if: needs.lint.outputs.changelog_only == 'true'
+        env:
+          RELEASE_SEAL_ONLY: ${{ needs.lint.outputs.release_seal_only }}
         run: |
-          echo "Only the trusted base-equivalent CHANGELOG validator ran; executable sources are unchanged." \
-            >> "$GITHUB_STEP_SUMMARY"
+          if [ "$RELEASE_SEAL_ONLY" = true ]; then
+            echo "Only the trusted release-seal and fragment validators ran; executable sources are unchanged." \
+              >> "$GITHUB_STEP_SUMMARY"
+          else
+            echo "Only the trusted base-equivalent CHANGELOG validator ran; executable sources are unchanged." \
+              >> "$GITHUB_STEP_SUMMARY"
+          fi
 
       - name: Validate scoped policy
         if: ${{ needs.lint.outputs.changelog_only != 'true' && (needs.lint.outputs.docs_only == 'true' || (needs.lint.outputs.full_suite != 'true' && needs.lint.outputs.interface_sensitive != 'true')) }}

.github/workflows/release.yml

@@ -2645,6 +2645,40 @@ jobs:
           "$GITHUB_WORKSPACE/tmp/trusted-release-tooling/scripts/release/verify-github-tag-authority.sh" \
             "$RELEASE_VERSION" "$RELEASE_COMMIT" "$RELEASE_TAG_OBJECT"
 
+      # The sealed candidate tag is intentionally visible while its GitHub
+      # authority is checked above. Compatibility must instead discover the
+      # previous delivered stable tag, so hide only this verified candidate
+      # from this isolated runner's local tag namespace.
+      - name: Prepare delivered-stable compatibility ref view
+        if: ${{ matrix.check == 'compatibility' }}
+        env:
+          RELEASE_VERSION: ${{ needs.release-contract.outputs.release_version }}
+          RELEASE_COMMIT: ${{ needs.release-contract.outputs.release_commit }}
+          RELEASE_TAG_OBJECT: ${{ needs.release-contract.outputs.release_tag_object }}
+          PREVIOUS_STABLE: ${{ needs.release-contract.outputs.previous_stable }}
+          PREVIOUS_STABLE_COMMIT: ${{ needs.release-contract.outputs.previous_stable_commit }}
+        run: |
+          set -eu
+          test -n "$RELEASE_VERSION"
+          test -n "$RELEASE_COMMIT"
+          test -n "$RELEASE_TAG_OBJECT"
+          test -n "$PREVIOUS_STABLE"
+          test -n "$PREVIOUS_STABLE_COMMIT"
+          test "$RELEASE_VERSION" != "$PREVIOUS_STABLE"
+          test "$(git rev-parse HEAD)" = "$RELEASE_COMMIT"
+          test "$(git rev-parse --verify "refs/tags/${RELEASE_VERSION}")" = "$RELEASE_TAG_OBJECT"
+          test "$(git rev-parse --verify "refs/tags/${RELEASE_VERSION}^{commit}")" = "$RELEASE_COMMIT"
+          test "$(git rev-parse --verify "${PREVIOUS_STABLE}^{commit}")" = "$PREVIOUS_STABLE_COMMIT"
+
+          git update-ref -d "refs/tags/${RELEASE_VERSION}" "$RELEASE_TAG_OBJECT"
+
+          if git show-ref --verify --quiet "refs/tags/${RELEASE_VERSION}"; then
+            echo "sealed candidate tag is still visible to compatibility baseline discovery" >&2
+            exit 2
+          fi
+          test "$(git rev-parse HEAD)" = "$RELEASE_COMMIT"
+          test "$(git rev-parse --verify "${PREVIOUS_STABLE}^{commit}")" = "$PREVIOUS_STABLE_COMMIT"
+
       - name: Set up Go
         uses: actions/setup-go@v5
         with:

CHANGELOG.md

@@ -6,6 +6,64 @@ The format is inspired by [Keep a Changelog](https://keepachangelog.com/) and th
 
 ## [Unreleased]
 
+## [1.0.58] - 2026-08-13
+
+This release promotes the sealed `v1.0.58-beta.6` contents to stable.
+
+### Changed
+
+- **Expanded collaborative workflows** — adds full AI Table, Sheet, Minutes,
+  approval-event, Drive-comment, document export, and CSV workflow support,
+  including safer validation, explicit confirmation for writes, and
+  machine-readable completion receipts.
+- **More capable Chat operations** — adds robot image/file messages, toolbar
+  management, streaming-card mentions, automatic pagination controls, and
+  clearer post-send ID, Markdown-image, paging, and result-shape guidance.
+- **Reliable Agent and CLI contracts** — expands Agent-visible Chat and
+  Minutes commands, aligns bundled skills, improves schema/result envelopes,
+  and hardens parameter, pagination, runtime-token, and write-result
+  verification so ambiguous or incomplete operations fail closed.
+- **Multi-skill install and upgrade** — makes the multi-skill layout the
+  default for fresh installs and upgrades while preserving an explicit legacy
+  mono option.
+- **Safer release delivery** — strengthens release-equivalent compatibility,
+  sealing, package verification, and evaluation-dispatch checks for more
+  reliable cross-platform releases.
+
+## [1.0.58-beta.6] - 2026-08-13
+
+### Fixed
+
+- **npm package verification for multi-skill installs** (#991) — aligns the
+  release verifier with the installer’s concrete Agent skill-root selection,
+  preventing valid multi-skill package layouts from failing release delivery.
+
+### Changed
+
+- **Release-seal CI classification** (#987) — recognizes the reviewed
+  CHANGELOG-and-fragment archival shape while retaining release-contract and
+  lifecycle validation, reducing unrelated CI work for release-seal PRs.
+
+## [1.0.58-beta.5] - 2026-08-13
+
+### Added
+
+- **Agent version and extended context passthrough** (Aone 85384225) — adds
+  validated `DWS_AGENT_VER` and sensitive JSON `DWS_AGENT_EXT` metadata to
+  ordinary non-plugin MCP requests without forwarding it to A2A, OAuth,
+  Discovery, or third-party plugins.
+
+- **Drive file comments** (#961) — adds `dws drive comment list` and `dws drive comment create` for comments on ordinary preview files.
+
+- **Chat automatic pagination controls** (#970) — adds bounded `--max-items` and cancellable `--page-delay` support to the core IM list shortcuts, with safe continuation metadata and truncation reporting.
+
+### Changed
+
+- **Chat message send help** - Clarifies Markdown image syntax for inline mixed text and images.
+
+- **Doc/drive/wiki routing descriptions** — clarifies the document-space container-vs-content boundary across the doc, drive, and wiki skill descriptions for more predictable first-round Agent selection, without changing CLI behavior.
+
+
 ## [1.0.58-beta.4] - 2026-08-12
 
 ### Added

Formula/dingtalk-workspace-cli-beta.rb

@@ -1,33 +1,33 @@
 class DingtalkWorkspaceCliBeta < Formula
   desc "Automate DingTalk workspace tasks from the terminal (beta channel)"
   homepage "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli"
-  version "1.0.58-beta.4"
+  version "1.0.58-beta.6"
   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.4/dws-darwin-arm64.tar.gz"
-      sha256 "5c2ac92e35b1f1dba80234af8b0c9505b2883f4a37c1e73892b8a1c3087b7702"
+      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.58-beta.6/dws-darwin-arm64.tar.gz"
+      sha256 "8f55497b84113f81b318e087c723016a02eded1cb5784cbd0811fe527d5852ca"
     else
-      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.58-beta.4/dws-darwin-amd64.tar.gz"
-      sha256 "93ef787770105fe1f0d27585adcac7b740aa6c37ff490275c4113814541ae095"
+      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.58-beta.6/dws-darwin-amd64.tar.gz"
+      sha256 "b1762f1640310fb4100634fe54d9baace46384bb270c59148fe306275554d491"
     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.4/dws-linux-arm64.tar.gz"
-      sha256 "011ce16a73d8fd24275e34c3122d3d0832c60cde2480f496018eb654059b5c05"
+      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.58-beta.6/dws-linux-arm64.tar.gz"
+      sha256 "55393310ef0e1f24ea2c0dc22f00c0eb3b343edc2deb18d0db7838cda65af25d"
     else
-      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.58-beta.4/dws-linux-amd64.tar.gz"
-      sha256 "847b17ff8a8d80dce38f0013eb35c77c102be16c9f98b955a632b983cd5ec104"
+      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.58-beta.6/dws-linux-amd64.tar.gz"
+      sha256 "3830f77d09b4da4aa39f0c08d772ff3fa1ffb837eb15bb417f97edbccb073b7d"
     end
   end
 
   resource "skills" do
-    url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.58-beta.4/dws-skills.zip"
-    sha256 "f5e0c72cc92cb7e8886409319cf68bbbfc7740e969bd39a389b74af4befdbc66"
+    url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.58-beta.6/dws-skills.zip"
+    sha256 "f304a883a4f9e938b26a44692cd5a8d3d8704ba70ee7f33ba7c288434da72b6f"
   end
 
   def install

Formula/dingtalk-workspace-cli.rb

@@ -1,33 +1,33 @@
 class DingtalkWorkspaceCli < Formula
   desc "Automate DingTalk workspace tasks from the terminal"
   homepage "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli"
-  version "1.0.57"
+  version "1.0.58"
   license "Apache-2.0"
 
 
   on_macos do
     if Hardware::CPU.arm?
-      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.57/dws-darwin-arm64.tar.gz"
-      sha256 "c01c28dc13948a70fca905207073dc8dbd22f7ba7fc90e68b3316eb9a9c98e88"
+      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.58/dws-darwin-arm64.tar.gz"
+      sha256 "7d98599f90cae9d42b51ff2863efc87dbfb4a3176ff3c84fc2216110c0157a70"
     else
-      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.57/dws-darwin-amd64.tar.gz"
-      sha256 "d7baa218beefc851c6a933b456055195f8272984ce008d7e0122bdfc5dad94ea"
+      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.58/dws-darwin-amd64.tar.gz"
+      sha256 "4c12e35e5bf7e0905812cd42dc94a5345068a2c16e306bb50b13c5c78b5cb95d"
     end
   end
 
   on_linux do
     if Hardware::CPU.arm?
-      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.57/dws-linux-arm64.tar.gz"
-      sha256 "0bbe9c233a3ff585077bae1ac5000937c32d967846d14cc44c46f98d49b95ae2"
+      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.58/dws-linux-arm64.tar.gz"
+      sha256 "5ef6bde24bc3db6a11a0f1d0b3343a048956b2cbcf6cd3409a037fb6ba425489"
     else
-      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.57/dws-linux-amd64.tar.gz"
-      sha256 "f113ce3654f21d1f9ecc7c196f815aeafbca54d377a347b244a15116c5cba698"
+      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.58/dws-linux-amd64.tar.gz"
+      sha256 "3ccadcc6f070a39d2b2ba20429a4fcdc2f21639bf79f34361dc7d16f501bfda6"
     end
   end
 
   resource "skills" do
-    url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.57/dws-skills.zip"
-    sha256 "0c9667209cf30761427a8f9348149cbbf1e397aa3c25587e99f205bc7525e101"
+    url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.58/dws-skills.zip"
+    sha256 "2626debc21c3daadfd155b4c167b2219b97e801398fe4441a8b48138960ab264"
   end
 
   def install

docs/cli-interface-flag-migrations.md

@@ -1,6 +1,6 @@
 # CLI flag 兼容迁移治理
 
-本文定义一种受控迁移：保留旧 flag 的可执行兼容性，但把它从 Help 与 Agent Schema 中隐藏，并将新的规范 flag 提升为必填。它只解决这一种精确变更，不是通用 breaking-change 豁免。
+本文定义一种受控迁移：保留旧 flag 的可执行兼容性，但把它从 Help 与 Agent Schema 中隐藏，并将新的规范 flag 设为唯一可见入口。迁移必须保持原 flag 的 requiredness：optional 只能迁到 optional，required 只能迁到 required。它只解决这一种精确变更，不是通用 breaking-change 豁免。
 
 同名 flag 的精确类型迁移属于另一类评审机制，只能进入
 `internal/interfacesnapshot/reviewed.go` 与 legacy smoke helper 的镜像表；flag rename
@@ -50,7 +50,7 @@ scripts/policy/interface-migrations/approved-flag-migrations-v1.json
 | 阶段 | PR 可以做什么 | 必须满足的快照状态 |
 |---|---|---|
 | 1. 治理审批 | 新增 `state: pending` 的精确记录；不得在同一个 PR 修改产品 surface | candidate 和 merge-base 都与记录中的 `before` 完全一致；该记录不改变 stable 的判断 |
-| 2. 产品迁移 | merge-base 已拥有 `pending` 后，按记录一次性切到精确 `after`，并把记录改为 `state: consumed` | legacy 仍存在但由 visible 变 hidden，且声明 `alias_of`；canonical 达到记录的必填状态 |
+| 2. 产品迁移 | merge-base 已拥有 `pending` 后，按记录一次性切到精确 `after`，并把记录改为 `state: consumed` | legacy 仍存在但由 visible 变 hidden，且声明 `alias_of`；canonical 的 requiredness 与 legacy 迁移前完全一致 |
 | 3. 保留回执 | 产品 PR 合入后，如果 stable 仍是 `before`，继续保留 `consumed` | merge-base 或 stable 仍有任一份尚未达到 `after` |
 | 4. 单独清理 | 当 merge-base 和 stable 都已经是 `after`，在后续 PR 删除该记录 | 两份参考快照均精确匹配 `after`；继续保留过期回执会被门禁拒绝 |
 
@@ -122,7 +122,7 @@ scripts/policy/interface-migrations/approved-flag-migrations-v1.json
 一条 base-owned、状态正确且前后快照精确匹配的记录，只会从普通兼容报告中移除以下两类预期 finding：
 
 1. legacy flag 的 `flag_became_hidden`（visible → hidden）；
-2. canonical flag 的 `required_flag_added`（新增时即必填）或 `flag_became_required`（已有 flag 从可选变必填）。
+2. required legacy 被新增的 required canonical 替代时产生的 `required_flag_added`；如果 canonical 在 before 阶段只是 hidden 占位符，则允许它在转为公开拼写时继承 legacy 的 requiredness。已有的 visible canonical 不允许借 rename 改变 requiredness。
 
 以下变化仍按普通兼容规则阻塞，不能被迁移记录掩盖：
 
@@ -145,7 +145,7 @@ legacy 名改为 canonical 名。Schema adapter 只接受已经由三方 Interfa
   `required` / `cli_required` 或重写 constraint；
 - rename 前后的 `type`、`property`、`interface_type`、default、format、enum 与
   `required_when` 必须完全一致；
-- `required` / `cli_required` 只能保持不变或按审批从 `false` 提升为 `true`，禁止降低；
+- `required` / `cli_required` 必须在 rename 前后完全一致，升高或降低都失败；
 - constraint 只允许在同一 tool 内按已枚举的 legacy → canonical map 做 member 替换、
   排序与去重；group kind、非迁移 member 或 group 增删仍然阻塞；
 - 多个 legacy 指向同一 canonical 时，所有历史 parameter signature 必须一致，否则

docs/reference.md

@@ -7,6 +7,8 @@
 | `DWS_CONFIG_DIR` | Override default config directory / 覆盖默认配置目录 |
 | `DWS_AGENT_PRODUCT` | Optional, caller-declared Agent product sent as `x-dws-agent-product` (for example `qwenwork`) for downstream logs/BI and used as the IM `clawType` display label when `--ai-tag` is enabled. `--ai-tag` defaults to `true`, so a configured Product changes the displayed label by default. With `--ai-tag=false`, native `chat message send` / `reply` calls send an empty `clawType`, while shortcut calls omit the argument. Surrounding ASCII spaces/tabs are trimmed; the remaining value must be at most 64 bytes and match `^[A-Za-z0-9][A-Za-z0-9_-]*$`. Unset or empty values omit the Header and use the edition's IM display default. This client never uses Product to change the separate HTTP `claw-type` PAT/routing label. / 可选、由调用方声明的 Agent 产品标识，经校验后作为 `x-dws-agent-product` 发送，并用于 IM 小尾巴；`--ai-tag` 默认为 `true`，因此配置 Product 后默认会改变展示标签。使用 `--ai-tag=false` 时，原生 `chat message send` / `reply` 发送空的 `clawType`，shortcut 调用则省略该参数。未设置时省略请求头且 IM 使用发行版默认值；本客户端不会用 Product 修改独立的 HTTP `claw-type` |
 | `DWS_AGENT_HOST` | Optional, caller-declared Agent runtime form sent as `x-dws-agent-host` (for example `cloud` or `desktop`) for downstream logs/BI. Surrounding ASCII spaces/tabs are trimmed; the remaining value must be at most 64 bytes and match `^[a-z0-9][a-z0-9_-]*$`; unset values are omitted. This client does not use Host for PAT, authentication, Discovery, or MCP endpoint selection. / 可选、由调用方声明的 Agent 运行形态，经校验后作为 `x-dws-agent-host` 发送给下游日志/BI；本客户端不使用该值进行 PAT、鉴权、Discovery 或 MCP 端点选择，未设置时省略 |
+| `DWS_AGENT_VER` | Optional caller-declared Agent version / 可选、由调用方声明的 Agent 版本。After trimming surrounding ASCII spaces/tabs, the value must be at most 64 bytes and match `^[A-Za-z0-9][A-Za-z0-9._+-]*$`; a non-empty valid value is sent as `x-dws-agent-ver`, while unset or empty values omit the Header. / 去除首尾 ASCII 空格和 Tab 后，值不得超过 64 字节且必须匹配上述格式；合法非空值通过 `x-dws-agent-ver` 发送，未设置或空值则省略请求头 |
+| `DWS_AGENT_EXT` | Optional caller-declared Agent extended context / 可选、由调用方声明的 Agent 扩展上下文。The value must be a UTF-8 JSON object no larger than 8 KiB, is compacted before being sent as the sensitive `x-dws-agent-ext` Header, and may use the recommended keys `umt`, `miniwua`, and `ua`; unknown keys remain supported. Unset or empty values omit the Header. / 值必须是 UTF-8 JSON 对象且不得超过 8 KiB，压缩后通过敏感请求头 `x-dws-agent-ext` 发送；推荐使用 `umt`、`miniwua`、`ua`，同时允许未知扩展键。未设置或空值则省略请求头 |
 | `DWS_<PRODUCT>_MCP_URL` | Override a product MCP endpoint for local development / 本地开发时覆盖指定产品 MCP endpoint |
 | `DWS_CLIENT_ID` | OAuth client ID (DingTalk AppKey) |
 | `DWS_CLIENT_SECRET` | OAuth client secret (DingTalk AppSecret) |
@@ -14,6 +16,47 @@
 | `DWS_ALLOW_HTTP_ENDPOINTS` | Set `1` to allow HTTP for loopback during dev / 设为 `1` 允许回环地址 HTTP，仅用于开发调试 |
 | `DWS_DISABLE_KEYCHAIN` | macOS only. Set `1` to skip system Keychain for the encryption key and use file-based storage (same scheme as Linux). For sandboxed runtimes (e.g. Codex App) that block Keychain APIs. Weakens at-rest protection — DEK and ciphertext live in the same directory. / 仅 macOS。设为 `1` 时跳过系统 Keychain，密钥以文件形式存储（与 Linux 一致）。用于 Keychain API 被拦截的沙盒环境（如 Codex App）。代价是 DEK 与密文同目录，保护强度低于默认方案 |
 
+### Agent Version and Extended Context / Agent 版本与扩展上下文
+
+`DWS_AGENT_VER` and `DWS_AGENT_EXT` are sent only on the CLI's ordinary,
+non-plugin MCP requests. They do not change the standard HTTP `User-Agent` or
+the separate `X-Cli-Version` that identifies the DWS CLI version, and they are
+not forwarded to A2A, OAuth, Discovery, or third-party plugin requests.
+
+`DWS_AGENT_EXT` is one JSON-object Header rather than a set of Headers. The
+recommended keys are `umt`, `miniwua`, and `ua`, but the open-source CLI keeps
+the object extensible and does not enforce a key allowlist. For example, using
+fictional, redacted values:
+
+```bash
+DWS_AGENT_VER=0.1.5
+DWS_AGENT_EXT='{"umt":"example-redacted","miniwua":"example-redacted","ua":"ExampleAgent/0.1.5"}'
+```
+
+The shell's outer single quotes group the JSON and are not part of the
+environment-variable value. The CLI trims surrounding ASCII spaces/tabs,
+omits either Header when its value is empty, and compacts EXT to a single-line
+JSON object. A representative current payload is about 657 bytes, well below
+the 8 KiB limit; integrations must still enforce the limit because values can
+grow. EXT may contain sensitive device or runtime signals: the CLI masks it in
+configuration and logs, and removes it on a cross-host redirect.
+
+Both values are declared by the caller and are therefore forgeable. They can
+support compatibility checks, diagnostics, and observability, but they are not
+credentials or attestations and must never be sufficient on their own to
+authenticate a caller or authorize access.
+
+`DWS_AGENT_VER` 与 `DWS_AGENT_EXT` 仅随 CLI 发起的普通非插件 MCP 请求发送，不会
+改变标准 HTTP `User-Agent`，也不会覆盖标识 DWS CLI 自身版本的 `X-Cli-Version`；
+二者不会进入 A2A、OAuth、Discovery 或第三方插件请求。EXT 使用单个 JSON 对象
+请求头，不拆成多个子请求头；推荐键为 `umt`、`miniwua`、`ua`，但开源 CLI 不限制
+扩展键。Shell 示例中的外层单引号只用于保护 JSON，不属于环境变量值。当前典型负载
+约为 657 字节，远低于 8 KiB 上限，但集成方仍须遵守大小限制。EXT 可能包含敏感的
+设备或运行时信号，配置展示和日志会对其脱敏，跨主机重定向时也会移除该请求头。
+
+这两个值都由调用方自行声明，可以被伪造；它们可用于兼容性判断、诊断和可观测性，
+但不是凭据或可信证明，不能单独用于身份认证或访问授权。
+
 ### Agent Product, Host, and `claw-type` / Agent 产品、运行形态与 `claw-type`
 
 `DWS_AGENT_PRODUCT` and `DWS_AGENT_HOST` are caller-declared observation

internal/app/agent_host_test.go

@@ -165,7 +165,7 @@ func TestResolveIdentityHeadersOmitsAbsentOrInvalidAgentHost(t *testing.T) {
 	}
 }
 
-func TestRootRejectsInvalidAgentHostBeforeEditionHook(t *testing.T) {
+func TestCrossPlatformCoverageRootRejectsInvalidAgentHostBeforeEditionHook(t *testing.T) {
 	t.Setenv("DWS_CONFIG_DIR", t.TempDir())
 	const invalidValue = "DO_NOT_ECHO"
 	t.Setenv(envDWSAgentHost, invalidValue)

internal/app/agent_metadata.go

@@ -0,0 +1,248 @@
+// 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 (
+	"bytes"
+	"context"
+	"encoding/json"
+	"os"
+	"regexp"
+	"strings"
+	"unicode"
+	"unicode/utf8"
+
+	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/executor"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/transport"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/configmeta"
+)
+
+const (
+	envDWSAgentVersion     = "DWS_AGENT_VER"
+	envDWSAgentExt         = "DWS_AGENT_EXT"
+	maxAgentVersionBytes   = 64
+	maxAgentExtensionBytes = 8 * 1024
+)
+
+var agentVersionPattern = regexp.MustCompile(`^[A-Za-z0-9][A-Za-z0-9._+-]*$`)
+
+type agentMetadataSnapshot struct {
+	version    string
+	ext        string
+	versionErr error
+	extErr     error
+}
+
+type agentMetadataSnapshotContextKey struct{}
+
+func (snapshot agentMetadataSnapshot) validationError() error {
+	if snapshot.versionErr != nil {
+		return snapshot.versionErr
+	}
+	return snapshot.extErr
+}
+
+func contextWithAgentMetadataSnapshot(ctx context.Context, snapshot agentMetadataSnapshot) context.Context {
+	return context.WithValue(ctx, agentMetadataSnapshotContextKey{}, snapshot)
+}
+
+func agentMetadataSnapshotFromContext(ctx context.Context) (agentMetadataSnapshot, bool) {
+	if ctx == nil {
+		return agentMetadataSnapshot{}, false
+	}
+	snapshot, ok := ctx.Value(agentMetadataSnapshotContextKey{}).(agentMetadataSnapshot)
+	return snapshot, ok
+}
+
+func init() {
+	configmeta.Register(configmeta.ConfigItem{
+		Name:        envDWSAgentVersion,
+		Category:    configmeta.CategoryExternal,
+		Description: "调用 DWS 的 Agent 版本；仅作为 x-dws-agent-ver 透传到非插件 MCP 请求",
+		Example:     "1.2.3-beta.1+build.7",
+	})
+	configmeta.Register(configmeta.ConfigItem{
+		Name:        envDWSAgentExt,
+		Category:    configmeta.CategoryExternal,
+		Description: "调用 DWS 的 Agent 扩展上下文 JSON；仅作为 x-dws-agent-ext 透传到非插件 MCP 请求",
+		Example:     `{"umt":"<token>","miniwua":"<token>","ua":"agent/1.0"}`,
+		Sensitive:   true,
+	})
+}
+
+// parseAgentVersion normalizes and validates the caller-declared Agent
+// version. Only surrounding ASCII spaces and tabs are trimmed. An unset or
+// ASCII-whitespace-only value means "do not emit".
+func parseAgentVersion(raw string) (string, error) {
+	value := strings.Trim(raw, " \t")
+	if value == "" {
+		return "", nil
+	}
+	if len(value) > maxAgentVersionBytes || !agentVersionPattern.MatchString(value) {
+		return "", invalidAgentVersionError()
+	}
+	return value, nil
+}
+
+// parseAgentExt validates one generic JSON object and returns its compact
+// one-line representation. Raw control characters other than horizontal tab
+// are rejected before JSON parsing; escaped JSON control characters remain
+// valid because they are safe on the HTTP header wire.
+func parseAgentExt(raw string) (string, error) {
+	if len(raw) > maxAgentExtensionBytes || !utf8.ValidString(raw) {
+		return "", invalidAgentExtError()
+	}
+	for _, r := range raw {
+		if unicode.IsControl(r) && r != '\t' {
+			return "", invalidAgentExtError()
+		}
+	}
+
+	value := strings.Trim(raw, " \t")
+	if value == "" {
+		return "", nil
+	}
+
+	var compact bytes.Buffer
+	if err := json.Compact(&compact, []byte(value)); err != nil {
+		return "", invalidAgentExtError()
+	}
+	compactBytes := compact.Bytes()
+	if len(compactBytes) > maxAgentExtensionBytes || len(compactBytes) < 2 || compactBytes[0] != '{' {
+		return "", invalidAgentExtError()
+	}
+	return compact.String(), nil
+}
+
+func invalidAgentVersionError() error {
+	return apperrors.NewValidation(
+		"DWS_AGENT_VER must be at most 64 bytes and match ^[A-Za-z0-9][A-Za-z0-9._+-]*$",
+		apperrors.WithReason("invalid_agent_version"),
+	)
+}
+
+func invalidAgentExtError() error {
+	return apperrors.NewValidation(
+		"DWS_AGENT_EXT must be a UTF-8 JSON object of at most 8192 bytes without raw control characters",
+		apperrors.WithReason("invalid_agent_ext"),
+	)
+}
+
+// readAgentMetadataSnapshot reads both environment variables from one
+// os.Environ snapshot, then parses them once. Normal CLI execution retains the
+// validated result through the invocation so hooks and transport observe the
+// same pair even in an embedding process that mutates its environment.
+func readAgentMetadataSnapshot() agentMetadataSnapshot {
+	var rawVersion, rawExt string
+	for _, entry := range os.Environ() {
+		key, value, _ := strings.Cut(entry, "=")
+		switch key {
+		case envDWSAgentVersion:
+			rawVersion = value
+		case envDWSAgentExt:
+			rawExt = value
+		}
+	}
+	version, versionErr := parseAgentVersion(rawVersion)
+	ext, extErr := parseAgentExt(rawExt)
+	return agentMetadataSnapshot{
+		version:    version,
+		ext:        ext,
+		versionErr: versionErr,
+		extErr:     extErr,
+	}
+}
+
+// removeAgentMetadataHeaders removes every case variant so edition or
+// credential hooks cannot smuggle MCP-only metadata into shared transports.
+func removeAgentMetadataHeaders(headers map[string]string) {
+	for key := range headers {
+		if strings.EqualFold(key, transport.HeaderAgentVersion) ||
+			strings.EqualFold(key, transport.HeaderAgentExt) {
+			delete(headers, key)
+		}
+	}
+}
+
+// applyAgentMetadataHeaders applies validated environment values as the final
+// authority for non-plugin MCP requests. Invalid values are omitted on
+// library paths that bypass root validation; normal CLI execution rejects
+// them before hooks or network access.
+func applyAgentMetadataHeaders(headers map[string]string) map[string]string {
+	return applyAgentMetadataSnapshot(headers, readAgentMetadataSnapshot())
+}
+
+func applyAgentMetadataSnapshot(headers map[string]string, snapshot agentMetadataSnapshot) map[string]string {
+	removeAgentMetadataHeaders(headers)
+
+	if (snapshot.versionErr != nil || snapshot.version == "") && (snapshot.extErr != nil || snapshot.ext == "") {
+		return headers
+	}
+	if headers == nil {
+		headers = make(map[string]string)
+	}
+	if snapshot.versionErr == nil && snapshot.version != "" {
+		headers[transport.HeaderAgentVersion] = snapshot.version
+	}
+	if snapshot.extErr == nil && snapshot.ext != "" {
+		headers[transport.HeaderAgentExt] = snapshot.ext
+	}
+	return headers
+}
+
+// resolveMCPRequestHeaders adds Agent version and extension metadata only to
+// the built-in DingTalk MCP request path. Shared identity consumers (notably
+// A2A) continue to use resolveIdentityHeaders and never receive these fields.
+func resolveMCPRequestHeaders() map[string]string {
+	return resolveMCPRequestHeadersWithSnapshot(readAgentMetadataSnapshot())
+}
+
+func resolveMCPRequestHeadersWithSnapshot(snapshot agentMetadataSnapshot) map[string]string {
+	return applyAgentMetadataSnapshot(resolveIdentityHeaders(), snapshot)
+}
+
+// resolveMCPRequestHeadersForInvocation resolves one immutable Header snapshot
+// for an invocation. The helper-only mcp-meta server performs endpoint
+// discovery rather than an ordinary MCP product call, so caller-declared
+// Agent metadata must not cross that boundary.
+func resolveMCPRequestHeadersForInvocation(invocation executor.Invocation, snapshots ...agentMetadataSnapshot) map[string]string {
+	headers := resolveIdentityHeaders()
+	if strings.EqualFold(strings.TrimSpace(invocation.CanonicalProduct), mcpMetaServerID) {
+		return headers
+	}
+	snapshot := readAgentMetadataSnapshot()
+	if len(snapshots) > 0 {
+		snapshot = snapshots[0]
+	}
+	return applyAgentMetadataSnapshot(headers, snapshot)
+}
+
+// pluginRequestHeaders returns a private, sanitized copy of plugin-owned
+// Headers. Third-party plugins never receive DWS-owned Agent metadata, even if
+// their manifest tries to declare the reserved Header names itself.
+func pluginRequestHeaders(pluginAuth *PluginAuth) map[string]string {
+	if pluginAuth == nil || len(pluginAuth.ExtraHeaders) == 0 {
+		return nil
+	}
+	headers := make(map[string]string, len(pluginAuth.ExtraHeaders))
+	for key, value := range pluginAuth.ExtraHeaders {
+		headers[key] = value
+	}
+	removeAgentMetadataHeaders(headers)
+	if len(headers) == 0 {
+		return nil
+	}
+	return headers
+}

internal/app/agent_metadata_test.go

@@ -0,0 +1,743 @@
+// 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 (
+	"context"
+	"encoding/json"
+	"errors"
+	"io"
+	"maps"
+	"os"
+	"strings"
+	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/audit"
+	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/executor"
+	outputpkg "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/output"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/pipeline"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/transport"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/agentproduct"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/configmeta"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/mcptypes"
+	"github.com/spf13/cobra"
+)
+
+func TestCrossPlatformCoverageParseAgentVersion(t *testing.T) {
+	var nilContext context.Context
+	if _, ok := agentMetadataSnapshotFromContext(nilContext); ok {
+		t.Fatal("nil context unexpectedly contained Agent metadata")
+	}
+	wantSnapshot := agentMetadataSnapshot{version: "context-version", ext: "{}"}
+	if got, ok := agentMetadataSnapshotFromContext(contextWithAgentMetadataSnapshot(context.Background(), wantSnapshot)); !ok || got != wantSnapshot {
+		t.Fatalf("context Agent metadata = %#v, %v; want %#v", got, ok, wantSnapshot)
+	}
+
+	valid := []struct {
+		name string
+		raw  string
+		want string
+	}{
+		{name: "unset", raw: "", want: ""},
+		{name: "ASCII whitespace only", raw: " \t ", want: ""},
+		{name: "semantic version", raw: "1.2.3", want: "1.2.3"},
+		{name: "pre-release and build", raw: " v1.2.3-rc.1+build_7 ", want: "v1.2.3-rc.1+build_7"},
+		{name: "maximum length", raw: strings.Repeat("a", maxAgentVersionBytes), want: strings.Repeat("a", maxAgentVersionBytes)},
+	}
+	for _, tc := range valid {
+		t.Run(tc.name, func(t *testing.T) {
+			got, err := parseAgentVersion(tc.raw)
+			if err != nil {
+				t.Fatalf("parseAgentVersion() error = %v", err)
+			}
+			if got != tc.want {
+				t.Fatalf("parseAgentVersion() = %q, want %q", got, tc.want)
+			}
+		})
+	}
+
+	invalid := []struct {
+		name string
+		raw  string
+	}{
+		{name: "leading punctuation", raw: "-1.2.3"},
+		{name: "internal space", raw: "1.2 3"},
+		{name: "slash", raw: "1.2/3"},
+		{name: "line feed", raw: "1.2.3\n"},
+		{name: "carriage return", raw: "1.2.3\r"},
+		{name: "NUL", raw: "1.2\x003"},
+		{name: "Unicode", raw: "版本1"},
+		{name: "too long", raw: strings.Repeat("a", maxAgentVersionBytes+1)},
+	}
+	for _, tc := range invalid {
+		t.Run(tc.name, func(t *testing.T) {
+			got, err := parseAgentVersion(tc.raw)
+			if err == nil || got != "" {
+				t.Fatalf("parseAgentVersion(%q) = %q, %v; want validation error", tc.raw, got, err)
+			}
+			assertAgentMetadataValidationError(t, err, "invalid_agent_version", tc.raw)
+		})
+	}
+}
+
+func TestCrossPlatformCoverageParseAgentExt(t *testing.T) {
+	boundary := `{"x":"` + strings.Repeat("a", maxAgentExtensionBytes-8) + `"}`
+	if len(boundary) != maxAgentExtensionBytes {
+		t.Fatalf("invalid boundary fixture size: %d", len(boundary))
+	}
+
+	valid := []struct {
+		name string
+		raw  string
+		want string
+	}{
+		{name: "unset", raw: "", want: ""},
+		{name: "ASCII whitespace only", raw: " \t ", want: ""},
+		{name: "empty object", raw: "{}", want: "{}"},
+		{name: "compact generic object", raw: " \t{ \"umt\": \"masked\",\t \"nested\": { \"ok\": true }, \"unknown\": [1, 2] }\t ", want: `{"umt":"masked","nested":{"ok":true},"unknown":[1,2]}`},
+		{name: "Unicode value", raw: `{"ua":"千问办公/1.0"}`, want: `{"ua":"千问办公/1.0"}`},
+		{name: "escaped control remains safe", raw: `{"ua":"line\nnext"}`, want: `{"ua":"line\nnext"}`},
+		{name: "maximum length", raw: boundary, want: boundary},
+	}
+	for _, tc := range valid {
+		t.Run(tc.name, func(t *testing.T) {
+			got, err := parseAgentExt(tc.raw)
+			if err != nil {
+				t.Fatalf("parseAgentExt() error = %v", err)
+			}
+			if got != tc.want {
+				t.Fatalf("parseAgentExt() = %q, want %q", got, tc.want)
+			}
+		})
+	}
+
+	invalidUTF8 := string([]byte{'{', '"', 'x', '"', ':', '"', 0xff, '"', '}'})
+	invalid := []struct {
+		name string
+		raw  string
+	}{
+		{name: "too long raw input", raw: strings.Repeat(" ", maxAgentExtensionBytes+1)},
+		{name: "invalid UTF-8", raw: invalidUTF8},
+		{name: "array", raw: `[]`},
+		{name: "string", raw: `"value"`},
+		{name: "number", raw: `1`},
+		{name: "boolean", raw: `true`},
+		{name: "null", raw: `null`},
+		{name: "malformed object", raw: `{"secret":"DO_NOT_ECHO"`},
+		{name: "trailing value", raw: `{} {}`},
+		{name: "line feed", raw: "{\n}"},
+		{name: "carriage return", raw: "{\r}"},
+		{name: "NUL", raw: "{\x00}"},
+		{name: "vertical tab", raw: "{\v}"},
+		{name: "form feed", raw: "{\f}"},
+		{name: "DEL", raw: "{\x7f}"},
+		{name: "C1 control", raw: "{\u0085}"},
+	}
+	for _, tc := range invalid {
+		t.Run(tc.name, func(t *testing.T) {
+			got, err := parseAgentExt(tc.raw)
+			if err == nil || got != "" {
+				t.Fatalf("parseAgentExt() = %q, %v; want validation error", got, err)
+			}
+			assertAgentMetadataValidationError(t, err, "invalid_agent_ext", tc.raw)
+		})
+	}
+}
+
+func assertAgentMetadataValidationError(t *testing.T, err error, reason, raw string) {
+	t.Helper()
+	var appErr *apperrors.Error
+	if !errors.As(err, &appErr) {
+		t.Fatalf("error type = %T, want *errors.Error", err)
+	}
+	if appErr.Category != apperrors.CategoryValidation || appErr.Reason != reason {
+		t.Fatalf("error = category %q reason %q, want validation/%s", appErr.Category, appErr.Reason, reason)
+	}
+	if strings.Contains(raw, "DO_NOT_ECHO") && strings.Contains(err.Error(), "DO_NOT_ECHO") {
+		t.Fatalf("error must not echo invalid value: %v", err)
+	}
+}
+
+func TestCrossPlatformCoverageAgentMetadataConfigRegistrationAndMasking(t *testing.T) {
+	items := configmeta.All()
+	var versionItem, extItem *configmeta.ConfigItem
+	for i := range items {
+		switch items[i].Name {
+		case envDWSAgentVersion:
+			versionItem = &items[i]
+		case envDWSAgentExt:
+			extItem = &items[i]
+		}
+	}
+	if versionItem == nil || extItem == nil {
+		t.Fatalf("Agent metadata config registration missing: version=%v ext=%v", versionItem != nil, extItem != nil)
+	}
+	if versionItem.Category != configmeta.CategoryExternal || versionItem.Sensitive {
+		t.Fatalf("version config metadata = %#v", *versionItem)
+	}
+	if extItem.Category != configmeta.CategoryExternal || !extItem.Sensitive {
+		t.Fatalf("extension config metadata = %#v", *extItem)
+	}
+
+	const canary = `{"umt":"SENSITIVE_CANARY"}`
+	t.Setenv(envDWSAgentExt, canary)
+	got, ok := configmeta.Resolve(envDWSAgentExt)
+	if !ok || got == "" || strings.Contains(got, "SENSITIVE_CANARY") || got == canary {
+		t.Fatalf("sensitive extension was not masked: value=%q ok=%v", got, ok)
+	}
+
+	t.Setenv(envDWSAgentVersion, "9.8.7")
+	command := newConfigListCommand()
+	var output strings.Builder
+	command.SetOut(&output)
+	command.SetArgs([]string{"--category", string(configmeta.CategoryExternal), "--show-values", "--json"})
+	if err := command.Execute(); err != nil {
+		t.Fatalf("config list failed: %v", err)
+	}
+	rawOutput := output.String()
+	if !json.Valid([]byte(rawOutput)) {
+		t.Fatalf("config list emitted invalid JSON: %q", rawOutput)
+	}
+	if !strings.Contains(rawOutput, envDWSAgentVersion) || !strings.Contains(rawOutput, envDWSAgentExt) {
+		t.Fatalf("config list omitted Agent metadata variables: %s", rawOutput)
+	}
+	if strings.Contains(rawOutput, "SENSITIVE_CANARY") || strings.Contains(rawOutput, canary) {
+		t.Fatalf("config list leaked Agent extension: %s", rawOutput)
+	}
+}
+
+func TestCrossPlatformCoverageResolveMCPRequestHeadersScopesAndFinalizesAgentMetadata(t *testing.T) {
+	t.Setenv("DWS_CONFIG_DIR", t.TempDir())
+	t.Setenv(envDWSAgentHost, "")
+	t.Setenv(agentproduct.EnvName, "")
+	t.Setenv(envDWSAgentVersion, " 1.2.3-rc.1 ")
+	t.Setenv(envDWSAgentExt, " { \"umt\": \"masked\", \"unknown\": true } ")
+
+	oldEdition := edition.Get()
+	t.Cleanup(func() { edition.Override(oldEdition) })
+	edition.Override(&edition.Hooks{
+		MergeHeaders: func(headers map[string]string) map[string]string {
+			headers["X-Dws-Agent-Ver"] = "merge-must-not-win"
+			headers["X-Dws-Agent-Ext"] = `{"source":"merge"}`
+			return headers
+		},
+		EnterpriseCredentialHeaders: func(headers map[string]string) map[string]string {
+			headers[transport.HeaderAgentVersion] = "credential-must-not-win"
+			headers[transport.HeaderAgentExt] = `{"source":"credential"}`
+			return headers
+		},
+	})
+
+	for name, headers := range map[string]map[string]string{
+		"shared identity": resolveIdentityHeaders(),
+		"A2A export":      MCPIdentityHeaders(),
+	} {
+		if hasHeaderFold(headers, transport.HeaderAgentVersion) || hasHeaderFold(headers, transport.HeaderAgentExt) {
+			t.Fatalf("%s leaked MCP-only metadata: %#v", name, headers)
+		}
+	}
+
+	headers := resolveMCPRequestHeaders()
+	if got := headers[transport.HeaderAgentVersion]; got != "1.2.3-rc.1" {
+		t.Fatalf("%s = %q, want 1.2.3-rc.1", transport.HeaderAgentVersion, got)
+	}
+	if got := headers[transport.HeaderAgentExt]; got != `{"umt":"masked","unknown":true}` {
+		t.Fatalf("%s = %q", transport.HeaderAgentExt, got)
+	}
+	if got := headers[transport.HeaderVersion]; got != version {
+		t.Fatalf("%s = %q, want CLI version %q", transport.HeaderVersion, got, version)
+	}
+	if _, ok := headers["User-Agent"]; ok {
+		t.Fatal("Agent extension must not create or replace the standard User-Agent header")
+	}
+	for _, key := range []string{"umt", "miniwua", "ua", "x-dws-agent-umt", "x-dws-agent-miniwua", "x-dws-agent-ua"} {
+		if hasHeaderFold(headers, key) {
+			t.Fatalf("Agent extension was split into an extra header %q: %#v", key, headers)
+		}
+	}
+
+	// Library paths are best-effort: one invalid value is omitted without
+	// suppressing the other valid field or preserving hook-injected values.
+	t.Setenv(envDWSAgentExt, `{"secret":"DO_NOT_ECHO"`)
+	headers = resolveMCPRequestHeaders()
+	if got := headers[transport.HeaderAgentVersion]; got != "1.2.3-rc.1" {
+		t.Fatalf("valid version was suppressed: %q", got)
+	}
+	if hasHeaderFold(headers, transport.HeaderAgentExt) {
+		t.Fatalf("invalid extension or hook value leaked: %#v", headers)
+	}
+
+	// Exercise the nil-map and empty-input library paths. An absent environment
+	// must not allocate a map, while an EXT-only value must allocate one and
+	// remain a single compact Header.
+	t.Setenv(envDWSAgentVersion, "")
+	t.Setenv(envDWSAgentExt, "")
+	if got := applyAgentMetadataHeaders(nil); got != nil {
+		t.Fatalf("empty metadata allocated headers: %#v", got)
+	}
+	t.Setenv(envDWSAgentExt, " { } ")
+	headers = applyAgentMetadataHeaders(nil)
+	if got := headers[transport.HeaderAgentExt]; got != "{}" {
+		t.Fatalf("EXT-only metadata = %q, want {}", got)
+	}
+}
+
+func TestCrossPlatformCoverageRootRejectsInvalidAgentMetadataBeforeEditionHook(t *testing.T) {
+	oldEdition := edition.Get()
+	t.Cleanup(func() { edition.Override(oldEdition) })
+
+	tests := []struct {
+		name   string
+		env    string
+		value  string
+		reason string
+	}{
+		{name: "version", env: envDWSAgentVersion, value: "DO_NOT ECHO", reason: "invalid_agent_version"},
+		{name: "extension", env: envDWSAgentExt, value: `{"secret":"DO_NOT_ECHO"`, reason: "invalid_agent_ext"},
+	}
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Setenv("DWS_CONFIG_DIR", t.TempDir())
+			t.Setenv(envDWSAgentHost, "")
+			t.Setenv(agentproduct.EnvName, "")
+			t.Setenv(envDWSAgentVersion, "")
+			t.Setenv(envDWSAgentExt, "")
+			t.Setenv(tc.env, tc.value)
+
+			headerHookCalled := false
+			afterHookCalled := false
+			edition.Override(&edition.Hooks{
+				MergeHeaders: func(headers map[string]string) map[string]string {
+					headerHookCalled = true
+					return headers
+				},
+				EnterpriseCredentialHeaders: func(headers map[string]string) map[string]string {
+					headerHookCalled = true
+					return headers
+				},
+				AfterPersistentPreRun: func(_ *cobra.Command, _ []string) error {
+					afterHookCalled = true
+					return nil
+				},
+			})
+
+			root := NewRootCommand()
+			root.SetOut(io.Discard)
+			root.SetErr(io.Discard)
+			root.SetArgs([]string{"version"})
+			err := root.Execute()
+			if err == nil {
+				t.Fatalf("root command accepted invalid %s", tc.env)
+			}
+			if headerHookCalled || afterHookCalled {
+				t.Fatalf("edition hook ran before %s validation", tc.env)
+			}
+			assertAgentMetadataValidationError(t, err, tc.reason, tc.value)
+		})
+	}
+}
+
+func TestCrossPlatformCoverageAgentMetadataProcessEntryValidationPrecedesRootConstruction(t *testing.T) {
+	for _, tc := range []struct {
+		name string
+		args []string
+		want bool
+	}{
+		{name: "default JSON", args: []string{"version"}, want: true},
+		{name: "long JSON", args: []string{"version", "--format", "JSON"}, want: true},
+		{name: "long table", args: []string{"--format=table", "version"}, want: false},
+		{name: "short attached JSON", args: []string{"version", "-fjson"}, want: true},
+		{name: "short table", args: []string{"version", "-f", "table"}, want: false},
+		{name: "last wins", args: []string{"--format", "table", "version", "-f=json"}, want: true},
+		{name: "terminator", args: []string{"version", "--format", "table", "--", "--format", "json"}, want: false},
+		{name: "missing value", args: []string{"version", "--format"}, want: false},
+	} {
+		t.Run("presentation/"+tc.name, func(t *testing.T) {
+			if got := processArgsRequestJSON(tc.args); got != tc.want {
+				t.Fatalf("processArgsRequestJSON(%q) = %v, want %v", tc.args, got, tc.want)
+			}
+		})
+	}
+
+	t.Setenv("DWS_CONFIG_DIR", t.TempDir())
+	t.Setenv(envDWSAgentHost, "")
+	t.Setenv(agentproduct.EnvName, "")
+	t.Setenv(envDWSAgentVersion, "")
+	sensitiveRaw := "{\"umt\":\"must-not-leak\"}\n"
+	t.Setenv(envDWSAgentExt, sensitiveRaw)
+	oldEdition := edition.Get()
+	t.Cleanup(func() { edition.Override(oldEdition) })
+	extensionHookCalls := 0
+	edition.Override(&edition.Hooks{
+		Name: "presentation-test",
+		RegisterExtraCommands: func(*cobra.Command, edition.ToolCaller) {
+			extensionHookCalls++
+		},
+		VisibleProducts: func() []string {
+			extensionHookCalls++
+			return nil
+		},
+		StaticServers: func() []edition.ServerInfo {
+			extensionHookCalls++
+			return nil
+		},
+	})
+
+	oldArgs := os.Args
+	os.Args = []string{"dws", "version"}
+	t.Cleanup(func() { os.Args = oldArgs })
+
+	rootConstructed := false
+	preParseCalled := false
+	testseam.Swap(t, &rootNewRootCommandWithEngine, func(context.Context, *pipeline.Engine) *cobra.Command {
+		rootConstructed = true
+		return &cobra.Command{Use: "dws"}
+	})
+	testseam.Swap(t, &rootRunPreParse, func(*cobra.Command, *pipeline.Engine) error {
+		preParseCalled = true
+		return nil
+	})
+
+	stderrFile, err := os.CreateTemp(t.TempDir(), "agent-metadata-stderr-*")
+	if err != nil {
+		t.Fatalf("create stderr capture: %v", err)
+	}
+	oldStderr := os.Stderr
+	os.Stderr = stderrFile
+	t.Cleanup(func() {
+		os.Stderr = oldStderr
+		_ = stderrFile.Close()
+	})
+
+	if code := Execute(); code == 0 {
+		t.Fatal("process entry accepted invalid Agent metadata")
+	}
+	if rootConstructed || preParseCalled {
+		t.Fatalf("invalid Agent metadata reached root hooks: constructed=%v preParse=%v", rootConstructed, preParseCalled)
+	}
+	if extensionHookCalls != 0 {
+		t.Fatalf("invalid Agent metadata executed %d extension hooks", extensionHookCalls)
+	}
+	if err := stderrFile.Sync(); err != nil {
+		t.Fatalf("sync stderr capture: %v", err)
+	}
+	stderrOutput, err := os.ReadFile(stderrFile.Name())
+	if err != nil {
+		t.Fatalf("read stderr capture: %v", err)
+	}
+	if strings.Contains(string(stderrOutput), "must-not-leak") || strings.Contains(string(stderrOutput), sensitiveRaw) {
+		t.Fatalf("process validation error leaked raw EXT: %q", stderrOutput)
+	}
+	if !json.Valid(stderrOutput) || !strings.Contains(string(stderrOutput), `"reason": "invalid_agent_ext"`) {
+		t.Fatalf("default JSON error presentation = %q", stderrOutput)
+	}
+
+	stdoutFile, err := os.CreateTemp(t.TempDir(), "agent-metadata-stdout-*")
+	if err != nil {
+		t.Fatalf("create stdout capture: %v", err)
+	}
+	oldStdout := os.Stdout
+	os.Stdout = stdoutFile
+	t.Cleanup(func() {
+		os.Stdout = oldStdout
+		_ = stdoutFile.Close()
+	})
+	emitEarlyAgentMetadataValidationError(invalidAgentExtError(), []string{"drive", "+list", "--format", "json"})
+	if err := stdoutFile.Sync(); err != nil {
+		t.Fatalf("sync stdout capture: %v", err)
+	}
+	unifiedOutput, err := os.ReadFile(stdoutFile.Name())
+	if err != nil {
+		t.Fatalf("read stdout capture: %v", err)
+	}
+	if !json.Valid(unifiedOutput) || !strings.Contains(string(unifiedOutput), `"outcome": "failure"`) ||
+		!strings.Contains(string(unifiedOutput), `"subtype": "invalid_agent_ext"`) {
+		t.Fatalf("unified JSON error presentation = %q", unifiedOutput)
+	}
+	if extensionHookCalls != 0 {
+		t.Fatalf("presentation-only root executed %d extension hooks", extensionHookCalls)
+	}
+
+	if err := stderrFile.Truncate(0); err != nil {
+		t.Fatalf("truncate fallback stderr capture: %v", err)
+	}
+	if _, err := stderrFile.Seek(0, io.SeekStart); err != nil {
+		t.Fatalf("rewind fallback stderr capture: %v", err)
+	}
+	testseam.Swap(t, &rootEmitResult, func(*cobra.Command, outputpkg.CommandResult) (int, error) {
+		return 0, errors.New("injected result emission failure")
+	})
+	emitEarlyAgentMetadataValidationError(invalidAgentExtError(), []string{"drive", "+list", "--format", "json"})
+	if err := stderrFile.Sync(); err != nil {
+		t.Fatalf("sync fallback stderr capture: %v", err)
+	}
+	fallbackOutput, err := os.ReadFile(stderrFile.Name())
+	if err != nil {
+		t.Fatalf("read fallback stderr capture: %v", err)
+	}
+	if !json.Valid(fallbackOutput) || !strings.Contains(string(fallbackOutput), `"reason": "invalid_agent_ext"`) ||
+		strings.Contains(string(fallbackOutput), "must-not-leak") {
+		t.Fatalf("fallback validation error presentation = %q", fallbackOutput)
+	}
+
+	if err := stderrFile.Truncate(0); err != nil {
+		t.Fatalf("truncate stderr capture: %v", err)
+	}
+	if _, err := stderrFile.Seek(0, io.SeekStart); err != nil {
+		t.Fatalf("rewind stderr capture: %v", err)
+	}
+	emitEarlyAgentMetadataValidationError(invalidAgentExtError(), []string{"version", "--format", "table"})
+	if err := stderrFile.Sync(); err != nil {
+		t.Fatalf("sync human stderr capture: %v", err)
+	}
+	humanOutput, err := os.ReadFile(stderrFile.Name())
+	if err != nil {
+		t.Fatalf("read human stderr capture: %v", err)
+	}
+	if json.Valid(humanOutput) || !strings.Contains(string(humanOutput), "DWS_AGENT_EXT") ||
+		strings.Contains(string(humanOutput), "must-not-leak") {
+		t.Fatalf("human validation error presentation = %q", humanOutput)
+	}
+
+	var capturedRunner *runtimeRunner
+	testseam.Swap(t, &rootNewCommandRunnerWithFlags, func(flags *GlobalFlags) executor.Runner {
+		capturedRunner = newCommandRunnerWithFlags(flags).(*runtimeRunner)
+		return capturedRunner
+	})
+	cachedSnapshot := agentMetadataSnapshot{version: "9.8.7", ext: `{"ua":"cached"}`}
+	_ = newRootCommandWithMode(
+		contextWithAgentMetadataSnapshot(context.Background(), cachedSnapshot),
+		nil,
+		false,
+		true,
+		true,
+	)
+	if capturedRunner == nil || capturedRunner.agentMetadata == nil || *capturedRunner.agentMetadata != cachedSnapshot {
+		t.Fatalf("root runner Agent metadata = %#v, want %#v", capturedRunner, cachedSnapshot)
+	}
+}
+
+func TestCrossPlatformCoverageAgentMetadataExcludedFromServiceDiscovery(t *testing.T) {
+	t.Setenv("DWS_CONFIG_DIR", t.TempDir())
+	t.Setenv(envDWSAgentHost, "")
+	t.Setenv(agentproduct.EnvName, "")
+	t.Setenv(envDWSAgentVersion, "3.0.0")
+	t.Setenv(envDWSAgentExt, `{"umt":"test-value"}`)
+
+	headers := resolveMCPRequestHeadersForInvocation(executor.Invocation{
+		CanonicalProduct: mcpMetaServerID,
+		Tool:             mcpMetaURLTool,
+	})
+	if hasHeaderFold(headers, transport.HeaderAgentVersion) || hasHeaderFold(headers, transport.HeaderAgentExt) {
+		t.Fatalf("service-discovery request leaked Agent metadata: %#v", headers)
+	}
+
+	headers = resolveMCPRequestHeadersForInvocation(executor.Invocation{CanonicalProduct: "doc", Tool: "read"})
+	if headers[transport.HeaderAgentVersion] != "3.0.0" || headers[transport.HeaderAgentExt] == "" {
+		t.Fatalf("ordinary MCP request omitted Agent metadata: %#v", headers)
+	}
+	cached := agentMetadataSnapshot{version: "3.1.0", ext: "{}"}
+	headers = resolveMCPRequestHeadersForInvocation(executor.Invocation{CanonicalProduct: "doc", Tool: "read"}, cached)
+	if headers[transport.HeaderAgentVersion] != "3.1.0" || headers[transport.HeaderAgentExt] != "{}" {
+		t.Fatalf("ordinary MCP request ignored its validated snapshot: %#v", headers)
+	}
+}
+
+func TestCrossPlatformCoverageAgentMetadataMCPAndPluginScoping(t *testing.T) {
+	t.Setenv("DWS_CONFIG_DIR", t.TempDir())
+	t.Setenv(envDWSAgentHost, "")
+	t.Setenv(agentproduct.EnvName, "")
+	t.Setenv(envDWSAgentVersion, "2.0.0")
+	t.Setenv(envDWSAgentExt, `{"ua":"test-agent/2.0"}`)
+
+	oldEdition := edition.Get()
+	t.Cleanup(func() { edition.Override(oldEdition) })
+	edition.Override(&edition.Hooks{})
+
+	pluginAuthMu.Lock()
+	oldPluginRegistry := pluginAuthRegistry
+	pluginAuthRegistry = make(map[string]*PluginAuth)
+	pluginAuthMu.Unlock()
+	t.Cleanup(func() {
+		pluginAuthMu.Lock()
+		pluginAuthRegistry = oldPluginRegistry
+		pluginAuthMu.Unlock()
+	})
+	dynamicMu.Lock()
+	oldDynamicEndpoints := dynamicEndpoints
+	oldDynamicProducts := dynamicProducts
+	oldDynamicAliases := dynamicAliases
+	oldDynamicToolEndpoints := dynamicToolEndpoints
+	dynamicEndpoints = nil
+	dynamicProducts = nil
+	dynamicAliases = nil
+	dynamicToolEndpoints = nil
+	dynamicMu.Unlock()
+	t.Cleanup(func() {
+		dynamicMu.Lock()
+		dynamicEndpoints = oldDynamicEndpoints
+		dynamicProducts = oldDynamicProducts
+		dynamicAliases = oldDynamicAliases
+		dynamicToolEndpoints = oldDynamicToolEndpoints
+		dynamicMu.Unlock()
+	})
+
+	testseam.Swap(t, &runnerPreflightDocDownload, func(*runtimeRunner, context.Context, *transport.Client, string, executor.Invocation) error {
+		return nil
+	})
+	type capturedRequest struct {
+		headers map[string]string
+		token   string
+	}
+	var captured []capturedRequest
+	testseam.Swap(t, &runnerCallTool, func(client *transport.Client, _ context.Context, _, _ string, _ map[string]any) (transport.ToolCallResult, error) {
+		copyHeaders := make(map[string]string, len(client.ExtraHeaders))
+		for key, value := range client.ExtraHeaders {
+			copyHeaders[key] = value
+		}
+		captured = append(captured, capturedRequest{headers: copyHeaders, token: client.AuthToken})
+		return transport.ToolCallResult{Content: map[string]any{"value": "ok"}}, nil
+	})
+
+	created := newCommandRunnerWithFlags(&GlobalFlags{}).(*runtimeRunner)
+	if hasHeaderFold(created.transport.ExtraHeaders, transport.HeaderAgentVersion) ||
+		hasHeaderFold(created.transport.ExtraHeaders, transport.HeaderAgentExt) {
+		t.Fatalf("new runner resolved Agent metadata before invocation validation: %#v", created.transport.ExtraHeaders)
+	}
+
+	// runSingle must not cache ambient MCP metadata on the shared base transport.
+	// Use mock mode to exercise the path without authentication or network I/O.
+	t.Setenv(envDWSAgentVersion, "2.0.1")
+	refreshRunner := &runtimeRunner{
+		transport:   transport.NewClient(nil),
+		globalFlags: &GlobalFlags{Mock: true},
+		auditSink:   audit.NopSink{},
+	}
+	refreshInvocation := executor.Invocation{CanonicalProduct: "refresh", Tool: "tool", Params: map[string]any{}}
+	if _, err := refreshRunner.runSingle(context.Background(), refreshInvocation, false); err != nil {
+		t.Fatalf("mock runSingle failed: %v", err)
+	}
+	if hasHeaderFold(refreshRunner.transport.ExtraHeaders, transport.HeaderAgentVersion) {
+		t.Fatalf("runSingle mutated the shared transport Header map: %#v", refreshRunner.transport.ExtraHeaders)
+	}
+	t.Setenv(envDWSAgentVersion, "2.0.0")
+
+	r := &runtimeRunner{
+		transport:   transport.NewClient(nil),
+		globalFlags: &GlobalFlags{Token: "test-token"},
+		auditSink:   audit.NopSink{},
+		agentMetadata: &agentMetadataSnapshot{
+			version: "2.0.0",
+			ext:     `{"ua":"test-agent/2.0"}`,
+		},
+	}
+	builtIn := executor.Invocation{CanonicalProduct: "built-in", Tool: "tool", Params: map[string]any{}}
+	if _, err := r.executeInvocation(context.Background(), "https://example.test", builtIn); err != nil {
+		t.Fatalf("built-in invocation failed: %v", err)
+	}
+
+	pluginDescriptor := mcptypes.ServerDescriptor{
+		Key:      "third-party",
+		Endpoint: "https://plugin.example.test",
+		CLI:      mcptypes.CLIOverlay{ID: "third-party"},
+		AuthHeaders: map[string]string{
+			"X-Plugin":        "yes",
+			"X-Dws-Agent-Ver": "plugin-must-not-forge-version",
+			"X-Dws-Agent-Ext": `{"source":"plugin"}`,
+		},
+	}
+	registerPluginHTTPServer(pluginDescriptor)
+	registeredPlugin, pluginOwned := LookupPluginAuth("third-party")
+	if !pluginOwned || registeredPlugin == nil || registeredPlugin.Token != "" {
+		t.Fatalf("anonymous HTTP plugin ownership = %#v, %v", registeredPlugin, pluginOwned)
+	}
+	registerPluginHTTPServer(mcptypes.ServerDescriptor{
+		Key:      "anonymous-empty",
+		Endpoint: "https://anonymous.example.test",
+		CLI:      mcptypes.CLIOverlay{ID: "anonymous-empty"},
+	})
+	if emptyPlugin, owned := LookupPluginAuth("anonymous-empty"); !owned || emptyPlugin == nil || emptyPlugin.Token != "" || len(emptyPlugin.ExtraHeaders) != 0 {
+		t.Fatalf("headerless HTTP plugin ownership = %#v, %v", emptyPlugin, owned)
+	}
+	originalPluginHeaders := maps.Clone(registeredPlugin.ExtraHeaders)
+	pluginInvocation := executor.Invocation{CanonicalProduct: "third-party", Tool: "tool", Params: map[string]any{}}
+	if _, err := r.executeInvocation(context.Background(), "https://plugin.example.test", pluginInvocation); err != nil {
+		t.Fatalf("plugin invocation failed: %v", err)
+	}
+
+	if len(captured) != 2 {
+		t.Fatalf("captured %d calls, want 2", len(captured))
+	}
+	if captured[0].headers[transport.HeaderAgentVersion] != "2.0.0" || captured[0].headers[transport.HeaderAgentExt] != `{"ua":"test-agent/2.0"}` {
+		t.Fatalf("built-in MCP metadata = %#v", captured[0].headers)
+	}
+	if hasHeaderFold(captured[1].headers, transport.HeaderAgentVersion) || hasHeaderFold(captured[1].headers, transport.HeaderAgentExt) {
+		t.Fatalf("plugin request leaked Agent metadata: %#v", captured[1].headers)
+	}
+	if got := captured[1].headers["X-Plugin"]; got != "yes" {
+		t.Fatalf("plugin-owned header = %q, want yes", got)
+	}
+	if captured[1].token != "" {
+		t.Fatalf("anonymous plugin unexpectedly received default OAuth token")
+	}
+	if !maps.Equal(registeredPlugin.ExtraHeaders, originalPluginHeaders) {
+		t.Fatalf("plugin Header sanitization mutated registry state: got %#v want %#v", registeredPlugin.ExtraHeaders, originalPluginHeaders)
+	}
+	if got := pluginRequestHeaders(nil); got != nil {
+		t.Fatalf("nil plugin auth produced Headers: %#v", got)
+	}
+	if got := pluginRequestHeaders(&PluginAuth{ExtraHeaders: map[string]string{
+		"X-DWS-AGENT-VER": "forged",
+		"X-DWS-AGENT-EXT": `{"forged":true}`,
+	}}); got != nil {
+		t.Fatalf("reserved-only plugin Headers survived sanitization: %#v", got)
+	}
+
+	// Keep the execution-boundary auth guard independently testable: even if a
+	// future token provider returns an empty token without an error, built-in MCP
+	// 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) {
+		resolveCalled = true
+		return "", nil
+	})
+	callsBefore := len(captured)
+	unauthenticated := &runtimeRunner{
+		transport:   transport.NewClient(nil),
+		globalFlags: &GlobalFlags{},
+		auditSink:   audit.NopSink{},
+	}
+	if _, err := unauthenticated.executeInvocation(context.Background(), "https://example.test", executor.Invocation{CanonicalProduct: "built-in-unauthenticated", Tool: "tool"}); err == nil || !isAuthError(err) {
+		t.Fatalf("unauthenticated built-in request = %v, want auth error", err)
+	}
+	if !resolveCalled {
+		t.Fatal("unauthenticated request did not exercise the token resolver")
+	}
+	if len(captured) != callsBefore {
+		t.Fatalf("unauthenticated built-in request reached transport: calls %d -> %d", callsBefore, len(captured))
+	}
+}
+
+func hasHeaderFold(headers map[string]string, want string) bool {
+	for key := range headers {
+		if strings.EqualFold(key, want) {
+			return true
+		}
+	}
+	return false
+}

internal/app/agent_product_test.go

@@ -158,7 +158,7 @@ func TestApplyAgentProductHeader(t *testing.T) {
 	}
 }
 
-func TestRootRejectsInvalidAgentProductBeforeEditionHook(t *testing.T) {
+func TestCrossPlatformCoverageRootRejectsInvalidAgentProductBeforeEditionHook(t *testing.T) {
 	t.Setenv("DWS_CONFIG_DIR", t.TempDir())
 	const invalidValue = "DO_NOT ECHO"
 	t.Setenv(agentproduct.EnvName, invalidValue)

internal/app/auth_registry.go

@@ -15,11 +15,10 @@ package app
 
 import "sync"
 
-// PluginAuth holds authentication credentials for a plugin-owned
-// streamable-http MCP server. Each server is keyed by its canonical
-// product ID (CLI.ID) so that different servers can use independent
-// tokens without interfering with each other or with the default
-// DingTalk OAuth token.
+// PluginAuth marks ownership of a plugin-owned streamable-http MCP server and
+// holds its optional authentication credentials. Every accepted HTTP plugin,
+// including an anonymous one, has a non-nil record keyed by canonical product
+// ID (CLI.ID) so execution never falls back to built-in DingTalk OAuth.
 type PluginAuth struct {
 	// Token is the Bearer token extracted from the plugin's
 	// "Authorization" header (e.g. a third-party API key).
@@ -39,27 +38,25 @@ var (
 	pluginAuthRegistry = make(map[string]*PluginAuth)
 )
 
-// RegisterPluginAuth stores authentication credentials for a plugin
-// server keyed by its canonical product ID. The runner looks up these
-// credentials at execution time to inject the correct Bearer token
-// instead of the default DingTalk OAuth token.
+// RegisterPluginAuth stores ownership and optional authentication credentials
+// for a plugin server keyed by its canonical product ID.
 func RegisterPluginAuth(productID string, auth *PluginAuth) {
 	pluginAuthMu.Lock()
 	defer pluginAuthMu.Unlock()
 	pluginAuthRegistry[productID] = auth
 }
 
-// ClearPluginAuth removes credentials for a plugin product. Registration uses
-// this before applying an accepted descriptor so a descriptor without custom
-// auth cannot inherit stale credentials from an earlier root construction.
+// ClearPluginAuth removes the ownership and credential record for a plugin
+// product.
 func ClearPluginAuth(productID string) {
 	pluginAuthMu.Lock()
 	defer pluginAuthMu.Unlock()
 	delete(pluginAuthRegistry, productID)
 }
 
-// LookupPluginAuth returns the authentication credentials registered
-// for the given product ID, or nil if none exists.
+// LookupPluginAuth returns plugin ownership and optional authentication
+// credentials for the product ID. The bool denotes ownership, not whether a
+// Bearer token is present.
 func LookupPluginAuth(productID string) (*PluginAuth, bool) {
 	pluginAuthMu.RLock()
 	defer pluginAuthMu.RUnlock()

internal/app/coverage_more_test.go

@@ -61,11 +61,16 @@ func appRPCServer(t *testing.T, initOK, listOK bool) *httptest.Server {
 }
 
 func TestCrossPlatformCoveragePluginAuthCoverage(t *testing.T) {
-	registerPluginAuthFromHeaders(mcptypes.ServerDescriptor{Key: "fallback", Endpoint: "%", AuthHeaders: map[string]string{"Authorization": "token"}})
-	registerPluginAuthFromHeaders(mcptypes.ServerDescriptor{Key: "server", Endpoint: "https://x.test", CLI: mcptypes.CLIOverlay{ID: "cli"}, AuthHeaders: map[string]string{"Authorization": "Bearer token", "X": "Y"}})
-	registerPluginAuthFromHeaders(mcptypes.ServerDescriptor{Key: "none"})
-	if got, ok := LookupPluginAuth("cli"); !ok || got == nil || got.Token != "token" {
-		t.Fatalf("registered plugin auth = %#v, %v", got, ok)
+	fallback := pluginAuthFromServerDescriptor(mcptypes.ServerDescriptor{Key: "fallback", Endpoint: "%", AuthHeaders: map[string]string{"Authorization": "token"}})
+	if fallback == nil || fallback.Token != "token" || len(fallback.TrustedDomains) != 0 {
+		t.Fatalf("fallback plugin auth = %#v", fallback)
+	}
+	got := pluginAuthFromServerDescriptor(mcptypes.ServerDescriptor{Key: "server", Endpoint: "https://x.test", CLI: mcptypes.CLIOverlay{ID: "cli"}, AuthHeaders: map[string]string{"Authorization": "Bearer token", "X": "Y"}})
+	if got == nil || got.Token != "token" || got.ExtraHeaders["X"] != "Y" || len(got.TrustedDomains) != 2 {
+		t.Fatalf("plugin auth = %#v", got)
+	}
+	if anonymous := pluginAuthFromServerDescriptor(mcptypes.ServerDescriptor{Key: "none"}); anonymous == nil || anonymous.Token != "" {
+		t.Fatalf("anonymous plugin ownership = %#v", anonymous)
 	}
 }
 

internal/app/identity_export.go

@@ -13,9 +13,9 @@
 
 package app
 
-// MCPIdentityHeaders returns the same header map used for MCP HTTP requests
-// (agent identity, env trace headers, edition MergeHeaders). Intended for
-// non-MCP transports such as the A2A gateway client.
+// MCPIdentityHeaders returns the shared identity header map used by non-MCP
+// transports such as the A2A gateway client. MCP-only Agent version and
+// extension metadata are intentionally excluded.
 func MCPIdentityHeaders() map[string]string {
 	return resolveIdentityHeaders()
 }

internal/app/param_alias_e2e_test.go

@@ -68,6 +68,45 @@ func (c *paramAliasCaptureCaller) paramAliasResponseForTool(tool string) string
 		return `{"result":[{"templateId":"fixture-template-id"}]}`
 	case "create_document":
 		return `{"nodeId":"fixture-node"}`
+	case "list_files":
+		return `{"success":true,"result":{"files":[],"hasMore":false}}`
+	case "list_recycle_items":
+		return `{"success":true,"result":{"recycleItems":[{"recycleItemId":"recycle-1","originalName":"Fixture Node"}],"hasMore":false}}`
+	case "get_star_list":
+		return `{"success":true,"result":{"starList":[],"hasMore":false}}`
+	case "list_file_versions":
+		return `{"success":true,"result":{"versions":[{"version":3,"name":"Fixture Version"}],"hasMore":false}}`
+	case "get_file_info":
+		name := "Fixture Node"
+		for index := len(c.calls) - 2; index >= 0; index-- {
+			call := c.calls[index]
+			switch call.tool {
+			case "create_folder":
+				if value, ok := call.args["name"].(string); ok {
+					name = value
+				}
+				index = -1
+			case "rename_document":
+				if value, ok := call.args["newName"].(string); ok {
+					name = value
+				}
+				index = -1
+			}
+		}
+		encoded, _ := json.Marshal(map[string]any{"success": true, "result": map[string]any{"fileId": "node-1", "name": name}})
+		return string(encoded)
+	case "get_cover", "get_node_stats":
+		return `{"success":true,"result":{"nodeId":"node-1"}}`
+	case "get_file_publish_status":
+		return `{"success":true,"result":{"fileId":"node-1","published":false}}`
+	case "create_folder", "create_shortcut":
+		return `{"success":true,"fileId":"node-1"}`
+	case "delete_document", "mark_star", "unmark_star", "restore_recycle_item", "rename_document", "revert_file_version":
+		return `{"success":true,"fileId":"node-1"}`
+	case "set_file_publish":
+		return `{"success":true}`
+	case "download_file", "download_file_version":
+		return `{"success":true,"result":{"downloadUrl":"http://invalid.test/fixture.bin","fileName":"fixture.bin"}}`
 	case "get_document_content":
 		for index := len(c.calls) - 2; index >= 0; index-- {
 			call := c.calls[index]
@@ -322,9 +361,9 @@ func TestCrossPlatformCoverageParamAliasWriteCommandFinalPayload(t *testing.T) {
 	caller := &paramAliasCaptureCaller{}
 	ctx, err := executeParamAliasE2E(t, caller,
 		"chat", "message", "send",
-		"--to-user", "D-recipient",
+		"--to-user", appFixtureCurrentDOpenID,
 		"--text", "hello alias",
-		"--uuid", "alias-e2e",
+		"--idempotency-key", "alias-e2e",
 	)
 	if err != nil {
 		t.Fatalf("chat write alias E2E error = %v", err)
@@ -336,7 +375,7 @@ func TestCrossPlatformCoverageParamAliasWriteCommandFinalPayload(t *testing.T) {
 		t.Fatalf("chat calls = %#v", caller.calls)
 	}
 	payload := caller.calls[0].args
-	if payload["receiverOpenDingTalkId"] != "D-recipient" || payload["uuid"] != "alias-e2e" || payload["msgType"] != "markdown" {
+	if payload["receiverOpenDingTalkId"] != appFixtureCurrentDOpenID || payload["uuid"] != "alias-e2e" || payload["msgType"] != "markdown" {
 		t.Fatalf("chat payload identity fields = %#v", payload)
 	}
 	content, _ := payload["content"].(string)
@@ -350,6 +389,29 @@ func TestCrossPlatformCoverageParamAliasWriteCommandFinalPayload(t *testing.T) {
 	}
 }
 
+func TestCrossPlatformCoverageChatMessageSendLegacyUUIDAliasFinalPayload(t *testing.T) {
+	caller := &paramAliasCaptureCaller{}
+	_, err := executeParamAliasE2E(t, caller,
+		"chat", "message", "send",
+		"--group", "fixture-conversation",
+		"--text", "hello legacy uuid",
+		"--uuid", "legacy-alias-e2e",
+	)
+	if err != nil {
+		t.Fatalf("chat message send legacy uuid error = %v", err)
+	}
+	if len(caller.calls) != 1 || caller.calls[0].tool != "send_personal_message" {
+		t.Fatalf("chat calls = %#v", caller.calls)
+	}
+	payload := caller.calls[0].args
+	if payload["uuid"] != "legacy-alias-e2e" || payload["openConversationId"] != "fixture-conversation" {
+		t.Fatalf("chat legacy uuid payload = %#v", payload)
+	}
+	if _, exists := payload["idempotency-key"]; exists {
+		t.Fatalf("chat payload leaked CLI-only idempotency-key: %#v", payload)
+	}
+}
+
 func TestCrossPlatformCoverageChatReactionConversationAliasesReachCanonicalPayload(t *testing.T) {
 	tests := []struct {
 		name     string
@@ -627,11 +689,11 @@ func TestCrossPlatformCoverageSelectedParamAliasesProduceCanonicalEquivalentDryR
 			tool: "send_personal_message",
 			canonicalArgs: []string{
 				"--dry-run", "chat", "message", "send",
-				"--user", "D-recipient", "--text", "hello dry-run", "--uuid", "alias-dry-run",
+				"--user", appFixtureCurrentDOpenID, "--text", "hello dry-run", "--uuid", "alias-dry-run",
 			},
 			aliasArgs: []string{
 				"--dry-run", "chat", "message", "send",
-				"--to-user", "D-recipient", "--text", "hello dry-run", "--uuid", "alias-dry-run",
+				"--to-user", appFixtureCurrentDOpenID, "--text", "hello dry-run", "--uuid", "alias-dry-run",
 			},
 			wantCorrections: 1,
 			wantArgKeys:     []string{"clawType", "content", "msgType", "receiverOpenDingTalkId", "uuid"},

internal/app/param_alias_payload_equivalence_test.go

@@ -4,14 +4,21 @@
 package app
 
 import (
+	"errors"
 	"reflect"
 	"strings"
 	"testing"
 
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/cli"
+	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/pipeline"
 )
 
+const (
+	appFixtureCurrentDOpenID  = "DAAAAAAAAAAAiE"
+	appFixtureCurrentDOpenID2 = "DAQEBAQEBAQEiE"
+)
+
 // paramAliasCompleteCommands is deliberately keyed by the exact reviewed
 // fixture command path. Every argv is a complete, business-valid invocation:
 // required companion flags are present, time and enum values are valid, and
@@ -32,12 +39,12 @@ var paramAliasCompleteCommands = map[string][]string{
 	"chat +chat-messages":                      {"chat", "+chat-messages", "--group", "fixture-conversation"},
 	"chat +chat-add-bot":                       {"chat", "+chat-add-bot", "--id", "fixture-conversation", "--robot-code", "robot-1", "--yes"},
 	"chat +chat-audit-join":                    {"chat", "+chat-audit-join", "--group", "fixture-conversation", "--record-id", "7", "--applicant", "user-1", "--inviter", "user-2", "--status", "AuditApprove", "--yes"},
-	"chat +chat-members-get":                   {"chat", "+chat-members-get", "--id", "fixture-conversation", "--users", "D-user-1,D-user-2"},
+	"chat +chat-members-get":                   {"chat", "+chat-members-get", "--id", "fixture-conversation", "--users", appFixtureCurrentDOpenID + "," + appFixtureCurrentDOpenID2},
 	"chat +chat-members-list":                  {"chat", "+chat-members-list", "--conversation-id", "fixture-conversation", "--member-types", "user,bot"},
-	"chat +chat-mute-member":                   {"chat", "+chat-mute-member", "--group", "fixture-conversation", "--users", "D-user-1,D-user-2", "--mute-time", "3600000", "--yes"},
+	"chat +chat-mute-member":                   {"chat", "+chat-mute-member", "--group", "fixture-conversation", "--users", appFixtureCurrentDOpenID + "," + appFixtureCurrentDOpenID2, "--mute-time", "3600000", "--yes"},
 	"chat +chat-remove-bot":                    {"chat", "+chat-remove-bot", "--id", "fixture-conversation", "--bot-id", "bot-1", "--yes"},
-	"chat +chat-role-remove-user":              {"chat", "+chat-role-remove-user", "--group", "fixture-conversation", "--user", "D-user-1", "--role-ids", "role-1", "--yes"},
-	"chat +chat-transfer-owner":                {"chat", "+chat-transfer-owner", "--group", "fixture-conversation", "--new-owner", "D-user-1", "--yes"},
+	"chat +chat-role-remove-user":              {"chat", "+chat-role-remove-user", "--group", "fixture-conversation", "--user", appFixtureCurrentDOpenID, "--role-ids", "role-1", "--yes"},
+	"chat +chat-transfer-owner":                {"chat", "+chat-transfer-owner", "--group", "fixture-conversation", "--new-owner", appFixtureCurrentDOpenID, "--yes"},
 	"chat +chat-update":                        {"chat", "+chat-update", "--group", "fixture-conversation", "--name", "Fixture Renamed Group", "--yes"},
 	"chat +bot-find":                           {"chat", "+bot-find", "--query", "fixture", "--limit", "7"},
 	"chat +bot-search":                         {"chat", "+bot-search", "--name", "Fixture Bot", "--page", "2", "--size", "7"},
@@ -55,7 +62,7 @@ var paramAliasCompleteCommands = map[string][]string{
 	"chat +messages-list":                      {"chat", "+messages-list", "--group", "fixture-conversation", "--time", "2026-03-10 00:00:00", "--limit", "7"},
 	"chat +messages-list-direct":               {"chat", "+messages-list-direct", "--user", "user-1", "--time", "2026-03-10 00:00:00", "--limit", "7"},
 	"chat +messages-list-unread-conversations": {"chat", "+messages-list-unread-conversations", "--count", "7", "--exclude-muted"},
-	"chat +messages-reply":                     {"chat", "+messages-reply", "--conversation-id", "fixture-conversation", "--ref-msg-id", "message-1", "--ref-sender", "D-sender", "--text", "hello fixture", "--yes"},
+	"chat +messages-reply":                     {"chat", "+messages-reply", "--conversation-id", "fixture-conversation", "--ref-msg-id", "message-1", "--ref-sender", appFixtureCurrentDOpenID, "--text", "hello fixture", "--yes"},
 	"chat +messages-resource-download":         {"chat", "+messages-resource-download", "--resource-id", "resource-1", "--message-id", "message-1", "--open-conversation-id", "fixture-conversation", "--output", "downloads/fixture.bin"},
 	"chat +messages-set-pin":                   {"chat", "+messages-set-pin", "--open-conversation-id", "fixture-conversation", "--msg-id", "message-1", "--yes"},
 	"chat +messages-send-by-webhook":           {"chat", "+messages-send-by-webhook", "--token", "fixture-token", "--title", "Fixture Alert", "--text", "fixture", "--at-users", "user-1,user-2", "--yes"},
@@ -68,10 +75,10 @@ var paramAliasCompleteCommands = map[string][]string{
 	"chat category create-smart":               {"chat", "category", "create-smart", "--name", "Fixture Smart Category", "--keywords", "fixture,priority", "--yes"},
 	"chat category rename":                     {"chat", "category", "rename", "--category-id", "7", "--title", "Renamed Cat", "--yes"},
 	"chat group members":                       {"chat", "group", "members", "--id", "fixture-conversation"},
-	"chat group members add":                   {"chat", "group", "members", "add", "--id", "fixture-conversation", "--users", "D-user-1"},
+	"chat group members add":                   {"chat", "group", "members", "add", "--id", "fixture-conversation", "--users", appFixtureCurrentDOpenID},
 	"chat group members add-bot":               {"chat", "group", "members", "add-bot", "--id", "fixture-conversation", "--robot-code", "robot-1", "--yes"},
-	"chat group members list-by-ids":           {"chat", "group", "members", "list-by-ids", "--id", "fixture-conversation", "--users", "D-user-1,D-user-2"},
-	"chat group members remove":                {"chat", "group", "members", "remove", "--id", "fixture-conversation", "--users", "D-user-1", "--yes"},
+	"chat group members list-by-ids":           {"chat", "group", "members", "list-by-ids", "--id", "fixture-conversation", "--users", appFixtureCurrentDOpenID + "," + appFixtureCurrentDOpenID2},
+	"chat group members remove":                {"chat", "group", "members", "remove", "--id", "fixture-conversation", "--users", appFixtureCurrentDOpenID, "--yes"},
 	"chat group members remove-bot":            {"chat", "group", "members", "remove-bot", "--id", "fixture-conversation", "--bot-id", "bot-1", "--yes"},
 	"chat group rename":                        {"chat", "group", "rename", "--id", "fixture-conversation", "--name", "Fixture Renamed Group", "--yes"},
 	"chat group set-admin":                     {"chat", "group", "set-admin", "--group", "fixture-conversation", "--user", "user-1", "--yes"},
@@ -86,9 +93,9 @@ var paramAliasCompleteCommands = map[string][]string{
 	"chat message list-by-ids":                 {"chat", "message", "list-by-ids", "--msg-ids", "message-1,message-2"},
 	"chat message list-unread-conversations":   {"chat", "message", "list-unread-conversations", "--count", "7", "--exclude-muted"},
 	"chat message recall":                      {"chat", "message", "recall", "--conversation-id", "fixture-conversation", "--msg-id", "message-1", "--yes"},
-	"chat message reply":                       {"chat", "message", "reply", "--conversation-id", "fixture-conversation", "--ref-msg-id", "message-1", "--ref-sender", "D-sender", "--text", "hello fixture", "--yes"},
+	"chat message reply":                       {"chat", "message", "reply", "--conversation-id", "fixture-conversation", "--ref-msg-id", "message-1", "--ref-sender", appFixtureCurrentDOpenID, "--text", "hello fixture", "--yes"},
 	"chat message search-advanced":             {"chat", "message", "search-advanced", "--conversation-ids", "fixture-conversation", "--query", "fixture"},
-	"chat message send":                        {"chat", "message", "send", "--user", "D-recipient", "--text", "hello fixture", "--uuid", "param-alias-equivalence", "--yes"},
+	"chat message send":                        {"chat", "message", "send", "--user", appFixtureCurrentDOpenID, "--text", "hello fixture", "--idempotency-key", "param-alias-equivalence", "--yes"},
 	"chat message send-by-bot":                 {"chat", "message", "send-by-bot", "--robot-code", "robot-1", "--group", "fixture-conversation", "--title", "Fixture Alert", "--text", "@user-1 @user-2 fixture", "--at-user-ids", "user-1,user-2", "--yes"},
 	"chat message send-by-webhook":             {"chat", "message", "send-by-webhook", "--token", "fixture-token", "--title", "Fixture Alert", "--text", "fixture", "--at-users", "user-1,user-2", "--yes"},
 	"contact +dept-members":                    {"contact", "+dept-members", "--dept", "Fixture Dept"},
@@ -124,6 +131,7 @@ var paramAliasCompleteCommands = map[string][]string{
 	"doc +version-revert":                      {"doc", "+version-revert", "--node", "node-1", "--version", "3", "--yes"},
 	"doc +version-save":                        {"doc", "+version-save", "--node", "node-1", "--yes"},
 	"doc +update":                              {"doc", "+update", "--node", "node-1", "--command", "overwrite", "--content", `["root",{}]`, "--doc-format", "jsonml", "--expected-revision", "1", "--yes"},
+	"doc +export":                              {"doc", "+export", "--node", "node-1", "--export-format", "docx", "--output", "exports/fixture.docx"},
 	"doc block insert":                         {"doc", "block", "insert", "--node", "node-1", "--text", "fixture paragraph", "--yes"},
 	"doc block update":                         {"doc", "block", "update", "--node", "node-1", "--block-id", "block-1", "--text", "fixture paragraph", "--yes"},
 	"doc comment create":                       {"doc", "comment", "create", "--node", "node-1", "--content", "fixture comment", "--yes"},
@@ -131,9 +139,43 @@ var paramAliasCompleteCommands = map[string][]string{
 	"doc comment delete":                       {"doc", "comment", "delete", "--node", "node-1", "--comment-key", "comment-1", "--yes"},
 	"doc comment reply":                        {"doc", "comment", "reply", "--node", "node-1", "--comment-key", "comment-1", "--content", "fixture reply", "--mentioned-open-conversation-id", "cid-1,cid-2", "--yes"},
 	"doc comment update":                       {"doc", "comment", "update", "--node", "node-1", "--comment-key", "comment-1", "--content", "fixture update", "--yes"},
+	"doc create":                               {"doc", "create", "--name", "Fixture Document", "--workspace", "workspace-1"},
 	"doc version revert":                       {"doc", "version", "revert", "--node", "node-1", "--version", "3", "--yes"},
+	"drive +cover":                             {"drive", "+cover", "--node", "node-1"},
+	"drive +create-folder":                     {"drive", "+create-folder", "--name", "Fixture Folder", "--space-id", "space-1", "--folder", "folder-1"},
+	"drive +create-shortcut":                   {"drive", "+create-shortcut", "--node", "node-1", "--folder", "folder-1", "--workspace", "workspace-1"},
+	"drive +delete":                            {"drive", "+delete", "--node", "node-1", "--yes"},
+	"drive +download":                          {"drive", "+download", "--node", "node-1", "--space-id", "space-1", "--output", "downloads/fixture.bin"},
+	"drive +info":                              {"drive", "+info", "--node", "node-1", "--space-id", "space-1"},
+	"drive +inspect":                           {"drive", "+inspect", "--node", "node-1", "--space-id", "space-1", "--include-stats"},
+	"drive +list":                              {"drive", "+list", "--space-id", "space-1", "--folder", "folder-1", "--limit", "7", "--cursor", "cursor-1", "--order-by", "name", "--order", "asc"},
+	"drive +publish-get":                       {"drive", "+publish-get", "--node", "node-1"},
+	"drive +publish-unset":                     {"drive", "+publish-unset", "--node", "node-1", "--yes"},
+	"drive +recycle-list":                      {"drive", "+recycle-list", "--space-id", "space-1", "--limit", "7", "--cursor", "cursor-1"},
+	"drive +recycle-restore":                   {"drive", "+recycle-restore", "--id", "recycle-1", "--yes"},
+	"drive +rename":                            {"drive", "+rename", "--node", "node-1", "--name", "Fixture Renamed", "--yes"},
+	"drive +search":                            {"drive", "+search", "--query", "fixture"},
+	"drive +star-add":                          {"drive", "+star-add", "--node", "node-1"},
+	"drive +star-list":                         {"drive", "+star-list", "--limit", "7", "--cursor", "cursor-1"},
+	"drive +star-remove":                       {"drive", "+star-remove", "--node", "node-1"},
+	"drive +stats":                             {"drive", "+stats", "--node", "node-1"},
+	"drive +upload":                            {"drive", "+upload", "--file", "param_alias_payload_equivalence_test.go", "--file-name", "fixture.txt", "--mime-type", "text/plain", "--space-id", "space-1", "--node", "node-1", "--yes"},
+	"drive +version-download":                  {"drive", "+version-download", "--node", "node-1", "--version", "3", "--output", "downloads/fixture-v3.bin"},
+	"drive +version-get":                       {"drive", "+version-get", "--node", "node-1", "--version", "3"},
+	"drive +version-history":                   {"drive", "+version-history", "--node", "node-1", "--limit", "7", "--cursor", "cursor-1"},
+	"drive +version-revert":                    {"drive", "+version-revert", "--node", "node-1", "--version", "3", "--yes"},
+	"drive commit":                             {"drive", "commit", "--file-name", "fixture.txt", "--file-size", "7", "--upload-id", "upload-1", "--space-id", "space-1"},
+	"drive copy":                               {"drive", "copy", "--node", "node-1", "--folder", "folder-1"},
+	"drive download":                           {"drive", "download", "--node", "node-1", "--output", "downloads/fixture.bin", "--version", "3", "--space-id", "space-1"},
 	"drive info":                               {"drive", "info", "--node", "node-1", "--space-id", "space-1"},
 	"drive list":                               {"drive", "list", "--folder", "folder-1", "--limit", "7"},
+	"drive mkdir":                              {"drive", "mkdir", "--name", "Fixture Folder", "--space-id", "space-1"},
+	"drive permission add":                     {"drive", "permission", "add", "--node", "node-1", "--users", "user-1,user-2", "--role", "READER"},
+	"drive recycle list":                       {"drive", "recycle", "list", "--space-id", "space-1", "--limit", "7"},
+	"drive recycle restore":                    {"drive", "recycle", "restore", "--id", "recycle-1"},
+	"drive search":                             {"drive", "search", "--query", "fixture", "--created-from", "1", "--created-to", "2", "--modified-from", "3", "--modified-to", "4", "--creator-uids", "user-1,user-2"},
+	"drive upload":                             {"drive", "upload", "--file", "../../go.mod", "--space-id", "space-1"},
+	"drive upload-info":                        {"drive", "upload-info", "--file-name", "fixture.txt", "--file-size", "7", "--space-id", "space-1"},
 	"mail +find-mail-user":                     {"mail", "+find-mail-user", "--query", "fixture", "--limit", "7"},
 	"mail folder update":                       {"mail", "folder", "update", "--email", "fixture@example.com", "--id", "folder-1", "--name", "Fixture Folder", "--yes"},
 	"mail message search":                      {"mail", "message", "search", "--email", "fixture@example.com", "--query", "subject:fixture"},
@@ -156,15 +198,29 @@ var paramAliasCompleteCommandVariants = map[string]map[string][]string{
 	"doc block insert": {
 		"parent-block": {"doc", "block", "insert", "--node", "node-1", "--parent-block", "parent-block-1", "--index", "0", "--text", "fixture paragraph", "--yes"},
 	},
+	"doc +inspect": {
+		"include-permissions": {"doc", "+inspect", "--node", "node-1", "--include-permissions"},
+	},
+	"doc +search": {
+		"created-from": {"doc", "+search", "--query", "fixture", "--created-from", "1"},
+		"created-to":   {"doc", "+search", "--query", "fixture", "--created-to", "2"},
+		"creator-uids": {"doc", "+search", "--query", "fixture", "--creator-uids", "user-1,user-2"},
+	},
+	"drive list": {
+		"workspace": {"drive", "list", "--workspace", "workspace-1", "--limit", "7"},
+		"order-by":  {"drive", "list", "--folder", "folder-1", "--order-by", "name", "--limit", "7"},
+		"space-id":  {"drive", "list", "--space-id", "space-1", "--limit", "7"},
+		"order":     {"drive", "list", "--folder", "folder-1", "--order", "asc", "--limit", "7"},
+	},
 	"chat message list": {
 		"user": {"chat", "message", "list", "--user", "user-1", "--time", "2026-03-10 00:00:00", "--limit", "7"},
 	},
 	"chat message list-by-sender": {
-		"sender-open-dingtalk-id": {"chat", "message", "list-by-sender", "--sender-open-dingtalk-id", "D-sender", "--start", "2026-03-10T00:00:00+08:00", "--end", "2026-03-11T00:00:00+08:00", "--limit", "7", "--cursor", "0"},
+		"sender-open-dingtalk-id": {"chat", "message", "list-by-sender", "--sender-open-dingtalk-id", appFixtureCurrentDOpenID, "--start", "2026-03-10T00:00:00+08:00", "--end", "2026-03-11T00:00:00+08:00", "--limit", "7", "--cursor", "0"},
 	},
 	"chat message send": {
-		"group":     {"chat", "message", "send", "--group", "fixture-conversation", "--text", "hello fixture", "--uuid", "param-alias-equivalence-group", "--yes"},
-		"file-path": {"chat", "message", "send", "--group", "fixture-conversation", "--msg-type", "file", "--file-path", "../../go.mod", "--dentry-id", "1", "--space-id", "2", "--uuid", "param-alias-equivalence-file", "--yes"},
+		"group":     {"chat", "message", "send", "--group", "fixture-conversation", "--text", "hello fixture", "--idempotency-key", "param-alias-equivalence-group", "--yes"},
+		"file-path": {"chat", "message", "send", "--group", "fixture-conversation", "--msg-type", "file", "--file-path", "../../go.mod", "--dentry-id", "1", "--space-id", "2", "--idempotency-key", "param-alias-equivalence-file", "--yes"},
 	},
 	"chat +conversation-set-top": {
 		"conversation-ids": {"chat", "+conversation-set-top", "--conversation-ids", "fixture-conversation-1,fixture-conversation-2", "--yes"},
@@ -241,12 +297,105 @@ var paramAliasNewIMCases = []struct {
 	{command: "chat +messages-set-pin", emitted: "conversation-id", canonical: "open-conversation-id"},
 }
 
+// paramAliasNewDriveCases is the exact executable-alias set introduced by the
+// reviewed Drive expansion. Guard fixtures are covered separately by the
+// exhaustive runtime-contract tests; every entry here must preserve the final
+// transport payload of its canonical spelling.
+var paramAliasNewDriveCases = []struct {
+	command   string
+	emitted   string
+	canonical string
+}{
+	{command: "drive +cover", emitted: "dentry-uuid", canonical: "node"},
+	{command: "drive +create-folder", emitted: "folder-name", canonical: "name"},
+	{command: "drive +create-folder", emitted: "storage-space-id", canonical: "space-id"},
+	{command: "drive +create-shortcut", emitted: "source-file-id", canonical: "node"},
+	{command: "drive +create-shortcut", emitted: "target-folder-id", canonical: "folder"},
+	{command: "drive +create-shortcut", emitted: "target-workspace-id", canonical: "workspace"},
+	{command: "drive +delete", emitted: "file-id", canonical: "node"},
+	{command: "drive +download", emitted: "dentry-uuid", canonical: "node"},
+	{command: "drive +download", emitted: "destination-path", canonical: "output"},
+	{command: "drive +inspect", emitted: "include-statistics", canonical: "include-stats"},
+	{command: "drive +list", emitted: "folder-id", canonical: "folder"},
+	{command: "drive +list", emitted: "page-size", canonical: "limit"},
+	{command: "drive +list", emitted: "next-token", canonical: "cursor"},
+	{command: "drive +list", emitted: "sort-direction", canonical: "order"},
+	{command: "drive +list", emitted: "sort-by", canonical: "order-by"},
+	{command: "drive +publish-get", emitted: "dentry-uuid", canonical: "node"},
+	{command: "drive +publish-unset", emitted: "file-id", canonical: "node"},
+	{command: "drive +recycle-list", emitted: "storage-space-id", canonical: "space-id"},
+	{command: "drive +recycle-list", emitted: "page-token", canonical: "cursor"},
+	{command: "drive +recycle-restore", emitted: "recycle-item-id", canonical: "id"},
+	{command: "drive +rename", emitted: "file-id", canonical: "node"},
+	{command: "drive +rename", emitted: "new-name", canonical: "name"},
+	{command: "drive +star-add", emitted: "dentry-uuid", canonical: "node"},
+	{command: "drive +star-list", emitted: "max-results", canonical: "limit"},
+	{command: "drive +star-remove", emitted: "file-id", canonical: "node"},
+	{command: "drive +stats", emitted: "dentry-uuid", canonical: "node"},
+	{command: "drive +upload", emitted: "source-file", canonical: "file"},
+	{command: "drive +upload", emitted: "name", canonical: "file-name"},
+	{command: "drive +upload", emitted: "overwrite-node-id", canonical: "node"},
+	{command: "drive +version-download", emitted: "version-number", canonical: "version"},
+	{command: "drive +version-download", emitted: "save-path", canonical: "output"},
+	{command: "drive +version-get", emitted: "version-no", canonical: "version"},
+	{command: "drive +version-history", emitted: "next-cursor", canonical: "cursor"},
+	{command: "drive +version-history", emitted: "page-size", canonical: "limit"},
+	{command: "drive +version-revert", emitted: "version-number", canonical: "version"},
+	{command: "drive +cover", emitted: "node-id", canonical: "node"},
+	{command: "drive +create-shortcut", emitted: "node-id", canonical: "node"},
+	{command: "drive +delete", emitted: "node-id", canonical: "node"},
+	{command: "drive +download", emitted: "node-id", canonical: "node"},
+	{command: "drive +inspect", emitted: "node-id", canonical: "node"},
+	{command: "drive +publish-get", emitted: "node-id", canonical: "node"},
+	{command: "drive +publish-unset", emitted: "node-id", canonical: "node"},
+	{command: "drive +rename", emitted: "node-id", canonical: "node"},
+	{command: "drive +star-add", emitted: "node-id", canonical: "node"},
+	{command: "drive +star-remove", emitted: "node-id", canonical: "node"},
+	{command: "drive +stats", emitted: "node-id", canonical: "node"},
+	{command: "drive +upload", emitted: "node-id", canonical: "node"},
+	{command: "drive +version-download", emitted: "node-id", canonical: "node"},
+	{command: "drive +version-get", emitted: "node-id", canonical: "node"},
+	{command: "drive +version-history", emitted: "node-id", canonical: "node"},
+	{command: "drive +version-revert", emitted: "node-id", canonical: "node"},
+	{command: "drive +cover", emitted: "url", canonical: "node"},
+	{command: "drive +create-shortcut", emitted: "document-id", canonical: "node"},
+	{command: "drive +delete", emitted: "folder-id", canonical: "node"},
+	{command: "drive +inspect", emitted: "document-id", canonical: "node"},
+	{command: "drive +inspect", emitted: "folder-id", canonical: "node"},
+	{command: "drive +publish-get", emitted: "url", canonical: "node"},
+	{command: "drive +publish-unset", emitted: "document-url", canonical: "node"},
+	{command: "drive +rename", emitted: "document-id", canonical: "node"},
+	{command: "drive +rename", emitted: "folder-id", canonical: "node"},
+	{command: "drive +star-add", emitted: "url", canonical: "node"},
+	{command: "drive +star-remove", emitted: "doc-id", canonical: "node"},
+	{command: "drive +stats", emitted: "document-url", canonical: "node"},
+	{command: "drive +upload", emitted: "file-id", canonical: "node"},
+}
+
+// paramAliasNewDriveConfirmationCases selects one newly reviewed alias for
+// every Drive command in the expansion whose declared runtime safety requires
+// confirmation. The full matrix below proves all spellings preserve the
+// confirmed payload; this smaller matrix proves aliases cannot cross the
+// confirmation boundary before any transport call is made.
+var paramAliasNewDriveConfirmationCases = []struct {
+	command   string
+	emitted   string
+	canonical string
+}{
+	{command: "drive +delete", emitted: "file-id", canonical: "node"},
+	{command: "drive +publish-unset", emitted: "document-url", canonical: "node"},
+	{command: "drive +recycle-restore", emitted: "recycle-item-id", canonical: "id"},
+	{command: "drive +rename", emitted: "new-name", canonical: "name"},
+	{command: "drive +upload", emitted: "source-file", canonical: "file"},
+	{command: "drive +version-revert", emitted: "version-number", canonical: "version"},
+}
+
 // paramAliasRepresentativePayloadCases keeps final transport coverage across
 // old concept aliases, command overrides, native compatibility flags, read and
 // write commands, and different products. Every reviewed alias is still
 // checked through the embedded PreParse delivery path and against a complete
-// business-valid command template. The separate IM gate below continues to
-// execute every alias introduced by the current IM optimization.
+// business-valid command template. The dedicated product gates below continue
+// to execute every alias introduced by the reviewed IM and Drive expansions.
 //
 // Keeping the older 100+ aliases at the contract layer avoids rebuilding and
 // executing the complete 800+ command Root twice per spelling under -race.
@@ -261,6 +410,7 @@ var paramAliasRepresentativePayloadCases = map[string]bool{
 	paramAliasPayloadCaseKey("devdoc article search", "current-page"):                true, // command override
 	paramAliasPayloadCaseKey("doc +comment-create", "body"):                          true, // write shortcut content alias
 	paramAliasPayloadCaseKey("doc +copy", "parent-folder-id"):                        true, // Doc folder role on a write shortcut
+	paramAliasPayloadCaseKey("doc create", "space-id"):                               true, // published Doc workspace compatibility remains payload-equivalent
 	paramAliasPayloadCaseKey("doc +create", "content-format"):                        true, // shortcut format alias preserves markdown/jsonml enum
 	paramAliasPayloadCaseKey("doc +create-from-template", "keyword"):                 true, // template search alias composes with a write workflow
 	paramAliasPayloadCaseKey("doc +create-from-template", "workspace-id"):            true, // template target workspace identifier
@@ -269,6 +419,8 @@ var paramAliasRepresentativePayloadCases = map[string]bool{
 	paramAliasPayloadCaseKey("doc +fetch", "start-block"):                            true, // section boundary role remains exact
 	paramAliasPayloadCaseKey("doc +history-revert", "version-number"):                true, // destructive history version alias keeps confirmation
 	paramAliasPayloadCaseKey("doc +inspect", "include-versions"):                     true, // boolean section alias preserves value
+	paramAliasPayloadCaseKey("doc +search", "create-time-start"):                     true, // observed lower-bound spelling preserves milliseconds
+	paramAliasPayloadCaseKey("doc +search", "create-time-end"):                       true, // observed upper-bound spelling preserves milliseconds
 	paramAliasPayloadCaseKey("doc +template-list", "next-token"):                     true, // Doc cursor alias on a read shortcut
 	paramAliasPayloadCaseKey("doc +update", "mode"):                                  true, // write operation selector alias
 	paramAliasPayloadCaseKey("doc +update", "revision"):                              true, // optimistic edit revision alias
@@ -278,6 +430,7 @@ var paramAliasRepresentativePayloadCases = map[string]bool{
 	paramAliasPayloadCaseKey("doc block insert", "parent-block-id"):                  true, // scoped block-role alias
 	paramAliasPayloadCaseKey("doc comment delete", "comment-id"):                     true, // destructive comment-key alias
 	paramAliasPayloadCaseKey("doc comment reply", "mentioned-open-conversation-ids"): true, // list-valued group mention role
+	paramAliasPayloadCaseKey("drive info", "workspace"):                              true, // published numeric storage-space compatibility remains payload-equivalent
 	paramAliasPayloadCaseKey("mail folder update", "folder-id"):                      true, // write-command identifier alias
 	paramAliasPayloadCaseKey("report list", "from-date"):                             true, // date-range concept alias
 }
@@ -421,14 +574,118 @@ func TestCrossPlatformCoverageNewIMParamAliasesReachCanonicalEquivalentFinalPayl
 	}
 }
 
-// Resource download deliberately continues from the transport call into a
-// local HTTPS download. The generic capture caller returns an empty object, so
-// this command's stable post-transport validation error is the expected test
-// boundary; canonical and alias calls must still produce the same request and
-// the same error.
+func TestCrossPlatformCoverageNewDriveParamAliasesReachCanonicalEquivalentFinalPayloads(t *testing.T) {
+	activeAliases := 0
+	for _, test := range paramAliasNewDriveCases {
+		test := test
+		t.Run(test.command+"/"+test.emitted, func(t *testing.T) {
+			complete, ok := paramAliasCompleteCommand(test.command, test.canonical)
+			if !ok {
+				t.Fatal("reviewed Drive alias has no complete-command E2E template")
+			}
+			canonicalArgs := append([]string(nil), complete...)
+			aliasArgs, replacements := replaceLongFlag(canonicalArgs, test.canonical, test.emitted)
+			if replacements != 1 {
+				t.Fatalf("complete command must contain canonical --%s exactly once; replacements=%d args=%v", test.canonical, replacements, canonicalArgs)
+			}
+
+			canonicalCaller := &paramAliasCaptureCaller{}
+			_, canonicalErr := executeParamAliasPayloadE2E(t, canonicalCaller, canonicalArgs...)
+			if canonicalErr != nil && !paramAliasExpectedCaptureBoundaryError(test.command, canonicalErr) {
+				t.Fatalf("complete canonical command failed: %v\nargs=%v\ncalls=%#v", canonicalErr, canonicalArgs, canonicalCaller.calls)
+			}
+			if len(canonicalCaller.calls) == 0 {
+				t.Fatalf("complete canonical command reached no final transport payload: args=%v", canonicalArgs)
+			}
+
+			entry, exists := cli.LookupParamAlias(test.command)
+			target, active := entry.ResolveAlias(test.emitted)
+			if !exists || !active {
+				return
+			}
+			if target != test.canonical {
+				t.Fatalf("active reviewed Drive alias --%s resolves to --%s, want --%s", test.emitted, target, test.canonical)
+			}
+			activeAliases++
+
+			aliasCaller := &paramAliasCaptureCaller{}
+			ctx, aliasErr := executeParamAliasPayloadE2E(t, aliasCaller, aliasArgs...)
+			if aliasErr != nil && !paramAliasExpectedCaptureBoundaryError(test.command, aliasErr) {
+				t.Fatalf("complete alias command failed: %v\nargs=%v\ncalls=%#v", aliasErr, aliasArgs, aliasCaller.calls)
+			}
+			if ctx == nil {
+				t.Fatal("complete alias command skipped PreParse")
+			}
+			if (canonicalErr == nil) != (aliasErr == nil) || (canonicalErr != nil && canonicalErr.Error() != aliasErr.Error()) {
+				t.Fatalf("canonical and alias completion errors differ: canonical=%v alias=%v", canonicalErr, aliasErr)
+			}
+			if !reflect.DeepEqual(aliasCaller.calls, canonicalCaller.calls) {
+				t.Fatalf("final transport calls differ\ncanonical args: %v\nalias args: %v\ncanonical calls: %#v\nalias calls: %#v", canonicalArgs, aliasArgs, canonicalCaller.calls, aliasCaller.calls)
+			}
+		})
+	}
+	if activeAliases != len(paramAliasNewDriveCases) {
+		t.Fatalf("new Drive aliases active in embedded table = %d, want %d", activeAliases, len(paramAliasNewDriveCases))
+	}
+}
+
+func TestCrossPlatformCoverageNewDriveParamAliasesCannotBypassConfirmation(t *testing.T) {
+	for _, test := range paramAliasNewDriveConfirmationCases {
+		test := test
+		t.Run(test.command+"/"+test.emitted, func(t *testing.T) {
+			complete, ok := paramAliasCompleteCommand(test.command, test.canonical)
+			if !ok {
+				t.Fatal("reviewed Drive confirmation alias has no complete-command E2E template")
+			}
+			aliasArgs, replacements := replaceLongFlag(complete, test.canonical, test.emitted)
+			if replacements != 1 {
+				t.Fatalf("complete command must contain canonical --%s exactly once; replacements=%d args=%v", test.canonical, replacements, complete)
+			}
+			unconfirmedArgs, removals := removeExactArg(aliasArgs, "--yes")
+			if removals != 1 {
+				t.Fatalf("confirmation template must contain --yes exactly once; removals=%d args=%v", removals, aliasArgs)
+			}
+
+			entry, exists := cli.LookupParamAlias(test.command)
+			target, active := entry.ResolveAlias(test.emitted)
+			if !exists || !active || target != test.canonical {
+				t.Fatalf("reviewed Drive alias --%s resolution = exists:%v active:%v target:%q, want --%s", test.emitted, exists, active, target, test.canonical)
+			}
+
+			caller := &paramAliasCaptureCaller{}
+			ctx, err := executeParamAliasPayloadE2E(t, caller, unconfirmedArgs...)
+			if ctx == nil {
+				t.Fatal("unconfirmed alias command skipped PreParse")
+			}
+			var appErr *apperrors.Error
+			if !errors.As(err, &appErr) || appErr.Reason != "confirmation_required" {
+				t.Fatalf("unconfirmed alias command error = %#v, want confirmation_required\nargs=%v", err, unconfirmedArgs)
+			}
+			if len(caller.calls) != 0 {
+				t.Fatalf("unconfirmed alias command crossed the transport boundary: args=%v calls=%#v", unconfirmedArgs, caller.calls)
+			}
+		})
+	}
+}
+
+// Some artifact commands deliberately continue past the final captured
+// transport call into local download/upload handling. Deterministic invalid
+// resource responses form their expected post-transport test boundary;
+// canonical and alias calls must still produce the same request and error.
 func paramAliasExpectedCaptureBoundaryError(command string, err error) bool {
-	return command == "chat +messages-resource-download" && err != nil &&
-		strings.Contains(err.Error(), "资源下载接口未返回合法的 HTTPS 下载地址")
+	if err == nil {
+		return false
+	}
+	switch command {
+	case "chat +messages-resource-download":
+		return strings.Contains(err.Error(), "资源下载接口未返回合法的 HTTPS 下载地址")
+	case "drive +download", "drive +version-download":
+		return strings.Contains(err.Error(), "下载地址必须是受信任域名上的 HTTPS URL")
+	case "drive +upload":
+		return strings.Contains(err.Error(), "incomplete drive upload credentials")
+	default:
+		return false
+	}
 }
 
 // +chat-messages supplies the current wall-clock time when callers omit
@@ -483,3 +740,16 @@ func replaceLongFlag(args []string, canonical, emitted string) ([]string, int) {
 	}
 	return out, replacements
 }
+
+func removeExactArg(args []string, target string) ([]string, int) {
+	out := make([]string, 0, len(args))
+	removals := 0
+	for _, arg := range args {
+		if arg == target {
+			removals++
+			continue
+		}
+		out = append(out, arg)
+	}
+	return out, removals
+}

internal/app/pat_auth_retry_test.go

@@ -30,6 +30,7 @@ import (
 	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/executor"
 	"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/agentproduct"
 )
 
@@ -218,8 +219,16 @@ func TestPatScopeError_Error(t *testing.T) {
 // /cli/oauth/device/poll?flowId=<fid> with the given status sequence.
 // It also writes the server URL into a temp DWS_CONFIG_DIR/mcp_url so that
 // GetMCPBaseURL() returns the test server address.
+func stubPATPollAccessToken(t *testing.T) {
+	t.Helper()
+	testseam.Swap(t, &patResolveAccessToken, func(context.Context, string, string) (string, error) {
+		return "", authpkg.ErrTokenDataNotFound
+	})
+}
+
 func setupPollServer(t *testing.T, statuses []authpkg.DevicePollResponse) (*httptest.Server, string) {
 	t.Helper()
+	stubPATPollAccessToken(t)
 	var callCount atomic.Int32
 
 	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
@@ -381,6 +390,7 @@ func TestPollPatDeviceFlow_ServerErrorFallback(t *testing.T) {
 }
 
 func TestPollPatDeviceFlow_RedirectSkipped(t *testing.T) {
+	stubPATPollAccessToken(t)
 	// When server returns 302 (SSO redirect), poll should continue until real response.
 	var callCount int32
 	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
@@ -540,6 +550,7 @@ func (m *mockRunner) Run(ctx context.Context, inv executor.Invocation) (executor
 // It responds to device poll requests with the given status after the first poll.
 func setupHandlePATServer(t *testing.T, terminalStatus string, authCode string) (*httptest.Server, string) {
 	t.Helper()
+	stubPATPollAccessToken(t)
 	var pollCount atomic.Int32
 
 	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {

internal/app/root.go

@@ -79,6 +79,7 @@ var (
 	rootPluginSyncSkills            = plugin.SyncSkills
 	rootAuthLoadTokenData           = authpkg.LoadTokenData
 	rootNewCommandRunnerWithFlags   = newCommandRunnerWithFlags
+	rootEmitResult                  = output.EmitResult
 )
 
 // Execute runs the root command and returns the process exit code.
@@ -136,6 +137,16 @@ func Execute() (exitCode int) {
 	restoreArgs := rootNormalizeProcessProfileArgs()
 	defer restoreArgs()
 
+	// Validate MCP Agent metadata before constructing the command tree.
+	// Construction may invoke edition registration/static-server hooks and load
+	// plugin PreParse handlers, so PersistentPreRunE alone is too late for the
+	// process entry point. Retain this exact pair for the eventual invocation.
+	agentMetadata := readAgentMetadataSnapshot()
+	if err := agentMetadata.validationError(); err != nil {
+		emitEarlyAgentMetadataValidationError(err, os.Args[1:])
+		return apperrors.ExitCode(err)
+	}
+
 	timing := NewTimingCollector()
 	defer func() {
 		rootStopAllStdioClients() // Ensure child processes are terminated on exit
@@ -147,6 +158,7 @@ func Execute() (exitCode int) {
 
 	// Attach timing collector to context for use by child components
 	ctx := WithTimingCollector(context.Background(), timing)
+	ctx = contextWithAgentMetadataSnapshot(ctx, agentMetadata)
 	ctx, resultStore = output.WithResultStore(ctx)
 	var signalState *processSignalState
 	var stopSignals func()
@@ -260,6 +272,70 @@ func Execute() (exitCode int) {
 	return 0
 }
 
+// emitEarlyAgentMetadataValidationError preserves each built-in command's
+// legacy-vs-unified output contract without running extension hooks. The
+// presentation-only tree contains reviewed open-source commands and flags but
+// deliberately omits edition registration, plugin loading, and visibility
+// hooks; callers therefore still fail before any external hook executes.
+func emitEarlyAgentMetadataValidationError(err error, args []string) {
+	format := processArgsFormat(args)
+	presentationRoot := newRootPresentationCommand()
+	_ = presentationRoot.PersistentFlags().Set("format", format)
+	if target, _, findErr := presentationRoot.Find(args); findErr == nil && target != nil && output.UsesUnifiedResult(target) {
+		target.SetOut(os.Stdout)
+		target.SetErr(os.Stderr)
+		result := output.FailureWithExitCode(errorInfoFromExecutionError(err), apperrors.ExitCode(err))
+		if _, emitErr := rootEmitResult(target, result); emitErr == nil {
+			return
+		}
+	}
+	if strings.EqualFold(strings.TrimSpace(format), "json") {
+		_ = apperrors.PrintJSON(os.Stderr, err)
+		return
+	}
+	_ = apperrors.PrintHumanAt(os.Stderr, err, apperrors.VerbosityNormal)
+}
+
+// processArgsRequestJSON preserves the CLI's machine-readable error contract
+// for validation that must occur before Cobra and its presentation flags exist.
+// The global format defaults to JSON; an explicit non-JSON format switches to
+// the human diagnostic path. Last occurrence wins, matching pflag semantics.
+func processArgsRequestJSON(args []string) bool {
+	return strings.EqualFold(strings.TrimSpace(processArgsFormat(args)), "json")
+}
+
+func processArgsFormat(args []string) string {
+	format := "json"
+	for index := 0; index < len(args); index++ {
+		arg := args[index]
+		if arg == "--" {
+			break
+		}
+		if value, ok := strings.CutPrefix(arg, "--format="); ok {
+			format = value
+			continue
+		}
+		if value, ok := strings.CutPrefix(arg, "-f="); ok {
+			format = value
+			continue
+		}
+		if strings.HasPrefix(arg, "-f") && len(arg) > len("-f") {
+			format = strings.TrimPrefix(arg, "-f")
+			continue
+		}
+		if arg != "--format" && arg != "-f" {
+			continue
+		}
+		if index+1 >= len(args) {
+			format = ""
+			break
+		}
+		index++
+		format = args[index]
+	}
+	return format
+}
+
 // errorInfoFromExecutionError projects the repository error model into the unified
 // failure body. Exit code and category are derived from the same error value,
 // preventing the wire and process status from drifting apart.
@@ -633,12 +709,25 @@ func NewRootCommandWithEngine(rootCtx context.Context, engine *pipeline.Engine)
 }
 
 func newRootCommandWithEngine(rootCtx context.Context, engine *pipeline.Engine, loadRuntimeExtensions bool, declarationOnly bool) *cobra.Command {
+	return newRootCommandWithMode(rootCtx, engine, loadRuntimeExtensions, declarationOnly, false)
+}
+
+func newRootPresentationCommand() *cobra.Command {
+	return newRootCommandWithMode(context.Background(), nil, false, true, true)
+}
+
+func newRootCommandWithMode(rootCtx context.Context, engine *pipeline.Engine, loadRuntimeExtensions bool, declarationOnly bool, presentationOnly bool) *cobra.Command {
 	if rootCtx == nil {
 		rootCtx = context.Background()
 	}
 	flags := &GlobalFlags{}
 	authpkg.SetRuntimeProfile(preparseProfileFlag(os.Args[1:]))
 	runner := rootNewCommandRunnerWithFlags(flags)
+	if snapshot, ok := agentMetadataSnapshotFromContext(rootCtx); ok {
+		if runtime, ok := runner.(*runtimeRunner); ok {
+			runtime.agentMetadata = &snapshot
+		}
+	}
 
 	root := &cobra.Command{
 		Use:               "dws",
@@ -672,15 +761,29 @@ func newRootCommandWithEngine(rootCtx context.Context, engine *pipeline.Engine,
 			// --output sink instead opens at Run entry (after Cobra's own
 			// validation), so validation failures still cannot strand a
 			// temporary file.
-			// Validate caller-provided identity labels before any edition hook
-			// or command network activity can run. Header-only library callers
-			// use the best-effort path in resolveIdentityHeaders instead.
+			// Validate caller-provided identity and MCP metadata before command
+			// execution hooks or network activity. The process entry point additionally
+			// validates Agent metadata before command-tree construction; direct Cobra
+			// embedding retains this execution-boundary guard.
 			if _, err := parseAgentHost(os.Getenv(envDWSAgentHost)); err != nil {
 				return err
 			}
 			if _, err := parseAgentProduct(os.Getenv(agentproduct.EnvName)); err != nil {
 				return err
 			}
+			agentMetadata, cached := agentMetadataSnapshotFromContext(cmd.Context())
+			if !cached {
+				agentMetadata = readAgentMetadataSnapshot()
+			}
+			if err := agentMetadata.validationError(); err != nil {
+				return err
+			}
+			if runtime, ok := runner.(*runtimeRunner); ok {
+				// Retain the exact validated pair for this command execution so a
+				// concurrently mutating embedding environment cannot change what is
+				// later applied after edition and credential hooks.
+				runtime.agentMetadata = &agentMetadata
+			}
 			if shouldDetectNestedSkillLayout(cmd) {
 				if found, err := detectNestedMultiSkillLayout(); err == nil && found {
 					fmt.Fprintln(cmd.ErrOrStderr(), "⚠️  检测到旧升级器留下的嵌套 Skill；请运行 dws skill setup --mode multi 查看迁移计划并确认")
@@ -777,10 +880,12 @@ func newRootCommandWithEngine(rootCtx context.Context, engine *pipeline.Engine,
 	// PAT authorization commands (open-source core)
 	pat.RegisterCommands(root, patCaller)
 
-	if fn := edition.Get().RegisterExtraCommands; fn != nil {
-		caller := newToolCallerAdapter(runner, flags)
-		fn(root, caller)
-		deduplicateCommands(root)
+	if !presentationOnly {
+		if fn := edition.Get().RegisterExtraCommands; fn != nil {
+			caller := newToolCallerAdapter(runner, flags)
+			fn(root, caller)
+			deduplicateCommands(root)
+		}
 	}
 	if loadRuntimeExtensions {
 		// Resolve plugins only after the complete distribution command tree is
@@ -791,7 +896,9 @@ func newRootCommandWithEngine(rootCtx context.Context, engine *pipeline.Engine,
 			addPluginCommandsSafe(root, pluginCmds)
 		}
 	}
-	hideNonDirectRuntimeCommands(root)
+	if !presentationOnly {
+		hideNonDirectRuntimeCommands(root)
+	}
 	configureRootHelp(root)
 	// Set custom flag error handler for better UX
 	root.SetFlagErrorFunc(flagErrorWithSuggestions)
@@ -1755,17 +1862,16 @@ func distributionRootOwns(root *cobra.Command, name string) bool {
 func registerPluginHTTPServer(srv mcptypes.ServerDescriptor) {
 	AppendDynamicServer(srv)
 	productID := firstNonEmptyPluginString(srv.CLI.ID, srv.Key)
-	ClearPluginAuth(productID)
-	if len(srv.AuthHeaders) > 0 {
-		registerPluginAuthFromHeaders(srv)
-	}
+	// Register ownership for every accepted HTTP plugin, including anonymous
+	// plugins. Execution must never fall back to the built-in DingTalk OAuth or
+	// Agent-metadata path merely because a plugin has no Authorization Header.
+	RegisterPluginAuth(productID, pluginAuthFromServerDescriptor(srv))
 }
 
-// registerPluginAuthFromHeaders extracts authentication credentials from
-// a server descriptor's AuthHeaders and registers them in the global
-// PluginAuth registry. The runner uses this registry at execution time
-// to inject the correct Bearer token for third-party MCP servers.
-func registerPluginAuthFromHeaders(srv mcptypes.ServerDescriptor) {
+// pluginAuthFromServerDescriptor extracts plugin-owned credentials and custom
+// Headers. A non-nil result also acts as the HTTP plugin ownership marker for
+// anonymous plugins.
+func pluginAuthFromServerDescriptor(srv mcptypes.ServerDescriptor) *PluginAuth {
 	authToken := ""
 	extraHeaders := make(map[string]string)
 	for key, value := range srv.AuthHeaders {
@@ -1776,20 +1882,18 @@ func registerPluginAuthFromHeaders(srv mcptypes.ServerDescriptor) {
 			extraHeaders[key] = value
 		}
 	}
-	if authToken == "" {
-		return
-	}
 	var trustedDomains []string
 	if parsed, err := url.Parse(srv.Endpoint); err == nil {
 		host := parsed.Hostname()
-		trustedDomains = []string{host, "*." + host}
+		if host != "" {
+			trustedDomains = []string{host, "*." + host}
+		}
 	}
-	productID := firstNonEmptyPluginString(srv.CLI.ID, srv.Key)
-	RegisterPluginAuth(productID, &PluginAuth{
+	return &PluginAuth{
 		Token:          authToken,
 		ExtraHeaders:   extraHeaders,
 		TrustedDomains: trustedDomains,
-	})
+	}
 }
 
 // newPipelineEngine creates and configures the pipeline engine with

internal/app/root_help_test.go

@@ -22,6 +22,7 @@ import (
 	"strings"
 	"testing"
 
+	"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"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition"
@@ -369,6 +370,20 @@ func TestChatFileUploadDownlinedButMessageFileSendStays(t *testing.T) {
 			t.Fatalf("chat message send missing --%s", flag)
 		}
 	}
+	idempotencyKey := send.Flags().Lookup("idempotency-key")
+	if idempotencyKey == nil {
+		t.Fatal("chat message send missing --idempotency-key")
+	}
+	legacyUUID := send.Flags().Lookup("uuid")
+	if legacyUUID == nil || !legacyUUID.Hidden {
+		t.Fatalf("chat message send --uuid hidden = %#v, want hidden compatibility flag", legacyUUID)
+	}
+	if got := legacyUUID.Annotations[runtimeannotate.AnnotationFlagAliasOf]; len(got) != 1 || got[0] != "idempotency-key" {
+		t.Fatalf("chat message send --uuid alias_of = %#v, want idempotency-key", got)
+	}
+	if got := legacyUUID.Annotations[runtimeannotate.AnnotationFlagAliasOrigin]; len(got) != 1 || got[0] != runtimeannotate.FlagAliasOriginCorecmdV1 {
+		t.Fatalf("chat message send --uuid alias_origin = %#v, want %s", got, runtimeannotate.FlagAliasOriginCorecmdV1)
+	}
 
 	got, err := executeRootCaptureStdout(t, []string{
 		"chat", "file", "upload",

internal/app/runner.go

@@ -137,7 +137,6 @@ func newCommandRunnerWithFlags(flags *GlobalFlags) executor.Runner {
 		httpClient = &http.Client{Timeout: time.Duration(flags.Timeout) * time.Second}
 	}
 	transportClient := transport.NewClient(httpClient)
-	transportClient.ExtraHeaders = resolveIdentityHeaders()
 	transportClient.FileLogger = FileLoggerInstance()
 	return &runtimeRunner{
 		transport:          transportClient,
@@ -156,12 +155,14 @@ type runtimeRunner struct {
 	enforceContentScan bool
 	includeScanReport  bool
 	auditSink          audit.Sink
+	agentMetadata      *agentMetadataSnapshot
 }
 
 var (
 	runnerResolveMultiProfileSelections = resolveMultiProfileSelections
 	runnerResolveProfile                = authpkg.ResolveProfile
 	runnerGetCachedRuntimeToken         = getCachedRuntimeToken
+	runnerResolveAuthToken              = (*runtimeRunner).resolveAuthToken
 	runnerPreflightDocDownload          = (*runtimeRunner).preflightDocDownload
 	runnerCallTool                      = (*transport.Client).CallTool
 	runnerStdioEnsureInitialized        = (*transport.StdioClient).EnsureInitialized
@@ -237,7 +238,6 @@ func (r *runtimeRunner) runSingle(ctx context.Context, invocation executor.Invoc
 	if r.transport == nil {
 		return r.fallback.Run(ctx, invocation)
 	}
-	r.transport.ExtraHeaders = resolveIdentityHeaders()
 
 	// Mock mode: skip endpoint resolution, use a placeholder endpoint.
 	if r.globalFlags != nil && r.globalFlags.Mock {
@@ -543,9 +543,9 @@ func (r *runtimeRunner) executeInvocation(ctx context.Context, endpoint string,
 		emitAudit(auditSink, execID, invokeStart, invocation, endpoint, retErr, version)
 	}()
 
-	// Check if this product has plugin-level auth credentials registered.
-	// If so, use the plugin's token instead of the default DingTalk OAuth token.
-	// This allows third-party MCP servers (e.g. Bailian) to use their own API keys.
+	// Check whether this product belongs to an HTTP plugin. Every accepted
+	// plugin has an ownership record; credentials within that record are
+	// optional. Plugin requests never fall back to the default DingTalk OAuth.
 	pluginAuth, hasPluginAuth := LookupPluginAuth(invocation.CanonicalProduct)
 
 	authToken := ""
@@ -553,7 +553,7 @@ func (r *runtimeRunner) executeInvocation(ctx context.Context, endpoint string,
 		authToken = pluginAuth.Token
 	} else if !invocation.DryRun && (r.globalFlags == nil || !r.globalFlags.Mock) {
 		var tokenErr error
-		authToken, tokenErr = r.resolveAuthToken(ctx)
+		authToken, tokenErr = runnerResolveAuthToken(r, ctx)
 		if tokenErr != nil {
 			return executor.Result{}, tokenResolutionError(tokenErr)
 		}
@@ -603,9 +603,10 @@ func (r *runtimeRunner) executeInvocation(ctx context.Context, endpoint string,
 		}, nil
 	}
 
-	// Fail-fast: reject unauthenticated requests before making network calls.
-	// This provides a clear error message instead of cryptic HTTP 400 from MCP.
-	if strings.TrimSpace(authToken) == "" {
+	// Preserve a final execution-boundary guard even though the built-in token
+	// resolver normally returns either a non-empty token or an error. HTTP
+	// plugins are ownership-scoped separately and may intentionally be anonymous.
+	if !hasPluginAuth && strings.TrimSpace(authToken) == "" {
 		return executor.Result{}, apperrors.NewAuth(
 			"未登录，请先执行 dws auth login",
 			apperrors.WithReason("not_authenticated"),
@@ -616,12 +617,20 @@ func (r *runtimeRunner) executeInvocation(ctx context.Context, endpoint string,
 
 	var tc *transport.Client
 	if hasPluginAuth {
-		// Use plugin-level auth: inject the plugin's token and trust its domains.
-		tc = r.transport.WithAuth(authToken, pluginAuth.ExtraHeaders)
+		// Plugin ownership is authoritative even when the plugin is anonymous.
+		// Copy and sanitize manifest headers so plugins cannot opt themselves into
+		// DWS-owned Agent metadata by declaring the reserved names directly.
+		tc = r.transport.WithAuth(authToken, pluginRequestHeaders(pluginAuth))
 		tc.TrustedDomains = pluginAuth.TrustedDomains
 	} else {
-		// Default path: use DingTalk OAuth token with identity headers.
-		tc = r.transport.WithAuth(authToken, resolveIdentityHeaders())
+		// Default path: use DingTalk OAuth token with identity headers. Agent
+		// metadata is resolved exactly once per invocation and is excluded from
+		// helper-only service-discovery requests.
+		if r.agentMetadata != nil {
+			tc = r.transport.WithAuth(authToken, resolveMCPRequestHeadersForInvocation(invocation, *r.agentMetadata))
+		} else {
+			tc = r.transport.WithAuth(authToken, resolveMCPRequestHeadersForInvocation(invocation))
+		}
 	}
 
 	callCtx := ctx
@@ -1069,6 +1078,10 @@ func resolveIdentityHeaders() map[string]string {
 	} else {
 		delete(headers, agentproduct.HeaderName)
 	}
+	// Agent version and extension are intentionally MCP-request-only. Remove
+	// every case variant potentially supplied by an edition or credential hook
+	// so shared consumers such as A2A cannot inherit them.
+	removeAgentMetadataHeaders(headers)
 	return headers
 }
 

internal/app/testmain_test.go

@@ -83,6 +83,10 @@ func TestMain(m *testing.M) {
 	// remove a TempDir while the audit lock is still open.
 	setupAuditSink()
 	openBrowserFunc = func(string) error { return nil }
+	// App tests may run in filtered CI processes. Install the same lazy Schema
+	// source factory as NewRootCommand without constructing a root so ResolveMeta
+	// tests never depend on an earlier test having initialized process state.
+	registerSchemaRuntimeDelivery()
 	code := m.Run()
 	StopAllStdioClients()
 	CloseAuditSink()

internal/auth/agent_metadata_headers_test.go

@@ -0,0 +1,80 @@
+// 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 (
+	"context"
+	"io"
+	"net/http"
+	"strings"
+	"testing"
+)
+
+type agentMetadataHeaderRoundTripFunc func(*http.Request) (*http.Response, error)
+
+func (f agentMetadataHeaderRoundTripFunc) RoundTrip(req *http.Request) (*http.Response, error) {
+	return f(req)
+}
+
+func TestCrossPlatformCoverageOAuthRequestsExcludeAgentMetadataHeaders(t *testing.T) {
+	t.Setenv("DWS_AGENT_VER", "1.2.3-test")
+	t.Setenv("DWS_AGENT_EXT", `{"umt":"test-umt","miniwua":"test-wua","ua":"test-agent"}`)
+
+	assertExcluded := func(t *testing.T, header http.Header) {
+		t.Helper()
+		for _, name := range []string{"x-dws-agent-ver", "x-dws-agent-ext"} {
+			if values := header.Values(name); len(values) != 0 {
+				t.Fatalf("OAuth request header %q = %q, want absent", name, values)
+			}
+		}
+	}
+
+	newCaptureClient := func(responseBody string) (*http.Client, <-chan http.Header) {
+		seen := make(chan http.Header, 1)
+		client := &http.Client{Transport: agentMetadataHeaderRoundTripFunc(func(req *http.Request) (*http.Response, error) {
+			seen <- req.Header.Clone()
+			return &http.Response{
+				StatusCode: http.StatusOK,
+				Header:     http.Header{"Content-Type": {"application/json"}},
+				Body:       io.NopCloser(strings.NewReader(responseBody)),
+				Request:    req,
+			}, nil
+		})}
+		return client, seen
+	}
+
+	t.Run("JSON token request", func(t *testing.T) {
+		client, seen := newCaptureClient(`{}`)
+		provider := &OAuthProvider{httpClient: client}
+		if _, err := provider.postJSON(context.Background(), "https://oauth.test/token", map[string]string{
+			"code":      "test-code",
+			"grantType": "authorization_code",
+		}); err != nil {
+			t.Fatalf("postJSON() error = %v", err)
+		}
+		assertExcluded(t, <-seen)
+	})
+
+	t.Run("device code request", func(t *testing.T) {
+		client, seen := newCaptureClient(`{"success":true,"result":{"deviceCode":"test-device-code","userCode":"TEST-CODE","verificationUri":"https://example.test/device","expiresIn":900,"interval":1}}`)
+		provider := NewDeviceFlowProvider(t.TempDir(), newDeviceFlowTestLogger())
+		provider.clientID = "test-client-id"
+		provider.httpClient = client
+		provider.SetBaseURL("https://oauth.test")
+		if _, err := provider.requestDeviceCode(context.Background()); err != nil {
+			t.Fatalf("requestDeviceCode() error = %v", err)
+		}
+		assertExcluded(t, <-seen)
+	})
+}

internal/cli/param_aliases_test.go

@@ -515,3 +515,68 @@ func TestGeneratedParamAliasesAreWellFormed(t *testing.T) {
 		}
 	}
 }
+
+func TestCrossPlatformCoveragePublishedSpaceWorkspaceAliasesRemainExecutable(t *testing.T) {
+	docCommands := []string{
+		"doc +access-change",
+		"doc +access-grant",
+		"doc +access-revoke",
+		"doc +copy",
+		"doc +create",
+		"doc +create-from-template",
+		"doc +grant-and-share",
+		"doc +import",
+		"doc +list",
+		"doc +move",
+		"doc create",
+		"doc file create",
+		"doc import",
+		"doc template apply",
+	}
+	for _, command := range docCommands {
+		entry, ok := LookupParamAlias(command)
+		if !ok {
+			t.Errorf("published Doc command %q has no generated parameter-alias entry", command)
+			continue
+		}
+		for _, emitted := range []string{"space", "space-id"} {
+			target, active := entry.ResolveAlias(emitted)
+			if !active || target != "workspace" {
+				t.Errorf("%s --%s resolution = active:%v target:%q, want --workspace", command, emitted, active, target)
+			}
+			if entry.IsBlocked(emitted) || entry.IsAmbiguous(emitted) {
+				t.Errorf("%s --%s remains protected after restoring its published alias", command, emitted)
+			}
+		}
+	}
+
+	driveInfo, ok := LookupParamAlias("drive info")
+	if !ok {
+		t.Fatal("published drive info command has no generated parameter-alias entry")
+	}
+	for _, emitted := range []string{"space", "workspace", "workspace-id"} {
+		target, active := driveInfo.ResolveAlias(emitted)
+		if !active || target != "space-id" {
+			t.Errorf("drive info --%s resolution = active:%v target:%q, want --space-id", emitted, active, target)
+		}
+		if driveInfo.IsBlocked(emitted) || driveInfo.IsAmbiguous(emitted) {
+			t.Errorf("drive info --%s remains protected after restoring its published alias", emitted)
+		}
+	}
+
+	// Compatibility remains exact-path scoped. Strong type spellings introduced
+	// after the split continue to guard the two value domains elsewhere.
+	for _, test := range []struct {
+		command string
+		emitted string
+	}{
+		{command: "doc create", emitted: "storage-space-id"},
+		{command: "drive +upload", emitted: "workspace-id"},
+		{command: "drive info", emitted: "knowledge-base-id"},
+	} {
+		entry, ok := LookupParamAlias(test.command)
+		if !ok || !entry.IsBlocked(test.emitted) {
+			t.Errorf("%s --%s must remain blocked outside the published compatibility set", test.command, test.emitted)
+		}
+	}
+}

internal/cli/param_concepts.json

@@ -10,10 +10,10 @@
   },
 
   "concepts": {
-    "search_query": {"denotes": "search keyword string", "canonical_hint": "query", "members": ["query", "keyword", "keywords", "q", "search-word"], "excludes": ["name", "subject", "text", "title"], "commands": ["aitable +base-search", "contact +dept-members", "contact +resolve-dept", "contact +search-user", "doc +create-from-template", "doc +find-doc", "doc +search", "doc +template-search", "doc template search", "mail +find-mail-user", "mail user search", "oa +search-forms", "oa approval search-forms"], "risk": "green"},
-    "pagination_size": {"denotes": "returned item count upper bound", "canonical_hint": "limit", "members": ["limit", "size", "page-size", "max-results", "max-result", "take", "top", "per-page"], "excludes": ["count", "page", "cursor"], "commands": ["aitable record query", "calendar event list", "chat message list", "devdoc article search", "doc +comment-list", "doc +find-doc", "doc +list", "doc +search", "doc +template-list", "doc +template-search", "doc +version-list", "doc comment list", "doc template list", "doc template search", "doc version list", "mail thread list", "oa +list-executed"], "risk": "green"},
+    "search_query": {"denotes": "search keyword string", "canonical_hint": "query", "members": ["query", "keyword", "keywords", "q", "search-word"], "excludes": ["name", "subject", "text", "title"], "commands": ["aitable +base-search", "contact +dept-members", "contact +resolve-dept", "contact +search-user", "doc +create-from-template", "doc +find-doc", "doc +search", "doc +template-search", "doc template search", "drive +find-file", "drive +search", "drive +search-docs", "drive search", "mail +find-mail-user", "mail user search", "oa +search-forms", "oa approval search-forms"], "risk": "green"},
+    "pagination_size": {"denotes": "returned item count upper bound", "canonical_hint": "limit", "members": ["limit", "size", "page-size", "max-results", "max-result", "take", "top", "per-page"], "excludes": ["count", "page", "cursor"], "commands": ["aitable record query", "calendar event list", "chat message list", "devdoc article search", "doc +comment-list", "doc +find-doc", "doc +list", "doc +search", "doc +template-list", "doc +template-search", "doc +version-list", "doc comment list", "doc template list", "doc template search", "doc version list", "drive +list", "drive +recent", "drive +recycle-list", "drive +search", "drive +search-docs", "drive +star-list", "drive +version-history", "drive list", "drive list-spaces", "drive permission list", "drive recent", "drive recycle list", "drive search", "drive star list", "mail thread list", "oa +list-executed"], "risk": "green"},
     "page_number": {"denotes": "one-based page number", "canonical_hint": "page", "members": ["page", "page-no", "current-page", "page-num"], "excludes": ["cursor", "page-index", "page-size", "page-token"], "commands": ["devdoc article search"], "risk": "green"},
-    "page_cursor": {"denotes": "pagination cursor/token", "canonical_hint": "cursor", "members": ["cursor", "next-cursor", "page-token", "next-token", "next-page-token"], "excludes": ["page", "offset"], "commands": ["calendar event list", "doc +comment-list", "doc +list", "doc +search", "doc +template-list", "doc +template-search", "doc +version-list", "doc comment list", "doc template list", "doc template search", "doc version list"], "risk": "green"},
+    "page_cursor": {"denotes": "pagination cursor/token", "canonical_hint": "cursor", "members": ["cursor", "next-cursor", "page-token", "next-token", "next-page-token"], "excludes": ["page", "offset"], "commands": ["calendar event list", "doc +comment-list", "doc +list", "doc +search", "doc +template-list", "doc +template-search", "doc +version-list", "doc comment list", "doc template list", "doc template search", "doc version list", "drive +list", "drive +recent", "drive +recycle-list", "drive +search", "drive +star-list", "drive +version-history", "drive list", "drive list-spaces", "drive recent", "drive recycle list", "drive search", "drive star list"], "risk": "green"},
     "content_text": {"denotes": "text body content", "canonical_hint": "text", "members": ["text", "content", "body"], "excludes": ["title", "name"], "commands": ["doc +checkpoint-update", "doc +comment-create", "doc +comment-reply", "doc +comment-update", "doc +create", "doc +doc-append", "doc block insert", "doc block update", "doc comment create", "doc comment create-inline", "doc comment reply", "doc comment update", "doc create"], "risk": "green"},
     "time_start": {"denotes": "start time point with unchanged value format and unit", "canonical_hint": "start", "members": ["start", "start-time", "start-date", "from", "from-date", "begin", "since", "time-min", "min-time"], "excludes": ["date", "time", "end"], "commands": ["calendar event list", "chat message list-all", "report list"], "risk": "yellow"},
     "time_end": {"denotes": "end time point with unchanged value format and unit", "canonical_hint": "end", "members": ["end", "end-time", "end-date", "time-max", "max-time"], "excludes": ["date", "time", "start"], "commands": ["calendar event list"], "risk": "yellow"},
@@ -31,20 +31,31 @@
     "user_ids": {"denotes": "user id list", "canonical_hint": "user-ids", "members": ["users", "user-ids"], "excludes": ["user", "user-id", "userid", "uid", "staff-id", "at-user-ids"], "commands": ["attendance +check-result", "attendance check result", "chat +messages-batch-send-by-bot", "chat group members remove", "chat group set-admin", "chat group-mute-member", "chat message read-status", "chat message search-advanced", "chat message send-by-bot"], "risk": "yellow"},
     "open_dingtalk_ids": {"denotes": "DingTalk openDingTalkId list with unchanged element values", "canonical_hint": "open-dingtalk-ids", "members": ["open-dingtalk-ids"], "excludes": ["user", "user-id", "user-ids", "staff-id", "users"], "commands": ["chat +chat-members-get", "chat category create-smart", "chat group members list-by-ids", "chat message send-by-bot"], "risk": "yellow"},
     "ding_id": {"denotes": "DING id", "canonical_hint": "ding-id", "members": ["ding-id", "open-ding-id"], "excludes": ["id"], "commands": ["ding message receiver-status"], "risk": "yellow"},
-    "folder_id": {"denotes": "drive folder id", "canonical_hint": "folder", "members": ["folder", "folder-id"], "excludes": ["space-id"], "commands": ["drive list", "mail folder update"], "risk": "green"},
-    "space_id": {"denotes": "drive/wiki/Doc workspace id with unchanged value", "canonical_hint": "space-id", "members": ["space-id", "space", "workspace", "workspace-id"], "excludes": ["folder", "node"], "commands": ["doc +access-change", "doc +access-grant", "doc +access-revoke", "doc +copy", "doc +create", "doc +create-from-template", "doc +grant-and-share", "doc +import", "doc +list", "doc +move", "doc create", "doc file create", "doc import", "doc template apply", "drive info"], "risk": "yellow"},
+    "folder_id": {"denotes": "drive folder id", "canonical_hint": "folder", "members": ["folder", "folder-id"], "excludes": ["space-id"], "commands": ["drive +copy", "drive +create-folder", "drive +create-shortcut", "drive +list", "drive +move", "drive +upload", "drive commit", "drive copy", "drive list", "drive mkdir", "drive move", "drive shortcut", "drive upload", "drive upload-info", "mail folder update"], "risk": "green"},
+    "drive_storage_space_id": {"denotes": "single numeric DingDrive storage space ID with unchanged value", "canonical_hint": "space-id", "members": ["space-id", "drive-space-id", "storage-space-id", "dingdrive-space-id"], "excludes": ["space", "workspace", "workspace-id", "knowledge-base-id", "wiki-workspace-id"], "commands": ["drive +create-folder", "drive +download", "drive +info", "drive +inspect", "drive +list", "drive +recycle-list", "drive +upload", "drive commit", "drive download", "drive info", "drive list", "drive mkdir", "drive recycle list", "drive upload", "drive upload-info"], "risk": "yellow"},
     "app_id": {"denotes": "application id", "canonical_hint": "unified-app-id", "members": ["app-id", "unified-app-id", "application-id"], "excludes": ["app-key", "app-secret", "agent-id"], "commands": ["dev app get"], "risk": "yellow"},
     "robot_code": {"denotes": "robot code", "canonical_hint": "robot-code", "members": ["robot-code", "robot"], "excludes": ["robot-id", "bot-id", "open-bot-id", "bot-code"], "commands": ["chat +chat-add-bot", "chat +messages-batch-recall-by-bot", "chat +messages-batch-send-by-bot", "chat +messages-recall-by-bot", "chat +messages-send-by-bot", "chat group members add-bot", "chat message recall-by-bot", "chat message send-by-bot", "ding message send"], "risk": "yellow"},
     "open_bot_id": {"denotes": "single DingTalk openBotId with unchanged value", "canonical_hint": "bot-id", "members": ["bot-id", "open-bot-id"], "excludes": ["robot-code", "robot", "robot-id", "bot-code"], "commands": ["chat +chat-remove-bot", "chat group members remove-bot"], "risk": "yellow"},
-    "doc_node_id": {"denotes": "single DingTalk document nodeId or accepted document URL/token with unchanged value", "canonical_hint": "node", "members": ["node", "node-id", "doc", "doc-id", "file-id", "document-id", "url"], "excludes": ["id", "folder", "folder-id", "parent-id", "workspace", "workspace-id", "block-id", "comment-id", "comment-key", "job-id", "task-id", "template-id", "version", "revision"], "commands": ["doc +access-change", "doc +access-grant", "doc +access-revoke", "doc +background-delete", "doc +background-update", "doc +checkpoint-update", "doc +comment-create", "doc +comment-delete", "doc +comment-list", "doc +comment-reply", "doc +comment-update", "doc +copy", "doc +doc-append", "doc +export", "doc +export-submit", "doc +fetch", "doc +history-list", "doc +history-revert", "doc +history-save", "doc +inspect", "doc +move", "doc +review", "doc +version-list", "doc +version-revert", "doc +version-save", "doc block delete", "doc block insert", "doc block list", "doc block update", "doc comment create", "doc comment create-inline", "doc comment delete", "doc comment list", "doc comment reply", "doc comment update", "doc export", "doc info", "doc media download", "doc media insert", "doc media upload", "doc read", "doc style background clear", "doc style background set", "doc style cover clear", "doc style cover set", "doc style get", "doc update", "doc version list", "doc version revert", "doc version save", "doc whiteboard insert"], "risk": "yellow"},
+    "doc_node_id": {"denotes": "single DingTalk document nodeId or accepted document URL/token with unchanged value", "canonical_hint": "node", "members": ["node", "node-id", "doc", "doc-id", "file-id", "document-id", "url", "dentry-uuid"], "excludes": ["id", "folder", "folder-id", "parent-id", "workspace", "workspace-id", "block-id", "comment-id", "comment-key", "job-id", "task-id", "template-id", "version", "revision", "dentry-id", "space-id", "name", "role"], "commands": ["doc +access-change", "doc +access-grant", "doc +access-revoke", "doc +background-delete", "doc +background-update", "doc +checkpoint-update", "doc +comment-create", "doc +comment-delete", "doc +comment-list", "doc +comment-reply", "doc +comment-update", "doc +copy", "doc +doc-append", "doc +export", "doc +export-submit", "doc +fetch", "doc +history-list", "doc +history-revert", "doc +history-save", "doc +inspect", "doc +move", "doc +review", "doc +version-list", "doc +version-revert", "doc +version-save", "doc block delete", "doc block insert", "doc block list", "doc block update", "doc comment create", "doc comment create-inline", "doc comment delete", "doc comment list", "doc comment reply", "doc comment update", "doc export", "doc info", "doc media download", "doc media insert", "doc media upload", "doc read", "doc style background clear", "doc style background set", "doc style cover clear", "doc style cover set", "doc style get", "doc update", "doc version list", "doc version revert", "doc version save", "doc whiteboard insert"], "risk": "yellow"},
     "doc_comment_key": {"denotes": "single DingTalk document commentKey with unchanged value", "canonical_hint": "comment-key", "members": ["comment-key", "comment-id"], "excludes": ["id", "node", "node-id", "doc-id", "block-id"], "commands": ["doc +comment-delete", "doc +comment-reply", "doc +comment-update", "doc comment delete", "doc comment reply", "doc comment update"], "risk": "yellow"},
-    "doc_version_number": {"denotes": "single DingTalk document historical version number with unchanged integer value", "canonical_hint": "version", "members": ["version", "version-number", "version-no"], "excludes": ["revision", "id", "node", "node-id", "doc-id"], "commands": ["doc +history-revert", "doc +version-revert", "doc version revert"], "risk": "yellow"},
+    "doc_version_number": {"denotes": "single document or Drive ordinary-file historical version number with unchanged positive integer value", "canonical_hint": "version", "members": ["version", "version-number", "version-no"], "excludes": ["revision", "id", "node", "node-id", "doc-id"], "commands": ["doc +history-revert", "doc +version-revert", "doc version revert", "drive +version-download", "drive +version-get", "drive +version-revert", "drive download", "drive download-version", "drive revert"], "risk": "yellow"},
     "doc_content_format": {"denotes": "DingTalk document body format with unchanged markdown/jsonml value", "canonical_hint": "content-format", "members": ["content-format", "doc-format"], "excludes": ["format", "export-format", "mime-type"], "commands": ["doc +create", "doc +update", "doc create", "doc update"], "risk": "green"},
-    "doc_edit_revision": {"denotes": "single optimistic-concurrency revision for a document edit", "canonical_hint": "revision", "members": ["revision", "expected-revision"], "excludes": ["version", "version-number", "version-no"], "commands": ["doc +update", "doc update"], "risk": "yellow"}
+    "doc_edit_revision": {"denotes": "single optimistic-concurrency revision for a document edit", "canonical_hint": "revision", "members": ["revision", "expected-revision"], "excludes": ["version", "version-number", "version-no"], "commands": ["doc +update", "doc update"], "risk": "yellow"},
+    "drive_recycle_item_id": {"denotes": "single Drive recycle-bin item ID returned by recycle list", "canonical_hint": "id", "members": ["id", "recycle-item-id", "trash-item-id", "deleted-item-id"], "excludes": ["node", "node-id", "file-id", "folder-id", "space-id", "workspace-id"], "commands": ["drive +recycle-restore", "drive recycle restore"], "risk": "yellow"},
+    "drive_modified_time_start": {"denotes": "Drive search modified-time lower bound in unchanged millisecond timestamp unit", "canonical_hint": "modified-from", "members": ["modified-from", "modified-after", "modify-time-from", "modified-time-start"], "excludes": ["modified-to", "created-from", "created-to", "start", "from"], "commands": ["drive +search", "drive search"], "risk": "yellow"},
+    "drive_modified_time_end": {"denotes": "Drive search modified-time upper bound in unchanged millisecond timestamp unit", "canonical_hint": "modified-to", "members": ["modified-to", "modified-before", "modify-time-to", "modified-time-end"], "excludes": ["modified-from", "created-from", "created-to", "end", "to"], "commands": ["drive +search", "drive search"], "risk": "yellow"},
+    "drive_file_size_bytes": {"denotes": "file size in bytes passed unchanged", "canonical_hint": "file-size", "members": ["file-size", "file-size-bytes", "size-bytes", "content-length"], "excludes": ["part-size", "page-size", "limit", "size"], "commands": ["drive commit", "drive upload-info"], "risk": "yellow"},
+    "drive_sort_direction": {"denotes": "Drive result sort direction with unchanged asc/desc enum", "canonical_hint": "order", "members": ["order", "sort", "sort-direction", "order-direction"], "excludes": ["order-by", "sort-by", "order-field"], "commands": ["drive +list", "drive list", "drive star list"], "risk": "green"},
+    "workspace_id": {"denotes": "single knowledge-base or document-space workspace ID/URL passed unchanged; never a numeric DingDrive storage space ID", "canonical_hint": "workspace", "members": ["workspace", "workspace-id", "knowledge-base-id", "wiki-workspace-id"], "excludes": ["space", "space-id", "drive-space-id", "storage-space-id", "dingdrive-space-id", "folder", "folder-id", "node", "node-id", "dentry-id"], "commands": ["doc +access-change", "doc +access-grant", "doc +access-revoke", "doc +copy", "doc +create", "doc +create-from-template", "doc +grant-and-share", "doc +import", "doc +list", "doc +move", "doc create", "doc file create", "doc import", "doc template apply", "drive +copy", "drive +create-shortcut", "drive +move", "drive copy", "drive list", "drive move", "drive permission add", "drive permission list", "drive permission remove", "drive permission transfer-owner", "drive permission update", "drive shortcut", "drive upload"], "risk": "yellow"},
+    "created_time_start": {"denotes": "Doc/Drive search created-time lower bound in unchanged millisecond timestamp unit", "canonical_hint": "created-from", "members": ["created-from", "created-after", "create-time-from", "created-time-start", "create-time-start"], "excludes": ["created-to", "modified-from", "modified-to", "start", "from"], "commands": ["doc +search", "drive +search", "drive search"], "risk": "yellow"},
+    "created_time_end": {"denotes": "Doc/Drive search created-time upper bound in unchanged millisecond timestamp unit", "canonical_hint": "created-to", "members": ["created-to", "created-before", "create-time-to", "created-time-end", "create-time-end"], "excludes": ["created-from", "modified-from", "modified-to", "end", "to"], "commands": ["doc +search", "drive +search", "drive search"], "risk": "yellow"},
+    "document_permission_role": {"denotes": "direct document-space permission role on grant/apply/update, passed unchanged", "canonical_hint": "role", "members": ["role", "permission-role", "access-role", "member-role"], "excludes": ["filter-role", "reserve-role", "permission", "public-permission"], "commands": ["doc +access-change", "doc +access-grant", "doc +grant-and-share", "drive permission add", "drive permission apply", "drive permission update"], "risk": "yellow"},
+    "creator_user_ids": {"denotes": "creator userId list used to filter Doc/Drive search results, passed unchanged", "canonical_hint": "creator-uids", "members": ["creator-uids", "creator-user-ids", "creator-ids", "created-by-user-ids"], "excludes": ["user", "user-id", "user-ids", "users", "owner-id", "modifier-uids"], "commands": ["doc +search", "drive +search", "drive search"], "risk": "yellow"},
+    "local_output_path": {"denotes": "local destination file or directory path for a download/export result, passed unchanged", "canonical_hint": "output", "members": ["output", "output-path", "destination-path", "save-path"], "excludes": ["file", "file-path", "folder", "folder-id", "content-file"], "commands": ["doc +export", "doc +export-get", "doc +media-download", "doc +resource-download", "doc read", "drive +download", "drive +version-download", "drive download", "drive download-version"], "risk": "green"}
   },
 
   "command_overrides": {
-	"doc +version-list": {"ambiguous": ["size", "max-results", "max-result", "take", "top", "per-page", "next-cursor", "next-token", "next-page-token"], "note": "--limit/--cursor and the shipped visible compatibility flags --page-size/--page-token remain native. Other pagination spellings cannot choose between two visible real flags and must stop before execution."},
+    "doc +version-list": {"ambiguous": ["size", "max-results", "max-result", "take", "top", "per-page", "next-cursor", "next-token", "next-page-token"], "note": "--limit/--cursor and the shipped visible compatibility flags --page-size/--page-token remain native. Other pagination spellings cannot choose between two visible real flags and must stop before execution."},
     "chat group rename": {"bind": {"id": "open_conversation_id"}, "note": "This command's real --id carries one openConversationId; aliases reduce to --id without changing the value."},
     "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."},
@@ -54,8 +65,8 @@
     "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."},
-    "drive list": {"ambiguous": ["space"], "note": "both --space-id and native compatibility --workspace-id/--workspace exist; bare --space cannot choose one"},
-    "drive upload": {"ambiguous": ["space"], "note": "both --space-id and native compatibility --workspace-id/--workspace exist; bare --space cannot choose one"},
+    "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"},
     "ding message receiver-status": {"scoped_aliases": {"id": "ding-id"}},
     "contact user profile get": {"scoped_aliases": {"id": "staff-id", "ids": "staff-id"}, "note": "user-id is reduced by the user_id concept; generic id/ids bound explicitly"},
@@ -101,9 +112,9 @@
     "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."},
     "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"}, "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."},
-    "doc +list": {"scoped_aliases": {"folder-id": "folder", "parent-folder": "folder", "parent-folder-id": "folder", "parent-node-id": "folder"}, "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."},
-    "doc +move": {"scoped_aliases": {"folder-id": "folder", "parent-folder": "folder", "parent-folder-id": "folder", "parent-node-id": "folder"}, "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."},
+    "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."},
+    "doc +list": {"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."},
+    "doc +move": {"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."},
     "doc comment create": {"scoped_aliases": {"mentioned-open-conversation-ids": "mentioned-open-conversation-id", "open-conversation-id": "mentioned-open-conversation-id", "open-conversation-ids": "mentioned-open-conversation-id"}, "block": ["chat-id", "chat-ids", "conversation-id", "conversation-ids", "group-id", "group-ids"], "scope_strict": true, "note": "The target is a list of mentioned openConversationIds. Explicit open-conversation spellings preserve the list value; numeric groupId and role-free conversation spellings are rejected."},
     "doc comment reply": {"scoped_aliases": {"mentioned-open-conversation-ids": "mentioned-open-conversation-id", "open-conversation-id": "mentioned-open-conversation-id", "open-conversation-ids": "mentioned-open-conversation-id"}, "block": ["chat-id", "chat-ids", "conversation-id", "conversation-ids", "group-id", "group-ids"], "scope_strict": true, "note": "The target is a list of mentioned openConversationIds. Explicit open-conversation spellings preserve the list value; numeric groupId and role-free conversation spellings are rejected."},
     "doc comment update": {"scoped_aliases": {"mentioned-open-conversation-ids": "mentioned-open-conversation-id", "open-conversation-id": "mentioned-open-conversation-id", "open-conversation-ids": "mentioned-open-conversation-id"}, "block": ["chat-id", "chat-ids", "conversation-id", "conversation-ids", "group-id", "group-ids"], "scope_strict": true, "note": "The target is a list of mentioned openConversationIds. Explicit open-conversation spellings preserve the list value; numeric groupId and role-free conversation spellings are rejected."},
@@ -114,7 +125,7 @@
     "doc export get": {"scoped_aliases": {"export-job-id": "job-id"}, "block": ["doc-id", "document-id", "file-id", "node", "node-id", "url"], "scope_strict": true, "note": "This command queries one export jobId. Document node identifiers are rejected; native hidden --task-id remains the command's reviewed add-only compatibility alias for --job-id."},
     "doc import get": {"scoped_aliases": {"import-task-id": "task-id"}, "block": ["doc-id", "document-id", "file-id", "job-id", "node", "node-id", "url"], "scope_strict": true, "note": "This command queries one import taskId. Document node identifiers and export jobId spellings are different entities and are rejected."},
     "doc +share-doc": {"block": ["doc", "doc-id", "document-id", "file-id", "id", "node", "node-id"], "note": "The real --url requires a shareable document link. Name-only normalization cannot turn a document nodeId into a URL, so identifier spellings are rejected with guidance to provide --url."},
-    "doc update": {"block": ["version", "version-no", "version-number"], "note": "--revision is an optimistic-concurrency revision, not a historical document version number. Version spellings must not reduce to --revision."},
+    "doc update": {"block": ["stdin", "version", "version-no", "version-number"], "note": "--revision is an optimistic-concurrency revision, not a historical document version number. Version spellings must not reduce to --revision. --stdin is not a real switch: stdin input is expressed as --content -, which requires a value-form transformation outside central name aliases."},
     "report outbox list": {"block": ["template-type"], "note": "type vs name are different fields"},
     "chat group members add-bot": {"bind": {"id": "open_conversation_id"}},
     "chat group members list-by-ids": {"bind": {"id": "open_conversation_id", "users": "open_dingtalk_ids"}, "block": ["user-id", "user-ids"], "note": "This command's --id carries openConversationId, while --users carries an openDingTalkId list."},
@@ -158,21 +169,86 @@
     "chat +messages-recall-by-bot": {"block": ["msg-id", "message-id", "open-message-id", "msg-ids", "message-ids", "open-message-ids"], "note": "--keys carries processQueryKey values, not openMessageId values."},
     "chat +messages-reply": {"scoped_aliases": {"msg-id": "ref-msg-id", "open-message-id": "ref-msg-id"}, "block": ["group", "msg-ids", "message-ids", "open-message-ids"], "scope_strict": true, "note": "The observed --group spelling carried a natural group name and is blocked. The only message role is the referenced message; plural IDs are not accepted, while --chat remains a CID alias and native --message-id stays native."},
     "chat +messages-resource-download": {"block": ["download-dir"], "note": "--output may be a file or directory under workspace safety rules; a download directory cannot be assumed equivalent."},
-    "doc +create": {"scoped_aliases": {"folder-id": "folder", "parent-folder": "folder", "parent-folder-id": "folder", "parent-node-id": "folder"}, "block": ["content-file", "parent-id"], "scope_strict": true, "note": "--content-format is value-preservingly normalized to --doc-format. A raw --content-file path cannot become --content without adding the required @file transform, so it is blocked with guidance to use @relative-path or stable doc create."},
-    "doc +create-from-template": {"scoped_aliases": {"folder-id": "folder", "parent-folder": "folder", "parent-folder-id": "folder", "parent-node-id": "folder"}, "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."},
-    "doc +import": {"scoped_aliases": {"folder-id": "folder", "parent-folder": "folder", "parent-folder-id": "folder", "parent-node-id": "folder"}, "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."},
-    "doc +update": {"scoped_aliases": {"mode": "command", "doc-id": "node", "document-id": "node", "file-id": "node", "node-id": "node", "url": "node"}, "block": ["content-file"], "scope_strict": true, "note": "--mode append/overwrite is the same operation selector subset as --command and preserves its value. --content-file is blocked because +update requires @relative-path or stdin and central aliases cannot read/transform a file value."},
-    "doc +inspect": {"scoped_aliases": {"include-versions": "include-history"}, "block": ["include", "include-info"], "scope_strict": true, "note": "Historical versions and history are the same optional section on this exact shortcut. Generic --include needs value-dependent flag expansion, while base document info is always returned, so those spellings are rejected with precise guidance."},
-    "doc +fetch": {"scoped_aliases": {"start-block": "start-block-id", "end-block": "end-block-id"}, "ambiguous": ["block-id"], "scope_strict": true, "note": "Start/end block roles are preserved. A role-free --block-id cannot choose a range/section boundary and must stop before execution."},
+    "doc +access-change": {"scoped_aliases": {"space": "workspace", "space-id": "workspace"}, "scope_strict": true, "note": "Command-scoped compatibility published before the workspace/storage-space concept split: these spellings keep passing their value unchanged to this Doc command's --workspace flag and do not establish global equivalence with a numeric DingDrive storage space."},
+    "doc +access-grant": {"scoped_aliases": {"space": "workspace", "space-id": "workspace"}, "block": ["target-user-id", "target-user-ids", "user-id", "user-ids"], "ambiguous": ["target-user", "user", "users"], "scope_strict": true, "note": "The real --to accepts collaborator names and resolves them before granting access. Explicit ID spellings cannot be passed through unchanged, while role-free user spellings do not prove whether their values are names or IDs. The command-scoped --space/--space-id aliases preserve previously published Doc workspace compatibility without making workspace and numeric DingDrive storage-space values globally equivalent."},
+    "doc +access-revoke": {"scoped_aliases": {"space": "workspace", "space-id": "workspace"}, "scope_strict": true, "note": "Command-scoped compatibility published before the workspace/storage-space concept split: these spellings keep passing their value unchanged to this Doc command's --workspace flag and do not establish global equivalence with a numeric DingDrive storage space."},
+    "doc +create": {"scoped_aliases": {"folder-id": "folder", "parent-folder": "folder", "parent-folder-id": "folder", "parent-node-id": "folder", "space": "workspace", "space-id": "workspace"}, "block": ["content-file", "parent-id"], "scope_strict": true, "note": "--content-format is value-preservingly normalized to --doc-format. A raw --content-file path cannot become --content without adding the required @file transform, so it is blocked with guidance to use @relative-path or stable doc create. The command-scoped --space/--space-id aliases preserve previously published Doc workspace compatibility without making workspace and numeric DingDrive storage-space values globally equivalent."},
+    "doc +create-from-template": {"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 previously published Doc workspace compatibility without making workspace and numeric DingDrive storage-space values globally equivalent."},
+    "doc +import": {"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 previously published Doc workspace compatibility without making workspace and numeric DingDrive storage-space values globally equivalent."},
+    "doc create": {"scoped_aliases": {"space": "workspace", "space-id": "workspace"}, "scope_strict": true, "note": "Command-scoped compatibility published before the workspace/storage-space concept split: these spellings keep passing their value unchanged to this Doc command's --workspace flag and do not establish global equivalence with a numeric DingDrive storage space."},
+    "doc file create": {"scoped_aliases": {"space": "workspace", "space-id": "workspace"}, "scope_strict": true, "note": "Command-scoped compatibility published before the workspace/storage-space concept split: these spellings keep passing their value unchanged to this Doc command's --workspace flag and do not establish global equivalence with a numeric DingDrive storage space."},
+    "doc import": {"scoped_aliases": {"space": "workspace", "space-id": "workspace"}, "scope_strict": true, "note": "Command-scoped compatibility published before the workspace/storage-space concept split: these spellings keep passing their value unchanged to this Doc command's --workspace flag and do not establish global equivalence with a numeric DingDrive storage space."},
+    "doc template apply": {"scoped_aliases": {"space": "workspace", "space-id": "workspace"}, "scope_strict": true, "note": "Command-scoped compatibility published before the workspace/storage-space concept split: these spellings keep passing their value unchanged to this Doc command's --workspace flag and do not establish global equivalence with a numeric DingDrive storage space."},
+    "doc +update": {"scoped_aliases": {"mode": "command", "doc-id": "node", "document-id": "node", "file-id": "node", "node-id": "node", "url": "node"}, "block": ["content-file"], "ambiguous": ["element"], "scope_strict": true, "note": "--mode append/overwrite is the same operation selector subset as --command and preserves its value. --content-file is blocked because +update requires @relative-path or stdin and central aliases cannot read/transform a file value. --element cannot choose between document content, a block target, or an insertion reference."},
+    "doc +inspect": {"scoped_aliases": {"include-access": "include-permissions", "include-member": "include-permissions", "include-members": "include-permissions", "include-versions": "include-history"}, "block": ["include", "include-blocks", "include-content", "include-info", "include-meta", "include-metadata"], "scope_strict": true, "note": "Access/member spellings denote the same optional permission list, and versions/history denote the same history section. Generic --include needs value-dependent expansion; base metadata is already returned; block/content reads belong to +fetch, so those spellings stop before fuzzy correction or dispatch."},
+    "doc +fetch": {"scoped_aliases": {"start-block": "start-block-id", "end-block": "end-block-id"}, "block": ["content-format", "doc-format", "range"], "ambiguous": ["block-id"], "scope_strict": true, "note": "Start/end block roles are preserved. A role-free --block-id cannot choose a range/section boundary. --range is an invented composite argument observed alongside --scope range and cannot be split into block IDs by name-only normalization; content-format spellings do not map to the independent --detail contract."},
+    "doc +export": {"block": ["wait"], "scope_strict": true, "note": "The shortcut already submits, polls, and downloads in one workflow. A generic --wait value cannot be converted into the distinct integer --max-polls contract by parameter-name normalization."},
     "doc +media-download": {"scoped_aliases": {"doc": "node", "doc-id": "node", "document-id": "node", "node-id": "node"}, "ambiguous": ["file-id", "url"], "scope_strict": true, "note": "This command has both document-node and attachment-resource roles. Strong document spellings map to --node; --file-id and --url cannot safely choose between document and media identities."},
-    "doc +media-insert": {"scoped_aliases": {"doc": "node", "doc-id": "node", "document-id": "node", "node-id": "node"}, "ambiguous": ["file-id", "url"], "scope_strict": true, "note": "This command has both document-node and local-media roles. Strong document spellings map to --node; --file-id and --url cannot safely choose a role."},
+    "doc +media-insert": {"scoped_aliases": {"doc": "node", "doc-id": "node", "document-id": "node", "node-id": "node"}, "block": ["after-block-id", "before-block-id"], "ambiguous": ["file-id", "url"], "scope_strict": true, "note": "This command has both document-node and local-media roles. Strong document spellings map to --node; --file-id and --url cannot safely choose a role. Before/after block spellings each require expansion into both --ref-block and --where, which name-only normalization cannot perform."},
     "doc +media-list": {"scoped_aliases": {"doc": "node", "doc-id": "node", "document-id": "node", "node-id": "node"}, "ambiguous": ["file-id", "url"], "scope_strict": true, "note": "The command lists media inside one document, so only strong document spellings map to --node. File and URL spellings remain role-ambiguous."},
     "doc +media-preview": {"scoped_aliases": {"doc": "node", "doc-id": "node", "document-id": "node", "node-id": "node"}, "ambiguous": ["file-id", "url"], "scope_strict": true, "note": "This command has both document-node and attachment-resource roles. Strong document spellings map to --node; --file-id and --url cannot safely choose a role."},
     "doc +resource-delete": {"scoped_aliases": {"doc": "node", "doc-id": "node", "document-id": "node", "node-id": "node"}, "ambiguous": ["file-id", "url"], "scope_strict": true, "note": "This command removes a document resource while targeting the document by --node. File and URL spellings do not uniquely identify that document role."},
     "doc +resource-download": {"scoped_aliases": {"doc": "node", "doc-id": "node", "document-id": "node", "node-id": "node"}, "ambiguous": ["file-id", "url"], "scope_strict": true, "note": "This command downloads a document resource while targeting the document by --node. File and URL spellings do not uniquely identify that document role."},
     "doc +resource-update": {"scoped_aliases": {"doc": "node", "doc-id": "node", "document-id": "node", "node-id": "node"}, "ambiguous": ["file-id", "url"], "scope_strict": true, "note": "This command has document-node, local-file, and HTTPS image URL roles. Only strong document spellings map to --node; --file-id and --url must stop as ambiguous."},
     "doc +share": {"block": ["doc", "doc-id", "document-id", "file-id", "id", "node", "node-id"], "note": "The real --url requires a shareable document link. Name-only normalization cannot turn a node identifier into a URL, so identifier spellings are rejected with guidance to provide --url."},
-    "doc +grant-and-share": {"scoped_aliases": {"doc": "node", "doc-id": "node", "document-id": "node", "file-id": "node", "node-id": "node"}, "scope_strict": true, "note": "This workflow has two different real URL roles: --node selects the document for access control and --url is the shareable link sent to recipients. Explicit document-ID spellings map only to --node; --url remains native."}
+    "doc +grant-and-share": {"scoped_aliases": {"doc": "node", "doc-id": "node", "document-id": "node", "file-id": "node", "node-id": "node", "space": "workspace", "space-id": "workspace"}, "scope_strict": true, "note": "This workflow has two different real URL roles: --node selects the document for access control and --url is the shareable link sent to recipients. Explicit document-ID spellings map only to --node; --url remains native. The command-scoped --space/--space-id aliases preserve previously published Doc workspace compatibility without making workspace and numeric DingDrive storage-space values globally equivalent."},
+    "doc +version-save": {"block": ["message", "title"], "scope_strict": true, "note": "The current snapshot API accepts only the document target. Version title/message metadata are unsupported and cannot be represented by another existing flag."},
+    "drive copy": {"scoped_aliases": {"document-id": "node", "dentry-uuid": "node", "directory-id": "folder", "source-node-id": "node", "source-file-id": "node", "target-folder-id": "folder", "destination-folder-id": "folder", "target-workspace-id": "workspace", "destination-workspace-id": "workspace"}, "scope_strict": true, "note": "Source node and destination folder/workspace are different roles; role-free target IDs stop before write dispatch. --name is not a rename field on this command and must not be fuzzy-corrected to --node.", "block": ["dentry-id", "destination-node-id", "dingdrive-space-id", "drive-space-id", "name", "source-folder-id", "space-id", "storage-space-id"], "ambiguous": ["destination-id", "target-id"]},
+    "drive cover": {"scoped_aliases": {"document-id": "node", "dentry-uuid": "node"}, "scope_strict": true, "note": "The command accepts a Drive node ID or URL; native file-id/node-id/doc-id/url aliases stay native and are not duplicated centrally.", "block": ["dentry-id"]},
+    "drive download-version": {"scoped_aliases": {"document-id": "node", "dentry-uuid": "node", "chunk-size": "part-size", "concurrency": "parallel", "parallelism": "parallel"}, "scope_strict": true, "note": "Output path, chunk size, and concurrency names preserve values; local input and remote folder roles remain blocked.", "block": ["dentry-id", "file", "file-path", "folder", "folder-id"]},
+    "drive move": {"scoped_aliases": {"document-id": "node", "dentry-uuid": "node", "directory-id": "folder", "source-node-id": "node", "source-file-id": "node", "target-folder-id": "folder", "destination-folder-id": "folder", "target-workspace-id": "workspace", "destination-workspace-id": "workspace"}, "scope_strict": true, "note": "Source node and destination folder/workspace are different roles; role-free target IDs stop before write dispatch. --name is not a rename field on this command and must not be fuzzy-corrected to --node.", "block": ["dentry-id", "destination-node-id", "dingdrive-space-id", "drive-space-id", "name", "source-folder-id", "space-id", "storage-space-id"], "ambiguous": ["destination-id", "target-id"]},
+    "drive permission add": {"scoped_aliases": {"document-id": "node", "dentry-uuid": "node", "member-user-ids": "users", "collaborator-ids": "users", "target-user-ids": "users", "target-node-id": "node"}, "scope_strict": true, "note": "The user list denotes target collaborators on this exact node permission command; the native singular compatibility spellings remain native.", "block": ["dentry-id", "dingdrive-space-id", "drive-space-id", "space-id", "storage-space-id"]},
+    "drive permission apply": {"scoped_aliases": {"document-id": "node", "dentry-uuid": "node", "approver-user-ids": "users", "approver-ids": "users", "target-node-id": "node", "apply-reason": "reason", "notification-mode": "notify-mode"}, "scope_strict": true, "note": "The user list denotes approvers, not target collaborators; values and notification enum are passed unchanged.", "block": ["dentry-id"]},
+    "drive permission apply-info": {"scoped_aliases": {"document-id": "node", "dentry-uuid": "node"}, "scope_strict": true, "note": "The command accepts a Drive node ID or URL; native file-id/node-id/doc-id/url aliases stay native and are not duplicated centrally.", "block": ["dentry-id"]},
+    "drive permission list": {"scoped_aliases": {"document-id": "node", "dentry-uuid": "node", "role-filter": "filter-role", "permission-role-filter": "filter-role", "target-node-id": "node"}, "scope_strict": true, "note": "Filtering by a role is not the same as granting/updating a role.", "block": ["dentry-id", "dingdrive-space-id", "drive-space-id", "permission", "role", "space-id", "storage-space-id"]},
+    "drive permission remove": {"scoped_aliases": {"document-id": "node", "dentry-uuid": "node", "member-user-ids": "users", "collaborator-ids": "users", "target-user-ids": "users", "target-node-id": "node"}, "scope_strict": true, "note": "The user list denotes target collaborators on this exact node permission command; the native singular compatibility spellings remain native.", "block": ["dentry-id", "dingdrive-space-id", "drive-space-id", "space-id", "storage-space-id"]},
+    "drive permission transfer-owner": {"scoped_aliases": {"document-id": "node", "dentry-uuid": "node", "target-node-id": "node", "target-workspace-id": "workspace", "old-owner-role": "reserve-role", "keep-role": "reserve-role", "new-owner-id": "new-owner", "new-owner-user-id": "new-owner"}, "scope_strict": true, "note": "Node/workspace target and new/old owner roles are distinct on this irreversible command; role-free names stop before dispatch.", "block": ["current-owner", "dentry-id", "dingdrive-space-id", "drive-space-id", "space-id", "storage-space-id", "user-ids", "users"], "ambiguous": ["owner", "owner-user-id", "target-id", "user-id"]},
+    "drive permission update": {"scoped_aliases": {"document-id": "node", "dentry-uuid": "node", "member-user-ids": "users", "collaborator-ids": "users", "target-user-ids": "users", "target-node-id": "node"}, "scope_strict": true, "note": "The user list denotes target collaborators on this exact node permission command; the native singular compatibility spellings remain native.", "block": ["dentry-id", "dingdrive-space-id", "drive-space-id", "space-id", "storage-space-id"]},
+    "drive publish get": {"scoped_aliases": {"document-id": "node", "dentry-uuid": "node"}, "scope_strict": true, "note": "The command accepts a Drive node ID or URL; native file-id/node-id/doc-id/url aliases stay native and are not duplicated centrally.", "block": ["dentry-id"]},
+    "drive publish set": {"scoped_aliases": {"document-id": "node", "dentry-uuid": "node", "public-permission": "permission", "public-role": "permission"}, "scope_strict": true, "note": "Internet-public permission is not the same as a direct collaborator role.", "block": ["access-role", "dentry-id", "permission-role", "role"]},
+    "drive publish unset": {"scoped_aliases": {"document-id": "node", "dentry-uuid": "node"}, "scope_strict": true, "note": "The command accepts a Drive node ID or URL; native file-id/node-id/doc-id/url aliases stay native and are not duplicated centrally.", "block": ["dentry-id"]},
+    "drive rename": {"scoped_aliases": {"document-id": "node", "dentry-uuid": "node", "file-name": "name", "display-name": "name", "new-name": "name"}, "scope_strict": true, "note": "The name is this exact folder/node display name; search query and local path are different roles.", "block": ["dentry-id"]},
+    "drive revert": {"scoped_aliases": {"document-id": "node", "dentry-uuid": "node"}, "scope_strict": true, "note": "The command accepts a Drive node ID or URL; native file-id/node-id/doc-id/url aliases stay native and are not duplicated centrally.", "block": ["dentry-id"]},
+    "drive shortcut": {"scoped_aliases": {"document-id": "node", "dentry-uuid": "node", "directory-id": "folder", "source-node-id": "node", "source-file-id": "node", "target-folder-id": "folder", "destination-folder-id": "folder", "target-workspace-id": "workspace", "destination-workspace-id": "workspace"}, "scope_strict": true, "note": "Source node and destination folder/workspace are different roles; role-free target IDs stop before write dispatch. --name is not a rename field on this command and must not be fuzzy-corrected to --node.", "block": ["dentry-id", "destination-node-id", "dingdrive-space-id", "drive-space-id", "name", "source-folder-id", "space-id", "storage-space-id"], "ambiguous": ["destination-id", "target-id"]},
+    "drive star add": {"scoped_aliases": {"document-id": "node", "dentry-uuid": "node"}, "scope_strict": true, "note": "The command accepts a Drive node ID or URL; native file-id/node-id/doc-id/url aliases stay native and are not duplicated centrally.", "block": ["dentry-id"]},
+    "drive star remove": {"scoped_aliases": {"document-id": "node", "dentry-uuid": "node"}, "scope_strict": true, "note": "The command accepts a Drive node ID or URL; native file-id/node-id/doc-id/url aliases stay native and are not duplicated centrally.", "block": ["dentry-id"]},
+    "drive stats": {"scoped_aliases": {"document-id": "node", "dentry-uuid": "node"}, "scope_strict": true, "note": "The command accepts a Drive node ID or URL; native file-id/node-id/doc-id/url aliases stay native and are not duplicated centrally.", "block": ["dentry-id"]},
+    "drive +cover": {"scoped_aliases": {"dentry-uuid": "node", "file-id": "node", "node-id": "node", "doc-id": "node", "document-id": "node", "url": "node", "document-url": "node", "id": "node"}, "block": ["dentry-id", "doc", "folder", "folder-id", "name"], "scope_strict": true, "note": "This shortcut calls the same get_cover nodeId interface as drive cover, so its reviewed ID/URL aliases are preserved unchanged. Numeric dentryId, folder-role spellings and --name remain protected."},
+    "drive +copy": {"scoped_aliases": {"dentry-uuid": "node", "directory-id": "folder", "source-node-id": "node", "source-file-id": "node", "target-folder-id": "folder", "destination-folder-id": "folder", "target-workspace-id": "workspace", "destination-workspace-id": "workspace"}, "block": ["dentry-id", "destination-node-id", "dingdrive-space-id", "document-url", "drive-space-id", "name", "source-folder-id", "space-id", "storage-space-id"], "scope_strict": true, "note": "Source node and destination folder/workspace are different roles; role-free target IDs stop before write dispatch. --name is not a rename field on this command and must not be fuzzy-corrected to --node.", "ambiguous": ["destination-id", "target-id"]},
+    "drive +create-folder": {"scoped_aliases": {"directory-id": "folder", "parent-directory-id": "folder", "parent-folder-id": "folder", "folder-name": "name", "display-name": "name", "new-name": "name"}, "block": ["dentry-id", "parent-id", "knowledge-base-id", "wiki-workspace-id", "workspace", "workspace-id"], "scope_strict": true, "note": "The new shortcut creates a numeric DingDrive-space folder. Folder display name, parent dentryUuid and numeric storage space are separate roles; knowledge-base workspace spellings are not accepted."},
+    "drive +create-shortcut": {"scoped_aliases": {"dentry-uuid": "node", "file-id": "node", "node-id": "node", "doc-id": "node", "document-id": "node", "url": "node", "document-url": "node", "directory-id": "folder", "source-node-id": "node", "source-file-id": "node", "target-folder-id": "folder", "destination-folder-id": "folder", "target-workspace-id": "workspace", "destination-workspace-id": "workspace"}, "block": ["dentry-id", "destination-node-id", "dingdrive-space-id", "doc", "drive-space-id", "name", "source-folder-id", "space-id", "storage-space-id"], "scope_strict": true, "note": "Source node and destination folder/workspace are different roles. The source ID/URL aliases match drive shortcut and pass through unchanged; generic target/id spellings remain ambiguous, and storage-space IDs are not knowledge-base workspace IDs.", "ambiguous": ["destination-id", "id", "target-id"]},
+    "drive +delete": {"scoped_aliases": {"dentry-uuid": "node", "file-id": "node", "node-id": "node", "folder": "node", "folder-id": "node"}, "block": ["dentry-id", "doc", "doc-id", "document-id", "document-url", "id", "name", "url"], "scope_strict": true, "note": "Delete targets one already confirmed Drive file or folder dentryUuid. Folder spellings are the same single target role; numeric dentryId, unreviewed Doc URL spellings and --name stop before confirmation or write dispatch."},
+    "drive +download": {"scoped_aliases": {"dentry-uuid": "node", "file-id": "node", "node-id": "node"}, "block": ["dentry-id", "doc", "doc-id", "document-id", "document-url", "file", "file-path", "folder", "folder-id", "id", "knowledge-base-id", "name", "url", "wiki-workspace-id", "workspace", "workspace-id"], "scope_strict": true, "note": "The remote ordinary-file node and local output path are different roles. Node-ID spelling is accepted, while Doc URLs, local input paths, folders, knowledge-base workspaces and numeric dentryId values are not interchangeable."},
+    "drive +info": {"scoped_aliases": {"dentry-uuid": "node"}, "block": ["dentry-id", "document-url", "knowledge-base-id", "wiki-workspace-id", "workspace", "workspace-id"], "scope_strict": true, "note": "This command has only a numeric DingDrive space target; knowledge-base workspace spellings are a different value domain."},
+    "drive +inspect": {"scoped_aliases": {"dentry-uuid": "node", "file-id": "node", "node-id": "node", "doc-id": "node", "document-id": "node", "folder": "node", "folder-id": "node", "include-statistics": "include-stats", "include-publish-status": "include-publish", "include-public-status": "include-publish", "include-thumbnail": "include-cover"}, "block": ["dentry-id", "doc", "document-url", "id", "include", "include-content", "include-history", "include-permissions", "name", "url"], "scope_strict": true, "note": "Drive inspect accepts one file, folder or document node ID and can aggregate only stats, public-publish status and cover. URL spellings, Doc inspect section names and a generic --include remain protected because this shortcut does not declare URL input or value splitting."},
+    "drive +list": {"ambiguous": ["root-id", "space"], "scoped_aliases": {"directory-id": "folder", "parent-folder-id": "folder", "order-field": "order-by", "sort-by": "order-by", "sort-field": "order-by"}, "block": ["dentry-id", "knowledge-base-id", "wiki-workspace-id", "workspace", "workspace-id"], "scope_strict": true, "note": "This shortcut accepts one numeric DingDrive space and an optional parent dentryUuid; it does not accept a knowledge-base workspace. Sort field and direction remain separate roles."},
+    "drive +move": {"scoped_aliases": {"dentry-uuid": "node", "directory-id": "folder", "source-node-id": "node", "source-file-id": "node", "target-folder-id": "folder", "destination-folder-id": "folder", "target-workspace-id": "workspace", "destination-workspace-id": "workspace"}, "block": ["dentry-id", "destination-node-id", "dingdrive-space-id", "document-url", "drive-space-id", "name", "source-folder-id", "space-id", "storage-space-id"], "scope_strict": true, "note": "Source node and destination folder/workspace are different roles; role-free target IDs stop before write dispatch. --name is not a rename field on this command and must not be fuzzy-corrected to --node.", "ambiguous": ["destination-id", "target-id"]},
+    "drive +publish-get": {"scoped_aliases": {"dentry-uuid": "node", "file-id": "node", "node-id": "node", "doc-id": "node", "document-id": "node", "url": "node", "document-url": "node", "id": "node"}, "block": ["dentry-id", "doc", "folder", "folder-id", "name"], "scope_strict": true, "note": "The shortcut calls the same publication-status fileId interface as drive publish get, so its reviewed ID/URL aliases are preserved unchanged. Numeric dentryId and folder/name roles remain protected."},
+    "drive +publish-unset": {"scoped_aliases": {"dentry-uuid": "node", "file-id": "node", "node-id": "node", "doc-id": "node", "document-id": "node", "url": "node", "document-url": "node", "id": "node"}, "block": ["dentry-id", "doc", "folder", "folder-id", "name"], "scope_strict": true, "note": "The shortcut calls the same set_file_publish fileId interface as drive publish unset, so its reviewed ID/URL aliases are preserved unchanged. Numeric dentryId and folder/name roles remain protected before confirmation."},
+    "drive +recycle-restore": {"bind": {"id": "drive_recycle_item_id"}, "block": ["file-id", "folder-id", "node", "node-id", "space-id", "workspace-id"], "scope_strict": true, "note": "The real --id is a recycleItemId returned by drive +recycle-list, not a normal Drive node ID."},
+    "drive +rename": {"scoped_aliases": {"dentry-uuid": "node", "file-id": "node", "node-id": "node", "doc-id": "node", "document-id": "node", "url": "node", "document-url": "node", "id": "node", "folder": "node", "folder-id": "node", "file-name": "name", "display-name": "name", "new-name": "name"}, "block": ["dentry-id"], "scope_strict": true, "note": "The existing document, file or folder node and the requested new display name are separate required roles. Node ID/URL aliases match drive rename and pass through unchanged; numeric dentryId remains protected."},
+    "drive delete": {"scoped_aliases": {"dentry-uuid": "node"}, "block": ["dentry-id", "document-url"], "scope_strict": true, "note": "This command publicly accepts an ID-only Drive node; dentry spellings preserve the value and URL-specific spellings remain protected."},
+    "drive download": {"scoped_aliases": {"dentry-uuid": "node", "chunk-size": "part-size", "concurrency": "parallel", "parallelism": "parallel"}, "block": ["dentry-id", "document-url", "file", "file-path", "folder", "folder-id", "knowledge-base-id", "wiki-workspace-id", "workspace", "workspace-id"], "scope_strict": true, "note": "Output path, chunk size, and concurrency names preserve values; local input and remote folder roles remain blocked."},
+    "drive info": {"scoped_aliases": {"dentry-uuid": "node", "space": "space-id", "workspace": "space-id", "workspace-id": "space-id"}, "block": ["dentry-id", "document-url", "knowledge-base-id", "wiki-workspace-id"], "scope_strict": true, "note": "This command has only a numeric DingDrive space target. Its command-scoped --space/--workspace/--workspace-id aliases preserve compatibility published before the workspace/storage-space concept split and pass the value unchanged to --space-id; new commands must not infer that knowledge-base workspace IDs and numeric storage-space IDs are globally interchangeable."},
+    "drive commit": {"scoped_aliases": {"directory-id": "folder", "parent-directory-id": "folder", "upload-session-id": "upload-id", "size-bytes": "file-size", "name": "file-name", "display-name": "file-name", "filename": "file-name", "upload-name": "file-name"}, "scope_strict": true, "note": "Upload session, file name, file size in bytes, parent folder, and storage space remain separate roles.", "block": ["knowledge-base-id", "wiki-workspace-id", "workspace", "workspace-id"]},
+    "drive mkdir": {"scoped_aliases": {"directory-id": "folder", "parent-directory-id": "folder", "folder-name": "name", "display-name": "name", "new-name": "name"}, "scope_strict": true, "note": "The name is this exact folder/node display name; search query and local path are different roles.", "block": ["knowledge-base-id", "wiki-workspace-id", "workspace", "workspace-id"]},
+    "drive upload-info": {"scoped_aliases": {"directory-id": "folder", "parent-directory-id": "folder", "content-type": "mime-type", "size-bytes": "file-size", "name": "file-name", "display-name": "file-name", "filename": "file-name", "upload-name": "file-name"}, "scope_strict": true, "note": "File metadata aliases preserve MIME and byte units; file path and upload session are different stages.", "block": ["knowledge-base-id", "wiki-workspace-id", "workspace", "workspace-id"]},
+    "drive recycle list": {"block": ["knowledge-base-id", "wiki-workspace-id", "workspace", "workspace-id"], "scope_strict": true, "note": "This command has only a numeric DingDrive space target; knowledge-base workspace spellings are a different value domain."},
+    "drive search": {"ambiguous": ["end", "from", "start", "time-from", "time-to", "to", "types"], "block": ["offset", "page"], "scope_strict": true, "note": "Created/modified ranges and file/content type arrays are separate roles; generic time/type names are not guessed."},
+    "drive +search": {"ambiguous": ["end", "from", "start", "time-from", "time-to", "to", "types"], "block": ["offset", "page"], "scope_strict": true, "note": "Created/modified ranges and file/content type arrays are separate roles; generic time/type names are not guessed."},
+    "drive +star-add": {"scoped_aliases": {"dentry-uuid": "node", "file-id": "node", "node-id": "node", "doc-id": "node", "document-id": "node", "url": "node", "document-url": "node", "id": "node"}, "block": ["dentry-id", "doc", "folder", "folder-id", "name"], "scope_strict": true, "note": "The shortcut calls the same mark_star nodeId interface as drive star add, so its reviewed document/node ID and URL aliases are preserved unchanged. Numeric dentryId and folder/name roles remain protected."},
+    "drive +star-remove": {"scoped_aliases": {"dentry-uuid": "node", "file-id": "node", "node-id": "node", "doc-id": "node", "document-id": "node", "url": "node", "document-url": "node", "id": "node"}, "block": ["dentry-id", "doc", "folder", "folder-id", "name"], "scope_strict": true, "note": "The shortcut calls the same unmark_star nodeId interface as drive star remove, so its reviewed document/node ID and URL aliases are preserved unchanged. Numeric dentryId and folder/name roles remain protected."},
+    "drive +stats": {"scoped_aliases": {"dentry-uuid": "node", "file-id": "node", "node-id": "node", "doc-id": "node", "document-id": "node", "url": "node", "document-url": "node", "id": "node"}, "block": ["dentry-id", "doc", "folder", "folder-id", "name"], "scope_strict": true, "note": "The shortcut calls the same get_node_stats nodeId interface as drive stats, so its reviewed ID/URL aliases are preserved unchanged. Numeric dentryId and folder/name roles remain protected."},
+    "drive +version-download": {"scoped_aliases": {"dentry-uuid": "node", "file-id": "node", "node-id": "node"}, "block": ["dentry-id", "doc", "doc-id", "document-id", "document-url", "file", "file-path", "folder", "folder-id", "id", "name", "url"], "scope_strict": true, "note": "Ordinary-file node, positive historical version number and local output path are three distinct roles; revision and Doc URL spellings must not be guessed."},
+    "drive +version-get": {"scoped_aliases": {"dentry-uuid": "node", "file-id": "node", "node-id": "node"}, "block": ["dentry-id", "doc", "doc-id", "document-id", "document-url", "folder", "folder-id", "id", "name", "url"], "scope_strict": true, "note": "This command reads one ordinary-file historical version by node ID and positive version number; document revision and URL roles are different."},
+    "drive +version-history": {"scoped_aliases": {"dentry-uuid": "node", "file-id": "node", "node-id": "node"}, "block": ["dentry-id", "doc", "doc-id", "document-id", "document-url", "folder", "folder-id", "id", "name", "url"], "scope_strict": true, "note": "This command pages versions for one ordinary-file Drive node; document URLs and numeric dentryId are not accepted."},
+    "drive +version-revert": {"scoped_aliases": {"dentry-uuid": "node", "file-id": "node", "node-id": "node"}, "block": ["dentry-id", "doc", "doc-id", "document-id", "document-url", "folder", "folder-id", "id", "name", "url"], "scope_strict": true, "note": "The high-risk revert targets one ordinary-file Drive node and a positive historical version number. Doc revisions and URLs must stop before confirmation or write dispatch."},
+    "drive recycle restore": {"bind": {"id": "drive_recycle_item_id"}, "block": ["file-id", "folder-id", "node", "node-id", "space-id", "workspace-id"], "scope_strict": true, "note": "The real --id is a recycle-item ID from recycle list, not a normal Drive node ID."},
+    "drive star list": {"ambiguous": ["type", "types"], "scope_strict": true, "note": "Content types and resource types are separate arrays; a generic type list cannot choose one.", "scoped_aliases": {"order-field": "order-by", "sort-by": "order-by", "sort-field": "order-by"}},
+    "drive recent": {"ambiguous": ["type", "types"], "scope_strict": true, "note": "Creator type, operation type, and file type filters are distinct and keep their enum/list forms."},
+    "drive +recent": {"ambiguous": ["type", "types"], "scope_strict": true, "note": "Creator type, operation type, and file type filters are distinct and keep their enum/list forms."},
+    "drive +star-list": {"ambiguous": ["type", "types"], "scope_strict": true, "note": "The shortcut exposes only the API contentTypes filter. Generic type spellings may denote file extensions or node/resource types, so the current name-only layer must not guess the value domain."},
+    "drive +upload": {"ambiguous": ["destination-id", "space", "target-id"], "scoped_aliases": {"dentry-uuid": "node", "file-id": "node", "node-id": "node", "overwrite-node-id": "node", "directory-id": "folder", "parent-directory-id": "folder", "parent-folder-id": "folder", "target-folder-id": "folder", "source-file": "file", "local-file": "file", "file-path": "file", "content-type": "mime-type", "filename": "file-name", "name": "file-name", "display-name": "file-name", "upload-name": "file-name"}, "block": ["dentry-id", "document-url", "knowledge-base-id", "wiki-workspace-id", "workspace", "workspace-id", "output-path"], "scope_strict": true, "note": "Local source path, remote display name, MIME type, parent folder, numeric storage space and optional overwrite node are distinct roles. ID-suffixed file/node spellings denote the overwrite target; the shortcut does not expose a knowledge-base workspace route."}
   },
 
   "validation_fixture": {
@@ -243,7 +319,7 @@
       {"command": "doc +export-get", "emitted": "node", "expect": "did-you-mean:blocked", "via": "override:block", "occ": 2},
       {"command": "doc block delete", "emitted": "index", "expect": "did-you-mean:blocked", "via": "override:block", "occ": 2},
       {"command": "doc block insert", "emitted": "before-block-id", "expect": "did-you-mean:blocked", "via": "guard:requires-multi-parameter-transform", "occ": 2},
-      {"command": "drive info", "emitted": "workspace", "expect": "space-id", "via": "concept:space_id", "occ": 2},
+      {"command": "drive info", "emitted": "workspace", "expect": "space-id", "via": "override:published-storage-space-compatibility", "occ": 2},
       {"command": "mail folder update", "emitted": "folder-id", "expect": "id", "via": "override:bind(folder_id)", "occ": 2},
       {"command": "report outbox list", "emitted": "template-type", "expect": "did-you-mean:blocked", "via": "override:block", "occ": 2},
       {"command": "chat +group-members", "emitted": "group-name", "expect": "group", "via": "concept:group_name+bind"},
@@ -325,7 +401,7 @@
       {"command": "doc +search", "emitted": "q", "expect": "query", "via": "concept:search_query"},
       {"command": "doc +comment-list", "emitted": "max-results", "expect": "limit", "via": "concept:pagination_size"},
       {"command": "doc +list", "emitted": "page-token", "expect": "cursor", "via": "concept:page_cursor"},
-      {"command": "doc +copy", "emitted": "workspace-id", "expect": "workspace", "via": "concept:space_id"},
+      {"command": "doc +copy", "emitted": "workspace-id", "expect": "workspace", "via": "concept:workspace_id"},
       {"command": "doc +copy", "emitted": "parent-folder-id", "expect": "folder", "via": "override:scoped-doc-folder"},
       {"command": "doc +copy", "emitted": "parent-id", "expect": "did-you-mean:blocked", "via": "guard:doc-folder-value-domain"},
       {"command": "doc +comment-reply", "emitted": "comment-id", "expect": "comment-key", "via": "concept:doc_comment_key"},
@@ -415,9 +491,9 @@
       {"command": "doc +create", "emitted": "content-format", "expect": "doc-format", "via": "concept:doc_content_format"},
       {"command": "doc +create", "emitted": "content-file", "expect": "did-you-mean:blocked", "via": "guard:requires-file-read-transform"},
       {"command": "doc +inspect", "emitted": "include-versions", "expect": "include-history", "via": "override:scoped-section"},
-      {"command": "doc +inspect", "emitted": "include", "expect": "did-you-mean:blocked", "via": "guard:requires-value-dependent-flag-expansion"},
-      {"command": "doc +inspect", "emitted": "include-info", "expect": "did-you-mean:blocked", "via": "guard:base-info-always-returned"},
-      {"command": "doc +update", "emitted": "mode", "expect": "command", "via": "override:scoped-operation"},
+      {"command": "doc +inspect", "emitted": "include", "expect": "did-you-mean:blocked", "via": "guard:requires-value-dependent-flag-expansion", "occ": 1},
+      {"command": "doc +inspect", "emitted": "include-info", "expect": "did-you-mean:blocked", "via": "guard:base-info-always-returned", "occ": 1},
+      {"command": "doc +update", "emitted": "mode", "expect": "command", "via": "override:scoped-operation", "occ": 5},
       {"command": "doc +update", "emitted": "revision", "expect": "expected-revision", "via": "concept:doc_edit_revision"},
       {"command": "doc +update", "emitted": "version", "expect": "did-you-mean:blocked", "via": "guard:historical-version-vs-edit-revision"},
       {"command": "doc +fetch", "emitted": "start-block", "expect": "start-block-id", "via": "override:scoped-boundary-role"},
@@ -425,11 +501,154 @@
       {"command": "doc +access-grant", "emitted": "doc-id", "expect": "node", "via": "concept:doc_node_id"},
       {"command": "doc +history-revert", "emitted": "version-number", "expect": "version", "via": "concept:doc_version_number"},
       {"command": "doc +create-from-template", "emitted": "keyword", "expect": "query", "via": "concept:search_query"},
-      {"command": "doc +create-from-template", "emitted": "workspace-id", "expect": "workspace", "via": "concept:space_id"},
+      {"command": "doc +create-from-template", "emitted": "workspace-id", "expect": "workspace", "via": "concept:workspace_id"},
       {"command": "doc +create-from-template", "emitted": "parent-folder-id", "expect": "folder", "via": "override:scoped-doc-folder"},
       {"command": "doc +media-download", "emitted": "file-id", "expect": "did-you-mean:ambiguous", "via": "guard:document-node-vs-attachment-resource-role"},
       {"command": "doc +resource-update", "emitted": "url", "expect": "did-you-mean:ambiguous", "via": "guard:document-url-vs-image-url-role"},
-      {"command": "doc +share", "emitted": "node-id", "expect": "did-you-mean:blocked", "via": "guard:node-id-needs-url-conversion"}
+      {"command": "doc +share", "emitted": "node-id", "expect": "did-you-mean:blocked", "via": "guard:node-id-needs-url-conversion"},
+      {"command": "doc +copy", "emitted": "dentry-uuid", "expect": "node", "via": "concept:doc_node_id"},
+      {"command": "doc info", "emitted": "dentry-id", "expect": "did-you-mean:blocked", "via": "guard:dentry-id-vs-dentry-uuid"},
+      {"command": "doc create", "emitted": "knowledge-base-id", "expect": "workspace", "via": "concept:workspace_id"},
+      {"command": "doc create", "emitted": "space-id", "expect": "workspace", "via": "override:published-workspace-compatibility"},
+      {"command": "drive list", "emitted": "knowledge-base-id", "expect": "workspace", "via": "concept:workspace_id"},
+      {"command": "drive list", "emitted": "order-field", "expect": "order-by", "via": "override:scoped-sort-field"},
+      {"command": "drive info", "emitted": "dentry-uuid", "expect": "node", "via": "override:scoped-node-id"},
+      {"command": "drive info", "emitted": "dentry-id", "expect": "did-you-mean:blocked", "via": "guard:dentry-id-vs-dentry-uuid"},
+      {"command": "drive copy", "emitted": "target-folder-id", "expect": "folder", "via": "override:scoped-destination-folder"},
+      {"command": "drive copy", "emitted": "target-id", "expect": "did-you-mean:ambiguous", "via": "guard:destination-role-required"},
+      {"command": "drive search", "emitted": "created-after", "expect": "created-from", "via": "concept:created_time_start"},
+      {"command": "drive search", "emitted": "created-before", "expect": "created-to", "via": "concept:created_time_end"},
+      {"command": "drive search", "emitted": "modified-after", "expect": "modified-from", "via": "concept:drive_modified_time_start"},
+      {"command": "drive search", "emitted": "modified-before", "expect": "modified-to", "via": "concept:drive_modified_time_end"},
+      {"command": "drive search", "emitted": "creator-user-ids", "expect": "creator-uids", "via": "concept:creator_user_ids"},
+      {"command": "drive permission add", "emitted": "permission-role", "expect": "role", "via": "concept:document_permission_role"},
+      {"command": "drive permission list", "emitted": "role", "expect": "did-you-mean:blocked", "via": "guard:permission-role-vs-filter-role"},
+      {"command": "drive upload", "emitted": "source-file", "expect": "file", "via": "override:scoped-local-file"},
+      {"command": "doc +search", "emitted": "created-after", "expect": "created-from", "via": "concept:created_time_start"},
+      {"command": "doc +search", "emitted": "create-time-start", "expect": "created-from", "via": "concept:created_time_start", "occ": 1},
+      {"command": "doc +search", "emitted": "create-time-end", "expect": "created-to", "via": "concept:created_time_end", "occ": 1},
+      {"command": "doc +search", "emitted": "creator-user-ids", "expect": "creator-uids", "via": "concept:creator_user_ids"},
+      {"command": "doc +access-grant", "emitted": "permission-role", "expect": "role", "via": "concept:document_permission_role"},
+      {"command": "doc +export", "emitted": "output-path", "expect": "output", "via": "concept:local_output_path"},
+      {"command": "drive download", "emitted": "destination-path", "expect": "output", "via": "concept:local_output_path"},
+      {"command": "drive download", "emitted": "version-number", "expect": "version", "via": "concept:doc_version_number"},
+      {"command": "drive recycle restore", "emitted": "recycle-item-id", "expect": "id", "via": "concept:drive_recycle_item_id"},
+      {"command": "drive upload-info", "emitted": "size-bytes", "expect": "file-size", "via": "concept:drive_file_size_bytes"},
+      {"command": "drive +info", "emitted": "drive-space-id", "expect": "space-id", "via": "concept:drive_storage_space_id"},
+      {"command": "drive commit", "emitted": "storage-space-id", "expect": "space-id", "via": "concept:drive_storage_space_id"},
+      {"command": "drive download", "emitted": "dingdrive-space-id", "expect": "space-id", "via": "concept:drive_storage_space_id"},
+      {"command": "drive info", "emitted": "drive-space-id", "expect": "space-id", "via": "concept:drive_storage_space_id"},
+      {"command": "drive list", "emitted": "storage-space-id", "expect": "space-id", "via": "concept:drive_storage_space_id"},
+      {"command": "drive list", "emitted": "sort-direction", "expect": "order", "via": "concept:drive_sort_direction"},
+      {"command": "drive mkdir", "emitted": "dingdrive-space-id", "expect": "space-id", "via": "concept:drive_storage_space_id"},
+      {"command": "drive recycle list", "emitted": "drive-space-id", "expect": "space-id", "via": "concept:drive_storage_space_id"},
+      {"command": "drive upload", "emitted": "storage-space-id", "expect": "space-id", "via": "concept:drive_storage_space_id"},
+      {"command": "drive upload-info", "emitted": "dingdrive-space-id", "expect": "space-id", "via": "concept:drive_storage_space_id"},
+      {"command": "doc +access-grant", "emitted": "user", "expect": "did-you-mean:ambiguous", "via": "guard:collaborator-name-vs-id-value-domain", "occ": 6},
+      {"command": "doc +access-grant", "emitted": "target-user", "expect": "did-you-mean:ambiguous", "via": "guard:collaborator-name-vs-id-value-domain", "occ": 1},
+      {"command": "doc +access-grant", "emitted": "user-id", "expect": "did-you-mean:blocked", "via": "guard:user-id-cannot-feed-name-resolver", "occ": 1},
+      {"command": "doc +access-grant", "emitted": "user-ids", "expect": "did-you-mean:blocked", "via": "guard:user-id-cannot-feed-name-resolver", "occ": 1},
+      {"command": "doc +access-grant", "emitted": "target-user-id", "expect": "did-you-mean:blocked", "via": "guard:user-id-cannot-feed-name-resolver"},
+      {"command": "doc +access-grant", "emitted": "target-user-ids", "expect": "did-you-mean:blocked", "via": "guard:user-id-cannot-feed-name-resolver"},
+      {"command": "doc +fetch", "emitted": "content-format", "expect": "did-you-mean:blocked", "via": "guard:content-format-vs-detail-contract", "occ": 3},
+      {"command": "doc +fetch", "emitted": "doc-format", "expect": "did-you-mean:blocked", "via": "guard:content-format-vs-detail-contract", "occ": 1},
+      {"command": "doc +fetch", "emitted": "range", "expect": "did-you-mean:blocked", "via": "guard:composite-range-needs-block-ids", "occ": 1},
+      {"command": "doc +inspect", "emitted": "include-access", "expect": "include-permissions", "via": "override:scoped-permission-section", "occ": 3},
+      {"command": "doc +inspect", "emitted": "include-member", "expect": "include-permissions", "via": "override:scoped-permission-section", "occ": 1},
+      {"command": "doc +inspect", "emitted": "include-members", "expect": "include-permissions", "via": "override:scoped-permission-section", "occ": 2},
+      {"command": "doc +inspect", "emitted": "include-meta", "expect": "did-you-mean:blocked", "via": "guard:base-metadata-already-returned", "occ": 2},
+      {"command": "doc +inspect", "emitted": "include-metadata", "expect": "did-you-mean:blocked", "via": "guard:base-metadata-already-returned", "occ": 1},
+      {"command": "doc +inspect", "emitted": "include-blocks", "expect": "did-you-mean:blocked", "via": "guard:content-read-belongs-to-fetch", "occ": 1},
+      {"command": "doc +inspect", "emitted": "include-content", "expect": "did-you-mean:blocked", "via": "guard:content-read-belongs-to-fetch", "occ": 1},
+      {"command": "doc +inspect", "emitted": "role", "expect": "did-you-mean:blocked", "via": "guard:permission-role-vs-document-node", "occ": 1},
+      {"command": "doc +copy", "emitted": "name", "expect": "did-you-mean:blocked", "via": "guard:fuzzy-name-vs-node-role", "occ": 2},
+      {"command": "doc +export", "emitted": "wait", "expect": "did-you-mean:blocked", "via": "guard:workflow-wait-vs-max-polls", "occ": 1},
+      {"command": "doc +media-insert", "emitted": "after-block-id", "expect": "did-you-mean:blocked", "via": "guard:requires-ref-block-and-where-expansion", "occ": 1},
+      {"command": "doc +media-insert", "emitted": "before-block-id", "expect": "did-you-mean:blocked", "via": "guard:requires-ref-block-and-where-expansion"},
+      {"command": "doc +update", "emitted": "content-file", "expect": "did-you-mean:blocked", "via": "guard:requires-file-read-transform", "occ": 1},
+      {"command": "doc +update", "emitted": "element", "expect": "did-you-mean:ambiguous", "via": "guard:content-vs-block-vs-reference-role", "occ": 1},
+      {"command": "doc update", "emitted": "stdin", "expect": "did-you-mean:blocked", "via": "guard:stdin-requires-content-dash-transform", "occ": 1},
+      {"command": "doc +version-save", "emitted": "title", "expect": "did-you-mean:blocked", "via": "guard:unsupported-version-metadata", "occ": 1},
+      {"command": "doc +version-save", "emitted": "message", "expect": "did-you-mean:blocked", "via": "guard:unsupported-version-metadata", "occ": 1},
+      {"command": "drive +search", "emitted": "keyword", "expect": "query", "via": "concept:search_query", "occ": 1},
+      {"command": "contact +search-user", "emitted": "name", "expect": "did-you-mean:blocked", "via": "guard:person-name-vs-search-query", "occ": 1},
+      {"command": "drive copy", "emitted": "name", "expect": "did-you-mean:blocked", "via": "guard:fuzzy-name-vs-node-role"},
+      {"command": "drive +copy", "emitted": "name", "expect": "did-you-mean:blocked", "via": "guard:fuzzy-name-vs-node-role"},
+      {"command": "drive move", "emitted": "name", "expect": "did-you-mean:blocked", "via": "guard:fuzzy-name-vs-node-role"},
+      {"command": "drive +move", "emitted": "name", "expect": "did-you-mean:blocked", "via": "guard:fuzzy-name-vs-node-role"},
+      {"command": "drive shortcut", "emitted": "name", "expect": "did-you-mean:blocked", "via": "guard:fuzzy-name-vs-node-role"},
+      {"command": "drive +cover", "emitted": "dentry-uuid", "expect": "node", "via": "override:scoped-drive-node"},
+      {"command": "drive +cover", "emitted": "name", "expect": "did-you-mean:blocked", "via": "guard:fuzzy-name-vs-drive-node"},
+      {"command": "drive +create-folder", "emitted": "folder-name", "expect": "name", "via": "override:scoped-folder-name"},
+      {"command": "drive +create-folder", "emitted": "storage-space-id", "expect": "space-id", "via": "concept:drive_storage_space_id"},
+      {"command": "drive +create-shortcut", "emitted": "source-file-id", "expect": "node", "via": "override:scoped-source-node"},
+      {"command": "drive +create-shortcut", "emitted": "target-folder-id", "expect": "folder", "via": "override:scoped-target-folder"},
+      {"command": "drive +create-shortcut", "emitted": "target-workspace-id", "expect": "workspace", "via": "override:scoped-target-workspace"},
+      {"command": "drive +create-shortcut", "emitted": "name", "expect": "did-you-mean:blocked", "via": "guard:fuzzy-name-vs-drive-node"},
+      {"command": "drive +delete", "emitted": "file-id", "expect": "node", "via": "override:scoped-drive-node"},
+      {"command": "drive +delete", "emitted": "dentry-id", "expect": "did-you-mean:blocked", "via": "guard:dentry-id-vs-node-id"},
+      {"command": "drive +download", "emitted": "dentry-uuid", "expect": "node", "via": "override:scoped-drive-node"},
+      {"command": "drive +download", "emitted": "destination-path", "expect": "output", "via": "concept:local_output_path"},
+      {"command": "drive +inspect", "emitted": "include-statistics", "expect": "include-stats", "via": "override:scoped-inspect-section"},
+      {"command": "drive +inspect", "emitted": "include-history", "expect": "did-you-mean:blocked", "via": "guard:doc-inspect-section"},
+      {"command": "drive +list", "emitted": "folder-id", "expect": "folder", "via": "concept:folder_id"},
+      {"command": "drive +list", "emitted": "page-size", "expect": "limit", "via": "concept:pagination_size"},
+      {"command": "drive +list", "emitted": "next-token", "expect": "cursor", "via": "concept:page_cursor"},
+      {"command": "drive +list", "emitted": "sort-direction", "expect": "order", "via": "concept:drive_sort_direction"},
+      {"command": "drive +list", "emitted": "sort-by", "expect": "order-by", "via": "override:scoped-sort-field"},
+      {"command": "drive +publish-get", "emitted": "dentry-uuid", "expect": "node", "via": "override:scoped-drive-node"},
+      {"command": "drive +publish-unset", "emitted": "file-id", "expect": "node", "via": "override:scoped-drive-node"},
+      {"command": "drive +recycle-list", "emitted": "storage-space-id", "expect": "space-id", "via": "concept:drive_storage_space_id"},
+      {"command": "drive +recycle-list", "emitted": "page-token", "expect": "cursor", "via": "concept:page_cursor"},
+      {"command": "drive +recycle-restore", "emitted": "recycle-item-id", "expect": "id", "via": "override:bind(drive_recycle_item_id)"},
+      {"command": "drive +recycle-restore", "emitted": "node-id", "expect": "did-you-mean:blocked", "via": "guard:recycle-item-vs-node-id"},
+      {"command": "drive +rename", "emitted": "file-id", "expect": "node", "via": "override:scoped-drive-node"},
+      {"command": "drive +rename", "emitted": "new-name", "expect": "name", "via": "override:scoped-display-name"},
+      {"command": "drive +star-add", "emitted": "dentry-uuid", "expect": "node", "via": "override:scoped-drive-node"},
+      {"command": "drive +star-list", "emitted": "max-results", "expect": "limit", "via": "concept:pagination_size"},
+      {"command": "drive +star-list", "emitted": "types", "expect": "did-you-mean:ambiguous", "via": "guard:content-type-value-domain"},
+      {"command": "drive +star-remove", "emitted": "file-id", "expect": "node", "via": "override:scoped-drive-node"},
+      {"command": "drive +stats", "emitted": "dentry-uuid", "expect": "node", "via": "override:scoped-drive-node"},
+      {"command": "drive +upload", "emitted": "source-file", "expect": "file", "via": "override:scoped-local-file"},
+      {"command": "drive +upload", "emitted": "name", "expect": "file-name", "via": "override:scoped-remote-name"},
+      {"command": "drive +upload", "emitted": "overwrite-node-id", "expect": "node", "via": "override:scoped-overwrite-node"},
+      {"command": "drive +upload", "emitted": "workspace-id", "expect": "did-you-mean:blocked", "via": "guard:unsupported-workspace-route"},
+      {"command": "drive +version-download", "emitted": "version-number", "expect": "version", "via": "concept:doc_version_number"},
+      {"command": "drive +version-download", "emitted": "save-path", "expect": "output", "via": "concept:local_output_path"},
+      {"command": "drive +version-get", "emitted": "version-no", "expect": "version", "via": "concept:doc_version_number"},
+      {"command": "drive +version-history", "emitted": "next-cursor", "expect": "cursor", "via": "concept:page_cursor"},
+      {"command": "drive +version-history", "emitted": "page-size", "expect": "limit", "via": "concept:pagination_size"},
+      {"command": "drive +version-revert", "emitted": "version-number", "expect": "version", "via": "concept:doc_version_number"},
+      {"command": "drive +version-revert", "emitted": "revision", "expect": "did-you-mean:blocked", "via": "guard:document-revision-vs-file-version"},
+      {"command": "drive +cover", "emitted": "node-id", "expect": "node", "via": "override:node-id-parity"},
+      {"command": "drive +create-shortcut", "emitted": "node-id", "expect": "node", "via": "override:node-id-parity"},
+      {"command": "drive +delete", "emitted": "node-id", "expect": "node", "via": "override:node-id-parity"},
+      {"command": "drive +download", "emitted": "node-id", "expect": "node", "via": "override:node-id-parity"},
+      {"command": "drive +inspect", "emitted": "node-id", "expect": "node", "via": "override:node-id-parity"},
+      {"command": "drive +publish-get", "emitted": "node-id", "expect": "node", "via": "override:node-id-parity"},
+      {"command": "drive +publish-unset", "emitted": "node-id", "expect": "node", "via": "override:node-id-parity"},
+      {"command": "drive +rename", "emitted": "node-id", "expect": "node", "via": "override:node-id-parity"},
+      {"command": "drive +star-add", "emitted": "node-id", "expect": "node", "via": "override:node-id-parity"},
+      {"command": "drive +star-remove", "emitted": "node-id", "expect": "node", "via": "override:node-id-parity"},
+      {"command": "drive +stats", "emitted": "node-id", "expect": "node", "via": "override:node-id-parity"},
+      {"command": "drive +upload", "emitted": "node-id", "expect": "node", "via": "override:node-id-parity"},
+      {"command": "drive +version-download", "emitted": "node-id", "expect": "node", "via": "override:node-id-parity"},
+      {"command": "drive +version-get", "emitted": "node-id", "expect": "node", "via": "override:node-id-parity"},
+      {"command": "drive +version-history", "emitted": "node-id", "expect": "node", "via": "override:node-id-parity"},
+      {"command": "drive +version-revert", "emitted": "node-id", "expect": "node", "via": "override:node-id-parity"},
+      {"command": "drive +cover", "emitted": "url", "expect": "node", "via": "override:existing-command-parity"},
+      {"command": "drive +create-shortcut", "emitted": "document-id", "expect": "node", "via": "override:existing-command-parity"},
+      {"command": "drive +delete", "emitted": "folder-id", "expect": "node", "via": "override:single-folder-node-role"},
+      {"command": "drive +inspect", "emitted": "document-id", "expect": "node", "via": "override:document-node-id"},
+      {"command": "drive +inspect", "emitted": "folder-id", "expect": "node", "via": "override:single-folder-node-role"},
+      {"command": "drive +publish-get", "emitted": "url", "expect": "node", "via": "override:existing-command-parity"},
+      {"command": "drive +publish-unset", "emitted": "document-url", "expect": "node", "via": "override:existing-command-parity"},
+      {"command": "drive +rename", "emitted": "document-id", "expect": "node", "via": "override:existing-command-parity"},
+      {"command": "drive +rename", "emitted": "folder-id", "expect": "node", "via": "override:single-folder-node-role"},
+      {"command": "drive +star-add", "emitted": "url", "expect": "node", "via": "override:existing-command-parity"},
+      {"command": "drive +star-remove", "emitted": "doc-id", "expect": "node", "via": "override:existing-command-parity"},
+      {"command": "drive +stats", "emitted": "document-url", "expect": "node", "via": "override:existing-command-parity"},
+      {"command": "drive +upload", "emitted": "file-id", "expect": "node", "via": "override:overwrite-node-id-role"}
     ]
   }
 }

internal/cli/schema_catalog_test.go

@@ -1356,6 +1356,7 @@ func TestDeliveryCatalogChatParamDeclsFrom87910880Reviewed(t *testing.T) {
 		{"chat message edit", "conversation-id", "openConversationId", true, ""},
 		{"chat message edit", "msg-id", "openMessageId", true, ""},
 		{"chat message edit", "at-open-dingtalk-ids", "atOpenDingTalkIds", false, "array"},
+		{"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, ""},
@@ -1407,6 +1408,14 @@ func TestDeliveryCatalogChatParamDeclsFrom87910880Reviewed(t *testing.T) {
 			t.Fatalf("chat message edit unexpectedly publishes hidden alias --%s", hidden)
 		}
 	}
+	sendLeaf, err = queryDeliverySchemaPayload([]string{"chat message send"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	sendParams = schemaMap(sendLeaf["parameters"])
+	if _, ok := sendParams["uuid"]; ok {
+		t.Fatal("chat message send unexpectedly publishes hidden alias --uuid")
+	}
 	listByConv, err := queryDeliverySchemaPayload([]string{"chat category list-by-conv"})
 	if err != nil {
 		t.Fatal(err)

internal/helpers/chat.go

@@ -18,6 +18,7 @@ import (
 	"unicode/utf8"
 
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/cli"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd"
 	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut/chatmsg"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut/targetresolver"
@@ -467,22 +468,50 @@ func validateNativeSearchConversationScope(conversationIDs []string) error {
 }
 
 func chatMessageListAllArgs(cmd *cobra.Command) (map[string]any, error) {
-	if err := validateRequiredFlags(cmd, "start", "end"); err != nil {
+	startRaw, endRaw, err := defaultChatMessageListAllTimeRange(cmd, 24*time.Hour)
+	if err != nil {
+		return nil, err
+	}
+	startMs, err := parseISOTimeToMillis("start", startRaw)
+	if err != nil {
+		return nil, err
+	}
+	endMs, err := parseISOTimeToMillis("end", endRaw)
+	if err != nil {
+		return nil, err
+	}
+	if err := validateTimeRange(startMs, endMs); err != nil {
 		return nil, err
 	}
 	cursor, _ := cmd.Flags().GetString("cursor")
 	return map[string]any{
-		"startTime": mustGetFlag(cmd, "start"),
-		"endTime":   mustGetFlag(cmd, "end"),
+		"startTime": startRaw,
+		"endTime":   endRaw,
 		"limit":     chatIntFlagOrFallback(cmd, "limit", "size"),
 		"cursor":    cursor,
 	}, nil
 }
 
-func chatMessageListBySenderArgs(cmd *cobra.Command) (map[string]any, error) {
-	if err := validateRequiredFlags(cmd, "start"); err != nil {
-		return nil, err
+func defaultChatMessageListAllTimeRange(cmd *cobra.Command, lookback time.Duration) (string, string, error) {
+	startRaw := mustGetFlag(cmd, "start")
+	endRaw := mustGetFlag(cmd, "end")
+	anchor := time.Now()
+	if endRaw == "" {
+		endRaw = formatChatMessageListAllTime(anchor.UnixMilli())
+	} else if startRaw == "" {
+		endMs, err := parseISOTimeToMillis("end", endRaw)
+		if err != nil {
+			return "", "", err
+		}
+		anchor = time.UnixMilli(endMs)
 	}
+	if startRaw == "" {
+		startRaw = formatChatMessageListAllTime(anchor.Add(-lookback).UnixMilli())
+	}
+	return startRaw, endRaw, nil
+}
+
+func chatMessageListBySenderArgs(cmd *cobra.Command) (map[string]any, error) {
 	senderUserID := flagOrFallback(cmd, "sender-user-id", "sender")
 	senderOpenDingTalkID, _ := cmd.Flags().GetString("sender-open-dingtalk-id")
 	if senderUserID != "" && senderOpenDingTalkID != "" {
@@ -491,13 +520,18 @@ func chatMessageListBySenderArgs(cmd *cobra.Command) (map[string]any, error) {
 	if senderUserID == "" && senderOpenDingTalkID == "" {
 		return nil, fmt.Errorf("--sender-user-id or --sender-open-dingtalk-id is required")
 	}
-	startMs, err := parseISOTimeToMillis("start", mustGetFlag(cmd, "start"))
+	if senderOpenDingTalkID != "" {
+		if err := targetresolver.ValidateExplicitOpenDingTalkID("--sender-open-dingtalk-id", senderOpenDingTalkID); err != nil {
+			return nil, err
+		}
+	}
+	startRaw, endRaw, err := defaultChatMessageTimeRange(cmd, 7*24*time.Hour)
 	if err != nil {
 		return nil, err
 	}
-	endRaw, _ := cmd.Flags().GetString("end")
-	if strings.TrimSpace(endRaw) == "" {
-		endRaw = time.Now().Format(time.RFC3339)
+	startMs, err := parseISOTimeToMillis("start", startRaw)
+	if err != nil {
+		return nil, err
 	}
 	endMs, err := parseISOTimeToMillis("end", endRaw)
 	if err != nil {
@@ -522,14 +556,15 @@ func chatMessageListBySenderArgs(cmd *cobra.Command) (map[string]any, error) {
 }
 
 func chatMessageListMentionsArgs(cmd *cobra.Command) (map[string]any, error) {
-	if err := validateRequiredFlags(cmd, "start", "end"); err != nil {
-		return nil, err
-	}
-	startMs, err := parseISOTimeToMillis("start", mustGetFlag(cmd, "start"))
+	startRaw, endRaw, err := defaultChatMessageTimeRange(cmd, 7*24*time.Hour)
 	if err != nil {
 		return nil, err
 	}
-	endMs, err := parseISOTimeToMillis("end", mustGetFlag(cmd, "end"))
+	startMs, err := parseISOTimeToMillis("start", startRaw)
+	if err != nil {
+		return nil, err
+	}
+	endMs, err := parseISOTimeToMillis("end", endRaw)
 	if err != nil {
 		return nil, err
 	}
@@ -564,14 +599,15 @@ func chatMessageSearchArgs(cmd *cobra.Command) (map[string]any, error) {
 	if err := validateRequiredFlagWithAliases(cmd, "query", "keyword"); err != nil {
 		return nil, err
 	}
-	if err := validateRequiredFlags(cmd, "start", "end"); err != nil {
-		return nil, err
-	}
-	startMs, err := parseISOTimeToMillis("start", mustGetFlag(cmd, "start"))
+	startRaw, endRaw, err := defaultChatMessageTimeRange(cmd, 7*24*time.Hour)
 	if err != nil {
 		return nil, err
 	}
-	endMs, err := parseISOTimeToMillis("end", mustGetFlag(cmd, "end"))
+	startMs, err := parseISOTimeToMillis("start", startRaw)
+	if err != nil {
+		return nil, err
+	}
+	endMs, err := parseISOTimeToMillis("end", endRaw)
 	if err != nil {
 		return nil, err
 	}
@@ -592,6 +628,33 @@ func chatMessageSearchArgs(cmd *cobra.Command) (map[string]any, error) {
 	return toolArgs, nil
 }
 
+func defaultChatMessageTimeRange(cmd *cobra.Command, lookback time.Duration) (string, string, error) {
+	startRaw := mustGetFlag(cmd, "start")
+	endRaw := mustGetFlag(cmd, "end")
+	anchor := time.Now()
+	if endRaw == "" {
+		endRaw = anchor.Format(time.RFC3339)
+	} else if startRaw == "" {
+		endMs, err := parseISOTimeToMillis("end", endRaw)
+		if err != nil {
+			return "", "", err
+		}
+		anchor = time.UnixMilli(endMs)
+	}
+	if startRaw == "" {
+		startRaw = anchor.Add(-lookback).Format(time.RFC3339)
+	}
+	return startRaw, endRaw, nil
+}
+
+func formatChatMessageListAllTime(ms int64) string {
+	return time.UnixMilli(ms).In(shanghaiLocation()).Format("2006-01-02 15:04:05")
+}
+
+func defaultChatMessageListTime() string {
+	return time.Now().In(shanghaiLocation()).Format("2006-01-02 15:04:05")
+}
+
 func chatMessageSearchAdvancedArgs(cmd *cobra.Command) (map[string]any, error) {
 	toolArgs := map[string]any{}
 	if v := flagOrFallback(cmd, "query", "keyword"); v != "" {
@@ -993,8 +1056,7 @@ func isNumericUserID(value string) bool {
 }
 
 func isOpenDingTalkID(value string) bool {
-	value = strings.TrimSpace(value)
-	return len(value) > 0 && (value[0] == 'D' || value[0] == 'd')
+	return targetresolver.LooksLikeCurrentDOpenDingTalkID(value)
 }
 
 // webhookErrcodeFailure 解析自定义机器人 webhook 的响应，判定是否发送失败。
@@ -2605,8 +2667,9 @@ func newChatCommand() *cobra.Command {
 	chatMessageListCmd := &cobra.Command{
 		Use:   "list",
 		Short: "拉取会话消息内容",
-		Long:  `拉取指定群聊或单聊的会话消息内容。输出顶层 messages，稳定字段为 messageId 和 text；兼容保留 openMessageId 和 content。--group 指定群聊，--user 指定单聊用户（userId），--open-dingtalk-id 指定单聊用户（openDingTalkId），三者互斥。推荐使用 --direction newer/older 控制时间方向：newer 表示从给定时间往现在拉，older 表示从给定时间往以前拉。hasMore=true 时用结果中的边界 createTime 作为下次 --time 翻页。引用回复消息会返回 quotedMessage 引用上下文；被引用的原消息是合并转发或图片时，对应的类型与内容也会随引用上下文返回。如果返回的会话消息中包含 openConvThreadId 字段，说明是话题消息，可以调用 dws chat message list-topic-replies 拉取话题回复消息列表，openConvThreadId 作为 topic-id 参数。`,
-		Example: `  dws chat message list --group <openconversation_id> --time "2025-03-01 00:00:00"
+		Long:  `拉取指定群聊或单聊的会话消息内容。输出顶层 messages，稳定字段为 messageId 和 text；兼容保留 openMessageId 和 content。--group 指定群聊，--user 指定单聊用户（userId），--open-dingtalk-id 指定单聊用户（openDingTalkId），三者互斥。--time 可选，不传时默认上海时间当前时间并向旧消息拉取。推荐使用 --direction newer/older 控制时间方向：newer 表示从给定时间往现在拉，older 表示从给定时间往以前拉。hasMore=true 时用结果中的边界 createTime 作为下次 --time 翻页。引用回复消息会返回 quotedMessage 引用上下文；被引用的原消息是合并转发或图片时，对应的类型与内容也会随引用上下文返回。如果返回的会话消息中包含 openConvThreadId 字段，说明是话题消息，可以调用 dws chat message list-topic-replies 拉取话题回复消息列表，openConvThreadId 作为 topic-id 参数。`,
+		Example: `  dws chat message list --group <openconversation_id>
+  dws chat message list --group <openconversation_id> --time "2025-03-01 00:00:00"
   dws chat message list --user <userId> --time "2025-03-01 00:00:00" --limit 50
   dws chat message list --open-dingtalk-id <openDingTalkId> --time "2025-03-01 00:00:00" --limit 50
   dws chat message list --group <openconversation_id> --time "2025-03-01 00:00:00" --direction older
@@ -2614,9 +2677,6 @@ func newChatCommand() *cobra.Command {
   # 查询群 ID: dws chat search --query "群名"
   # 查询 userId: dws contact user search --query "姓名"`,
 		RunE: func(cmd *cobra.Command, args []string) error {
-			if err := validateRequiredFlags(cmd, "time"); err != nil {
-				return err
-			}
 			groupID := flagOrFallback(cmd, "group", "conversation-id", "id", "chat")
 			userID, _ := cmd.Flags().GetString("user")
 			openDingTalkID, _ := cmd.Flags().GetString("open-dingtalk-id")
@@ -2636,15 +2696,25 @@ func newChatCommand() *cobra.Command {
 			if specified == 0 {
 				return fmt.Errorf("--group, --user or --open-dingtalk-id is required")
 			}
+			if openDingTalkID != "" {
+				if err := targetresolver.ValidateExplicitOpenDingTalkID("--open-dingtalk-id", openDingTalkID); err != nil {
+					return err
+				}
+			}
 			if userID != "" && isOpenDingTalkID(userID) {
 				openDingTalkID = userID
 				userID = ""
 			}
-			forward, err := resolveMessageForward(cmd, true)
+			timeVal := mustGetFlag(cmd, "time")
+			defaultForward := true
+			if timeVal == "" {
+				timeVal = defaultChatMessageListTime()
+				defaultForward = false
+			}
+			forward, err := resolveMessageForward(cmd, defaultForward)
 			if err != nil {
 				return err
 			}
-			timeVal := mustGetFlag(cmd, "time")
 			if groupID != "" {
 				toolArgs := map[string]any{
 					"openconversation_id": groupID,
@@ -2695,7 +2765,7 @@ func newChatCommand() *cobra.Command {
 				UseWhen:      []string{"用户明确指定某个会话，并要读取消息或追溯引用回复中的原消息上下文时"},
 				AvoidWhen:    []string{"跨全部会话按时间查询时使用 chat message list-all"},
 				Examples: []string{
-					"dws chat message list --group <openConversationId> --time \"2026-07-01 00:00:00\" --limit 50",
+					"dws chat message list --group <openConversationId> --limit 50",
 					"dws chat message list --group <openConversationId> --time \"2026-07-01 00:00:00\" --limit 50 --jq '.messages[] | {messageId, text}'",
 				},
 			},
@@ -2723,6 +2793,11 @@ func newChatCommand() *cobra.Command {
 			if userID == "" && openDingTalkID == "" {
 				return fmt.Errorf("--user or --open-dingtalk-id is required")
 			}
+			if openDingTalkID != "" {
+				if err := targetresolver.ValidateExplicitOpenDingTalkID("--open-dingtalk-id", openDingTalkID); err != nil {
+					return err
+				}
+			}
 			if userID != "" && isOpenDingTalkID(userID) {
 				openDingTalkID = userID
 				userID = ""
@@ -2730,7 +2805,7 @@ func newChatCommand() *cobra.Command {
 			timeVal, _ := cmd.Flags().GetString("time")
 			defaultForward := true
 			if strings.TrimSpace(timeVal) == "" {
-				timeVal = time.Now().Format("2006-01-02 15:04:05")
+				timeVal = defaultChatMessageListTime()
 				defaultForward = false
 			}
 			forward, err := resolveMessageForward(cmd, defaultForward)
@@ -2835,7 +2910,7 @@ func newChatCommand() *cobra.Command {
 			groupID := flagOrFallback(cmd, "group", "conversation-id", "id", "chat")
 			userID, _ := cmd.Flags().GetString("user")
 			openDingTalkID, _ := cmd.Flags().GetString("open-dingtalk-id")
-			msgUuid, _ := cmd.Flags().GetString("uuid")
+			msgUuid := flagOrFallback(cmd, "idempotency-key", "uuid")
 			specified := 0
 			if groupID != "" {
 				specified++
@@ -2852,6 +2927,11 @@ func newChatCommand() *cobra.Command {
 			if specified == 0 {
 				return fmt.Errorf("--group, --user or --open-dingtalk-id is required")
 			}
+			if openDingTalkID != "" {
+				if err := targetresolver.ValidateExplicitOpenDingTalkID("--open-dingtalk-id", openDingTalkID); err != nil {
+					return err
+				}
+			}
 			if userID != "" && isOpenDingTalkID(userID) {
 				openDingTalkID = userID
 				userID = ""
@@ -3050,6 +3130,7 @@ func newChatCommand() *cobra.Command {
 				{Name: "ai-tag", Property: "clawType", InterfaceType: "string"},
 				{Name: "at-open-dingtalk-ids", Property: "atOpenDingTalkIds"},
 				{Name: "group", Property: "openConversationId"},
+				{Name: "idempotency-key", Property: "uuid"},
 				{Name: "open-dingtalk-id", Property: "receiverOpenDingTalkId"},
 			},
 		},
@@ -3487,7 +3568,7 @@ func newChatCommand() *cobra.Command {
 	chatMessageListAllCmd := &cobra.Command{
 		Use:   "list-all",
 		Short: "拉取指定时间范围内当前用户的所有会话消息",
-		Long:  `分页拉取当前登录用户在指定时间范围内的所有会话消息。--start 和 --end 限定时间范围，--limit 指定每页数量，--cursor 传分页游标（首页传 0）。服务端按 cursor 分页返回，hasMore=true 时用返回的 nextCursor 值继续翻页。默认只读取单页；只有显式传 --page-all 才会自动翻页并保留、合并 result.conversationMessagesList，同一会话跨页合并 messages。只传 --page-limit、--max-items 或 --page-delay 仍保持单页调用。自动翻页时 --page-limit 控制最多请求页数，--max-items 按消息数精确截断，--page-delay 控制页间等待毫秒数。如果当前账号没有消息搜索权益，CLI 会保留服务端返回的友好提示与开通入口；不要把权限错误解释为时间范围内没有消息。`,
+		Long:  `分页拉取当前登录用户在指定时间范围内的所有会话消息。--start 和 --end 可选，不传时默认最近 1 天到当前时间，避免跨全部会话范围过大；--limit 指定每页数量，--cursor 传分页游标（首页传 0）。服务端按 cursor 分页返回，hasMore=true 时用返回的 nextCursor 值继续翻页。默认只读取单页；只有显式传 --page-all 才会自动翻页并保留、合并 result.conversationMessagesList，同一会话跨页合并 messages。只传 --page-limit、--max-items 或 --page-delay 仍保持单页调用。自动翻页时 --page-limit 控制最多请求页数，--max-items 按消息数精确截断，--page-delay 控制页间等待毫秒数。如果当前账号没有消息搜索权益，CLI 会保留服务端返回的友好提示与开通入口；不要把权限错误解释为时间范围内没有消息。`,
 		Example: `  dws chat message list-all --start "2025-03-01 00:00:00" --end "2025-03-31 23:59:59" --limit 50
   dws chat message list-all --start "2025-03-01 00:00:00" --end "2025-03-31 23:59:59" --limit 50 --cursor "abc123token"
   dws chat message list-all --start "2025-03-01 00:00:00" --end "2025-03-31 23:59:59" --limit 100 --page-all --page-limit 20 --max-items 500 --page-delay 0`,
@@ -3534,7 +3615,7 @@ func newChatCommand() *cobra.Command {
 	chatMessageListBySenderCmd := &cobra.Command{
 		Use:   "list-by-sender",
 		Short: "拉取指定发送者的消息（包含单聊和群聊）",
-		Long:  `搜索特定人发送给我的消息，返回结果包含单聊和群聊标识。--sender-user-id 指定发送者 userId，--sender-open-dingtalk-id 指定发送者 openDingTalkId，二者互斥。分页参数 --limit（默认 50）和 --cursor（默认 "0"）始终传递；hasMore=true 时用返回的 nextCursor 作为下次 --cursor 继续翻页。默认只读取单页；只有显式传 --page-all 才会自动翻页并保留、合并 result.conversationMessagesList，同一会话跨页合并 messages。只传 --page-limit、--max-items 或 --page-delay 仍保持单页调用。自动翻页时 --page-limit 控制最多请求页数，--max-items 按消息数精确截断，--page-delay 控制页间等待毫秒数。`,
+		Long:  `搜索特定人发送给我的消息，返回结果包含单聊和群聊标识。--sender-user-id 指定发送者 userId，--sender-open-dingtalk-id 指定发送者 openDingTalkId，二者互斥。--start 和 --end 可选，不传时默认最近 7 天到当前时间。分页参数 --limit（默认 50）和 --cursor（默认 "0"）始终传递；hasMore=true 时用返回的 nextCursor 作为下次 --cursor 继续翻页。默认只读取单页；只有显式传 --page-all 才会自动翻页并保留、合并 result.conversationMessagesList，同一会话跨页合并 messages。只传 --page-limit、--max-items 或 --page-delay 仍保持单页调用。自动翻页时 --page-limit 控制最多请求页数，--max-items 按消息数精确截断，--page-delay 控制页间等待毫秒数。`,
 		Example: `  dws chat message list-by-sender --sender-user-id <userId> --start "2026-03-10T00:00:00+08:00" --end "2026-03-11T00:00:00+08:00" --limit 50 --cursor 0
   dws chat message list-by-sender --sender-open-dingtalk-id <openDingTalkId> --start "2026-03-10T00:00:00+08:00" --end "2026-03-11T00:00:00+08:00" --limit 50 --cursor 0
   dws chat message list-by-sender --sender-user-id <userId> --start "2026-03-10T00:00:00+08:00" --end "2026-03-10T23:59:59+08:00" --limit 20 --cursor 0
@@ -3586,7 +3667,7 @@ func newChatCommand() *cobra.Command {
 	chatMessageListMentionsCmd := &cobra.Command{
 		Use:   "list-mentions",
 		Short: "拉取 @我 的消息",
-		Long:  `搜索时间范围内 @我 的消息，可选指定群聊。返回结果包含单聊和群聊标识。分页参数 --limit（默认 50）和 --cursor（默认 "0"）始终传递；hasMore=true 时用返回的 nextCursor 作为下次 --cursor 继续翻页。默认只读取单页；只有显式传 --page-all 才会自动翻页并保留、合并 result.conversationMessagesList，同一会话跨页合并 messages。只传 --page-limit、--max-items 或 --page-delay 仍保持单页调用。自动翻页时 --page-limit 控制最多请求页数，--max-items 按消息数精确截断，--page-delay 控制页间等待毫秒数。`,
+		Long:  `搜索时间范围内 @我 的消息，可选指定群聊。--start 和 --end 可选，不传时默认最近 7 天到当前时间。返回结果包含单聊和群聊标识。分页参数 --limit（默认 50）和 --cursor（默认 "0"）始终传递；hasMore=true 时用返回的 nextCursor 作为下次 --cursor 继续翻页。默认只读取单页；只有显式传 --page-all 才会自动翻页并保留、合并 result.conversationMessagesList，同一会话跨页合并 messages。只传 --page-limit、--max-items 或 --page-delay 仍保持单页调用。自动翻页时 --page-limit 控制最多请求页数，--max-items 按消息数精确截断，--page-delay 控制页间等待毫秒数。`,
 		Example: `  dws chat message list-mentions --start "2026-03-10T00:00:00+08:00" --end "2026-03-11T00:00:00+08:00" --limit 50 --cursor 0
   dws chat message list-mentions --start "2026-04-01T00:00:00+08:00" --end "2026-04-14T00:00:00+08:00" --limit 20 --cursor 0
   dws chat message list-mentions --group <openconversation_id> --start "2026-03-10T00:00:00+08:00" --end "2026-03-11T00:00:00+08:00" --limit 50 --cursor 0
@@ -3774,7 +3855,7 @@ func newChatCommand() *cobra.Command {
 	chatMessageSearchCmd := &cobra.Command{
 		Use:   "search",
 		Short: "按关键词搜索消息",
-		Long:  `在当前用户的会话中按关键词搜索消息。输出顶层 messages，稳定字段为 messageId 和 text；兼容保留 openMessageId、content 和原始 result。--query 指定搜索关键词（必填）。可选 --group 限定搜索某个会话，不传则搜索所有会话。显式指定会话时，CLI 会先验证 CID，再扫描全局搜索流并在本地精确过滤，避免下层忽略非法 CID 或群聊 CID；默认最多扫描 40 页并返回至 --limit 条范围内消息。时间参数 --start/--end（ISO-8601）限定搜索时间范围。分页参数 --limit（默认 100）和 --cursor（默认 "0"）始终传递；hasMore=true 时用返回的 nextCursor 作为下次 --cursor 继续翻页。未指定会话时默认只读取单页；只有显式传 --page-all 才会自动翻页并保留、合并 result.conversationMessagesList，同一会话跨页合并 messages。只传 --page-limit、--max-items 或 --page-delay 仍保持默认行为。自动翻页时 --page-limit 控制最多请求页数，--max-items 按消息数精确截断，--page-delay 控制页间等待毫秒数。`,
+		Long:  `在当前用户的会话中按关键词搜索消息。输出顶层 messages，稳定字段为 messageId 和 text；兼容保留 openMessageId、content 和原始 result。--query 指定搜索关键词（必填）。可选 --group 限定搜索某个会话，不传则搜索所有会话。显式指定会话时，CLI 会先验证 CID，再扫描全局搜索流并在本地精确过滤，避免下层忽略非法 CID 或群聊 CID；默认最多扫描 40 页并返回至 --limit 条范围内消息。时间参数 --start/--end（ISO-8601）可选，不传时默认最近 7 天到当前时间。分页参数 --limit（默认 100）和 --cursor（默认 "0"）始终传递；hasMore=true 时用返回的 nextCursor 作为下次 --cursor 继续翻页。未指定会话时默认只读取单页；只有显式传 --page-all 才会自动翻页并保留、合并 result.conversationMessagesList，同一会话跨页合并 messages。只传 --page-limit、--max-items 或 --page-delay 仍保持默认行为。自动翻页时 --page-limit 控制最多请求页数，--max-items 按消息数精确截断，--page-delay 控制页间等待毫秒数。`,
 		Example: `  dws chat message search --query "changefree" --start "2026-04-01T00:00:00+08:00" --end "2026-04-15T00:00:00+08:00" --limit 50 --cursor 0
   dws chat message search --query "codereview" --group <openconversation_id> --start "2026-04-01T00:00:00+08:00" --end "2026-04-15T00:00:00+08:00" --limit 100 --cursor 0
   dws chat message search --query "链接" --start "2026-04-15T00:00:00+08:00" --end "2026-04-16T00:00:00+08:00" --limit 100 --cursor <nextCursor>
@@ -4332,9 +4413,9 @@ chat message edit 或 chat message recall 的 --msg-id 和 --conversation-id。
 	chatMessageListCmd.Flags().String("group", "", "群聊 openconversation_id（群聊时必填）")
 	chatMessageListCmd.Flags().String("user", "", "单聊用户 userId（单聊时与 --open-dingtalk-id 二选一）")
 	chatMessageListCmd.Flags().String("open-dingtalk-id", "", "单聊用户 openDingTalkId（单聊时与 --user 二选一，适用于无法获取 userId 的场景）")
-	chatMessageListCmd.Flags().String("time", "", "开始时间，格式: yyyy-MM-dd HH:mm:ss (必填)")
-	chatMessageListCmd.Flags().String("direction", "", "时间方向: newer=从给定时间往现在拉，older=从给定时间往以前拉（推荐）")
-	chatMessageListCmd.Flags().String("forward", "true", "true 等价 --direction newer，false 等价 --direction older")
+	chatMessageListCmd.Flags().String("time", "", "开始时间，格式: yyyy-MM-dd HH:mm:ss（可选，默认当前时间）")
+	chatMessageListCmd.Flags().String("direction", "", "时间方向: newer=从给定时间往现在拉，older=从给定时间往以前拉（未传 --time 时默认 older）")
+	chatMessageListCmd.Flags().String("forward", "true", "true 等价 --direction newer，false 等价 --direction older（未传 --time 时默认 false）")
 	_ = chatMessageListCmd.Flags().MarkHidden("forward")
 	chatMessageListCmd.Flags().Int("limit", 0, "返回数量，不传则不限制")
 	chatMessageListCmd.Flags().Int("size", 0, "--limit 的旧版别名")
@@ -4385,7 +4466,11 @@ chat message edit 或 chat message recall 的 --msg-id 和 --conversation-id。
 	_ = chatMessageSendCmd.Flags().MarkHidden("file-type")
 	_ = chatMessageSendCmd.Flags().MarkHidden("file-size")
 	chatMessageSendCmd.Flags().Bool("ai-tag", true, "消息是否带 AI 发送角标（默认 true）")
-	chatMessageSendCmd.Flags().String("uuid", "", "幂等 UUID，相同 uuid 在 24h 内不会重复发送（可选）")
+	corecmd.RegisterFlags(chatMessageSendCmd, []corecmd.FlagSpec{{
+		Name:    "idempotency-key",
+		Usage:   "幂等键，相同 key 在 24h 内不会重复发送（可选）",
+		Aliases: []string{"uuid"},
+	}})
 	cli.AttachRuntimeSchema(chatMessageSendCmd, "chat", "send_personal_message", "hardcoded:chat")
 	cli.AnnotateRuntimeConstraints(chatMessageSendCmd, cli.RuntimeSchemaConstraints{
 		MutuallyExclusive: [][]string{{"group", "user", "open-dingtalk-id"}},
@@ -4448,10 +4533,8 @@ chat message edit 或 chat message recall 的 --msg-id 和 --conversation-id。
 	chatMessageListTopicRepliesCmd.Flags().String("forward", "false", "true 等价 --direction newer，false 等价 --direction older（默认 false）")
 	_ = chatMessageListTopicRepliesCmd.Flags().MarkHidden("forward")
 
-	chatMessageListAllCmd.Flags().String("start", "", "起始时间，格式: yyyy-MM-dd HH:mm:ss (必填)")
-	_ = chatMessageListAllCmd.MarkFlagRequired("start")
-	chatMessageListAllCmd.Flags().String("end", "", "结束时间，格式: yyyy-MM-dd HH:mm:ss (必填)")
-	_ = chatMessageListAllCmd.MarkFlagRequired("end")
+	chatMessageListAllCmd.Flags().String("start", "", "起始时间，格式: yyyy-MM-dd HH:mm:ss（可选，默认当前时间前 1 天）")
+	chatMessageListAllCmd.Flags().String("end", "", "结束时间，格式: yyyy-MM-dd HH:mm:ss（可选，默认当前时间）")
 	chatMessageListAllCmd.Flags().Int("limit", 50, "每页返回数量（默认 50）")
 	chatMessageListAllCmd.Flags().Int("size", 0, "--limit 的旧版别名")
 	_ = chatMessageListAllCmd.Flags().MarkHidden("size")
@@ -4465,9 +4548,8 @@ chat message edit 或 chat message recall 的 --msg-id 和 --conversation-id。
 	chatMessageListBySenderCmd.Flags().String("sender-open-dingtalk-id", "", "发送者 openDingTalkId（与 --sender-user-id 二选一，适用于无法获取 userId 的场景）")
 	chatMessageListBySenderCmd.Flags().String("user", "", "")
 	_ = chatMessageListBySenderCmd.Flags().MarkHidden("user")
-	chatMessageListBySenderCmd.Flags().String("start", "", "开始时间，ISO-8601 格式 (必填)")
-	_ = chatMessageListBySenderCmd.MarkFlagRequired("start")
-	chatMessageListBySenderCmd.Flags().String("end", "", "结束时间，ISO-8601 格式 (必填)")
+	chatMessageListBySenderCmd.Flags().String("start", "", "开始时间，ISO-8601 格式（可选，默认当前时间前 7 天）")
+	chatMessageListBySenderCmd.Flags().String("end", "", "结束时间，ISO-8601 格式（可选，默认当前时间）")
 	chatMessageListBySenderCmd.Flags().Int("limit", 50, "每页返回数量（默认 50）")
 	chatMessageListBySenderCmd.Flags().Int("size", 0, "--limit 的旧版别名")
 	_ = chatMessageListBySenderCmd.Flags().MarkHidden("size")
@@ -4476,10 +4558,8 @@ chat message edit 或 chat message recall 的 --msg-id 和 --conversation-id。
 
 	// list-mentions flags
 	chatMessageListMentionsCmd.Flags().String("group", "", "群聊 openconversation_id（可选，不传则查全部）")
-	chatMessageListMentionsCmd.Flags().String("start", "", "开始时间，ISO-8601 格式 (必填)")
-	_ = chatMessageListMentionsCmd.MarkFlagRequired("start")
-	chatMessageListMentionsCmd.Flags().String("end", "", "结束时间，ISO-8601 格式 (必填)")
-	_ = chatMessageListMentionsCmd.MarkFlagRequired("end")
+	chatMessageListMentionsCmd.Flags().String("start", "", "开始时间，ISO-8601 格式（可选，默认当前时间前 7 天）")
+	chatMessageListMentionsCmd.Flags().String("end", "", "结束时间，ISO-8601 格式（可选，默认当前时间）")
 	chatMessageListMentionsCmd.Flags().Int("limit", 50, "每页返回数量（默认 50）")
 	chatMessageListMentionsCmd.Flags().Int("size", 0, "--limit 的旧版别名")
 	_ = chatMessageListMentionsCmd.Flags().MarkHidden("size")
@@ -4504,10 +4584,8 @@ chat message edit 或 chat message recall 的 --msg-id 和 --conversation-id。
 	chatMessageSearchCmd.Flags().String("keyword", "", "--query 的别名")
 	_ = chatMessageSearchCmd.Flags().MarkHidden("keyword")
 	chatMessageSearchCmd.Flags().String("group", "", "群聊 openconversation_id（可选，不传则搜索所有会话）")
-	chatMessageSearchCmd.Flags().String("start", "", "开始时间，ISO-8601 格式 (必填)")
-	_ = chatMessageSearchCmd.MarkFlagRequired("start")
-	chatMessageSearchCmd.Flags().String("end", "", "结束时间，ISO-8601 格式 (必填)")
-	_ = chatMessageSearchCmd.MarkFlagRequired("end")
+	chatMessageSearchCmd.Flags().String("start", "", "开始时间，ISO-8601 格式（可选，默认当前时间前 7 天）")
+	chatMessageSearchCmd.Flags().String("end", "", "结束时间，ISO-8601 格式（可选，默认当前时间）")
 	chatMessageSearchCmd.Flags().Int("limit", 100, "每页返回数量（默认 100）")
 	chatMessageSearchCmd.Flags().Int("size", 0, "--limit 的旧版别名")
 	_ = chatMessageSearchCmd.Flags().MarkHidden("size")
@@ -4667,9 +4745,10 @@ chat message edit 或 chat message recall 的 --msg-id 和 --conversation-id。
 
 			userID := rawUserID
 			openDingTalkID := rawOpenDingTalkID
-			if openDingTalkID != "" && !isOpenDingTalkID(openDingTalkID) {
-				userID = openDingTalkID
-				openDingTalkID = ""
+			if openDingTalkID != "" {
+				if err := targetresolver.ValidateExplicitOpenDingTalkID("--open-dingtalk-id", openDingTalkID); err != nil {
+					return err
+				}
 			}
 			if userID != "" && isOpenDingTalkID(userID) {
 				openDingTalkID = userID
@@ -5917,6 +5996,9 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成
 		Short: "下载消息中的资源（图片/视频/语音等）到本地",
 		Long: `下载聊天消息中的图片、视频、语音等资源到本地文件。
 
+本命令只支持聊天消息 mediaId 下载，不支持钉盘 fileId。
+如需用 fileId 下载，请使用钉盘/drive 下载命令。
+
 流程:
   1. 根据 resourceType + resource-id + message-id + open-conversation-id 向服务端获取下载 URL
   2. HTTP GET 下载文件到本地
@@ -5927,6 +6009,7 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成
   dws chat message download-media --type mediaId --resource-id <mediaId> --message-id <openMessageId> --open-conversation-id <openConversationId> --output ./downloads/
   dws chat message download-media --type mediaId --resource-id <mediaId> --message-id <openMessageId> --open-conversation-id <openConversationId> --output ./photo.jpg
   # resource-id: 从 dws chat message list 返回的消息内容中获取 mediaId
+  # 不支持钉盘 fileId；fileId 下载请使用钉盘/drive 下载命令
   # message-id: 从 dws chat message list 返回的 openMessageId
   # open-conversation-id: 从 dws chat search 获取 openConversationId`,
 		PreRunE: func(cmd *cobra.Command, args []string) error {
@@ -6056,16 +6139,16 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成
 			Selection: contract.SelectionSpec{
 				AgentSummary: "下载消息中的媒体资源到本地",
 				UseWhen:      []string{"已知消息、会话和资源 ID，需要保存媒体文件时"},
-				AvoidWhen:    []string{"只查看文本消息内容时使用对应消息查询命令"},
+				AvoidWhen:    []string{"只查看文本消息内容时使用对应消息查询命令", "资源是钉盘 fileId 时使用钉盘/drive 下载命令"},
 				Examples:     []string{"dws chat message download-media --type mediaId --resource-id <mediaId> --message-id <openMessageId> --open-conversation-id <openConversationId> --output ."},
 			},
 		},
 	})
 
 	// download-media flags
-	chatMessageDownloadMediaCmd.Flags().String("type", "", "资源类型: mediaId (必填)")
+	chatMessageDownloadMediaCmd.Flags().String("type", "", "资源类型: mediaId（必填；仅支持聊天消息 mediaId，不支持钉盘 fileId）")
 	_ = chatMessageDownloadMediaCmd.MarkFlagRequired("type")
-	chatMessageDownloadMediaCmd.Flags().String("resource-id", "", "资源 ID，mediaId 类型时为消息中的 mediaId 值 (必填)")
+	chatMessageDownloadMediaCmd.Flags().String("resource-id", "", "资源 ID，mediaId 类型时为消息中的 mediaId 值（必填；不是钉盘 fileId）")
 	_ = chatMessageDownloadMediaCmd.MarkFlagRequired("resource-id")
 	chatMessageDownloadMediaCmd.Flags().String("open-conversation-id", "", "会话 openConversationId (必填)")
 	_ = chatMessageDownloadMediaCmd.MarkFlagRequired("open-conversation-id")

internal/helpers/chat_command_edges_test.go

@@ -160,6 +160,9 @@ func TestCrossPlatformCoverageChatCommandValidationAndSuccessEdges(t *testing.T)
 	os.Args = []string{"dws", "chat"}
 	t.Cleanup(func() { deps, os.Args = previousDeps, previousArgs })
 	caller := &productExampleCaller{}
+	if got := formatChatMessageListAllTime(0); got == "" {
+		t.Fatal("formatChatMessageListAllTime returned empty string")
+	}
 
 	commands := [][]string{
 		{"chmod", "chat.read", "--ttl="},
@@ -168,9 +171,17 @@ func TestCrossPlatformCoverageChatCommandValidationAndSuccessEdges(t *testing.T)
 		{"message", "list", "--user=D-user", "--time=2026-01-01", "--limit=1"},
 		{"message", "list", "--open-dingtalk-id=D-user", "--time=2026-01-01", "--direction=sideways"},
 		{"message", "list-direct", "--user=D-user", "--limit=1"},
+		{"message", "list-all"},
+		{"message", "list-all", "--end=2026-01-02T00:00:00Z"},
+		{"message", "list-all", "--end=bad"},
+		{"message", "list-all", "--start=not-a-time", "--end=2026-01-02T00:00:00Z"},
+		{"message", "list-all", "--start=2026-01-01 00:00:00", "--end=bad"},
+		{"message", "list-all", "--start=2026-01-02 00:00:00", "--end=2026-01-01 00:00:00"},
+		{"message", "list-all", "--start=2027-01-01 00:00:00"},
 		{"message", "list-by-sender", "--sender-user-id=u1", "--start=bad"},
 		{"message", "list-by-sender", "--sender-user-id=u1", "--start=2026-01-01T00:00:00Z", "--end=bad"},
 		{"message", "list-by-sender", "--sender-user-id=u1", "--start=2026-01-02T00:00:00Z", "--end=2026-01-01T00:00:00Z"},
+		{"message", "list-by-sender", "--sender-user-id=u1", "--end=2026-01-02T00:00:00Z"},
 		{"message", "list-by-sender", "--sender-user-id=u1", "--start=2026-01-01T00:00:00Z", "--end=2026-01-02T00:00:00Z"},
 		{"message", "list-by-sender", "--sender-open-dingtalk-id=D1", "--start=2026-01-01T00:00:00Z"},
 		{"message", "list-mentions", "--start=bad", "--end=2026-01-02T00:00:00Z"},

internal/helpers/chat_coverage_more_test.go

@@ -14,6 +14,11 @@ import (
 	"github.com/spf13/cobra"
 )
 
+const (
+	helperCurrentDOpenID  = "DAAAAAAAAAAAiE"
+	helperCurrentDOpenID2 = "DAQEBAQEBAQEiE"
+)
+
 func newChatFlagTestCommand() *cobra.Command {
 	cmd := &cobra.Command{Use: "chat"}
 	cmd.Flags().String("forward", "", "")
@@ -37,6 +42,22 @@ func newChatFlagTestCommand() *cobra.Command {
 	return cmd
 }
 
+func TestNativeChatIDSplitUsesCurrentDFormat(t *testing.T) {
+	userIDs, openIDs := splitChatIDValues([]string{
+		helperCurrentDOpenID,
+		"D-prefix-fixture-user",
+		"d-prefix-fixture-user",
+		"D-invalid",
+		"fixture-user-id",
+	})
+	if len(openIDs) != 1 || openIDs[0] != helperCurrentDOpenID {
+		t.Fatalf("open IDs=%#v", openIDs)
+	}
+	if got := strings.Join(userIDs, ","); got != "D-prefix-fixture-user,d-prefix-fixture-user,D-invalid,fixture-user-id" {
+		t.Fatalf("user IDs=%#v", userIDs)
+	}
+}
+
 func TestCrossPlatformCoverageChatDirectionAndScalarCoverage(t *testing.T) {
 	search := &cobra.Command{Use: "search"}
 	search.Flags().String("nicks", "", "")
@@ -151,18 +172,18 @@ func TestCrossPlatformCoverageChatContactMappingCoverage(t *testing.T) {
 }
 
 func TestCrossPlatformCoverageResolveOpenDingTalkIDsCoverage(t *testing.T) {
-	if id, err := resolveOpenDingTalkID(context.Background(), "D-direct"); err != nil || id != "D-direct" {
+	if id, err := resolveOpenDingTalkID(context.Background(), helperCurrentDOpenID); err != nil || id != helperCurrentDOpenID {
 		t.Fatalf("direct ID = %q, %v", id, err)
 	}
 	if _, err := resolveOpenDingTalkID(context.Background(), ""); err == nil {
 		t.Fatal("empty ID unexpectedly resolved")
 	}
-	if ids, err := resolveOpenDingTalkIDs(context.Background(), []string{" D1 ", ""}); err != nil || ids[0] != "D1" {
+	if ids, err := resolveOpenDingTalkIDs(context.Background(), []string{" " + helperCurrentDOpenID + " ", ""}); err != nil || ids[0] != helperCurrentDOpenID {
 		t.Fatalf("direct IDs = %#v, %v", ids, err)
 	}
-	caller := &scriptedToolCaller{steps: []scriptedToolStep{{text: `{"result":[{"userId":"u1","openDingTalkId":"D1"}]}`}}}
+	caller := &scriptedToolCaller{steps: []scriptedToolStep{{text: `{"result":[{"userId":"u1","openDingTalkId":"` + helperCurrentDOpenID2 + `"}]}`}}}
 	installScriptedCaller(t, caller)
-	if ids, err := resolveOpenDingTalkIDs(context.Background(), []string{"u1", "u1"}); err != nil || ids[1] != "D1" {
+	if ids, err := resolveOpenDingTalkIDs(context.Background(), []string{"u1", "u1"}); err != nil || ids[1] != helperCurrentDOpenID2 {
 		t.Fatalf("resolved IDs = %#v, %v", ids, err)
 	}
 	caller.steps = []scriptedToolStep{{text: `{}`}, {text: `{}`}}

internal/helpers/chat_file_path_send_test.go

@@ -178,7 +178,7 @@ func TestChatMessageSendFilePathUsesOpenDingTalkIDTarget(t *testing.T) {
 	caller := &chatFilePathCaller{}
 	commandArgs := []string{
 		"message", "send",
-		"--open-dingtalk-id=D-target",
+		"--open-dingtalk-id=" + helperCurrentDOpenID,
 		"--msg-type=file",
 		"--file-path=" + filePath,
 	}
@@ -203,7 +203,7 @@ func TestChatMessageSendFilePathUsesOpenDingTalkIDTarget(t *testing.T) {
 		server: "im",
 		tool:   "init_conversation_file_upload",
 		args: map[string]any{
-			"openDingTalkId": "D-target",
+			"openDingTalkId": helperCurrentDOpenID,
 			"fileName":       "report.pdf",
 			"fileSize":       int64(len(payload)),
 			"md5":            fileMD5,
@@ -216,7 +216,7 @@ func TestChatMessageSendFilePathUsesOpenDingTalkIDTarget(t *testing.T) {
 		server: "im",
 		tool:   "commit_conversation_file_upload",
 		args: map[string]any{
-			"openDingTalkId": "D-target",
+			"openDingTalkId": helperCurrentDOpenID,
 			"uploadKey":      "upload-key",
 			"fileName":       "report.pdf",
 			"fileSize":       int64(len(payload)),
@@ -231,7 +231,7 @@ func TestChatMessageSendFilePathUsesOpenDingTalkIDTarget(t *testing.T) {
 	if send.server != "chat" || send.tool != "send_personal_message" || send.args["msgType"] != "file" {
 		t.Fatalf("send direct target call = %#v", send)
 	}
-	if send.args["receiverOpenDingTalkId"] != "D-target" {
+	if send.args["receiverOpenDingTalkId"] != helperCurrentDOpenID {
 		t.Fatalf("send direct target = %#v", send.args)
 	}
 	if _, ok := send.args["openDingTalkId"]; ok {

internal/helpers/chat_message_help_test.go

@@ -90,3 +90,96 @@ func TestCrossPlatformCoverageChatMessageHelpDocumentsPostSendIDChain(t *testing
 		})
 	}
 }
+
+func TestCrossPlatformCoverageChatMessageHelpDocumentsOptionalTimeDefaults(t *testing.T) {
+	tests := []struct {
+		name     string
+		args     []string
+		contains []string
+		absent   []string
+	}{
+		{
+			name: "list",
+			args: []string{"message", "list", "--help"},
+			contains: []string{
+				"--time 可选，不传时默认上海时间当前时间并向旧消息拉取",
+				"默认上海时间当前时间",
+				"未传 --time 时默认 older",
+			},
+			absent: []string{"开始时间，格式: yyyy-MM-dd HH:mm:ss (必填)"},
+		},
+		{
+			name: "search",
+			args: []string{"message", "search", "--help"},
+			contains: []string{
+				"可选，不传时默认最近 7 天到当前时间",
+				"默认当前时间前 7 天",
+				"默认当前时间",
+			},
+			absent: []string{"开始时间，ISO-8601 格式 (必填)", "结束时间，ISO-8601 格式 (必填)"},
+		},
+		{
+			name: "list-by-sender",
+			args: []string{"message", "list-by-sender", "--help"},
+			contains: []string{
+				"--start 和 --end 可选，不传时默认最近 7 天到当前时间",
+				"默认当前时间前 7 天",
+				"默认当前时间",
+			},
+			absent: []string{"开始时间，ISO-8601 格式 (必填)", "结束时间，ISO-8601 格式 (必填)"},
+		},
+		{
+			name: "list-mentions",
+			args: []string{"message", "list-mentions", "--help"},
+			contains: []string{
+				"--start 和 --end 可选，不传时默认最近 7 天到当前时间",
+				"默认当前时间前 7 天",
+				"默认当前时间",
+			},
+			absent: []string{"开始时间，ISO-8601 格式 (必填)", "结束时间，ISO-8601 格式 (必填)"},
+		},
+		{
+			name: "list-all",
+			args: []string{"message", "list-all", "--help"},
+			contains: []string{
+				"--start 和 --end 可选，不传时默认最近 1 天到当前时间",
+				"默认当前时间前 1 天",
+				"默认当前时间",
+			},
+			absent: []string{"起始时间，格式: yyyy-MM-dd HH:mm:ss (必填)", "结束时间，格式: yyyy-MM-dd HH:mm:ss (必填)"},
+		},
+		{
+			name: "download-media",
+			args: []string{"message", "download-media", "--help"},
+			contains: []string{
+				"只支持聊天消息 mediaId 下载，不支持钉盘 fileId",
+				"fileId 下载请使用钉盘/drive 下载命令",
+				"仅支持聊天消息 mediaId，不支持钉盘 fileId",
+			},
+		},
+	}
+
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			cmd := newChatCommand()
+			var output bytes.Buffer
+			cmd.SetOut(&output)
+			cmd.SetErr(&output)
+			cmd.SetArgs(test.args)
+			if err := cmd.Execute(); err != nil {
+				t.Fatalf("dws chat %s: %v\n%s", strings.Join(test.args, " "), err, output.String())
+			}
+			help := output.String()
+			for _, want := range test.contains {
+				if !strings.Contains(help, want) {
+					t.Errorf("chat message %s help missing %q:\n%s", test.name, want, help)
+				}
+			}
+			for _, unwanted := range test.absent {
+				if strings.Contains(help, unwanted) {
+					t.Errorf("chat message %s help still contains %q:\n%s", test.name, unwanted, help)
+				}
+			}
+		})
+	}
+}

internal/helpers/chat_message_pagination_test.go

@@ -6,6 +6,7 @@ import (
 	"encoding/json"
 	"io"
 	"reflect"
+	"strings"
 	"testing"
 	"time"
 
@@ -148,6 +149,356 @@ func TestChatMessagePaginationDefaultSinglePageUnchanged(t *testing.T) {
 	}
 }
 
+func TestChatMessagePaginationUsesDefaultTimeWindows(t *testing.T) {
+	tests := []struct {
+		name         string
+		args         []string
+		wantTool     string
+		wantLookback time.Duration
+	}{
+		{
+			name:         "list-all defaults to one day",
+			args:         []string{"message", "list-all"},
+			wantTool:     "search_messages_by_time_range",
+			wantLookback: 24 * time.Hour,
+		},
+		{
+			name:         "list-by-sender defaults to seven days",
+			args:         []string{"message", "list-by-sender", "--sender-user-id", "u1"},
+			wantTool:     "search_messages_by_sender",
+			wantLookback: 7 * 24 * time.Hour,
+		},
+		{
+			name:         "list-mentions defaults to seven days",
+			args:         []string{"message", "list-mentions"},
+			wantTool:     "search_at_me_message",
+			wantLookback: 7 * 24 * time.Hour,
+		},
+		{
+			name:         "search defaults to seven days",
+			args:         []string{"message", "search", "--query", "发布"},
+			wantTool:     "search_messages_by_keyword",
+			wantLookback: 7 * 24 * time.Hour,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			caller := &chatMessagePaginationCaller{}
+			before := time.Now()
+			_, err := executeChatMessagePaginationCommand(t, caller, tt.args...)
+			after := time.Now()
+			if err != nil {
+				t.Fatal(err)
+			}
+			if len(caller.calls) != 1 {
+				t.Fatalf("calls = %#v, want one call", caller.calls)
+			}
+			got := caller.calls[0]
+			if got.tool != tt.wantTool {
+				t.Fatalf("tool = %q, want %q", got.tool, tt.wantTool)
+			}
+			startMs := chatMessageTimeArgAsMillis(t, got.args["startTime"], tt.wantTool)
+			endMs := chatMessageTimeArgAsMillis(t, got.args["endTime"], tt.wantTool)
+			wantEndMin := before.Truncate(time.Second).UnixMilli()
+			wantEndMax := after.Add(time.Second).UnixMilli()
+			if endMs < wantEndMin || endMs > wantEndMax {
+				t.Fatalf("endTime = %d, want between %d and %d", endMs, wantEndMin, wantEndMax)
+			}
+			wantStartMin := before.Add(-tt.wantLookback).Truncate(time.Second).UnixMilli()
+			wantStartMax := after.Add(-tt.wantLookback).Add(time.Second).UnixMilli()
+			if startMs < wantStartMin || startMs > wantStartMax {
+				t.Fatalf("startTime = %d, want between %d and %d", startMs, wantStartMin, wantStartMax)
+			}
+			if tt.wantTool == "search_messages_by_time_range" {
+				assertChatMessageListAllTimeFormat(t, got.args["startTime"])
+				assertChatMessageListAllTimeFormat(t, got.args["endTime"])
+			}
+		})
+	}
+}
+
+func TestChatMessagePaginationDefaultsStartFromExplicitEnd(t *testing.T) {
+	endRaw := "2026-01-01T00:00:00+08:00"
+	endMs, err := parseISOTimeToMillis("end", endRaw)
+	if err != nil {
+		t.Fatal(err)
+	}
+	tests := []struct {
+		name         string
+		args         []string
+		wantTool     string
+		wantLookback time.Duration
+	}{
+		{
+			name:         "list-all defaults start one day before explicit end",
+			args:         []string{"message", "list-all", "--end", endRaw},
+			wantTool:     "search_messages_by_time_range",
+			wantLookback: 24 * time.Hour,
+		},
+		{
+			name:         "list-by-sender defaults start seven days before explicit end",
+			args:         []string{"message", "list-by-sender", "--sender-user-id", "u1", "--end", endRaw},
+			wantTool:     "search_messages_by_sender",
+			wantLookback: 7 * 24 * time.Hour,
+		},
+		{
+			name:         "list-mentions defaults start seven days before explicit end",
+			args:         []string{"message", "list-mentions", "--end", endRaw},
+			wantTool:     "search_at_me_message",
+			wantLookback: 7 * 24 * time.Hour,
+		},
+		{
+			name:         "search defaults start seven days before explicit end",
+			args:         []string{"message", "search", "--query", "发布", "--end", endRaw},
+			wantTool:     "search_messages_by_keyword",
+			wantLookback: 7 * 24 * time.Hour,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			caller := &chatMessagePaginationCaller{}
+			_, err := executeChatMessagePaginationCommand(t, caller, tt.args...)
+			if err != nil {
+				t.Fatal(err)
+			}
+			if len(caller.calls) != 1 {
+				t.Fatalf("calls = %#v, want one call", caller.calls)
+			}
+			got := caller.calls[0]
+			if got.tool != tt.wantTool {
+				t.Fatalf("tool = %q, want %q", got.tool, tt.wantTool)
+			}
+			startMs := chatMessageTimeArgAsMillis(t, got.args["startTime"], tt.wantTool)
+			gotEndMs := chatMessageTimeArgAsMillis(t, got.args["endTime"], tt.wantTool)
+			if gotEndMs != endMs {
+				t.Fatalf("endTime = %d, want %d", gotEndMs, endMs)
+			}
+			wantStartMs := time.UnixMilli(endMs).Add(-tt.wantLookback).UnixMilli()
+			if startMs != wantStartMs {
+				t.Fatalf("startTime = %d, want %d", startMs, wantStartMs)
+			}
+			if tt.wantTool == "search_messages_by_time_range" {
+				assertStringArg(t, got.args["startTime"], formatChatMessageListAllTime(wantStartMs))
+				assertStringArg(t, got.args["endTime"], endRaw)
+			}
+		})
+	}
+}
+
+func TestChatMessageListAllDefaultStartFromTimezoneLessEndUsesShanghai(t *testing.T) {
+	previousLocal := time.Local
+	t.Cleanup(func() { time.Local = previousLocal })
+
+	for _, loc := range []*time.Location{time.UTC, time.FixedZone("EST", -5*3600)} {
+		t.Run(loc.String(), func(t *testing.T) {
+			time.Local = loc
+			caller := &chatMessagePaginationCaller{}
+			_, err := executeChatMessagePaginationCommand(t, caller, "message", "list-all", "--end", "2026-03-01 00:00:00")
+			if err != nil {
+				t.Fatal(err)
+			}
+			if len(caller.calls) != 1 {
+				t.Fatalf("calls = %#v, want one call", caller.calls)
+			}
+			got := caller.calls[0]
+			assertStringArg(t, got.args["endTime"], "2026-03-01 00:00:00")
+			assertStringArg(t, got.args["startTime"], "2026-02-28 00:00:00")
+
+			startMs, err := parseISOTimeToMillis("start", got.args["startTime"].(string))
+			if err != nil {
+				t.Fatal(err)
+			}
+			endMs, err := parseISOTimeToMillis("end", got.args["endTime"].(string))
+			if err != nil {
+				t.Fatal(err)
+			}
+			if gotWindow := time.Duration(endMs-startMs) * time.Millisecond; gotWindow != 24*time.Hour {
+				t.Fatalf("window = %v, want 24h", gotWindow)
+			}
+		})
+	}
+}
+
+func TestChatMessagePaginationDefaultsEndFromNowWhenOnlyStartProvided(t *testing.T) {
+	startRaw := "2026-01-01T00:00:00+08:00"
+	startMs, err := parseISOTimeToMillis("start", startRaw)
+	if err != nil {
+		t.Fatal(err)
+	}
+	tests := []struct {
+		name     string
+		args     []string
+		wantTool string
+	}{
+		{
+			name:     "list-all defaults end to now",
+			args:     []string{"message", "list-all", "--start", startRaw},
+			wantTool: "search_messages_by_time_range",
+		},
+		{
+			name:     "list-by-sender defaults end to now",
+			args:     []string{"message", "list-by-sender", "--sender-user-id", "u1", "--start", startRaw},
+			wantTool: "search_messages_by_sender",
+		},
+		{
+			name:     "list-mentions defaults end to now",
+			args:     []string{"message", "list-mentions", "--start", startRaw},
+			wantTool: "search_at_me_message",
+		},
+		{
+			name:     "search defaults end to now",
+			args:     []string{"message", "search", "--query", "发布", "--start", startRaw},
+			wantTool: "search_messages_by_keyword",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			caller := &chatMessagePaginationCaller{}
+			before := time.Now()
+			_, err := executeChatMessagePaginationCommand(t, caller, tt.args...)
+			after := time.Now()
+			if err != nil {
+				t.Fatal(err)
+			}
+			if len(caller.calls) != 1 {
+				t.Fatalf("calls = %#v, want one call", caller.calls)
+			}
+			got := caller.calls[0]
+			if got.tool != tt.wantTool {
+				t.Fatalf("tool = %q, want %q", got.tool, tt.wantTool)
+			}
+			gotStartMs := chatMessageTimeArgAsMillis(t, got.args["startTime"], tt.wantTool)
+			if gotStartMs != startMs {
+				t.Fatalf("startTime = %d, want %d", gotStartMs, startMs)
+			}
+			endMs := chatMessageTimeArgAsMillis(t, got.args["endTime"], tt.wantTool)
+			wantEndMin := before.Truncate(time.Second).UnixMilli()
+			wantEndMax := after.Add(time.Second).UnixMilli()
+			if endMs < wantEndMin || endMs > wantEndMax {
+				t.Fatalf("endTime = %d, want between %d and %d", endMs, wantEndMin, wantEndMax)
+			}
+			if tt.wantTool == "search_messages_by_time_range" {
+				assertStringArg(t, got.args["startTime"], startRaw)
+				assertChatMessageListAllTimeFormat(t, got.args["endTime"])
+			}
+		})
+	}
+}
+
+func TestChatMessageListAllRejectsInvalidTimeBounds(t *testing.T) {
+	tests := []struct {
+		name    string
+		args    []string
+		wantErr string
+	}{
+		{
+			name:    "invalid start",
+			args:    []string{"message", "list-all", "--start", "not-a-time", "--end", "2020-01-01T00:00:00+08:00"},
+			wantErr: "cannot parse time for --start",
+		},
+		{
+			name:    "end before start",
+			args:    []string{"message", "list-all", "--start", "2021-01-01T00:00:00+08:00", "--end", "2020-01-01T00:00:00+08:00"},
+			wantErr: "--end must be after --start",
+		},
+		{
+			name:    "default end before future start",
+			args:    []string{"message", "list-all", "--start", "2027-01-01 00:00:00"},
+			wantErr: "--end must be after --start",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			caller := &chatMessagePaginationCaller{}
+			_, err := executeChatMessagePaginationCommand(t, caller, tt.args...)
+			if err == nil {
+				t.Fatal("expected validation error, got nil")
+			}
+			if !strings.Contains(err.Error(), tt.wantErr) {
+				t.Fatalf("error = %q, want contains %q", err.Error(), tt.wantErr)
+			}
+			if len(caller.calls) != 0 {
+				t.Fatalf("calls = %#v, want no MCP call", caller.calls)
+			}
+		})
+	}
+}
+
+func numericArgAsInt64(t *testing.T, value any) int64 {
+	t.Helper()
+	switch v := value.(type) {
+	case int64:
+		return v
+	case int:
+		return int64(v)
+	case float64:
+		return int64(v)
+	case string:
+		parsed, err := parseISOTimeToMillis("time", v)
+		if err != nil {
+			t.Fatalf("parse time arg %q: %v", v, err)
+		}
+		return parsed
+	default:
+		t.Fatalf("unsupported numeric arg type %T (%#v)", value, value)
+		return 0
+	}
+}
+
+func chatMessageTimeArgAsMillis(t *testing.T, value any, tool string) int64 {
+	t.Helper()
+	if tool == "search_messages_by_time_range" {
+		return parseChatMessageListAllTimeArg(t, value).UnixMilli()
+	}
+	return numericArgAsInt64(t, value)
+}
+
+func parseChatMessageListAllTimeArg(t *testing.T, value any) time.Time {
+	t.Helper()
+	raw, ok := value.(string)
+	if !ok {
+		t.Fatalf("time arg = %#v, want time string", value)
+	}
+	if strings.Contains(raw, "T") {
+		parsedMs, err := parseISOTimeToMillis("time", raw)
+		if err != nil {
+			t.Fatalf("time arg = %q, parse err = %v", raw, err)
+		}
+		return time.UnixMilli(parsedMs)
+	}
+	parsedMs, err := parseISOTimeToMillis("time", raw)
+	if err != nil {
+		t.Fatalf("time arg = %q, parse err = %v", raw, err)
+	}
+	return time.UnixMilli(parsedMs)
+}
+
+func assertChatMessageListAllTimeFormat(t *testing.T, value any) {
+	t.Helper()
+	raw, ok := value.(string)
+	if !ok {
+		t.Fatalf("time arg = %#v, want time string", value)
+	}
+	if strings.Contains(raw, "T") {
+		t.Fatalf("time arg = %q, want yyyy-MM-dd HH:mm:ss without RFC3339 separator", raw)
+	}
+	if _, err := parseISOTimeToMillis("time", raw); err != nil {
+		t.Fatalf("time arg = %q, parse err = %v", raw, err)
+	}
+}
+
+func assertStringArg(t *testing.T, value any, want string) {
+	t.Helper()
+	got, ok := value.(string)
+	if !ok || got != want {
+		t.Fatalf("arg = %#v, want %q", value, want)
+	}
+}
+
 func TestChatMessagePaginationPageAllAggregatesSevenCommands(t *testing.T) {
 	tests := []struct {
 		name      string

internal/helpers/chat_message_search_test.go

@@ -724,6 +724,99 @@ func TestCrossPlatformCoverageChatMessageListUsesMCPMetadataGroupKey(t *testing.
 	}
 }
 
+func TestCrossPlatformCoverageChatMessageListDefaultTimeUsesShanghaiLocation(t *testing.T) {
+	previousLocal := time.Local
+	t.Cleanup(func() { time.Local = previousLocal })
+
+	tests := []struct {
+		name       string
+		args       []string
+		wantTool   string
+		wantTarget map[string]any
+	}{
+		{
+			name:       "group",
+			args:       []string{"message", "list", "--group", "cid-1", "--limit", "50"},
+			wantTool:   "list_conversation_message_v2",
+			wantTarget: map[string]any{"openconversation_id": "cid-1"},
+		},
+		{
+			name:       "user",
+			args:       []string{"message", "list", "--user", "user-1", "--limit", "50"},
+			wantTool:   "list_individual_chat_message",
+			wantTarget: map[string]any{"userId": "user-1"},
+		},
+		{
+			name:       "user open DingTalk ID fallback",
+			args:       []string{"message", "list", "--user", helperCurrentDOpenID, "--limit", "50"},
+			wantTool:   "list_individual_chat_message",
+			wantTarget: map[string]any{"openDingTalkId": helperCurrentDOpenID},
+		},
+		{
+			name:       "open DingTalk ID",
+			args:       []string{"message", "list", "--open-dingtalk-id", helperCurrentDOpenID, "--limit", "50"},
+			wantTool:   "list_individual_chat_message",
+			wantTarget: map[string]any{"openDingTalkId": helperCurrentDOpenID},
+		},
+		{
+			name:       "direct user",
+			args:       []string{"message", "list-direct", "--user", "user-1", "--limit", "50"},
+			wantTool:   "list_individual_chat_message",
+			wantTarget: map[string]any{"userId": "user-1"},
+		},
+		{
+			name:       "direct open DingTalk ID",
+			args:       []string{"message", "list-direct", "--open-dingtalk-id", helperCurrentDOpenID, "--limit", "50"},
+			wantTool:   "list_individual_chat_message",
+			wantTarget: map[string]any{"openDingTalkId": helperCurrentDOpenID},
+		},
+	}
+
+	for _, loc := range []*time.Location{time.UTC, time.FixedZone("EST", -5*3600)} {
+		t.Run(loc.String(), func(t *testing.T) {
+			time.Local = loc
+			for _, tt := range tests {
+				t.Run(tt.name, func(t *testing.T) {
+					caller := &chatChangedContractCaller{}
+					before := time.Now()
+					err := executeChatChangedContract(t, caller, tt.args...)
+					after := time.Now()
+					if err != nil {
+						t.Fatal(err)
+					}
+					if len(caller.calls) != 1 {
+						t.Fatalf("calls = %#v, want one MCP call", caller.calls)
+					}
+					if caller.calls[0].toolName != tt.wantTool {
+						t.Fatalf("tool = %q, want %q", caller.calls[0].toolName, tt.wantTool)
+					}
+					for key, want := range tt.wantTarget {
+						if got := caller.calls[0].args[key]; got != want {
+							t.Fatalf("arg %s = %#v, want %#v", key, got, want)
+						}
+					}
+					raw, ok := caller.calls[0].args["time"].(string)
+					if !ok || raw == "" {
+						t.Fatalf("time arg = %#v, want non-empty string", caller.calls[0].args["time"])
+					}
+					gotMs, err := parseISOTimeToMillis("time", raw)
+					if err != nil {
+						t.Fatalf("time arg = %q, parse err = %v", raw, err)
+					}
+					wantMin := before.Add(-time.Second).UnixMilli()
+					wantMax := after.Add(time.Second).UnixMilli()
+					if gotMs < wantMin || gotMs > wantMax {
+						t.Fatalf("time arg = %q (%d), want between %d and %d", raw, gotMs, wantMin, wantMax)
+					}
+					if caller.calls[0].args["forward"] != false {
+						t.Fatalf("forward = %#v, want false when --time is omitted", caller.calls[0].args["forward"])
+					}
+				})
+			}
+		})
+	}
+}
+
 func TestCrossPlatformCoverageChatAuditUsesUserIDs(t *testing.T) {
 	caller := &chatChangedContractCaller{}
 	err := executeChatChangedContract(t, caller,
@@ -786,11 +879,11 @@ func TestChatSendAndReplyDefaultToAgentProductForIMClawType(t *testing.T) {
 	}{
 		{
 			name: "send",
-			args: []string{"message", "send", "--open-dingtalk-id", "D1", "--text", "hello"},
+			args: []string{"message", "send", "--open-dingtalk-id", helperCurrentDOpenID, "--text", "hello"},
 		},
 		{
 			name: "reply",
-			args: []string{"message", "reply", "--conversation-id", "cid", "--ref-msg-id", "mid", "--ref-sender", "D1", "--text", "hello"},
+			args: []string{"message", "reply", "--conversation-id", "cid", "--ref-msg-id", "mid", "--ref-sender", helperCurrentDOpenID, "--text", "hello"},
 		},
 	}
 
@@ -819,11 +912,11 @@ func TestChatSendAndReplyDisableAITagWithEmptyClawType(t *testing.T) {
 	}{
 		{
 			name: "send",
-			args: []string{"message", "send", "--open-dingtalk-id", "D1", "--text", "hello", "--ai-tag=false"},
+			args: []string{"message", "send", "--open-dingtalk-id", helperCurrentDOpenID, "--text", "hello", "--ai-tag=false"},
 		},
 		{
 			name: "reply",
-			args: []string{"message", "reply", "--conversation-id", "cid", "--ref-msg-id", "mid", "--ref-sender", "D1", "--text", "hello", "--ai-tag=false"},
+			args: []string{"message", "reply", "--conversation-id", "cid", "--ref-msg-id", "mid", "--ref-sender", helperCurrentDOpenID, "--text", "hello", "--ai-tag=false"},
 		},
 	}
 
@@ -857,25 +950,25 @@ func TestCrossPlatformCoverageChatCurrentUserSendAndReplyMentions(t *testing.T)
 			name: "send",
 			args: []string{
 				"message", "send", "--group", "cid",
-				"--text", "收到 @D-target 和 <@D-second>",
-				"--at-open-dingtalk-ids", "D-target,D-second",
+				"--text", "收到 @" + helperCurrentDOpenID + " 和 <@" + helperCurrentDOpenID2 + ">",
+				"--at-open-dingtalk-ids", helperCurrentDOpenID + "," + helperCurrentDOpenID2,
 				"--at-all",
 			},
 			contentField: "text",
-			wantContent:  "<@all> 收到 <@D-target> 和 <@D-second>",
+			wantContent:  "<@all> 收到 <@" + helperCurrentDOpenID + "> 和 <@" + helperCurrentDOpenID2 + ">",
 			wantAtAll:    true,
-			wantOpenIDs:  []string{"D-target", "D-second"},
+			wantOpenIDs:  []string{helperCurrentDOpenID, helperCurrentDOpenID2},
 		},
 		{
 			name: "send keeps missing member placeholders unchanged",
 			args: []string{
 				"message", "send", "--group", "cid",
 				"--text", "DWS 发消息自测",
-				"--at-open-dingtalk-ids", "D-target",
+				"--at-open-dingtalk-ids", helperCurrentDOpenID,
 			},
 			contentField: "text",
 			wantContent:  "DWS 发消息自测",
-			wantOpenIDs:  []string{"D-target"},
+			wantOpenIDs:  []string{helperCurrentDOpenID},
 		},
 		{
 			name: "reply",
@@ -883,15 +976,15 @@ func TestCrossPlatformCoverageChatCurrentUserSendAndReplyMentions(t *testing.T)
 				"message", "reply",
 				"--conversation-id", "cid",
 				"--ref-msg-id", "mid",
-				"--ref-sender", "D-sender",
-				"--text", "收到 @D-target 和 <@D-second>",
-				"--at-open-dingtalk-ids", "D-target,D-second",
+				"--ref-sender", helperCurrentDOpenID,
+				"--text", "收到 @" + helperCurrentDOpenID + " 和 <@" + helperCurrentDOpenID2 + ">",
+				"--at-open-dingtalk-ids", helperCurrentDOpenID + "," + helperCurrentDOpenID2,
 				"--at-all",
 			},
 			contentField: "content",
-			wantContent:  "<@all> 收到 <@D-target> 和 <@D-second>",
+			wantContent:  "<@all> 收到 <@" + helperCurrentDOpenID + "> 和 <@" + helperCurrentDOpenID2 + ">",
 			wantAtAll:    true,
-			wantOpenIDs:  []string{"D-target", "D-second"},
+			wantOpenIDs:  []string{helperCurrentDOpenID, helperCurrentDOpenID2},
 		},
 		{
 			name: "reply adds missing member placeholders",
@@ -899,13 +992,13 @@ func TestCrossPlatformCoverageChatCurrentUserSendAndReplyMentions(t *testing.T)
 				"message", "reply",
 				"--conversation-id", "cid",
 				"--ref-msg-id", "mid",
-				"--ref-sender", "D-sender",
-				"--text", "DWS 回复艾特前津（非主用）自测",
-				"--at-open-dingtalk-ids", "D-target,D-second,D-target",
+				"--ref-sender", helperCurrentDOpenID,
+				"--text", "DWS synthetic reply mention test",
+				"--at-open-dingtalk-ids", helperCurrentDOpenID + "," + helperCurrentDOpenID2 + "," + helperCurrentDOpenID,
 			},
 			contentField: "content",
-			wantContent:  "<@D-target> <@D-second> DWS 回复艾特前津（非主用）自测",
-			wantOpenIDs:  []string{"D-target", "D-second", "D-target"},
+			wantContent:  "<@" + helperCurrentDOpenID + "> <@" + helperCurrentDOpenID2 + "> DWS synthetic reply mention test",
+			wantOpenIDs:  []string{helperCurrentDOpenID, helperCurrentDOpenID2, helperCurrentDOpenID},
 		},
 		{
 			name: "reply adds missing member placeholders after at-all",
@@ -913,15 +1006,15 @@ func TestCrossPlatformCoverageChatCurrentUserSendAndReplyMentions(t *testing.T)
 				"message", "reply",
 				"--conversation-id", "cid",
 				"--ref-msg-id", "mid",
-				"--ref-sender", "D-sender",
+				"--ref-sender", helperCurrentDOpenID,
 				"--text", "请大家确认",
-				"--at-open-dingtalk-ids", "D-target",
+				"--at-open-dingtalk-ids", helperCurrentDOpenID,
 				"--at-all",
 			},
 			contentField: "content",
-			wantContent:  "<@all> <@D-target> 请大家确认",
+			wantContent:  "<@all> <@" + helperCurrentDOpenID + "> 请大家确认",
 			wantAtAll:    true,
-			wantOpenIDs:  []string{"D-target"},
+			wantOpenIDs:  []string{helperCurrentDOpenID},
 		},
 		{
 			name: "reply at-all preserves alliance word",
@@ -929,7 +1022,7 @@ func TestCrossPlatformCoverageChatCurrentUserSendAndReplyMentions(t *testing.T)
 				"message", "reply",
 				"--conversation-id", "cid",
 				"--ref-msg-id", "mid",
-				"--ref-sender", "D-sender",
+				"--ref-sender", helperCurrentDOpenID,
 				"--text", "联系 @alliance",
 				"--at-all",
 			},
@@ -943,7 +1036,7 @@ func TestCrossPlatformCoverageChatCurrentUserSendAndReplyMentions(t *testing.T)
 				"message", "reply",
 				"--conversation-id", "cid",
 				"--ref-msg-id", "mid",
-				"--ref-sender", "D-sender",
+				"--ref-sender", helperCurrentDOpenID,
 				"--text", "联系 @alliance",
 			},
 			contentField: "content",

internal/helpers/drive.go

@@ -413,6 +413,13 @@ func newDriveCommand() *cobra.Command {
 				}
 			}
 
+			// --type/--start/--end 客户端过滤：激活即切 BFS 全量拉取后筛（两路由统一）；
+			// 未启用返回零值，存量分支字节级不变。互斥/非法值/start>end 在此拒绝。
+			filter, err := parseDriveListFilter(cmd)
+			if err != nil {
+				return err
+			}
+
 			// --versions 模式：列出文件历史版本（仅普通文件）
 			// 先于 --depth 校验执行：versions 模式合法使用 --limit，
 			// 不应被「--limit 与 --depth 不兼容」的误导性报错拦截。
@@ -454,7 +461,8 @@ func newDriveCommand() *cobra.Command {
 			if workspaceID != "" {
 				// depth>1 时 --pattern 放开（先递归后过滤）；--order-by/--space-id/--thumbnail
 				// 知识库无对应参数，静默忽略。
-				if depth > 1 || latest > 0 {
+				// filter 激活时 depth==1 也走 BFS 退化态（全量拉取→CLI 侧筛）。
+				if depth > 1 || latest > 0 || filter.active() {
 					quiet, _ := cmd.Flags().GetBool("quiet")
 					baseArgs := map[string]any{"workspaceId": workspaceID}
 					rootFolder := docFolderFlag(cmd, "node", "file-id")
@@ -463,7 +471,7 @@ func newDriveCommand() *cobra.Command {
 							return err
 						}
 					}
-					return runDriveListDepth(cmd, newDocDepthRoute(), baseArgs, rootFolder, depth, pattern, quiet, latest)
+					return runDriveListDepth(cmd, newDocDepthRoute(), baseArgs, rootFolder, depth, pattern, quiet, latest, filter)
 				}
 				if pattern != "" {
 					return &CLIError{
@@ -487,7 +495,9 @@ func newDriveCommand() *cobra.Command {
 				return callMCPToolOnServer("doc", "list_nodes", toolArgs)
 			}
 
-			if depth > 1 {
+			// 钉盘：filter 激活即 depth=1 单层退化态（全量翻完当前目录后 CLI 侧筛）；
+			// filter+latest 单层同走 BFS（先筛后排，不走 runDriveListLatest 凑够即停）。
+			if depth > 1 || filter.active() {
 				quiet, _ := cmd.Flags().GetBool("quiet")
 				baseArgs := map[string]any{}
 				if v, _ := cmd.Flags().GetString("space-id"); v != "" {
@@ -508,7 +518,7 @@ func newDriveCommand() *cobra.Command {
 						return err
 					}
 				}
-				return runDriveListDepth(cmd, newDrivePanDepthRoute(), baseArgs, rootFolder, depth, pattern, quiet, latest)
+				return runDriveListDepth(cmd, newDrivePanDepthRoute(), baseArgs, rootFolder, depth, pattern, quiet, latest, filter)
 			}
 
 			// 默认路由：钉盘文件列表
@@ -563,6 +573,11 @@ func newDriveCommand() *cobra.Command {
 			if v, _ := cmd.Flags().GetBool("thumbnail"); v {
 				argsMap["withThumbnail"] = true
 			}
+			// --pattern 页内过滤（现状缺口附带修复：透传即打印无法夹过滤，取回解析后筛）；
+			// 不带 pattern 时保持 callMCPTool 纯透传，存量行为不变。
+			if pattern != "" {
+				return callDriveListPageWithPattern(argsMap, pattern)
+			}
 			return callMCPTool("list_files", argsMap)
 		},
 	}
@@ -591,11 +606,13 @@ func newDriveCommand() *cobra.Command {
 					"用户要浏览「我的文件」/钉盘/网盘某目录下有哪些文件或文件夹时",
 					"已知父文件夹 dentryUuid，要列出其子项以便继续 download/copy/move 时",
 					"传 --workspace 时要列出文档空间/知识库根或子目录（与 wiki node list 场景重叠时，用户说钉盘/我的文件优先本命令）",
+					"要在已知目录内按类型/修改时间做无关键词筛选时：--type file --start 7d（钉盘与知识库路由均可，CLI 侧过滤）",
 				},
 				AvoidWhen: []string{
 					"只记得关键词、不知道所在目录时改用 dws drive search",
 					"明确要在某个知识库内按目录浏览且已有 workspaceId 时可用 dws wiki node list",
 					"要找最近打开/编辑过的文档改用 dws drive recent",
+					"带关键词的过滤改用 dws drive search（--extensions/--modified-from 等已可用）",
 				},
 				Examples: []string{
 					"dws drive list --limit 20 --format json",
@@ -1211,6 +1228,9 @@ func newDriveCommand() *cobra.Command {
 	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().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）(可选)")
+	driveListCmd.Flags().String("end", "", "按修改时间过滤·截止: 语法同 --start（客户端过滤，互斥同 --type）(可选)")
 
 	driveInfoCmd.Flags().String("node", "", "节点 ID (dentryUuid) (必填)")
 	driveInfoCmd.Flags().String("space-id", "", "节点所属空间 ID (可选)")
@@ -3279,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,
@@ -3302,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

@@ -178,7 +178,8 @@ func newDocDepthRoute() driveDepthRoute {
 }
 
 // SIGINT 检查两点（出队后发首页前 + 翻页循环发每页前），入队是纯内存操作不检查。
-func runDriveListDepth(cmd *cobra.Command, route driveDepthRoute, baseArgs map[string]any, rootFolderID string, maxDepth int, pattern string, quiet bool, latest int) error {
+// filter 零值 = 未启用；启用时由 emitDriveDepthResult 管线在 pattern 之后、latest 之前筛。
+func runDriveListDepth(cmd *cobra.Command, route driveDepthRoute, baseArgs map[string]any, rootFolderID string, maxDepth int, pattern string, quiet bool, latest int, filter driveListFilter) error {
 	if deps.Caller.DryRun() {
 		return printDriveDepthDryRun(route, baseArgs, maxDepth)
 	}
@@ -209,7 +210,7 @@ func runDriveListDepth(cmd *cobra.Command, route driveDepthRoute, baseArgs map[s
 bfs:
 	for len(queue) > 0 {
 		if ctx.Err() != nil {
-			return emitDriveDepthCancelled(collected, errs, pattern, latest, maxDepth)
+			return emitDriveDepthCancelled(collected, errs, pattern, latest, maxDepth, route, filter)
 		}
 		folder := queue[0]
 		queue = queue[1:]
@@ -220,7 +221,7 @@ bfs:
 		pages := 0
 		for {
 			if ctx.Err() != nil {
-				return emitDriveDepthCancelled(collected, errs, pattern, latest, maxDepth)
+				return emitDriveDepthCancelled(collected, errs, pattern, latest, maxDepth, route, filter)
 			}
 			pages++
 			if pages > maxPagesPerFolder {
@@ -233,7 +234,7 @@ bfs:
 			args := route.buildArgs(baseArgs, folder.id, pageToken)
 			text, err := route.fetchPage(ctx, args)
 			if ctx.Err() != nil {
-				return emitDriveDepthCancelled(collected, errs, pattern, latest, maxDepth)
+				return emitDriveDepthCancelled(collected, errs, pattern, latest, maxDepth, route, filter)
 			}
 			if err != nil {
 				folderErr = err
@@ -297,7 +298,7 @@ bfs:
 			if driveDepthUnrecoverable(folderErr) {
 				// partial 照吐 stdout，错误详情走 stderr，非零退出
 				errs = append(errs, newDriveDepthError(folder, folderErr))
-				if emitErr := emitDriveDepthResult(collected, errs, truncated, pattern, latest, maxDepth); emitErr != nil {
+				if emitErr := emitDriveDepthResult(collected, errs, truncated, pattern, latest, maxDepth, route, filter); emitErr != nil {
 					return emitErr
 				}
 				return folderErr
@@ -338,18 +339,18 @@ bfs:
 		}
 	}
 
-	return emitDriveDepthResult(collected, errs, truncated, pattern, latest, maxDepth)
+	return emitDriveDepthResult(collected, errs, truncated, pattern, latest, maxDepth, route, filter)
 }
 
-func emitDriveDepthCancelled(items []map[string]any, errs []driveDepthError, pattern string, latest, reqDepth int) error {
-	if err := emitDriveDepthResult(items, errs, true, pattern, latest, reqDepth); err != nil {
+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
 	}
 	return &driveDepthCancelledError{}
 }
 
 // depth>1 不输出 nextToken。
-func emitDriveDepthResult(items []map[string]any, errs []driveDepthError, truncated bool, pattern string, latest, reqDepth int) error {
+func emitDriveDepthResult(items []map[string]any, errs []driveDepthError, truncated bool, pattern string, latest, reqDepth int, route driveDepthRoute, filter driveListFilter) error {
 	if pattern != "" {
 		// 先递归后过滤，过滤仅作用于输出项，不阻止文件夹下钻
 		filtered := make([]map[string]any, 0, len(items))
@@ -364,8 +365,13 @@ func emitDriveDepthResult(items []map[string]any, errs []driveDepthError, trunca
 		}
 		items = filtered
 	}
+	if filter.active() {
+		// 类型（route.isFolder 反判）+ 时间（直读收集段注入的 sortTime 毫秒）区间筛
+		items = applyDriveListFilter(items, route, filter)
+	}
 	if latest > 0 {
-		items = applyDriveListLatest(items, latest)
+		// --type folder 时 latest 对过滤后的目录取 Top-N，避免「先留目录再剔目录」的空结果。
+		items = applyDriveListLatest(items, latest, filter.nodeType == "folder")
 	} else {
 		// 排列为 rel_path 树序：BFS 只决定截断时哪些条目入选，树序决定呈现顺序。
 		sort.SliceStable(items, func(i, j int) bool {
@@ -383,7 +389,7 @@ func emitDriveDepthResult(items []map[string]any, errs []driveDepthError, trunca
 			maxDepth = d
 		}
 	}
-	if latest > 0 && reqDepth == 1 {
+	if (latest > 0 || filter.active()) && reqDepth == 1 {
 		stripDriveDepthDecorations(items)
 	}
 	if items == nil {

internal/helpers/drive_depth_test.go

@@ -306,7 +306,7 @@ func TestCrossPlatformCoverageEmitDriveDepthResult(t *testing.T) {
 		{"name": "a-file.xlsx", "rel_path": "a", "depth": 2, "fileId": "f1"},
 		{"name": "skip-me.csv", "rel_path": "c", "depth": 1, "fileId": "f3"},
 	}
-	if err := emitDriveDepthResult(items, nil, false, "*.xlsx", 0, 0); err != nil {
+	if err := emitDriveDepthResult(items, nil, false, "*.xlsx", 0, 0, newDrivePanDepthRoute(), driveListFilter{}); err != nil {
 		t.Fatal(err)
 	}
 	result := decodeDepthResult(t, out)
@@ -325,7 +325,7 @@ func TestCrossPlatformCoverageEmitDriveDepthResult(t *testing.T) {
 	}
 
 	out.Reset()
-	if err := emitDriveDepthResult(nil, nil, false, "", 0, 0); err != nil {
+	if err := emitDriveDepthResult(nil, nil, false, "", 0, 0, newDrivePanDepthRoute(), driveListFilter{}); err != nil {
 		t.Fatal(err)
 	}
 	result = decodeDepthResult(t, out)
@@ -338,7 +338,7 @@ func TestCrossPlatformCoverageEmitDriveDepthResult(t *testing.T) {
 		{"name": "dup", "rel_path": "p/dup", "fileId": "a1"},
 	}
 	out.Reset()
-	if err := emitDriveDepthResult(samePath, nil, false, "", 0, 0); err != nil {
+	if err := emitDriveDepthResult(samePath, nil, false, "", 0, 0, newDrivePanDepthRoute(), driveListFilter{}); err != nil {
 		t.Fatal(err)
 	}
 	got = decodeDepthResult(t, out)["items"].([]any)
@@ -347,7 +347,7 @@ func TestCrossPlatformCoverageEmitDriveDepthResult(t *testing.T) {
 	}
 
 	deps.Out.w = failingWriter{}
-	if err := emitDriveDepthResult(nil, nil, false, "", 0, 0); err == nil {
+	if err := emitDriveDepthResult(nil, nil, false, "", 0, 0, newDrivePanDepthRoute(), driveListFilter{}); err == nil {
 		t.Fatal("failing writer returned nil")
 	}
 }
@@ -382,7 +382,7 @@ func runDepthBFS(t *testing.T, caller *scriptedToolCaller, route driveDepthRoute
 	t.Helper()
 	out := installDepthCaller(t, caller)
 	cmd := &cobra.Command{Use: "list"}
-	err := runDriveListDepth(cmd, route, map[string]any{}, root, maxDepth, pattern, true, 0)
+	err := runDriveListDepth(cmd, route, map[string]any{}, root, maxDepth, pattern, true, 0, driveListFilter{})
 	return decodeDepthResult(t, out), err
 }
 
@@ -390,7 +390,7 @@ func TestCrossPlatformCoverageRunDriveListDepthDryRun(t *testing.T) {
 	caller := &scriptedToolCaller{format: "json", dry: true}
 	out := installDepthCaller(t, caller)
 	cmd := &cobra.Command{Use: "list"}
-	if err := runDriveListDepth(cmd, newDrivePanDepthRoute(), map[string]any{}, "", 2, "", true, 0); err != nil {
+	if err := runDriveListDepth(cmd, newDrivePanDepthRoute(), map[string]any{}, "", 2, "", true, 0, driveListFilter{}); err != nil {
 		t.Fatal(err)
 	}
 	if caller.calls != 0 {
@@ -413,7 +413,7 @@ func TestCrossPlatformCoverageRunDriveListDepthPanBFS(t *testing.T) {
 	}}
 	out := installDepthCaller(t, caller)
 	cmd := &cobra.Command{Use: "list"}
-	if err := runDriveListDepth(cmd, newDrivePanDepthRoute(), map[string]any{}, "", 3, "", false, 0); err != nil {
+	if err := runDriveListDepth(cmd, newDrivePanDepthRoute(), map[string]any{}, "", 3, "", false, 0, driveListFilter{}); err != nil {
 		t.Fatal(err)
 	}
 	if caller.calls != 2 {
@@ -548,7 +548,7 @@ func TestCrossPlatformCoverageRunDriveListDepthRateLimitResumesFromFailedPage(t
 	deps.Out.w = out
 	deps.Out.errW = io.Discard
 	cmd := &cobra.Command{Use: "list"}
-	if err := runDriveListDepth(cmd, newDrivePanDepthRoute(), map[string]any{}, "", 3, "", true, 0); err != nil {
+	if err := runDriveListDepth(cmd, newDrivePanDepthRoute(), map[string]any{}, "", 3, "", true, 0, driveListFilter{}); err != nil {
 		t.Fatal(err)
 	}
 	if len(caller.calls) != 3 {
@@ -593,7 +593,7 @@ func TestCrossPlatformCoverageRunDriveListDepthRootFailure(t *testing.T) {
 	}}
 	installDepthCaller(t, caller)
 	cmd := &cobra.Command{Use: "list"}
-	err := runDriveListDepth(cmd, newDrivePanDepthRoute(), map[string]any{}, "", 3, "", true, 0)
+	err := runDriveListDepth(cmd, newDrivePanDepthRoute(), map[string]any{}, "", 3, "", true, 0, driveListFilter{})
 	if err == nil {
 		t.Fatal("root failure returned nil")
 	}
@@ -610,7 +610,7 @@ func TestCrossPlatformCoverageRunDriveListDepthUnrecoverable(t *testing.T) {
 	}}
 	out := installDepthCaller(t, caller)
 	cmd := &cobra.Command{Use: "list"}
-	err := runDriveListDepth(cmd, newDrivePanDepthRoute(), map[string]any{}, "", 3, "", true, 0)
+	err := runDriveListDepth(cmd, newDrivePanDepthRoute(), map[string]any{}, "", 3, "", true, 0, driveListFilter{})
 	if err == nil {
 		t.Fatal("unrecoverable returned nil")
 	}
@@ -635,7 +635,7 @@ func TestCrossPlatformCoverageRunDriveListDepthUnrecoverableEmitFailure(t *testi
 	installDepthCaller(t, caller)
 	deps.Out.w = failingWriter{}
 	cmd := &cobra.Command{Use: "list"}
-	err := runDriveListDepth(cmd, newDrivePanDepthRoute(), map[string]any{}, "", 3, "", true, 0)
+	err := runDriveListDepth(cmd, newDrivePanDepthRoute(), map[string]any{}, "", 3, "", true, 0, driveListFilter{})
 	if err == nil || !strings.Contains(err.Error(), "write failed") {
 		t.Fatalf("err = %v, want emit failure", err)
 	}
@@ -648,7 +648,7 @@ func TestCrossPlatformCoverageRunDriveListDepthPaginationLoop(t *testing.T) {
 	}}
 	installDepthCaller(t, caller)
 	cmd := &cobra.Command{Use: "list"}
-	err := runDriveListDepth(cmd, newDrivePanDepthRoute(), map[string]any{}, "", 3, "", true, 0)
+	err := runDriveListDepth(cmd, newDrivePanDepthRoute(), map[string]any{}, "", 3, "", true, 0, driveListFilter{})
 	if err == nil || !strings.Contains(err.Error(), "cursor loop suspected") {
 		t.Fatalf("err = %v, want pagination anomaly", err)
 	}
@@ -690,7 +690,7 @@ func TestCrossPlatformCoverageRunDriveListDepthCancelled(t *testing.T) {
 	cancel()
 	cmd := &cobra.Command{Use: "list"}
 	cmd.SetContext(ctx)
-	err := runDriveListDepth(cmd, newDrivePanDepthRoute(), map[string]any{}, "", 3, "", true, 0)
+	err := runDriveListDepth(cmd, newDrivePanDepthRoute(), map[string]any{}, "", 3, "", true, 0, driveListFilter{})
 	var cancelErr *driveDepthCancelledError
 	if !errors.As(err, &cancelErr) {
 		t.Fatalf("err = %T %v, want driveDepthCancelledError", err, err)
@@ -710,7 +710,7 @@ func TestCrossPlatformCoverageRunDriveListDepthCancelledEmitFailure(t *testing.T
 	cancel()
 	cmd := &cobra.Command{Use: "list"}
 	cmd.SetContext(ctx)
-	err := runDriveListDepth(cmd, newDrivePanDepthRoute(), map[string]any{}, "", 3, "", true, 0)
+	err := runDriveListDepth(cmd, newDrivePanDepthRoute(), map[string]any{}, "", 3, "", true, 0, driveListFilter{})
 	if err == nil || !strings.Contains(err.Error(), "write failed") {
 		t.Fatalf("err = %v, want emit failure", err)
 	}
@@ -724,7 +724,7 @@ func TestCrossPlatformCoverageRunDriveListDepthFinalEmitFailure(t *testing.T) {
 	installDepthCaller(t, caller)
 	deps.Out.w = failingWriter{}
 	cmd := &cobra.Command{Use: "list"}
-	err := runDriveListDepth(cmd, newDrivePanDepthRoute(), map[string]any{}, "", 3, "", true, 0)
+	err := runDriveListDepth(cmd, newDrivePanDepthRoute(), map[string]any{}, "", 3, "", true, 0, driveListFilter{})
 	if err == nil || !strings.Contains(err.Error(), "write failed") {
 		t.Fatalf("err = %v, want emit failure", err)
 	}
@@ -772,7 +772,7 @@ func TestCrossPlatformCoverageRunDriveListDepthCancelledInsidePagination(t *test
 	out := installDepthCaller(t, caller)
 	cmd := &cobra.Command{Use: "list"}
 	cmd.SetContext(ctx)
-	err := runDriveListDepth(cmd, route, map[string]any{}, "", 3, "", true, 0)
+	err := runDriveListDepth(cmd, route, map[string]any{}, "", 3, "", true, 0, driveListFilter{})
 	var cancelErr *driveDepthCancelledError
 	if !errors.As(err, &cancelErr) {
 		t.Fatalf("err = %T %v, want driveDepthCancelledError", err, err)
@@ -801,7 +801,7 @@ func TestCrossPlatformCoverageRunDriveListDepthCancelledAfterFetch(t *testing.T)
 	deps.Out.errW = io.Discard
 	cmd := &cobra.Command{Use: "list"}
 	cmd.SetContext(ctx)
-	err := runDriveListDepth(cmd, newDrivePanDepthRoute(), map[string]any{}, "", 3, "", true, 0)
+	err := runDriveListDepth(cmd, newDrivePanDepthRoute(), map[string]any{}, "", 3, "", true, 0, driveListFilter{})
 	var cancelErr *driveDepthCancelledError
 	if !errors.As(err, &cancelErr) {
 		t.Fatalf("err = %T %v, want driveDepthCancelledError", err, err)

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.go

@@ -49,10 +49,11 @@ func driveLatestExclusiveError(flag string, latest int) error {
 	}
 }
 
-func applyDriveListLatest(items []map[string]any, latest int) []map[string]any {
+// foldersOnly=true 时对目录取 Top-N（--type folder --latest 组合），否则对文件取 Top-N。
+func applyDriveListLatest(items []map[string]any, latest int, foldersOnly bool) []map[string]any {
 	files := make([]map[string]any, 0, len(items))
 	for _, item := range items {
-		if isDriveDepthFolder(item) || isDocDepthFolder(item) {
+		if (isDriveDepthFolder(item) || isDocDepthFolder(item)) != foldersOnly {
 			continue
 		}
 		files = append(files, item)

internal/helpers/drive_list_filter.go

@@ -0,0 +1,232 @@
+package helpers
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/spf13/cobra"
+)
+
+// ──────────────────────────────────────────────────────────
+// drive list --type/--start/--end 客户端过滤（CLI 侧筛）
+//
+// 两路由统一（拍板⑤）：钉盘与知识库均为全量拉取后在进程内筛——
+// 复用 depth/latest 的 BFS 基建（钉盘单层 = depth=1 退化态，全量翻完当前目录不下钻），
+// 过滤挂在 emitDriveDepthResult 管线内（pattern 名称筛之后、latest Top-N 之前）。
+// 类型判定复用 route.isFolder 反判；时间比较直读 BFS 收集段注入的 sortTime 毫秒。
+// ──────────────────────────────────────────────────────────
+
+type driveListFilter struct {
+	nodeType string // ""=不过滤 / "file" / "folder"
+	startMs  int64
+	endMs    int64
+	hasStart bool
+	hasEnd   bool
+}
+
+func (f driveListFilter) active() bool {
+	return f.nodeType != "" || f.hasStart || f.hasEnd
+}
+
+// parseDriveListFilter 读取并校验 --type/--start/--end。
+// 三 flag 均未给值时返回零值（active()=false，调用方走存量分支）。
+// 非法值 / start>end / 互斥组合在此拒绝（退出码 3，风格对齐 drive_latest.go 互斥条款）。
+func parseDriveListFilter(cmd *cobra.Command) (driveListFilter, error) {
+	var filter driveListFilter
+	nodeType, _ := cmd.Flags().GetString("type")
+	startRaw, _ := cmd.Flags().GetString("start")
+	endRaw, _ := cmd.Flags().GetString("end")
+	nodeType = strings.TrimSpace(nodeType)
+	startRaw = strings.TrimSpace(startRaw)
+	endRaw = strings.TrimSpace(endRaw)
+	if nodeType == "" && startRaw == "" && endRaw == "" {
+		return filter, nil
+	}
+
+	if nodeType != "" {
+		switch strings.ToLower(nodeType) {
+		case "file", "folder":
+			filter.nodeType = strings.ToLower(nodeType)
+		default:
+			return filter, &CLIError{
+				Code:    CodeInvalidParam,
+				Message: fmt.Sprintf("--type 取值非法: %q（合法值: file|folder）", nodeType),
+			}
+		}
+	}
+	if startRaw != "" {
+		ms, err := parseDriveListTime(startRaw)
+		if err != nil {
+			return filter, &CLIError{Code: CodeInvalidParam, Message: fmt.Sprintf("--start %s", err)}
+		}
+		filter.startMs = ms
+		filter.hasStart = true
+	}
+	if endRaw != "" {
+		ms, err := parseDriveListTime(endRaw)
+		if err != nil {
+			return filter, &CLIError{Code: CodeInvalidParam, Message: fmt.Sprintf("--end %s", err)}
+		}
+		filter.endMs = ms
+		filter.hasEnd = true
+	}
+	if filter.hasStart && filter.hasEnd && filter.startMs > filter.endMs {
+		return filter, &CLIError{
+			Code:    CodeInvalidParam,
+			Message: fmt.Sprintf("--start %q 晚于 --end %q，请修正时间范围", startRaw, endRaw),
+		}
+	}
+
+	// 互斥：filter 为 CLI 侧全量扫描模式，服务端分页/排序语义无法保持。
+	if cmd.Flags().Changed("versions") {
+		return filter, driveListFilterExclusiveError("versions", "--versions 为独立的版本列表模式，请去掉 --versions 或过滤条件")
+	}
+	// 用 Changed 判定而非值非空：显式 --cursor= 空值同样视为启用游标分页。
+	for _, f := range []string{"cursor", "next-token", "page-token"} {
+		if fl := cmd.Flags().Lookup(f); fl != nil && fl.Changed {
+			return filter, driveListFilterExclusiveError("cursor", "过滤模式为从头全量扫描，无连续游标；如需逐页翻页请去掉过滤条件")
+		}
+	}
+	for _, f := range []string{"order-by", "order"} {
+		if cmd.Flags().Changed(f) {
+			return filter, driveListFilterExclusiveError(f, "过滤模式输出由客户端筛选后重排，服务端排序语义无法保持；如需服务端排序请去掉过滤条件")
+		}
+	}
+	if cmd.Flags().Changed("limit") || cmd.Flags().Changed("max") {
+		return filter, driveListFilterExclusiveError("limit", "过滤模式为全量扫描，数据量由全局上限 2000 与目录范围控制；如需控制单页条数请去掉过滤条件")
+	}
+	return filter, nil
+}
+
+func driveListFilterExclusiveError(flag, guidance string) error {
+	return &CLIError{
+		Code:    CodeInvalidParam,
+		Message: fmt.Sprintf("--type/--start/--end 不能与 --%s 同时使用：%s", flag, guidance),
+	}
+}
+
+// parseDriveListTime 单一时间解析入口：先试相对时间语法，失败回落 ISO8601
+// （agoal.go parseISO8601ToMillis，RFC3339/无时区默认 Asia/Shanghai/仅日期）。
+// 两 flag 共用同一入口；不接受毫秒时间戳（规约红线，与 search 历史遗留切割）。
+func parseDriveListTime(value string) (int64, error) {
+	if ms, ok := parseDriveRelativeTimeAgo(value); ok {
+		return ms, nil
+	}
+	if ms, err := parseISO8601ToMillis(value); err == nil {
+		return ms, nil
+	}
+	return 0, fmt.Errorf("时间格式不支持: %q（支持: 相对时间如 24h/7d/2w、RFC3339 如 2026-08-01T00:00:00+08:00、无时区 ISO8601 如 2026-08-01 08:00:00（默认 Asia/Shanghai）、仅日期 2026-08-01；不支持毫秒时间戳与 m 单位）", value)
+}
+
+// parseDriveRelativeTimeAgo 相对时间 Nh/Nd/Nw（小时/天/周），按本机时钟换算为绝对毫秒。
+// 不支持 m 单位（lark 双解析器 m=分钟/月语义打架的教训，直接规避）；
+// ok=false 表示非相对时间语法，由调用方回落 ISO8601 解析。
+func parseDriveRelativeTimeAgo(value string) (int64, bool) {
+	s := strings.TrimSpace(value)
+	if len(s) < 2 {
+		return 0, false
+	}
+	var unit time.Duration
+	switch s[len(s)-1] {
+	case 'h':
+		unit = time.Hour
+	case 'd':
+		unit = 24 * time.Hour
+	case 'w':
+		unit = 7 * 24 * time.Hour
+	default:
+		return 0, false
+	}
+	n, err := strconv.Atoi(s[:len(s)-1])
+	if err != nil || n <= 0 {
+		return 0, false
+	}
+	return time.Now().Add(-time.Duration(n) * unit).UnixMilli(), true
+}
+
+// applyDriveListFilter 在 emit 管线内做类型/时间筛（pattern 之后、latest Top-N 之前）。
+func applyDriveListFilter(items []map[string]any, route driveDepthRoute, filter driveListFilter) []map[string]any {
+	filtered := make([]map[string]any, 0, len(items))
+	for _, item := range items {
+		if filter.nodeType != "" {
+			folder := route.isFolder(item)
+			if filter.nodeType == "folder" && !folder {
+				continue
+			}
+			if filter.nodeType == "file" && folder {
+				continue
+			}
+		}
+		if filter.hasStart || filter.hasEnd {
+			// sortTime 由 BFS 收集段无条件注入（drive_depth.go 时间戳归一）；
+			// 无时间信息的条目（sortTime<=0）在时间条件下不可判定，保守滤除。
+			ts, _ := item["sortTime"].(int64)
+			if ts <= 0 {
+				continue
+			}
+			if filter.hasStart && ts < filter.startMs {
+				continue
+			}
+			if filter.hasEnd && ts > filter.endMs {
+				continue
+			}
+		}
+		filtered = append(filtered, item)
+	}
+	return filtered
+}
+
+// callDriveListPageWithPattern 单层钉盘 --pattern 页内过滤（现状缺口附带修复：
+// 纯透传分支此前未消费 pattern，flag 文案承诺的客户端过滤静默失效）。
+// callMCPTool 透传即打印、无夹过滤的钩子，故取回解析后页内筛再输出；
+// 输出保留原 body 形态（nextToken 等分页字段不动），仅条目数组被筛。
+func callDriveListPageWithPattern(argsMap map[string]any, pattern string) error {
+	if deps.Caller.DryRun() {
+		return deps.Out.PrintJSON(map[string]any{
+			"dry_run":   true,
+			"executed":  false,
+			"tool":      "list_files",
+			"arguments": argsMap,
+			"pattern":   pattern,
+			"note":      "pattern 为客户端过滤，仅作用于本页返回条目",
+		})
+	}
+	text, err := callMCPToolReturnText(context.Background(), "list_files", argsMap)
+	if err != nil {
+		return err
+	}
+	var body map[string]any
+	if json.Unmarshal([]byte(text), &body) != nil {
+		// 非 JSON 返回无法筛，原样输出（与透传分支的兜底形态一致）。
+		deps.Out.PrintRaw(text)
+		return nil
+	}
+	target := body
+	if inner, ok := body["result"].(map[string]any); ok && driveDepthListItemsKey(inner) != "" {
+		target = inner
+	}
+	if key := driveDepthListItemsKey(target); key != "" {
+		arr, _ := target[key].([]any)
+		filtered := make([]any, 0, len(arr))
+		for _, entry := range arr {
+			item, ok := entry.(map[string]any)
+			if !ok {
+				filtered = append(filtered, entry)
+				continue
+			}
+			name, _ := item["name"].(string)
+			if name == "" {
+				name, _ = item["fileName"].(string)
+			}
+			if matchDriveNamePattern(name, pattern) {
+				filtered = append(filtered, entry)
+			}
+		}
+		target[key] = filtered
+	}
+	return deps.Out.PrintJSON(body)
+}

internal/helpers/drive_list_filter_test.go

@@ -0,0 +1,587 @@
+package helpers
+
+import (
+	"bytes"
+	"errors"
+	"fmt"
+	"io"
+	"os"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition"
+)
+
+// drive list --type/--start/--end 客户端过滤测试矩阵（设计稿 §9.3）。
+// 命令级用例统一经 executeDriveListCapture 捕获 stdout JSON；
+// 零值 filter 的存量分支行为由 drive_depth_test.go / drive_list_modes_test.go 既有用例兜底。
+
+// 钉盘路由（serverID 空）经 resolveProductID 扫 os.Args 推断产品，命令级测试需伪装命令行。
+func useDriveListArgs(t *testing.T) {
+	t.Helper()
+	old := os.Args
+	os.Args = []string{"dws", "drive", "list"}
+	t.Cleanup(func() { os.Args = old })
+}
+
+func executeDriveListCapture(t *testing.T, caller edition.ToolCaller, args ...string) (*bytes.Buffer, error) {
+	t.Helper()
+	previousDeps := deps
+	t.Cleanup(func() { deps = previousDeps })
+	InitDeps(caller)
+	buf := &bytes.Buffer{}
+	deps.Out.w = buf
+	deps.Out.errW = io.Discard
+	root := newDriveCommand()
+	root.SilenceErrors = true
+	root.SilenceUsage = true
+	root.SetArgs(args)
+	err := root.Execute()
+	return buf, err
+}
+
+// 1. 正向：--workspace --type file → list_nodes 全量拉取后仅 file，单层剥装饰字段。
+func TestCrossPlatformCoverageDriveListFilterWorkspaceTypeFile(t *testing.T) {
+	caller := &scriptedToolCaller{steps: []scriptedToolStep{
+		{text: `{"nodes":[
+			{"nodeId":"n1","name":"doc1","nodeType":"doc","updateTime":1754000000000},
+			{"nodeId":"n2","name":"sub","nodeType":"folder","updateTime":1754000000000}
+		],"hasMore":false}`},
+	}}
+	buf, err := executeDriveListCapture(t, caller, "list", "--workspace", "ws-1", "--type", "file")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if caller.calls != 1 {
+		t.Fatalf("calls = %d, want 1（depth=1 退化态不下钻 folder）", caller.calls)
+	}
+	result := decodeDepthResult(t, buf)
+	items := result["items"].([]any)
+	if len(items) != 1 {
+		t.Fatalf("filtered items = %#v", items)
+	}
+	item := items[0].(map[string]any)
+	if item["nodeId"] != "n1" {
+		t.Fatalf("item = %#v", item)
+	}
+	for _, key := range []string{"depth", "parentId", "rel_path", "sortTime"} {
+		if _, ok := item[key]; ok {
+			t.Fatalf("decoration %q not stripped: %#v", key, item)
+		}
+	}
+	if result["truncated"] != false || result["maxDepth"] != float64(1) {
+		t.Fatalf("result = %#v", result)
+	}
+}
+
+// 2. 正向：--workspace --start 7d --end <RFC3339> → sortTime 区间断言。
+func TestCrossPlatformCoverageDriveListFilterWorkspaceTimeRange(t *testing.T) {
+	now := time.Now()
+	within := now.Add(-24 * time.Hour).UnixMilli()
+	before := now.Add(-30 * 24 * time.Hour).UnixMilli()
+	after := now.Add(24 * time.Hour).UnixMilli()
+	caller := &scriptedToolCaller{steps: []scriptedToolStep{
+		{text: fmt.Sprintf(`{"nodes":[
+			{"nodeId":"in","name":"within","nodeType":"doc","updateTime":%d},
+			{"nodeId":"old","name":"before","nodeType":"doc","updateTime":%d},
+			{"nodeId":"new","name":"after","nodeType":"doc","updateTime":%d}
+		],"hasMore":false}`, within, before, after)},
+	}}
+	buf, err := executeDriveListCapture(t, caller,
+		"list", "--workspace", "ws-1", "--start", "7d", "--end", now.Format(time.RFC3339))
+	if err != nil {
+		t.Fatal(err)
+	}
+	items := decodeDepthResult(t, buf)["items"].([]any)
+	if len(items) != 1 || items[0].(map[string]any)["nodeId"] != "in" {
+		t.Fatalf("time-range items = %#v", items)
+	}
+}
+
+// 3. 组合：--workspace --depth 2 --type file → BFS 路径 filter 生效，装饰字段保留。
+func TestCrossPlatformCoverageDriveListFilterWithDepthKeepsDecorations(t *testing.T) {
+	caller := &scriptedToolCaller{steps: []scriptedToolStep{
+		{text: `{"nodes":[
+			{"nodeId":"fA","name":"dirA","nodeType":"folder"},
+			{"nodeId":"n1","name":"doc1","nodeType":"doc"}
+		],"hasMore":false}`},
+		{text: `{"nodes":[{"nodeId":"n2","name":"doc2","nodeType":"doc"}],"hasMore":false}`},
+	}}
+	buf, err := executeDriveListCapture(t, caller,
+		"list", "--workspace", "ws-1", "--depth", "2", "--type", "file")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if caller.calls != 2 {
+		t.Fatalf("calls = %d, want 2（depth=2 下钻 dirA）", caller.calls)
+	}
+	items := decodeDepthResult(t, buf)["items"].([]any)
+	if len(items) != 2 {
+		t.Fatalf("filtered items = %#v（folder 应被滤除）", items)
+	}
+	for _, raw := range items {
+		item := raw.(map[string]any)
+		if _, ok := item["depth"]; !ok {
+			t.Fatalf("depth>1 装饰字段应保留: %#v", item)
+		}
+	}
+}
+
+// 4. 组合：--workspace --type file --latest 3 → filter 先筛后 Top-N；
+// 触顶时 LATEST_SCAN_TRUNCATED 拒绝优先于 filter 的 partial 语义。
+func TestCrossPlatformCoverageDriveListFilterWithLatestTopN(t *testing.T) {
+	caller := &scriptedToolCaller{steps: []scriptedToolStep{
+		{text: `{"nodes":[
+			{"nodeId":"d1","name":"dir","nodeType":"folder","updateTime":400},
+			{"nodeId":"f1","name":"a","nodeType":"doc","updateTime":100},
+			{"nodeId":"f2","name":"b","nodeType":"doc","updateTime":300},
+			{"nodeId":"f3","name":"c","nodeType":"doc","updateTime":200},
+			{"nodeId":"f4","name":"d","nodeType":"doc","updateTime":50}
+		],"hasMore":false}`},
+	}}
+	buf, err := executeDriveListCapture(t, caller,
+		"list", "--workspace", "ws-1", "--type", "file", "--latest", "2")
+	if err != nil {
+		t.Fatal(err)
+	}
+	items := decodeDepthResult(t, buf)["items"].([]any)
+	if len(items) != 2 {
+		t.Fatalf("top-n items = %#v", items)
+	}
+	// folder（updateTime 最大）不得进入 Top-N 排序基；筛选后按 sortTime 倒序。
+	if items[0].(map[string]any)["nodeId"] != "f2" || items[1].(map[string]any)["nodeId"] != "f3" {
+		t.Fatalf("top-n order = %#v", items)
+	}
+}
+
+func TestCrossPlatformCoverageDriveListFilterLatestTruncatedRejected(t *testing.T) {
+	useDriveListArgs(t)
+	var sb strings.Builder
+	sb.WriteString(`{"items":[`)
+	for i := 0; i < driveDepthMaxItems; i++ {
+		if i > 0 {
+			sb.WriteString(",")
+		}
+		fmt.Fprintf(&sb, `{"fileId":"f%d","name":"file-%d.txt","type":"FILE","modifyTime":%d}`, i, i, 1000+i)
+	}
+	sb.WriteString(`]}`)
+	caller := &scriptedToolCaller{steps: []scriptedToolStep{{text: sb.String()}}}
+	_, err := executeDriveListCapture(t, caller, "list", "--type", "file", "--latest", "2")
+	if err == nil || !strings.Contains(err.Error(), "LATEST_SCAN_TRUNCATED") {
+		t.Fatalf("err = %v, want LATEST_SCAN_TRUNCATED", err)
+	}
+}
+
+// 5. 钉盘路由：--folder + --type file 单层退化态全量翻页后仅 file；
+// --start 7d --latest 3 走 BFS(depth=1)；filter 与 cursor/order-by/order/limit/versions 互斥退出码 3。
+func TestCrossPlatformCoverageDriveListFilterPanFolderTypeFile(t *testing.T) {
+	useDriveListArgs(t)
+	caller := &depthArgsRecordingCaller{steps: []scriptedToolStep{
+		{text: `{"items":[
+			{"fileId":"d1","name":"sub","type":"FOLDER"},
+			{"fileId":"f1","name":"a.txt","type":"FILE"}
+		],"nextToken":"p2"}`},
+		{text: `{"items":[{"fileId":"f2","name":"b.txt","type":"FILE"}]}`},
+	}}
+	buf, err := executeDriveListCapture(t, caller, "list", "--folder", "root-1", "--type", "file")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(caller.calls) != 2 {
+		t.Fatalf("calls = %d, want 2（翻完当前目录两页，sub 不下钻）", len(caller.calls))
+	}
+	if caller.calls[0]["parentId"] != "root-1" || caller.calls[0]["maxResults"] != float64(driveDepthPageSize) {
+		t.Fatalf("page args = %#v", caller.calls[0])
+	}
+	if caller.calls[1]["nextToken"] != "p2" {
+		t.Fatalf("page2 args = %#v", caller.calls[1])
+	}
+	items := decodeDepthResult(t, buf)["items"].([]any)
+	if len(items) != 2 {
+		t.Fatalf("filtered items = %#v", items)
+	}
+	for _, raw := range items {
+		item := raw.(map[string]any)
+		if item["type"] != "FILE" {
+			t.Fatalf("folder leaked: %#v", item)
+		}
+		if _, ok := item["depth"]; ok {
+			t.Fatalf("single-layer decorations not stripped: %#v", item)
+		}
+	}
+}
+
+func TestCrossPlatformCoverageDriveListFilterPanStartWithLatest(t *testing.T) {
+	useDriveListArgs(t)
+	now := time.Now()
+	within := now.Add(-24 * time.Hour).UnixMilli()
+	stale := now.Add(-30 * 24 * time.Hour).UnixMilli()
+	caller := &scriptedToolCaller{steps: []scriptedToolStep{
+		{text: fmt.Sprintf(`{"items":[
+			{"fileId":"f1","name":"a.txt","type":"FILE","modifyTime":%d},
+			{"fileId":"f2","name":"b.txt","type":"FILE","modifyTime":%d},
+			{"fileId":"f3","name":"c.txt","type":"FILE","modifyTime":%d}
+		]}`, within-1000, within, stale)},
+	}}
+	buf, err := executeDriveListCapture(t, caller, "list", "--start", "7d", "--latest", "1")
+	if err != nil {
+		t.Fatal(err)
+	}
+	result := decodeDepthResult(t, buf)
+	if _, ok := result["truncated"]; !ok {
+		t.Fatalf("filter+latest 应走 BFS 聚合形态: %#v", result)
+	}
+	items := result["items"].([]any)
+	// --start 7d 先筛掉 stale，Top-1 取 sortTime 最大的 f2。
+	if len(items) != 1 || items[0].(map[string]any)["fileId"] != "f2" {
+		t.Fatalf("items = %#v", items)
+	}
+}
+
+func TestCrossPlatformCoverageDriveListFilterExclusiveFlags(t *testing.T) {
+	cases := [][]string{
+		{"list", "--type", "file", "--cursor", "c1"},
+		{"list", "--type", "file", "--cursor", ""},
+		{"list", "--type", "file", "--order-by", "name"},
+		{"list", "--start", "7d", "--order", "asc"},
+		{"list", "--type", "file", "--limit", "5"},
+		{"list", "--end", "2026-08-01", "--max", "5"},
+		{"list", "--versions", "--node", "n1", "--type", "file"},
+	}
+	for _, args := range cases {
+		caller := &scriptedToolCaller{}
+		_, err := executeDriveListCapture(t, caller, args...)
+		var cliErr *CLIError
+		if !errors.As(err, &cliErr) || cliErr.ExitCode() != ExitValidation {
+			t.Fatalf("args %v: err = %v, want CLIError exit 3", args, err)
+		}
+		if !strings.Contains(err.Error(), "不能与") || !strings.Contains(err.Error(), "同时使用") {
+			t.Fatalf("args %v: err = %v, want exclusivity message", args, err)
+		}
+		if caller.calls != 0 {
+			t.Fatalf("args %v: calls = %d, want 0", args, caller.calls)
+		}
+	}
+}
+
+// 6. 边界：--type 非法值列合法值；start>end 退出码 3；相对时间解析与 m/毫秒拒绝。
+func TestCrossPlatformCoverageDriveListFilterInvalidValues(t *testing.T) {
+	caller := &scriptedToolCaller{}
+	_, err := executeDriveListCapture(t, caller, "list", "--type", "dir")
+	var cliErr *CLIError
+	if !errors.As(err, &cliErr) || cliErr.ExitCode() != ExitValidation {
+		t.Fatalf("--type dir err = %v, want exit 3", err)
+	}
+	if !strings.Contains(err.Error(), "file|folder") {
+		t.Fatalf("--type dir err = %v, want valid values listed", err)
+	}
+
+	_, err = executeDriveListCapture(t, caller, "list", "--start", "2026-08-10", "--end", "2026-08-01")
+	if !errors.As(err, &cliErr) || cliErr.ExitCode() != ExitValidation {
+		t.Fatalf("start>end err = %v, want exit 3", err)
+	}
+	if !strings.Contains(err.Error(), "晚于") {
+		t.Fatalf("start>end err = %v", err)
+	}
+	if caller.calls != 0 {
+		t.Fatalf("calls = %d, want 0", caller.calls)
+	}
+}
+
+func TestCrossPlatformCoverageDriveListFilterTimeParsing(t *testing.T) {
+	// 相对时间按本机时钟换算为绝对毫秒。
+	for _, tc := range []struct {
+		raw  string
+		unit time.Duration
+	}{
+		{"24h", time.Hour},
+		{"7d", 24 * time.Hour},
+		{"2w", 7 * 24 * time.Hour},
+	} {
+		before := time.Now()
+		ms, err := parseDriveListTime(tc.raw)
+		after := time.Now()
+		if err != nil {
+			t.Fatalf("%s: %v", tc.raw, err)
+		}
+		expected := time.Duration(mustAtoi(t, tc.raw[:len(tc.raw)-1])) * tc.unit
+		lo := before.Add(-expected).UnixMilli()
+		hi := after.Add(-expected).UnixMilli()
+		if ms < lo || ms > hi {
+			t.Fatalf("%s: ms = %d, want in [%d, %d]", tc.raw, ms, lo, hi)
+		}
+	}
+
+	// RFC3339 / 无时区 ISO8601（默认 Asia/Shanghai）/ 仅日期。
+	shanghai := time.FixedZone("CST", 8*3600)
+	for _, tc := range []struct {
+		raw  string
+		want int64
+	}{
+		{"2026-08-01T00:00:00+08:00", time.Date(2026, 8, 1, 0, 0, 0, 0, shanghai).UnixMilli()},
+		{"2026-08-01 08:00:00", time.Date(2026, 8, 1, 8, 0, 0, 0, shanghai).UnixMilli()},
+		{"2026-08-01", time.Date(2026, 8, 1, 0, 0, 0, 0, shanghai).UnixMilli()},
+	} {
+		ms, err := parseDriveListTime(tc.raw)
+		if err != nil || ms != tc.want {
+			t.Fatalf("%s: ms = %d err = %v, want %d", tc.raw, ms, err, tc.want)
+		}
+	}
+
+	// m 单位 / 毫秒时间戳 / 零与负值一律拒绝。
+	for _, raw := range []string{"7m", "30m", "1754000000000", "0d", "-3d", "abc"} {
+		if _, err := parseDriveListTime(raw); err == nil {
+			t.Fatalf("%q accepted, want rejection", raw)
+		}
+	}
+}
+
+func mustAtoi(t *testing.T, s string) int {
+	t.Helper()
+	n := 0
+	if _, err := fmt.Sscanf(s, "%d", &n); err != nil {
+		t.Fatalf("atoi %q: %v", s, err)
+	}
+	return n
+}
+
+// 7. dry-run：--workspace --type file --dry-run → printDriveDepthDryRun 路径，不发起调用。
+func TestCrossPlatformCoverageDriveListFilterDryRun(t *testing.T) {
+	caller := &scriptedToolCaller{format: "json", dry: true}
+	buf, err := executeDriveListCapture(t, caller, "list", "--workspace", "ws-1", "--type", "file")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if caller.calls != 0 {
+		t.Fatalf("dry-run calls = %d", caller.calls)
+	}
+	result := decodeDepthResult(t, buf)
+	if result["dry_run"] != true || result["tool"] != "list_nodes" || result["maxDepth"] != float64(1) {
+		t.Fatalf("dry-run payload = %#v", result)
+	}
+}
+
+// 8. 触顶：2000 条上限 → partial + truncated=true + 退出码 0（filter 触顶结果不全但不会错）。
+func TestCrossPlatformCoverageDriveListFilterTruncatedPartial(t *testing.T) {
+	useDriveListArgs(t)
+	var sb strings.Builder
+	sb.WriteString(`{"items":[`)
+	for i := 0; i < driveDepthMaxItems; i++ {
+		if i > 0 {
+			sb.WriteString(",")
+		}
+		fmt.Fprintf(&sb, `{"fileId":"f%d","name":"file-%d.txt","type":"FILE","modifyTime":%d}`, i, i, 1000+i)
+	}
+	sb.WriteString(`]}`)
+	caller := &scriptedToolCaller{steps: []scriptedToolStep{{text: sb.String()}}}
+	buf, err := executeDriveListCapture(t, caller, "list", "--type", "file")
+	if err != nil {
+		t.Fatalf("filter 触顶应放行（退出码 0）: %v", err)
+	}
+	result := decodeDepthResult(t, buf)
+	if result["truncated"] != true {
+		t.Fatalf("truncated = %#v", result["truncated"])
+	}
+	if got := len(result["items"].([]any)); got != driveDepthMaxItems {
+		t.Fatalf("items len = %d, want %d（全 FILE 类型筛全保留）", got, driveDepthMaxItems)
+	}
+}
+
+// 9. 回归：不带 filter 的存量分支行为不变；--pattern 单层钉盘页内过滤为本次有意修复。
+func TestCrossPlatformCoverageDriveListFilterRegressionUnaffectedPaths(t *testing.T) {
+	useDriveListArgs(t)
+	// 单层纯透传（无 filter/pattern）：body 原样输出，args 语义不变。
+	caller := &scriptedToolCaller{steps: []scriptedToolStep{
+		{text: `{"items":[{"fileId":"f1","name":"a.txt"}],"nextToken":"nt"}`},
+	}}
+	buf, err := executeDriveListCapture(t, caller, "list")
+	if err != nil {
+		t.Fatal(err)
+	}
+	result := decodeDepthResult(t, buf)
+	if result["nextToken"] != "nt" || len(result["items"].([]any)) != 1 {
+		t.Fatalf("透传 body 被改变: %#v", result)
+	}
+	if _, ok := result["truncated"]; ok {
+		t.Fatalf("透传形态不应含 BFS 聚合字段: %#v", result)
+	}
+	if caller.args["maxResults"] != float64(20) {
+		t.Fatalf("args = %#v", caller.args)
+	}
+
+	// workspace 单层透传：无 filter/depth/latest 时仍走单页 list_nodes。
+	caller2 := &scriptedToolCaller{steps: []scriptedToolStep{
+		{text: `{"nodes":[{"nodeId":"n1","name":"doc1","nodeType":"doc"}],"hasMore":false}`},
+	}}
+	buf2, err := executeDriveListCapture(t, caller2, "list", "--workspace", "ws-1")
+	if err != nil {
+		t.Fatal(err)
+	}
+	result2 := decodeDepthResult(t, buf2)
+	if _, ok := result2["nodes"]; !ok {
+		t.Fatalf("workspace 单层透传形态被改变: %#v", result2)
+	}
+	if caller2.args["pageSize"] != 20 || caller2.args["workspaceId"] != "ws-1" {
+		t.Fatalf("args = %#v", caller2.args)
+	}
+
+	// 钉盘单层 --latest（无 filter）：仍走 runDriveListLatest（非 BFS 聚合形态）。
+	now := time.Now().UnixMilli()
+	caller3 := &depthArgsRecordingCaller{steps: []scriptedToolStep{
+		{text: fmt.Sprintf(`{"items":[{"fileId":"f1","name":"a.txt","type":"FILE","modifyTime":%d}],"nextToken":""}`, now)},
+	}}
+	buf3, err := executeDriveListCapture(t, caller3, "list", "--latest", "1")
+	if err != nil {
+		t.Fatal(err)
+	}
+	result3 := decodeDepthResult(t, buf3)
+	if _, ok := result3["truncated"]; ok {
+		t.Fatalf("单层 latest 不应切到 BFS 聚合形态: %#v", result3)
+	}
+	if len(result3["items"].([]any)) != 1 {
+		t.Fatalf("items = %#v", result3["items"])
+	}
+	if caller3.calls[0]["orderBy"] != "modifyTime" || caller3.calls[0]["order"] != "desc" {
+		t.Fatalf("latest 扫描参数被改变: %#v", caller3.calls[0])
+	}
+}
+
+func TestCrossPlatformCoverageDriveListPatternSingleLayerFixed(t *testing.T) {
+	useDriveListArgs(t)
+	caller := &scriptedToolCaller{steps: []scriptedToolStep{
+		{text: `{"items":[
+			{"fileId":"f1","name":"a.txt"},
+			{"fileId":"f2","name":"b.md"}
+		],"nextToken":"nt"}`},
+	}}
+	buf, err := executeDriveListCapture(t, caller, "list", "--pattern", "*.txt")
+	if err != nil {
+		t.Fatal(err)
+	}
+	result := decodeDepthResult(t, buf)
+	items := result["items"].([]any)
+	if len(items) != 1 || items[0].(map[string]any)["fileId"] != "f1" {
+		t.Fatalf("pattern 页内过滤未生效: %#v", items)
+	}
+	if result["nextToken"] != "nt" {
+		t.Fatalf("分页字段应保留: %#v", result)
+	}
+}
+
+// 10. 钉盘路由：--type folder 反向筛（FILE 被滤除，仅 FOLDER 保留）。
+func TestCrossPlatformCoverageDriveListFilterPanFolderTypeFolder(t *testing.T) {
+	useDriveListArgs(t)
+	caller := &scriptedToolCaller{steps: []scriptedToolStep{
+		{text: `{"items":[
+			{"fileId":"d1","name":"sub","type":"FOLDER"},
+			{"fileId":"f1","name":"a.txt","type":"FILE"}
+		]}`},
+	}}
+	buf, err := executeDriveListCapture(t, caller, "list", "--folder", "root-1", "--type", "folder")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if caller.calls != 1 {
+		t.Fatalf("calls = %d, want 1（depth=1 退化态不下钻 folder）", caller.calls)
+	}
+	items := decodeDepthResult(t, buf)["items"].([]any)
+	if len(items) != 1 || items[0].(map[string]any)["fileId"] != "d1" {
+		t.Fatalf("folder filter items = %#v", items)
+	}
+}
+
+// 11. 钉盘路由：--start 下无时间信息的条目（sortTime<=0）不可判定，保守滤除。
+func TestCrossPlatformCoverageDriveListFilterPanMissingTimeDropped(t *testing.T) {
+	useDriveListArgs(t)
+	now := time.Now().UnixMilli()
+	caller := &scriptedToolCaller{steps: []scriptedToolStep{
+		{text: fmt.Sprintf(`{"items":[
+			{"fileId":"f1","name":"a.txt","type":"FILE","modifyTime":%d},
+			{"fileId":"f2","name":"no-time.txt","type":"FILE"}
+		]}`, now)},
+	}}
+	buf, err := executeDriveListCapture(t, caller, "list", "--start", "7d")
+	if err != nil {
+		t.Fatal(err)
+	}
+	items := decodeDepthResult(t, buf)["items"].([]any)
+	if len(items) != 1 || items[0].(map[string]any)["fileId"] != "f1" {
+		t.Fatalf("missing-time 条目应被滤除: %#v", items)
+	}
+}
+
+// 12. 单层钉盘 --pattern 页内过滤边界：dry-run 预览 / MCP 错误透传 / 非 JSON 原样输出 /
+// 非 map 条目保留 + name 缺失时 fileName 兜底匹配。
+func TestCrossPlatformCoverageDriveListPatternPassthroughEdges(t *testing.T) {
+	useDriveListArgs(t)
+
+	// dry-run：打印预览，不发起调用。
+	dryCaller := &scriptedToolCaller{dry: true}
+	buf, err := executeDriveListCapture(t, dryCaller, "list", "--pattern", "*.txt")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if dryCaller.calls != 0 {
+		t.Fatalf("dry-run calls = %d", dryCaller.calls)
+	}
+	preview := decodeDepthResult(t, buf)
+	if preview["dry_run"] != true || preview["tool"] != "list_files" || preview["pattern"] != "*.txt" {
+		t.Fatalf("dry-run payload = %#v", preview)
+	}
+
+	// MCP 错误：原样返回。
+	errCaller := &scriptedToolCaller{steps: []scriptedToolStep{{err: errors.New("boom")}}}
+	if _, err := executeDriveListCapture(t, errCaller, "list", "--pattern", "*.txt"); err == nil || !strings.Contains(err.Error(), "boom") {
+		t.Fatalf("err = %v, want boom", err)
+	}
+
+	// 非 JSON 返回：无法筛，原样输出（与透传分支兜底形态一致）。
+	rawCaller := &scriptedToolCaller{steps: []scriptedToolStep{{text: "plain-text-result"}}}
+	rawBuf, err := executeDriveListCapture(t, rawCaller, "list", "--pattern", "*.txt")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(rawBuf.String(), "plain-text-result") {
+		t.Fatalf("raw output = %q", rawBuf.String())
+	}
+
+	// 非 map 条目原样保留；name 缺失时 fileName 兜底参与匹配。
+	mixedCaller := &scriptedToolCaller{steps: []scriptedToolStep{
+		{text: `{"items":[
+			"raw-entry",
+			{"fileId":"f1","fileName":"日报模板.doc"},
+			{"fileId":"f2","name":"其他.txt"}
+		],"nextToken":"nt"}`},
+	}}
+	mixedBuf, err := executeDriveListCapture(t, mixedCaller, "list", "--pattern", "*模板*")
+	if err != nil {
+		t.Fatal(err)
+	}
+	mixed := decodeDepthResult(t, mixedBuf)["items"].([]any)
+	if len(mixed) != 2 || mixed[0] != "raw-entry" || mixed[1].(map[string]any)["fileId"] != "f1" {
+		t.Fatalf("items = %#v", mixed)
+	}
+}
+
+// 13. --type folder --latest 回归（P1 CR）：latest 对过滤后的目录按时间取 Top-N，
+// 不再「先留目录再剔目录」返回空列表。
+func TestCrossPlatformCoverageDriveListFilterFolderLatest(t *testing.T) {
+	useDriveListArgs(t)
+	now := time.Now().UnixMilli()
+	caller := &scriptedToolCaller{steps: []scriptedToolStep{
+		{text: fmt.Sprintf(`{"items":[
+			{"fileId":"d1","name":"old-dir","type":"FOLDER","modifyTime":%d},
+			{"fileId":"d2","name":"new-dir","type":"FOLDER","modifyTime":%d},
+			{"fileId":"f1","name":"a.txt","type":"FILE","modifyTime":%d}
+		]}`, now-5000, now, now)},
+	}}
+	buf, err := executeDriveListCapture(t, caller, "list", "--type", "folder", "--latest", "1")
+	if err != nil {
+		t.Fatal(err)
+	}
+	items := decodeDepthResult(t, buf)["items"].([]any)
+	if len(items) != 1 || items[0].(map[string]any)["fileId"] != "d2" {
+		t.Fatalf("folder latest items = %#v", items)
+	}
+}

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)
+	}
+}

internal/helpers/drive_pull_times_unix.go

@@ -0,0 +1,16 @@
+//go:build !windows
+
+package helpers
+
+import (
+	"os"
+	"time"
+
+	"golang.org/x/sys/unix"
+)
+
+// setPullFileTimes 只通过已打开文件描述符更新访问/修改时间，不重新解析文件名。
+func setPullFileTimes(file *os.File, modified time.Time) error {
+	stamp := unix.NsecToTimeval(modified.UnixNano())
+	return unix.Futimes(int(file.Fd()), []unix.Timeval{stamp, stamp})
+}

internal/helpers/drive_pull_times_windows.go

@@ -0,0 +1,16 @@
+//go:build windows
+
+package helpers
+
+import (
+	"os"
+	"time"
+
+	"golang.org/x/sys/windows"
+)
+
+// setPullFileTimes 只通过已打开文件句柄更新访问/修改时间，不重新解析文件名。
+func setPullFileTimes(file *os.File, modified time.Time) error {
+	stamp := windows.NsecToFiletime(modified.UnixNano())
+	return windows.SetFileTime(windows.Handle(file.Fd()), nil, &stamp, &stamp)
+}

internal/helpers/drive_pull_toctou_test.go

@@ -0,0 +1,933 @@
+package helpers
+
+import (
+	"context"
+	"errors"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"runtime"
+	"strings"
+	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam"
+)
+
+func installPinnedPullSuccess(t *testing.T) {
+	t.Helper()
+	testseam.Swap(t, &deps, &Deps{Caller: &driveSyncMockCaller{}, Out: &Formatter{w: io.Discard}})
+	testseam.Swap(t, &os.Args, []string{"dws", "drive"})
+	testseam.Swap(t, &pullDownloadFile, func(_ context.Context, _ string, _ map[string]string, destination *os.File) error {
+		_, err := destination.WriteString("remote")
+		return err
+	})
+}
+
+// replacePullAncestorWithOutsideLink 把已被 pull 固定的 sub 目录移走，
+// 再在原名处放置指向根外的符号链接，确定性复现远端调用/下载期间的换链。
+func replacePullAncestorWithOutsideLink(t *testing.T, root, outside string) string {
+	t.Helper()
+	sub := filepath.Join(root, "sub")
+	parked := filepath.Join(root, "sub-pinned")
+	if forcePinnedFallbackForTest {
+		swapPinnedParentIdentity(t, "sub")
+		return sub
+	}
+	if err := os.Rename(sub, parked); err != nil {
+		// Windows 在目录内有已打开的句柄（如 pull 的临时文件）时会锁住该目录，
+		// 移走再换链于该平台物理不可达。退化为等价的父目录身份注入，命中
+		// verifyParent 同一条 fail-closed 分支；原目录未移动，故返回 sub。
+		if runtime.GOOS != "windows" {
+			t.Fatal(err)
+		}
+		swapPinnedParentIdentity(t, "sub")
+		return sub
+	}
+	if err := os.Symlink(outside, sub); err != nil {
+		t.Skipf("平台不支持创建符号链接: %v", err)
+	}
+	return parked
+}
+
+// replacePullCommandRootWithOutsideLink 把命令根整体移走，并在原名处放置指向根外的
+// 符号链接，复现「固定后命令根被换掉」的场景。Windows 在根目录持有已打开句柄时会
+// 锁住该目录，移走于该平台物理不可达，此时退化为等价的根身份注入。
+func replacePullCommandRootWithOutsideLink(t *testing.T, root, parked, outside string) {
+	t.Helper()
+	if forcePinnedFallbackForTest {
+		swapPinnedRootIdentity(t, root)
+		return
+	}
+	if err := os.Rename(root, parked); err != nil {
+		if runtime.GOOS != "windows" {
+			t.Fatal(err)
+		}
+		swapPinnedRootIdentity(t, root)
+		return
+	}
+	if err := os.Symlink(outside, root); err != nil {
+		t.Skipf("symlink unsupported: %v", err)
+	}
+}
+
+func runPullTOCTOUCase(t *testing.T, command string, root string) error {
+	t.Helper()
+	rf := &remoteFile{RelPath: "sub/a.txt", FileID: "F"}
+	if command == "pull" {
+		_, err := pullOneFileAtRoot(context.Background(), "", rf, root, rf.RelPath, ifExistsOverwrite)
+		return err
+	}
+	res := &driveSyncResult{}
+	syncPullFile(res, context.Background(), "", rf, root, rf.RelPath, syncDirectionPull)
+	if res.Summary.Failed != 1 || len(res.Items) != 1 {
+		t.Fatalf("sync TOCTOU result = %#v", res)
+	}
+	if res.Items[0].Error == "" {
+		t.Fatal("sync TOCTOU failure must retain the cause")
+	}
+	return &drivePullTestError{message: res.Items[0].Error}
+}
+
+type drivePullTestError struct{ message string }
+
+func (e *drivePullTestError) Error() string { return e.message }
+
+// download_file 返回期间父目录被换成指向根外的软链时，pull/sync
+// 必须在创建临时文件和发出 HTTP GET 前失败。
+func TestCrossPlatformCoverageDrivePullSyncRejectAncestorSwapBeforeTransfer(t *testing.T) {
+	for _, command := range []string{"pull", "sync"} {
+		t.Run(command, func(t *testing.T) {
+			root := t.TempDir()
+			outside := t.TempDir()
+			if err := os.Mkdir(filepath.Join(root, "sub"), 0o755); err != nil {
+				t.Fatal(err)
+			}
+
+			var parked string
+			caller := &driveScriptCaller{reply: func(tool string, _ map[string]any, _ int) (string, error) {
+				if tool != "download_file" {
+					t.Fatalf("unexpected MCP tool %q", tool)
+				}
+				parked = replacePullAncestorWithOutsideLink(t, root, outside)
+				return `{"result":{"downloadUrl":"https://oss.example.com/get"}}`, nil
+			}}
+			testseam.Swap(t, &deps, &Deps{Caller: caller, Out: &Formatter{w: io.Discard}})
+			testseam.Swap(t, &os.Args, []string{"dws", "drive"})
+
+			tempCalls, getCalls := 0, 0
+			testseam.Swap(t, &pullCreateTemp, func(root *os.Root) (*os.File, string, error) {
+				tempCalls++
+				return createPinnedPullTemp(root)
+			})
+			testseam.Swap(t, &pullDownloadFile, func(context.Context, string, map[string]string, *os.File) error {
+				getCalls++
+				return nil
+			})
+
+			err := runPullTOCTOUCase(t, command, root)
+			if err == nil {
+				t.Fatal("换链后不应继续下载")
+			}
+			if tempCalls != 0 || getCalls != 0 {
+				t.Fatalf("换链后发生了落盘: temp=%d HTTP_GET=%d", tempCalls, getCalls)
+			}
+			if entries, readErr := os.ReadDir(outside); readErr != nil || len(entries) != 0 {
+				t.Fatalf("根外目录被写入: entries=%v err=%v", entries, readErr)
+			}
+			if entries, readErr := os.ReadDir(parked); readErr != nil || len(entries) != 0 {
+				t.Fatalf("已移走的固定目录被写入: entries=%v err=%v", entries, readErr)
+			}
+		})
+	}
+}
+
+// HTTP 传输完成前父目录被换链时，已打开临时文件可以安全清理，
+// 但最终发布必须在再次核对父目录身份后失败，不得沿新软链写到根外。
+func TestCrossPlatformCoverageDrivePullSyncRechecksAncestorBeforePublish(t *testing.T) {
+	for _, command := range []string{"pull", "sync"} {
+		t.Run(command, func(t *testing.T) {
+			root := t.TempDir()
+			outside := t.TempDir()
+			if err := os.Mkdir(filepath.Join(root, "sub"), 0o755); err != nil {
+				t.Fatal(err)
+			}
+			caller := &driveScriptCaller{reply: func(tool string, _ map[string]any, _ int) (string, error) {
+				return `{"result":{"downloadUrl":"https://oss.example.com/get"}}`, nil
+			}}
+			testseam.Swap(t, &deps, &Deps{Caller: caller, Out: &Formatter{w: io.Discard}})
+			testseam.Swap(t, &os.Args, []string{"dws", "drive"})
+
+			parked := ""
+			testseam.Swap(t, &pullDownloadFile, func(_ context.Context, _ string, _ map[string]string, destination *os.File) error {
+				if _, err := destination.WriteString("remote"); err != nil {
+					return err
+				}
+				parked = replacePullAncestorWithOutsideLink(t, root, outside)
+				return nil
+			})
+
+			err := runPullTOCTOUCase(t, command, root)
+			if err == nil {
+				t.Fatal("发布前换链未被拒绝")
+			}
+			if command == "pull" && !strings.Contains(err.Error(), "目标目录在下载期间被替换") {
+				t.Fatalf("pull error = %v", err)
+			}
+			if _, statErr := os.Stat(filepath.Join(outside, "a.txt")); !os.IsNotExist(statErr) {
+				t.Fatalf("根外目标被发布: %v", statErr)
+			}
+			if entries, readErr := os.ReadDir(parked); readErr != nil || len(entries) != 0 {
+				t.Fatalf("失败后应清理临时文件: entries=%v err=%v", entries, readErr)
+			}
+		})
+	}
+}
+
+func TestCrossPlatformCoverageDriveSyncKeepBothRejectsAncestorSwapWithoutRollback(t *testing.T) {
+	root := t.TempDir()
+	outside := t.TempDir()
+	sub := filepath.Join(root, "sub")
+	if err := os.Mkdir(sub, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(sub, "a.txt"), []byte("local"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	testseam.Swap(t, &deps, &Deps{Caller: &driveSyncMockCaller{}, Out: &Formatter{w: io.Discard}})
+	testseam.Swap(t, &os.Args, []string{"dws", "drive"})
+
+	parked := ""
+	testseam.Swap(t, &pullDownloadFile, func(_ context.Context, _ string, _ map[string]string, destination *os.File) error {
+		if _, err := destination.WriteString("remote"); err != nil {
+			return err
+		}
+		parked = replacePullAncestorWithOutsideLink(t, root, outside)
+		return nil
+	})
+
+	res := &driveSyncResult{}
+	syncKeepBoth(res, context.Background(), "", &remoteFile{FileID: "FID"}, root, "sub/a.txt", map[string]bool{})
+
+	if res.Summary.Failed != 1 || len(res.Items) != 1 {
+		t.Fatalf("keep-both TOCTOU result = %#v", res)
+	}
+	if !strings.Contains(res.Items[0].Error, "目标目录在下载期间被替换") {
+		t.Fatalf("error = %q", res.Items[0].Error)
+	}
+	if entries, err := os.ReadDir(outside); err != nil || len(entries) != 0 {
+		t.Fatalf("不得沿换链路径触碰根外目录: entries=%v err=%v", entries, err)
+	}
+	kept := filepath.Join(parked, "a.conflict-FID.txt")
+	if content, err := os.ReadFile(kept); err != nil || string(content) != "local" {
+		t.Fatalf("本地保留硬链接应留在原固定目录: content=%q err=%v", content, err)
+	}
+}
+
+func TestCrossPlatformCoveragePinnedPullFilesystemErrorBranches(t *testing.T) {
+	t.Run("root mkdir", func(t *testing.T) {
+		testseam.Swap(t, &pullMkdirAll, func(string, os.FileMode) error { return errTestDownload })
+		if _, err := openPinnedPullTarget(filepath.Join(t.TempDir(), "root"), "a.txt"); err == nil {
+			t.Fatal("expected root mkdir failure")
+		}
+	})
+
+	t.Run("open root", func(t *testing.T) {
+		root := t.TempDir()
+		testseam.Swap(t, &pullOpenRoot, func(string) (*os.Root, error) { return nil, errTestDownload })
+		if _, err := openPinnedPullTarget(root, "a.txt"); err == nil {
+			t.Fatal("expected root open failure")
+		}
+	})
+
+	t.Run("relative path", func(t *testing.T) {
+		root := t.TempDir()
+		for name, relFn := range map[string]func(string, string) (string, error){
+			"error":  func(string, string) (string, error) { return "", errTestDownload },
+			"escape": func(string, string) (string, error) { return "../escape", nil },
+		} {
+			t.Run(name, func(t *testing.T) {
+				testseam.Swap(t, &pullRelPath, relFn)
+				if _, err := openPinnedPullTarget(root, "a.txt"); err == nil {
+					t.Fatal("expected relative-path failure")
+				}
+			})
+		}
+	})
+
+	t.Run("parent mkdir", func(t *testing.T) {
+		root := t.TempDir()
+		testseam.Swap(t, &pullRootMkdir, func(*os.Root, string, os.FileMode) error { return errTestDownload })
+		if _, err := openPinnedPullTarget(root, "sub/a.txt"); err == nil {
+			t.Fatal("expected parent mkdir failure")
+		}
+	})
+
+	t.Run("parent mkdir success", func(t *testing.T) {
+		root := t.TempDir()
+		target, err := openPinnedPullTarget(root, "sub/a.txt")
+		if err != nil {
+			t.Fatal(err)
+		}
+		target.close()
+		if info, err := os.Lstat(filepath.Join(root, "sub")); err != nil || !info.IsDir() || info.Mode()&os.ModeSymlink != 0 {
+			t.Fatalf("created parent is not a real directory: info=%v err=%v", info, err)
+		}
+	})
+
+	t.Run("open root clone", func(t *testing.T) {
+		root := t.TempDir()
+		testseam.Swap(t, &pullOpenParentRoot, func(*os.Root, string) (*os.Root, error) { return nil, errTestDownload })
+		if _, err := openPinnedPullTarget(root, "sub/a.txt"); err == nil {
+			t.Fatal("expected root clone failure")
+		}
+	})
+
+	t.Run("open parent segment", func(t *testing.T) {
+		root := t.TempDir()
+		if err := os.Mkdir(filepath.Join(root, "sub"), 0o755); err != nil {
+			t.Fatal(err)
+		}
+		testseam.Swap(t, &pullOpenParentRoot, func(root *os.Root, name string) (*os.Root, error) {
+			if name == "sub" {
+				return nil, errTestDownload
+			}
+			return root.OpenRoot(name)
+		})
+		if _, err := openPinnedPullTarget(root, "sub/a.txt"); err == nil {
+			t.Fatal("expected parent segment open failure")
+		}
+	})
+
+	t.Run("lstat root parent", func(t *testing.T) {
+		root := t.TempDir()
+		testseam.Swap(t, &pullRootLstat, func(*os.Root, string) (os.FileInfo, error) { return nil, errTestDownload })
+		if _, err := openPinnedPullTarget(root, "a.txt"); err == nil {
+			t.Fatal("expected root parent lstat failure")
+		}
+	})
+
+	t.Run("lstat parent segment", func(t *testing.T) {
+		root := t.TempDir()
+		testseam.Swap(t, &pullRootLstat, func(root *os.Root, name string) (os.FileInfo, error) {
+			if name == "sub" {
+				return nil, errTestDownload
+			}
+			return root.Lstat(name)
+		})
+		if _, err := openPinnedPullTarget(root, "sub/a.txt"); err == nil {
+			t.Fatal("expected parent segment lstat failure")
+		}
+	})
+
+	t.Run("stat parent", func(t *testing.T) {
+		root := t.TempDir()
+		testseam.Swap(t, &pullRootStat, func(*os.Root, string) (os.FileInfo, error) { return nil, errTestDownload })
+		if _, err := openPinnedPullTarget(root, "a.txt"); err == nil {
+			t.Fatal("expected parent stat failure")
+		}
+	})
+
+	t.Run("parent changes while target opens", func(t *testing.T) {
+		root := t.TempDir()
+		calls := 0
+		testseam.Swap(t, &pullRootStat, func(root *os.Root, name string) (os.FileInfo, error) {
+			calls++
+			if calls == 2 {
+				return nil, errTestDownload
+			}
+			return root.Stat(name)
+		})
+		if _, err := openPinnedPullTarget(root, "a.txt"); err == nil {
+			t.Fatal("expected construction-time parent identity failure")
+		}
+	})
+
+	t.Run("lstat target", func(t *testing.T) {
+		root := t.TempDir()
+		target, err := openPinnedPullTarget(root, "a.txt")
+		if err != nil {
+			t.Fatal(err)
+		}
+		defer target.close()
+		testseam.Swap(t, &pullRootLstat, func(*os.Root, string) (os.FileInfo, error) { return nil, errTestDownload })
+		if _, err := target.regularTargetInfo(); err == nil {
+			t.Fatal("expected target lstat failure")
+		}
+	})
+
+	t.Run("create temp root error and collision exhaustion", func(t *testing.T) {
+		closed, err := os.OpenRoot(t.TempDir())
+		if err != nil {
+			t.Fatal(err)
+		}
+		_ = closed.Close()
+		if _, _, err := createPinnedPullTemp(closed); err == nil {
+			t.Fatal("expected closed root failure")
+		}
+
+		rootDir := t.TempDir()
+		root, err := os.OpenRoot(rootDir)
+		if err != nil {
+			t.Fatal(err)
+		}
+		defer root.Close()
+		const collision = "collision"
+		if err := os.WriteFile(filepath.Join(rootDir, ".dws-pull-"+collision), []byte("x"), 0o600); err != nil {
+			t.Fatal(err)
+		}
+		testseam.Swap(t, &pullTempName, func() string { return collision })
+		if _, _, err := createPinnedPullTemp(root); err == nil {
+			t.Fatal("expected collision exhaustion")
+		}
+	})
+}
+
+func TestCrossPlatformCoveragePinnedPullPublicationErrorBranches(t *testing.T) {
+	call := func(t *testing.T, root string) error {
+		t.Helper()
+		_, err := pullOneFileAtRoot(context.Background(), "", &remoteFile{FileID: "F"}, root, "a.txt", ifExistsOverwrite)
+		return err
+	}
+
+	t.Run("temp stat", func(t *testing.T) {
+		root := t.TempDir()
+		installPinnedPullSuccess(t)
+		testseam.Swap(t, &pullCreateTemp, func(root *os.Root) (*os.File, string, error) {
+			file, name, err := createPinnedPullTemp(root)
+			if err == nil {
+				_ = file.Close()
+			}
+			return file, name, err
+		})
+		if err := call(t, root); err == nil || !strings.Contains(err.Error(), "读取临时文件身份失败") {
+			t.Fatalf("error = %v", err)
+		}
+	})
+
+	t.Run("temp sync", func(t *testing.T) {
+		root := t.TempDir()
+		installPinnedPullSuccess(t)
+		testseam.Swap(t, &pullSyncTemp, func(*os.File) error { return errTestDownload })
+		if err := call(t, root); err == nil || !strings.Contains(err.Error(), "同步临时文件失败") {
+			t.Fatalf("error = %v", err)
+		}
+	})
+
+	t.Run("temp close", func(t *testing.T) {
+		root := t.TempDir()
+		installPinnedPullSuccess(t)
+		testseam.Swap(t, &pullCloseTemp, func(*os.File) error { return errTestDownload })
+		if err := call(t, root); err == nil || !strings.Contains(err.Error(), "关闭临时文件失败") {
+			t.Fatalf("error = %v", err)
+		}
+	})
+
+	t.Run("temp identity", func(t *testing.T) {
+		root := t.TempDir()
+		installPinnedPullSuccess(t)
+		other := filepath.Join(t.TempDir(), "other")
+		if err := os.WriteFile(other, []byte("other"), 0o600); err != nil {
+			t.Fatal(err)
+		}
+		otherInfo, err := os.Lstat(other)
+		if err != nil {
+			t.Fatal(err)
+		}
+		downloaded := false
+		testseam.Swap(t, &pullDownloadFile, func(_ context.Context, _ string, _ map[string]string, destination *os.File) error {
+			downloaded = true
+			_, err := destination.WriteString("remote")
+			return err
+		})
+		testseam.Swap(t, &pullRootLstat, func(root *os.Root, name string) (os.FileInfo, error) {
+			if downloaded && strings.HasPrefix(name, ".dws-pull-") {
+				return otherInfo, nil
+			}
+			return root.Lstat(name)
+		})
+		if err := call(t, root); err == nil || !strings.Contains(err.Error(), "临时文件在下载期间被替换") {
+			t.Fatalf("error = %v", err)
+		}
+	})
+
+	t.Run("target becomes directory", func(t *testing.T) {
+		root := t.TempDir()
+		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
+			}
+			return os.Mkdir(filepath.Join(root, "a.txt"), 0o755)
+		})
+		if err := call(t, root); err == nil || !strings.Contains(err.Error(), "不是常规文件") {
+			t.Fatalf("error = %v", err)
+		}
+	})
+}
+
+func TestCrossPlatformCoverageDefaultPullDownloadFileBranches(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, request *http.Request) {
+		if request.Header.Get("X-Test") != "yes" {
+			t.Errorf("header = %q", request.Header.Get("X-Test"))
+		}
+		if request.URL.Path == "/status" {
+			http.Error(w, "denied", http.StatusTeapot)
+			return
+		}
+		_, _ = io.WriteString(w, "payload")
+	}))
+	defer server.Close()
+
+	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")
+	}
+	cancelled, cancel := context.WithCancel(context.Background())
+	cancel()
+	if err := defaultPullDownloadFile(cancelled, server.URL, nil, destination); !errors.Is(err, context.Canceled) {
+		t.Fatalf("cancelled error = %v", err)
+	}
+	if err := defaultPullDownloadFile(context.Background(), server.URL+"/status", map[string]string{"X-Test": "yes"}, destination); err == nil {
+		t.Fatal("expected HTTP status failure")
+	}
+	if err := defaultPullDownloadFile(context.Background(), server.URL+"/ok", map[string]string{"X-Test": "yes"}, destination); err != nil {
+		t.Fatal(err)
+	}
+
+	closed, err := os.Create(filepath.Join(t.TempDir(), "closed"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	_ = closed.Close()
+	if err := defaultPullDownloadFile(context.Background(), server.URL+"/ok", map[string]string{"X-Test": "yes"}, closed); err == nil {
+		t.Fatal("expected destination copy failure")
+	}
+}
+
+func TestCrossPlatformCoverageDriveSyncKeepBothLinkRemainsPinnedWhenParentMoves(t *testing.T) {
+	root := t.TempDir()
+	outside := t.TempDir()
+	sub := filepath.Join(root, "sub")
+	if err := os.Mkdir(sub, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(sub, "a.txt"), []byte("local"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	for name, content := range map[string]string{
+		"a.txt":              "attacker-destination",
+		"a.conflict-FID.txt": "attacker-source",
+	} {
+		if err := os.WriteFile(filepath.Join(outside, name), []byte(content), 0o600); err != nil {
+			t.Fatal(err)
+		}
+	}
+	testseam.Swap(t, &deps, &Deps{Caller: &driveSyncMockCaller{}, Out: &Formatter{w: io.Discard}})
+	testseam.Swap(t, &os.Args, []string{"dws", "drive"})
+
+	links := 0
+	parked := ""
+	testseam.Swap(t, &syncRootLink, func(parent *os.Root, oldName, newName string) error {
+		links++
+		// reserve 已完成 verifyParent；在真正 no-clobber Link 前换链，验证操作
+		// 仍只落在已固定的 parentRoot，而不会沿新软链进入根外目录。
+		parked = replacePullAncestorWithOutsideLink(t, root, outside)
+		return parent.Link(oldName, newName)
+	})
+
+	res := &driveSyncResult{}
+	syncKeepBoth(res, context.Background(), "", &remoteFile{FileID: "FID"}, root, "sub/a.txt", map[string]bool{})
+	if res.Summary.Failed != 1 || links != 1 {
+		t.Fatalf("result=%#v links=%d", res, links)
+	}
+	for _, name := range []string{"a.txt", "a.conflict-FID.txt"} {
+		if content, err := os.ReadFile(filepath.Join(parked, name)); err != nil || string(content) != "local" {
+			t.Fatalf("固定目录内的 %s 未安全保留: content=%q err=%v", name, content, err)
+		}
+	}
+	for name, want := range map[string]string{
+		"a.txt":              "attacker-destination",
+		"a.conflict-FID.txt": "attacker-source",
+	} {
+		if content, err := os.ReadFile(filepath.Join(outside, name)); err != nil || string(content) != want {
+			t.Fatalf("根外 %s 被硬链接触碰: content=%q err=%v", name, content, err)
+		}
+	}
+}
+
+func TestCrossPlatformCoverageDriveSyncKeepBothDetectsCandidateMutationDuringTransfer(t *testing.T) {
+	for _, mutation := range []string{"deleted", "replaced", "modified"} {
+		t.Run(mutation, func(t *testing.T) {
+			root := t.TempDir()
+			if err := os.WriteFile(filepath.Join(root, "a.txt"), []byte("local"), 0o600); err != nil {
+				t.Fatal(err)
+			}
+			candidate := filepath.Join(root, "a.conflict-FID.txt")
+			testseam.Swap(t, &deps, &Deps{Caller: &driveSyncMockCaller{}, Out: &Formatter{w: io.Discard}})
+			testseam.Swap(t, &os.Args, []string{"dws", "drive"})
+			testseam.Swap(t, &pullDownloadFile, func(_ context.Context, _ string, _ map[string]string, destination *os.File) error {
+				if _, err := destination.WriteString("remote"); err != nil {
+					return err
+				}
+				switch mutation {
+				case "deleted":
+					return os.Remove(candidate)
+				case "replaced":
+					if err := os.Remove(candidate); err != nil {
+						return err
+					}
+					return os.WriteFile(candidate, []byte("attacker"), 0o600)
+				default:
+					return os.WriteFile(candidate, []byte("modified-local-version"), 0o600)
+				}
+			})
+
+			res := &driveSyncResult{}
+			syncKeepBoth(res, context.Background(), "", &remoteFile{FileID: "FID"}, root, "a.txt", map[string]bool{})
+			if res.Summary.Failed != 1 || res.Summary.Pulled != 0 || len(res.Items) != 1 {
+				t.Fatalf("result=%#v", res)
+			}
+			if res.Items[0].Action != syncActionFailed || !strings.Contains(res.Items[0].Error, "本地保留版本在传输期间") {
+				t.Fatalf("candidate mutation must be failed, got %#v", res.Items)
+			}
+			if content, err := os.ReadFile(filepath.Join(root, "a.txt")); err != nil || string(content) != "remote" {
+				t.Fatalf("remote publish result changed: content=%q err=%v", content, err)
+			}
+		})
+	}
+}
+
+func TestCrossPlatformCoverageDrivePullCommandPinsRootAcrossAllFiles(t *testing.T) {
+	root := t.TempDir()
+	outside := t.TempDir()
+	caller := pullListingCaller(
+		`{"name":"a.txt","type":"file","fileId":"A"},` +
+			`{"name":"b.txt","type":"file","fileId":"B"}`)
+	testseam.Swap(t, &deps, &Deps{Caller: caller, Out: &Formatter{w: io.Discard}})
+	testseam.Swap(t, &os.Args, []string{"dws", "drive", "pull"})
+
+	calls := 0
+	parked := filepath.Join(t.TempDir(), "original-root")
+	testseam.Swap(t, &pullDownloadFile, func(_ context.Context, _ string, _ map[string]string, destination *os.File) error {
+		calls++
+		if _, err := destination.WriteString("remote"); err != nil {
+			return err
+		}
+		if calls == 1 {
+			replacePullCommandRootWithOutsideLink(t, root, parked, outside)
+		}
+		return nil
+	})
+
+	cmd := findDriveSubcommand(t, "pull")
+	mustSetFlags(t, cmd, map[string]string{"local-folder": root, "remote-folder": "ROOT", "if-exists": "overwrite"})
+	if err := runDrivePull(cmd, nil); err == nil {
+		t.Fatal("root replacement must fail the command")
+	}
+	if calls != 1 {
+		t.Fatalf("second file must fail before transfer when command root changed: calls=%d", calls)
+	}
+	if entries, err := os.ReadDir(outside); err != nil || len(entries) != 0 {
+		t.Fatalf("outside root was touched: entries=%v err=%v", entries, err)
+	}
+}
+
+func TestCrossPlatformCoverageDrivePullPlansExistingRootBeforeRemoteRead(t *testing.T) {
+	parent := t.TempDir()
+	root := filepath.Join(parent, "mirror")
+	outside := t.TempDir()
+	parked := filepath.Join(parent, "mirror-pinned")
+	if err := os.Mkdir(root, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	caller := &driveScriptCaller{reply: func(tool string, _ map[string]any, _ int) (string, error) {
+		if tool != "list_files" {
+			t.Fatalf("root replacement must stop before %s", tool)
+		}
+		replacePullCommandRootWithOutsideLink(t, root, parked, outside)
+		return `{"result":{"items":[{"name":"a.txt","type":"file","fileId":"A"}]}}`, nil
+	}}
+	getCalls := 0
+	testseam.Swap(t, &pullDownloadFile, func(context.Context, string, map[string]string, *os.File) error {
+		getCalls++
+		return nil
+	})
+
+	err := runDriveCmd(t, caller, "pull", "--local-folder", root, "--remote-folder", "ROOT", "--if-exists", "overwrite")
+	if err == nil || !strings.Contains(err.Error(), "本地根目录在同步期间被替换") {
+		t.Fatalf("error=%v", err)
+	}
+	if len(caller.callsFor("download_file")) != 0 || getCalls != 0 {
+		t.Fatalf("root replacement reached transfer: MCP=%d GET=%d", len(caller.callsFor("download_file")), getCalls)
+	}
+	if entries, readErr := os.ReadDir(outside); readErr != nil || len(entries) != 0 {
+		t.Fatalf("outside root was touched: entries=%v err=%v", entries, readErr)
+	}
+}
+
+func TestCrossPlatformCoverageDrivePullPlansMissingRootBeforeRemoteRead(t *testing.T) {
+	for _, takeover := range []string{"directory", "symlink"} {
+		t.Run(takeover, func(t *testing.T) {
+			parent := t.TempDir()
+			root := filepath.Join(parent, "missing", "mirror")
+			outside := t.TempDir()
+			caller := &driveScriptCaller{reply: func(tool string, _ map[string]any, _ int) (string, error) {
+				if tool != "list_files" {
+					t.Fatalf("missing-root takeover must stop before %s", tool)
+				}
+				if takeover == "directory" {
+					if err := os.MkdirAll(root, 0o755); err != nil {
+						t.Fatal(err)
+					}
+				} else {
+					if err := os.MkdirAll(filepath.Dir(root), 0o755); err != nil {
+						t.Fatal(err)
+					}
+					if err := os.Symlink(outside, root); err != nil {
+						t.Skipf("symlink unsupported: %v", err)
+					}
+				}
+				return `{"result":{"items":[{"name":"a.txt","type":"file","fileId":"A"}]}}`, nil
+			}}
+			getCalls := 0
+			testseam.Swap(t, &pullDownloadFile, func(context.Context, string, map[string]string, *os.File) error {
+				getCalls++
+				return nil
+			})
+
+			err := runDriveCmd(t, caller, "pull", "--local-folder", root, "--remote-folder", "ROOT", "--if-exists", "overwrite")
+			if err == nil || !strings.Contains(err.Error(), "在远端读取期间被占用") {
+				t.Fatalf("error=%v", err)
+			}
+			if len(caller.callsFor("download_file")) != 0 || getCalls != 0 {
+				t.Fatalf("missing-root takeover reached transfer: MCP=%d GET=%d", len(caller.callsFor("download_file")), getCalls)
+			}
+			if entries, readErr := os.ReadDir(outside); readErr != nil || len(entries) != 0 {
+				t.Fatalf("outside root was touched: entries=%v err=%v", entries, readErr)
+			}
+		})
+	}
+}
+
+func TestCrossPlatformCoverageDrivePullDryRunDoesNotMaterializeMissingRoot(t *testing.T) {
+	root := filepath.Join(t.TempDir(), "missing", "mirror")
+	caller := &driveScriptCaller{dryRun: true, reply: func(tool string, _ map[string]any, _ int) (string, error) {
+		if tool != "list_files" {
+			t.Fatalf("dry-run must stop before %s", tool)
+		}
+		return `{"result":{"items":[{"name":"a.txt","type":"file","fileId":"A"}]}}`, nil
+	}}
+	if err := runDriveCmd(t, caller, "pull", "--local-folder", root, "--remote-folder", "ROOT", "--dry-run"); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := os.Lstat(root); !os.IsNotExist(err) {
+		t.Fatalf("dry-run materialized missing root: %v", err)
+	}
+}
+
+func TestCrossPlatformCoverageDriveSyncCommandPinsRootAcrossAllFiles(t *testing.T) {
+	root := t.TempDir()
+	outside := t.TempDir()
+	caller := &driveSyncMockCaller{listJSON: `{"result":{"items":[` +
+		`{"name":"a.txt","type":"file","fileId":"A"},` +
+		`{"name":"b.txt","type":"file","fileId":"B"}` +
+		`],"nextToken":""}}`}
+	testseam.Swap(t, &deps, &Deps{Caller: caller, Out: &Formatter{w: io.Discard}})
+	testseam.Swap(t, &os.Args, []string{"dws", "drive", "sync"})
+	testseam.Swap(t, &pushPutOpenedFile, func(context.Context, string, map[string]string, *os.File, int64) error { return nil })
+
+	calls := 0
+	parked := filepath.Join(t.TempDir(), "original-root")
+	testseam.Swap(t, &pullDownloadFile, func(_ context.Context, _ string, _ map[string]string, destination *os.File) error {
+		calls++
+		if _, err := destination.WriteString("remote"); err != nil {
+			return err
+		}
+		if calls == 1 {
+			replacePullCommandRootWithOutsideLink(t, root, parked, outside)
+		}
+		return nil
+	})
+
+	cmd := findDriveSubcommand(t, "sync")
+	mustSetFlags(t, cmd, map[string]string{"local-folder": root, "remote-folder": "ROOT"})
+	if err := runDriveSync(cmd, nil); err == nil {
+		t.Fatal("root replacement must fail sync")
+	}
+	if calls != 1 {
+		t.Fatalf("second sync file must fail before transfer when command root changed: calls=%d", calls)
+	}
+	if entries, err := os.ReadDir(outside); err != nil || len(entries) != 0 {
+		t.Fatalf("outside root was touched: entries=%v err=%v", entries, err)
+	}
+}
+
+func TestCrossPlatformCoverageDrivePullReappliesSkipAndSmartAtPublish(t *testing.T) {
+	for _, policy := range []string{ifExistsSkip, ifExistsSmart} {
+		t.Run(policy, func(t *testing.T) {
+			root := t.TempDir()
+			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
+				}
+				return os.WriteFile(filepath.Join(root, "a.txt"), []byte("concurrent"), 0o600)
+			})
+			action, err := pullOneFileAtRoot(context.Background(), "", &remoteFile{FileID: "F"}, root, "a.txt", policy)
+			if err != nil || action != pullActionSkipped {
+				t.Fatalf("action=%q err=%v", action, err)
+			}
+			if content, err := os.ReadFile(filepath.Join(root, "a.txt")); err != nil || string(content) != "concurrent" {
+				t.Fatalf("concurrent target was overwritten: content=%q err=%v", content, err)
+			}
+		})
+	}
+}
+
+func TestCrossPlatformCoverageDrivePullPublicationIdentityAndLinkFailures(t *testing.T) {
+	t.Run("link failure without target is not skipped", func(t *testing.T) {
+		root := t.TempDir()
+		installPinnedPullSuccess(t)
+		testseam.Swap(t, &pullLink, func(*os.Root, string, 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 mismatch preserves unknown terminal", func(t *testing.T) {
+		root := t.TempDir()
+		installPinnedPullSuccess(t)
+		other := filepath.Join(t.TempDir(), "other")
+		if err := os.WriteFile(other, []byte("other"), 0o600); err != nil {
+			t.Fatal(err)
+		}
+		otherInfo, _ := os.Lstat(other)
+		published := false
+		testseam.Swap(t, &pullRename, func(root *os.Root, oldName, newName string) error {
+			if err := root.Rename(oldName, newName); err != nil {
+				return err
+			}
+			published = true
+			return nil
+		})
+		testseam.Swap(t, &pullRootLstat, func(root *os.Root, name string) (os.FileInfo, error) {
+			if published && name == "a.txt" {
+				return otherInfo, nil
+			}
+			return root.Lstat(name)
+		})
+		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)
+		}
+		if content, err := os.ReadFile(filepath.Join(root, "a.txt")); err != nil || string(content) != "remote" {
+			t.Fatalf("未知 terminal entry 应保留: content=%q err=%v", content, err)
+		}
+	})
+}
+
+// os.Root 只保证路径不能逃逸根目录，仍会跟随指向根内目录的相对软链接。若 sub 在
+// Lstat 与 OpenRoot 之间被换成 sub -> victim，pull/sync/keep-both 都必须在任何远端
+// 读取或本地写入前拒绝，不能把 remote sub/a.txt 重定向到 victim/a.txt。
+func TestCrossPlatformCoverageDrivePullSyncKeepBothRejectRootInternalRedirect(t *testing.T) {
+	for _, redirect := range []string{"symlink", "directory"} {
+		for _, command := range []string{"pull", "sync", "keep-both"} {
+			t.Run(redirect+"/"+command, func(t *testing.T) {
+				root := t.TempDir()
+				sub := filepath.Join(root, "sub")
+				parked := filepath.Join(root, "sub-pinned")
+				victim := filepath.Join(root, "victim")
+				if err := os.Mkdir(sub, 0o755); err != nil {
+					t.Fatal(err)
+				}
+				if err := os.Mkdir(victim, 0o755); err != nil {
+					t.Fatal(err)
+				}
+				mustWrite(t, filepath.Join(sub, "a.txt"), "local")
+				mustWrite(t, filepath.Join(victim, "a.txt"), "victim")
+
+				caller := &driveScriptCaller{reply: func(tool string, _ map[string]any, _ int) (string, error) {
+					if tool != "download_file" {
+						t.Fatalf("unexpected tool %q", tool)
+					}
+					return `{"result":{"downloadUrl":"https://oss.example.com/get"}}`, nil
+				}}
+				testseam.Swap(t, &deps, &Deps{Caller: caller, Out: &Formatter{w: io.Discard}})
+				testseam.Swap(t, &os.Args, []string{"dws", "drive"})
+				testseam.Swap(t, &pullDownloadFile, func(_ context.Context, _ string, _ map[string]string, destination *os.File) error {
+					_, err := destination.WriteString("remote")
+					return err
+				})
+
+				redirectedVictim := filepath.Join(victim, "a.txt")
+				swapped := false
+				testseam.Swap(t, &pullOpenParentRoot, func(parent *os.Root, name string) (*os.Root, error) {
+					if name == "sub" && !swapped {
+						swapped = true
+						if err := os.Rename(sub, parked); err != nil {
+							t.Fatal(err)
+						}
+						if redirect == "symlink" {
+							if err := os.Symlink("victim", sub); err != nil {
+								t.Skipf("平台不支持创建符号链接: %v", err)
+							}
+						} else {
+							if err := os.Rename(victim, sub); err != nil {
+								t.Fatal(err)
+							}
+							redirectedVictim = filepath.Join(sub, "a.txt")
+						}
+					}
+					return parent.OpenRoot(name)
+				})
+
+				rf := &remoteFile{RelPath: "sub/a.txt", FileID: "F"}
+				switch command {
+				case "pull":
+					action, err := pullOneFileAtRoot(context.Background(), "", rf, root, rf.RelPath, ifExistsOverwrite)
+					if err == nil || action != pullActionFailed {
+						t.Fatalf("action=%q err=%v", action, err)
+					}
+				case "sync":
+					res := &driveSyncResult{}
+					syncPullFile(res, context.Background(), "", rf, root, rf.RelPath, syncDirectionPull)
+					if res.Summary.Failed != 1 || res.Summary.Pulled != 0 {
+						t.Fatalf("sync result=%#v", res)
+					}
+				default:
+					res := &driveSyncResult{}
+					syncKeepBoth(res, context.Background(), "", rf, root, rf.RelPath, map[string]bool{})
+					if res.Summary.Failed != 1 || res.Summary.Pulled != 0 {
+						t.Fatalf("keep-both result=%#v", res)
+					}
+				}
+
+				if !swapped {
+					t.Fatal("test did not install the root-internal redirect")
+				}
+				if got := len(caller.callsFor("download_file")); got != 0 {
+					t.Fatalf("root-internal redirect reached download_file: %d", got)
+				}
+				for path, want := range map[string]string{
+					filepath.Join(parked, "a.txt"): "local",
+					redirectedVictim:               "victim",
+				} {
+					content, err := os.ReadFile(path)
+					if err != nil || string(content) != want {
+						t.Fatalf("%s changed: content=%q err=%v", path, content, err)
+					}
+				}
+				if matches, err := filepath.Glob(filepath.Join(filepath.Dir(redirectedVictim), "a.conflict-*.txt")); err != nil || len(matches) != 0 {
+					t.Fatalf("keep-both wrote into redirected victim: matches=%v err=%v", matches, err)
+				}
+			})
+		}
+	}
+}

internal/helpers/drive_push.go

@@ -0,0 +1,862 @@
+package helpers
+
+import (
+	"context"
+	"crypto/md5"
+	"encoding/base64"
+	"encoding/json"
+	"fmt"
+	"io"
+	"io/fs"
+	"net/http"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+	"time"
+
+	"github.com/spf13/cobra"
+	"golang.org/x/text/unicode/norm"
+)
+
+// ==========================================================
+// drive push — 把本地文件夹镜像到钉盘（本地 → Drive）
+// ==========================================================
+// ──────────────────────────────────────────────────────────
+// dws drive push — 把本地目录单向、文件级镜像到钉盘（本地 → Drive）
+//
+// 递归遍历 --local-folder 下所有常规文件与子目录（含空目录），按相对路径在
+// --remote-folder 指向的钉盘文件夹里新建/覆盖/跳过。已存在的远端目录复用其
+// fileId、不重建；缺失的目录按需 create_folder。文件按 --if-exists 决定
+// skip / smart / overwrite。summary.failed > 0 时以非零退出码退出（结构化
+// summary + items 仍打印在 stdout 上）。
+// ──────────────────────────────────────────────────────────
+
+// push 动作分类。
+const (
+	pushActionUploaded      = "uploaded"       // 新建上传
+	pushActionOverwritten   = "overwritten"    // 覆盖已存在的远端文件
+	pushActionSkipped       = "skipped"        // 按 --if-exists 跳过
+	pushActionFolderCreated = "folder_created" // 新建远端目录（不计入 uploaded）
+	pushActionFailed        = "failed"
+)
+
+// localPushFile 描述一个待推送的本地常规文件。
+type localPushFile struct {
+	RelPath       string
+	AbsPath       string
+	ModTimeMillis int64
+	Size          int64
+	scanInfo      os.FileInfo
+}
+
+// pushPutOpenedFile 把已由固定 os.Root 打开的本地文件句柄上传到 OSS。生产 push/sync
+// 不再把可被并发换链的绝对路径交给 HTTP 层重新打开；测试必须通过 testseam.Swap 替换。
+var (
+	pushPutOpenedFile  = defaultPushPutOpenedFile
+	pushStatOpenedFile = func(file *os.File) (os.FileInfo, error) {
+		return file.Stat()
+	}
+	pushVerifyPinnedSourceRoot = func(root *pinnedPullRoot) error {
+		return root.verify()
+	}
+	pushMD5OpenedFile = func(file *os.File) (string, error) {
+		hash := md5.New()
+		if _, err := io.Copy(hash, file); err != nil {
+			return "", err
+		}
+		return base64.StdEncoding.EncodeToString(hash.Sum(nil)), nil
+	}
+)
+
+// drivePushItem 是输出 items[] 中每个条目的明细。
+type drivePushItem struct {
+	RelPath   string `json:"rel_path"`
+	Action    string `json:"action"`
+	SizeBytes *int64 `json:"size_bytes,omitempty"`
+	Error     string `json:"error,omitempty"`
+}
+
+// drivePushSummary 是各动作的计数汇总。uploaded 同时统计新建与覆盖。
+type drivePushSummary struct {
+	Uploaded int  `json:"uploaded"`
+	Skipped  int  `json:"skipped"`
+	Failed   int  `json:"failed"`
+	Aborted  bool `json:"aborted"`
+}
+
+type drivePushResult struct {
+	Summary drivePushSummary `json:"summary"`
+	Items   []drivePushItem  `json:"items"`
+}
+
+type drivePushDryRunResult 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        drivePushResult `json:"plan"`
+}
+
+// drivePushFailure 在 summary.failed > 0 时返回：结构化结果已打印到 stdout，
+// 这里只负责以 exit=1 退出并向 stderr 输出一行简短说明。
+type drivePushFailure struct{ failed int }
+
+func (e *drivePushFailure) Error() string {
+	return fmt.Sprintf("drive push: %d file(s) failed", e.failed)
+}
+func (e *drivePushFailure) RawStderr() string { return e.Error() }
+func (e *drivePushFailure) ExitCode() int     { return 1 }
+
+func runDrivePush(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")
+	spaceID := mustGetFlag(cmd, "space-id")
+
+	// push 默认 skip（安全，只新增不覆盖）。
+	ifExists, _ := cmd.Flags().GetString("if-exists")
+	if ifExists == "" {
+		ifExists = ifExistsSkip
+	}
+	switch ifExists {
+	case ifExistsSkip, ifExistsSmart, ifExistsOverwrite:
+	default:
+		return fmt.Errorf("--if-exists 取值非法: %s（可选 skip|smart|overwrite）", ifExists)
+	}
+
+	absDir, err := validateLocalDirAbs(localDir)
+	if err != nil {
+		return err
+	}
+	pinnedRoot, err := openExistingPinnedPullRoot(absDir)
+	if err != nil {
+		return fmt.Errorf("扫描本地目录失败: %w", err)
+	}
+	defer pinnedRoot.close()
+
+	localDirs, localFiles, err := runDriveMirrorWalkLocalForPushPinned(pinnedRoot)
+	if err != nil {
+		return fmt.Errorf("扫描本地目录失败: %w", err)
+	}
+
+	ctx := cmd.Context()
+	// 远端现状：已存在的文件（用于 --if-exists 判断）与目录（rel_path → fileId，用于复用/定位父目录）。
+	remoteFiles, remoteFolders, err := fetchRemoteTreeForPush(ctx, spaceID, remoteDirID)
+	if err != nil {
+		return err
+	}
+
+	preflight := buildMirrorPreflight(localDirs, localFiles, remoteFiles, remoteFolders)
+
+	res := drivePushResult{Items: make([]drivePushItem, 0, len(localDirs)+len(localFiles))}
+	if deps.Caller.DryRun() {
+		return printDrivePushDryRunWithPreflight(ifExists, remoteFiles, remoteFolders, localDirs, localFiles, preflight)
+	}
+	if len(preflight) > 0 {
+		appendDrivePushPreflightFailures(&res, preflight)
+		if perr := deps.Out.PrintJSON(res); perr != nil {
+			return perr
+		}
+		return &drivePushFailure{failed: res.Summary.Failed}
+	}
+	// 本地扫描与远端读取都可能耗时。首个远端写之前确认命令行路径仍指向最初固定
+	// 的根；若根已被移走或替换，整批中止，不能把替代目录的数据当成扫描快照上传。
+	if err := pinnedRoot.verify(); err != nil {
+		return err
+	}
+
+	// 第一阶段：按需创建远端目录（浅层在前，保证父目录先于子目录存在）。
+	for _, dir := range localDirs {
+		if _, ok := remoteFolders[dir]; ok {
+			continue // 远端已存在，复用 fileId，不留痕
+		}
+		parentRel, name := splitRel(dir)
+		parentID, ok := remoteFolders[parentRel]
+		if !ok || parentID == "" {
+			res.Summary.Failed++
+			res.Items = append(res.Items, drivePushItem{RelPath: dir, Action: pushActionFailed, Error: "父目录未能创建"})
+			continue
+		}
+		if err := pinnedRoot.verify(); err != nil {
+			return err
+		}
+		fid, cerr := pushCreateFolder(ctx, spaceID, parentID, name)
+		if cerr != nil || fid == "" {
+			res.Summary.Failed++
+			msg := "create_folder 未返回 fileId"
+			if cerr != nil {
+				msg = cerr.Error()
+			}
+			res.Items = append(res.Items, drivePushItem{RelPath: dir, Action: pushActionFailed, Error: msg})
+			continue
+		}
+		remoteFolders[dir] = fid
+		res.Items = append(res.Items, drivePushItem{RelPath: dir, Action: pushActionFolderCreated})
+	}
+
+	// 第二阶段：上传/覆盖/跳过文件。
+	for i := range localFiles {
+		lf := localFiles[i]
+		size := lf.Size
+		parentRel, name := splitRel(lf.RelPath)
+		parentID, ok := remoteFolders[parentRel]
+		if !ok || parentID == "" {
+			res.Summary.Failed++
+			res.Items = append(res.Items, drivePushItem{RelPath: lf.RelPath, Action: pushActionFailed, SizeBytes: &size, Error: "父目录未能创建"})
+			continue
+		}
+
+		rf, exists := remoteFiles[lf.RelPath]
+		action := pushActionUploaded
+		overwriteID := ""
+		if exists {
+			switch ifExists {
+			case ifExistsSkip:
+				res.Summary.Skipped++
+				res.Items = append(res.Items, drivePushItem{RelPath: lf.RelPath, Action: pushActionSkipped, SizeBytes: &size})
+				continue
+			case ifExistsSmart:
+				// 远端时间可信且已 ≥ 本地 → 跳过；否则走覆盖路径。
+				if rf.ModifiedTimeValid && rf.ModifiedTime >= lf.ModTimeMillis {
+					res.Summary.Skipped++
+					res.Items = append(res.Items, drivePushItem{RelPath: lf.RelPath, Action: pushActionSkipped, SizeBytes: &size})
+					continue
+				}
+				action = pushActionOverwritten
+			case ifExistsOverwrite:
+				action = pushActionOverwritten
+			}
+			// 覆盖分支必须走覆盖上传（传 overwriteFileId、不传 parentId），
+			// 否则会在同目录新建重名副本而非原地覆盖。
+			if action == pushActionOverwritten {
+				overwriteID = rf.FileID
+			}
+		}
+
+		if err := pushUploadFilePinned(ctx, spaceID, parentID, overwriteID, name, pinnedRoot, lf); err != nil {
+			res.Summary.Failed++
+			res.Items = append(res.Items, drivePushItem{RelPath: lf.RelPath, Action: pushActionFailed, SizeBytes: &size, Error: err.Error()})
+			continue
+		}
+		res.Summary.Uploaded++ // uploaded 同时统计新建与覆盖
+		res.Items = append(res.Items, drivePushItem{RelPath: lf.RelPath, Action: action, SizeBytes: &size})
+	}
+
+	// 结构化结果始终打印到 stdout；有失败则额外以非零退出码退出。
+	if perr := deps.Out.PrintJSON(res); perr != nil {
+		return perr
+	}
+	if res.Summary.Failed > 0 {
+		return &drivePushFailure{failed: res.Summary.Failed}
+	}
+	return nil
+}
+
+// fetchRemoteTreeForPush 递归拉取 rootID 下的远端现状：files（rel_path → *remoteFile，
+// 用于 --if-exists 判断）与 folders（rel_path → fileId，rel_path "" 即 rootID 本身）。
+func fetchRemoteTreeForPush(ctx context.Context, spaceID, rootID string) (map[string]*remoteFile, map[string]string, error) {
+	files := make(map[string]*remoteFile)
+	folders := map[string]string{"": rootID}
+	occupied := make(map[string]string)
+	if err := walkRemoteForPush(ctx, spaceID, rootID, "", files, folders, occupied, 0); err != nil {
+		return nil, nil, err
+	}
+	return files, folders, nil
+}
+
+func walkRemoteForPush(ctx context.Context, spaceID, parentID, relBase string, files map[string]*remoteFile, folders map[string]string, occupied map[string]string, depth int) error {
+	if depth > remoteMaxDepth {
+		return fmt.Errorf("drive 目录层级超过 %d 层，疑似循环引用，已中止", remoteMaxDepth)
+	}
+	nextToken := ""
+	seenTokens := make(map[string]struct{})
+	for {
+		args := map[string]any{"maxResults": float64(driveListPageSize)}
+		if spaceID != "" {
+			args["spaceId"] = spaceID
+		}
+		if parentID != "" {
+			args["parentId"] = parentID
+		}
+		if nextToken != "" {
+			args["nextToken"] = nextToken
+		}
+
+		text, err := callDriveListFiles(ctx, args)
+		if err != nil {
+			return err
+		}
+		items, token, err := parseDriveList(text)
+		if err != nil {
+			return err
+		}
+
+		for _, it := range items {
+			name, included, err := remoteMirrorEntryName(it, relBase)
+			if err != nil {
+				return err
+			}
+			if !included {
+				continue
+			}
+			childRel := name
+			if relBase != "" {
+				childRel = relBase + "/" + name
+			}
+			if it.isFolder() {
+				if err := claimRemotePath(occupied, childRel, "目录"); err != nil {
+					return err
+				}
+				folderID := it.id()
+				if folderID == "" {
+					return fmt.Errorf("远端目录 %q 缺少目录 ID，已中止递归", childRel)
+				}
+				folders[childRel] = folderID
+				if err := walkRemoteForPush(ctx, spaceID, folderID, childRel, files, folders, occupied, depth+1); err != nil {
+					return err
+				}
+				continue
+			}
+			// 非文件类型已由 remoteMirrorEntryName 过滤；目录在上方完成递归后返回。
+			if err := claimRemotePath(occupied, childRel, "文件"); err != nil {
+				return err
+			}
+			fileID := it.id()
+			if fileID == "" {
+				return fmt.Errorf("远端文件 %q 缺少文件 ID，已中止遍历", childRel)
+			}
+			modMillis, modValid := it.modifiedMillis()
+			files[childRel] = &remoteFile{
+				RelPath:           childRel,
+				FileID:            fileID,
+				Hash:              it.hash(),
+				ModifiedTime:      modMillis,
+				ModifiedTimeValid: modValid,
+			}
+		}
+
+		if token == "" {
+			break
+		}
+		if _, exists := seenTokens[token]; exists {
+			return fmt.Errorf("远端目录 %q 的分页 token 重复，疑似分页循环，已中止", relBase)
+		}
+		seenTokens[token] = struct{}{}
+		nextToken = token
+	}
+	return nil
+}
+
+func printDrivePushDryRun(ifExists string, remoteFiles map[string]*remoteFile, remoteFolders map[string]string, localDirs []string, localFiles []localPushFile) error {
+	return printDrivePushDryRunWithPreflight(ifExists, remoteFiles, remoteFolders, localDirs, localFiles,
+		buildMirrorPreflight(localDirs, localFiles, remoteFiles, remoteFolders))
+}
+
+func printDrivePushDryRunWithPreflight(ifExists string, remoteFiles map[string]*remoteFile, remoteFolders map[string]string, localDirs []string, localFiles []localPushFile, preflight map[string]string) error {
+	plan := drivePushResult{Items: make([]drivePushItem, 0, len(localDirs)+len(localFiles))}
+	if len(preflight) > 0 {
+		appendDrivePushPreflightFailures(&plan, preflight)
+		return deps.Out.PrintJSON(drivePushDryRunResult{
+			DryRun: true, Executed: false, PreviewKind: "plan", Operation: "drive push",
+			IfExists: ifExists, Plan: plan,
+		})
+	}
+	plannedFolders := make(map[string]string, len(remoteFolders)+len(localDirs))
+	for rel, fileID := range remoteFolders {
+		plannedFolders[rel] = fileID
+	}
+	for _, dir := range localDirs {
+		if _, ok := plannedFolders[dir]; ok {
+			continue
+		}
+		parentRel, _ := splitRel(dir)
+		if plannedFolders[parentRel] == "" {
+			plan.Summary.Failed++
+			plan.Items = append(plan.Items, drivePushItem{RelPath: dir, Action: pushActionFailed, Error: "父目录未能创建"})
+			continue
+		}
+		plannedFolders[dir] = "dry-run-planned-folder"
+		plan.Items = append(plan.Items, drivePushItem{RelPath: dir, Action: pushActionFolderCreated})
+	}
+	for _, lf := range localFiles {
+		size := lf.Size
+		parentRel, _ := splitRel(lf.RelPath)
+		if plannedFolders[parentRel] == "" {
+			plan.Summary.Failed++
+			plan.Items = append(plan.Items, drivePushItem{RelPath: lf.RelPath, Action: pushActionFailed, SizeBytes: &size, Error: "父目录未能创建"})
+			continue
+		}
+		action := pushActionUploaded
+		if rf, exists := remoteFiles[lf.RelPath]; exists {
+			switch ifExists {
+			case ifExistsSkip:
+				action = pushActionSkipped
+			case ifExistsSmart:
+				if rf.ModifiedTimeValid && rf.ModifiedTime >= lf.ModTimeMillis {
+					action = pushActionSkipped
+				} else {
+					action = pushActionOverwritten
+				}
+			case ifExistsOverwrite:
+				action = pushActionOverwritten
+			}
+		}
+		if action == pushActionSkipped {
+			plan.Summary.Skipped++
+		} else {
+			plan.Summary.Uploaded++
+		}
+		plan.Items = append(plan.Items, drivePushItem{RelPath: lf.RelPath, Action: action, SizeBytes: &size})
+	}
+	return deps.Out.PrintJSON(drivePushDryRunResult{
+		DryRun: true, Executed: false, PreviewKind: "plan", Operation: "drive push",
+		IfExists: ifExists, Plan: plan,
+	})
+}
+
+func appendDrivePushPreflightFailures(res *drivePushResult, preflight map[string]string) {
+	res.Summary.Aborted = true
+	for _, rel := range mirrorPreflightFailureRels(preflight) {
+		res.Summary.Failed++
+		res.Items = append(res.Items, drivePushItem{RelPath: rel, Action: pushActionFailed, Error: preflight[rel]})
+	}
+}
+
+// pushTypeConflictError 在任何写操作或 dry-run 成功预览之前，拒绝同一路径下
+// “本地目录 ↔ 远端文件”或“本地文件 ↔ 远端目录”的类型冲突。
+func pushTypeConflictError(rel string, localIsFolder bool, remoteFiles map[string]*remoteFile, remoteFolders map[string]string) string {
+	if localIsFolder {
+		if _, exists := remoteFiles[rel]; exists {
+			return "远端同路径已存在文件，无法创建目录"
+		}
+		return ""
+	}
+	if _, exists := remoteFolders[rel]; exists {
+		return "远端同路径已存在目录，无法上传文件"
+	}
+	return ""
+}
+
+// walkLocalForPush 遍历本地根目录，返回所有子目录 rel_path（不含根本身，浅层在前）
+// 与所有常规文件。dirs 升序排序保证父目录先于子目录被创建。
+func walkLocalForPush(root string) ([]string, []localPushFile, error) {
+	pinned, err := openExistingPinnedPullRoot(root)
+	if err != nil {
+		return nil, nil, err
+	}
+	defer pinned.close()
+	return walkLocalForPushPinned(pinned)
+}
+
+// 文件系统遍历与命令入口通过显式 seam 暴露仅用于确定性覆盖 I/O 失败；测试必须用
+// testseam.Swap 替换，生产仍直接使用 fs.WalkDir / walkLocalForPushPinned。
+var (
+	walkPinnedLocalFS                    = fs.WalkDir
+	runDriveMirrorWalkLocalForPushPinned = walkLocalForPushPinned
+)
+
+// walkLocalForPushPinned 从命令开始时固定的同一个 os.Root/FS 扫描本地树。即使调用方
+// 给出的路径随后被替换成软链或另一目录，遍历也只会读取原目录树。
+func walkLocalForPushPinned(root *pinnedPullRoot) ([]string, []localPushFile, error) {
+	if err := root.verify(); err != nil {
+		return nil, nil, err
+	}
+	var dirs []string
+	var files []localPushFile
+	err := walkPinnedLocalFS(root.root.FS(), ".", func(path string, d fs.DirEntry, err error) error {
+		if err != nil {
+			return err
+		}
+		if path == "." {
+			return nil
+		}
+		relSlash := filepath.ToSlash(path)
+		if d.IsDir() {
+			dirs = append(dirs, relSlash)
+			return nil
+		}
+		info, infoErr := d.Info()
+		if infoErr != nil {
+			return infoErr
+		}
+		if !info.Mode().IsRegular() {
+			return nil
+		}
+		files = append(files, localPushFile{
+			RelPath: relSlash, AbsPath: filepath.Join(root.absDir, filepath.FromSlash(relSlash)),
+			ModTimeMillis: info.ModTime().UnixMilli(), Size: info.Size(), scanInfo: info,
+		})
+		return nil
+	})
+	if err != nil {
+		return nil, nil, err
+	}
+	if err := root.verify(); err != nil {
+		return nil, nil, err
+	}
+	// 字典序即浅层在前（"a" < "a/b" < "a/b/c"），父目录先于子目录。
+	sort.Strings(dirs)
+	sort.Slice(files, func(i, j int) bool { return files[i].RelPath < files[j].RelPath })
+	return dirs, files, nil
+}
+
+// judgePinnedPushFileMatch 与 judgeFileMatch 的判定保持一致，但 exact 模式只从固定
+// os.Root 打开的句柄计算 MD5，绝不按可被换链的 AbsPath 重开文件。
+func judgePinnedPushFileMatch(root *pinnedPullRoot, local localPushFile, remote *remoteFile, quick bool) (string, error) {
+	if quick {
+		if remote.ModifiedTimeValid && local.ModTimeMillis == remote.ModifiedTime {
+			return matchUnchanged, nil
+		}
+		return matchModified, nil
+	}
+	if remote.Hash == "" {
+		return matchUnknown, nil
+	}
+	file, err := root.root.Open(filepath.FromSlash(local.RelPath))
+	if err != nil {
+		return "", fmt.Errorf("计算 %s 的 MD5 失败: %w", local.RelPath, err)
+	}
+	defer file.Close()
+	info, err := pushStatOpenedFile(file)
+	if err != nil || !info.Mode().IsRegular() || (local.scanInfo != nil && !os.SameFile(local.scanInfo, info)) {
+		return "", fmt.Errorf("计算 %s 的 MD5 失败: 本地文件在扫描后被替换", local.RelPath)
+	}
+	hash, err := pushMD5OpenedFile(file)
+	if err != nil {
+		return "", fmt.Errorf("计算 %s 的 MD5 失败: %w", local.RelPath, err)
+	}
+	if err := pushVerifyPinnedSourceRoot(root); err != nil {
+		return "", err
+	}
+	if hash == remote.Hash {
+		return matchUnchanged, nil
+	}
+	return matchModified, nil
+}
+
+// mirrorPathKey 表示 Drive 镜像契约中的等价路径：逐段 Unicode NFC + 大小写折叠。
+// 该规则独立于运行命令的本地文件系统，避免 macOS/Windows 与 Drive 间把 a/A 或
+// NFC/NFD 当成“双向新增”，也避免把等价目录前缀错误拼接成另一棵树。
+func mirrorPathKey(rel string) string {
+	parts := strings.Split(rel, "/")
+	for i := range parts {
+		parts[i] = norm.NFC.String(strings.ToLower(parts[i]))
+	}
+	return strings.Join(parts, "/")
+}
+
+func mirrorLocalRelError(rel string) string {
+	for _, segment := range strings.Split(rel, "/") {
+		if !isSafeRemoteSegment(segment) || strings.IndexByte(segment, 0) >= 0 {
+			return fmt.Sprintf("本地路径 %q 含无法安全映射到远端的名称段 %q，已中止镜像", rel, segment)
+		}
+	}
+	return ""
+}
+
+// buildMirrorPreflight 在任何远端写之前统一检查本地名称和双端等价路径/类型。
+// 每个条目同时声明全部祖先目录，因而 local A/x 与 remote a/y 会在祖先键上冲突；
+// 即便本地为空，remote A/a 也会被完整性门禁识别。调用方必须整体拒绝写入，不能只
+// 跳过冲突项。
+func buildMirrorPreflight(localDirs []string, localFiles []localPushFile, remoteFiles map[string]*remoteFile, remoteFolders map[string]string) map[string]string {
+	type mirrorKind string
+	const (
+		mirrorFile mirrorKind = "文件"
+		mirrorDir  mirrorKind = "目录"
+	)
+	type entry struct {
+		rel  string
+		kind mirrorKind
+	}
+	local := make(map[string]map[entry]struct{})
+	remote := make(map[string]map[entry]struct{})
+	failures := make(map[string]string)
+	addClaims := func(index map[string]map[entry]struct{}, rel string, kind mirrorKind) {
+		parts := strings.Split(rel, "/")
+		for i := range parts {
+			claimKind := mirrorDir
+			if i == len(parts)-1 {
+				claimKind = kind
+			}
+			claimRel := strings.Join(parts[:i+1], "/")
+			key := mirrorPathKey(claimRel)
+			if index[key] == nil {
+				index[key] = make(map[entry]struct{})
+			}
+			index[key][entry{rel: claimRel, kind: claimKind}] = struct{}{}
+		}
+	}
+	addLocal := func(rel string, kind mirrorKind) {
+		if msg := mirrorLocalRelError(rel); msg != "" {
+			failures[rel] = msg
+		}
+		addClaims(local, rel, kind)
+	}
+	for _, rel := range localDirs {
+		addLocal(rel, mirrorDir)
+	}
+	for _, f := range localFiles {
+		addLocal(f.RelPath, mirrorFile)
+	}
+	for rel := range remoteFolders {
+		if rel != "" {
+			addClaims(remote, rel, mirrorDir)
+		}
+	}
+	for rel := range remoteFiles {
+		addClaims(remote, rel, mirrorFile)
+	}
+	keys := make(map[string]struct{}, len(local)+len(remote))
+	for key := range local {
+		keys[key] = struct{}{}
+	}
+	for key := range remote {
+		keys[key] = struct{}{}
+	}
+	for key := range keys {
+		claims := make(map[entry]struct{}, len(local[key])+len(remote[key]))
+		for claim := range local[key] {
+			claims[claim] = struct{}{}
+		}
+		for claim := range remote[key] {
+			claims[claim] = struct{}{}
+		}
+		if len(claims) <= 1 {
+			continue
+		}
+		for claim := range claims {
+			failures[claim.rel] = fmt.Sprintf("%s路径 %q 在镜像规则下存在大小写/Unicode NFC 等价路径拼写或类型歧义，已中止镜像", claim.kind, claim.rel)
+		}
+	}
+	return failures
+}
+
+func mirrorPreflightFailureRels(preflight map[string]string) []string {
+	rels := make([]string, 0, len(preflight))
+	for rel := range preflight {
+		rels = append(rels, rel)
+	}
+	sort.Strings(rels)
+	return rels
+}
+
+// walkLocalForPushEntry 是 walkLocalForPush 的单条目处理逻辑。抽成命名函数只为可测：
+// filepath.Rel / Info() 的失败在真实 WalkDir 下几乎不可复现，单测可直接注入。
+func walkLocalForPushEntry(root, path string, d fs.DirEntry, err error, dirs *[]string, files *[]localPushFile) error {
+	if err != nil {
+		return err
+	}
+	rel, rerr := filepath.Rel(root, path)
+	if rerr != nil {
+		return rerr
+	}
+	if rel == "." {
+		return nil // 根目录本身不处理
+	}
+	relSlash := filepath.ToSlash(rel)
+	if d.IsDir() {
+		*dirs = append(*dirs, relSlash)
+		return nil
+	}
+	info, ierr := d.Info()
+	if ierr != nil {
+		return ierr
+	}
+	// 只推送常规文件；符号链接、设备文件等忽略。
+	if !info.Mode().IsRegular() {
+		return nil
+	}
+	*files = append(*files, localPushFile{
+		RelPath:       relSlash,
+		AbsPath:       path,
+		ModTimeMillis: info.ModTime().UnixMilli(),
+		Size:          info.Size(),
+		scanInfo:      info,
+	})
+	return nil
+}
+
+// pushCreateFolder 在 parentID 下创建名为 name 的文件夹，返回新目录的 fileId。
+func pushCreateFolder(ctx context.Context, spaceID, parentID, name string) (string, error) {
+	args := map[string]any{"name": name}
+	if spaceID != "" {
+		args["spaceId"] = spaceID
+	}
+	if parentID != "" {
+		args["parentId"] = parentID
+	}
+	text, err := callMCPToolReturnText(ctx, "create_folder", args)
+	if err != nil {
+		return "", err
+	}
+	return parseNodeID(text), nil
+}
+
+// pushUploadFile 走 get_upload_info → OSS PUT → commit_upload 三步，把本地文件
+// 上传到 parentID 目录下。复用 drive upload 的凭证解析与 HTTP PUT。
+//
+// overwriteFileID 非空时走覆盖流程（与 uploadToDrive 一致）：get_upload_info 与
+// commit_upload 两个阶段都传 overwriteFileId、都不传 parentId（服务端据此设置
+// conflictStrategy=OVERWRITE，原地覆盖而非在同目录新建重名副本）。
+func pushUploadFile(ctx context.Context, spaceID, parentID, overwriteFileID, fileName, filePath string, fileSize int64) error {
+	return pushUploadWithTransport(ctx, spaceID, parentID, overwriteFileID, fileName, fileSize,
+		func(resourceURL string, ossHeaders map[string]string) error {
+			return httpPutFile(ctx, resourceURL, ossHeaders, filePath, fileSize)
+		})
+}
+
+// pushUploadFilePinned 从固定本地根打开 rel_path，并在发出 get_upload_info 前核对
+// 文件身份与扫描快照。HTTP PUT 只读取这个已打开句柄，绝不按 AbsPath 二次解析。
+func pushUploadFilePinned(ctx context.Context, spaceID, parentID, overwriteFileID, fileName string, root *pinnedPullRoot, local localPushFile) error {
+	if err := root.verify(); err != nil {
+		return err
+	}
+	file, err := root.root.Open(filepath.FromSlash(local.RelPath))
+	if err != nil {
+		return fmt.Errorf("打开本地上传文件失败: %w", err)
+	}
+	defer file.Close()
+	info, err := pushStatOpenedFile(file)
+	if err != nil {
+		return fmt.Errorf("读取本地上传文件身份失败: %w", err)
+	}
+	if !info.Mode().IsRegular() {
+		return fmt.Errorf("本地上传目标 %q 已不再是常规文件", local.RelPath)
+	}
+	if local.scanInfo != nil && !os.SameFile(local.scanInfo, info) {
+		return fmt.Errorf("本地上传目标 %q 在扫描后被替换，已中止上传", local.RelPath)
+	}
+	if info.Size() != local.Size || info.ModTime().UnixMilli() != local.ModTimeMillis {
+		return fmt.Errorf("本地上传目标 %q 在扫描后发生变化，已中止上传", local.RelPath)
+	}
+	if err := pushVerifyPinnedSourceRoot(root); err != nil {
+		return err
+	}
+	return pushUploadWithTransport(ctx, spaceID, parentID, overwriteFileID, fileName, local.Size,
+		func(resourceURL string, ossHeaders map[string]string) error {
+			if err := pushPutOpenedFile(ctx, resourceURL, ossHeaders, file, local.Size); err != nil {
+				return err
+			}
+			// OSS 传输期间若源文件被原地改写（编辑器覆盖、截断重写、mmap），
+			// PUT 里发送的可能是新旧内容的混合体，root.verify() 又不检查文件本身。
+			// commit 前对已打开句柄再取一次身份，与 PUT 前的 inode/size/mtime 逐项比对;
+			// 任一变化都拒绝 commit，避免 overwrite/local-wins 场景把混合内容覆盖到远端。
+			after, err := pushStatOpenedFile(file)
+			if err != nil {
+				return fmt.Errorf("上传后读取本地上传文件身份失败: %w", err)
+			}
+			if !os.SameFile(info, after) ||
+				after.Size() != info.Size() ||
+				after.ModTime().UnixMilli() != info.ModTime().UnixMilli() {
+				return fmt.Errorf("本地上传目标 %q 在传输期间被修改，已中止提交", local.RelPath)
+			}
+			// OSS 传输期间若命令行根已被替换，不提交这个上传会话；已发送的字节仍来自
+			// 固定根内的原文件句柄，不可能读取替代路径或根外内容。
+			return root.verify()
+		})
+}
+
+func pushUploadWithTransport(ctx context.Context, spaceID, parentID, overwriteFileID, fileName string, fileSize int64, put func(string, map[string]string) error) error {
+	step1 := map[string]any{"fileName": fileName, "fileSize": float64(fileSize)}
+	if spaceID != "" {
+		step1["spaceId"] = spaceID
+	}
+	if overwriteFileID != "" {
+		step1["overwriteFileId"] = overwriteFileID
+	} else if parentID != "" {
+		step1["parentId"] = parentID
+	}
+	text, err := callMCPToolReturnText(ctx, "get_upload_info", step1)
+	if err != nil {
+		return err
+	}
+	resourceURL, uploadID, ossHeaders, err := parseDriveUploadInfo(text)
+	if err != nil {
+		return err
+	}
+	if err := put(resourceURL, ossHeaders); err != nil {
+		return err
+	}
+	commit := map[string]any{"fileName": fileName, "fileSize": float64(fileSize), "uploadId": uploadID}
+	if spaceID != "" {
+		commit["spaceId"] = spaceID
+	}
+	if overwriteFileID != "" {
+		commit["overwriteFileId"] = overwriteFileID
+	} else if parentID != "" {
+		commit["parentId"] = parentID
+	}
+	commitText, err := callMCPToolReturnText(ctx, "commit_upload", commit)
+	if err != nil {
+		return err
+	}
+	if strings.TrimSpace(commitText) == "" {
+		return fmt.Errorf("commit_upload returned no business result; remote effect is unknown")
+	}
+	var result map[string]any
+	if err := json.Unmarshal([]byte(commitText), &result); err != nil {
+		return fmt.Errorf("parse commit_upload response: %w", err)
+	}
+	if len(result) == 0 {
+		return fmt.Errorf("commit_upload returned an empty JSON object; remote effect is unknown")
+	}
+	return nil
+}
+
+func defaultPushPutOpenedFile(ctx context.Context, url string, headers map[string]string, file *os.File, fileSize int64) error {
+	if _, err := file.Seek(0, io.SeekStart); err != nil {
+		return fmt.Errorf("failed to seek upload file: %w", err)
+	}
+	req, err := http.NewRequestWithContext(ctx, http.MethodPut, url, file)
+	if err != nil {
+		return fmt.Errorf("failed to create upload request: %w", err)
+	}
+	req.ContentLength = fileSize
+	req.Header.Del("Content-Type")
+	for key, value := range headers {
+		req.Header.Set(key, value)
+	}
+	resp, err := (&http.Client{Timeout: 5 * time.Minute}).Do(req)
+	if err != nil {
+		return fmt.Errorf("file upload failed: %w", err)
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode != http.StatusOK {
+		body, _ := io.ReadAll(resp.Body)
+		return fmt.Errorf("OSS upload failed: %w", &httpStatusError{StatusCode: resp.StatusCode, Body: string(body)})
+	}
+	return nil
+}
+
+// parseNodeID 从 create_folder / commit 等返回里抽出节点 fileId（带 fallback）。
+func parseNodeID(text string) string {
+	var data map[string]any
+	if err := json.Unmarshal([]byte(text), &data); err != nil {
+		return ""
+	}
+	if r, ok := data["result"].(map[string]any); ok {
+		data = r
+	}
+	for _, k := range []string{"fileId", "dentryUuid", "dentryId", "id", "nodeId"} {
+		if s, ok := data[k].(string); ok && s != "" {
+			return s
+		}
+	}
+	return ""
+}
+
+// splitRel 把 rel_path 拆成父路径与末段名："a/b/c" → ("a/b","c")，"c" → ("","c")。
+func splitRel(rel string) (string, string) {
+	if i := strings.LastIndex(rel, "/"); i >= 0 {
+		return rel[:i], rel[i+1:]
+	}
+	return "", rel
+}
+
+// checkFileNotDingTalkDoc 通过 get_file_info 检查文件类型，
+// 若为钉钉在线文档 (adoc/axls/amind/adraw) 则返回错误，提示使用对应服务命令。
+// 探测失败（如无效 fileId）不阻断流程，让后续 MCP 工具自行报错。

internal/helpers/drive_push_coverage_test.go

@@ -0,0 +1,449 @@
+package helpers
+
+import (
+	"context"
+	"errors"
+	"io"
+	"os"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam"
+)
+
+var errTestUpload = errors.New("simulated upload failure")
+
+// pushOKCaller 是 push 的“一切正常”mock：list_files 按 parentId 返回远端现状，
+// create_folder 返回新 fileId，get_upload_info 返回可解析凭证，ln 提交成功。
+func pushOKCaller(listing map[string]string) *driveScriptCaller {
+	return &driveScriptCaller{reply: func(tool string, args map[string]any, _ int) (string, error) {
+		switch tool {
+		case "list_files":
+			parent, _ := args["parentId"].(string)
+			if body, ok := listing[parent]; ok {
+				return body, nil
+			}
+			return `{"result":{"items":[],"nextToken":""}}`, nil
+		case "create_folder":
+			return `{"result":{"fileId":"NEWDIR"},"success":true}`, nil
+		case "get_upload_info":
+			return `{"result":{"resourceUrls":[{"url":"https://oss.example.com/put","headers":{}}],"uploadId":"U1"}}`, nil
+		}
+		return `{"result":{"fileId":"NEWFILE"},"success":true}`, nil
+	}}
+}
+
+func withNoopPut(t *testing.T) {
+	t.Helper()
+	testseam.Swap(t, &pushPutOpenedFile, func(context.Context, string, map[string]string, *os.File, int64) error { return nil })
+}
+
+// ──────────────────────────────────────────────────────────
+// runDrivePush — 端到端
+// ──────────────────────────────────────────────────────────
+
+// 本地子目录在远端缺失 → 按需 create_folder 并留 folder_created 痕迹，再上传其中文件。
+func TestCrossPlatformCoverageDrivePush_createsMissingRemoteFolders(t *testing.T) {
+	dir := t.TempDir()
+	if err := os.MkdirAll(filepath.Join(dir, "sub"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	mustWrite(t, filepath.Join(dir, "sub", "deep.txt"), "d")
+	withNoopPut(t)
+
+	caller := pushOKCaller(map[string]string{"ROOT": `{"result":{"items":[],"nextToken":""}}`})
+	if err := runDriveCmd(t, caller, "push", "--local-folder", dir, "--remote-folder", "ROOT"); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	cf := caller.callsFor("create_folder")
+	if len(cf) != 1 || cf[0].args["name"] != "sub" {
+		t.Fatalf("expected create_folder(sub), got %v", cf)
+	}
+	if cf[0].args["parentId"] != "ROOT" {
+		t.Errorf("create_folder parentId = %v, want ROOT", cf[0].args["parentId"])
+	}
+	// 新建目录的 fileId 必须成为其中文件的 parentId。
+	up := caller.callsFor("get_upload_info")
+	if len(up) != 1 || up[0].args["parentId"] != "NEWDIR" {
+		t.Errorf("upload parentId = %v, want NEWDIR", up[0].args["parentId"])
+	}
+}
+
+// 远端已存在同名目录 → 复用其 fileId，不重建、不出现在 items[]。
+func TestCrossPlatformCoverageDrivePush_reusesExistingRemoteFolder(t *testing.T) {
+	dir := t.TempDir()
+	if err := os.MkdirAll(filepath.Join(dir, "sub"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	mustWrite(t, filepath.Join(dir, "sub", "deep.txt"), "d")
+	withNoopPut(t)
+
+	caller := pushOKCaller(map[string]string{
+		"ROOT": `{"result":{"items":[{"name":"sub","type":"folder","fileId":"EXISTING"}],"nextToken":""}}`,
+	})
+	if err := runDriveCmd(t, caller, "push", "--local-folder", dir, "--remote-folder", "ROOT"); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if got := caller.callsFor("create_folder"); len(got) != 0 {
+		t.Errorf("existing remote folder must not be recreated, got %v", got)
+	}
+	if up := caller.callsFor("get_upload_info"); up[0].args["parentId"] != "EXISTING" {
+		t.Errorf("upload parentId = %v, want EXISTING", up[0].args["parentId"])
+	}
+}
+
+// create_folder 失败 / 未返回 fileId → 该目录记 failed，其中文件因父目录缺失也 failed。
+func TestCrossPlatformCoverageDrivePush_folderCreationFailureCascades(t *testing.T) {
+	for _, tc := range []struct {
+		name  string
+		reply func(string, map[string]any, int) (string, error)
+	}{
+		{"tool error", func(tool string, _ map[string]any, _ int) (string, error) {
+			if tool == "create_folder" {
+				return "", errors.New("create_folder boom")
+			}
+			return `{"result":{"items":[],"nextToken":""}}`, nil
+		}},
+		{"no fileId", func(tool string, _ map[string]any, _ int) (string, error) {
+			if tool == "create_folder" {
+				return `{"result":{},"success":true}`, nil
+			}
+			return `{"result":{"items":[],"nextToken":""}}`, nil
+		}},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			dir := t.TempDir()
+			if err := os.MkdirAll(filepath.Join(dir, "sub"), 0o755); err != nil {
+				t.Fatal(err)
+			}
+			mustWrite(t, filepath.Join(dir, "sub", "deep.txt"), "d")
+			withNoopPut(t)
+
+			caller := &driveScriptCaller{reply: tc.reply}
+			err := runDriveCmd(t, caller, "push", "--local-folder", dir, "--remote-folder", "ROOT")
+			var pf *drivePushFailure
+			if !errors.As(err, &pf) {
+				t.Fatalf("expected drivePushFailure, got %T %v", err, err)
+			}
+			// 目录 + 其中文件各记一次失败。
+			if pf.failed != 2 {
+				t.Errorf("failed = %d, want 2 (folder + orphaned file)", pf.failed)
+			}
+			if got := caller.callsFor("get_upload_info"); len(got) != 0 {
+				t.Errorf("no upload may happen without a parent folder, got %v", got)
+			}
+		})
+	}
+}
+
+// --if-exists skip（默认）：远端已存在 → 跳过，不上传。
+func TestCrossPlatformCoverageDrivePush_ifExistsSkipIsDefault(t *testing.T) {
+	dir := t.TempDir()
+	mustWrite(t, filepath.Join(dir, "a.txt"), "local")
+	withNoopPut(t)
+
+	caller := pushOKCaller(map[string]string{
+		"ROOT": `{"result":{"items":[{"name":"a.txt","type":"file","fileId":"A","modifyTime":1}],"nextToken":""}}`,
+	})
+	if err := runDriveCmd(t, caller, "push", "--local-folder", dir, "--remote-folder", "ROOT"); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if got := caller.callsFor("get_upload_info"); len(got) != 0 {
+		t.Errorf("default skip must not upload, got %v", got)
+	}
+}
+
+// --if-exists smart：远端时间已 ≥ 本地 → 跳过；远端更旧 → 覆盖上传。
+func TestCrossPlatformCoverageDrivePush_ifExistsSmart(t *testing.T) {
+	t.Run("remote newer skips", func(t *testing.T) {
+		dir := t.TempDir()
+		p := filepath.Join(dir, "a.txt")
+		mustWrite(t, p, "local")
+		local := readFileMTimeMillis(t, p)
+		withNoopPut(t)
+
+		caller := pushOKCaller(map[string]string{
+			"ROOT": `{"result":{"items":[{"name":"a.txt","type":"file","fileId":"A","modifyTime":` +
+				strconv.FormatInt(local+60000, 10) + `}],"nextToken":""}}`,
+		})
+		if err := runDriveCmd(t, caller, "push", "--local-folder", dir, "--remote-folder", "ROOT", "--if-exists", "smart"); err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if got := caller.callsFor("get_upload_info"); len(got) != 0 {
+			t.Errorf("smart must skip when remote is newer, got %v", got)
+		}
+	})
+
+	t.Run("remote older overwrites in place", func(t *testing.T) {
+		dir := t.TempDir()
+		p := filepath.Join(dir, "a.txt")
+		mustWrite(t, p, "local")
+		local := readFileMTimeMillis(t, p)
+		withNoopPut(t)
+
+		caller := pushOKCaller(map[string]string{
+			"ROOT": `{"result":{"items":[{"name":"a.txt","type":"file","fileId":"A","modifyTime":` +
+				strconv.FormatInt(local-60000, 10) + `}],"nextToken":""}}`,
+		})
+		if err := runDriveCmd(t, caller, "push", "--local-folder", dir, "--remote-folder", "ROOT", "--if-exists", "smart"); err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		up := caller.callsFor("get_upload_info")
+		if len(up) != 1 || up[0].args["overwriteFileId"] != "A" {
+			t.Fatalf("smart overwrite must pass overwriteFileId=A, got %v", up)
+		}
+		if _, has := up[0].args["parentId"]; has {
+			t.Error("overwrite upload must not carry parentId")
+		}
+	})
+
+	t.Run("remote time invalid overwrites", func(t *testing.T) {
+		dir := t.TempDir()
+		mustWrite(t, filepath.Join(dir, "a.txt"), "local")
+		withNoopPut(t)
+
+		// 远端无 modifyTime → 时间不可信，smart 不敢跳过，走覆盖。
+		caller := pushOKCaller(map[string]string{
+			"ROOT": `{"result":{"items":[{"name":"a.txt","type":"file","fileId":"A"}],"nextToken":""}}`,
+		})
+		if err := runDriveCmd(t, caller, "push", "--local-folder", dir, "--remote-folder", "ROOT", "--if-exists", "smart"); err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if up := caller.callsFor("get_upload_info"); len(up) != 1 {
+			t.Fatalf("expected overwrite upload, got %v", up)
+		}
+	})
+}
+
+// 上传失败 → 记 failed 并以非零退出码退出，结构化结果仍打印。
+func TestCrossPlatformCoverageDrivePush_uploadFailureExitsNonZero(t *testing.T) {
+	dir := t.TempDir()
+	mustWrite(t, filepath.Join(dir, "a.txt"), "local")
+	testseam.Swap(t, &pushPutOpenedFile, func(context.Context, string, map[string]string, *os.File, int64) error { return errTestUpload })
+
+	caller := pushOKCaller(nil)
+	err := runDriveCmd(t, caller, "push", "--local-folder", dir, "--remote-folder", "ROOT")
+	var pf *drivePushFailure
+	if !errors.As(err, &pf) || pf.failed != 1 {
+		t.Fatalf("expected 1 push failure, got %T %v", err, err)
+	}
+}
+
+// --if-exists 非法值直接拒绝。
+func TestCrossPlatformCoverageDrivePush_invalidIfExistsRejected(t *testing.T) {
+	err := runDriveCmd(t, pushOKCaller(nil), "push", "--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 必须透传到 create_folder / get_upload_info / ln 三处。
+func TestCrossPlatformCoverageDrivePush_passesSpaceIDEverywhere(t *testing.T) {
+	dir := t.TempDir()
+	if err := os.MkdirAll(filepath.Join(dir, "sub"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	mustWrite(t, filepath.Join(dir, "sub", "a.txt"), "x")
+	withNoopPut(t)
+
+	caller := pushOKCaller(nil)
+	if err := runDriveCmd(t, caller, "push", "--local-folder", dir, "--remote-folder", "ROOT", "--space-id", "SP7"); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	for _, tool := range []string{"list_files", "create_folder", "get_upload_info"} {
+		calls := caller.callsFor(tool)
+		if len(calls) == 0 {
+			t.Fatalf("%s was never called", tool)
+		}
+		if calls[0].args["spaceId"] != "SP7" {
+			t.Errorf("%s spaceId = %v, want SP7", tool, calls[0].args["spaceId"])
+		}
+	}
+}
+
+// 远端列举失败 → push 直接报错，不做任何上传。
+func TestCrossPlatformCoverageDrivePush_remoteListFailurePropagates(t *testing.T) {
+	dir := t.TempDir()
+	mustWrite(t, filepath.Join(dir, "a.txt"), "x")
+	caller := &driveScriptCaller{reply: func(string, map[string]any, int) (string, error) { return "", errTestList }}
+	if err := runDriveCmd(t, caller, "push", "--local-folder", dir, "--remote-folder", "ROOT"); err == nil {
+		t.Fatal("expected remote listing failure to propagate")
+	}
+}
+
+// 本地根目录不存在 → 扫描失败。
+func TestCrossPlatformCoverageDrivePush_missingLocalRootFails(t *testing.T) {
+	missing := filepath.Join(t.TempDir(), "absent")
+	err := runDriveCmd(t, pushOKCaller(nil), "push", "--local-folder", missing, "--remote-folder", "ROOT")
+	if err == nil || !strings.Contains(err.Error(), "扫描本地目录失败") {
+		t.Fatalf("expected local scan failure, got %v", err)
+	}
+}
+
+// ──────────────────────────────────────────────────────────
+// walkRemoteForPush — 分页、递归、深度上限、非镜像类型跳过
+// ──────────────────────────────────────────────────────────
+
+func TestCrossPlatformCoverageWalkRemoteForPush_paginationRecursionAndSkips(t *testing.T) {
+	// 递归会插在 ROOT 的两页之间，所以按 (parentId, nextToken) 判定而非调用序号。
+	caller := &driveScriptCaller{reply: func(_ string, args map[string]any, _ int) (string, error) {
+		parent, _ := args["parentId"].(string)
+		token, _ := args["nextToken"].(string)
+		if parent == "SUB" {
+			return `{"result":{"items":[{"name":"deep.txt","type":"file","fileId":"D"}],"nextToken":""}}`, nil
+		}
+		if parent == "ROOT" && token == "" {
+			return `{"result":{"items":[{"name":"sub","type":"folder","fileId":"SUB"}],"nextToken":"P2"}}`, nil
+		}
+		if parent == "ROOT" && token == "P2" {
+			return `{"result":{"items":[` +
+				`{"name":"online.adoc","type":"document","fileId":"DOC"},` +
+				`{"name":"ok.txt","type":"file","fileId":"OK"}` +
+				`],"nextToken":""}}`, nil
+		}
+		return `{"result":{"items":[],"nextToken":""}}`, nil
+	}}
+
+	testseam.Swap(t, &deps, &Deps{Caller: caller, Out: &Formatter{w: io.Discard}})
+	testseam.Swap(t, &os.Args, []string{"dws", "drive"})
+
+	files, folders, err := fetchRemoteTreeForPush(context.Background(), "", "ROOT")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if _, ok := folders["sub"]; !ok {
+		t.Error("sub folder must be indexed")
+	}
+	if _, ok := files["sub/deep.txt"]; !ok {
+		t.Error("nested file must be indexed with joined rel_path")
+	}
+	if _, ok := files["ok.txt"]; !ok {
+		t.Error("second page file must be indexed")
+	}
+	if _, ok := files["online.adoc"]; ok {
+		t.Error("non-file document must remain outside the folder mirror index")
+	}
+}
+
+func TestCrossPlatformCoverageWalkRemoteForPush_depthLimitAborts(t *testing.T) {
+	caller := &driveScriptCaller{reply: func(string, map[string]any, int) (string, error) {
+		return `{"result":{"items":[{"name":"loop","type":"folder","fileId":"LOOP"}],"nextToken":""}}`, nil
+	}}
+	testseam.Swap(t, &deps, &Deps{Caller: caller, Out: &Formatter{w: io.Discard}})
+	testseam.Swap(t, &os.Args, []string{"dws", "drive"})
+
+	if _, _, err := fetchRemoteTreeForPush(context.Background(), "", "ROOT"); err == nil ||
+		!strings.Contains(err.Error(), "循环引用") {
+		t.Fatalf("expected depth-limit abort, got %v", err)
+	}
+}
+
+// ──────────────────────────────────────────────────────────
+// walkLocalForPush — 非常规文件与错误分支
+// ──────────────────────────────────────────────────────────
+
+func TestCrossPlatformCoverageWalkLocalForPush_skipsIrregularAndMissingRoot(t *testing.T) {
+	if _, _, err := walkLocalForPush(filepath.Join(t.TempDir(), "absent")); err == nil {
+		t.Fatal("expected error for missing root")
+	}
+
+	dir := t.TempDir()
+	mustWrite(t, filepath.Join(dir, "real.txt"), "x")
+	if err := os.Symlink(filepath.Join(dir, "absent"), filepath.Join(dir, "dangling")); err != nil {
+		t.Skipf("symlink unsupported: %v", err)
+	}
+	_, files, err := walkLocalForPush(dir)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	for _, f := range files {
+		if f.RelPath == "dangling" {
+			t.Error("dangling symlink must not be pushed")
+		}
+	}
+}
+
+// ──────────────────────────────────────────────────────────
+// pushUploadFile — 凭证解析与提交失败分支
+// ──────────────────────────────────────────────────────────
+
+func TestCrossPlatformCoveragePushUploadFile_failureBranches(t *testing.T) {
+	dir := t.TempDir()
+	p := filepath.Join(dir, "a.txt")
+	mustWrite(t, p, "payload")
+
+	cases := []struct {
+		name  string
+		reply func(string, map[string]any, int) (string, error)
+		put   func(context.Context, string, map[string]string, string, int64) error
+	}{
+		{"get_upload_info tool error",
+			func(tool string, _ map[string]any, _ int) (string, error) {
+				if tool == "get_upload_info" {
+					return "", errTestUpload
+				}
+				return `{"result":{},"success":true}`, nil
+			}, nil},
+		{"unparsable upload credential",
+			func(tool string, _ map[string]any, _ int) (string, error) {
+				if tool == "get_upload_info" {
+					return `{"result":{}}`, nil // 无 resourceUrls
+				}
+				return `{"result":{},"success":true}`, nil
+			}, nil},
+		{"oss put fails",
+			func(string, map[string]any, int) (string, error) {
+				return `{"result":{"resourceUrls":[{"url":"https://oss.example.com/put","headers":{}}],"uploadId":"U1"}}`, nil
+			},
+			func(context.Context, string, map[string]string, string, int64) error { return errTestUpload }},
+		{"commit fails",
+			func(tool string, _ map[string]any, _ int) (string, error) {
+				if tool == "get_upload_info" {
+					return `{"result":{"resourceUrls":[{"url":"https://oss.example.com/put","headers":{}}],"uploadId":"U1"}}`, nil
+				}
+				return "", errTestUpload
+			}, nil},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			testseam.Swap(t, &deps, &Deps{Caller: &driveScriptCaller{reply: tc.reply}, Out: &Formatter{w: io.Discard}})
+			testseam.Swap(t, &os.Args, []string{"dws", "drive"})
+			put := tc.put
+			if put == nil {
+				put = func(context.Context, string, map[string]string, string, int64) error { return nil }
+			}
+			testseam.Swap(t, &httpPutFile, put)
+
+			if err := pushUploadFile(context.Background(), "SP", "PARENT", "", "a.txt", p, 7); err == nil {
+				t.Fatal("expected upload failure")
+			}
+		})
+	}
+}
+
+// pushCreateFolder：MCP 失败上抛，成功时从返回体提取 fileId。
+func TestCrossPlatformCoveragePushCreateFolder_errorAndSuccess(t *testing.T) {
+	testseam.Swap(t, &os.Args, []string{"dws", "drive"})
+
+	testseam.Swap(t, &deps, &Deps{Caller: &driveScriptCaller{reply: func(string, map[string]any, int) (string, error) {
+		return "", errTestUpload
+	}}, Out: &Formatter{w: io.Discard}})
+	if _, err := pushCreateFolder(context.Background(), "", "P", "n"); err == nil {
+		t.Fatal("expected create_folder error to propagate")
+	}
+
+	ok := &driveScriptCaller{reply: func(string, map[string]any, int) (string, error) {
+		return `{"result":{"fileId":"FID42"},"success":true}`, nil
+	}}
+	testseam.Swap(t, &deps, &Deps{Caller: ok, Out: &Formatter{w: io.Discard}})
+	got, err := pushCreateFolder(context.Background(), "SP", "P", "n")
+	if err != nil || got != "FID42" {
+		t.Fatalf("pushCreateFolder = (%q, %v), want (FID42, nil)", got, err)
+	}
+	if ok.calls[0].args["spaceId"] != "SP" || ok.calls[0].args["parentId"] != "P" {
+		t.Errorf("create_folder args = %v", ok.calls[0].args)
+	}
+}

internal/helpers/drive_push_sync_final_coverage_test.go

@@ -0,0 +1,719 @@
+package helpers
+
+import (
+	"context"
+	"crypto/md5"
+	"encoding/base64"
+	"errors"
+	"io"
+	"io/fs"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam"
+)
+
+var errDriveFinalCoverage = errors.New("drive final coverage failure")
+
+func openDriveFinalCoverageRoot(t *testing.T) (string, *pinnedPullRoot, localPushFile) {
+	t.Helper()
+	rootPath := t.TempDir()
+	path := filepath.Join(rootPath, "a.txt")
+	mustWrite(t, path, "payload")
+	info, err := os.Lstat(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	root, err := openExistingPinnedPullRoot(rootPath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(root.close)
+	return rootPath, root, localPushFile{
+		RelPath: "a.txt", AbsPath: path, Size: info.Size(),
+		ModTimeMillis: info.ModTime().UnixMilli(), scanInfo: info,
+	}
+}
+
+func TestCrossPlatformCoverageDrivePushFinalMD5AndPinnedMatchEdges(t *testing.T) {
+	t.Run("default md5 success and read failure", func(t *testing.T) {
+		path := filepath.Join(t.TempDir(), "payload")
+		mustWrite(t, path, "payload")
+		file, err := os.Open(path)
+		if err != nil {
+			t.Fatal(err)
+		}
+		got, err := pushMD5OpenedFile(file)
+		_ = file.Close()
+		wantSum := md5.Sum([]byte("payload"))
+		want := base64.StdEncoding.EncodeToString(wantSum[:])
+		if err != nil || got != want {
+			t.Fatalf("md5=(%q,%v), want %q", got, err, want)
+		}
+		if _, err := pushMD5OpenedFile(file); err == nil {
+			t.Fatal("closed file must fail MD5 reading")
+		}
+	})
+
+	t.Run("open failure", func(t *testing.T) {
+		_, root, local := openDriveFinalCoverageRoot(t)
+		local.RelPath = "missing.txt"
+		if _, err := judgePinnedPushFileMatch(root, local, &remoteFile{Hash: "x"}, false); err == nil {
+			t.Fatal("missing file must fail exact matching")
+		}
+	})
+
+	t.Run("stat and identity failures", func(t *testing.T) {
+		_, root, local := openDriveFinalCoverageRoot(t)
+		testseam.Swap(t, &pushStatOpenedFile, func(*os.File) (os.FileInfo, error) {
+			return nil, errDriveFinalCoverage
+		})
+		if _, err := judgePinnedPushFileMatch(root, local, &remoteFile{Hash: "x"}, false); err == nil {
+			t.Fatal("opened file stat failure must abort matching")
+		}
+	})
+
+	t.Run("directory and replaced scan identity", func(t *testing.T) {
+		rootPath, root, local := openDriveFinalCoverageRoot(t)
+		if _, err := judgePinnedPushFileMatch(root, localPushFile{RelPath: "."}, &remoteFile{Hash: "x"}, false); err == nil {
+			t.Fatal("directory must not be hashed as a regular file")
+		}
+		other := filepath.Join(rootPath, "other.txt")
+		mustWrite(t, other, "other")
+		otherInfo, _ := os.Lstat(other)
+		local.scanInfo = otherInfo
+		if _, err := judgePinnedPushFileMatch(root, local, &remoteFile{Hash: "x"}, false); err == nil {
+			t.Fatal("scan identity mismatch must abort matching")
+		}
+	})
+
+	t.Run("hash failure and root verification", func(t *testing.T) {
+		_, root, local := openDriveFinalCoverageRoot(t)
+		testseam.Swap(t, &pushMD5OpenedFile, func(*os.File) (string, error) {
+			return "", errDriveFinalCoverage
+		})
+		if _, err := judgePinnedPushFileMatch(root, local, &remoteFile{Hash: "x"}, false); err == nil {
+			t.Fatal("hash read failure must abort matching")
+		}
+	})
+
+	t.Run("root verification and both verdicts", func(t *testing.T) {
+		_, root, local := openDriveFinalCoverageRoot(t)
+		sum := md5.Sum([]byte("payload"))
+		hash := base64.StdEncoding.EncodeToString(sum[:])
+		testseam.Swap(t, &pushVerifyPinnedSourceRoot, func(*pinnedPullRoot) error {
+			return errDriveFinalCoverage
+		})
+		if _, err := judgePinnedPushFileMatch(root, local, &remoteFile{Hash: hash}, false); !errors.Is(err, errDriveFinalCoverage) {
+			t.Fatalf("root verification error=%v", err)
+		}
+	})
+
+	t.Run("unchanged and modified", func(t *testing.T) {
+		_, root, local := openDriveFinalCoverageRoot(t)
+		sum := md5.Sum([]byte("payload"))
+		hash := base64.StdEncoding.EncodeToString(sum[:])
+		if got, err := judgePinnedPushFileMatch(root, local, &remoteFile{Hash: hash}, false); err != nil || got != matchUnchanged {
+			t.Fatalf("equal hash=(%q,%v)", got, err)
+		}
+		if got, err := judgePinnedPushFileMatch(root, local, &remoteFile{Hash: "different"}, false); err != nil || got != matchModified {
+			t.Fatalf("different hash=(%q,%v)", got, err)
+		}
+	})
+}
+
+func TestCrossPlatformCoverageDrivePushFinalPinnedUploadGuards(t *testing.T) {
+	t.Run("initial root replacement", func(t *testing.T) {
+		rootPath, root, local := openDriveFinalCoverageRoot(t)
+		moved := filepath.Join(filepath.Dir(rootPath), "moved-root")
+		replacePinnedMirrorRoot(t, rootPath, moved)
+		if err := pushUploadFilePinned(context.Background(), "", "P", "", "a.txt", root, local); err == nil {
+			t.Fatal("replaced root must abort before opening upload")
+		}
+	})
+
+	t.Run("open and stat failures", func(t *testing.T) {
+		_, root, local := openDriveFinalCoverageRoot(t)
+		_ = root.root.Close()
+		if err := pushUploadFilePinned(context.Background(), "", "P", "", "a.txt", root, local); err == nil {
+			t.Fatal("closed pinned root must fail file open")
+		}
+	})
+
+	t.Run("opened file stat failure", func(t *testing.T) {
+		_, root, local := openDriveFinalCoverageRoot(t)
+		testseam.Swap(t, &pushStatOpenedFile, func(*os.File) (os.FileInfo, error) {
+			return nil, errDriveFinalCoverage
+		})
+		if err := pushUploadFilePinned(context.Background(), "", "P", "", "a.txt", root, local); err == nil {
+			t.Fatal("stat failure must abort upload")
+		}
+	})
+
+	t.Run("non regular replaced and changed", func(t *testing.T) {
+		rootPath, root, local := openDriveFinalCoverageRoot(t)
+		if err := pushUploadFilePinned(context.Background(), "", "P", "", "root", root, localPushFile{RelPath: "."}); err == nil {
+			t.Fatal("directory upload must fail")
+		}
+		other := filepath.Join(rootPath, "other")
+		mustWrite(t, other, "other")
+		otherInfo, _ := os.Lstat(other)
+		replaced := local
+		replaced.scanInfo = otherInfo
+		if err := pushUploadFilePinned(context.Background(), "", "P", "", "a.txt", root, replaced); err == nil {
+			t.Fatal("replaced scan identity must fail")
+		}
+		changed := local
+		changed.Size++
+		if err := pushUploadFilePinned(context.Background(), "", "P", "", "a.txt", root, changed); err == nil {
+			t.Fatal("changed size must fail")
+		}
+	})
+
+	t.Run("second root verification", func(t *testing.T) {
+		_, root, local := openDriveFinalCoverageRoot(t)
+		testseam.Swap(t, &pushVerifyPinnedSourceRoot, func(*pinnedPullRoot) error {
+			return errDriveFinalCoverage
+		})
+		if err := pushUploadFilePinned(context.Background(), "", "P", "", "a.txt", root, local); !errors.Is(err, errDriveFinalCoverage) {
+			t.Fatalf("second verification error=%v", err)
+		}
+	})
+
+	// PUT 期间源文件被原地改写（编辑器覆盖、截断重写、mmap）时，PUT 已把混合内容
+	// 送到 OSS；如果 commit 只看根身份而不复核文件本身，overwrite/local-wins 会把
+	// 半新半旧的字节流覆盖到远端。commit 前必须再取一次源身份，size/mtime/inode
+	// 任一变化都要拒绝提交。
+	for _, mutation := range []struct {
+		name   string
+		mutate func(t *testing.T, dir string)
+	}{
+		{"size grows during PUT", func(t *testing.T, dir string) {
+			path := filepath.Join(dir, "a.txt")
+			if err := os.WriteFile(path, []byte("payload-mutated-mid-transfer"), 0o600); err != nil {
+				t.Fatal(err)
+			}
+		}},
+		{"mtime advances during PUT", func(t *testing.T, dir string) {
+			path := filepath.Join(dir, "a.txt")
+			future := time.Now().Add(2 * time.Second)
+			if err := os.Chtimes(path, future, future); err != nil {
+				t.Fatal(err)
+			}
+		}},
+	} {
+		t.Run("mid transfer source modification: "+mutation.name, func(t *testing.T) {
+			rootPath, root, local := openDriveFinalCoverageRoot(t)
+			caller := pushOKCaller(nil)
+			testseam.Swap(t, &deps, &Deps{Caller: caller, Out: &Formatter{w: io.Discard}})
+			testseam.Swap(t, &os.Args, []string{"dws", "drive"})
+
+			putCalls := 0
+			testseam.Swap(t, &pushPutOpenedFile, func(context.Context, string, map[string]string, *os.File, int64) error {
+				putCalls++
+				mutation.mutate(t, rootPath)
+				return nil
+			})
+
+			err := pushUploadFilePinned(context.Background(), "", "P", "", "a.txt", root, local)
+			if err == nil || !strings.Contains(err.Error(), "在传输期间被修改") {
+				t.Fatalf("PUT-time mutation must abort commit, got err=%v", err)
+			}
+			if putCalls != 1 {
+				t.Fatalf("PUT must run exactly once, got %d", putCalls)
+			}
+			if commits := caller.callsFor("commit_upload"); len(commits) != 0 {
+				t.Fatalf("commit_upload must not run after mid-transfer mutation, got %v", commits)
+			}
+		})
+		// PUT 之后再取源身份可能因文件被移动/删除失败：那也必须拒绝 commit，防止
+		// 一个不能被验证的传输被提交到远端。
+		t.Run("mid transfer stat failure aborts commit", func(t *testing.T) {
+			_, root, local := openDriveFinalCoverageRoot(t)
+			caller := pushOKCaller(nil)
+			testseam.Swap(t, &deps, &Deps{Caller: caller, Out: &Formatter{w: io.Discard}})
+			testseam.Swap(t, &os.Args, []string{"dws", "drive"})
+
+			calls := 0
+			testseam.Swap(t, &pushStatOpenedFile, func(file *os.File) (os.FileInfo, error) {
+				calls++
+				if calls == 1 {
+					return file.Stat()
+				}
+				return nil, errDriveFinalCoverage
+			})
+			testseam.Swap(t, &pushPutOpenedFile, func(context.Context, string, map[string]string, *os.File, int64) error {
+				return nil
+			})
+
+			err := pushUploadFilePinned(context.Background(), "", "P", "", "a.txt", root, local)
+			if err == nil || !strings.Contains(err.Error(), "上传后读取本地上传文件身份失败") {
+				t.Fatalf("post-PUT stat failure must abort commit, got %v", err)
+			}
+			if commits := caller.callsFor("commit_upload"); len(commits) != 0 {
+				t.Fatalf("commit_upload must not run after post-PUT stat failure, got %v", commits)
+			}
+		})
+	}
+	t.Run("command scan errors", func(t *testing.T) {
+		for _, command := range []string{"push", "sync"} {
+			t.Run(command, func(t *testing.T) {
+				testseam.Swap(t, &runDriveMirrorWalkLocalForPushPinned, func(*pinnedPullRoot) ([]string, []localPushFile, error) {
+					return nil, nil, errDriveFinalCoverage
+				})
+				err := runDriveCmd(t, pushOKCaller(nil), command, "--local-folder", t.TempDir(), "--remote-folder", "ROOT")
+				if !errors.Is(err, errDriveFinalCoverage) {
+					t.Fatalf("scan error=%v", err)
+				}
+			})
+		}
+	})
+
+	t.Run("walk initial and callback errors", func(t *testing.T) {
+		rootPath, root, _ := openDriveFinalCoverageRoot(t)
+		moved := filepath.Join(filepath.Dir(rootPath), "moved-walk-root")
+		replacePinnedMirrorRoot(t, rootPath, moved)
+		if _, _, err := walkLocalForPushPinned(root); err == nil {
+			t.Fatal("initial root replacement must fail walk")
+		}
+	})
+
+	t.Run("walk entry info error", func(t *testing.T) {
+		_, root, _ := openDriveFinalCoverageRoot(t)
+		testseam.Swap(t, &walkPinnedLocalFS, func(_ fs.FS, _ string, fn fs.WalkDirFunc) error {
+			return fn("bad", errDirEntry{}, nil)
+		})
+		if _, _, err := walkLocalForPushPinned(root); !errors.Is(err, errTestInfo) {
+			t.Fatalf("walk info error=%v", err)
+		}
+	})
+
+	// fs.WalkDir 允许把中途的 lstat 失败通过第三个参数传给回调而不是 DirEntry.Info；
+	// 该短路分支必须直接原样上抛，不能吞掉底层错误。macOS 上并非每次遍历都会经过它，
+	// 因此需要一个显式测试固定这条路径。
+	t.Run("walk callback receives error", func(t *testing.T) {
+		_, root, _ := openDriveFinalCoverageRoot(t)
+		testseam.Swap(t, &walkPinnedLocalFS, func(_ fs.FS, _ string, fn fs.WalkDirFunc) error {
+			return fn("bad", nil, errTestInfo)
+		})
+		if _, _, err := walkLocalForPushPinned(root); !errors.Is(err, errTestInfo) {
+			t.Fatalf("walk callback error = %v", err)
+		}
+	})
+
+	t.Run("walk final root verification", func(t *testing.T) {
+		rootPath, root, _ := openDriveFinalCoverageRoot(t)
+		moved := filepath.Join(filepath.Dir(rootPath), "moved-after-walk")
+		testseam.Swap(t, &walkPinnedLocalFS, func(_ fs.FS, _ string, _ fs.WalkDirFunc) error {
+			replacePinnedMirrorRoot(t, rootPath, moved)
+			return nil
+		})
+		if _, _, err := walkLocalForPushPinned(root); err == nil {
+			t.Fatal("post-walk root replacement must fail")
+		}
+	})
+
+	t.Run("regular entry", func(t *testing.T) {
+		var dirs []string
+		var files []localPushFile
+		if err := walkLocalForPushEntry("/root", "/root/a", regularDirEntry{}, nil, &dirs, &files); err != nil || len(files) != 1 {
+			t.Fatalf("files=%v err=%v", files, err)
+		}
+	})
+
+	t.Run("root replacement between folder writes", func(t *testing.T) {
+		for _, command := range []string{"push", "sync"} {
+			t.Run(command, func(t *testing.T) {
+				parent := t.TempDir()
+				rootPath := filepath.Join(parent, "root")
+				if err := os.MkdirAll(filepath.Join(rootPath, "a"), 0o755); err != nil {
+					t.Fatal(err)
+				}
+				if err := os.MkdirAll(filepath.Join(rootPath, "b"), 0o755); err != nil {
+					t.Fatal(err)
+				}
+				moved := filepath.Join(parent, "moved")
+				caller := &driveScriptCaller{reply: func(tool string, _ map[string]any, nth int) (string, error) {
+					switch tool {
+					case "list_files":
+						return `{"result":{"items":[]}}`, nil
+					case "create_folder":
+						if nth == 0 {
+							replacePinnedMirrorRoot(t, rootPath, moved)
+						}
+						return `{"result":{"fileId":"DIR"}}`, nil
+					default:
+						return `{"result":{"fileId":"FILE"}}`, nil
+					}
+				}}
+				args := []string{command, "--local-folder", rootPath, "--remote-folder", "ROOT"}
+				if command == "sync" {
+					args = append(args, "--quick")
+				}
+				if err := runDriveCmd(t, caller, args...); err == nil || !strings.Contains(err.Error(), "本地根目录") {
+					t.Fatalf("root replacement error=%v", err)
+				}
+			})
+		}
+	})
+}
+
+func TestCrossPlatformCoverageDrivePushFinalDefaultOpenedPUTAndCommit(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, request *http.Request) {
+		if request.Header.Get("X-Test") != "yes" {
+			t.Errorf("header=%q", request.Header.Get("X-Test"))
+		}
+		if request.URL.Path == "/status" {
+			http.Error(w, "denied", http.StatusTeapot)
+			return
+		}
+		_, _ = io.Copy(io.Discard, request.Body)
+	}))
+	defer server.Close()
+	path := filepath.Join(t.TempDir(), "payload")
+	mustWrite(t, path, "payload")
+	put := func(ctx context.Context, url string, headers map[string]string) error {
+		file, err := os.Open(path)
+		if err != nil {
+			return err
+		}
+		defer file.Close()
+		return defaultPushPutOpenedFile(ctx, url, headers, file, 7)
+	}
+	if err := put(context.Background(), ":", nil); err == nil {
+		t.Fatal("invalid PUT URL must fail")
+	}
+	cancelled, cancel := context.WithCancel(context.Background())
+	cancel()
+	if err := put(cancelled, server.URL, nil); !errors.Is(err, context.Canceled) {
+		t.Fatalf("cancelled PUT error=%v", err)
+	}
+	if err := put(context.Background(), server.URL+"/status", map[string]string{"X-Test": "yes"}); err == nil {
+		t.Fatal("non-200 PUT must fail")
+	}
+	if err := put(context.Background(), server.URL+"/ok", map[string]string{"X-Test": "yes"}); err != nil {
+		t.Fatal(err)
+	}
+	closed, err := os.Open(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	_ = closed.Close()
+	if err := defaultPushPutOpenedFile(context.Background(), server.URL, nil, closed, 7); err == nil {
+		t.Fatal("closed upload file must fail seek")
+	}
+
+	caller := &driveScriptCaller{reply: func(tool string, _ map[string]any, _ int) (string, error) {
+		if tool == "get_upload_info" {
+			return `{"result":{"resourceUrls":[{"url":"https://upload.invalid","headers":{}}],"uploadId":"U"}}`, nil
+		}
+		return "{", nil
+	}}
+	testseam.Swap(t, &deps, &Deps{Caller: caller, Out: &Formatter{w: io.Discard}})
+	testseam.Swap(t, &os.Args, []string{"dws", "drive"})
+	if err := pushUploadWithTransport(context.Background(), "", "P", "", "a.txt", 7, func(string, map[string]string) error { return nil }); err == nil || !strings.Contains(err.Error(), "parse commit_upload") {
+		t.Fatalf("malformed commit error=%v", err)
+	}
+}
+
+func TestCrossPlatformCoverageDriveSyncFinalPreflightAndKeepBothErrors(t *testing.T) {
+	t.Run("local target preflight lstat error and directory", func(t *testing.T) {
+		_, root, _ := openDriveFinalCoverageRoot(t)
+		failures := map[string]string{}
+		testseam.Swap(t, &pullRootLstat, func(*os.Root, string) (os.FileInfo, error) {
+			return nil, errDriveFinalCoverage
+		})
+		addPinnedLocalTargetPreflightFailures(root, map[string]*remoteFile{"remote.txt": {}}, failures)
+		if !strings.Contains(failures["remote.txt"], "检查本地目标失败") {
+			t.Fatalf("failures=%v", failures)
+		}
+	})
+
+	t.Run("local target preflight walks existing directory", func(t *testing.T) {
+		rootPath, root, _ := openDriveFinalCoverageRoot(t)
+		if err := os.Mkdir(filepath.Join(rootPath, "sub"), 0o755); err != nil {
+			t.Fatal(err)
+		}
+		failures := map[string]string{}
+		addPinnedLocalTargetPreflightFailures(root, map[string]*remoteFile{"sub/remote.txt": {}}, failures)
+		if len(failures) != 0 {
+			t.Fatalf("failures=%v", failures)
+		}
+		addPinnedLocalTargetPreflightFailures(root, map[string]*remoteFile{"sub": {}}, failures)
+		if failures["sub"] == "" {
+			t.Fatal("terminal directory must fail file target preflight")
+		}
+	})
+
+	t.Run("wrapper root failures", func(t *testing.T) {
+		path := filepath.Join(t.TempDir(), "file")
+		mustWrite(t, path, "x")
+		pullResult := &driveSyncResult{}
+		syncPullFile(pullResult, context.Background(), "", &remoteFile{}, path, "a", syncDirectionPull)
+		if pullResult.Summary.Failed != 1 {
+			t.Fatalf("pull result=%#v", pullResult)
+		}
+		keepResult := &driveSyncResult{}
+		syncKeepBoth(keepResult, context.Background(), "", &remoteFile{}, path, "a", map[string]bool{})
+		if keepResult.Summary.Failed != 1 {
+			t.Fatalf("keep result=%#v", keepResult)
+		}
+	})
+
+	t.Run("missing and non-regular local versions", func(t *testing.T) {
+		rootPath := t.TempDir()
+		missing := &driveSyncResult{}
+		syncKeepBoth(missing, context.Background(), "", &remoteFile{FileID: "F"}, rootPath, "missing.txt", map[string]bool{})
+		if missing.Summary.Failed != 1 || !strings.Contains(missing.Items[0].Error, "不存在") {
+			t.Fatalf("missing result=%#v", missing)
+		}
+		if err := os.Mkdir(filepath.Join(rootPath, "dir"), 0o755); err != nil {
+			t.Fatal(err)
+		}
+		nonRegular := &driveSyncResult{}
+		syncKeepBoth(nonRegular, context.Background(), "", &remoteFile{FileID: "F"}, rootPath, "dir", map[string]bool{})
+		if nonRegular.Summary.Failed != 1 || !strings.Contains(nonRegular.Items[0].Error, "不是常规文件") {
+			t.Fatalf("non-regular result=%#v", nonRegular)
+		}
+	})
+
+	t.Run("saved identity mismatch", func(t *testing.T) {
+		rootPath := t.TempDir()
+		mustWrite(t, filepath.Join(rootPath, "a.txt"), "local")
+		other := filepath.Join(t.TempDir(), "other")
+		mustWrite(t, other, "other")
+		otherInfo, _ := os.Lstat(other)
+		candidate := filepath.FromSlash(syncKeepBothCandidate("a.txt", "F", 0))
+		testseam.Swap(t, &pullRootLstat, func(root *os.Root, name string) (os.FileInfo, error) {
+			if name == candidate {
+				return otherInfo, nil
+			}
+			return root.Lstat(name)
+		})
+		res := &driveSyncResult{}
+		syncKeepBoth(res, context.Background(), "", &remoteFile{FileID: "F"}, rootPath, "a.txt", map[string]bool{})
+		if res.Summary.Failed != 1 || !strings.Contains(res.Items[0].Error, "身份不一致") {
+			t.Fatalf("result=%#v", res)
+		}
+	})
+
+	t.Run("nil transfer error fallback", func(t *testing.T) {
+		rootPath := t.TempDir()
+		mustWrite(t, filepath.Join(rootPath, "a.txt"), "local")
+		testseam.Swap(t, &syncPullOneFilePinned, func(context.Context, string, *remoteFile, *pinnedPullTarget, string) (string, error) {
+			return pullActionFailed, nil
+		})
+		res := &driveSyncResult{}
+		syncKeepBoth(res, context.Background(), "", &remoteFile{FileID: "F"}, rootPath, "a.txt", map[string]bool{})
+		if res.Summary.Failed != 1 || !strings.Contains(res.Items[0].Error, "未能拉取") {
+			t.Fatalf("result=%#v", res)
+		}
+	})
+
+	t.Run("unsafe candidate and parent verification", func(t *testing.T) {
+		rootPath := t.TempDir()
+		mustWrite(t, filepath.Join(rootPath, "a.txt"), "local")
+		target, err := openPinnedPullTarget(rootPath, "a.txt")
+		if err != nil {
+			t.Fatal(err)
+		}
+		if _, _, err := reserveSyncKeepBothTargetPinned(target, "\x00", "", map[string]bool{}); err == nil {
+			t.Fatal("unsafe candidate must fail")
+		}
+		target.close()
+
+		target, err = openPinnedPullTarget(rootPath, "a.txt")
+		if err != nil {
+			t.Fatal(err)
+		}
+		defer target.close()
+		moved := filepath.Join(filepath.Dir(rootPath), "moved-keep-root")
+		replacePinnedMirrorRoot(t, rootPath, moved)
+		if _, _, err := reserveSyncKeepBothTargetPinned(target, "a.txt", "", map[string]bool{}); err == nil {
+			t.Fatal("replaced parent must fail before link")
+		}
+	})
+}
+
+type driveFinalCallbackReader struct{ callback func() }
+
+func (reader driveFinalCallbackReader) Read(buffer []byte) (int, error) {
+	reader.callback()
+	return copy(buffer, "s\n"), nil
+}
+
+func TestCrossPlatformCoverageDriveSyncFinalPostDecisionRootVerification(t *testing.T) {
+	parent := t.TempDir()
+	rootPath := filepath.Join(parent, "root")
+	if err := os.Mkdir(rootPath, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	path := filepath.Join(rootPath, "a.txt")
+	mustWrite(t, path, "local")
+	mtime := readFileMTimeMillis(t, path)
+	moved := filepath.Join(parent, "moved")
+	testseam.Swap(t, &syncAskStdin, io.Reader(driveFinalCallbackReader{callback: func() {
+		replacePinnedMirrorRoot(t, rootPath, moved)
+	}}))
+	caller := syncCaller(map[string]string{
+		"ROOT": `{"result":{"items":[{"name":"a.txt","type":"file","fileId":"F","modifyTime":` + differentMillis(mtime) + `}]}}`,
+	})
+	err := runDriveCmd(t, caller, "sync", "--local-folder", rootPath, "--remote-folder", "ROOT", "--quick", "--on-conflict", "ask")
+	if err == nil || !strings.Contains(err.Error(), "本地根目录") {
+		t.Fatalf("post-decision root verification error=%v", err)
+	}
+}
+
+func TestCrossPlatformCoverageDrivePushSyncFinalCommandValidationAndPrintErrors(t *testing.T) {
+	for _, command := range []string{"push", "sync"} {
+		t.Run(command+" required", func(t *testing.T) {
+			cmd := findDriveSubcommand(t, command)
+			var err error
+			if command == "push" {
+				err = runDrivePush(cmd, nil)
+			} else {
+				err = runDriveSync(cmd, nil)
+			}
+			if err == nil || !strings.Contains(err.Error(), "required") {
+				t.Fatalf("required error=%v", err)
+			}
+		})
+
+		t.Run(command+" relative", func(t *testing.T) {
+			cmd := findDriveSubcommand(t, command)
+			mustSetFlags(t, cmd, map[string]string{"local-folder": "relative", "remote-folder": "ROOT"})
+			var err error
+			if command == "push" {
+				err = runDrivePush(cmd, nil)
+			} else {
+				err = runDriveSync(cmd, nil)
+			}
+			if err == nil || !strings.Contains(err.Error(), "绝对路径") {
+				t.Fatalf("relative error=%v", err)
+			}
+		})
+
+		t.Run(command+" preflight print", func(t *testing.T) {
+			rootPath := t.TempDir()
+			mustWrite(t, filepath.Join(rootPath, "A.txt"), "local")
+			caller := pushOKCaller(map[string]string{
+				"ROOT": `{"result":{"items":[{"name":"a.txt","type":"file","fileId":"F"}]}}`,
+			})
+			testseam.Swap(t, &deps, &Deps{Caller: caller, Out: &Formatter{w: failingWriter{}}})
+			testseam.Swap(t, &os.Args, []string{"dws", "drive", command})
+			cmd := findDriveSubcommand(t, command)
+			flags := map[string]string{"local-folder": rootPath, "remote-folder": "ROOT"}
+			if command == "sync" {
+				flags["quick"] = "true"
+			}
+			mustSetFlags(t, cmd, flags)
+			var err error
+			if command == "push" {
+				err = runDrivePush(cmd, nil)
+			} else {
+				err = runDriveSync(cmd, nil)
+			}
+			if err == nil || !strings.Contains(err.Error(), "write failed") {
+				t.Fatalf("PrintJSON error=%v", err)
+			}
+		})
+	}
+}
+
+func TestCrossPlatformCoverageDriveSyncFinalPullWrapperSuccess(t *testing.T) {
+	rootPath := t.TempDir()
+	installPinnedPullSuccess(t)
+	res := &driveSyncResult{}
+	syncPullFile(res, context.Background(), "", &remoteFile{FileID: "F"}, rootPath, "a.txt", syncDirectionPull)
+	if res.Summary.Pulled != 1 || res.Summary.Failed != 0 {
+		t.Fatalf("result=%#v", res)
+	}
+}
+
+func TestCrossPlatformCoverageDrivePushFinalPureRemainingEdges(t *testing.T) {
+	if got := mirrorLocalRelError("good/../bad"); got == "" {
+		t.Fatal("unsafe local mirror segment must fail")
+	}
+	failures := buildMirrorPreflight(nil, []localPushFile{{RelPath: "bad\x00name"}}, nil, nil)
+	if failures["bad\x00name"] == "" {
+		t.Fatalf("failures=%v", failures)
+	}
+	if got := parseNodeID("{"); got != "" {
+		t.Fatalf("malformed node ID=%q", got)
+	}
+}
+
+func TestCrossPlatformCoverageDrivePushFinalRemoteWalkerFailClosedEdges(t *testing.T) {
+	cases := []struct {
+		name  string
+		reply func(map[string]any) string
+		want  string
+	}{
+		{
+			name: "unsafe entry",
+			reply: func(map[string]any) string {
+				return `{"result":{"items":[{"name":"../escape","type":"file","fileId":"F"}]}}`
+			},
+			want: "无法安全映射",
+		},
+		{
+			name: "duplicate folder",
+			reply: func(args map[string]any) string {
+				if args["parentId"] == "D" {
+					return `{"result":{"items":[]}}`
+				}
+				return `{"result":{"items":[{"name":"dir","type":"folder","fileId":"D"},{"name":"dir","type":"folder","fileId":"D"}]}}`
+			},
+			want: "重复",
+		},
+		{
+			name: "folder without ID",
+			reply: func(map[string]any) string {
+				return `{"result":{"items":[{"name":"dir","type":"folder"}]}}`
+			},
+			want: "缺少目录 ID",
+		},
+		{
+			name: "duplicate file",
+			reply: func(map[string]any) string {
+				return `{"result":{"items":[{"name":"a","type":"file","fileId":"A"},{"name":"a","type":"file","fileId":"A"}]}}`
+			},
+			want: "重复",
+		},
+		{
+			name: "file without ID",
+			reply: func(map[string]any) string {
+				return `{"result":{"items":[{"name":"a","type":"file"}]}}`
+			},
+			want: "缺少文件 ID",
+		},
+		{
+			name: "pagination cycle",
+			reply: func(map[string]any) string {
+				return `{"result":{"items":[],"nextToken":"P"}}`
+			},
+			want: "分页 token 重复",
+		},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			caller := &driveScriptCaller{reply: func(tool string, args map[string]any, _ int) (string, error) {
+				if tool != "list_files" {
+					t.Fatalf("unexpected tool %s", tool)
+				}
+				return tc.reply(args), nil
+			}}
+			testseam.Swap(t, &deps, &Deps{Caller: caller, Out: &Formatter{w: io.Discard}})
+			testseam.Swap(t, &os.Args, []string{"dws", "drive"})
+			_, _, err := fetchRemoteTreeForPush(context.Background(), "", "ROOT")
+			if err == nil || !strings.Contains(err.Error(), tc.want) {
+				t.Fatalf("error=%v, want %q", err, tc.want)
+			}
+		})
+	}
+}

internal/helpers/drive_push_test.go

@@ -0,0 +1,360 @@
+package helpers
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+	"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"
+)
+
+// ──────────────────────────────────────────────────────────
+// splitRel — rel_path 拆父路径 / 末段名
+// ──────────────────────────────────────────────────────────
+
+func TestCrossPlatformCoverageSplitRel(t *testing.T) {
+	cases := []struct {
+		in           string
+		parent, base string
+	}{
+		{"a/b/c", "a/b", "c"},
+		{"a/b", "a", "b"},
+		{"c", "", "c"},
+		{"", "", ""},
+	}
+	for _, c := range cases {
+		p, b := splitRel(c.in)
+		if p != c.parent || b != c.base {
+			t.Errorf("splitRel(%q) = (%q,%q), want (%q,%q)", c.in, p, b, c.parent, c.base)
+		}
+	}
+}
+
+// ──────────────────────────────────────────────────────────
+// parseNodeID — create_folder / commit 返回里抽 fileId
+// ──────────────────────────────────────────────────────────
+
+func TestCrossPlatformCoverageParseNodeID(t *testing.T) {
+	cases := []struct {
+		name string
+		text string
+		want string
+	}{
+		{"result.fileId", `{"result":{"fileId":"F1","name":"x"},"success":true}`, "F1"},
+		{"top-level fileId", `{"fileId":"F2"}`, "F2"},
+		{"dentryUuid fallback", `{"result":{"dentryUuid":"D1"}}`, "D1"},
+		{"dentryId fallback", `{"result":{"dentryId":"D2"}}`, "D2"},
+		{"missing", `{"result":{"name":"x"}}`, ""},
+		{"invalid json", `not json`, ""},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			if got := parseNodeID(c.text); got != c.want {
+				t.Errorf("parseNodeID = %q, want %q", got, c.want)
+			}
+		})
+	}
+}
+
+// ──────────────────────────────────────────────────────────
+// walkLocalForPush — 本地遍历（含空目录，父目录先于子目录）
+// ──────────────────────────────────────────────────────────
+
+func TestCrossPlatformCoverageWalkLocalForPush(t *testing.T) {
+	root := t.TempDir()
+	mustWrite(t, filepath.Join(root, "a.txt"), "hello")        // 5 bytes
+	mustWrite(t, filepath.Join(root, "sub1", "b.txt"), "worl") // 4 bytes, 建出 sub1
+	if err := os.MkdirAll(filepath.Join(root, "sub1", "sub2"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.MkdirAll(filepath.Join(root, "empty"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+
+	dirs, files, err := walkLocalForPush(root)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	// 目录：含空目录，不含根本身，且父目录先于子目录（字典序即可保证）。
+	wantDirs := []string{"empty", "sub1", "sub1/sub2"}
+	if !sort.StringsAreSorted(dirs) {
+		t.Errorf("dirs should be sorted (parent before child): %v", dirs)
+	}
+	if !equalStrings(dirs, wantDirs) {
+		t.Errorf("dirs = %v, want %v", dirs, wantDirs)
+	}
+
+	// 文件：rel_path 用 /，记录 size 与 mtime。
+	byRel := map[string]localPushFile{}
+	for _, f := range files {
+		byRel[f.RelPath] = f
+	}
+	if len(byRel) != 2 {
+		t.Fatalf("expected 2 files, got %d: %v", len(byRel), files)
+	}
+	a, ok := byRel["a.txt"]
+	if !ok || a.Size != 5 {
+		t.Errorf("a.txt size = %d, want 5 (present=%v)", a.Size, ok)
+	}
+	if a.AbsPath == "" || a.ModTimeMillis == 0 {
+		t.Error("file should record AbsPath and mtime")
+	}
+	b, ok := byRel["sub1/b.txt"]
+	if !ok || b.Size != 4 {
+		t.Errorf("sub1/b.txt size = %d, want 4 (present=%v)", b.Size, ok)
+	}
+}
+
+// ──────────────────────────────────────────────────────────
+// drivePushFailure — push 部分失败错误：exit=1
+// ──────────────────────────────────────────────────────────
+
+func TestCrossPlatformCoverageDrivePushFailure(t *testing.T) {
+	e := &drivePushFailure{failed: 3}
+	if e.ExitCode() != 1 {
+		t.Errorf("ExitCode() = %d, want 1", e.ExitCode())
+	}
+	if e.Error() != e.RawStderr() {
+		t.Error("Error() 与 RawStderr() 应一致")
+	}
+	if !strings.Contains(e.Error(), "3") {
+		t.Errorf("Error() 应包含失败数, got %q", e.Error())
+	}
+}
+
+// ──────────────────────────────────────────────────────────
+// push 覆盖流程 — get_upload_info / commit_upload 两阶段的 MCP 参数
+// ──────────────────────────────────────────────────────────
+
+// driveMCPCall 记录一次 MCP 工具调用。
+type driveMCPCall struct {
+	toolName string
+	args     map[string]any
+}
+
+// driveSyncMockCaller 按工具名分发返回，并记录全部调用，供断言 MCP 参数。
+type driveSyncMockCaller struct {
+	calls      []driveMCPCall
+	listJSON   string  // list_files 返回体
+	commitJSON *string // 非 nil 时覆盖 commit_upload 返回体（包括空响应）
+	dryRun     bool    // --dry-run：只算差异，不执行任何写操作
+}
+
+func (m *driveSyncMockCaller) CallTool(_ context.Context, _ string, toolName string, args map[string]any) (*edition.ToolResult, error) {
+	m.calls = append(m.calls, driveMCPCall{toolName: toolName, args: args})
+	var text string
+	switch toolName {
+	case "list_files":
+		text = m.listJSON
+	case "get_upload_info":
+		// 返回可被 parseDriveUploadInfo 解析的凭证。
+		text = `{"result":{"resourceUrls":[{"url":"https://oss.example.com/put","headers":{}}],"uploadId":"U1"}}`
+	case "download_file":
+		// 返回可被 parseDriveDownloadInfo 解析的预签名下载链接。
+		text = `{"result":{"downloadUrl":"https://oss.example.com/get","headers":{}}}`
+	case "commit_upload":
+		if m.commitJSON != nil {
+			text = *m.commitJSON
+		} else {
+			text = `{"result":{"fileId":"NEW_FID"},"success":true}`
+		}
+	default:
+		text = `{"result":{"fileId":"NEW_FID"},"success":true}`
+	}
+	return &edition.ToolResult{Content: []edition.ContentBlock{{Type: "text", Text: text}}}, nil
+}
+
+func (m *driveSyncMockCaller) CallReadTool(ctx context.Context, productID, toolName string, args map[string]any) (*edition.ToolResult, error) {
+	return m.CallTool(ctx, productID, toolName, args)
+}
+
+func (m *driveSyncMockCaller) Format() string { return "raw" }
+func (m *driveSyncMockCaller) DryRun() bool   { return m.dryRun }
+func (m *driveSyncMockCaller) Fields() string { return "" }
+func (m *driveSyncMockCaller) JQ() string     { return "" }
+
+func (m *driveSyncMockCaller) callsFor(tool string) []driveMCPCall {
+	var out []driveMCPCall
+	for _, c := range m.calls {
+		if c.toolName == tool {
+			out = append(out, c)
+		}
+	}
+	return out
+}
+
+// runDrivePushTest 用 mock caller 执行 `drive push`，返回捕获的调用。
+// 注入已打开文件句柄的 PUT seam 为 no-op，避免真实 OSS 上传。
+func runDrivePushTest(t *testing.T, caller *driveSyncMockCaller, localDir string, args ...string) error {
+	t.Helper()
+
+	testseam.Swap(t, &pushPutOpenedFile, func(context.Context, string, map[string]string, *os.File, int64) error { return nil })
+	testseam.Swap(t, &deps, &Deps{Caller: caller, Out: &Formatter{w: io.Discard}})
+
+	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 := append([]string{"push", "--local-folder", localDir, "--remote-folder", "ROOT", "--yes"}, args...)
+	testseam.Swap(t, &os.Args, append([]string{"dws", "drive"}, full...))
+	root.SetArgs(append([]string{"drive"}, full...))
+
+	return root.Execute()
+}
+
+func runDriveMirrorUploadCommandCapture(t *testing.T, command string, caller *driveSyncMockCaller, localDir string) (error, string, int) {
+	t.Helper()
+	putCalls := 0
+	testseam.Swap(t, &pushPutOpenedFile, func(context.Context, string, map[string]string, *os.File, int64) error {
+		putCalls++
+		return nil
+	})
+	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 := []string{command, "--local-folder", localDir, "--remote-folder", "ROOT", "--yes"}
+	testseam.Swap(t, &os.Args, append([]string{"dws", "drive"}, full...))
+	root.SetArgs(append([]string{"drive"}, full...))
+	return root.Execute(), out.String(), putCalls
+}
+
+func assertMirrorUploadFailedJSON(t *testing.T, output string) {
+	t.Helper()
+	var payload struct {
+		Summary struct {
+			Failed int `json:"failed"`
+		} `json:"summary"`
+		Items []struct {
+			Action string `json:"action"`
+			Error  string `json:"error"`
+		} `json:"items"`
+	}
+	if err := json.Unmarshal([]byte(output), &payload); err != nil {
+		t.Fatalf("output is not structured JSON: %q: %v", output, err)
+	}
+	if payload.Summary.Failed != 1 || len(payload.Items) != 1 || payload.Items[0].Action != pushActionFailed || payload.Items[0].Error == "" {
+		t.Fatalf("structured failure=%#v", payload)
+	}
+}
+
+// 覆盖分支：get_upload_info 与 commit_upload 两阶段都必须传 overwriteFileId、都不传 parentId。
+func TestCrossPlatformCoverageDrivePush_overwriteUsesOverwriteFileId(t *testing.T) {
+	dir := t.TempDir()
+	mustWrite(t, filepath.Join(dir, "a.txt"), "new-content")
+
+	caller := &driveSyncMockCaller{
+		// 远端根目录下已存在同名 a.txt，fileId=REMOTE_FID。
+		listJSON: `{"result":{"items":[{"name":"a.txt","type":"file","fileId":"REMOTE_FID","md5":"x","modifyTime":1000}],"nextToken":""}}`,
+	}
+	if err := runDrivePushTest(t, caller, dir, "--if-exists", "overwrite"); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	up := caller.callsFor("get_upload_info")
+	if len(up) != 1 {
+		t.Fatalf("expected 1 get_upload_info call, got %d", len(up))
+	}
+	if got := up[0].args["overwriteFileId"]; got != "REMOTE_FID" {
+		t.Errorf("get_upload_info overwriteFileId = %v, want REMOTE_FID", got)
+	}
+	if _, ok := up[0].args["parentId"]; ok {
+		t.Error("覆盖时 get_upload_info 不应传 parentId")
+	}
+
+	commit := caller.callsFor("commit_upload")
+	if len(commit) != 1 {
+		t.Fatalf("expected 1 commit_upload call, got %d", len(commit))
+	}
+	if got := commit[0].args["overwriteFileId"]; got != "REMOTE_FID" {
+		t.Errorf("commit_upload overwriteFileId = %v, want REMOTE_FID", got)
+	}
+	if _, ok := commit[0].args["parentId"]; ok {
+		t.Error("覆盖时 commit_upload 不应传 parentId")
+	}
+}
+
+// 新建分支：远端不存在同名文件时走普通上传——两阶段都传 parentId、都不传 overwriteFileId。
+func TestCrossPlatformCoverageDrivePush_newUploadUsesParentId(t *testing.T) {
+	dir := t.TempDir()
+	mustWrite(t, filepath.Join(dir, "b.txt"), "brand-new")
+
+	caller := &driveSyncMockCaller{
+		listJSON: `{"result":{"items":[],"nextToken":""}}`, // 远端空
+	}
+	if err := runDrivePushTest(t, caller, dir, "--if-exists", "overwrite"); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	up := caller.callsFor("get_upload_info")
+	if len(up) != 1 {
+		t.Fatalf("expected 1 get_upload_info call, got %d", len(up))
+	}
+	if _, ok := up[0].args["overwriteFileId"]; ok {
+		t.Error("新建上传不应传 overwriteFileId")
+	}
+	if got := up[0].args["parentId"]; got != "ROOT" {
+		t.Errorf("get_upload_info parentId = %v, want ROOT", got)
+	}
+	commit := caller.callsFor("commit_upload")
+	if len(commit) != 1 || commit[0].args["parentId"] != "ROOT" {
+		t.Errorf("commit_upload should carry parentId=ROOT, got %v", commit)
+	}
+}
+
+func TestCrossPlatformCoverageDrivePushRejectsUnknownCommitEffect(t *testing.T) {
+	for _, response := range []string{"", `{}`} {
+		t.Run(fmt.Sprintf("response-%q", response), func(t *testing.T) {
+			dir := t.TempDir()
+			mustWrite(t, filepath.Join(dir, "a.txt"), "payload")
+			caller := &driveSyncMockCaller{
+				listJSON:   `{"result":{"items":[]}}`,
+				commitJSON: &response,
+			}
+			err, output, putCalls := runDriveMirrorUploadCommandCapture(t, "push", caller, dir)
+			if err == nil {
+				t.Fatal("empty commit result must make push exit non-zero")
+			}
+			if failure, ok := err.(*drivePushFailure); !ok || failure.ExitCode() != 1 {
+				t.Fatalf("error=%T %v", err, err)
+			}
+			assertMirrorUploadFailedJSON(t, output)
+			if putCalls != 1 {
+				t.Fatalf("OSS PUT calls=%d, want exactly 1", putCalls)
+			}
+			if got := len(caller.callsFor("get_upload_info")); got != 1 {
+				t.Fatalf("get_upload_info calls=%d, want 1", got)
+			}
+			if got := len(caller.callsFor("commit_upload")); got != 1 {
+				t.Fatalf("commit_upload calls=%d, want 1", got)
+			}
+		})
+	}
+}
+
+func equalStrings(a, b []string) bool {
+	if len(a) != len(b) {
+		return false
+	}
+	for i := range a {
+		if a[i] != b[i] {
+			return false
+		}
+	}
+	return true
+}

internal/helpers/drive_push_toctou_test.go

@@ -0,0 +1,164 @@
+package helpers
+
+import (
+	"context"
+	"io"
+	"os"
+	"path/filepath"
+	"runtime"
+	"strings"
+	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam"
+)
+
+// replacePinnedMirrorRoot 返回 true 表示原目录被真实移走、原名处已换成另一个目录；
+// 返回 false 表示走了 Windows 身份注入降级，原目录仍留在原处。依赖「替代目录内容」
+// 的断言必须按返回值分流。
+func replacePinnedMirrorRoot(t *testing.T, root, moved string) bool {
+	t.Helper()
+	if forcePinnedFallbackForTest {
+		swapPinnedRootIdentity(t, root)
+		return false
+	}
+	if err := os.Rename(root, moved); err != nil {
+		// Windows 在目录内有已打开的句柄（如上传读取中的源文件）时会锁住该目录，
+		// 移走固定根于该平台物理不可达。退化为等价的根身份注入，命中同一条
+		// fail-closed 分支。
+		if runtime.GOOS != "windows" {
+			t.Fatalf("move pinned root: %v", err)
+		}
+		swapPinnedRootIdentity(t, root)
+		return false
+	}
+	if err := os.Mkdir(root, 0o755); err != nil {
+		t.Fatalf("create replacement root: %v", err)
+	}
+	mustWrite(t, filepath.Join(root, "a.txt"), "outside-replacement")
+	return true
+}
+
+// 本地扫描完成后、任何 create_folder/get_upload_info/commit_upload 前若命令行根已
+// 被另一目录替换，push 与 sync 都必须整批失败，不能把替代目录当成扫描快照继续写远端。
+func TestCrossPlatformCoverageDrivePushSyncRejectRootReplacementBeforeRemoteWrite(t *testing.T) {
+	for _, command := range []string{"push", "sync"} {
+		t.Run(command, func(t *testing.T) {
+			parent := t.TempDir()
+			root := filepath.Join(parent, "root")
+			moved := filepath.Join(parent, "moved-original")
+			if err := os.Mkdir(root, 0o755); err != nil {
+				t.Fatal(err)
+			}
+			mustWrite(t, filepath.Join(root, "a.txt"), "pinned-original")
+
+			replaced := false
+			realMove := false
+			caller := &driveScriptCaller{reply: func(tool string, _ map[string]any, _ int) (string, error) {
+				if tool == "list_files" {
+					if !replaced {
+						realMove = replacePinnedMirrorRoot(t, root, moved)
+						replaced = true
+					}
+					return `{"result":{"items":[],"nextToken":""}}`, nil
+				}
+				return `{"result":{"fileId":"UNEXPECTED"},"success":true}`, nil
+			}}
+			putCalls := 0
+			testseam.Swap(t, &pushPutOpenedFile, func(context.Context, string, map[string]string, *os.File, int64) error {
+				putCalls++
+				return nil
+			})
+
+			args := []string{command, "--local-folder", root, "--remote-folder", "ROOT"}
+			if command == "sync" {
+				args = append(args, "--quick")
+			}
+			err := runDriveCmd(t, caller, args...)
+			if err == nil || !strings.Contains(err.Error(), "本地根目录在同步期间被替换") {
+				t.Fatalf("expected root replacement rejection, got %v", err)
+			}
+			for _, tool := range []string{"create_folder", "get_upload_info", "commit_upload"} {
+				if got := caller.callsFor(tool); len(got) != 0 {
+					t.Errorf("%s must not run after root replacement: %v", tool, got)
+				}
+			}
+			if putCalls != 0 {
+				t.Fatalf("OSS PUT must not run after root replacement, got %d", putCalls)
+			}
+			want := "outside-replacement"
+			if !realMove {
+				// 身份注入降级：原目录仍在原处，内容同样不得被镜像流程改写。
+				want = "pinned-original"
+			}
+			if b, err := os.ReadFile(filepath.Join(root, "a.txt")); err != nil || string(b) != want {
+				t.Fatalf("replacement tree changed: %q err=%v", string(b), err)
+			}
+		})
+	}
+}
+
+// 即使根在 get_upload_info 之后、OSS PUT 读取前被替换，PUT 也只能读取扫描时固定根
+// 打开的文件句柄。传输后身份复核会拒绝 commit，替代目录内容绝不能泄漏到上传流。
+func TestCrossPlatformCoverageDrivePushSyncUploadReadsPinnedFileHandle(t *testing.T) {
+	for _, command := range []string{"push", "sync"} {
+		t.Run(command, func(t *testing.T) {
+			parent := t.TempDir()
+			root := filepath.Join(parent, "root")
+			moved := filepath.Join(parent, "moved-original")
+			if err := os.Mkdir(root, 0o755); err != nil {
+				t.Fatal(err)
+			}
+			mustWrite(t, filepath.Join(root, "a.txt"), "pinned-original")
+
+			caller := &driveScriptCaller{reply: func(tool string, _ map[string]any, _ int) (string, error) {
+				switch tool {
+				case "list_files":
+					return `{"result":{"items":[],"nextToken":""}}`, nil
+				case "get_upload_info":
+					return `{"result":{"resourceUrls":[{"url":"https://oss.example.com/put","headers":{}}],"uploadId":"U1"}}`, nil
+				}
+				return `{"result":{"fileId":"NEW"},"success":true}`, nil
+			}}
+
+			var uploaded string
+			putCalls := 0
+			realMove := false
+			testseam.Swap(t, &pushPutOpenedFile, func(_ context.Context, _ string, _ map[string]string, file *os.File, _ int64) error {
+				putCalls++
+				realMove = replacePinnedMirrorRoot(t, root, moved)
+				body, err := io.ReadAll(file)
+				if err != nil {
+					return err
+				}
+				uploaded = string(body)
+				return nil
+			})
+
+			args := []string{command, "--local-folder", root, "--remote-folder", "ROOT"}
+			if command == "sync" {
+				args = append(args, "--quick")
+			}
+			err := runDriveCmd(t, caller, args...)
+			if err == nil {
+				t.Fatal("root replacement during PUT must prevent commit")
+			}
+			if putCalls != 1 || uploaded != "pinned-original" {
+				t.Fatalf("PUT read %q in %d call(s), want pinned-original once", uploaded, putCalls)
+			}
+			if commits := caller.callsFor("commit_upload"); len(commits) != 0 {
+				t.Fatalf("root replacement must prevent commit_upload: %v", commits)
+			}
+			if realMove {
+				if b, readErr := os.ReadFile(filepath.Join(root, "a.txt")); readErr != nil || string(b) != "outside-replacement" {
+					t.Fatalf("replacement file was read or changed: %q err=%v", string(b), readErr)
+				}
+				if b, readErr := os.ReadFile(filepath.Join(moved, "a.txt")); readErr != nil || string(b) != "pinned-original" {
+					t.Fatalf("pinned original changed: %q err=%v", string(b), readErr)
+				}
+			} else if b, readErr := os.ReadFile(filepath.Join(root, "a.txt")); readErr != nil || string(b) != "pinned-original" {
+				// 身份注入降级：原目录仍在原处，内容同样不得被上传路径改写。
+				t.Fatalf("pinned original changed: %q err=%v", string(b), readErr)
+			}
+		})
+	}
+}

internal/helpers/drive_push_type_conflict_test.go

@@ -0,0 +1,108 @@
+package helpers
+
+import (
+	"bytes"
+	"encoding/json"
+	"errors"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam"
+)
+
+func TestCrossPlatformCoverageDrivePushDryRun_typeConflictsFail(t *testing.T) {
+	var out bytes.Buffer
+	testseam.Swap(t, &deps, &Deps{Out: &Formatter{w: &out}})
+
+	tests := []struct {
+		name          string
+		remoteFiles   map[string]*remoteFile
+		remoteFolders map[string]string
+		localDirs     []string
+		localFiles    []localPushFile
+	}{
+		{
+			name:          "remote file conflicts with local folder",
+			remoteFiles:   map[string]*remoteFile{"conflict": {RelPath: "conflict", FileID: "REMOTE_FILE"}},
+			remoteFolders: map[string]string{"": "ROOT"},
+			localDirs:     []string{"conflict"},
+		},
+		{
+			name:          "remote folder conflicts with local file",
+			remoteFiles:   map[string]*remoteFile{},
+			remoteFolders: map[string]string{"": "ROOT", "conflict": "REMOTE_FOLDER"},
+			localFiles:    []localPushFile{{RelPath: "conflict", Size: 1}},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			out.Reset()
+			if err := printDrivePushDryRun(ifExistsSkip, tt.remoteFiles, tt.remoteFolders, tt.localDirs, tt.localFiles); err != nil {
+				t.Fatalf("printDrivePushDryRun: %v", err)
+			}
+
+			var got drivePushDryRunResult
+			if err := json.Unmarshal(out.Bytes(), &got); err != nil {
+				t.Fatalf("decode dry-run result: %v\n%s", err, out.String())
+			}
+			if got.Plan.Summary.Failed != 1 || got.Plan.Summary.Uploaded != 0 {
+				t.Fatalf("summary = %+v, want failed=1 uploaded=0", got.Plan.Summary)
+			}
+			if len(got.Plan.Items) != 1 || got.Plan.Items[0].Action != pushActionFailed || got.Plan.Items[0].Error == "" {
+				t.Fatalf("items = %+v, want one failed item with an error", got.Plan.Items)
+			}
+		})
+	}
+}
+
+func TestCrossPlatformCoverageDrivePush_typeConflictsFailBeforeWrites(t *testing.T) {
+	tests := []struct {
+		name       string
+		prepare    func(*testing.T, string)
+		remoteItem string
+	}{
+		{
+			name: "remote file conflicts with local folder",
+			prepare: func(t *testing.T, root string) {
+				t.Helper()
+				if err := os.Mkdir(filepath.Join(root, "conflict"), 0o755); err != nil {
+					t.Fatal(err)
+				}
+			},
+			remoteItem: `{"name":"conflict","type":"file","fileId":"REMOTE_FILE"}`,
+		},
+		{
+			name: "remote folder conflicts with local file",
+			prepare: func(t *testing.T, root string) {
+				t.Helper()
+				mustWrite(t, filepath.Join(root, "conflict"), "local")
+			},
+			remoteItem: `{"name":"conflict","type":"folder","fileId":"REMOTE_FOLDER"}`,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			root := t.TempDir()
+			tt.prepare(t, root)
+			withNoopPut(t)
+
+			caller := pushOKCaller(map[string]string{
+				"ROOT": `{"result":{"items":[` + tt.remoteItem + `],"nextToken":""}}`,
+			})
+			err := runDriveCmd(t, caller, "push", "--local-folder", root, "--remote-folder", "ROOT")
+			var failure *drivePushFailure
+			if !errors.As(err, &failure) || failure.failed != 1 {
+				t.Fatalf("error = %T %v, want drivePushFailure(failed=1)", err, err)
+			}
+			if calls := caller.callsFor("create_folder"); len(calls) != 0 {
+				t.Fatalf("type conflict must not create folders, got %v", calls)
+			}
+			if calls := caller.callsFor("get_upload_info"); len(calls) != 0 {
+				t.Fatalf("type conflict must not upload, got %v", calls)
+			}
+		})
+	}
+}

internal/helpers/drive_remote_duplicate_test.go

@@ -0,0 +1,86 @@
+package helpers
+
+import (
+	"context"
+	"io"
+	"os"
+	"strings"
+	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam"
+)
+
+func TestCrossPlatformCoverageDriveRemoteTree_duplicatePathsFail(t *testing.T) {
+	tests := []struct {
+		name  string
+		reply func(string, map[string]any, int) (string, error)
+		path  string
+	}{
+		{
+			name: "same file path across pages",
+			path: "duplicate.txt",
+			reply: func(_ string, args map[string]any, _ int) (string, error) {
+				if _, ok := args["nextToken"]; !ok {
+					return `{"result":{"items":[{"name":"duplicate.txt","type":"file","fileId":"F1"}],"nextToken":"PAGE2"}}`, nil
+				}
+				return `{"result":{"items":[{"name":"duplicate.txt","type":"file","fileId":"F2"}],"nextToken":""}}`, nil
+			},
+		},
+		{
+			name: "same folder path with duplicate descendants",
+			path: "duplicate",
+			reply: func(_ string, args map[string]any, _ int) (string, error) {
+				switch args["parentId"] {
+				case "ROOT":
+					return `{"result":{"items":[` +
+						`{"name":"duplicate","type":"folder","fileId":"D1"},` +
+						`{"name":"duplicate","type":"folder","fileId":"D2"}` +
+						`],"nextToken":""}}`, nil
+				case "D1":
+					return `{"result":{"items":[{"name":"child.txt","type":"file","fileId":"C1"}],"nextToken":""}}`, nil
+				case "D2":
+					return `{"result":{"items":[{"name":"child.txt","type":"file","fileId":"C2"}],"nextToken":""}}`, nil
+				default:
+					return `{"result":{"items":[],"nextToken":""}}`, nil
+				}
+			},
+		},
+	}
+
+	fetchers := []struct {
+		name  string
+		fetch func(context.Context) error
+	}{
+		{
+			name: "status and pull tree",
+			fetch: func(ctx context.Context) error {
+				_, err := fetchRemoteDriveTree(ctx, "", "ROOT", true)
+				return err
+			},
+		},
+		{
+			name: "push and sync tree",
+			fetch: func(ctx context.Context) error {
+				_, _, err := fetchRemoteTreeForPush(ctx, "", "ROOT")
+				return err
+			},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			for _, fetcher := range fetchers {
+				t.Run(fetcher.name, func(t *testing.T) {
+					caller := &driveScriptCaller{reply: tt.reply}
+					testseam.Swap(t, &deps, &Deps{Caller: caller, Out: &Formatter{w: io.Discard}})
+					testseam.Swap(t, &os.Args, []string{"dws", "drive"})
+
+					err := fetcher.fetch(context.Background())
+					if err == nil || !strings.Contains(err.Error(), "重复远端路径") || !strings.Contains(err.Error(), tt.path) {
+						t.Fatalf("error = %v, want duplicate remote path %q", err, tt.path)
+					}
+				})
+			}
+		})
+	}
+}

internal/helpers/drive_remote_folder_id_test.go

@@ -0,0 +1,77 @@
+package helpers
+
+import (
+	"context"
+	"io"
+	"os"
+	"strings"
+	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam"
+)
+
+func TestCrossPlatformCoverageDriveRemoteTree_folderIDFallbacks(t *testing.T) {
+	for _, key := range []string{"fileId", "dentryUuid", "dentryId", "id", "nodeId"} {
+		t.Run(key, func(t *testing.T) {
+			caller := &driveScriptCaller{reply: func(_ string, args map[string]any, _ int) (string, error) {
+				if args["parentId"] == "ROOT" {
+					return `{"result":{"items":[{"name":"sub","type":"folder","` + key + `":"SUB"}],"nextToken":""}}`, nil
+				}
+				if args["parentId"] != "SUB" {
+					t.Fatalf("nested parentId = %v, want SUB", args["parentId"])
+				}
+				return `{"result":{"items":[],"nextToken":""}}`, nil
+			}}
+			testseam.Swap(t, &deps, &Deps{Caller: caller, Out: &Formatter{w: io.Discard}})
+			testseam.Swap(t, &os.Args, []string{"dws", "drive"})
+
+			if _, err := fetchRemoteDriveTree(context.Background(), "", "ROOT", true); err != nil {
+				t.Fatalf("fetch with %s: %v", key, err)
+			}
+			if got := len(caller.callsFor("list_files")); got != 2 {
+				t.Fatalf("list_files calls = %d, want root + nested", got)
+			}
+		})
+	}
+}
+
+func TestCrossPlatformCoverageDriveRemoteTree_missingFolderIDFailsClosed(t *testing.T) {
+	for _, fetcher := range []struct {
+		name  string
+		fetch func(context.Context) error
+	}{
+		{
+			name: "status and pull tree",
+			fetch: func(ctx context.Context) error {
+				_, err := fetchRemoteDriveTree(ctx, "", "ROOT", true)
+				return err
+			},
+		},
+		{
+			name: "push and sync tree",
+			fetch: func(ctx context.Context) error {
+				_, _, err := fetchRemoteTreeForPush(ctx, "", "ROOT")
+				return err
+			},
+		},
+	} {
+		t.Run(fetcher.name, func(t *testing.T) {
+			caller := &driveScriptCaller{reply: func(_ string, args map[string]any, nth int) (string, error) {
+				if nth > 0 || args["parentId"] != "ROOT" {
+					t.Fatalf("missing folder ID must not trigger another list_files call: nth=%d args=%v", nth, args)
+				}
+				return `{"result":{"items":[{"name":"sub","type":"folder"}],"nextToken":""}}`, nil
+			}}
+			testseam.Swap(t, &deps, &Deps{Caller: caller, Out: &Formatter{w: io.Discard}})
+			testseam.Swap(t, &os.Args, []string{"dws", "drive"})
+
+			err := fetcher.fetch(context.Background())
+			if err == nil || !strings.Contains(err.Error(), "目录 ID") || !strings.Contains(err.Error(), "sub") {
+				t.Fatalf("error = %v, want missing folder ID for sub", err)
+			}
+			if got := len(caller.callsFor("list_files")); got != 1 {
+				t.Fatalf("list_files calls = %d, want only root query", got)
+			}
+		})
+	}
+}

internal/helpers/drive_remote_tree_integrity_test.go

@@ -0,0 +1,309 @@
+package helpers
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam"
+)
+
+func TestCrossPlatformCoverageParseDriveList_requiresAuthoritativeResult(t *testing.T) {
+	tests := []struct {
+		name      string
+		body      string
+		wantError string
+		wantItems int
+	}{
+		{name: "missing result", body: `{}`, wantError: "缺少 result"},
+		{name: "null result", body: `{"result":null}`, wantError: "result 为 null"},
+		{name: "empty result object", body: `{"result":{}}`, wantError: "缺少 items"},
+		{name: "null item", body: `{"result":{"items":[null]}}`, wantError: "缺少有效 type"},
+		{name: "empty item object", body: `{"result":{"items":[{}]}}`, wantError: "缺少有效 type"},
+		{name: "item missing type", body: `{"result":{"items":[{"name":"unknown"}]}}`, wantError: "缺少有效 type"},
+		{name: "item empty type", body: `{"result":{"items":[{"name":"unknown","type":"  "}]}}`, wantError: "缺少有效 type"},
+		{name: "has more without token", body: `{"result":{"items":[],"hasMore":true,"nextToken":""}}`, wantError: "hasMore=true"},
+		{name: "empty items", body: `{"result":{"items":[]}}`},
+		{name: "empty result array", body: `{"result":[]}`},
+		{name: "explicit unsupported type remains parseable", body: `{"result":{"items":[{"name":"online.adoc","type":"document"}]}}`, wantItems: 1},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			items, token, err := parseDriveList(tt.body)
+			if tt.wantError != "" {
+				if err == nil || !strings.Contains(err.Error(), tt.wantError) {
+					t.Fatalf("parseDriveList error = %v, want containing %q", err, tt.wantError)
+				}
+				return
+			}
+			if err != nil {
+				t.Fatalf("parseDriveList(%s): %v", tt.body, err)
+			}
+			if len(items) != tt.wantItems || token != "" {
+				t.Fatalf("parseDriveList(%s) = (%v, %q), want %d authoritative item(s) with no token", tt.body, items, token, tt.wantItems)
+			}
+		})
+	}
+}
+
+func TestCrossPlatformCoverageDriveRemoteTree_integrityFailuresStopFourCommandsBeforeWrites(t *testing.T) {
+	failures := []struct {
+		name          string
+		wantError     string
+		wantListCalls int
+		reply         func(int) string
+	}{
+		{
+			name:          "missing result",
+			wantError:     "缺少 result",
+			wantListCalls: 1,
+			reply:         func(int) string { return `{}` },
+		},
+		{
+			name:          "null result",
+			wantError:     "result 为 null",
+			wantListCalls: 1,
+			reply:         func(int) string { return `{"result":null}` },
+		},
+		{
+			name:          "empty result object",
+			wantError:     "缺少 items",
+			wantListCalls: 1,
+			reply:         func(int) string { return `{"result":{}}` },
+		},
+		{
+			name:          "null item",
+			wantError:     "缺少有效 type",
+			wantListCalls: 1,
+			reply:         func(int) string { return `{"result":{"items":[null],"nextToken":""}}` },
+		},
+		{
+			name:          "empty item object",
+			wantError:     "缺少有效 type",
+			wantListCalls: 1,
+			reply:         func(int) string { return `{"result":{"items":[{}],"nextToken":""}}` },
+		},
+		{
+			name:          "item missing type",
+			wantError:     "缺少有效 type",
+			wantListCalls: 1,
+			reply: func(int) string {
+				return `{"result":{"items":[{"name":"unknown"}],"nextToken":""}}`
+			},
+		},
+		{
+			name:          "item empty type",
+			wantError:     "缺少有效 type",
+			wantListCalls: 1,
+			reply: func(int) string {
+				return `{"result":{"items":[{"name":"unknown","type":""}],"nextToken":""}}`
+			},
+		},
+		{
+			name:          "has more without token",
+			wantError:     "hasMore=true",
+			wantListCalls: 1,
+			reply: func(int) string {
+				return `{"result":{"items":[],"hasMore":true,"nextToken":""}}`
+			},
+		},
+		{
+			name:          "file without an ID",
+			wantError:     "缺少文件 ID",
+			wantListCalls: 1,
+			reply: func(int) string {
+				return `{"result":{"items":[{"name":"remote.txt","type":"file"}],"nextToken":""}}`
+			},
+		},
+		{
+			name:          "file name with an ASCII control",
+			wantError:     "无法安全映射到本地路径",
+			wantListCalls: 1,
+			reply: func(int) string {
+				return `{"result":{"items":[{"name":"remote\u0000.txt","type":"file","fileId":"REMOTE"}],"nextToken":""}}`
+			},
+		},
+		{
+			name:          "pagination token cycle",
+			wantError:     "分页 token",
+			wantListCalls: 3,
+			reply: func(nth int) string {
+				tokens := []string{"PAGE_A", "PAGE_B", "PAGE_A"}
+				if nth >= len(tokens) {
+					return `{"result":{"items":[],"nextToken":""}}`
+				}
+				return fmt.Sprintf(`{"result":{"items":[],"nextToken":%q}}`, tokens[nth])
+			},
+		},
+	}
+
+	commands := []struct {
+		name    string
+		args    func(string) []string
+		prepare func(*testing.T, string)
+	}{
+		{
+			name: "status",
+			args: func(localRoot string) []string {
+				return []string{"status", "--local-folder", localRoot, "--remote-folder", "ROOT", "--quick"}
+			},
+			prepare: prepareRemoteTreeReadRoot,
+		},
+		{
+			name: "pull",
+			args: func(localRoot string) []string {
+				return []string{"pull", "--local-folder", localRoot, "--remote-folder", "ROOT"}
+			},
+		},
+		{
+			name: "push",
+			args: func(localRoot string) []string {
+				return []string{"push", "--local-folder", localRoot, "--remote-folder", "ROOT"}
+			},
+			prepare: prepareRemoteTreeWriteSource,
+		},
+		{
+			name: "sync",
+			args: func(localRoot string) []string {
+				return []string{"sync", "--local-folder", localRoot, "--remote-folder", "ROOT", "--quick"}
+			},
+			prepare: prepareRemoteTreeWriteSource,
+		},
+	}
+
+	for _, failure := range failures {
+		t.Run(failure.name, func(t *testing.T) {
+			for _, command := range commands {
+				t.Run(command.name, func(t *testing.T) {
+					localRoot := filepath.Join(t.TempDir(), "mirror")
+					if command.prepare != nil {
+						command.prepare(t, localRoot)
+					}
+
+					caller := &driveScriptCaller{reply: func(tool string, _ map[string]any, nth int) (string, error) {
+						if tool != "list_files" {
+							return "", fmt.Errorf("远端清单预检完成前调用了写工具 %s", tool)
+						}
+						return failure.reply(nth), nil
+					}}
+					getCalls, putCalls := swapRemoteTreeTransferCounters(t)
+
+					err := runDriveCmd(t, caller, command.args(localRoot)...)
+					if err == nil || !strings.Contains(err.Error(), failure.wantError) {
+						t.Fatalf("error = %v, want remote tree integrity failure containing %q", err, failure.wantError)
+					}
+					if got := len(caller.callsFor("list_files")); got != failure.wantListCalls {
+						t.Fatalf("list_files calls = %d, want %d", got, failure.wantListCalls)
+					}
+					for _, call := range caller.calls {
+						if call.toolName != "list_files" {
+							t.Fatalf("remote tree integrity failure must stop before MCP writes, got %s", call.toolName)
+						}
+					}
+					if *getCalls != 0 || *putCalls != 0 {
+						t.Fatalf("remote tree integrity failure must stop before transfers: GET=%d PUT=%d", *getCalls, *putCalls)
+					}
+					if command.name == "pull" {
+						if _, statErr := os.Stat(localRoot); !os.IsNotExist(statErr) {
+							t.Fatalf("pull must fail before creating its local root: %v", statErr)
+						}
+					}
+				})
+			}
+		})
+	}
+}
+
+func TestCrossPlatformCoverageDriveRemoteTree_validEmptyListsRemainSupported(t *testing.T) {
+	for _, listing := range []struct {
+		name string
+		body string
+	}{
+		{name: "items object", body: `{"result":{"items":[]}}`},
+		{name: "result array", body: `{"result":[]}`},
+	} {
+		t.Run(listing.name, func(t *testing.T) {
+			for _, fetcher := range []struct {
+				name  string
+				fetch func(context.Context) error
+			}{
+				{
+					name: "status and pull walker",
+					fetch: func(ctx context.Context) error {
+						files, err := fetchRemoteDriveTree(ctx, "", "ROOT", true)
+						if len(files) != 0 {
+							return fmt.Errorf("remote files = %v, want empty", files)
+						}
+						return err
+					},
+				},
+				{
+					name: "push and sync walker",
+					fetch: func(ctx context.Context) error {
+						files, folders, err := fetchRemoteTreeForPush(ctx, "", "ROOT")
+						if len(files) != 0 || len(folders) != 1 || folders[""] != "ROOT" {
+							return fmt.Errorf("remote tree = files %v folders %v, want empty root", files, folders)
+						}
+						return err
+					},
+				},
+			} {
+				t.Run(fetcher.name, func(t *testing.T) {
+					caller := &driveScriptCaller{reply: func(tool string, _ map[string]any, _ int) (string, error) {
+						if tool != "list_files" {
+							t.Fatalf("unexpected tool %s", tool)
+						}
+						return listing.body, nil
+					}}
+					testseam.Swap(t, &deps, &Deps{Caller: caller, Out: &Formatter{w: io.Discard}})
+					testseam.Swap(t, &os.Args, []string{"dws", "drive"})
+					if err := fetcher.fetch(context.Background()); err != nil {
+						t.Fatalf("valid empty listing: %v", err)
+					}
+					if got := len(caller.callsFor("list_files")); got != 1 {
+						t.Fatalf("list_files calls = %d, want 1", got)
+					}
+				})
+			}
+		})
+	}
+}
+
+func TestCrossPlatformCoverageIsSafeRemoteSegment_rejectsASCIIControls(t *testing.T) {
+	for _, name := range []string{"nul\x00name", "unit\x1fseparator", "delete\x7fcharacter"} {
+		if isSafeRemoteSegment(name) {
+			t.Errorf("isSafeRemoteSegment(%q) = true, want false", name)
+		}
+	}
+}
+
+func prepareRemoteTreeReadRoot(t *testing.T, localRoot string) {
+	t.Helper()
+	if err := os.MkdirAll(localRoot, 0o755); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func prepareRemoteTreeWriteSource(t *testing.T, localRoot string) {
+	t.Helper()
+	mustWrite(t, filepath.Join(localRoot, "local.txt"), "local")
+}
+
+func swapRemoteTreeTransferCounters(t *testing.T) (*int, *int) {
+	t.Helper()
+	getCalls, putCalls := 0, 0
+	swapPullDownloadPath(t, func(context.Context, string, map[string]string, string) error {
+		getCalls++
+		return nil
+	})
+	testseam.Swap(t, &pushPutOpenedFile, func(context.Context, string, map[string]string, *os.File, int64) error {
+		putCalls++
+		return nil
+	})
+	return &getCalls, &putCalls
+}

internal/helpers/drive_remote_unsafe_name_test.go

@@ -0,0 +1,125 @@
+package helpers
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam"
+)
+
+func TestCrossPlatformCoverageDriveRemoteTree_unsafeNamesFailClosed(t *testing.T) {
+	tests := []struct {
+		name     string
+		listing  string
+		wantKind string
+	}{
+		{
+			name:     "file name containing a backslash",
+			listing:  `{"result":{"items":[{"name":"a\\b.txt","type":"file","fileId":"UNSAFE_FILE"}],"nextToken":""}}`,
+			wantKind: "文件",
+		},
+		{
+			name:     "folder name escaping its parent",
+			listing:  `{"result":{"items":[{"name":"..","type":"folder","fileId":"UNSAFE_FOLDER"}],"nextToken":""}}`,
+			wantKind: "目录",
+		},
+	}
+
+	commands := []struct {
+		name    string
+		args    func(localRoot string) []string
+		prepare func(t *testing.T, localRoot string)
+	}{
+		{
+			name: "status",
+			args: func(localRoot string) []string {
+				return []string{"status", "--local-folder", localRoot, "--remote-folder", "ROOT", "--quick"}
+			},
+			prepare: func(t *testing.T, localRoot string) {
+				t.Helper()
+				if err := os.MkdirAll(localRoot, 0o755); err != nil {
+					t.Fatal(err)
+				}
+			},
+		},
+		{
+			name: "pull",
+			args: func(localRoot string) []string {
+				return []string{"pull", "--local-folder", localRoot, "--remote-folder", "ROOT"}
+			},
+		},
+		{
+			name: "push",
+			args: func(localRoot string) []string {
+				return []string{"push", "--local-folder", localRoot, "--remote-folder", "ROOT"}
+			},
+			prepare: prepareUnsafeNameWriteSource,
+		},
+		{
+			name: "sync",
+			args: func(localRoot string) []string {
+				return []string{"sync", "--local-folder", localRoot, "--remote-folder", "ROOT", "--quick"}
+			},
+			prepare: prepareUnsafeNameWriteSource,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			for _, command := range commands {
+				t.Run(command.name, func(t *testing.T) {
+					localRoot := filepath.Join(t.TempDir(), "mirror")
+					if command.prepare != nil {
+						command.prepare(t, localRoot)
+					}
+
+					caller := &driveScriptCaller{reply: func(tool string, args map[string]any, nth int) (string, error) {
+						if tool != "list_files" || nth != 0 || args["parentId"] != "ROOT" {
+							t.Fatalf("unsafe remote entry must stop before recursion: tool=%s nth=%d args=%v", tool, nth, args)
+						}
+						return tt.listing, nil
+					}}
+					getCalls, putCalls := 0, 0
+					swapPullDownloadPath(t, func(context.Context, string, map[string]string, string) error {
+						getCalls++
+						return nil
+					})
+					testseam.Swap(t, &pushPutOpenedFile, func(context.Context, string, map[string]string, *os.File, int64) error {
+						putCalls++
+						return nil
+					})
+
+					err := runDriveCmd(t, caller, command.args(localRoot)...)
+					if err == nil || !strings.Contains(err.Error(), "无法安全映射到本地路径") ||
+						!strings.Contains(err.Error(), tt.wantKind) {
+						t.Fatalf("error = %v, want unsafe remote %s name failure", err, tt.wantKind)
+					}
+					if got := len(caller.callsFor("list_files")); got != 1 {
+						t.Fatalf("list_files calls = %d, want only the root query", got)
+					}
+					for _, tool := range []string{"create_folder", "download_file", "get_upload_info", "commit_upload"} {
+						if calls := caller.callsFor(tool); len(calls) != 0 {
+							t.Fatalf("unsafe remote name must not call %s: %v", tool, calls)
+						}
+					}
+					if getCalls != 0 || putCalls != 0 {
+						t.Fatalf("unsafe remote name must not transfer content: GET=%d PUT=%d", getCalls, putCalls)
+					}
+					if command.name == "pull" {
+						if _, statErr := os.Stat(localRoot); !os.IsNotExist(statErr) {
+							t.Fatalf("pull must fail before creating its local root: %v", statErr)
+						}
+					}
+				})
+			}
+		})
+	}
+}
+
+func prepareUnsafeNameWriteSource(t *testing.T, localRoot string) {
+	t.Helper()
+	mustWrite(t, filepath.Join(localRoot, "local.txt"), "local")
+}

internal/helpers/drive_replace_unix.go

@@ -0,0 +1,11 @@
+//go:build !windows
+
+package helpers
+
+import "os"
+
+// driveReplaceFile 在同一文件系统内以 source 替换既有非目录 target。
+// Unix 的 rename(2) 原生提供原子替换语义。
+func driveReplaceFile(source, target string) error {
+	return os.Rename(source, target)
+}

internal/helpers/drive_replace_unix_test.go

@@ -0,0 +1,34 @@
+//go:build !windows
+
+package helpers
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+// Unix 的 rename(2) 原生提供原子替换语义；该路径与 Windows 的
+// MOVEFILE_REPLACE_EXISTING 同样服务 pull overwrite、sync remote-wins 与
+// keep-both 的占位文件替换，因此两侧都需要平台覆盖。
+func TestCrossPlatformCoverageDriveReplaceFileUnix_replacesExistingTarget(t *testing.T) {
+	dir := t.TempDir()
+	source := filepath.Join(dir, "source.tmp")
+	target := filepath.Join(dir, "target.txt")
+	if err := os.WriteFile(source, []byte("new"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(target, []byte("old"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+
+	if err := driveReplaceFile(source, target); err != nil {
+		t.Fatalf("replace existing target: %v", err)
+	}
+	if got, err := os.ReadFile(target); err != nil || string(got) != "new" {
+		t.Fatalf("target = %q, err=%v; want new content", got, err)
+	}
+	if _, err := os.Stat(source); !os.IsNotExist(err) {
+		t.Fatalf("source must be moved, stat err=%v", err)
+	}
+}

internal/helpers/drive_replace_windows.go

@@ -0,0 +1,11 @@
+//go:build windows
+
+package helpers
+
+import "golang.org/x/sys/windows"
+
+// driveReplaceFile 使用 MoveFileEx(MOVEFILE_REPLACE_EXISTING) 替换既有非目录目标。
+// 不使用“先删除再改名”，避免覆盖过程中出现目标暂时缺失或原文件丢失。
+func driveReplaceFile(source, target string) error {
+	return windows.Rename(source, target)
+}

internal/helpers/drive_replace_windows_test.go

@@ -0,0 +1,33 @@
+//go:build windows
+
+package helpers
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+// Windows 必须通过 MOVEFILE_REPLACE_EXISTING 原子替换既有非目录目标；该路径同时
+// 服务 pull overwrite、sync remote-wins 与 keep-both 的占位文件替换。
+func TestCrossPlatformCoverageDriveReplaceFileWindows_replacesExistingTarget(t *testing.T) {
+	dir := t.TempDir()
+	source := filepath.Join(dir, "source.tmp")
+	target := filepath.Join(dir, "target.txt")
+	if err := os.WriteFile(source, []byte("new"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(target, []byte("old"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+
+	if err := driveReplaceFile(source, target); err != nil {
+		t.Fatalf("replace existing target: %v", err)
+	}
+	if got, err := os.ReadFile(target); err != nil || string(got) != "new" {
+		t.Fatalf("target = %q, err=%v; want new content", got, err)
+	}
+	if _, err := os.Stat(source); !os.IsNotExist(err) {
+		t.Fatalf("source must be moved, stat err=%v", err)
+	}
+}

internal/helpers/drive_status.go

@@ -0,0 +1,671 @@
+package helpers
+
+import (
+	"bytes"
+	"context"
+	"crypto/md5"
+	"encoding/base64"
+	"encoding/json"
+	"fmt"
+	"io"
+	"io/fs"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+
+	"github.com/spf13/cobra"
+)
+
+// ==========================================================
+// drive status — 比较本地文件夹与钉盘文件夹的差异
+// ==========================================================
+// ──────────────────────────────────────────────────────────
+// dws drive status — 比较本地文件夹与钉盘文件夹的差异
+//
+// 只读命令：本地取 --local-folder（绝对路径），钉盘取 --remote-folder
+// （文件夹 dentryUuid）指向的文件夹，按精确 MD5（默认）或快速 modified_time
+// （--quick）逐文件比对，输出 new_local / new_remote / modified / unchanged /
+// unknown 五类差异（exact 模式远端无可靠 md5 的文件归入 unknown）。两侧各自递归
+// 遍历，rel_path 相对各自根目录。
+//
+// 后端交互（按 parentId 递归拉取 list_files、只保留 type=file 的二进制文件、并为
+// 每个条目填充 hash 或者 modified_time），见 fetchRemoteDriveTree。
+// ──────────────────────────────────────────────────────────
+
+// driveStatusEntry 是输出 schema 中每个差异项的形态：{"rel_path": "..."}。
+type driveStatusEntry struct {
+	RelPath string `json:"rel_path"`
+}
+
+// driveStatusResult 是 status 命令成功时的输出 schema。
+// 五个切片都初始化为非 nil，保证 JSON 序列化为 [] 而不是 null。
+//
+// unknown：exact 模式下双端都存在、但远端未返回可靠 md5 的文件——此时无法核对
+// 内容，既不能判 unchanged（会误报未变更），也不宜硬判 modified（会误报变更），
+// 如实归入 unknown，让降级模式在输出里显式可见。quick 模式不会产生 unknown。
+type driveStatusResult struct {
+	Detection string             `json:"detection"`
+	NewLocal  []driveStatusEntry `json:"new_local"`
+	NewRemote []driveStatusEntry `json:"new_remote"`
+	Modified  []driveStatusEntry `json:"modified"`
+	Unchanged []driveStatusEntry `json:"unchanged"`
+	Unknown   []driveStatusEntry `json:"unknown"`
+}
+
+// localFile 描述一个本地常规文件。
+type localFile struct {
+	RelPath       string
+	AbsPath       string // 绝对路径，用于按需计算 MD5
+	Hash          string // MD5（base64）；仅在双端都存在且非 quick 模式时按需计算
+	Size          int64  // 本地文件字节数
+	ModTimeMillis int64  // 本地 mtime，Unix 毫秒
+}
+
+// remoteFile 描述一个云端 type=file 的二进制文件。
+// 由 fetchRemoteDriveTree 填充。
+type remoteFile struct {
+	RelPath           string
+	FileID            string // dentryUuid；pull 下载时作为 download_file 的 fileId
+	Hash              string // 远端 md5（base64，exact 模式用；为空时该文件归入 unknown）
+	Size              int64  // 远端文件字节数
+	ModifiedTime      int64  // 远端 modified_time，Unix 毫秒（quick / smart 模式比较用）
+	ModifiedTimeValid bool   // 远端时间戳是否可信；不可信时走保守路径
+}
+
+// 每次 list_files 请求的分页大小。后端约束 maxResults 必须在 1..50 之间。
+const driveListPageSize = 50
+
+// remoteMaxDepth 是递归遍历子文件夹的最大层级，防止云端目录出现环形引用时死循环。
+const remoteMaxDepth = 64
+
+// fetchRemoteDriveTree 递归拉取云端文件夹 parentID 下的文件树，返回所有 type=FILE 的
+// 二进制文件索引（key 为 rel_path）。spaceID 为空时省略 spaceId 参数，由 MCP Server
+// 默认到「我的文件」（与其它 drive 命令一致）；parentID 为待比对的云端根文件夹 dentryUuid。
+//
+// 实现要点：
+//   - 通过 drive 的 list_files MCP 工具，按 parentId（文件夹 dentryUuid）逐层遍历；
+//   - 单个目录文件过多时按 nextToken 分批拉取（maxResults ≤ 50）；
+//   - 遇到子文件夹用其 dentryUuid 作为下一层的 parentId 递归进入；
+//   - rel_path 由各层文件夹名逐层拼接得到（相对 parentID 根），与本地相对路径对齐；
+//   - 只纳入明确 type=FILE 的条目，其余类型（在线文档、快捷方式等）一律跳过。
+func fetchRemoteDriveTree(ctx context.Context, spaceID, parentID string, quick bool) (map[string]*remoteFile, error) {
+	out := make(map[string]*remoteFile)
+	occupied := make(map[string]string)
+	if err := walkRemoteDir(ctx, spaceID, parentID, "", out, occupied, 0); err != nil {
+		return nil, err
+	}
+	_ = quick // hash 与 modified_time 都会被填充，比对模式由 compareTrees 决定
+	return out, nil
+}
+
+// walkRemoteDir 遍历 parentID 指向的文件夹，把其中的二进制文件写入 out（key 为 rel_path），
+// 并递归进入子文件夹。occupied 同时记录文件和目录；精确路径被第二个条目占用时立即失败，
+// 防止分页或返回顺序决定最终镜像。relBase 是当前文件夹相对遍历起点的路径前缀。
+func walkRemoteDir(ctx context.Context, spaceID, parentID, relBase string, out map[string]*remoteFile, occupied map[string]string, depth int) error {
+	if depth > remoteMaxDepth {
+		return fmt.Errorf("drive 目录层级超过 %d 层，疑似循环引用，已中止", remoteMaxDepth)
+	}
+
+	nextToken := ""
+	seenTokens := make(map[string]struct{})
+	for {
+		args := map[string]any{"maxResults": float64(driveListPageSize)}
+		// space-id 为空则省略，交给 MCP Server 默认「我的文件」。
+		if spaceID != "" {
+			args["spaceId"] = spaceID
+		}
+		// 按 parentId（文件夹 dentryUuid）导航；空则由 MCP Server 默认列空间根目录。
+		if parentID != "" {
+			args["parentId"] = parentID
+		}
+		if nextToken != "" {
+			args["nextToken"] = nextToken
+		}
+
+		text, err := callDriveListFiles(ctx, args)
+		if err != nil {
+			return err
+		}
+
+		items, token, err := parseDriveList(text)
+		if err != nil {
+			return err
+		}
+
+		for _, it := range items {
+			name, included, err := remoteMirrorEntryName(it, relBase)
+			if err != nil {
+				return err
+			}
+			if !included {
+				continue
+			}
+			// rel_path 由文件夹名逐层拼接，统一用 / 分隔，与本地相对路径对齐。
+			childRel := name
+			if relBase != "" {
+				childRel = relBase + "/" + name
+			}
+
+			if it.isFolder() {
+				if err := claimRemotePath(occupied, childRel, "目录"); err != nil {
+					return err
+				}
+				folderID := it.id()
+				if folderID == "" {
+					return fmt.Errorf("远端目录 %q 缺少目录 ID，已中止递归", childRel)
+				}
+				// 用子文件夹的 dentryUuid 作为下一层 parentId 递归进入。
+				if err := walkRemoteDir(ctx, spaceID, folderID, childRel, out, occupied, depth+1); err != nil {
+					return err
+				}
+				continue
+			}
+			// 非文件类型已由 remoteMirrorEntryName 过滤；目录在上方完成递归后返回。
+			if err := claimRemotePath(occupied, childRel, "文件"); err != nil {
+				return err
+			}
+			fileID := it.id()
+			if fileID == "" {
+				return fmt.Errorf("远端文件 %q 缺少文件 ID，已中止遍历", childRel)
+			}
+
+			modMillis, modValid := it.modifiedMillis()
+			out[childRel] = &remoteFile{
+				RelPath:           childRel,
+				FileID:            fileID,
+				Hash:              it.hash(),
+				Size:              it.size(),
+				ModifiedTime:      modMillis,
+				ModifiedTimeValid: modValid,
+			}
+		}
+
+		if token == "" {
+			break
+		}
+		if _, exists := seenTokens[token]; exists {
+			return fmt.Errorf("远端目录 %q 的分页 token 重复，疑似分页循环，已中止", relBase)
+		}
+		seenTokens[token] = struct{}{}
+		nextToken = token
+	}
+	return nil
+}
+
+// claimRemotePath 保证一棵远端树中的每个精确 rel_path 只对应一个文件或目录。
+// 重复条目会让本地镜像不可完整表达，因此必须失败，不能任意选择其中一个 fileId。
+func claimRemotePath(occupied map[string]string, rel, kind string) error {
+	if previous, exists := occupied[rel]; exists {
+		return fmt.Errorf("检测到重复远端路径 %q（已有%s，重复%s），无法构建确定性镜像", rel, previous, kind)
+	}
+	occupied[rel] = kind
+	return nil
+}
+
+// remoteMirrorEntryName 只选择文件夹镜像支持的 file / folder 条目，并验证其名称
+// 能安全、无歧义地表示为本地单层路径。无法表示的镜像条目必须中止整棵远端树构建；
+// 静默跳过会让 status/pull/push/sync 在遗漏文件或目录子树时误报成功。
+func remoteMirrorEntryName(it driveItem, relBase string) (string, bool, error) {
+	kind := ""
+	switch {
+	case it.isFolder():
+		kind = "目录"
+	case it.isFile():
+		kind = "文件"
+	default:
+		return "", false, nil
+	}
+
+	name := it.name()
+	if !isSafeRemoteSegment(name) {
+		return "", false, fmt.Errorf("远端%s名称 %q 无法安全映射到本地路径（父路径 %q），已中止", kind, name, relBase)
+	}
+	return name, true, nil
+}
+
+// callDriveListFiles 让文件夹同步族在 --dry-run 下仍可通过受控只读通道获取
+// 远端现状；普通 CallTool 在 dry-run 下只会返回执行计划，不能被当作业务数据解析。
+func callDriveListFiles(ctx context.Context, args map[string]any) (string, error) {
+	if deps.Caller.DryRun() {
+		return callMCPReadToolReturnTextOnServer(ctx, "drive", "list_files", args)
+	}
+	return callMCPToolReturnText(ctx, "list_files", args)
+}
+
+// driveItem 是 list_files 返回里的一个 dentry 条目。
+// 后端字段命名存在多种历史写法，这里用带 fallback 的访问器做防御式解析。
+type driveItem map[string]any
+
+func (d driveItem) str(keys ...string) string {
+	for _, k := range keys {
+		if s, ok := d[k].(string); ok && s != "" {
+			return s
+		}
+	}
+	return ""
+}
+
+func (d driveItem) name() string { return d.str("name") }
+func (d driveItem) id() string   { return d.str("fileId", "dentryUuid", "dentryId", "id", "nodeId") }
+func (d driveItem) typ() string  { return d.str("type") }
+func (d driveItem) hash() string { return d.str("md5") }
+func (d driveItem) path() string { return d.str("path") }
+
+// size 返回远端文件字节数（fileSize 字段），用于 exact 无 md5 时的降级比对。
+func (d driveItem) size() int64 {
+	switch v := d["fileSize"].(type) {
+	case float64:
+		return int64(v)
+	case json.Number:
+		if n, err := v.Int64(); err == nil {
+			return n
+		}
+	}
+	return 0
+}
+
+func (d driveItem) isFolder() bool {
+	return strings.ToUpper(d.typ()) == "FOLDER"
+}
+
+func (d driveItem) isFile() bool {
+	return strings.ToUpper(d.typ()) == "FILE"
+}
+
+func (d driveItem) modifiedMillis() (int64, bool) {
+	for _, k := range []string{"modifiedTime", "modifyTime", "modified_time", "gmtModified", "lastModifiedTime", "updateTime"} {
+		if v, ok := d[k]; ok {
+			if ms, ok := toMillis(v); ok {
+				return ms, true
+			}
+		}
+	}
+	return 0, false
+}
+
+// parseDriveList 解析 list_files 返回文本，抽出 items 列表与 nextToken。
+// 兼容两种 result 形态：
+//   - {"result":{"items":[...],"nextToken":"..."}}
+//   - {"result":[...]}（result 直接是条目数组，无分页）
+func parseDriveList(text string) ([]driveItem, string, error) {
+	var envelope map[string]json.RawMessage
+	if err := json.Unmarshal([]byte(text), &envelope); err != nil {
+		return nil, "", fmt.Errorf("解析 list_files 返回失败: %w", err)
+	}
+	result, exists := envelope["result"]
+	if !exists {
+		return nil, "", fmt.Errorf("解析 list_files 返回失败: 缺少 result")
+	}
+	result = json.RawMessage(bytes.TrimSpace(result))
+	if bytes.Equal(result, []byte("null")) {
+		return nil, "", fmt.Errorf("解析 list_files 返回失败: result 为 null")
+	}
+
+	toItems := func(ms []map[string]any) ([]driveItem, error) {
+		items := make([]driveItem, 0, len(ms))
+		for index, m := range ms {
+			item := driveItem(m)
+			// FILE / FOLDER 之外的显式类型（在线文档、快捷方式等）可以由镜像
+			// walker 跳过；但 null、空对象或缺少有效 type 的条目不是一个可判定的
+			// 业务对象。静默跳过会把不完整清单伪装成权威目录，必须失败关闭。
+			if m == nil || strings.TrimSpace(item.typ()) == "" {
+				return nil, fmt.Errorf("解析 list_files 返回失败: result.items[%d] 缺少有效 type", index)
+			}
+			items = append(items, item)
+		}
+		return items, nil
+	}
+
+	switch {
+	case len(result) > 0 && result[0] == '{':
+		// 形态一：result 是对象 {items, nextToken}。items 必须显式存在，不能把
+		// 缺失/null 的非权威响应误判为空目录。
+		var obj struct {
+			Items     json.RawMessage `json:"items"`
+			NextToken string          `json:"nextToken"`
+			HasMore   *bool           `json:"hasMore"`
+		}
+		if err := json.Unmarshal(result, &obj); err != nil {
+			return nil, "", fmt.Errorf("解析 list_files 返回失败: %w", err)
+		}
+		if len(obj.Items) == 0 {
+			return nil, "", fmt.Errorf("解析 list_files 返回失败: result 缺少 items")
+		}
+		var items []map[string]any
+		if err := json.Unmarshal(obj.Items, &items); err != nil || items == nil {
+			return nil, "", fmt.Errorf("解析 list_files 返回失败: result.items 不是数组")
+		}
+		if obj.HasMore != nil && *obj.HasMore && obj.NextToken == "" {
+			return nil, "", fmt.Errorf("解析 list_files 返回失败: hasMore=true 但 nextToken 为空，远端清单可能被截断")
+		}
+		parsed, err := toItems(items)
+		if err != nil {
+			return nil, "", err
+		}
+		return parsed, obj.NextToken, nil
+	case len(result) > 0 && result[0] == '[':
+		// 形态二：result 直接是条目数组。
+		var arr []map[string]any
+		if err := json.Unmarshal(result, &arr); err != nil {
+			return nil, "", fmt.Errorf("解析 list_files 返回失败: result 数组无效: %w", err)
+		}
+		parsed, err := toItems(arr)
+		if err != nil {
+			return nil, "", err
+		}
+		return parsed, "", nil
+	}
+
+	return nil, "", fmt.Errorf("解析 list_files 返回失败: result 既不是 {items:[]} 也不是数组")
+}
+
+// validateLocalDirAbs 校验 --local-folder 必须是绝对路径，返回其清理后的绝对路径。
+func validateLocalDirAbs(localDir string) (string, error) {
+	if localDir == "" {
+		return "", fmt.Errorf("flag --local-folder is required")
+	}
+	if !filepath.IsAbs(localDir) {
+		return "", fmt.Errorf("--local-folder 必须是绝对路径: %s", localDir)
+	}
+	return filepath.Clean(localDir), nil
+}
+
+// isSafeRemoteSegment 校验单个远端条目名称是否可安全用作一层相对路径段。
+// 拒绝空串、"."、".."、ASCII 控制字符、含卷标（如 Windows 的 "C:"）以及任意平台
+// 的路径分隔符（/ 与 \）——这些成分无法安全表示为本地文件名，或可能让下载目标逃逸
+// 出本地根目录。
+func isSafeRemoteSegment(name string) bool {
+	if name == "" || name == "." || name == ".." {
+		return false
+	}
+	for i := 0; i < len(name); i++ {
+		if name[i] <= 0x1f || name[i] == 0x7f {
+			return false
+		}
+	}
+	// 任意平台分隔符都不允许出现在单层名称里。
+	if strings.ContainsAny(name, `/\`) {
+		return false
+	}
+	// 余下的卷标/规范化检查只在 Windows 上可达：Unix 的 filepath.VolumeName 恒为空，
+	// 且经上面的分隔符过滤后 filepath.Clean 不会再改写名称。按平台分文件承载。
+	return isSafeRemoteSegmentPlatform(name)
+}
+
+// resolveLocalTarget 把远端 rel_path 拼到本地根目录 absDir 下，并确认结果仍位于
+// absDir 内。除词法检查（filepath.Rel）外，还解析已存在路径组件的符号链接，防止
+// root 内的目录软链（如 root/sub -> /outside）把落盘点指到根目录外。逃逸时返回错误。
+func resolveLocalTarget(absDir, rel string) (string, error) {
+	target := filepath.Join(absDir, filepath.FromSlash(rel))
+	back, err := filepath.Rel(absDir, target)
+	if err != nil || back == ".." || strings.HasPrefix(back, ".."+string(filepath.Separator)) {
+		return "", fmt.Errorf("远端路径 %q 逃逸出本地根目录", rel)
+	}
+	if err := verifyNoSymlinkEscape(absDir, target); err != nil {
+		return "", err
+	}
+	return target, nil
+}
+
+// verifyNoSymlinkEscape 挡住「absDir 之内的目录软链指向外部」的逃逸：从 target 的父
+// 目录向上、在**不越过 absDir 边界**的前提下，找到最深的已存在祖先，解析其真实路径
+// （EvalSymlinks 展开整条软链），确认仍位于 absDir 真实路径之内。
+//
+// absDir 尚不存在时直接放行：其下不可能有已存在的组件可供逃逸，后续 MkdirAll 只会
+// 创建真实目录、绝不新建软链——这也是 pull 自动创建目标根目录的正常路径。target 尚不
+// 存在的末段同理无软链可谈，故只需校验 [absDir, target] 之间的现有组件。
+func verifyNoSymlinkEscape(absDir, target string) error {
+	absDir = filepath.Clean(absDir)
+	realRoot, err := filepath.EvalSymlinks(absDir)
+	if err != nil {
+		// 根目录尚不存在（无软链可解析）→ 放行，交给 MkdirAll 按需创建真实目录。
+		return nil
+	}
+
+	// 循环必然终止，无需不动点兜底：每轮 ancestor 严格变短，要么越界后由下面的 ".."
+	// 分支退出，要么下降到 absDir 自身——absDir 必然存在（EvalSymlinks 刚成功），于是
+	// 在 Lstat 成功分支退出。即便 absDir 在此期间被删除，下一轮 ancestor 升到 absDir
+	// 之上，同样由 ".." 分支退出。
+	ancestor := filepath.Dir(target)
+	for {
+		// 越过 absDir 边界（祖先跑到根目录之上）就停止：根目录之上不属于逃逸判定范围。
+		rel, relErr := filepath.Rel(absDir, ancestor)
+		if relErr != nil || rel == ".." || strings.HasPrefix(rel, ".."+string(filepath.Separator)) {
+			return nil
+		}
+		if _, statErr := os.Lstat(ancestor); statErr == nil {
+			real, evErr := filepath.EvalSymlinks(ancestor)
+			if evErr != nil {
+				return fmt.Errorf("解析路径 %q 失败: %w", ancestor, evErr)
+			}
+			back, bErr := filepath.Rel(realRoot, real)
+			if bErr != nil || back == ".." || strings.HasPrefix(back, ".."+string(filepath.Separator)) {
+				return fmt.Errorf("路径 %q 经符号链接逃逸出本地根目录", target)
+			}
+			return nil
+		}
+		ancestor = filepath.Dir(ancestor)
+	}
+}
+
+// md5File 计算文件内容的 MD5，并按 base64 编码返回（与钉盘 list_files 返回的
+// md5 字段编码一致，便于直接字符串比较）。变量形式只用于测试确定性注入读取失败；
+// 测试必须通过 testseam.Swap 替换并自动恢复。
+var md5File = func(path string) (string, error) {
+	f, err := os.Open(path)
+	if err != nil {
+		return "", err
+	}
+	defer f.Close()
+
+	h := md5.New()
+	if _, err := io.Copy(h, f); err != nil {
+		return "", err
+	}
+	return base64.StdEncoding.EncodeToString(h.Sum(nil)), nil
+}
+
+// statusRootLstat 是根类型校验的注入 seam；测试通过 testseam.Swap 注入不同的
+// FileInfo 来复现 Windows 上无法创建的符号链接场景。
+var statusRootLstat = os.Lstat
+
+// statusWalkDir 是本地目录遍历的注入 seam。改造根类型校验后，filepath.WalkDir
+// 的错误分支（walkLocalTreeEntry 之外的外层错误）在 macOS/Windows 上都难以自然
+// 触发，需要 seam 让该分支可以确定性回归。
+var statusWalkDir = filepath.WalkDir
+
+// walkLocalTree 递归遍历本地目录，只收集常规文件（跳过符号链接、设备文件等）。
+// rel_path 统一使用 / 作为分隔符，相对于 root。
+//
+// 这里只记录路径与 mtime，不计算 MD5：本地 hash 采用惰性策略，仅在文件双端
+// 都存在且非 quick 模式时，由 compareTrees 按需计算（见 judgeFileMatch）。
+func walkLocalTree(root string) (map[string]*localFile, error) {
+	// filepath.WalkDir 不会跟随根本身的符号链接：若 root 是指向目录的 symlink，
+	// WalkDir 只以 symlink 身份触发一次回调，随后 !IsRegular 分支静默跳过，最终
+	// 返回空索引，让 status 把所有远端文件报成 new_remote。fail-closed 于遍历前：
+	// 根必须是真实目录，任何其它类型都必须报错。
+	info, err := statusRootLstat(root)
+	if err != nil {
+		return nil, fmt.Errorf("读取本地根目录身份失败: %w", err)
+	}
+	if info.Mode()&os.ModeSymlink != 0 {
+		return nil, fmt.Errorf("本地根目录 %q 是符号链接，请传入真实目录路径", root)
+	}
+	if !info.IsDir() {
+		return nil, fmt.Errorf("本地根目录 %q 不是目录", root)
+	}
+	files := make(map[string]*localFile)
+	err = statusWalkDir(root, func(path string, d fs.DirEntry, err error) error {
+		return walkLocalTreeEntry(root, path, d, err, files)
+	})
+	if err != nil {
+		return nil, err
+	}
+	return files, nil
+}
+
+// runDriveStatusWalkLocalTree 仅作为 runDriveStatus 扫描失败分支的确定性测试 seam；
+// 测试必须通过 testseam.Swap 替换并自动恢复。
+var runDriveStatusWalkLocalTree = walkLocalTree
+
+// walkLocalTreeEntry 是 walkLocalTree 的单条目处理逻辑。抽成命名函数只为可测：
+// Info() / filepath.Rel 的失败在真实 WalkDir 下几乎不可复现，单测可直接注入。
+func walkLocalTreeEntry(root, path string, d fs.DirEntry, err error, files map[string]*localFile) error {
+	if err != nil {
+		return err
+	}
+	if d.IsDir() {
+		return nil
+	}
+	info, err := d.Info()
+	if err != nil {
+		return err
+	}
+	// 只比对常规文件；符号链接、设备文件等被忽略。
+	if !info.Mode().IsRegular() {
+		return nil
+	}
+	rel, err := filepath.Rel(root, path)
+	if err != nil {
+		return err
+	}
+	relSlash := filepath.ToSlash(rel)
+
+	files[relSlash] = &localFile{
+		RelPath:       relSlash,
+		AbsPath:       path,
+		Size:          info.Size(),
+		ModTimeMillis: info.ModTime().UnixMilli(),
+	}
+	return nil
+}
+
+// 双端都存在文件的比对结论。
+const (
+	matchUnchanged = "unchanged"
+	matchModified  = "modified"
+	matchUnknown   = "unknown" // exact 模式且远端无可靠 md5，内容无法核对
+)
+
+// judgeFileMatch 判定双端都存在的文件本次的比对结论：unchanged / modified / unknown。
+//
+// exact 模式下，本地 MD5 在此处按需计算——只有走到这里的文件才是双端都存在的，
+// local-only 文件不会触发 hash 计算。若远端未返回 md5（list_files 目前通常如此），
+// 无法核对内容，则返回 unknown：不判 unchanged（避免把不同内容误报为未变更），
+// 也不硬判 modified（避免把相同内容误报为已变更），让降级如实反映在输出中。
+func judgeFileMatch(lf *localFile, rf *remoteFile, quick bool) (string, error) {
+	if quick {
+		// quick：远端时间戳必须可信且与本地 mtime 相等才算 unchanged；
+		// 远端时间缺失/非法时走保守路径记为 modified。
+		if rf.ModifiedTimeValid && lf.ModTimeMillis == rf.ModifiedTime {
+			return matchUnchanged, nil
+		}
+		return matchModified, nil
+	}
+
+	// exact：远端缺少可靠 md5 时无法核对内容 → unknown（既不判 unchanged 也不判 modified）。
+	if rf.Hash == "" {
+		return matchUnknown, nil
+	}
+
+	// exact：按需计算本地 MD5（base64），再与远端 md5（钉盘也返回 base64）直接比较。
+	if lf.Hash == "" {
+		h, err := md5File(lf.AbsPath)
+		if err != nil {
+			return "", fmt.Errorf("计算 %s 的 MD5 失败: %w", lf.RelPath, err)
+		}
+		lf.Hash = h
+	}
+	if lf.Hash == rf.Hash {
+		return matchUnchanged, nil
+	}
+	return matchModified, nil
+}
+
+// compareTrees 比较本地与云端文件树，产出五类差异。
+func compareTrees(local map[string]*localFile, remote map[string]*remoteFile, detection string, quick bool) (driveStatusResult, error) {
+	res := driveStatusResult{
+		Detection: detection,
+		NewLocal:  []driveStatusEntry{},
+		NewRemote: []driveStatusEntry{},
+		Modified:  []driveStatusEntry{},
+		Unchanged: []driveStatusEntry{},
+		Unknown:   []driveStatusEntry{},
+	}
+
+	for rel, lf := range local {
+		rf, ok := remote[rel]
+		if !ok {
+			res.NewLocal = append(res.NewLocal, driveStatusEntry{RelPath: rel})
+			continue
+		}
+		verdict, err := judgeFileMatch(lf, rf, quick)
+		if err != nil {
+			return res, err
+		}
+		switch verdict {
+		case matchUnchanged:
+			res.Unchanged = append(res.Unchanged, driveStatusEntry{RelPath: rel})
+		case matchUnknown:
+			res.Unknown = append(res.Unknown, driveStatusEntry{RelPath: rel})
+		default:
+			res.Modified = append(res.Modified, driveStatusEntry{RelPath: rel})
+		}
+	}
+	for rel := range remote {
+		if _, ok := local[rel]; !ok {
+			res.NewRemote = append(res.NewRemote, driveStatusEntry{RelPath: rel})
+		}
+	}
+
+	sortEntries(res.NewLocal)
+	sortEntries(res.NewRemote)
+	sortEntries(res.Modified)
+	sortEntries(res.Unchanged)
+	sortEntries(res.Unknown)
+	return res, nil
+}
+
+func sortEntries(entries []driveStatusEntry) {
+	sort.Slice(entries, func(i, j int) bool { return entries[i].RelPath < entries[j].RelPath })
+}
+
+func runDriveStatus(cmd *cobra.Command, _ []string) error {
+	if err := validateRequiredFlags(cmd, "local-folder", "remote-folder"); err != nil {
+		return err
+	}
+	localDir := mustGetFlag(cmd, "local-folder")
+	// remote-folder 必传：待比对的云端根文件夹 dentryUuid。
+	remoteDirID := mustGetFlag(cmd, "remote-folder")
+	// space-id 可选：不传则由 fetchRemoteDriveTree 使用「我的文件」对应的空间。
+	spaceID := mustGetFlag(cmd, "space-id")
+
+	quick, _ := cmd.Flags().GetBool("quick")
+	detection := "exact"
+	if quick {
+		detection = "quick"
+	}
+
+	absDir, err := validateLocalDirAbs(localDir)
+	if err != nil {
+		return err
+	}
+
+	local, err := runDriveStatusWalkLocalTree(absDir)
+	if err != nil {
+		return fmt.Errorf("扫描本地目录失败: %w", err)
+	}
+
+	ctx := cmd.Context()
+	remoteIndex, err := fetchRemoteDriveTree(ctx, spaceID, remoteDirID, quick)
+	if err != nil {
+		return err
+	}
+
+	result, err := compareTrees(local, remoteIndex, detection, quick)
+	if err != nil {
+		return err
+	}
+	return deps.Out.PrintJSON(result)
+}

internal/helpers/drive_status_coverage_test.go

@@ -0,0 +1,418 @@
+package helpers
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"io"
+	"io/fs"
+	"os"
+	"path/filepath"
+	"runtime"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition"
+	"github.com/spf13/cobra"
+)
+
+// ──────────────────────────────────────────────────────────
+// driveScriptCaller — 可编程 MCP mock：按 (toolName, 第几次调用) 决定返回，
+// 覆盖分页、递归、错误分支等 walkRemoteDir / runDriveStatus 路径。
+// ──────────────────────────────────────────────────────────
+
+type driveScriptCaller struct {
+	calls  []driveMCPCall
+	reply  func(toolName string, args map[string]any, nth int) (string, error)
+	dryRun bool
+}
+
+func (m *driveScriptCaller) CallTool(_ context.Context, _ string, toolName string, args map[string]any) (*edition.ToolResult, error) {
+	nth := 0
+	for _, c := range m.calls {
+		if c.toolName == toolName {
+			nth++
+		}
+	}
+	m.calls = append(m.calls, driveMCPCall{toolName: toolName, args: args})
+	text, err := m.reply(toolName, args, nth)
+	if err != nil {
+		return nil, err
+	}
+	return &edition.ToolResult{Content: []edition.ContentBlock{{Type: "text", Text: text}}}, nil
+}
+
+func (m *driveScriptCaller) CallReadTool(ctx context.Context, productID, toolName string, args map[string]any) (*edition.ToolResult, error) {
+	return m.CallTool(ctx, productID, toolName, args)
+}
+
+func (m *driveScriptCaller) Format() string { return "raw" }
+func (m *driveScriptCaller) DryRun() bool   { return m.dryRun }
+func (m *driveScriptCaller) Fields() string { return "" }
+func (m *driveScriptCaller) JQ() string     { return "" }
+
+func (m *driveScriptCaller) callsFor(tool string) []driveMCPCall {
+	var out []driveMCPCall
+	for _, c := range m.calls {
+		if c.toolName == tool {
+			out = append(out, c)
+		}
+	}
+	return out
+}
+
+var errTestList = errors.New("list_files boom")
+
+// runDriveCmd 以给定 caller 执行 `dws drive <args...>`。
+//
+// pull / push / sync 声明了 Safety.Confirmation = user_required，非交互环境下必须带
+// --yes 才能越过统一确认门；这里自动补上，让用例专注被测行为。要断言「未确认即拒绝」
+// 请改用 runDriveCmdWithoutConfirm。
+func runDriveCmd(t *testing.T, caller edition.ToolCaller, args ...string) error {
+	t.Helper()
+	switch {
+	case len(args) == 0:
+	case args[0] == "pull", args[0] == "push", args[0] == "sync":
+		args = append(args, "--yes")
+	}
+	return runDriveCmdWithoutConfirm(t, caller, args...)
+}
+
+// runDriveCmdWithoutConfirm 原样执行，不补 --yes，用于验证确认门本身。
+func runDriveCmdWithoutConfirm(t *testing.T, caller edition.ToolCaller, args ...string) error {
+	t.Helper()
+
+	testseam.Swap(t, &deps, &Deps{Caller: caller, Out: &Formatter{w: io.Discard}})
+
+	root := &cobra.Command{Use: "dws"}
+	root.PersistentFlags().BoolP("yes", "y", false, "")
+	root.PersistentFlags().Bool("dry-run", false, "")
+	root.AddCommand(newDriveCommand())
+
+	testseam.Swap(t, &os.Args, append([]string{"dws", "drive"}, args...))
+	root.SetArgs(append([]string{"drive"}, args...))
+	return root.Execute()
+}
+
+// ──────────────────────────────────────────────────────────
+// runDriveStatus — 端到端：本地 + 远端树 → diff
+// ──────────────────────────────────────────────────────────
+
+// 端到端 status：递归进入子文件夹、拼接 rel_path、跳过非 file 类型。
+func TestCrossPlatformCoverageDriveStatus_endToEndNestedTree(t *testing.T) {
+	dir := t.TempDir()
+	mustWrite(t, filepath.Join(dir, "root.txt"), "r")
+	if err := os.MkdirAll(filepath.Join(dir, "sub"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	mustWrite(t, filepath.Join(dir, "sub", "nested.txt"), "n")
+
+	caller := &driveScriptCaller{reply: func(_ string, args map[string]any, _ int) (string, error) {
+		switch args["parentId"] {
+		case "ROOT":
+			return `{"result":{"items":[` +
+				`{"name":"root.txt","type":"file","fileId":"R1","modifyTime":1000},` +
+				`{"name":"sub","type":"folder","fileId":"SUB"},` +
+				`{"name":"online.adoc","type":"document","fileId":"D1"}` +
+				`],"nextToken":""}}`, nil
+		case "SUB":
+			return `{"result":{"items":[{"name":"nested.txt","type":"file","fileId":"N1","modifyTime":2000}],"nextToken":""}}`, nil
+		}
+		return `{"result":{"items":[],"nextToken":""}}`, nil
+	}}
+
+	if err := runDriveCmd(t, caller, "status", "--local-folder", dir, "--remote-folder", "ROOT", "--quick"); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	// 递归进入 sub 一次；不属于文件夹镜像范围的在线文档不产生额外调用。
+	if got := len(caller.callsFor("list_files")); got != 2 {
+		t.Errorf("expected 2 list_files calls (ROOT + SUB), got %d", got)
+	}
+}
+
+// 分页 token 未推进意味着远端清单可能被截断，必须失败而不是把当前页当作 EOF。
+func TestCrossPlatformCoverageDriveStatus_stalledPaginationTokenFailsClosed(t *testing.T) {
+	dir := t.TempDir()
+
+	caller := &driveScriptCaller{reply: func(_ string, args map[string]any, nth int) (string, error) {
+		switch nth {
+		case 0:
+			if _, ok := args["nextToken"]; ok {
+				t.Error("first page must not carry nextToken")
+			}
+			return `{"result":{"items":[{"name":"a.txt","type":"file","fileId":"A"}],"nextToken":"T1"}}`, nil
+		case 1:
+			if args["nextToken"] != "T1" {
+				t.Errorf("second page nextToken = %v, want T1", args["nextToken"])
+			}
+			// 返回同一个 token → 未推进，必须 fail closed。
+			return `{"result":{"items":[{"name":"b.txt","type":"file","fileId":"B"}],"nextToken":"T1"}}`, nil
+		}
+		return `{"result":{"items":[],"nextToken":""}}`, nil
+	}}
+
+	err := runDriveCmd(t, caller, "status", "--local-folder", dir, "--remote-folder", "ROOT", "--quick")
+	if err == nil || !strings.Contains(err.Error(), "分页 token") {
+		t.Fatalf("error = %v, want stalled pagination failure", err)
+	}
+	if got := len(caller.callsFor("list_files")); got != 2 {
+		t.Fatalf("stalled token must fail after 2 calls, got %d", got)
+	}
+}
+
+// space-id 显式传入时必须透传到 list_files。
+func TestCrossPlatformCoverageDriveStatus_passesSpaceID(t *testing.T) {
+	dir := t.TempDir()
+	caller := &driveScriptCaller{reply: func(_ string, _ map[string]any, _ int) (string, error) {
+		return `{"result":{"items":[],"nextToken":""}}`, nil
+	}}
+	if err := runDriveCmd(t, caller, "status", "--local-folder", dir, "--remote-folder", "ROOT", "--space-id", "SP1"); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if got := caller.callsFor("list_files")[0].args["spaceId"]; got != "SP1" {
+		t.Errorf("spaceId = %v, want SP1", got)
+	}
+}
+
+// list_files 失败 → status 直接报错。
+func TestCrossPlatformCoverageDriveStatus_listFailurePropagates(t *testing.T) {
+	dir := t.TempDir()
+	caller := &driveScriptCaller{reply: func(string, map[string]any, int) (string, error) { return "", errTestList }}
+	if err := runDriveCmd(t, caller, "status", "--local-folder", dir, "--remote-folder", "ROOT"); err == nil {
+		t.Fatal("expected list_files error to propagate")
+	}
+}
+
+// 返回体无法解析 → status 报解析失败。
+func TestCrossPlatformCoverageDriveStatus_unparsableListPropagates(t *testing.T) {
+	dir := t.TempDir()
+	caller := &driveScriptCaller{reply: func(string, map[string]any, int) (string, error) {
+		return `{"result":"not-a-list"}`, nil
+	}}
+	err := runDriveCmd(t, caller, "status", "--local-folder", dir, "--remote-folder", "ROOT")
+	if err == nil || !strings.Contains(err.Error(), "list_files") {
+		t.Fatalf("expected list_files parse error, got %v", err)
+	}
+}
+
+// exact 模式下本地文件不可读 → MD5 计算失败要作为错误上抛，不能静默当成一致。
+func TestCrossPlatformCoverageDriveStatus_unreadableLocalFileFailsExactCompare(t *testing.T) {
+	dir := t.TempDir()
+	p := filepath.Join(dir, "secret.txt")
+	mustWrite(t, p, "data")
+	testseam.Swap(t, &md5File, func(string) (string, error) {
+		return "", errors.New("MD5 boom")
+	})
+
+	caller := &driveScriptCaller{reply: func(_ string, _ map[string]any, _ int) (string, error) {
+		return `{"result":{"items":[{"name":"secret.txt","type":"file","fileId":"S","md5":"abc"}],"nextToken":""}}`, nil
+	}}
+	err := runDriveCmd(t, caller, "status", "--local-folder", dir, "--remote-folder", "ROOT")
+	if err == nil || !strings.Contains(err.Error(), "MD5") {
+		t.Fatalf("expected MD5 failure, got %v", err)
+	}
+}
+
+func TestCrossPlatformCoverageDriveStatus_walkLocalFailurePropagates(t *testing.T) {
+	dir := t.TempDir()
+	testseam.Swap(t, &runDriveStatusWalkLocalTree, func(string) (map[string]*localFile, error) {
+		return nil, errors.New("walk boom")
+	})
+	caller := &driveScriptCaller{reply: func(string, map[string]any, int) (string, error) {
+		t.Error("local scan failure must abort before MCP calls")
+		return "", nil
+	}}
+	err := runDriveCmd(t, caller, "status", "--local-folder", dir, "--remote-folder", "ROOT")
+	if err == nil || !strings.Contains(err.Error(), "扫描本地目录失败") {
+		t.Fatalf("expected local scan failure, got %v", err)
+	}
+}
+
+// --local-folder 不是绝对路径 → 校验拦下，不发起任何 MCP 调用。
+func TestCrossPlatformCoverageDriveStatus_relativeLocalFolderRejected(t *testing.T) {
+	caller := &driveScriptCaller{reply: func(string, map[string]any, int) (string, error) {
+		t.Error("must not call MCP when --local-folder is rejected")
+		return "", nil
+	}}
+	if err := runDriveCmd(t, caller, "status", "--local-folder", "relative/path", "--remote-folder", "ROOT"); err == nil {
+		t.Fatal("expected relative --local-folder to be rejected")
+	}
+}
+
+// ──────────────────────────────────────────────────────────
+// walkRemoteDir — 深度上限
+// ──────────────────────────────────────────────────────────
+
+// 远端目录自引用时深度上限必须中止遍历，避免无限递归。
+func TestCrossPlatformCoverageWalkRemoteDir_depthLimitAborts(t *testing.T) {
+	caller := &driveScriptCaller{reply: func(_ string, _ map[string]any, _ int) (string, error) {
+		// 每层都返回一个同名子文件夹 → 无限深。
+		return `{"result":{"items":[{"name":"loop","type":"folder","fileId":"LOOP"}],"nextToken":""}}`, nil
+	}}
+	testseam.Swap(t, &deps, &Deps{Caller: caller, Out: &Formatter{w: io.Discard}})
+	testseam.Swap(t, &os.Args, []string{"dws", "drive"}) // 工具路由需要命令上下文
+
+	_, err := fetchRemoteDriveTree(context.Background(), "", "ROOT", true)
+	if err == nil || !strings.Contains(err.Error(), "循环引用") {
+		t.Fatalf("expected depth-limit abort, got %v", err)
+	}
+}
+
+// ──────────────────────────────────────────────────────────
+// isSafeRemoteSegment / resolveLocalTarget 的剩余分支
+// ──────────────────────────────────────────────────────────
+
+func TestCrossPlatformCoverageIsSafeRemoteSegment_volumeAndNonCanonical(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		if isSafeRemoteSegment(`C:name.txt`) {
+			t.Error("volume-qualified name must be rejected")
+		}
+	}
+	// 非规范形式（Clean 后不等于自身）必须拒绝。
+	for _, name := range []string{"./a.txt", "a/../b.txt", "a//b.txt"} {
+		if isSafeRemoteSegment(name) {
+			t.Errorf("non-canonical %q must be rejected", name)
+		}
+	}
+}
+
+// ──────────────────────────────────────────────────────────
+// md5File / walkLocalTree 错误分支
+// ──────────────────────────────────────────────────────────
+
+func TestCrossPlatformCoverageMD5File_missingFile(t *testing.T) {
+	if _, err := md5File(filepath.Join(t.TempDir(), "nope.bin")); err == nil {
+		t.Fatal("expected error for missing file")
+	}
+}
+
+func TestCrossPlatformCoverageMD5File_directoryIsNotReadable(t *testing.T) {
+	// 目录不是常规文件：io.Copy 读取时必然报错。
+	if _, err := md5File(t.TempDir()); err == nil {
+		t.Fatal("expected error when hashing a directory")
+	}
+}
+
+func TestCrossPlatformCoverageWalkLocalTree_missingRootErrors(t *testing.T) {
+	if _, err := walkLocalTree(filepath.Join(t.TempDir(), "absent")); err == nil {
+		t.Fatal("expected error for missing local root")
+	}
+}
+
+// 根路径是指向目录的符号链接时，filepath.WalkDir 只把根本身当成一次 !IsRegular
+// 回调静默跳过，结果是空索引，而 status 会把所有远端文件误报为 new_remote。
+// 必须在遍历前 fail-closed。这里通过 seam 注入，兼顾无法真实创建 symlink 的平台。
+func TestCrossPlatformCoverageWalkLocalTree_rejectsSymlinkRootViaSeam(t *testing.T) {
+	testseam.Swap(t, &statusRootLstat, func(string) (os.FileInfo, error) {
+		return fakeSymlinkFileInfo{}, nil
+	})
+	if _, err := walkLocalTree(t.TempDir()); err == nil || !strings.Contains(err.Error(), "符号链接") {
+		t.Fatalf("symlink root must fail closed, got %v", err)
+	}
+}
+
+// 真实 symlink 复现：非 Windows 平台可以直接创建，进一步保证 seam 与真实语义一致。
+func TestCrossPlatformCoverageWalkLocalTree_rejectsSymlinkRootReal(t *testing.T) {
+	target := t.TempDir()
+	link := filepath.Join(t.TempDir(), "root-link")
+	if err := os.Symlink(target, link); err != nil {
+		t.Skipf("symlink unsupported: %v", err)
+	}
+	if _, err := walkLocalTree(link); err == nil || !strings.Contains(err.Error(), "符号链接") {
+		t.Fatalf("symlink root must fail closed, got %v", err)
+	}
+}
+
+// 根类型校验通过后 WalkDir 内部返回的错误必须原样上抛，不能被吞掉；根消失或
+// 权限变更之类的情形在 Linux/Windows runner 上都难以稳定复现，用 seam 注入。
+func TestCrossPlatformCoverageWalkLocalTree_propagatesWalkDirError(t *testing.T) {
+	testseam.Swap(t, &statusWalkDir, func(string, fs.WalkDirFunc) error {
+		return errWalkDirSentinel
+	})
+	dir := t.TempDir()
+	if _, err := walkLocalTree(dir); !errors.Is(err, errWalkDirSentinel) {
+		t.Fatalf("walk dir error must be surfaced, got %v", err)
+	}
+}
+
+var errWalkDirSentinel = errors.New("simulated walk dir failure")
+
+// 根路径既非目录也非符号链接（例如普通文件被误传）时，也必须报错而非空索引。
+func TestCrossPlatformCoverageWalkLocalTree_rejectsNonDirectoryRoot(t *testing.T) {
+	file := filepath.Join(t.TempDir(), "not-a-dir")
+	mustWrite(t, file, "x")
+	if _, err := walkLocalTree(file); err == nil || !strings.Contains(err.Error(), "不是目录") {
+		t.Fatalf("file root must fail closed, got %v", err)
+	}
+}
+
+// fakeSymlinkFileInfo 是一个 Mode()&os.ModeSymlink != 0 的 os.FileInfo。Windows
+// 上创建目录符号链接需要管理员权限，测试通过它绕过创建步骤。
+type fakeSymlinkFileInfo struct{}
+
+func (fakeSymlinkFileInfo) Name() string       { return "root-link" }
+func (fakeSymlinkFileInfo) Size() int64        { return 0 }
+func (fakeSymlinkFileInfo) Mode() os.FileMode  { return os.ModeSymlink | 0o755 }
+func (fakeSymlinkFileInfo) ModTime() time.Time { return time.Time{} }
+func (fakeSymlinkFileInfo) IsDir() bool        { return false }
+func (fakeSymlinkFileInfo) Sys() any           { return nil }
+
+// 非常规文件（FIFO/符号链接目标缺失等）不计入本地索引。
+func TestCrossPlatformCoverageWalkLocalTree_skipsIrregularEntries(t *testing.T) {
+	dir := t.TempDir()
+	mustWrite(t, filepath.Join(dir, "real.txt"), "x")
+	if err := os.Symlink(filepath.Join(dir, "absent"), filepath.Join(dir, "dangling")); err != nil {
+		t.Skipf("symlink unsupported: %v", err)
+	}
+	got, err := walkLocalTree(dir)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if _, ok := got["dangling"]; ok {
+		t.Error("dangling symlink must not be indexed")
+	}
+	if _, ok := got["real.txt"]; !ok {
+		t.Error("regular file must be indexed")
+	}
+}
+
+// ──────────────────────────────────────────────────────────
+// toMillis 的 json.Number / float64 分支
+// ──────────────────────────────────────────────────────────
+
+func TestCrossPlatformCoverageDriveItem_modifiedMillisFromNumericForms(t *testing.T) {
+	if got, ok := (driveItem{"modifyTime": float64(1500)}).modifiedMillis(); !ok || got != 1500 {
+		t.Errorf("float64 modifyTime = (%d,%v), want (1500,true)", got, ok)
+	}
+	if got, ok := (driveItem{"modifyTime": json.Number("2500")}).modifiedMillis(); !ok || got != 2500 {
+		t.Errorf("json.Number modifyTime = (%d,%v), want (2500,true)", got, ok)
+	}
+	if _, ok := (driveItem{"modifyTime": json.Number("nope")}).modifiedMillis(); ok {
+		t.Error("malformed json.Number modifyTime must be invalid")
+	}
+	if _, ok := (driveItem{"modifyTime": float64(0)}).modifiedMillis(); ok {
+		t.Error("non-positive modifyTime must be invalid")
+	}
+	if _, ok := (driveItem{}).modifiedMillis(); ok {
+		t.Error("missing modifyTime must be invalid")
+	}
+}
+
+// fileSize 的 float64 / json.Number 两种形态，以及缺失时的兜底。
+func TestCrossPlatformCoverageDriveItem_sizeForms(t *testing.T) {
+	if got := (driveItem{"fileSize": float64(42)}).size(); got != 42 {
+		t.Errorf("float fileSize = %d, want 42", got)
+	}
+	if got := (driveItem{"fileSize": json.Number("77")}).size(); got != 77 {
+		t.Errorf("json.Number fileSize = %d, want 77", got)
+	}
+	if got := (driveItem{"fileSize": json.Number("not-a-number")}).size(); got != 0 {
+		t.Errorf("malformed json.Number fileSize = %d, want 0", got)
+	}
+	if got := (driveItem{}).size(); got != 0 {
+		t.Errorf("missing fileSize = %d, want 0", got)
+	}
+}

internal/helpers/drive_status_test.go

@@ -0,0 +1,400 @@
+package helpers
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+// ──────────────────────────────────────────────────────────
+// validateLocalDirAbs — 本地路径校验（必须为绝对路径）
+// ──────────────────────────────────────────────────────────
+
+func TestCrossPlatformCoverageValidateLocalDirAbs_empty(t *testing.T) {
+	if _, err := validateLocalDirAbs(""); err == nil {
+		t.Fatal("expected error for empty --local-folder")
+	}
+}
+
+func TestCrossPlatformCoverageValidateLocalDirAbs_relative(t *testing.T) {
+	if _, err := validateLocalDirAbs(filepath.Join(".", "repo")); err == nil {
+		t.Fatal("expected error for relative path")
+	}
+}
+
+func TestCrossPlatformCoverageValidateLocalDirAbs_ok(t *testing.T) {
+	abs := filepath.Join(t.TempDir(), "repo")
+	got, err := validateLocalDirAbs(abs)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if got != filepath.Clean(abs) {
+		t.Errorf("got %q, want %q", got, filepath.Clean(abs))
+	}
+}
+
+// ──────────────────────────────────────────────────────────
+// walkLocalTree — 本地遍历
+// ──────────────────────────────────────────────────────────
+
+func TestCrossPlatformCoverageWalkLocalTree_collectsRegularFiles(t *testing.T) {
+	root := t.TempDir()
+	mustWrite(t, filepath.Join(root, "a.txt"), "hello")
+	mustWrite(t, filepath.Join(root, "sub", "b.txt"), "world")
+
+	files, err := walkLocalTree(root)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if len(files) != 2 {
+		t.Fatalf("expected 2 files, got %d: %v", len(files), files)
+	}
+	// rel_path 用 / 分隔（跨平台一致）
+	if _, ok := files["sub/b.txt"]; !ok {
+		t.Errorf("expected key sub/b.txt, got keys %v", keys(files))
+	}
+	// walk 阶段不计算 hash（惰性策略），但记录 AbsPath 与 mtime
+	if files["a.txt"].Hash != "" {
+		t.Error("walkLocalTree should not compute MD5 eagerly")
+	}
+	if files["a.txt"].AbsPath == "" {
+		t.Error("walkLocalTree should record AbsPath")
+	}
+	if files["a.txt"].ModTimeMillis == 0 {
+		t.Error("walkLocalTree should record mtime")
+	}
+}
+
+// ──────────────────────────────────────────────────────────
+// compareTrees — 四类差异分类
+// ──────────────────────────────────────────────────────────
+
+func TestCrossPlatformCoverageCompareTrees_exact(t *testing.T) {
+	local := map[string]*localFile{
+		"same.txt":   {RelPath: "same.txt", Hash: "h1"},
+		"diff.txt":   {RelPath: "diff.txt", Hash: "local"},
+		"onlyme.txt": {RelPath: "onlyme.txt", Hash: "h3"},
+	}
+	remote := map[string]*remoteFile{
+		"same.txt":     {RelPath: "same.txt", Hash: "h1"},
+		"diff.txt":     {RelPath: "diff.txt", Hash: "remote"},
+		"onlythem.txt": {RelPath: "onlythem.txt", Hash: "h4"},
+	}
+	res, err := compareTrees(local, remote, "exact", false)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	assertPaths(t, "unchanged", res.Unchanged, "same.txt")
+	assertPaths(t, "modified", res.Modified, "diff.txt")
+	assertPaths(t, "new_local", res.NewLocal, "onlyme.txt")
+	assertPaths(t, "new_remote", res.NewRemote, "onlythem.txt")
+	if res.Detection != "exact" {
+		t.Errorf("detection = %q, want exact", res.Detection)
+	}
+}
+
+func TestCrossPlatformCoverageCompareTrees_exact_unknownRemoteHashIsUnknown(t *testing.T) {
+	local := map[string]*localFile{"a.txt": {RelPath: "a.txt", Hash: "h1"}}
+	remote := map[string]*remoteFile{"a.txt": {RelPath: "a.txt", Hash: ""}}
+	res, err := compareTrees(local, remote, "exact", false)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	// 远端无 md5 → 无法核对内容，归入 unknown（既非 unchanged 也非 modified）。
+	assertPaths(t, "unknown", res.Unknown, "a.txt")
+	if len(res.Unchanged) != 0 {
+		t.Error("unknown remote hash must not be judged unchanged")
+	}
+	if len(res.Modified) != 0 {
+		t.Error("unknown remote hash must not be judged modified")
+	}
+}
+
+// TestCompareTrees_exact_hashesOnlyIntersection 验证本地 hash 只在双端都存在时才
+// 计算：local-only 文件即使 AbsPath 指向不存在的文件也不会触发 hash（不报错）。
+func TestCrossPlatformCoverageCompareTrees_exact_hashesOnlyIntersection(t *testing.T) {
+	root := t.TempDir()
+	bothPath := filepath.Join(root, "both.txt")
+	mustWrite(t, bothPath, "same-content")
+	h, err := md5File(bothPath)
+	if err != nil {
+		t.Fatalf("md5File: %v", err)
+	}
+
+	local := map[string]*localFile{
+		"both.txt":  {RelPath: "both.txt", AbsPath: bothPath},
+		"local.txt": {RelPath: "local.txt", AbsPath: filepath.Join(root, "does-not-exist.txt")},
+	}
+	remote := map[string]*remoteFile{
+		"both.txt": {RelPath: "both.txt", Hash: h},
+	}
+	res, err := compareTrees(local, remote, "exact", false)
+	if err != nil {
+		t.Fatalf("local-only file must not be hashed, got error: %v", err)
+	}
+	assertPaths(t, "unchanged", res.Unchanged, "both.txt")
+	assertPaths(t, "new_local", res.NewLocal, "local.txt")
+	// 双端都存在的 both.txt 被惰性 hash 后应回填 Hash
+	if local["both.txt"].Hash == "" {
+		t.Error("intersection file should have been hashed lazily")
+	}
+	if local["local.txt"].Hash != "" {
+		t.Error("local-only file should never be hashed")
+	}
+}
+
+// TestCompareTrees_exact_noRemoteMD5AllUnknown 验证 exact 模式在远端无 md5 时
+// 一律归入 unknown——不再用 fileSize + modified_time 近似判 unchanged（否则大小与
+// mtime 恰好相同但内容不同的文件会被误报为未变更），无论大小/时间是否相同。
+func TestCrossPlatformCoverageCompareTrees_exact_noRemoteMD5AllUnknown(t *testing.T) {
+	local := map[string]*localFile{
+		"sameSizeTime.txt": {RelPath: "sameSizeTime.txt", Size: 100, ModTimeMillis: 1000},
+		"diffsize.txt":     {RelPath: "diffsize.txt", Size: 100, ModTimeMillis: 1000},
+		"difftime.txt":     {RelPath: "difftime.txt", Size: 100, ModTimeMillis: 1000},
+	}
+	remote := map[string]*remoteFile{
+		// 远端均无 md5（Hash 空）→ 全部 unknown，绝不判 unchanged。
+		"sameSizeTime.txt": {RelPath: "sameSizeTime.txt", Size: 100, ModifiedTime: 1000, ModifiedTimeValid: true},
+		"diffsize.txt":     {RelPath: "diffsize.txt", Size: 200, ModifiedTime: 1000, ModifiedTimeValid: true},
+		"difftime.txt":     {RelPath: "difftime.txt", Size: 100, ModifiedTime: 2000, ModifiedTimeValid: true},
+	}
+	res, err := compareTrees(local, remote, "exact", false)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	assertPaths(t, "unknown", res.Unknown, "diffsize.txt", "difftime.txt", "sameSizeTime.txt")
+	if len(res.Unchanged) != 0 {
+		t.Errorf("远端无 md5 时不应有 unchanged, got %v", entryPaths(res.Unchanged))
+	}
+	if len(res.Modified) != 0 {
+		t.Errorf("远端无 md5 时不应有 modified, got %v", entryPaths(res.Modified))
+	}
+}
+
+// TestCompareTrees_exact_base64RemoteMD5 验证 exact 用 base64 md5 比对：本地按
+// base64 算 md5，与钉盘返回的 base64 md5 直接相等 → unchanged。
+func TestCrossPlatformCoverageCompareTrees_exact_base64RemoteMD5(t *testing.T) {
+	root := t.TempDir()
+	p := filepath.Join(root, "a.txt")
+	mustWrite(t, p, "hello root\n") // 11 字节，md5 base64 = 6y9K7B0b2K0AInNZZV/70A==
+	remoteB64 := "6y9K7B0b2K0AInNZZV/70A=="
+	local := map[string]*localFile{"a.txt": {RelPath: "a.txt", AbsPath: p}}
+	remote := map[string]*remoteFile{"a.txt": {RelPath: "a.txt", Hash: remoteB64}}
+	res, err := compareTrees(local, remote, "exact", false)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	assertPaths(t, "unchanged", res.Unchanged, "a.txt")
+	if len(res.Modified) != 0 {
+		t.Errorf("同一 md5(base64) 不应判 modified, got modified=%d", len(res.Modified))
+	}
+	// 本地按需 hash 后应回填为 base64
+	if local["a.txt"].Hash != remoteB64 {
+		t.Errorf("本地 md5 应回填为 base64 %q, got %q", remoteB64, local["a.txt"].Hash)
+	}
+}
+
+func TestCrossPlatformCoverageCompareTrees_quick(t *testing.T) {
+	local := map[string]*localFile{
+		"eq.txt":  {RelPath: "eq.txt", ModTimeMillis: 1000},
+		"ne.txt":  {RelPath: "ne.txt", ModTimeMillis: 1000},
+		"bad.txt": {RelPath: "bad.txt", ModTimeMillis: 1000},
+	}
+	remote := map[string]*remoteFile{
+		"eq.txt":  {RelPath: "eq.txt", ModifiedTime: 1000, ModifiedTimeValid: true},
+		"ne.txt":  {RelPath: "ne.txt", ModifiedTime: 2000, ModifiedTimeValid: true},
+		"bad.txt": {RelPath: "bad.txt", ModifiedTime: 1000, ModifiedTimeValid: false},
+	}
+	res, err := compareTrees(local, remote, "quick", true)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	assertPaths(t, "unchanged", res.Unchanged, "eq.txt")
+	// ne.txt 时间不等、bad.txt 远端时间不可信 → 都记为 modified
+	assertPaths(t, "modified", res.Modified, "bad.txt", "ne.txt")
+}
+
+func TestCrossPlatformCoverageCompareTrees_emptyRemote_allNewLocal(t *testing.T) {
+	local := map[string]*localFile{
+		"a.txt": {RelPath: "a.txt", Hash: "h1"},
+		"b.txt": {RelPath: "b.txt", Hash: "h2"},
+	}
+	res, err := compareTrees(local, map[string]*remoteFile{}, "exact", false)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	assertPaths(t, "new_local", res.NewLocal, "a.txt", "b.txt")
+	if len(res.NewRemote) != 0 || len(res.Modified) != 0 || len(res.Unchanged) != 0 {
+		t.Error("with empty remote, only new_local should be populated")
+	}
+}
+
+// ──────────────────────────────────────────────────────────
+// helpers
+// ──────────────────────────────────────────────────────────
+
+func mustWrite(t *testing.T, path, content string) {
+	t.Helper()
+	if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+		t.Fatalf("mkdir: %v", err)
+	}
+	if err := os.WriteFile(path, []byte(content), 0o644); err != nil {
+		t.Fatalf("write %s: %v", path, err)
+	}
+}
+
+func keys(m map[string]*localFile) []string {
+	out := make([]string, 0, len(m))
+	for k := range m {
+		out = append(out, k)
+	}
+	return out
+}
+
+func assertPaths(t *testing.T, label string, entries []driveStatusEntry, want ...string) {
+	t.Helper()
+	if len(entries) != len(want) {
+		t.Fatalf("%s: got %d entries %v, want %v", label, len(entries), entryPaths(entries), want)
+	}
+	for i, w := range want {
+		if entries[i].RelPath != w {
+			t.Errorf("%s[%d] = %q, want %q", label, i, entries[i].RelPath, w)
+		}
+	}
+}
+
+func entryPaths(entries []driveStatusEntry) []string {
+	out := make([]string, len(entries))
+	for i, e := range entries {
+		out[i] = e.RelPath
+	}
+	return out
+}
+
+// ──────────────────────────────────────────────────────────
+// parseDriveList — list_files 返回解析
+// ──────────────────────────────────────────────────────────
+
+func TestCrossPlatformCoverageParseDriveList_resultItems(t *testing.T) {
+	text := `{"result":{"items":[{"name":"a.txt","type":"file"},{"name":"sub","type":"folder"}],"nextToken":"tok"}}`
+	items, token, err := parseDriveList(text)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if len(items) != 2 {
+		t.Fatalf("expected 2 items, got %d", len(items))
+	}
+	if token != "tok" {
+		t.Errorf("token = %q, want tok", token)
+	}
+}
+
+func TestCrossPlatformCoverageParseDriveList_topLevelArray(t *testing.T) {
+	text := `{"result":[{"name":"a.txt","type":"file"}]}`
+	items, token, err := parseDriveList(text)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if len(items) != 1 || items[0].name() != "a.txt" {
+		t.Errorf("unexpected items: %v", items)
+	}
+	if token != "" {
+		t.Errorf("expected empty token, got %q", token)
+	}
+}
+
+func TestCrossPlatformCoverageParseDriveList_invalid(t *testing.T) {
+	if _, _, err := parseDriveList("not json"); err == nil {
+		t.Fatal("expected error for invalid JSON")
+	}
+}
+
+// ──────────────────────────────────────────────────────────
+// driveItem — 字段访问器（带 fallback）
+// ──────────────────────────────────────────────────────────
+
+func TestCrossPlatformCoverageDriveItem_accessors(t *testing.T) {
+	it := driveItem{
+		"name":       "报告.pdf",
+		"type":       "file",
+		"fileId":     "d-123",
+		"md5":        "abc",
+		"path":       "/dir/报告.pdf",
+		"modifyTime": float64(1700000000000),
+	}
+	if it.name() != "报告.pdf" {
+		t.Errorf("name() = %q", it.name())
+	}
+	if it.id() != "d-123" {
+		t.Errorf("id() = %q", it.id())
+	}
+	if it.typ() != "file" {
+		t.Errorf("typ() = %q, want file", it.typ())
+	}
+	if it.hash() != "abc" {
+		t.Errorf("hash() = %q", it.hash())
+	}
+	if it.path() != "/dir/报告.pdf" {
+		t.Errorf("path() = %q", it.path())
+	}
+	if it.isFolder() {
+		t.Error("type=file should not be a folder")
+	}
+	if !it.isFile() {
+		t.Error("type=file should be a file")
+	}
+	ms, ok := it.modifiedMillis()
+	if !ok || ms != 1700000000000 {
+		t.Errorf("modifiedMillis() = %d,%v", ms, ok)
+	}
+}
+
+func TestCrossPlatformCoverageDriveItem_folderAndFile(t *testing.T) {
+	folder := driveItem{"name": "sub", "type": "folder"}
+	if !folder.isFolder() || folder.isFile() {
+		t.Error("type=folder should be folder, not file")
+	}
+	file := driveItem{"name": "a.txt", "type": "file"}
+	if !file.isFile() || file.isFolder() {
+		t.Error("type=file should be file, not folder")
+	}
+	// 非 file / 非 folder 的类型（在线文档、快捷方式等）都不纳入比对。
+	doc := driveItem{"name": "设计稿", "type": "docx"}
+	if doc.isFile() {
+		t.Error("docx should not be treated as file")
+	}
+	shortcut := driveItem{"name": "快捷方式", "type": "shortcut"}
+	if shortcut.isFile() {
+		t.Error("shortcut should not be treated as file")
+	}
+}
+
+// ──────────────────────────────────────────────────────────
+// toMillis — 时间字段归一化
+// ──────────────────────────────────────────────────────────
+
+func TestCrossPlatformCoverageToMillis(t *testing.T) {
+	cases := []struct {
+		name string
+		in   any
+		want int64
+		ok   bool
+	}{
+		{"epoch-ms-number", float64(1700000000000), 1700000000000, true},
+		{"epoch-ms-string", "1700000000000", 1700000000000, true},
+		{"rfc3339", "2023-11-14T22:13:20Z", 1700000000000, true},
+		{"zero", float64(0), 0, false},
+		{"empty", "", 0, false},
+		{"garbage", "not-a-time", 0, false},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			got, ok := toMillis(c.in)
+			if ok != c.ok || (ok && got != c.want) {
+				t.Errorf("toMillis(%v) = %d,%v; want %d,%v", c.in, got, ok, c.want, c.ok)
+			}
+		})
+	}
+}

internal/helpers/drive_status_unix.go

@@ -0,0 +1,8 @@
+//go:build !windows
+
+package helpers
+
+// isSafeRemoteSegmentPlatform 在非 Windows 平台没有额外约束：filepath.VolumeName
+// 恒为空字符串，而调用方已过滤掉 ""、"."、".." 与任意平台分隔符，剩下的名称
+// filepath.Clean 不会再改写。
+func isSafeRemoteSegmentPlatform(string) bool { return true }

internal/helpers/drive_status_windows.go

@@ -0,0 +1,52 @@
+//go:build windows
+
+package helpers
+
+import (
+	"path/filepath"
+	"strings"
+)
+
+// isSafeRemoteSegmentPlatform 承载 Windows 专有的单层名称校验。
+//
+// 除盘符与 Clean 改写外，还拒绝 Win32 非法字符、尾随点/空格以及设备保留名。
+// 这些名称即使不造成词法逃逸，也可能无法落盘、落到 ADS，或与另一个名称映射到
+// 同一 Win32 对象；文件夹镜像必须在构建权威远端树时统一 fail closed。
+func isSafeRemoteSegmentPlatform(name string) bool {
+	if filepath.VolumeName(name) != "" {
+		return false
+	}
+	if filepath.Clean(name) != name {
+		return false
+	}
+	if strings.TrimRight(name, " .") != name {
+		return false
+	}
+	for _, char := range name {
+		if char < 0x20 || char == 0x7f || strings.ContainsRune(`<>:"|?*`, char) {
+			return false
+		}
+	}
+	if isWindowsReservedMirrorName(name) {
+		return false
+	}
+	return true
+}
+
+func isWindowsReservedMirrorName(name string) bool {
+	base := name
+	if index := strings.IndexAny(base, ".:"); index >= 0 {
+		base = base[:index]
+	}
+	base = strings.ToUpper(strings.TrimRight(base, " ."))
+	switch base {
+	case "CON", "PRN", "AUX", "NUL", "CONIN$", "CONOUT$":
+		return true
+	}
+	if len(base) == 4 && (strings.HasPrefix(base, "COM") || strings.HasPrefix(base, "LPT")) && base[3] >= '1' && base[3] <= '9' {
+		return true
+	}
+	runes := []rune(base)
+	return len(runes) == 4 && (strings.HasPrefix(base, "COM") || strings.HasPrefix(base, "LPT")) &&
+		strings.ContainsRune("¹²³", runes[3])
+}

internal/helpers/drive_sync.go

@@ -0,0 +1,684 @@
+package helpers
+
+import (
+	"bufio"
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+
+	"github.com/spf13/cobra"
+)
+
+// keep-both 的本地保留副本通过同一个固定父目录 os.Root 原子建立硬链接；以下 seam
+// 仅用于文件系统失败与并发替换的确定性测试，测试必须通过 testseam.Swap 替换。
+var (
+	syncRootLink          = func(root *os.Root, oldName, newName string) error { return root.Link(oldName, newName) }
+	syncPullOneFilePinned = pullOneFilePinned
+)
+
+// ==========================================================
+// drive sync — 本地与钉盘双向同步（本地 ⇄ Drive）
+// ==========================================================
+// ──────────────────────────────────────────────────────────
+// dws drive sync — 把 --local-folder 与 --remote-folder 做文件级双向同步。
+//
+// 复用 status 的差异判定（exact MD5 / --quick modified_time）先算出 diff，再按方向执行：
+//   new_local   仅本地存在   → push（缺失的远端目录按需创建，再上传）
+//   new_remote  仅钉盘存在   → pull（下载到本地对应路径）
+//   modified    两侧都变更   → 按 --on-conflict 解决：
+//                 skip       默认：两侧都不动并保留两边内容
+//                 remote-wins     ：拉取远端覆盖本地
+//                 local-wins       ：上传本地覆盖远端
+//                 keep-both        ：本地改名保留，再拉取远端到原路径
+//                 ask              ：交互式逐个询问
+//   unknown     exact 模式远端无可靠 md5、内容无法核对 → 跳过（记 skipped，提示改用 --quick）
+//   unchanged   两侧一致                                → 不动
+//
+// 文件级同步——只新增/覆盖，不删除任何一侧的多余文件。summary.failed > 0 时以非零
+// 退出码退出，结构化 summary + diff + items 仍打印在 stdout 上。
+// ──────────────────────────────────────────────────────────
+
+// --on-conflict 的五种冲突解决策略。
+const (
+	syncConflictLocalWins  = "local-wins"  // 上传本地覆盖远端
+	syncConflictRemoteWins = "remote-wins" // 拉取远端覆盖本地
+	syncConflictKeepBoth   = "keep-both"   // 本地改名保留，再拉取远端到原路径
+	syncConflictAsk        = "ask"         // 交互式逐个询问
+	syncConflictSkip       = "skip"        // 默认：两侧都变更时什么都不做，两边内容都保留
+)
+
+// sync 动作分类（direction 标注每条记录属于哪个方向）。
+const (
+	syncDirectionPull     = "pull"
+	syncDirectionPush     = "push"
+	syncDirectionConflict = "conflict"
+
+	syncActionDownloaded    = "downloaded"
+	syncActionUploaded      = "uploaded"
+	syncActionOverwritten   = "overwritten"
+	syncActionFolderCreated = "folder_created"
+	syncActionRenamedLocal  = "renamed_local"
+	syncActionSkipped       = "skipped"
+	syncActionFailed        = "failed"
+)
+
+// driveSyncItem 是输出 items[] 中每条操作的明细。
+type driveSyncItem struct {
+	RelPath   string `json:"rel_path"`
+	Action    string `json:"action"`
+	Direction string `json:"direction,omitempty"`
+	Error     string `json:"error,omitempty"`
+}
+
+// driveSyncSummary 是各方向的计数汇总。
+type driveSyncSummary struct {
+	Pulled  int `json:"pulled"`
+	Pushed  int `json:"pushed"`
+	Skipped int `json:"skipped"`
+	Failed  int `json:"failed"`
+}
+
+// driveSyncDiff 是本次同步前算出的五类差异（与 status 同源）。
+type driveSyncDiff struct {
+	NewLocal  []driveStatusEntry `json:"new_local"`
+	NewRemote []driveStatusEntry `json:"new_remote"`
+	Modified  []driveStatusEntry `json:"modified"`
+	Unchanged []driveStatusEntry `json:"unchanged"`
+	Unknown   []driveStatusEntry `json:"unknown"`
+}
+
+// driveSyncResult 是 sync 命令的输出 schema。
+type driveSyncResult struct {
+	Detection string           `json:"detection"`
+	Diff      driveSyncDiff    `json:"diff"`
+	Summary   driveSyncSummary `json:"summary"`
+	Items     []driveSyncItem  `json:"items"`
+}
+
+type driveSyncDryRunResult struct {
+	DryRun      bool            `json:"dry_run"`
+	Executed    bool            `json:"executed"`
+	PreviewKind string          `json:"preview_kind"`
+	Operation   string          `json:"operation"`
+	Plan        driveSyncResult `json:"plan"`
+}
+
+// driveSyncFailure 在 summary.failed > 0 时返回：结构化结果已打印到 stdout，
+// 这里只负责以 exit=1 退出并向 stderr 输出一行简短说明（与 drivePushFailure 一致）。
+type driveSyncFailure struct{ failed int }
+
+func (e *driveSyncFailure) Error() string {
+	return fmt.Sprintf("drive sync: %d item(s) failed", e.failed)
+}
+func (e *driveSyncFailure) RawStderr() string { return e.Error() }
+func (e *driveSyncFailure) ExitCode() int     { return 1 }
+
+func runDriveSync(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 可选：不传则由底层使用「我的文件」对应的空间。
+	spaceID := mustGetFlag(cmd, "space-id")
+
+	onConflict, _ := cmd.Flags().GetString("on-conflict")
+	if onConflict == "" {
+		// 安全默认：两侧都变更时不擅自覆盖任何一侧。
+		onConflict = syncConflictSkip
+	}
+	switch onConflict {
+	case syncConflictSkip, syncConflictLocalWins, syncConflictRemoteWins, syncConflictKeepBoth, syncConflictAsk:
+	default:
+		return fmt.Errorf("--on-conflict 取值非法: %s（可选 skip|local-wins|remote-wins|keep-both|ask）", onConflict)
+	}
+
+	quick, _ := cmd.Flags().GetBool("quick")
+	detection := "exact"
+	if quick {
+		detection = "quick"
+	}
+
+	absDir, err := validateLocalDirAbs(localDir)
+	if err != nil {
+		return err
+	}
+	pinnedRoot, err := openExistingPinnedPullRoot(absDir)
+	if err != nil {
+		return fmt.Errorf("扫描本地目录失败: %w", err)
+	}
+	defer pinnedRoot.close()
+	// sync 的本地快照与后续 hash / upload / pull 全部绑定到同一个固定根。
+	localDirs, localFiles, err := runDriveMirrorWalkLocalForPushPinned(pinnedRoot)
+	if err != nil {
+		return fmt.Errorf("扫描本地目录失败: %w", err)
+	}
+
+	ctx := cmd.Context()
+
+	// 远端现状：文件（含 hash/mtime/fileId）与目录（rel_path → fileId，"" 即根本身）。
+	remoteFiles, remoteFolders, err := fetchRemoteTreeForPush(ctx, spaceID, remoteDirID)
+	if err != nil {
+		return err
+	}
+	localByRel := make(map[string]localPushFile, len(localFiles))
+	for _, f := range localFiles {
+		localByRel[f.RelPath] = f
+	}
+	preflight := buildMirrorPreflight(localDirs, localFiles, remoteFiles, remoteFolders)
+	addPinnedLocalTargetPreflightFailures(pinnedRoot, remoteFiles, preflight)
+
+	// 在计算 diff 前先识别文件/目录同路径冲突。冲突根及其全部后代都不能再进入
+	// new_local / new_remote 或后续执行阶段，否则会在远端制造同名异类对象，或尝试
+	// 把远端目录内容下载到本地文件之下。
+	typeConflicts := make(map[string]string)
+	for rel, msg := range preflight {
+		typeConflicts[rel] = msg
+	}
+	for _, dir := range localDirs {
+		if msg := pushTypeConflictError(dir, true, remoteFiles, remoteFolders); msg != "" {
+			typeConflicts[dir] = msg
+		}
+	}
+	for rel := range localByRel {
+		if msg := pushTypeConflictError(rel, false, remoteFiles, remoteFolders); msg != "" {
+			typeConflicts[rel] = msg
+		}
+	}
+
+	// 计算 diff：双端都存在的文件复用 judgeFileMatch，保持与 status 完全一致的判定。
+	diff := driveSyncDiff{
+		NewLocal:  []driveStatusEntry{},
+		NewRemote: []driveStatusEntry{},
+		Modified:  []driveStatusEntry{},
+		Unchanged: []driveStatusEntry{},
+		Unknown:   []driveStatusEntry{},
+	}
+	var newLocal, newRemote, modified, unknown []string
+	for rel, pf := range localByRel {
+		if syncPathBlockedByTypeConflict(rel, typeConflicts) {
+			continue
+		}
+		rf, ok := remoteFiles[rel]
+		if !ok {
+			newLocal = append(newLocal, rel)
+			continue
+		}
+		verdict, jerr := judgePinnedPushFileMatch(pinnedRoot, pf, rf, quick)
+		if jerr != nil {
+			return jerr
+		}
+		switch verdict {
+		case matchUnchanged:
+			diff.Unchanged = append(diff.Unchanged, driveStatusEntry{RelPath: rel})
+		case matchUnknown:
+			unknown = append(unknown, rel)
+		default:
+			modified = append(modified, rel)
+		}
+	}
+	for rel := range remoteFiles {
+		if syncPathBlockedByTypeConflict(rel, typeConflicts) {
+			continue
+		}
+		if _, ok := localByRel[rel]; !ok {
+			newRemote = append(newRemote, rel)
+		}
+	}
+	sort.Strings(newLocal)
+	sort.Strings(newRemote)
+	sort.Strings(modified)
+	sort.Strings(unknown)
+	for _, rel := range newLocal {
+		diff.NewLocal = append(diff.NewLocal, driveStatusEntry{RelPath: rel})
+	}
+	for _, rel := range newRemote {
+		diff.NewRemote = append(diff.NewRemote, driveStatusEntry{RelPath: rel})
+	}
+	for _, rel := range modified {
+		diff.Modified = append(diff.Modified, driveStatusEntry{RelPath: rel})
+	}
+	for _, rel := range unknown {
+		diff.Unknown = append(diff.Unknown, driveStatusEntry{RelPath: rel})
+	}
+	sortEntries(diff.Unchanged)
+
+	res := driveSyncResult{Detection: detection, Diff: diff, Items: []driveSyncItem{}}
+	conflictRels := make([]string, 0, len(typeConflicts))
+	for rel := range typeConflicts {
+		conflictRels = append(conflictRels, rel)
+	}
+	sort.Strings(conflictRels)
+	for _, rel := range conflictRels {
+		res.Summary.Failed++
+		res.Items = append(res.Items, driveSyncItem{
+			RelPath: rel, Action: syncActionFailed, Direction: syncDirectionConflict,
+			Error: typeConflicts[rel],
+		})
+	}
+	if err := pinnedRoot.verify(); err != nil {
+		return err
+	}
+
+	// --dry-run：只算差异、不执行任何同步动作。
+	if deps.Caller.DryRun() {
+		return deps.Out.PrintJSON(driveSyncDryRunResult{
+			DryRun: true, Executed: false, PreviewKind: "plan", Operation: "drive sync", Plan: res,
+		})
+	}
+	// 镜像前置检查是整批门禁：发现任一本地非法名称或跨端等价路径歧义后，
+	// sync 不得执行 create/download/upload 等任一写动作。
+	if len(preflight) > 0 {
+		if perr := deps.Out.PrintJSON(res); perr != nil {
+			return perr
+		}
+		return &driveSyncFailure{failed: res.Summary.Failed}
+	}
+
+	// unknown：exact 模式下远端无可靠 md5、内容无法核对，不擅自覆盖任何一侧，记 skipped。
+	for _, rel := range unknown {
+		res.Summary.Skipped++
+		res.Items = append(res.Items, driveSyncItem{
+			RelPath: rel, Action: syncActionSkipped, Direction: syncDirectionConflict,
+			Error: "远端无可靠 md5，内容无法核对，已跳过（可改用 --quick 按 modified_time 比对）",
+		})
+	}
+
+	// ask 模式：先把所有 modified 的解决策略问全，再统一执行，避免边执行边交互。
+	resolutions := make(map[string]string, len(modified))
+	for _, rel := range modified {
+		strategy := onConflict
+		switch strategy {
+		case syncConflictAsk:
+			strategy, err = driveSyncAskConflict(rel)
+			if err != nil {
+				return err
+			}
+		case syncConflictSkip:
+			strategy = "" // 与 ask 选择「跳过」同一条落地路径
+		}
+		resolutions[rel] = strategy
+	}
+	// 交互决策期间本地根也可能被替换；首个双端写动作前再次核对固定身份。
+	if err := pinnedRoot.verify(); err != nil {
+		return err
+	}
+
+	// occupied：keep-both 生成不冲突的本地重命名目标时用，覆盖两侧全部已知路径。
+	occupied := make(map[string]bool)
+	for rel := range localByRel {
+		occupied[rel] = true
+	}
+	for _, d := range localDirs {
+		occupied[d] = true
+	}
+	for rel := range remoteFiles {
+		occupied[rel] = true
+	}
+	for rel := range remoteFolders {
+		if rel != "" {
+			occupied[rel] = true
+		}
+	}
+
+	// 阶段 1：镜像本地目录结构到远端（缺失则创建），保证空目录与 push 目标的父目录先存在。
+	for _, dir := range localDirs {
+		if _, ok := remoteFolders[dir]; ok {
+			continue // 远端已存在，复用 fileId
+		}
+		parentRel, name := splitRel(dir)
+		parentID, ok := remoteFolders[parentRel]
+		if !ok || parentID == "" {
+			res.Summary.Failed++
+			res.Items = append(res.Items, driveSyncItem{RelPath: dir, Action: syncActionFailed, Direction: syncDirectionPush, Error: "父目录未能创建"})
+			continue
+		}
+		if err := pinnedRoot.verify(); err != nil {
+			return err
+		}
+		fid, cerr := pushCreateFolder(ctx, spaceID, parentID, name)
+		if cerr != nil || fid == "" {
+			res.Summary.Failed++
+			msg := "create_folder 未返回 fileId"
+			if cerr != nil {
+				msg = cerr.Error()
+			}
+			res.Items = append(res.Items, driveSyncItem{RelPath: dir, Action: syncActionFailed, Direction: syncDirectionPush, Error: msg})
+			continue
+		}
+		remoteFolders[dir] = fid
+		res.Summary.Pushed++
+		res.Items = append(res.Items, driveSyncItem{RelPath: dir, Action: syncActionFolderCreated, Direction: syncDirectionPush})
+	}
+
+	// 阶段 2：new_remote 下载到本地。
+	for _, rel := range newRemote {
+		syncPullFilePinned(&res, ctx, spaceID, remoteFiles[rel], pinnedRoot, rel, syncDirectionPull)
+	}
+
+	// 阶段 3：new_local 上传到远端。
+	for _, rel := range newLocal {
+		pf := localByRel[rel]
+		syncPushFile(&res, ctx, spaceID, remoteFolders, pinnedRoot, pf, rel, "")
+	}
+
+	// 阶段 4：modified 按 --on-conflict 解决。
+	for _, rel := range modified {
+		pf := localByRel[rel]
+		rf := remoteFiles[rel]
+		switch resolutions[rel] {
+		case syncConflictRemoteWins:
+			syncPullFilePinned(&res, ctx, spaceID, rf, pinnedRoot, rel, syncDirectionPull)
+		case syncConflictLocalWins:
+			syncPushFile(&res, ctx, spaceID, remoteFolders, pinnedRoot, pf, rel, rf.FileID)
+		case syncConflictKeepBoth:
+			syncKeepBothPinned(&res, ctx, spaceID, rf, pinnedRoot, rel, occupied)
+		default: // "" — ask 选择跳过
+			res.Summary.Skipped++
+			res.Items = append(res.Items, driveSyncItem{RelPath: rel, Action: syncActionSkipped, Direction: syncDirectionConflict})
+		}
+	}
+
+	// 结构化结果始终打印到 stdout；有失败则额外以非零退出码退出。
+	if perr := deps.Out.PrintJSON(res); perr != nil {
+		return perr
+	}
+	if res.Summary.Failed > 0 {
+		return &driveSyncFailure{failed: res.Summary.Failed}
+	}
+	return nil
+}
+
+// syncPathBlockedByTypeConflict 判断 rel 本身或任一祖先是否是文件/目录类型冲突根。
+// 祖先检查保证冲突目录下的本地、远端后代不会绕过根路径的 fail-closed 结论。
+func syncPathBlockedByTypeConflict(rel string, conflicts map[string]string) bool {
+	for rel != "" {
+		if _, blocked := conflicts[rel]; blocked {
+			return true
+		}
+		rel, _ = splitRel(rel)
+	}
+	return false
+}
+
+// addPinnedLocalTargetPreflightFailures 从 sync 已固定的本地根核对所有远端落盘点。
+// 每一层既有祖先都必须是真实目录，末段若存在则必须是常规文件；软链即使仍指向根内
+// 也不属于可移植镜像树，必须在任何双端写之前整批拒绝。
+func addPinnedLocalTargetPreflightFailures(root *pinnedPullRoot, remote map[string]*remoteFile, failures map[string]string) {
+	for rel := range remote {
+		if mirrorPreflightFailureForRel(rel, failures) != "" {
+			continue
+		}
+		parts := strings.Split(filepath.FromSlash(rel), string(filepath.Separator))
+		for i := range parts {
+			name := filepath.Join(parts[:i+1]...)
+			info, err := pullRootLstat(root.root, name)
+			if err != nil {
+				if os.IsNotExist(err) {
+					break
+				}
+				failures[rel] = fmt.Sprintf("检查本地目标失败: %v", err)
+				break
+			}
+			if i < len(parts)-1 {
+				if !info.IsDir() {
+					failures[rel] = fmt.Sprintf("本地目标 %q 的祖先 %q 已存在且不是目录，已拒绝镜像", rel, filepath.ToSlash(name))
+					break
+				}
+				continue
+			}
+			if !info.Mode().IsRegular() {
+				failures[rel] = fmt.Sprintf("本地目标 %q 已存在且不是常规文件，已拒绝覆盖", rel)
+			}
+		}
+	}
+}
+
+// syncPullFile 下载单个远端文件到本地 rel 对应路径（总是覆盖，Drive 为该项权威源），
+// 并把结果计入 res。命中大小写/规范化冲突或逃逸的路径记 failed、不落盘。
+func syncPullFile(res *driveSyncResult, ctx context.Context, spaceID string, rf *remoteFile, absDir, rel, direction string) {
+	root, err := openPinnedPullRoot(absDir)
+	if err != nil {
+		res.Summary.Failed++
+		res.Items = append(res.Items, driveSyncItem{RelPath: rel, Action: syncActionFailed, Direction: direction, Error: err.Error()})
+		return
+	}
+	defer root.close()
+	syncPullFilePinned(res, ctx, spaceID, rf, root, rel, direction)
+}
+
+func syncPullFilePinned(res *driveSyncResult, ctx context.Context, spaceID string, rf *remoteFile, root *pinnedPullRoot, rel string, direction string) {
+	action, perr := pullRemoteFilePinned(ctx, spaceID, rf, root, rel, ifExistsOverwrite)
+	if action == pullActionDownloaded {
+		res.Summary.Pulled++
+		res.Items = append(res.Items, driveSyncItem{RelPath: rel, Action: syncActionDownloaded, Direction: direction})
+		return
+	}
+	res.Summary.Failed++
+	item := driveSyncItem{RelPath: rel, Action: syncActionFailed, Direction: direction}
+	if perr != nil {
+		item.Error = perr.Error()
+	}
+	res.Items = append(res.Items, item)
+}
+
+// syncPushFile 上传单个本地文件到远端；overwriteID 非空时走覆盖上传（原地覆盖同名远端文件）。
+func syncPushFile(res *driveSyncResult, ctx context.Context, spaceID string, remoteFolders map[string]string, root *pinnedPullRoot, pf localPushFile, rel, overwriteID string) {
+	parentRel, name := splitRel(rel)
+	parentID, ok := remoteFolders[parentRel]
+	if !ok || parentID == "" {
+		res.Summary.Failed++
+		res.Items = append(res.Items, driveSyncItem{RelPath: rel, Action: syncActionFailed, Direction: syncDirectionPush, Error: "父目录未能创建"})
+		return
+	}
+	if err := pushUploadFilePinned(ctx, spaceID, parentID, overwriteID, name, root, pf); err != nil {
+		res.Summary.Failed++
+		res.Items = append(res.Items, driveSyncItem{RelPath: rel, Action: syncActionFailed, Direction: syncDirectionPush, Error: err.Error()})
+		return
+	}
+	res.Summary.Pushed++
+	action := syncActionUploaded
+	direction := syncDirectionPush
+	if overwriteID != "" {
+		action = syncActionOverwritten
+		direction = syncDirectionConflict
+	}
+	res.Items = append(res.Items, driveSyncItem{RelPath: rel, Action: action, Direction: direction})
+}
+
+// syncKeepBoth 解决 modified 冲突的 keep-both 策略：先为本地文件原子建立带冲突后缀
+// 的 no-clobber 硬链接，再把远端文件拉取到原 rel 路径。拉取失败时保留两个本地名字，
+// 不执行可能误删或覆盖并发文件的回滚。
+func syncKeepBoth(res *driveSyncResult, ctx context.Context, spaceID string, rf *remoteFile, absDir, rel string, occupied map[string]bool) {
+	root, err := openPinnedPullRoot(absDir)
+	if err != nil {
+		res.Summary.Failed++
+		res.Items = append(res.Items, driveSyncItem{RelPath: rel, Action: syncActionFailed, Direction: syncDirectionConflict, Error: err.Error()})
+		return
+	}
+	defer root.close()
+	syncKeepBothPinned(res, ctx, spaceID, rf, root, rel, occupied)
+}
+
+func syncKeepBothPinned(res *driveSyncResult, ctx context.Context, spaceID string, rf *remoteFile, root *pinnedPullRoot, rel string, occupied map[string]bool) {
+	pinned, e1 := root.openTarget(rel)
+	if e1 != nil {
+		res.Summary.Failed++
+		res.Items = append(res.Items, driveSyncItem{RelPath: rel, Action: syncActionFailed, Direction: syncDirectionConflict, Error: e1.Error()})
+		return
+	}
+	defer pinned.close()
+	localInfo, err := pinned.regularTargetInfo()
+	if err != nil {
+		res.Summary.Failed++
+		res.Items = append(res.Items, driveSyncItem{RelPath: rel, Action: syncActionFailed, Direction: syncDirectionConflict, Error: err.Error()})
+		return
+	}
+	if localInfo == nil {
+		res.Summary.Failed++
+		res.Items = append(res.Items, driveSyncItem{RelPath: rel, Action: syncActionFailed, Direction: syncDirectionConflict, Error: "本地保留版本不存在"})
+		return
+	}
+	// Root.Link(original,candidate) 在同一固定父目录中原子 no-clobber 地保留本地版本。
+	// occupied 的精确字符串查重覆盖不到的文件系统等价名称，由 Link 的 EEXIST 兜底。
+	suffixedRel, newName, e2 := reserveSyncKeepBothTargetPinned(pinned, rel, rf.FileID, occupied)
+	if e2 != nil {
+		res.Summary.Failed++
+		res.Items = append(res.Items, driveSyncItem{RelPath: rel, Action: syncActionFailed, Direction: syncDirectionConflict, Error: e2.Error()})
+		return
+	}
+	savedInfo, err := pullRootLstat(pinned.parentRoot, newName)
+	if err != nil || !sameKeepBothVersion(localInfo, savedInfo) {
+		res.Summary.Failed++
+		res.Items = append(res.Items, driveSyncItem{RelPath: rel, Action: syncActionFailed, Direction: syncDirectionConflict, Error: "本地保留版本身份不一致"})
+		return
+	}
+	occupied[suffixedRel] = true
+
+	action, perr := syncPullOneFilePinned(ctx, spaceID, rf, pinned, ifExistsOverwrite)
+	if action != pullActionDownloaded {
+		res.Summary.Failed++
+		msg := ""
+		if perr != nil {
+			msg = perr.Error()
+		}
+		if msg == "" {
+			msg = "远端版本未能拉取，本地保留版本已保留"
+		}
+		res.Items = append(res.Items, driveSyncItem{RelPath: rel, Action: syncActionFailed, Direction: syncDirectionConflict, Error: msg})
+		return
+	}
+	currentSaved, err := pullRootLstat(pinned.parentRoot, newName)
+	if err != nil || !sameKeepBothVersion(savedInfo, currentSaved) {
+		res.Summary.Failed++
+		res.Items = append(res.Items, driveSyncItem{RelPath: rel, Action: syncActionFailed, Direction: syncDirectionConflict, Error: "本地保留版本在传输期间被删除、替换或修改"})
+		return
+	}
+	res.Summary.Pulled++
+	res.Items = append(res.Items,
+		driveSyncItem{RelPath: suffixedRel, Action: syncActionRenamedLocal, Direction: syncDirectionConflict},
+		driveSyncItem{RelPath: rel, Action: syncActionDownloaded, Direction: syncDirectionPull},
+	)
+}
+
+func sameKeepBothVersion(expected, current os.FileInfo) bool {
+	return expected != nil && current != nil && current.Mode().IsRegular() &&
+		os.SameFile(expected, current) && expected.Size() == current.Size() &&
+		expected.ModTime().Equal(current.ModTime())
+}
+
+// syncKeepBothCandidate 生成 keep-both 的第 n 个候选相对路径（n=0 为首选）：在扩展名前
+// 插入基于远端 fileId 末段的后缀（缺失时用 conflict），n>0 再追加序号消歧。
+func syncKeepBothCandidate(rel, fileID string, n int) string {
+	suffix := "conflict"
+	if fileID != "" {
+		s := fileID
+		if len(s) > 8 {
+			s = s[len(s)-8:]
+		}
+		suffix = "conflict-" + s
+	}
+	dir, base := splitRel(rel)
+	ext := filepath.Ext(base) // base 无路径分隔符，取末尾扩展名安全
+	stem := strings.TrimSuffix(base, ext)
+	name := stem + "." + suffix + ext
+	if n > 0 {
+		name = fmt.Sprintf("%s.%s.%d%s", stem, suffix, n, ext)
+	}
+	if dir == "" {
+		return name
+	}
+	return dir + "/" + name
+}
+
+// driveSyncSuffixedRel 返回首个不在 occupied（纯字符串查重）中的候选。仅用于快速路径与
+// 单元测试；keep-both 实际执行走 reserveSyncKeepBothTarget，以 OS 兜底等价性。
+func driveSyncSuffixedRel(rel, fileID string, occupied map[string]bool) string {
+	for n := 0; ; n++ {
+		if cand := syncKeepBothCandidate(rel, fileID, n); !occupied[cand] {
+			return cand
+		}
+	}
+}
+
+// reserveSyncKeepBothTarget 生成候选并通过 Root.Link(original,candidate) 原子建立
+// no-clobber 本地保留版本。EEXIST（含文件系统等价名称）时换下一个候选。
+func reserveSyncKeepBothTarget(absDir, rel, fileID string, occupied map[string]bool) (string, string, error) {
+	target, err := openPinnedPullTarget(absDir, rel)
+	if err != nil {
+		return "", "", err
+	}
+	defer target.close()
+	candidate, _, err := reserveSyncKeepBothTargetPinned(target, rel, fileID, occupied)
+	if err != nil {
+		return "", "", err
+	}
+	return candidate, filepath.Join(absDir, filepath.FromSlash(candidate)), nil
+}
+
+func reserveSyncKeepBothTargetPinned(target *pinnedPullTarget, rel, fileID string, occupied map[string]bool) (string, string, error) {
+	parentRel, _ := splitRel(rel)
+	for n := 0; ; n++ {
+		cand := syncKeepBothCandidate(rel, fileID, n)
+		if occupied[cand] {
+			continue // 本次运行内已知占用，快速跳过
+		}
+		candidateParent, candidateName := splitRel(cand)
+		if candidateParent != parentRel || !isSafeRemoteSegment(candidateName) {
+			return "", "", fmt.Errorf("keep-both 候选路径 %q 不在原目标目录内", cand)
+		}
+		if err := target.verifyParent(); err != nil {
+			return "", "", err
+		}
+		oerr := syncRootLink(target.parentRoot, target.name, filepath.FromSlash(candidateName))
+		if oerr == nil {
+			return cand, filepath.FromSlash(candidateName), nil
+		}
+		if os.IsExist(oerr) {
+			occupied[cand] = true // 等价目标已存在，记下避免重试，换下一个后缀
+			continue
+		}
+		return "", "", oerr
+	}
+}
+
+// syncAskStdin 是 --on-conflict=ask 交互提问的输入源，默认 os.Stdin；测试可替换它以
+// 注入非交互（EOF）场景。
+var syncAskStdin io.Reader = os.Stdin
+
+// driveSyncAskConflict 在 --on-conflict=ask 下交互式询问单个冲突文件的解决策略。
+// 返回四种具体策略之一，或 ""（跳过）。当 stdin 在给出选择前结束（管道/无 TTY 等非交互
+// 环境）时，按文档约定等价于「跳过」，返回 ""——绝不因此中止整个同步，new_local/new_remote
+// 等其余差异仍会照常处理。
+func driveSyncAskConflict(rel string) (string, error) {
+	fmt.Fprintf(os.Stderr, "冲突: 本地与远端都修改了 %q。请选择 [R]远端优先 / [L]本地优先 / [K]保留两者 / [S]跳过 (默认 R): ", rel)
+	line, err := bufio.NewReader(syncAskStdin).ReadString('\n')
+	if err != nil && !errors.Is(err, io.EOF) {
+		return "", fmt.Errorf("读取冲突选择失败 (%s): %w", rel, err)
+	}
+	switch strings.TrimSpace(strings.ToLower(line)) {
+	case "r", "remote", "remote-wins":
+		return syncConflictRemoteWins, nil
+	case "l", "local", "local-wins":
+		return syncConflictLocalWins, nil
+	case "k", "keep", "keep-both":
+		return syncConflictKeepBoth, nil
+	case "s", "skip":
+		return "", nil
+	case "":
+		if errors.Is(err, io.EOF) {
+			// 非交互（管道/无 TTY）：stdin 在给出选择前结束。按文档约定等价于跳过，
+			// 返回 "" 而非报错——否则单个冲突会让 runDriveSync 直接中止，连
+			// new_local/new_remote 都不再处理。
+			return "", nil
+		}
+		return syncConflictRemoteWins, nil // 交互式回车 → 默认远端优先
+	default:
+		return "", fmt.Errorf("无效的冲突选择: %q（可选 remote/local/keep/skip）", strings.TrimSpace(line))
+	}
+}

internal/helpers/drive_sync_confirmation_test.go

@@ -0,0 +1,416 @@
+package helpers
+
+import (
+	"bytes"
+	"context"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam"
+)
+
+// pull / push / sync 声明 Safety.Confirmation = user_required。本文件断言两件事：
+//   1. 未确认（无 --yes、非 dry-run）时命令必须在任何写操作之前拒绝执行；
+//   2. 明确确认（--yes）后才发出精确的工具调用并落盘。
+// status 是只读叶子（not_required），不受确认门约束。
+
+// ──────────────────────────────────────────────────────────
+// 1. 未确认即拒绝，且一个写操作都不发生
+// ──────────────────────────────────────────────────────────
+
+func TestCrossPlatformCoverageDriveSyncFamily_refusesWithoutConfirmation(t *testing.T) {
+	cases := []struct {
+		name     string
+		args     []string
+		setup    func(t *testing.T, dir string)
+		listJSON string
+	}{
+		{
+			name: "pull",
+			args: []string{"pull"},
+			// 远端有文件、本地为空：即便是纯新增也必须先确认。
+			listJSON: `{"result":{"items":[{"name":"a.txt","type":"file","fileId":"A","modifyTime":1}],"nextToken":""}}`,
+		},
+		{
+			name:     "push",
+			args:     []string{"push"},
+			setup:    func(t *testing.T, dir string) { mustWrite(t, filepath.Join(dir, "a.txt"), "local") },
+			listJSON: `{"result":{"items":[],"nextToken":""}}`,
+		},
+		{
+			name:     "sync",
+			args:     []string{"sync", "--quick", "--on-conflict", "remote-wins"},
+			setup:    func(t *testing.T, dir string) { mustWrite(t, filepath.Join(dir, "a.txt"), "local") },
+			listJSON: `{"result":{"items":[{"name":"b.txt","type":"file","fileId":"B","modifyTime":2}],"nextToken":""}}`,
+		},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			dir := t.TempDir()
+			if tc.setup != nil {
+				tc.setup(t, dir)
+			}
+
+			caller := &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 tc.listJSON, nil
+				case "download_file":
+					return `{"result":{"downloadUrl":"https://oss.example.com/get","headers":{}}}`, nil
+				case "get_upload_info":
+					return `{"result":{"resourceUrls":[{"url":"https://oss.example.com/put","headers":{}}],"uploadId":"U1"}}`, nil
+				}
+				return `{"result":{"fileId":"NEW"},"success":true}`, nil
+			}}
+			swapPullDownloadPath(t, func(_ context.Context, _ string, _ map[string]string, dest string) error {
+				t.Error("no download may happen before confirmation")
+				return os.WriteFile(dest, []byte("leaked"), 0o644)
+			})
+			testseam.Swap(t, &pushPutOpenedFile, func(context.Context, string, map[string]string, *os.File, int64) error {
+				t.Error("no upload may happen before confirmation")
+				return nil
+			})
+
+			args := append(append([]string{}, tc.args...), "--local-folder", dir, "--remote-folder", "ROOT")
+			err := runDriveCmdWithoutConfirm(t, caller, args...)
+			if err == nil {
+				t.Fatal("expected the command to refuse without --yes")
+			}
+			if !strings.Contains(err.Error(), "--yes") {
+				t.Errorf("error must tell the user to confirm with --yes, got %q", err.Error())
+			}
+			// 拒绝必须发生在任何写工具调用之前。
+			for _, tool := range []string{"download_file", "get_upload_info", "create_folder", "ln"} {
+				if got := caller.callsFor(tool); len(got) != 0 {
+					t.Errorf("%s must not be called before confirmation, got %v", tool, got)
+				}
+			}
+			// 本地目录不得新增任何文件。
+			entries, _ := os.ReadDir(dir)
+			for _, e := range entries {
+				if e.Name() == "b.txt" || e.Name() == "a.txt" && tc.name == "pull" {
+					t.Errorf("%s must not be materialized before confirmation", e.Name())
+				}
+			}
+		})
+	}
+}
+
+// --dry-run 无需 --yes 也能预览：这是让用户看清将发生什么的必要出口，且不写任何东西。
+func TestCrossPlatformCoverageDriveSyncFamily_dryRunNeedsNoConfirmation(t *testing.T) {
+	dir := t.TempDir()
+	mustWrite(t, filepath.Join(dir, "local.txt"), "l")
+
+	caller := syncCaller(map[string]string{
+		"ROOT": `{"result":{"items":[{"name":"remote.txt","type":"file","fileId":"R","modifyTime":2}],"nextToken":""}}`,
+	})
+	caller.dryRun = true
+	swapPullDownloadPath(t, func(context.Context, string, map[string]string, string) error {
+		t.Error("dry-run must not download")
+		return nil
+	})
+	testseam.Swap(t, &pushPutOpenedFile, func(context.Context, string, map[string]string, *os.File, int64) error {
+		t.Error("dry-run must not upload")
+		return nil
+	})
+
+	if err := runDriveCmdWithoutConfirm(t, caller, "sync",
+		"--local-folder", dir, "--remote-folder", "ROOT", "--quick"); err != nil {
+		t.Fatalf("dry-run must not require confirmation: %v", err)
+	}
+	if _, err := os.Stat(filepath.Join(dir, "remote.txt")); !os.IsNotExist(err) {
+		t.Error("dry-run must not write remote files locally")
+	}
+}
+
+func TestCrossPlatformCoverageDrivePull_dryRunPlansWithoutLocalWrites(t *testing.T) {
+	parent := t.TempDir()
+	target := filepath.Join(parent, "not-created")
+	caller := pullListingCaller(`{"name":"remote.txt","type":"file","fileId":"R","modifyTime":2}`)
+	caller.dryRun = true
+	swapPullDownloadPath(t, func(context.Context, string, map[string]string, string) error {
+		t.Error("dry-run must not download")
+		return nil
+	})
+
+	var out bytes.Buffer
+	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": target, "remote-folder": "ROOT"})
+	if err := cmd.RunE(cmd, nil); err != nil {
+		t.Fatalf("dry-run pull: %v", err)
+	}
+	if _, err := os.Stat(target); !os.IsNotExist(err) {
+		t.Fatalf("dry-run must not create local root: %v", err)
+	}
+	if got := len(caller.callsFor("download_file")); got != 0 {
+		t.Fatalf("download_file calls = %d, want 0", got)
+	}
+	if text := out.String(); !strings.Contains(text, `"dry_run": true`) || !strings.Contains(text, `"remote.txt"`) {
+		t.Fatalf("missing pull plan: %s", text)
+	}
+}
+
+func TestCrossPlatformCoverageDrivePush_dryRunPlansWithoutRemoteWrites(t *testing.T) {
+	dir := t.TempDir()
+	if err := os.MkdirAll(filepath.Join(dir, "sub"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	mustWrite(t, filepath.Join(dir, "sub", "local.txt"), "local")
+	caller := syncCaller(nil)
+	caller.dryRun = true
+	testseam.Swap(t, &pushPutOpenedFile, func(context.Context, string, map[string]string, *os.File, int64) error {
+		t.Error("dry-run must not upload")
+		return nil
+	})
+
+	var out bytes.Buffer
+	testseam.Swap(t, &deps, &Deps{Caller: caller, Out: &Formatter{w: &out}})
+	testseam.Swap(t, &os.Args, []string{"dws", "drive", "push"})
+	cmd := findDriveSubcommand(t, "push")
+	mustSetFlags(t, cmd, map[string]string{"local-folder": dir, "remote-folder": "ROOT"})
+	if err := cmd.RunE(cmd, nil); err != nil {
+		t.Fatalf("dry-run push: %v", err)
+	}
+	for _, tool := range []string{"create_folder", "get_upload_info", "commit_upload"} {
+		if got := len(caller.callsFor(tool)); got != 0 {
+			t.Fatalf("%s calls = %d, want 0", tool, got)
+		}
+	}
+	if text := out.String(); !strings.Contains(text, `"dry_run": true`) || !strings.Contains(text, `"sub/local.txt"`) {
+		t.Fatalf("missing push plan: %s", text)
+	}
+}
+
+func TestCrossPlatformCoverageDrivePull_dryRunPlanBranches(t *testing.T) {
+	root := t.TempDir()
+	mustWrite(t, filepath.Join(root, "skip.txt"), "skip")
+	mustWrite(t, filepath.Join(root, "smart.txt"), "smart")
+	remote := map[string]*remoteFile{
+		"A.txt":     {RelPath: "A.txt"},
+		"a.txt":     {RelPath: "a.txt"},
+		"../escape": {RelPath: "../escape"},
+		"skip.txt":  {RelPath: "skip.txt"},
+		"smart.txt": {RelPath: "smart.txt", ModifiedTime: 1, ModifiedTimeValid: true},
+		"new.txt":   {RelPath: "new.txt"},
+	}
+	var out bytes.Buffer
+	testseam.Swap(t, &deps, &Deps{Out: &Formatter{w: &out}})
+
+	if err := printDrivePullDryRun(root, ifExistsSkip, remote,
+		[]string{"A.txt", "a.txt", "../escape", "skip.txt", "new.txt"}, true); err != nil {
+		t.Fatalf("skip plan: %v", err)
+	}
+	if text := out.String(); !strings.Contains(text, pullActionFailed) || !strings.Contains(text, pullActionSkipped) || !strings.Contains(text, pullActionDownloaded) {
+		t.Fatalf("skip plan did not cover failed/skipped/downloaded: %s", text)
+	}
+	out.Reset()
+	if err := printDrivePullDryRun(root, ifExistsSmart, remote, []string{"smart.txt"}, false); err != nil {
+		t.Fatalf("smart plan: %v", err)
+	}
+	if !strings.Contains(out.String(), pullActionSkipped) {
+		t.Fatalf("smart plan must skip newer local file: %s", out.String())
+	}
+}
+
+func TestCrossPlatformCoverageDrivePush_dryRunPlanBranches(t *testing.T) {
+	var out bytes.Buffer
+	testseam.Swap(t, &deps, &Deps{Out: &Formatter{w: &out}})
+	remoteFolders := map[string]string{"": "ROOT", "existing": "EXISTING"}
+	remoteFiles := map[string]*remoteFile{
+		"skip.txt":            {RelPath: "skip.txt"},
+		"smart-skip.txt":      {RelPath: "smart-skip.txt", ModifiedTime: 20, ModifiedTimeValid: true},
+		"smart-overwrite.txt": {RelPath: "smart-overwrite.txt", ModifiedTime: 1, ModifiedTimeValid: true},
+		"overwrite.txt":       {RelPath: "overwrite.txt"},
+	}
+	files := func(paths ...string) []localPushFile {
+		result := make([]localPushFile, 0, len(paths))
+		for _, path := range paths {
+			result = append(result, localPushFile{RelPath: path, Size: 1, ModTimeMillis: 10})
+		}
+		return result
+	}
+
+	if err := printDrivePushDryRun(ifExistsSkip, remoteFiles, remoteFolders,
+		[]string{"existing", "missing/child"}, files("orphan/a.txt", "skip.txt", "new.txt")); err != nil {
+		t.Fatalf("skip plan: %v", err)
+	}
+	if text := out.String(); !strings.Contains(text, pushActionFailed) || !strings.Contains(text, pushActionSkipped) || !strings.Contains(text, pushActionUploaded) {
+		t.Fatalf("skip plan did not cover failed/skipped/uploaded: %s", text)
+	}
+	out.Reset()
+	if err := printDrivePushDryRun(ifExistsSmart, remoteFiles, remoteFolders, nil,
+		files("smart-skip.txt", "smart-overwrite.txt")); err != nil {
+		t.Fatalf("smart plan: %v", err)
+	}
+	if text := out.String(); !strings.Contains(text, pushActionSkipped) || !strings.Contains(text, pushActionOverwritten) {
+		t.Fatalf("smart plan did not cover skip/overwrite: %s", text)
+	}
+	out.Reset()
+	if err := printDrivePushDryRun(ifExistsOverwrite, remoteFiles, remoteFolders, nil, files("overwrite.txt")); err != nil {
+		t.Fatalf("overwrite plan: %v", err)
+	}
+	if !strings.Contains(out.String(), pushActionOverwritten) {
+		t.Fatalf("overwrite plan must overwrite existing file: %s", out.String())
+	}
+}
+
+// ──────────────────────────────────────────────────────────
+// 2. 明确确认后才发出精确的工具调用
+// ──────────────────────────────────────────────────────────
+
+// sync --on-conflict remote-wins --yes：确认后只下载指定远端文件，且不上传。
+func TestCrossPlatformCoverageDriveSync_confirmedRemoteWinsIssuesExactCalls(t *testing.T) {
+	dir := t.TempDir()
+	p := filepath.Join(dir, "f.txt")
+	mustWrite(t, p, "local-version")
+	local := readFileMTimeMillis(t, p)
+	withSyncTransport(t, "remote-version")
+
+	caller := syncCaller(map[string]string{
+		"ROOT": `{"result":{"items":[{"name":"f.txt","type":"file","fileId":"F","modifyTime":` +
+			differentMillis(local) + `}],"nextToken":""}}`,
+	})
+	if err := runDriveCmdWithoutConfirm(t, caller, "sync", "--local-folder", dir,
+		"--remote-folder", "ROOT", "--quick", "--on-conflict", "remote-wins", "--yes"); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	dl := caller.callsFor("download_file")
+	if len(dl) != 1 || dl[0].args["fileId"] != "F" {
+		t.Fatalf("expected exactly one download_file(fileId=F), got %v", dl)
+	}
+	if up := caller.callsFor("get_upload_info"); len(up) != 0 {
+		t.Errorf("remote-wins must not upload, got %v", up)
+	}
+	if b, _ := os.ReadFile(p); string(b) != "remote-version" {
+		t.Errorf("remote-wins must replace the local content, got %q", string(b))
+	}
+}
+
+// pull --if-exists overwrite --yes：确认后才 download_file(fileId=A) 并覆盖本地内容。
+func TestCrossPlatformCoverageDrivePull_confirmedOverwriteIssuesExactCalls(t *testing.T) {
+	dir := t.TempDir()
+	p := filepath.Join(dir, "a.txt")
+	mustWrite(t, p, "local-old")
+
+	caller := pullListingCaller(`{"name":"a.txt","type":"file","fileId":"A","modifyTime":9}`)
+	swapPullDownloadPath(t, func(_ context.Context, _ string, _ map[string]string, dest string) error {
+		return os.WriteFile(dest, []byte("remote-new"), 0o644)
+	})
+
+	if err := runDriveCmdWithoutConfirm(t, caller, "pull", "--local-folder", dir,
+		"--remote-folder", "ROOT", "--if-exists", "overwrite", "--yes"); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	dl := caller.callsFor("download_file")
+	if len(dl) != 1 || dl[0].args["fileId"] != "A" {
+		t.Fatalf("expected exactly one download_file(fileId=A), got %v", dl)
+	}
+	if b, _ := os.ReadFile(p); string(b) != "remote-new" {
+		t.Errorf("confirmed overwrite must replace the local file, got %q", string(b))
+	}
+}
+
+// push --if-exists overwrite --yes：确认后原地覆盖，必须带 overwriteFileId 且不带 parentId。
+func TestCrossPlatformCoverageDrivePush_confirmedOverwriteIssuesExactCalls(t *testing.T) {
+	dir := t.TempDir()
+	mustWrite(t, filepath.Join(dir, "a.txt"), "local")
+	withNoopPut(t)
+
+	caller := pushOKCaller(map[string]string{
+		"ROOT": `{"result":{"items":[{"name":"a.txt","type":"file","fileId":"A","modifyTime":1}],"nextToken":""}}`,
+	})
+	if err := runDriveCmdWithoutConfirm(t, caller, "push", "--local-folder", dir,
+		"--remote-folder", "ROOT", "--if-exists", "overwrite", "--yes"); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	up := caller.callsFor("get_upload_info")
+	if len(up) != 1 || up[0].args["overwriteFileId"] != "A" {
+		t.Fatalf("expected get_upload_info(overwriteFileId=A), got %v", up)
+	}
+	if _, has := up[0].args["parentId"]; has {
+		t.Error("in-place overwrite must not carry parentId")
+	}
+}
+
+// sync --on-conflict local-wins --yes：确认后覆盖上传远端，且不下载。
+func TestCrossPlatformCoverageDriveSync_confirmedLocalWinsIssuesExactCalls(t *testing.T) {
+	dir := t.TempDir()
+	p := filepath.Join(dir, "f.txt")
+	mustWrite(t, p, "local-version")
+	local := readFileMTimeMillis(t, p)
+	withSyncTransport(t, "unused")
+
+	caller := syncCaller(map[string]string{
+		"ROOT": `{"result":{"items":[{"name":"f.txt","type":"file","fileId":"F","modifyTime":` +
+			differentMillis(local) + `}],"nextToken":""}}`,
+	})
+	if err := runDriveCmdWithoutConfirm(t, caller, "sync", "--local-folder", dir,
+		"--remote-folder", "ROOT", "--quick", "--on-conflict", "local-wins", "--yes"); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	up := caller.callsFor("get_upload_info")
+	if len(up) != 1 || up[0].args["overwriteFileId"] != "F" {
+		t.Fatalf("expected get_upload_info(overwriteFileId=F), got %v", up)
+	}
+	if dl := caller.callsFor("download_file"); len(dl) != 0 {
+		t.Errorf("local-wins must not download, got %v", dl)
+	}
+	if b, _ := os.ReadFile(p); string(b) != "local-version" {
+		t.Errorf("local-wins must keep the local content, got %q", string(b))
+	}
+}
+
+// ──────────────────────────────────────────────────────────
+// 3. 安全默认值本身
+// ──────────────────────────────────────────────────────────
+
+// sync 默认 --on-conflict=skip：两侧都变更时两边内容都保留，且不发出任何传输调用。
+func TestCrossPlatformCoverageDriveSync_defaultSkipsConflictsEntirely(t *testing.T) {
+	dir := t.TempDir()
+	p := filepath.Join(dir, "f.txt")
+	mustWrite(t, p, "local-version")
+	local := readFileMTimeMillis(t, p)
+	withSyncTransport(t, "remote-version")
+
+	caller := syncCaller(map[string]string{
+		"ROOT": `{"result":{"items":[{"name":"f.txt","type":"file","fileId":"F","modifyTime":` +
+			differentMillis(local) + `}],"nextToken":""}}`,
+	})
+	if err := runDriveCmd(t, caller, "sync", "--local-folder", dir, "--remote-folder", "ROOT", "--quick"); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if got := len(caller.callsFor("download_file")) + len(caller.callsFor("get_upload_info")); got != 0 {
+		t.Errorf("default skip must not transfer anything, got %d calls", got)
+	}
+	if b, _ := os.ReadFile(p); string(b) != "local-version" {
+		t.Errorf("default skip must keep the local content, got %q", string(b))
+	}
+}
+
+// pull 默认 --if-exists=skip：本地已存在的文件不被覆盖。
+func TestCrossPlatformCoverageDrivePull_defaultSkipsExistingLocalFiles(t *testing.T) {
+	dir := t.TempDir()
+	p := filepath.Join(dir, "a.txt")
+	mustWrite(t, p, "local-old")
+
+	caller := pullListingCaller(`{"name":"a.txt","type":"file","fileId":"A","modifyTime":9}`)
+	swapPullDownloadPath(t, func(context.Context, string, map[string]string, string) error {
+		t.Error("default skip must not download over an existing local file")
+		return nil
+	})
+
+	if err := runDriveCmd(t, caller, "pull", "--local-folder", dir, "--remote-folder", "ROOT"); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if b, _ := os.ReadFile(p); string(b) != "local-old" {
+		t.Errorf("default skip must keep the local file, got %q", string(b))
+	}
+}

internal/helpers/drive_sync_conflict_test.go

@@ -0,0 +1,220 @@
+package helpers
+
+import (
+	"context"
+	"errors"
+	"io"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam"
+)
+
+// failFolderCaller 让指定名字的 create_folder 失败，其余一切正常，
+// 用于构造「父目录未能创建 → 子目录/子文件连锁失败」。
+func failFolderCaller(failName string) *driveScriptCaller {
+	return &driveScriptCaller{reply: func(tool string, args map[string]any, _ int) (string, error) {
+		switch tool {
+		case "list_files":
+			return `{"result":{"items":[],"nextToken":""}}`, nil
+		case "create_folder":
+			if args["name"] == failName {
+				return "", errors.New("create_folder rejected: " + failName)
+			}
+			return `{"result":{"fileId":"NEWDIR"},"success":true}`, nil
+		case "get_upload_info":
+			return `{"result":{"resourceUrls":[{"url":"https://oss.example.com/put","headers":{}}],"uploadId":"U1"}}`, nil
+		case "download_file":
+			return `{"result":{"downloadUrl":"https://oss.example.com/get","headers":{}}}`, nil
+		}
+		return `{"result":{"fileId":"NEWFILE"},"success":true}`, nil
+	}}
+}
+
+// mkNested 建出 a/b/deep.txt 结构。
+func mkNested(t *testing.T) string {
+	t.Helper()
+	dir := t.TempDir()
+	if err := os.MkdirAll(filepath.Join(dir, "a", "b"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	mustWrite(t, filepath.Join(dir, "a", "b", "deep.txt"), "d")
+	return dir
+}
+
+// 顶层目录 a 建失败 → 子目录 a/b 因父目录缺失也 failed，其中文件同样 failed。
+func TestCrossPlatformCoverageDrivePush_nestedDirFailsWhenParentMissing(t *testing.T) {
+	dir := mkNested(t)
+	withNoopPut(t)
+
+	caller := failFolderCaller("a")
+	err := runDriveCmd(t, caller, "push", "--local-folder", dir, "--remote-folder", "ROOT")
+	var pf *drivePushFailure
+	if !errors.As(err, &pf) {
+		t.Fatalf("expected drivePushFailure, got %T %v", err, err)
+	}
+	// a（建失败）+ a/b（父缺失）+ a/b/deep.txt（父缺失）= 3
+	if pf.failed != 3 {
+		t.Errorf("failed = %d, want 3", pf.failed)
+	}
+	if got := caller.callsFor("get_upload_info"); len(got) != 0 {
+		t.Errorf("nothing may upload without a parent folder, got %v", got)
+	}
+}
+
+func TestCrossPlatformCoverageDriveSync_nestedDirFailsWhenParentMissing(t *testing.T) {
+	dir := mkNested(t)
+	withNoopPut(t)
+
+	caller := failFolderCaller("a")
+	err := runDriveCmd(t, caller, "sync", "--local-folder", dir, "--remote-folder", "ROOT", "--quick")
+	var sf *driveSyncFailure
+	if !errors.As(err, &sf) {
+		t.Fatalf("expected driveSyncFailure, got %T %v", err, err)
+	}
+	if sf.failed != 3 {
+		t.Errorf("failed = %d, want 3", sf.failed)
+	}
+}
+
+// new_remote 落盘目标经软链逃逸出本地根 → 记 failed，不写到根目录之外。
+func TestCrossPlatformCoverageDriveSync_newRemoteEscapeIsFailed(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)
+	}
+	withSyncTransport(t, "leak")
+
+	caller := syncCaller(map[string]string{
+		"ROOT": `{"result":{"items":[{"name":"sub","type":"folder","fileId":"SUB"}],"nextToken":""}}`,
+		"SUB":  `{"result":{"items":[{"name":"leaked.txt","type":"file","fileId":"L","modifyTime":1}],"nextToken":""}}`,
+	})
+	err := runDriveCmd(t, caller, "sync", "--local-folder", root, "--remote-folder", "ROOT", "--quick")
+	var sf *driveSyncFailure
+	if !errors.As(err, &sf) {
+		t.Fatalf("expected driveSyncFailure, got %T %v", err, err)
+	}
+	if _, statErr := os.Stat(filepath.Join(outside, "leaked.txt")); !os.IsNotExist(statErr) {
+		t.Error("file escaped the local root")
+	}
+}
+
+// ──────────────────────────────────────────────────────────
+// keep-both 的失败与回滚分支
+// ──────────────────────────────────────────────────────────
+
+// syncKeepBoth 在 rel 逃逸时直接 failed（resolveLocalTarget 报错）。
+func TestCrossPlatformCoverageSyncKeepBoth_escapingRelIsFailed(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{}
+	syncKeepBoth(res, context.Background(), "", &remoteFile{RelPath: "sub/f.txt", FileID: "FID12345678"},
+		root, "sub/f.txt", map[string]bool{})
+	if res.Summary.Failed != 1 {
+		t.Fatalf("failed = %d, want 1", res.Summary.Failed)
+	}
+}
+
+// 原子建立本地保留硬链接失败 → failed。
+func TestCrossPlatformCoverageSyncKeepBoth_reserveFailureIsFailed(t *testing.T) {
+	root := t.TempDir()
+	mustWrite(t, filepath.Join(root, "f.txt"), "local")
+	testseam.Swap(t, &syncRootLink, func(*os.Root, string, string) error {
+		return errors.New("link boom")
+	})
+
+	res := &driveSyncResult{}
+	syncKeepBoth(res, context.Background(), "", &remoteFile{RelPath: "f.txt", FileID: "FID12345678"},
+		root, "f.txt", map[string]bool{})
+	if res.Summary.Failed != 1 {
+		t.Fatalf("failed = %d, want 1", res.Summary.Failed)
+	}
+}
+
+// Link 失败不得留下空占位，也不得移动或修改原文件。
+func TestCrossPlatformCoverageSyncKeepBoth_linkFailureLeavesOriginal(t *testing.T) {
+	root := t.TempDir()
+	mustWrite(t, filepath.Join(root, "f.txt"), "local")
+	testseam.Swap(t, &syncRootLink, func(*os.Root, string, string) error {
+		return errors.New("link boom")
+	})
+	res := &driveSyncResult{}
+	occupied := map[string]bool{}
+	syncKeepBoth(res, context.Background(), "", &remoteFile{RelPath: "f.txt", FileID: "FID12345678"},
+		root, "f.txt", occupied)
+
+	if res.Summary.Failed != 1 {
+		t.Fatalf("failed = %d, want 1", res.Summary.Failed)
+	}
+	if _, err := os.Stat(filepath.Join(root, syncKeepBothCandidate("f.txt", "FID12345678", 0))); !os.IsNotExist(err) {
+		t.Error("failed link must not leave a placeholder")
+	}
+	if content, err := os.ReadFile(filepath.Join(root, "f.txt")); err != nil || string(content) != "local" {
+		t.Fatalf("original changed after failed link: content=%q err=%v", content, err)
+	}
+}
+
+// 拉取失败时不做回滚：原名尚未发布，候选硬链接也保留，避免误删并发对象。
+func TestCrossPlatformCoverageSyncKeepBoth_pullFailurePreservesCandidate(t *testing.T) {
+	root := t.TempDir()
+	p := filepath.Join(root, "f.txt")
+	mustWrite(t, p, "local-version")
+
+	testseam.Swap(t, &deps, &Deps{Caller: syncCaller(nil), Out: &Formatter{w: io.Discard}})
+	testseam.Swap(t, &os.Args, []string{"dws", "drive"})
+	swapPullDownloadPath(t, func(context.Context, string, map[string]string, string) error { return errTestDownload })
+
+	res := &driveSyncResult{}
+	syncKeepBoth(res, context.Background(), "", &remoteFile{RelPath: "f.txt", FileID: "FID12345678"},
+		root, "f.txt", map[string]bool{})
+
+	if res.Summary.Failed != 1 {
+		t.Fatalf("failed = %d, want 1", res.Summary.Failed)
+	}
+	if b, err := os.ReadFile(p); err != nil || string(b) != "local-version" {
+		t.Fatalf("original must remain before publish: %v / %q", err, string(b))
+	}
+	suffixed := filepath.Join(root, syncKeepBothCandidate("f.txt", "FID12345678", 0))
+	if b, err := os.ReadFile(suffixed); err != nil || string(b) != "local-version" {
+		t.Fatalf("candidate must remain after pull failure: %v / %q", err, string(b))
+	}
+	originalInfo, _ := os.Lstat(p)
+	candidateInfo, _ := os.Lstat(suffixed)
+	if !os.SameFile(originalInfo, candidateInfo) {
+		t.Fatal("candidate must be a hard link to the original local version")
+	}
+}
+
+// 拉取失败只能上报 failed，不得产生 renamed_local 成功项。
+func TestCrossPlatformCoverageSyncKeepBoth_pullFailureDoesNotReportRenamed(t *testing.T) {
+	root := t.TempDir()
+	p := filepath.Join(root, "f.txt")
+	mustWrite(t, p, "local-version")
+
+	testseam.Swap(t, &deps, &Deps{Caller: syncCaller(nil), Out: &Formatter{w: io.Discard}})
+	testseam.Swap(t, &os.Args, []string{"dws", "drive"})
+	swapPullDownloadPath(t, func(context.Context, string, map[string]string, string) error { return errTestDownload })
+
+	res := &driveSyncResult{}
+	syncKeepBoth(res, context.Background(), "", &remoteFile{RelPath: "f.txt", FileID: "FID12345678"},
+		root, "f.txt", map[string]bool{})
+
+	if res.Summary.Failed != 1 {
+		t.Fatalf("failed = %d, want 1", res.Summary.Failed)
+	}
+	if len(res.Items) != 1 || res.Items[0].Action != syncActionFailed {
+		t.Fatalf("items = %+v", res.Items)
+	}
+	suffixed := syncKeepBothCandidate("f.txt", "FID12345678", 0)
+	if b, err := os.ReadFile(filepath.Join(root, suffixed)); err != nil || string(b) != "local-version" {
+		t.Fatalf("local version must survive as %s: %v / %q", suffixed, err, string(b))
+	}
+	if res.Items[0].Action == syncActionRenamedLocal {
+		t.Fatalf("pull failure must not report renamed_local: %#v", res.Items)
+	}
+}

internal/helpers/drive_sync_coverage_test.go

@@ -0,0 +1,403 @@
+package helpers
+
+import (
+	"context"
+	"errors"
+	"io"
+	"os"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam"
+)
+
+// syncCaller 组合 push 与 pull 两侧：list_files 按 parentId 返回远端现状，
+// create_folder / get_upload_info / ln 走 push 路径，download_file 走 pull 路径。
+func syncCaller(listing map[string]string) *driveScriptCaller {
+	return &driveScriptCaller{reply: func(tool string, args map[string]any, _ int) (string, error) {
+		switch tool {
+		case "list_files":
+			parent, _ := args["parentId"].(string)
+			if body, ok := listing[parent]; ok {
+				return body, nil
+			}
+			return `{"result":{"items":[],"nextToken":""}}`, nil
+		case "create_folder":
+			return `{"result":{"fileId":"NEWDIR"},"success":true}`, nil
+		case "get_upload_info":
+			return `{"result":{"resourceUrls":[{"url":"https://oss.example.com/put","headers":{}}],"uploadId":"U1"}}`, nil
+		case "download_file":
+			return `{"result":{"downloadUrl":"https://oss.example.com/get","headers":{}}}`, nil
+		}
+		return `{"result":{"fileId":"NEWFILE"},"success":true}`, nil
+	}}
+}
+
+// withSyncTransport 注入成功的上传与下载。
+func withSyncTransport(t *testing.T, body string) {
+	t.Helper()
+	testseam.Swap(t, &pushPutOpenedFile, func(context.Context, string, map[string]string, *os.File, int64) error { return nil })
+	swapPullDownloadPath(t, func(_ context.Context, _ string, _ map[string]string, dest string) error {
+		return os.WriteFile(dest, []byte(body), 0o644)
+	})
+}
+
+// ──────────────────────────────────────────────────────────
+// --on-conflict 取值处理
+// ──────────────────────────────────────────────────────────
+
+// 显式传空 --on-conflict 时回落安全默认 skip：两侧都变更时两边内容都不动。
+func TestCrossPlatformCoverageDriveSync_emptyOnConflictDefaultsToSkip(t *testing.T) {
+	dir := t.TempDir()
+	p := filepath.Join(dir, "f.txt")
+	mustWrite(t, p, "local-old")
+	local := readFileMTimeMillis(t, p)
+	withSyncTransport(t, "remote-new")
+
+	caller := syncCaller(map[string]string{
+		"ROOT": `{"result":{"items":[{"name":"f.txt","type":"file","fileId":"F","modifyTime":` +
+			differentMillis(local) + `}],"nextToken":""}}`,
+	})
+	if err := runDriveCmd(t, caller, "sync", "--local-folder", dir, "--remote-folder", "ROOT",
+		"--quick", "--on-conflict", ""); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if b, _ := os.ReadFile(p); string(b) != "local-old" {
+		t.Errorf("empty --on-conflict must default to skip and keep the local file, got %q", string(b))
+	}
+}
+
+func TestCrossPlatformCoverageDriveSync_invalidOnConflictRejected(t *testing.T) {
+	err := runDriveCmd(t, syncCaller(nil), "sync", "--local-folder", t.TempDir(),
+		"--remote-folder", "ROOT", "--on-conflict", "bogus")
+	if err == nil || !strings.Contains(err.Error(), "--on-conflict") {
+		t.Fatalf("expected --on-conflict rejection, got %v", err)
+	}
+}
+
+// ──────────────────────────────────────────────────────────
+// unchanged / unknown 分类
+// ──────────────────────────────────────────────────────────
+
+// quick 模式下两侧 mtime 相同 → unchanged，不做任何读写。
+func TestCrossPlatformCoverageDriveSync_unchangedIsUntouched(t *testing.T) {
+	dir := t.TempDir()
+	p := filepath.Join(dir, "same.txt")
+	mustWrite(t, p, "identical")
+	local := readFileMTimeMillis(t, p)
+	withSyncTransport(t, "should-not-be-used")
+
+	caller := syncCaller(map[string]string{
+		"ROOT": `{"result":{"items":[{"name":"same.txt","type":"file","fileId":"S","modifyTime":` +
+			strconv.FormatInt(local, 10) + `}],"nextToken":""}}`,
+	})
+	if err := runDriveCmd(t, caller, "sync", "--local-folder", dir, "--remote-folder", "ROOT", "--quick"); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if got := len(caller.callsFor("download_file")) + len(caller.callsFor("get_upload_info")); got != 0 {
+		t.Errorf("unchanged file must not be transferred, got %d write calls", got)
+	}
+	if b, _ := os.ReadFile(p); string(b) != "identical" {
+		t.Errorf("unchanged file was modified: %q", string(b))
+	}
+}
+
+// exact 模式远端无可靠 md5 → unknown，一律计入 skipped 且不动任何一侧。
+func TestCrossPlatformCoverageDriveSync_unknownIsSkipped(t *testing.T) {
+	dir := t.TempDir()
+	p := filepath.Join(dir, "u.txt")
+	mustWrite(t, p, "local")
+	withSyncTransport(t, "remote")
+
+	// 无 md5 字段 → exact 模式无法核对内容。
+	caller := syncCaller(map[string]string{
+		"ROOT": `{"result":{"items":[{"name":"u.txt","type":"file","fileId":"U","modifyTime":1}],"nextToken":""}}`,
+	})
+	if err := runDriveCmd(t, caller, "sync", "--local-folder", dir, "--remote-folder", "ROOT"); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if got := len(caller.callsFor("download_file")) + len(caller.callsFor("get_upload_info")); got != 0 {
+		t.Errorf("unknown must not be transferred, got %d write calls", got)
+	}
+	if b, _ := os.ReadFile(p); string(b) != "local" {
+		t.Errorf("unknown file was modified: %q", string(b))
+	}
+}
+
+// exact 模式下本地 MD5 计算失败 → 整个 sync 中止。错误通过 seam 确定性注入，
+// 避免依赖 chmod：Windows 不遵循 POSIX 的 000 权限语义。
+func TestCrossPlatformCoverageDriveSync_md5FailureAborts(t *testing.T) {
+	testseam.Swap(t, &pushMD5OpenedFile, func(*os.File) (string, error) {
+		return "", errors.New("md5 boom")
+	})
+
+	dir := t.TempDir()
+	p := filepath.Join(dir, "secret.txt")
+	mustWrite(t, p, "data")
+
+	caller := syncCaller(map[string]string{
+		"ROOT": `{"result":{"items":[{"name":"secret.txt","type":"file","fileId":"S","md5":"abc"}],"nextToken":""}}`,
+	})
+	err := runDriveCmd(t, caller, "sync", "--local-folder", dir, "--remote-folder", "ROOT")
+	if err == nil || !strings.Contains(err.Error(), "MD5") {
+		t.Fatalf("expected MD5 failure to abort sync, got %v", err)
+	}
+}
+
+// ──────────────────────────────────────────────────────────
+// new_local 推送：按需建目录
+// ──────────────────────────────────────────────────────────
+
+// 本地子目录在远端缺失 → 建目录（记 folder_created + pushed）再上传其中文件。
+func TestCrossPlatformCoverageDriveSync_createsRemoteFolderForNewLocal(t *testing.T) {
+	dir := t.TempDir()
+	if err := os.MkdirAll(filepath.Join(dir, "sub"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	mustWrite(t, filepath.Join(dir, "sub", "deep.txt"), "d")
+	withSyncTransport(t, "unused")
+
+	caller := syncCaller(nil)
+	if err := runDriveCmd(t, caller, "sync", "--local-folder", dir, "--remote-folder", "ROOT", "--quick"); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	cf := caller.callsFor("create_folder")
+	if len(cf) != 1 || cf[0].args["name"] != "sub" {
+		t.Fatalf("expected create_folder(sub), got %v", cf)
+	}
+	up := caller.callsFor("get_upload_info")
+	if len(up) != 1 || up[0].args["parentId"] != "NEWDIR" {
+		t.Errorf("upload parentId = %v, want NEWDIR", up[0].args["parentId"])
+	}
+}
+
+// 远端已有同名目录 → 复用，不重建。
+func TestCrossPlatformCoverageDriveSync_reusesExistingRemoteFolder(t *testing.T) {
+	dir := t.TempDir()
+	if err := os.MkdirAll(filepath.Join(dir, "sub"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	mustWrite(t, filepath.Join(dir, "sub", "deep.txt"), "d")
+	withSyncTransport(t, "unused")
+
+	caller := syncCaller(map[string]string{
+		"ROOT": `{"result":{"items":[{"name":"sub","type":"folder","fileId":"EXISTING"}],"nextToken":""}}`,
+	})
+	if err := runDriveCmd(t, caller, "sync", "--local-folder", dir, "--remote-folder", "ROOT", "--quick"); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if got := caller.callsFor("create_folder"); len(got) != 0 {
+		t.Errorf("existing folder must be reused, got %v", got)
+	}
+}
+
+// create_folder 失败 → 目录与其中文件都记 failed，命令非零退出。
+func TestCrossPlatformCoverageDriveSync_folderCreationFailureCascades(t *testing.T) {
+	dir := t.TempDir()
+	if err := os.MkdirAll(filepath.Join(dir, "sub"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	mustWrite(t, filepath.Join(dir, "sub", "deep.txt"), "d")
+	withSyncTransport(t, "unused")
+
+	caller := &driveScriptCaller{reply: func(tool string, _ map[string]any, _ int) (string, error) {
+		if tool == "create_folder" {
+			return "", errors.New("create_folder boom")
+		}
+		return `{"result":{"items":[],"nextToken":""}}`, nil
+	}}
+	err := runDriveCmd(t, caller, "sync", "--local-folder", dir, "--remote-folder", "ROOT", "--quick")
+	var sf *driveSyncFailure
+	if !errors.As(err, &sf) || sf.failed != 2 {
+		t.Fatalf("expected 2 failures (folder + orphaned file), got %T %v", err, err)
+	}
+}
+
+// new_local 上传失败 → 记 failed 并非零退出。
+func TestCrossPlatformCoverageDriveSync_pushUploadFailureIsFailed(t *testing.T) {
+	dir := t.TempDir()
+	mustWrite(t, filepath.Join(dir, "only-local.txt"), "x")
+	testseam.Swap(t, &pushPutOpenedFile, func(context.Context, string, map[string]string, *os.File, int64) error { return errTestUpload })
+
+	caller := syncCaller(nil)
+	err := runDriveCmd(t, caller, "sync", "--local-folder", dir, "--remote-folder", "ROOT", "--quick")
+	var sf *driveSyncFailure
+	if !errors.As(err, &sf) || sf.failed != 1 {
+		t.Fatalf("expected 1 push failure, got %T %v", err, err)
+	}
+}
+
+// ──────────────────────────────────────────────────────────
+// --on-conflict ask 的每个交互答案
+// ──────────────────────────────────────────────────────────
+
+func TestCrossPlatformCoverageDriveSyncAskConflict_answers(t *testing.T) {
+	cases := []struct {
+		input string
+		want  string
+		isErr bool
+	}{
+		{"r\n", syncConflictRemoteWins, false},
+		{"remote\n", syncConflictRemoteWins, false},
+		{"l\n", syncConflictLocalWins, false},
+		{"local-wins\n", syncConflictLocalWins, false},
+		{"k\n", syncConflictKeepBoth, false},
+		{"keep\n", syncConflictKeepBoth, false},
+		{"s\n", "", false},
+		{"skip\n", "", false},
+		{"\n", syncConflictRemoteWins, false}, // 交互式回车 → 默认远端优先
+		{"nonsense\n", "", true},
+	}
+	for _, tc := range cases {
+		t.Run(strings.TrimSpace(tc.input), func(t *testing.T) {
+			testseam.Swap(t, &syncAskStdin, io.Reader(strings.NewReader(tc.input)))
+
+			got, err := driveSyncAskConflict("f.txt")
+			if tc.isErr {
+				if err == nil {
+					t.Fatalf("expected error for %q", tc.input)
+				}
+				return
+			}
+			if err != nil {
+				t.Fatalf("unexpected error: %v", err)
+			}
+			if got != tc.want {
+				t.Errorf("driveSyncAskConflict(%q) = %q, want %q", tc.input, got, tc.want)
+			}
+		})
+	}
+}
+
+// ask 选到无效值时整个 sync 中止（错误上抛，不是静默跳过）。
+func TestCrossPlatformCoverageDriveSync_askInvalidChoiceAborts(t *testing.T) {
+	testseam.Swap(t, &syncAskStdin, io.Reader(strings.NewReader("nonsense\n")))
+
+	dir := t.TempDir()
+	p := filepath.Join(dir, "f.txt")
+	mustWrite(t, p, "local")
+	local := readFileMTimeMillis(t, p)
+	withSyncTransport(t, "remote")
+
+	caller := syncCaller(map[string]string{
+		"ROOT": `{"result":{"items":[{"name":"f.txt","type":"file","fileId":"F","modifyTime":` +
+			differentMillis(local) + `}],"nextToken":""}}`,
+	})
+	if err := runDriveCmd(t, caller, "sync", "--local-folder", dir, "--remote-folder", "ROOT",
+		"--quick", "--on-conflict", "ask"); err == nil {
+		t.Fatal("expected invalid ask choice to abort sync")
+	}
+}
+
+// ask 选 keep-both：本地改名保留副本，远端拉到原名。
+func TestCrossPlatformCoverageDriveSync_askKeepBothViaStdin(t *testing.T) {
+	testseam.Swap(t, &syncAskStdin, io.Reader(strings.NewReader("k\n")))
+
+	dir := t.TempDir()
+	p := filepath.Join(dir, "f.txt")
+	mustWrite(t, p, "local-version")
+	local := readFileMTimeMillis(t, p)
+	withSyncTransport(t, "remote-version")
+
+	caller := syncCaller(map[string]string{
+		"ROOT": `{"result":{"items":[{"name":"f.txt","type":"file","fileId":"FID12345678","modifyTime":` +
+			differentMillis(local) + `}],"nextToken":""}}`,
+	})
+	if err := runDriveCmd(t, caller, "sync", "--local-folder", dir, "--remote-folder", "ROOT",
+		"--quick", "--on-conflict", "ask"); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if b, _ := os.ReadFile(p); string(b) != "remote-version" {
+		t.Errorf("original path must hold the remote version, got %q", string(b))
+	}
+	// 本地副本以 .conflict-<fileId 末 8 位> 保留。
+	entries, _ := os.ReadDir(dir)
+	var found bool
+	for _, e := range entries {
+		if strings.Contains(e.Name(), ".conflict-") {
+			found = true
+			if b, _ := os.ReadFile(filepath.Join(dir, e.Name())); string(b) != "local-version" {
+				t.Errorf("conflict copy content = %q, want local-version", string(b))
+			}
+		}
+	}
+	if !found {
+		t.Errorf("no .conflict-* copy kept, dir = %v", entries)
+	}
+}
+
+// keep-both 改名失败（目标被目录占位）→ 记 failed，本地原文件保持不动。
+func TestCrossPlatformCoverageDriveSync_keepBothRenameFailureKeepsLocal(t *testing.T) {
+	dir := t.TempDir()
+	p := filepath.Join(dir, "f.txt")
+	mustWrite(t, p, "local-version")
+	local := readFileMTimeMillis(t, p)
+	withSyncTransport(t, "remote-version")
+
+	// 让候选改名目标 f.conflict-FID12345.txt 被一个目录占住 → O_EXCL 建占位失败。
+	if err := os.MkdirAll(filepath.Join(dir, "f.conflict-ID123456.txt"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+
+	caller := syncCaller(map[string]string{
+		"ROOT": `{"result":{"items":[{"name":"f.txt","type":"file","fileId":"FID123456","modifyTime":` +
+			differentMillis(local) + `}],"nextToken":""}}`,
+	})
+	// 无论走到哪个失败分支，本地原文件都不能被破坏。
+	_ = runDriveCmd(t, caller, "sync", "--local-folder", dir, "--remote-folder", "ROOT",
+		"--quick", "--on-conflict", "keep-both")
+	if _, err := os.Stat(p); err != nil {
+		t.Fatalf("local file must still exist: %v", err)
+	}
+}
+
+// ──────────────────────────────────────────────────────────
+// dry-run 与 unknown 组合
+// ──────────────────────────────────────────────────────────
+
+// dry-run 下即使有 new_local / new_remote / modified 也不产生任何写调用。
+func TestCrossPlatformCoverageDriveSync_dryRunSkipsEveryWrite(t *testing.T) {
+	dir := t.TempDir()
+	mustWrite(t, filepath.Join(dir, "local.txt"), "l")
+	p := filepath.Join(dir, "both.txt")
+	mustWrite(t, p, "local")
+	local := readFileMTimeMillis(t, p)
+	withSyncTransport(t, "remote")
+
+	caller := syncCaller(map[string]string{
+		"ROOT": `{"result":{"items":[` +
+			`{"name":"both.txt","type":"file","fileId":"B","modifyTime":` + differentMillis(local) + `},` +
+			`{"name":"remote.txt","type":"file","fileId":"R","modifyTime":2000}` +
+			`],"nextToken":""}}`,
+	})
+	caller.dryRun = true
+
+	if err := runDriveCmd(t, caller, "sync", "--local-folder", dir, "--remote-folder", "ROOT", "--quick"); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if got := len(caller.callsFor("download_file")) + len(caller.callsFor("get_upload_info")) +
+		len(caller.callsFor("create_folder")); got != 0 {
+		t.Errorf("dry-run must not write, got %d calls", got)
+	}
+	if _, err := os.Stat(filepath.Join(dir, "remote.txt")); !os.IsNotExist(err) {
+		t.Error("dry-run must not materialize remote files locally")
+	}
+}
+
+// 远端列举失败 → sync 直接报错。
+func TestCrossPlatformCoverageDriveSync_remoteListFailurePropagates(t *testing.T) {
+	caller := &driveScriptCaller{reply: func(string, map[string]any, int) (string, error) { return "", errTestList }}
+	if err := runDriveCmd(t, caller, "sync", "--local-folder", t.TempDir(), "--remote-folder", "ROOT"); err == nil {
+		t.Fatal("expected remote listing failure to propagate")
+	}
+}
+
+// 本地根目录不存在 → 扫描失败上抛。
+func TestCrossPlatformCoverageDriveSync_missingLocalRootFails(t *testing.T) {
+	missing := filepath.Join(t.TempDir(), "absent")
+	if err := runDriveCmd(t, syncCaller(nil), "sync", "--local-folder", missing, "--remote-folder", "ROOT"); err == nil {
+		t.Fatal("expected missing local root to fail")
+	}
+}

internal/helpers/drive_sync_edges_test.go

@@ -0,0 +1,295 @@
+package helpers
+
+import (
+	"context"
+	"errors"
+	"io"
+	"os"
+	"path/filepath"
+	"runtime"
+	"strings"
+	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam"
+	"github.com/spf13/cobra"
+)
+
+var errTestRead = errors.New("simulated read failure")
+
+// errReader 让 bufio 读取返回非 EOF 错误，覆盖 ask 的读取失败分支。
+type errReader struct{}
+
+func (errReader) Read([]byte) (int, error) { return 0, errTestRead }
+
+// findDriveSubcommand 取出 drive 下的指定子命令，便于直接调用其 RunE。
+func findDriveSubcommand(t *testing.T, name string) *cobra.Command {
+	t.Helper()
+	for _, c := range newDriveCommand().Commands() {
+		if c.Name() == name {
+			return c
+		}
+	}
+	t.Fatalf("drive subcommand %q not found", name)
+	return nil
+}
+
+// mustSetFlags 设置一组 flag，任何失败都直接终止用例。
+func mustSetFlags(t *testing.T, cmd *cobra.Command, kv map[string]string) {
+	t.Helper()
+	for k, v := range kv {
+		if err := cmd.Flags().Set(k, v); err != nil {
+			t.Fatalf("set --%s=%s: %v", k, v, err)
+		}
+	}
+}
+
+// ──────────────────────────────────────────────────────────
+// --if-exists 显式空值回落默认
+// ──────────────────────────────────────────────────────────
+
+func TestCrossPlatformCoverageDrivePull_emptyIfExistsDefaultsToSkip(t *testing.T) {
+	root := t.TempDir()
+	p := filepath.Join(root, "a.txt")
+	mustWrite(t, p, "local-old")
+	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("remote-new"), 0o644)
+	})
+
+	if err := runDriveCmd(t, caller, "pull", "--local-folder", root, "--remote-folder", "ROOT", "--if-exists", ""); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if b, _ := os.ReadFile(p); string(b) != "local-old" {
+		t.Errorf("empty --if-exists must default to skip and keep the local file, got %q", string(b))
+	}
+}
+
+func TestCrossPlatformCoverageDrivePush_emptyIfExistsDefaultsToSkip(t *testing.T) {
+	dir := t.TempDir()
+	mustWrite(t, filepath.Join(dir, "a.txt"), "local")
+	withNoopPut(t)
+
+	caller := pushOKCaller(map[string]string{
+		"ROOT": `{"result":{"items":[{"name":"a.txt","type":"file","fileId":"A","modifyTime":1}],"nextToken":""}}`,
+	})
+	if err := runDriveCmd(t, caller, "push", "--local-folder", dir, "--remote-folder", "ROOT", "--if-exists", ""); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if got := caller.callsFor("get_upload_info"); len(got) != 0 {
+		t.Errorf("empty --if-exists must behave as skip, got %v", got)
+	}
+}
+
+// ──────────────────────────────────────────────────────────
+// pullOneFile 的落盘失败分支
+// ──────────────────────────────────────────────────────────
+
+// 目标目录不可写 → 创建临时文件失败。
+func TestCrossPlatformCoveragePullOneFile_tempFileCreationFailure(t *testing.T) {
+	root := t.TempDir()
+	testseam.Swap(t, &pullCreateTemp, func(*os.Root) (*os.File, string, error) {
+		return nil, "", errors.New("create temp boom")
+	})
+
+	testseam.Swap(t, &deps, &Deps{Caller: pullListingCaller(""), Out: &Formatter{w: io.Discard}})
+	testseam.Swap(t, &os.Args, []string{"dws", "drive"})
+
+	action, err := pullOneFile(context.Background(), "", &remoteFile{RelPath: "a.txt", FileID: "A"},
+		filepath.Join(root, "a.txt"), ifExistsOverwrite)
+	if action != pullActionFailed || err == nil {
+		t.Fatalf("action=%q err=%v, want failed + error", action, err)
+	}
+}
+
+// 目标路径是目录 → 最后的原子 rename 失败。
+func TestCrossPlatformCoveragePullOneFile_renameOntoDirectoryFails(t *testing.T) {
+	root := t.TempDir()
+	target := filepath.Join(root, "a.txt")
+	if err := os.MkdirAll(target, 0o755); err != nil { // 目标被目录占位
+		t.Fatal(err)
+	}
+
+	testseam.Swap(t, &deps, &Deps{Caller: pullListingCaller(""), 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("payload"), 0o644)
+	})
+
+	action, err := pullOneFile(context.Background(), "", &remoteFile{RelPath: "a.txt", FileID: "A"},
+		target, ifExistsOverwrite)
+	if action != pullActionFailed || err == nil {
+		t.Fatalf("action=%q err=%v, want failed + error", action, err)
+	}
+}
+
+// ──────────────────────────────────────────────────────────
+// PrintJSON 失败分支
+// ──────────────────────────────────────────────────────────
+
+func TestCrossPlatformCoverageDrivePull_printFailurePropagates(t *testing.T) {
+	dir := t.TempDir()
+
+	testseam.Swap(t, &deps, &Deps{Caller: pullListingCaller(""), Out: &Formatter{w: failingWriter{}}})
+	testseam.Swap(t, &os.Args, []string{"dws", "drive", "pull"})
+
+	cmd := findDriveSubcommand(t, "pull")
+	mustSetFlags(t, cmd, map[string]string{"local-folder": dir, "remote-folder": "ROOT"})
+	if err := runDrivePull(cmd, nil); err == nil {
+		t.Fatal("expected the PrintJSON writer failure to propagate")
+	}
+}
+
+func TestCrossPlatformCoverageDrivePush_printFailurePropagates(t *testing.T) {
+	dir := t.TempDir()
+	mustWrite(t, filepath.Join(dir, "a.txt"), "x")
+	withNoopPut(t)
+
+	testseam.Swap(t, &deps, &Deps{Caller: pushOKCaller(nil), Out: &Formatter{w: failingWriter{}}})
+	testseam.Swap(t, &os.Args, []string{"dws", "drive", "push"})
+
+	cmd := findDriveSubcommand(t, "push")
+	mustSetFlags(t, cmd, map[string]string{"local-folder": dir, "remote-folder": "ROOT"})
+	if err := runDrivePush(cmd, nil); err == nil {
+		t.Fatal("expected the PrintJSON writer failure to propagate")
+	}
+}
+
+func TestCrossPlatformCoverageDriveSync_printFailurePropagates(t *testing.T) {
+	dir := t.TempDir()
+	mustWrite(t, filepath.Join(dir, "a.txt"), "x")
+	testseam.Swap(t, &pushPutOpenedFile, func(context.Context, string, map[string]string, *os.File, int64) error { return nil })
+
+	testseam.Swap(t, &deps, &Deps{Caller: syncCaller(nil), Out: &Formatter{w: failingWriter{}}})
+	testseam.Swap(t, &os.Args, []string{"dws", "drive", "sync"})
+
+	cmd := findDriveSubcommand(t, "sync")
+	mustSetFlags(t, cmd, map[string]string{"local-folder": dir, "remote-folder": "ROOT", "quick": "true"})
+	if err := runDriveSync(cmd, nil); err == nil {
+		t.Fatal("expected the PrintJSON writer failure to propagate")
+	}
+}
+
+// ──────────────────────────────────────────────────────────
+// walkLocalForPush / walkLocalTree 的 WalkDir 错误回调
+// ──────────────────────────────────────────────────────────
+
+func TestCrossPlatformCoverageWalkLocal_unreadableSubdirectoryErrors(t *testing.T) {
+	if runtime.GOOS == "windows" || os.Geteuid() == 0 {
+		t.Skip("unreadable dir needs POSIX perms and a non-root user")
+	}
+	dir := t.TempDir()
+	sub := filepath.Join(dir, "locked")
+	if err := os.MkdirAll(sub, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	mustWrite(t, filepath.Join(sub, "inner.txt"), "x")
+	if err := os.Chmod(sub, 0o000); err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = os.Chmod(sub, 0o755) })
+
+	if _, _, err := walkLocalForPush(dir); err == nil {
+		t.Error("walkLocalForPush must surface the WalkDir error")
+	}
+	if _, err := walkLocalTree(dir); err == nil {
+		t.Error("walkLocalTree must surface the WalkDir error")
+	}
+}
+
+// ──────────────────────────────────────────────────────────
+// verifyNoSymlinkEscape 的剩余分支
+// ──────────────────────────────────────────────────────────
+
+// 目标位于 absDir 之外 → 走到根目录之上即放行（不是逃逸判定范围）。
+func TestCrossPlatformCoverageVerifyNoSymlinkEscape_targetOutsideRootIsIgnored(t *testing.T) {
+	root := t.TempDir()
+	outside := filepath.Join(t.TempDir(), "elsewhere", "x.txt")
+	if err := verifyNoSymlinkEscape(root, outside); err != nil {
+		t.Errorf("target above the root must be ignored, got %v", err)
+	}
+}
+
+// 已存在路径含符号链接环 → EvalSymlinks 失败要如实上报。
+func TestCrossPlatformCoverageVerifyNoSymlinkEscape_symlinkLoopErrors(t *testing.T) {
+	root := t.TempDir()
+	loop := filepath.Join(root, "loop")
+	if err := os.Symlink(loop, loop); err != nil {
+		t.Skipf("self-symlink unsupported: %v", err)
+	}
+	err := verifyNoSymlinkEscape(root, filepath.Join(loop, "child.txt"))
+	if err == nil || !strings.Contains(err.Error(), "解析路径") {
+		t.Fatalf("expected EvalSymlinks failure, got %v", err)
+	}
+}
+
+// ──────────────────────────────────────────────────────────
+// reserveSyncKeepBothTarget 的失败分支
+// ──────────────────────────────────────────────────────────
+
+// 候选目标逃逸出本地根（父目录是指向外部的软链）→ 直接失败。
+func TestCrossPlatformCoverageReserveSyncKeepBothTarget_escapeFails(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)
+	}
+	if _, _, err := reserveSyncKeepBothTarget(root, "sub/f.txt", "FID12345678", map[string]bool{}); err == nil {
+		t.Fatal("expected escaping keep-both target to fail")
+	}
+}
+
+// 候选硬链接创建返回非 EEXIST 错误时直接上报。
+func TestCrossPlatformCoverageReserveSyncKeepBothTarget_unwritableDirFails(t *testing.T) {
+	root := t.TempDir()
+	mustWrite(t, filepath.Join(root, "f.txt"), "local")
+	testseam.Swap(t, &syncRootLink, func(*os.Root, string, string) error {
+		return errors.New("link boom")
+	})
+
+	if _, _, err := reserveSyncKeepBothTarget(root, "f.txt", "FID12345678", map[string]bool{}); err == nil {
+		t.Fatal("expected unwritable directory to fail")
+	}
+}
+
+// occupied 中已知占用的首选候选被跳过，改用下一个后缀。
+func TestCrossPlatformCoverageReserveSyncKeepBothTarget_skipsKnownOccupied(t *testing.T) {
+	root := t.TempDir()
+	mustWrite(t, filepath.Join(root, "f.txt"), "local")
+	first := syncKeepBothCandidate("f.txt", "FID12345678", 0)
+	occupied := map[string]bool{first: true}
+
+	got, _, err := reserveSyncKeepBothTarget(root, "f.txt", "FID12345678", occupied)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if got == first {
+		t.Errorf("known-occupied candidate %q must be skipped", first)
+	}
+}
+
+// ──────────────────────────────────────────────────────────
+// ask 读取失败（非 EOF）
+// ──────────────────────────────────────────────────────────
+
+func TestCrossPlatformCoverageDriveSyncAskConflict_readErrorPropagates(t *testing.T) {
+	testseam.Swap(t, &syncAskStdin, io.Reader(errReader{}))
+
+	if _, err := driveSyncAskConflict("f.txt"); err == nil {
+		t.Fatal("expected read failure to propagate")
+	}
+}
+
+// ──────────────────────────────────────────────────────────
+// sync：本地根不可创建
+// ──────────────────────────────────────────────────────────
+
+// --local-folder 指向一个常规文件 → MkdirAll 失败。
+func TestCrossPlatformCoverageDriveSync_localRootIsFileFails(t *testing.T) {
+	dir := t.TempDir()
+	asFile := filepath.Join(dir, "not-a-dir")
+	mustWrite(t, asFile, "x")
+
+	if err := runDriveCmd(t, syncCaller(nil), "sync", "--local-folder", asFile, "--remote-folder", "ROOT", "--quick"); err == nil {
+		t.Fatal("expected a regular-file local root to fail")
+	}
+}

internal/helpers/drive_sync_gaps_test.go

@@ -0,0 +1,107 @@
+package helpers
+
+import (
+	"context"
+	"io"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam"
+)
+
+// 本文件补齐几条在默认策略改为 skip 后失去覆盖的边界分支。
+
+// pull 自动创建目标根失败（--local-folder 指向一个常规文件）→ 明确报错，不落盘。
+func TestCrossPlatformCoverageDrivePull_localRootIsFileFails(t *testing.T) {
+	dir := t.TempDir()
+	asFile := filepath.Join(dir, "not-a-dir")
+	mustWrite(t, asFile, "x")
+
+	caller := pullListingCaller(`{"name":"a.txt","type":"file","fileId":"A","modifyTime":1}`)
+	err := runDriveCmd(t, caller, "pull", "--local-folder", asFile, "--remote-folder", "ROOT")
+	if err == nil || !strings.Contains(err.Error(), "创建本地目录失败") {
+		t.Fatalf("expected local root creation failure, got %v", err)
+	}
+}
+
+// push 遍历远端时 list_files 在**子目录**层失败 → 错误如实上抛（walkRemoteForPush 的递归错误分支）。
+func TestCrossPlatformCoverageDrivePush_remoteSubdirListFailurePropagates(t *testing.T) {
+	dir := t.TempDir()
+	mustWrite(t, filepath.Join(dir, "a.txt"), "x")
+	withNoopPut(t)
+
+	caller := &driveScriptCaller{reply: func(tool string, args map[string]any, _ int) (string, error) {
+		if tool != "list_files" {
+			return `{"result":{},"success":true}`, nil
+		}
+		switch args["parentId"] {
+		case "ROOT":
+			return `{"result":{"items":[{"name":"sub","type":"folder","fileId":"SUB"}],"nextToken":""}}`, nil
+		default:
+			return "", errTestList // 递归进入子目录后失败
+		}
+	}}
+	if err := runDriveCmd(t, caller, "push", "--local-folder", dir, "--remote-folder", "ROOT"); err == nil {
+		t.Fatal("expected the nested list_files failure to propagate")
+	}
+}
+
+// push 的远端索引跳过非 file 类型（在线文档/快捷方式），不把它们当成可覆盖的既有文件。
+func TestCrossPlatformCoverageDrivePush_remoteNonFileEntriesAreSkipped(t *testing.T) {
+	caller := &driveScriptCaller{reply: func(tool string, args map[string]any, _ int) (string, error) {
+		if tool != "list_files" {
+			return `{"result":{},"success":true}`, nil
+		}
+		if args["parentId"] == "ROOT" {
+			return `{"result":{"items":[` +
+				`{"name":"online.adoc","type":"document","fileId":"D1"},` +
+				`{"name":"link","type":"shortcut","fileId":"S1"},` +
+				`{"name":"real.txt","type":"file","fileId":"F1"}` +
+				`],"nextToken":""}}`, nil
+		}
+		return `{"result":{"items":[],"nextToken":""}}`, nil
+	}}
+
+	testseam.Swap(t, &deps, &Deps{Caller: caller, Out: &Formatter{w: io.Discard}})
+	testseam.Swap(t, &os.Args, []string{"dws", "drive"})
+
+	files, _, err := fetchRemoteTreeForPush(context.Background(), "", "ROOT")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if _, ok := files["real.txt"]; !ok {
+		t.Error("regular file must be indexed")
+	}
+	for _, skipped := range []string{"online.adoc", "link"} {
+		if _, ok := files[skipped]; ok {
+			t.Errorf("non-file entry %q must not be indexed", skipped)
+		}
+	}
+}
+
+// list_files 是远端权威树的数据来源；缺失 result 不能伪装成空目录。
+func TestCrossPlatformCoverageParseDriveList_missingResultFailsClosed(t *testing.T) {
+	if _, _, err := parseDriveList(`{"success":true}`); err == nil || !strings.Contains(err.Error(), "缺少 result") {
+		t.Fatalf("parseDriveList error = %v, want missing-result failure", err)
+	}
+}
+
+// push 遍历远端时返回体无法解析 → 解析错误如实上抛（与调用失败是不同分支）。
+func TestCrossPlatformCoverageDrivePush_remoteListParseFailurePropagates(t *testing.T) {
+	dir := t.TempDir()
+	mustWrite(t, filepath.Join(dir, "a.txt"), "x")
+	withNoopPut(t)
+
+	caller := &driveScriptCaller{reply: func(tool string, _ map[string]any, _ int) (string, error) {
+		if tool != "list_files" {
+			return `{"result":{},"success":true}`, nil
+		}
+		return `{"result":"not-a-list"}`, nil // 既不是 {items:[]} 也不是数组
+	}}
+	err := runDriveCmd(t, caller, "push", "--local-folder", dir, "--remote-folder", "ROOT")
+	if err == nil || !strings.Contains(err.Error(), "list_files") {
+		t.Fatalf("expected a list_files parse error, got %v", err)
+	}
+}

internal/helpers/drive_sync_platform_test.go

@@ -0,0 +1,236 @@
+package helpers
+
+import (
+	"context"
+	"errors"
+	"io/fs"
+	"os"
+	"path/filepath"
+	"runtime"
+	"testing"
+	"time"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam"
+)
+
+// forceCaseInsensitiveFS 在当前用例内把大小写探测钉成不敏感，使等价路径冲突分支
+// 在大小写敏感的 CI 文件系统（ext4）上同样可达。
+func forceCaseInsensitiveFS(t *testing.T) {
+	t.Helper()
+	testseam.Swap(t, &isCaseInsensitiveFS, func(string) bool { return true })
+}
+
+// ──────────────────────────────────────────────────────────
+// 等价路径冲突：pull / sync 都必须全部记 failed 且一个都不落盘
+// ──────────────────────────────────────────────────────────
+
+// 远端 A.txt 与 a.txt 在大小写不敏感目标上映射到同一本地文件 → 两项都 failed，
+// 绝不顺序覆盖导致静默丢文件。
+func TestCrossPlatformCoverageDrivePull_equivalentPathCollisionFailsBoth(t *testing.T) {
+	forceCaseInsensitiveFS(t)
+	root := t.TempDir()
+
+	caller := pullListingCaller(
+		`{"name":"A.txt","type":"file","fileId":"UP","modifyTime":1},` +
+			`{"name":"a.txt","type":"file","fileId":"LOW","modifyTime":2}`)
+	swapPullDownloadPath(t, func(context.Context, string, map[string]string, string) error {
+		t.Error("collided entries must not be downloaded")
+		return nil
+	})
+
+	err := runDriveCmd(t, caller, "pull", "--local-folder", root, "--remote-folder", "ROOT")
+	var pf *drivePartialFailure
+	if !errors.As(err, &pf) {
+		t.Fatalf("expected drivePartialFailure, got %T %v", err, err)
+	}
+	for _, name := range []string{"A.txt", "a.txt"} {
+		if _, statErr := os.Stat(filepath.Join(root, name)); !os.IsNotExist(statErr) {
+			t.Errorf("%s must not be written on collision", name)
+		}
+	}
+}
+
+// sync 的 new_remote 阶段同样拒绝等价冲突项。
+func TestCrossPlatformCoverageDriveSync_equivalentPathCollisionFailsBoth(t *testing.T) {
+	forceCaseInsensitiveFS(t)
+	root := t.TempDir()
+	withSyncTransport(t, "remote")
+
+	caller := syncCaller(map[string]string{
+		"ROOT": `{"result":{"items":[` +
+			`{"name":"A.txt","type":"file","fileId":"UP","modifyTime":1},` +
+			`{"name":"a.txt","type":"file","fileId":"LOW","modifyTime":2}` +
+			`],"nextToken":""}}`,
+	})
+	err := runDriveCmd(t, caller, "sync", "--local-folder", root, "--remote-folder", "ROOT", "--quick")
+	var sf *driveSyncFailure
+	if !errors.As(err, &sf) {
+		t.Fatalf("expected driveSyncFailure, got %T %v", err, err)
+	}
+	if sf.failed != 2 {
+		t.Errorf("failed = %d, want 2 (both collided entries)", sf.failed)
+	}
+}
+
+// ──────────────────────────────────────────────────────────
+// detectCaseInsensitiveFS：探针名无大小写差异时回退平台默认
+// ──────────────────────────────────────────────────────────
+
+func TestCrossPlatformCoverageDetectCaseInsensitiveFS_caselessProbeFallsBackToPlatformDefault(t *testing.T) {
+	// 纯数字模板：ToUpper 与原名相同，无法据此判定。
+	testseam.Swap(t, &caseProbePattern, "1234567890*")
+
+	dir := t.TempDir()
+	got := detectCaseInsensitiveFS(dir)
+	// 回退值即平台默认；这里只断言它与平台默认一致，不写死具体布尔。
+	want := runtime.GOOS == "windows" || runtime.GOOS == "darwin"
+	if got != want {
+		t.Errorf("detectCaseInsensitiveFS = %v, want platform default %v", got, want)
+	}
+}
+
+// ──────────────────────────────────────────────────────────
+// isSafeRemoteSegmentPlatform：非 Windows 平台无额外约束
+// ──────────────────────────────────────────────────────────
+
+func TestCrossPlatformCoverageIsSafeRemoteSegmentPlatform_allowsPlainNames(t *testing.T) {
+	for _, name := range []string{"a.txt", "报告.pdf", "with space.md"} {
+		if !isSafeRemoteSegmentPlatform(name) {
+			t.Errorf("isSafeRemoteSegmentPlatform(%q) = false, want true", name)
+		}
+	}
+}
+
+func TestCrossPlatformCoverageIsSafeRemoteSegmentPlatform_rejectsNonCanonicalWindowsName(t *testing.T) {
+	if runtime.GOOS != "windows" {
+		return
+	}
+	for _, name := range []string{
+		`C:relative`, `a?.txt`, `a*.txt`, `a:stream`, `a<.txt`, `a>.txt`, `a|.txt`, `a".txt`,
+		"name.", "name ", "...", "CON", "con.txt", "PRN", "AUX", "NUL", "COM1", "LPT9", "COM¹", "CONIN$",
+		// 调用方 isSafeRemoteSegment 已先过滤分隔符，所以只有直接调用才会走到
+		// filepath.Clean 改写这条防御分支；平台函数本身仍必须 fail closed。
+		`a/b`, `.\a`,
+	} {
+		if isSafeRemoteSegmentPlatform(name) {
+			t.Errorf("Windows unsafe segment %q must be rejected", name)
+		}
+	}
+	for _, name := range []string{"report.txt", "报告 2026.pdf", "COM10", "LPT0"} {
+		if !isSafeRemoteSegmentPlatform(name) {
+			t.Errorf("Windows ordinary segment %q must be accepted", name)
+		}
+	}
+}
+
+// ──────────────────────────────────────────────────────────
+// WalkDir 单条目处理：Info() 与 filepath.Rel 的失败分支
+// ──────────────────────────────────────────────────────────
+
+// errDirEntry 是一个 Info() 必然报错的 fs.DirEntry。
+type errDirEntry struct{ dir bool }
+
+func (e errDirEntry) Name() string               { return "entry" }
+func (e errDirEntry) IsDir() bool                { return e.dir }
+func (e errDirEntry) Type() fs.FileMode          { return 0 }
+func (e errDirEntry) Info() (fs.FileInfo, error) { return nil, errTestInfo }
+
+var errTestInfo = errors.New("simulated DirEntry.Info failure")
+
+// irregularDirEntry 的 Info() 成功，但报告为非常规文件（如设备文件）。
+type irregularDirEntry struct{}
+
+func (irregularDirEntry) Name() string               { return "dev" }
+func (irregularDirEntry) IsDir() bool                { return false }
+func (irregularDirEntry) Type() fs.FileMode          { return fs.ModeDevice }
+func (irregularDirEntry) Info() (fs.FileInfo, error) { return irregularFileInfo{}, nil }
+
+type irregularFileInfo struct{}
+
+func (irregularFileInfo) Name() string       { return "dev" }
+func (irregularFileInfo) Size() int64        { return 0 }
+func (irregularFileInfo) Mode() fs.FileMode  { return fs.ModeDevice }
+func (irregularFileInfo) ModTime() time.Time { return time.Unix(0, 0) }
+func (irregularFileInfo) IsDir() bool        { return false }
+func (irregularFileInfo) Sys() any           { return nil }
+
+func TestCrossPlatformCoverageWalkLocalTreeEntry_errorBranches(t *testing.T) {
+	files := map[string]*localFile{}
+
+	// WalkDir 自身报错原样上抛。
+	if err := walkLocalTreeEntry("/root", "/root/a", errDirEntry{}, errTestInfo, files); !errors.Is(err, errTestInfo) {
+		t.Errorf("incoming error must propagate, got %v", err)
+	}
+	// 目录条目直接跳过。
+	if err := walkLocalTreeEntry("/root", "/root/sub", errDirEntry{dir: true}, nil, files); err != nil {
+		t.Errorf("directory entry must be skipped, got %v", err)
+	}
+	// Info() 失败上抛。
+	if err := walkLocalTreeEntry("/root", "/root/a", errDirEntry{}, nil, files); !errors.Is(err, errTestInfo) {
+		t.Errorf("Info() error must propagate, got %v", err)
+	}
+	// 非常规文件忽略。
+	if err := walkLocalTreeEntry("/root", "/root/dev", irregularDirEntry{}, nil, files); err != nil {
+		t.Errorf("irregular entry must be skipped, got %v", err)
+	}
+	// filepath.Rel 失败（root 绝对、path 相对）上抛。
+	if err := walkLocalTreeEntry("/root", "relative/path", regularDirEntry{}, nil, files); err == nil {
+		t.Error("filepath.Rel error must propagate")
+	}
+	if len(files) != 0 {
+		t.Errorf("no entry should have been indexed, got %v", files)
+	}
+}
+
+// regularDirEntry 的 Info() 返回一个常规文件，用于走到 filepath.Rel。
+type regularDirEntry struct{}
+
+func (regularDirEntry) Name() string               { return "a" }
+func (regularDirEntry) IsDir() bool                { return false }
+func (regularDirEntry) Type() fs.FileMode          { return 0 }
+func (regularDirEntry) Info() (fs.FileInfo, error) { return regularFileInfo{}, nil }
+
+type regularFileInfo struct{}
+
+func (regularFileInfo) Name() string       { return "a" }
+func (regularFileInfo) Size() int64        { return 1 }
+func (regularFileInfo) Mode() fs.FileMode  { return 0o644 }
+func (regularFileInfo) ModTime() time.Time { return time.Unix(1, 0) }
+func (regularFileInfo) IsDir() bool        { return false }
+func (regularFileInfo) Sys() any           { return nil }
+
+func TestCrossPlatformCoverageWalkLocalForPushEntry_errorBranches(t *testing.T) {
+	var dirs []string
+	var files []localPushFile
+
+	// WalkDir 自身报错原样上抛。
+	if err := walkLocalForPushEntry("/root", "/root/a", regularDirEntry{}, errTestInfo, &dirs, &files); !errors.Is(err, errTestInfo) {
+		t.Errorf("incoming error must propagate, got %v", err)
+	}
+	// filepath.Rel 失败上抛。
+	if err := walkLocalForPushEntry("/root", "relative/path", regularDirEntry{}, nil, &dirs, &files); err == nil {
+		t.Error("filepath.Rel error must propagate")
+	}
+	// 根目录本身跳过。
+	if err := walkLocalForPushEntry("/root", "/root", regularDirEntry{}, nil, &dirs, &files); err != nil {
+		t.Errorf("root itself must be skipped, got %v", err)
+	}
+	// Info() 失败上抛。
+	if err := walkLocalForPushEntry("/root", "/root/a", errDirEntry{}, nil, &dirs, &files); !errors.Is(err, errTestInfo) {
+		t.Errorf("Info() error must propagate, got %v", err)
+	}
+	// 非常规文件忽略。
+	if err := walkLocalForPushEntry("/root", "/root/dev", irregularDirEntry{}, nil, &dirs, &files); err != nil {
+		t.Errorf("irregular entry must be skipped, got %v", err)
+	}
+	// 目录条目进 dirs。
+	if err := walkLocalForPushEntry("/root", "/root/sub", errDirEntry{dir: true}, nil, &dirs, &files); err != nil {
+		t.Errorf("directory entry must be recorded, got %v", err)
+	}
+	if len(dirs) != 1 || dirs[0] != "sub" {
+		t.Errorf("dirs = %v, want [sub]", dirs)
+	}
+	if len(files) != 0 {
+		t.Errorf("files = %v, want empty", files)
+	}
+}

internal/helpers/drive_sync_test.go

@@ -0,0 +1,443 @@
+package helpers
+
+import (
+	"context"
+	"errors"
+	"io"
+	"os"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam"
+	"github.com/spf13/cobra"
+)
+
+// errTestDownload 用于模拟 httpGetFile 下载失败。
+var errTestDownload = errors.New("simulated download failure")
+
+// swapPullDownloadPath 为存量测试保留基于路径的传输模拟写法。
+// 生产 pull/sync 始终把已由 os.Root 安全打开的句柄交给 pullDownloadFile；
+// 只有测试适配层才把该句柄的名称传给旧 callback。
+func swapPullDownloadPath(t *testing.T, fn func(context.Context, string, map[string]string, string) error) {
+	t.Helper()
+	testseam.Swap(t, &pullDownloadFile, func(ctx context.Context, url string, headers map[string]string, destination *os.File) error {
+		return fn(ctx, url, headers, destination.Name())
+	})
+}
+
+// ──────────────────────────────────────────────────────────
+// driveSyncFailure — sync 部分失败错误：exit=1
+// ──────────────────────────────────────────────────────────
+
+func TestCrossPlatformCoverageDriveSyncFailure(t *testing.T) {
+	e := &driveSyncFailure{failed: 2}
+	if e.ExitCode() != 1 {
+		t.Errorf("ExitCode() = %d, want 1", e.ExitCode())
+	}
+	if e.Error() != e.RawStderr() {
+		t.Error("Error() 与 RawStderr() 应一致")
+	}
+	if !strings.Contains(e.Error(), "2") {
+		t.Errorf("Error() 应包含失败数, got %q", e.Error())
+	}
+}
+
+// ──────────────────────────────────────────────────────────
+// driveSyncSuffixedRel — keep-both 本地重命名目标生成
+// ──────────────────────────────────────────────────────────
+
+func TestCrossPlatformCoverageDriveSyncSuffixedRel(t *testing.T) {
+	// 基本：扩展名前插入基于 fileId 末 8 位的后缀。
+	got := driveSyncSuffixedRel("a/b.txt", "0123456789ABCDEF", map[string]bool{})
+	if want := "a/b.conflict-89ABCDEF.txt"; got != want {
+		t.Errorf("suffixed = %q, want %q", got, want)
+	}
+
+	// 根目录下、无扩展名。
+	if got := driveSyncSuffixedRel("readme", "", map[string]bool{}); got != "readme.conflict" {
+		t.Errorf("suffixed = %q, want readme.conflict", got)
+	}
+
+	// 首选目标已被占用时追加序号，直到不冲突。
+	occupied := map[string]bool{
+		"x.conflict-FID.log":   true,
+		"x.conflict-FID.0.log": true,
+	}
+	got = driveSyncSuffixedRel("x.log", "FID", occupied)
+	if want := "x.conflict-FID.1.log"; got != want {
+		t.Errorf("suffixed with collisions = %q, want %q", got, want)
+	}
+}
+
+// ──────────────────────────────────────────────────────────
+// sync 双向流程 — new_local 上传 / new_remote 下载
+// ──────────────────────────────────────────────────────────
+
+// runDriveSyncTest 用 mock caller 执行 `drive sync`，注入 opened-file PUT / GET 为
+// 可控 no-op，避免真实 OSS 传输。返回 root.Execute() 的结果。
+func runDriveSyncTest(t *testing.T, caller *driveSyncMockCaller, localDir string, args ...string) error {
+	// 默认下载：把远端内容写到目标路径，模拟成功落盘。
+	return runDriveSyncTestWithGet(t, caller, func(_ context.Context, _ string, _ map[string]string, dest string) error {
+		return os.WriteFile(dest, []byte("remote-content"), 0o644)
+	}, localDir, args...)
+}
+
+// runDriveSyncTestWithGet 同上，但允许自定义 httpGetFile 行为（例如模拟下载失败）。
+func runDriveSyncTestWithGet(t *testing.T, caller *driveSyncMockCaller, getFn func(context.Context, string, map[string]string, string) error, localDir string, args ...string) error {
+	t.Helper()
+
+	testseam.Swap(t, &pushPutOpenedFile, func(context.Context, string, map[string]string, *os.File, int64) error { return nil })
+	swapPullDownloadPath(t, getFn)
+	testseam.Swap(t, &deps, &Deps{Caller: caller, Out: &Formatter{w: io.Discard}})
+
+	root := &cobra.Command{Use: "dws"}
+	root.PersistentFlags().BoolP("yes", "y", false, "")
+	root.PersistentFlags().Bool("dry-run", false, "")
+	root.AddCommand(newDriveCommand())
+
+	// sync 是 user_required 叶子，非交互环境需 --yes 才能越过统一确认门。
+	full := append([]string{"sync", "--local-folder", localDir, "--remote-folder", "ROOT", "--yes"}, args...)
+	testseam.Swap(t, &os.Args, append([]string{"dws", "drive"}, full...))
+	root.SetArgs(append([]string{"drive"}, full...))
+
+	return root.Execute()
+}
+
+// 双向：本地独有 local.txt 应上传；远端独有 remote.txt 应下载到本地。
+func TestCrossPlatformCoverageDriveSync_bidirectional(t *testing.T) {
+	dir := t.TempDir()
+	mustWrite(t, filepath.Join(dir, "local.txt"), "local-only")
+
+	caller := &driveSyncMockCaller{
+		// 远端仅有 remote.txt（本地不存在）→ new_remote，应被下载。
+		listJSON: `{"result":{"items":[{"name":"remote.txt","type":"file","fileId":"R_FID","md5":"z","modifyTime":2000}],"nextToken":""}}`,
+	}
+	if err := runDriveSyncTest(t, caller, dir); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	// new_local：local.txt 走 get_upload_info（新建上传，传 parentId=ROOT、不传 overwriteFileId）。
+	up := caller.callsFor("get_upload_info")
+	if len(up) != 1 {
+		t.Fatalf("expected 1 get_upload_info call, got %d", len(up))
+	}
+	if got := up[0].args["parentId"]; got != "ROOT" {
+		t.Errorf("get_upload_info parentId = %v, want ROOT", got)
+	}
+	if _, ok := up[0].args["overwriteFileId"]; ok {
+		t.Error("新建上传不应传 overwriteFileId")
+	}
+
+	// new_remote：remote.txt 走 download_file，并已落盘到本地。
+	dl := caller.callsFor("download_file")
+	if len(dl) != 1 || dl[0].args["fileId"] != "R_FID" {
+		t.Fatalf("expected 1 download_file(fileId=R_FID), got %v", dl)
+	}
+	if _, err := os.Stat(filepath.Join(dir, "remote.txt")); err != nil {
+		t.Errorf("remote.txt 应被下载到本地: %v", err)
+	}
+}
+
+// modified + remote-wins：quick 模式下两侧 mtime 不同判为 modified，并显式拉取远端覆盖本地。
+func TestCrossPlatformCoverageDriveSync_modifiedRemoteWins(t *testing.T) {
+	dir := t.TempDir()
+	p := filepath.Join(dir, "f.txt")
+	mustWrite(t, p, "local-old")
+	// 本地 mtime 设为与远端不同，quick 模式判为 modified。
+	local := readFileMTimeMillis(t, p)
+
+	caller := &driveSyncMockCaller{
+		listJSON: `{"result":{"items":[{"name":"f.txt","type":"file","fileId":"F_FID","modifyTime":` +
+			differentMillis(local) + `}],"nextToken":""}}`,
+	}
+	if err := runDriveSyncTest(t, caller, dir, "--quick", "--on-conflict", "remote-wins"); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	// remote-wins → 下载覆盖本地，且不应发生上传。
+	if dl := caller.callsFor("download_file"); len(dl) != 1 || dl[0].args["fileId"] != "F_FID" {
+		t.Errorf("expected download_file(fileId=F_FID), got %v", dl)
+	}
+	if up := caller.callsFor("get_upload_info"); len(up) != 0 {
+		t.Errorf("remote-wins 不应上传, got %d get_upload_info calls", len(up))
+	}
+	if b, _ := os.ReadFile(p); string(b) != "remote-content" {
+		t.Errorf("本地文件应被远端内容覆盖, got %q", string(b))
+	}
+}
+
+// modified + local-wins：改用 local-wins 时应覆盖上传远端（传 overwriteFileId、不传 parentId）。
+func TestCrossPlatformCoverageDriveSync_modifiedLocalWins(t *testing.T) {
+	dir := t.TempDir()
+	p := filepath.Join(dir, "f.txt")
+	mustWrite(t, p, "local-new")
+	local := readFileMTimeMillis(t, p)
+
+	caller := &driveSyncMockCaller{
+		listJSON: `{"result":{"items":[{"name":"f.txt","type":"file","fileId":"F_FID","modifyTime":` +
+			differentMillis(local) + `}],"nextToken":""}}`,
+	}
+	if err := runDriveSyncTest(t, caller, dir, "--quick", "--on-conflict", "local-wins"); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	up := caller.callsFor("get_upload_info")
+	if len(up) != 1 {
+		t.Fatalf("expected 1 get_upload_info call, got %d", len(up))
+	}
+	if got := up[0].args["overwriteFileId"]; got != "F_FID" {
+		t.Errorf("local-wins 覆盖上传 overwriteFileId = %v, want F_FID", got)
+	}
+	if _, ok := up[0].args["parentId"]; ok {
+		t.Error("覆盖上传不应传 parentId")
+	}
+	if dl := caller.callsFor("download_file"); len(dl) != 0 {
+		t.Errorf("local-wins 不应下载, got %d download_file calls", len(dl))
+	}
+}
+
+func TestCrossPlatformCoverageDriveSyncRejectsUnknownCommitEffect(t *testing.T) {
+	for _, response := range []string{"", `{}`} {
+		t.Run(response, func(t *testing.T) {
+			dir := t.TempDir()
+			mustWrite(t, filepath.Join(dir, "local.txt"), "payload")
+			caller := &driveSyncMockCaller{
+				listJSON:   `{"result":{"items":[]}}`,
+				commitJSON: &response,
+			}
+			err, output, putCalls := runDriveMirrorUploadCommandCapture(t, "sync", caller, dir)
+			if err == nil {
+				t.Fatal("empty commit result must make sync exit non-zero")
+			}
+			if failure, ok := err.(*driveSyncFailure); !ok || failure.ExitCode() != 1 {
+				t.Fatalf("error=%T %v", err, err)
+			}
+			assertMirrorUploadFailedJSON(t, output)
+			if putCalls != 1 {
+				t.Fatalf("OSS PUT calls=%d, want exactly 1", putCalls)
+			}
+			if got := len(caller.callsFor("get_upload_info")); got != 1 {
+				t.Fatalf("get_upload_info calls=%d, want 1", got)
+			}
+			if got := len(caller.callsFor("commit_upload")); got != 1 {
+				t.Fatalf("commit_upload calls=%d, want 1", got)
+			}
+		})
+	}
+}
+
+// --dry-run：只计算差异，不触发任何 MCP 写操作与本地落盘。
+func TestCrossPlatformCoverageDriveSync_dryRun(t *testing.T) {
+	dir := t.TempDir()
+	mustWrite(t, filepath.Join(dir, "local.txt"), "x")
+
+	caller := &driveSyncMockCaller{
+		listJSON: `{"result":{"items":[{"name":"remote.txt","type":"file","fileId":"R_FID","modifyTime":2000}],"nextToken":""}}`,
+		dryRun:   true,
+	}
+	if err := runDriveSyncTest(t, caller, dir); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	if got := len(caller.callsFor("download_file")) + len(caller.callsFor("get_upload_info")); got != 0 {
+		t.Errorf("dry-run 不应触发下载/上传, got %d 次写操作调用", got)
+	}
+	if _, err := os.Stat(filepath.Join(dir, "remote.txt")); !os.IsNotExist(err) {
+		t.Error("dry-run 不应把远端文件落盘到本地")
+	}
+}
+
+// remote-wins 下载失败：本地原文件必须原样保留（pullOneFile 先写临时文件、成功才原子
+// rename 覆盖），且命令以非零退出码退出。
+func TestCrossPlatformCoverageDriveSync_pullFailureKeepsLocal(t *testing.T) {
+	dir := t.TempDir()
+	p := filepath.Join(dir, "f.txt")
+	mustWrite(t, p, "local-original")
+	local := readFileMTimeMillis(t, p)
+
+	caller := &driveSyncMockCaller{
+		listJSON: `{"result":{"items":[{"name":"f.txt","type":"file","fileId":"F_FID","modifyTime":` +
+			differentMillis(local) + `}],"nextToken":""}}`,
+	}
+	failGet := func(context.Context, string, map[string]string, string) error {
+		return errTestDownload
+	}
+	err := runDriveSyncTestWithGet(t, caller, failGet, dir, "--quick", "--on-conflict", "remote-wins")
+	if err == nil {
+		t.Fatal("下载失败时应以非零退出码退出")
+	}
+	if ec, ok := err.(*driveSyncFailure); !ok || ec.ExitCode() != 1 {
+		t.Fatalf("期望 driveSyncFailure(exit=1), got %T %v", err, err)
+	}
+	// 关键：原文件内容与存在性都不被破坏。
+	if b, rerr := os.ReadFile(p); rerr != nil || string(b) != "local-original" {
+		t.Errorf("下载失败后本地原文件应原样保留, got %q err=%v", string(b), rerr)
+	}
+}
+
+// keep-both 成功路径：先以 no-clobber 硬链接保留本地版本，再把远端拉取到原路径。
+func TestCrossPlatformCoverageDriveSync_keepBothSuccess(t *testing.T) {
+	dir := t.TempDir()
+	p := filepath.Join(dir, "f.txt")
+	mustWrite(t, p, "local-new")
+	local := readFileMTimeMillis(t, p)
+
+	caller := &driveSyncMockCaller{
+		listJSON: `{"result":{"items":[{"name":"f.txt","type":"file","fileId":"F_FID","modifyTime":` +
+			differentMillis(local) + `}],"nextToken":""}}`,
+	}
+	if err := runDriveSyncTest(t, caller, dir, "--quick", "--on-conflict", "keep-both"); err != nil {
+		t.Fatalf("keep-both 成功路径不应报错: %v", err)
+	}
+
+	// 原路径 f.txt 应为远端内容（拉取落盘）。
+	if b, _ := os.ReadFile(p); string(b) != "remote-content" {
+		t.Errorf("f.txt 应为远端内容, got %q", string(b))
+	}
+	// 本地版本改名保留为 f.conflict-F_FID.txt，内容不变。
+	aside := filepath.Join(dir, "f.conflict-F_FID.txt")
+	if b, err := os.ReadFile(aside); err != nil || string(b) != "local-new" {
+		t.Errorf("本地版本应改名保留为 %s 且内容不变, got %q err=%v", filepath.Base(aside), string(b), err)
+	}
+	// 下载发生一次（拉取远端到原路径），不应有上传。
+	if dl := caller.callsFor("download_file"); len(dl) != 1 {
+		t.Errorf("keep-both 应拉取远端一次, got %d download_file calls", len(dl))
+	}
+	if up := caller.callsFor("get_upload_info"); len(up) != 0 {
+		t.Errorf("keep-both 不应上传, got %d get_upload_info calls", len(up))
+	}
+}
+
+// keep-both 下载失败：不做可能误删并发文件的回滚，原名与本地保留候选都应保留。
+func TestCrossPlatformCoverageDriveSync_keepBothPreservesLinkOnPullFailure(t *testing.T) {
+	dir := t.TempDir()
+	p := filepath.Join(dir, "f.txt")
+	mustWrite(t, p, "local-original")
+	local := readFileMTimeMillis(t, p)
+
+	caller := &driveSyncMockCaller{
+		listJSON: `{"result":{"items":[{"name":"f.txt","type":"file","fileId":"F_FID","modifyTime":` +
+			differentMillis(local) + `}],"nextToken":""}}`,
+	}
+	failGet := func(context.Context, string, map[string]string, string) error {
+		return errTestDownload
+	}
+	err := runDriveSyncTestWithGet(t, caller, failGet, dir, "--quick", "--on-conflict", "keep-both")
+	if err == nil {
+		t.Fatal("下载失败时应以非零退出码退出")
+	}
+	// 原名尚未被远端发布，保持原内容。
+	if b, rerr := os.ReadFile(p); rerr != nil || string(b) != "local-original" {
+		t.Errorf("keep-both 拉取失败后原文件应保留: got %q err=%v", string(b), rerr)
+	}
+	aside := filepath.Join(dir, "f.conflict-F_FID.txt")
+	if b, rerr := os.ReadFile(aside); rerr != nil || string(b) != "local-original" {
+		t.Errorf("keep-both 拉取失败后候选应保留: got %q err=%v", string(b), rerr)
+	}
+}
+
+// reserveSyncKeepBothTarget 不得占用「精确同名」的既有文件（occupied 未记录时），
+// 应原子占位到下一个后缀，且既有文件内容不被破坏。此断言在任何文件系统上都成立。
+func TestCrossPlatformCoverageReserveSyncKeepBothTarget_noOverwriteExact(t *testing.T) {
+	dir := t.TempDir()
+	mustWrite(t, filepath.Join(dir, "f.txt"), "local-data")
+	// 预置一个与首选候选精确同名的既有文件（模拟未被 occupied 记录的外部残留）。
+	first := "f.conflict-ABCD1234.txt"
+	mustWrite(t, filepath.Join(dir, first), "existing-data")
+
+	rel, abs, err := reserveSyncKeepBothTarget(dir, "f.txt", "0000ABCD1234", map[string]bool{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if rel == first {
+		t.Fatalf("不应占用既有文件 %s", first)
+	}
+	if want := "f.conflict-ABCD1234.1.txt"; rel != want {
+		t.Errorf("rel = %q, want %q", rel, want)
+	}
+	// 既有文件内容原样保留（未被覆盖）。
+	if b, _ := os.ReadFile(filepath.Join(dir, first)); string(b) != "existing-data" {
+		t.Error("既有文件被覆盖，数据丢失")
+	}
+	// 返回的目标是原始本地版本的硬链接，不是空占位。
+	if b, e := os.ReadFile(abs); e != nil || string(b) != "local-data" {
+		t.Errorf("候选硬链接内容错误: content=%q err=%v", b, e)
+	}
+}
+
+// reserveSyncKeepBothTarget 在大小写不敏感文件系统上，不得覆盖与候选「大小写等价」的
+// 既有文件——O_EXCL 由 OS 兜底判等价性，occupied 的精确字符串键覆盖不到这种情况。
+func TestCrossPlatformCoverageReserveSyncKeepBothTarget_noOverwriteCaseEquivalent(t *testing.T) {
+	dir := t.TempDir()
+	mustWrite(t, filepath.Join(dir, "f.txt"), "local-data")
+	if !isCaseInsensitiveFS(dir) {
+		t.Skip("文件系统大小写敏感，跳过大小写等价覆盖测试")
+	}
+	// 既有文件用大写变体，occupied 为空（模拟精确键查重覆盖不到的等价文件）。
+	existing := "f.CONFLICT-ABCD1234.TXT"
+	mustWrite(t, filepath.Join(dir, existing), "case-variant-data")
+
+	rel, _, err := reserveSyncKeepBothTarget(dir, "f.txt", "0000abcd1234", map[string]bool{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	// 生成的小写候选与既有大写文件在不敏感 FS 上等价，本不应被占用。
+	if strings.EqualFold(rel, "f.conflict-abcd1234.txt") {
+		t.Errorf("首选候选与既有文件等价，不应被占用: %q", rel)
+	}
+	// 既有文件内容原样保留。
+	if b, _ := os.ReadFile(filepath.Join(dir, existing)); string(b) != "case-variant-data" {
+		t.Error("大小写等价的既有文件被覆盖，数据丢失")
+	}
+}
+
+// 非交互 ask（stdin 立即 EOF）：冲突项应被跳过而非中止整个同步，
+// new_local 仍上传、new_remote 仍下载，且被跳过的 modified 本地文件不被改动。
+func TestCrossPlatformCoverageDriveSync_askNonInteractiveSkipsConflict(t *testing.T) {
+	testseam.Swap(t, &syncAskStdin, io.Reader(strings.NewReader(""))) // 非交互：立即 EOF
+
+	dir := t.TempDir()
+	mustWrite(t, filepath.Join(dir, "local.txt"), "local-only") // new_local → 应上传
+	p := filepath.Join(dir, "f.txt")
+	mustWrite(t, p, "local-old") // modified → ask 非交互跳过
+	local := readFileMTimeMillis(t, p)
+
+	caller := &driveSyncMockCaller{
+		listJSON: `{"result":{"items":[` +
+			`{"name":"f.txt","type":"file","fileId":"F_FID","modifyTime":` + differentMillis(local) + `},` +
+			`{"name":"remote.txt","type":"file","fileId":"R_FID","modifyTime":2000}` +
+			`],"nextToken":""}}`,
+	}
+	if err := runDriveSyncTest(t, caller, dir, "--quick", "--on-conflict", "ask"); err != nil {
+		t.Fatalf("非交互 ask 不应中止同步: %v", err)
+	}
+
+	// new_local 上传、new_remote 下载都应照常发生。
+	if up := caller.callsFor("get_upload_info"); len(up) != 1 {
+		t.Errorf("new_local 应被上传, got %d get_upload_info calls", len(up))
+	}
+	if dl := caller.callsFor("download_file"); len(dl) != 1 || dl[0].args["fileId"] != "R_FID" {
+		t.Errorf("new_remote 应被下载, got %v", dl)
+	}
+	// modified 冲突被跳过：本地 f.txt 未被覆盖。
+	if b, _ := os.ReadFile(p); string(b) != "local-old" {
+		t.Errorf("ask 跳过的 modified 文件不应被改动, got %q", string(b))
+	}
+}
+
+// readFileMTimeMillis 返回文件的 mtime（Unix 毫秒）。
+func readFileMTimeMillis(t *testing.T, path string) int64 {
+	t.Helper()
+	fi, err := os.Stat(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return fi.ModTime().UnixMilli()
+}
+
+// differentMillis 返回一个与 base 不同的毫秒数字符串，保证 quick 模式判为 modified。
+func differentMillis(base int64) string {
+	return strconv.FormatInt(base+60000, 10) // 差 1 分钟，足以区分
+}

internal/helpers/drive_sync_type_conflict_test.go

@@ -0,0 +1,131 @@
+package helpers
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam"
+)
+
+type driveSyncTypeConflictFixture struct {
+	name     string
+	setup    func(t *testing.T, root string)
+	listings map[string]string
+}
+
+func driveSyncTypeConflictFixtures() []driveSyncTypeConflictFixture {
+	return []driveSyncTypeConflictFixture{
+		{
+			name: "local folder conflicts with remote file",
+			setup: func(t *testing.T, root string) {
+				t.Helper()
+				mustWrite(t, filepath.Join(root, "conflict", "local.txt"), "local")
+			},
+			listings: map[string]string{
+				"ROOT": `{"result":{"items":[{"name":"conflict","type":"file","fileId":"REMOTE_FILE","modifyTime":1}],"nextToken":""}}`,
+			},
+		},
+		{
+			name: "local file conflicts with remote folder",
+			setup: func(t *testing.T, root string) {
+				t.Helper()
+				mustWrite(t, filepath.Join(root, "conflict"), "local")
+			},
+			listings: map[string]string{
+				"ROOT":          `{"result":{"items":[{"name":"conflict","type":"folder","fileId":"REMOTE_FOLDER"}],"nextToken":""}}`,
+				"REMOTE_FOLDER": `{"result":{"items":[{"name":"remote.txt","type":"file","fileId":"REMOTE_CHILD","modifyTime":1}],"nextToken":""}}`,
+			},
+		},
+	}
+}
+
+func TestCrossPlatformCoverageDriveSync_typeConflictsFailClosedBeforeWrites(t *testing.T) {
+	for _, tc := range driveSyncTypeConflictFixtures() {
+		t.Run(tc.name, func(t *testing.T) {
+			root := t.TempDir()
+			tc.setup(t, root)
+			caller := syncCaller(tc.listings)
+
+			transferCalls := captureDriveSyncTransfers(t)
+
+			err := runDriveCmd(t, caller, "sync", "--local-folder", root,
+				"--remote-folder", "ROOT", "--quick")
+			var syncFailure *driveSyncFailure
+			if !errors.As(err, &syncFailure) || syncFailure.failed != 1 {
+				t.Fatalf("type conflict error = %v, want one failed item", err)
+			}
+			assertDriveSyncNoWriteCalls(t, caller, transferCalls)
+		})
+	}
+}
+
+func TestCrossPlatformCoverageDriveSync_dryRunReportsTypeConflictsWithoutWrites(t *testing.T) {
+	for _, tc := range driveSyncTypeConflictFixtures() {
+		t.Run(tc.name, func(t *testing.T) {
+			root := t.TempDir()
+			tc.setup(t, root)
+			caller := syncCaller(tc.listings)
+			caller.dryRun = true
+
+			transferCalls := captureDriveSyncTransfers(t)
+
+			var out bytes.Buffer
+			testseam.Swap(t, &deps, &Deps{Caller: caller, Out: &Formatter{w: &out}})
+			testseam.Swap(t, &os.Args, []string{"dws", "drive", "sync"})
+
+			cmd := findDriveSubcommand(t, "sync")
+			mustSetFlags(t, cmd, map[string]string{
+				"local-folder":  root,
+				"remote-folder": "ROOT",
+				"quick":         "true",
+			})
+			if err := cmd.RunE(cmd, nil); err != nil {
+				t.Fatalf("dry-run type conflict: %v", err)
+			}
+
+			text := out.String()
+			if !strings.Contains(text, `"failed": 1`) ||
+				!strings.Contains(text, `"action": "failed"`) ||
+				!strings.Contains(text, `"rel_path": "conflict"`) {
+				t.Fatalf("dry-run must report the type conflict as failed: %s", text)
+			}
+			assertDriveSyncNoWriteCalls(t, caller, transferCalls)
+		})
+	}
+}
+
+type driveSyncTransferCalls struct {
+	get int
+	put int
+}
+
+func captureDriveSyncTransfers(t *testing.T) *driveSyncTransferCalls {
+	t.Helper()
+	calls := &driveSyncTransferCalls{}
+	swapPullDownloadPath(t, func(context.Context, string, map[string]string, string) error {
+		calls.get++
+		return nil
+	})
+	testseam.Swap(t, &pushPutOpenedFile, func(context.Context, string, map[string]string, *os.File, int64) error {
+		calls.put++
+		return nil
+	})
+	return calls
+}
+
+func assertDriveSyncNoWriteCalls(t *testing.T, caller *driveScriptCaller, transferCalls *driveSyncTransferCalls) {
+	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("type conflict must not call %s, got %v", tool, calls)
+		}
+	}
+	if transferCalls.get != 0 || transferCalls.put != 0 {
+		t.Errorf("type conflict must not transfer HTTP content, GET=%d PUT=%d", transferCalls.get, transferCalls.put)
+	}
+}

internal/helpers/im_read_result_contract_test.go

@@ -21,7 +21,9 @@ import (
 	"io"
 	"os"
 	"reflect"
+	"strings"
 	"testing"
+	"time"
 
 	"github.com/spf13/cobra"
 
@@ -39,11 +41,16 @@ type imReadResultCaller struct {
 	results   map[string]*edition.ToolResult
 	errors    map[string]error
 	calls     []imReadResultCall
+	args      map[string]any
 	dryRun    bool
 }
 
-func (c *imReadResultCaller) CallTool(_ context.Context, productID, toolName string, _ map[string]any) (*edition.ToolResult, error) {
+func (c *imReadResultCaller) CallTool(_ context.Context, productID, toolName string, args map[string]any) (*edition.ToolResult, error) {
 	c.calls = append(c.calls, imReadResultCall{productID: productID, toolName: toolName})
+	c.args = map[string]any{}
+	for k, v := range args {
+		c.args[k] = v
+	}
 	if err := c.errors[toolName]; err != nil {
 		return nil, err
 	}
@@ -203,6 +210,37 @@ func TestCrossPlatformCoverageChatMessageListProjectsStableFieldsAndPreservesLeg
 	}
 }
 
+func TestCrossPlatformCoverageChatMessageListDefaultsTimeAndOlderDirection(t *testing.T) {
+	payload := `{"result":{"messages":[],"hasMore":false}}`
+	caller := &imReadResultCaller{responses: map[string]string{"list_conversation_message_v2": payload}}
+	loc := shanghaiLocation()
+
+	before := time.Now().In(loc)
+	_, err := executeIMReadCommand(t, caller, []string{"dws", "chat"}, newChatCommand,
+		"message", "list", "--group", "cid-1", "--limit", "50")
+	after := time.Now().In(loc)
+	if err != nil {
+		t.Fatalf("chat message list returned error: %v", err)
+	}
+	if len(caller.calls) != 1 || caller.calls[0] != (imReadResultCall{productID: "chat", toolName: "list_conversation_message_v2"}) {
+		t.Fatalf("calls = %#v, want chat/list_conversation_message_v2", caller.calls)
+	}
+	if got := caller.args["forward"]; got != false {
+		t.Fatalf("forward = %#v, want false when --time is omitted", got)
+	}
+	timeRaw, ok := caller.args["time"].(string)
+	if !ok || strings.TrimSpace(timeRaw) == "" {
+		t.Fatalf("time arg = %#v, want generated current time", caller.args["time"])
+	}
+	gotTime, err := time.ParseInLocation("2006-01-02 15:04:05", timeRaw, loc)
+	if err != nil {
+		t.Fatalf("parse generated time %q: %v", timeRaw, err)
+	}
+	if gotTime.Before(before.Add(-time.Second)) || gotTime.After(after.Add(time.Second)) {
+		t.Fatalf("time = %s, want between %s and %s", gotTime, before, after)
+	}
+}
+
 func TestCrossPlatformCoverageChatMessageSearchProjectsStableFieldsAndPreservesLegacy(t *testing.T) {
 	payload := `{
 		"result": {

internal/helpers/pr868_coverage_gaps_test.go

@@ -611,7 +611,7 @@ func TestCrossPlatformCoverageDriveLatestRemaining(t *testing.T) {
 		{"name": "c", "sortTime": int64(5), "rel_path": "z", "fileId": "3", "type": "file"},
 		{"nodeType": "Folder", "name": "folder"},
 	}
-	got := applyDriveListLatest(items, 10)
+	got := applyDriveListLatest(items, 10, false)
 	if len(got) != 3 {
 		t.Fatalf("len=%d", len(got))
 	}
@@ -674,7 +674,7 @@ func TestCrossPlatformCoverageDriveDepthLatestTruncatedAndSortTime(t *testing.T)
 	caller := &scriptedToolCaller{steps: []scriptedToolStep{{text: sb.String()}}}
 	out := installDepthCaller(t, caller)
 	cmd := &cobra.Command{Use: "list"}
-	err := runDriveListDepth(cmd, newDrivePanDepthRoute(), map[string]any{}, "", 3, "", true, 2)
+	err := runDriveListDepth(cmd, newDrivePanDepthRoute(), map[string]any{}, "", 3, "", true, 2, driveListFilter{})
 	if err == nil || !strings.Contains(err.Error(), "LATEST_SCAN_TRUNCATED") {
 		t.Fatalf("err=%v, want LATEST_SCAN_TRUNCATED", err)
 	}

internal/helpers/pr868_surfaces_coverage_test.go

@@ -322,7 +322,7 @@ func TestCrossPlatformCoverageDriveLatestHelpers(t *testing.T) {
 		{"name": "a.txt", "sortTime": int64(2), "rel_path": "a", "fileId": "1", "type": "file"},
 		{"name": "dir", "sortTime": int64(9), "type": "folder", "dentryType": "folder"},
 	}
-	got := applyDriveListLatest(items, 1)
+	got := applyDriveListLatest(items, 1, false)
 	if len(got) != 1 {
 		t.Fatalf("latest len=%d", len(got))
 	}

internal/interfacesnapshot/migrations.go

@@ -324,11 +324,23 @@ func (m FlagMigration) validate() error {
 	if m.Canonical.After.Hidden {
 		return fmt.Errorf("canonical flag must remain visible")
 	}
-	if !m.Canonical.After.Required {
-		return fmt.Errorf("canonical flag must be required after migration")
+	// Requiredness belongs to the one logical parameter. The hidden legacy
+	// spelling must not remain independently required, while the canonical
+	// spelling inherits the exact before-state contract. An already-visible
+	// canonical flag cannot change requiredness; an existing hidden canonical
+	// placeholder may inherit it when promoted to the public spelling.
+	if m.Legacy.After.Required {
+		return fmt.Errorf("legacy compatibility alias must not remain independently required after migration")
 	}
-	if m.Canonical.Before.Present && m.Canonical.Before.Required {
-		return fmt.Errorf("canonical flag must be absent or optional before migration")
+	if m.Legacy.Before.Required != m.Canonical.After.Required {
+		return fmt.Errorf(
+			"flag requiredness must be preserved from legacy before to canonical after",
+		)
+	}
+	if m.Canonical.Before.Present &&
+		!m.Canonical.Before.Hidden &&
+		m.Canonical.Before.Required != m.Canonical.After.Required {
+		return fmt.Errorf("canonical flag requiredness must remain unchanged when already present")
 	}
 	if m.Legacy.After.AliasOf != m.Canonical.Name {
 		return fmt.Errorf(
@@ -682,6 +694,7 @@ func flagMigrationAuthorizesChange(
 			return true
 		}
 		if migration.Canonical.Before.Present &&
+			migration.Canonical.Before.Hidden &&
 			!migration.Canonical.Before.Required &&
 			migration.Canonical.After.Required &&
 			change.Kind == "flag_became_required" {

internal/interfacesnapshot/migrations_coverage_test.go

@@ -188,7 +188,7 @@ func TestCrossPlatformCoverageFlagMigrationManifestParserEdges(t *testing.T) {
 
 func TestCrossPlatformCoverageFlagMigrationManifestRejectsEveryContractDrift(t *testing.T) {
 	optionalCanonical := func() FlagMigrationManifest {
-		manifest := coverageManifest(FlagMigrationPending)
+		manifest := coverageOptionalManifest(FlagMigrationPending)
 		manifest.Migrations[0].Canonical.Before = FlagMigrationState{
 			Present: true,
 			Type:    "string",
@@ -269,6 +269,36 @@ func TestCrossPlatformCoverageFlagMigrationManifestRejectsEveryContractDrift(t *
 			mutate:  func(m *FlagMigrationManifest) { m.Migrations[0].Canonical.After = FlagMigrationState{} },
 			wantErr: "canonical flag must be present after migration",
 		},
+		{
+			name:    "required legacy cannot become optional canonical",
+			make:    func() FlagMigrationManifest { return coverageManifest(FlagMigrationPending) },
+			mutate:  func(m *FlagMigrationManifest) { m.Migrations[0].Canonical.After.Required = false },
+			wantErr: "requiredness must be preserved from legacy before to canonical after",
+		},
+		{
+			name:    "optional legacy cannot become required canonical",
+			make:    func() FlagMigrationManifest { return coverageOptionalManifest(FlagMigrationPending) },
+			mutate:  func(m *FlagMigrationManifest) { m.Migrations[0].Canonical.After.Required = true },
+			wantErr: "requiredness must be preserved from legacy before to canonical after",
+		},
+		{
+			name: "existing canonical cannot change requiredness",
+			make: func() FlagMigrationManifest { return coverageManifest(FlagMigrationPending) },
+			mutate: func(manifest *FlagMigrationManifest) {
+				manifest.Migrations[0].Canonical.Before = FlagMigrationState{
+					Present: true,
+					Type:    "string",
+					Scope:   "local",
+				}
+			},
+			wantErr: "canonical flag requiredness must remain unchanged when already present",
+		},
+		{
+			name:    "hidden legacy alias is not independently required",
+			make:    func() FlagMigrationManifest { return coverageManifest(FlagMigrationPending) },
+			mutate:  func(m *FlagMigrationManifest) { m.Migrations[0].Legacy.After.Required = true },
+			wantErr: "legacy compatibility alias must not remain independently required",
+		},
 		{
 			name:    "legacy after declares alias target",
 			make:    func() FlagMigrationManifest { return coverageManifest(FlagMigrationPending) },
@@ -711,8 +741,32 @@ func TestCrossPlatformCoverageCompareAllWithFlagMigrationsInheritedAndOptionalCa
 		}
 	})
 
-	t.Run("existing optional canonical becomes required", func(t *testing.T) {
-		pending := coverageManifest(FlagMigrationPending)
+	t.Run("optional canonical is introduced without becoming required", func(t *testing.T) {
+		pending := coverageOptionalManifest(FlagMigrationPending)
+		consumed := coverageOptionalManifest(FlagMigrationConsumed)
+		before := coverageMigrationSnapshot(pending.Migrations[0], false, false)
+		after := coverageMigrationSnapshot(pending.Migrations[0], true, false)
+
+		ordinary := Compare(after, before, "merge-base")
+		if !hasFlagChange(ordinary.Blocking, "flag_became_hidden", pending.Migrations[0].Command, pending.Migrations[0].Legacy.Name) {
+			t.Fatalf("fixture did not create flag_became_hidden: %#v", ordinary.Blocking)
+		}
+		if hasFlagChange(ordinary.Blocking, "required_flag_added", pending.Migrations[0].Command, pending.Migrations[0].Canonical.Name) {
+			t.Fatalf("optional canonical was treated as required: %#v", ordinary.Blocking)
+		}
+		report, err := CompareAllWithFlagMigrations(
+			after,
+			map[string]Snapshot{"merge-base": before, "stable": before},
+			pending,
+			consumed,
+		)
+		if err != nil || !report.Compatible {
+			t.Fatalf("optional rename = (%#v, %v), want compatible", report, err)
+		}
+	})
+
+	t.Run("existing optional canonical remains optional", func(t *testing.T) {
+		pending := coverageOptionalManifest(FlagMigrationPending)
 		pending.Migrations[0].Canonical.Before = FlagMigrationState{
 			Present: true,
 			Type:    "string",
@@ -725,8 +779,8 @@ func TestCrossPlatformCoverageCompareAllWithFlagMigrationsInheritedAndOptionalCa
 		after := coverageMigrationSnapshot(pending.Migrations[0], true, false)
 
 		ordinary := Compare(after, before, "merge-base")
-		if !hasFlagChange(ordinary.Blocking, "flag_became_required", pending.Migrations[0].Command, pending.Migrations[0].Canonical.Name) {
-			t.Fatalf("fixture did not create flag_became_required: %#v", ordinary.Blocking)
+		if hasFlagChange(ordinary.Blocking, "flag_became_required", pending.Migrations[0].Command, pending.Migrations[0].Canonical.Name) {
+			t.Fatalf("fixture changed canonical requiredness: %#v", ordinary.Blocking)
 		}
 		report, err := CompareAllWithFlagMigrations(
 			after,
@@ -735,7 +789,83 @@ func TestCrossPlatformCoverageCompareAllWithFlagMigrationsInheritedAndOptionalCa
 			consumed,
 		)
 		if err != nil || !report.Compatible {
-			t.Fatalf("optional-to-required migration = (%#v, %v), want compatible", report, err)
+			t.Fatalf("existing optional canonical migration = (%#v, %v), want compatible", report, err)
+		}
+	})
+
+	t.Run("hidden canonical inherits requiredness when promoted", func(t *testing.T) {
+		pending := coverageManifest(FlagMigrationPending)
+		pending.Migrations[0].Canonical.Before = FlagMigrationState{
+			Present: true,
+			Type:    "string",
+			Hidden:  true,
+			Scope:   "local",
+		}
+		consumed := pending
+		consumed.Migrations = append([]FlagMigration(nil), pending.Migrations...)
+		consumed.Migrations[0].State = FlagMigrationConsumed
+		before := coverageMigrationSnapshot(pending.Migrations[0], false, false)
+		after := coverageMigrationSnapshot(pending.Migrations[0], true, false)
+
+		ordinary := Compare(after, before, "merge-base")
+		if !hasFlagChange(ordinary.Blocking, "flag_became_required", pending.Migrations[0].Command, pending.Migrations[0].Canonical.Name) {
+			t.Fatalf("fixture did not change canonical requiredness: %#v", ordinary.Blocking)
+		}
+		report, err := CompareAllWithFlagMigrations(
+			after,
+			map[string]Snapshot{"merge-base": before, "stable": before},
+			pending,
+			consumed,
+		)
+		if err != nil || !report.Compatible {
+			t.Fatalf("hidden canonical promotion = (%#v, %v), want compatible", report, err)
+		}
+	})
+}
+
+func TestCrossPlatformCoverageOptionalFlagMigrationLifecycleRemainsHostile(t *testing.T) {
+	pending := coverageOptionalManifest(FlagMigrationPending)
+	consumed := coverageOptionalManifest(FlagMigrationConsumed)
+	empty := coverageEmptyManifest()
+	migration := pending.Migrations[0]
+	before := coverageMigrationSnapshot(migration, false, false)
+	after := coverageMigrationSnapshot(migration, true, false)
+
+	t.Run("candidate cannot self authorize", func(t *testing.T) {
+		_, err := CompareAllWithFlagMigrations(
+			after,
+			map[string]Snapshot{"merge-base": before, "stable": before},
+			empty,
+			pending,
+		)
+		if err == nil || !strings.Contains(err.Error(), "cannot authorize its own interface change") {
+			t.Fatalf("candidate self-authorization error = %v", err)
+		}
+	})
+
+	t.Run("partial application remains rejected", func(t *testing.T) {
+		partial := coverageMigrationSnapshot(migration, false, false)
+		partial.Commands[len(partial.Commands)-1].LocalFlags[0].Hidden = true
+		_, err := CompareAllWithFlagMigrations(
+			partial,
+			map[string]Snapshot{"merge-base": before, "stable": before},
+			pending,
+			consumed,
+		)
+		if err == nil || !strings.Contains(err.Error(), "partially applied flag migration") {
+			t.Fatalf("partial optional migration error = %v", err)
+		}
+	})
+
+	t.Run("consumed receipt remains stale after every reference converges", func(t *testing.T) {
+		_, err := CompareAllWithFlagMigrations(
+			after,
+			map[string]Snapshot{"merge-base": after, "stable": after},
+			consumed,
+			consumed,
+		)
+		if err == nil || !strings.Contains(err.Error(), "stale after all references reached the after state") {
+			t.Fatalf("stale optional migration error = %v", err)
 		}
 	})
 }
@@ -886,6 +1016,13 @@ func coverageManifest(state string) FlagMigrationManifest {
 	}
 }
 
+func coverageOptionalManifest(state string) FlagMigrationManifest {
+	manifest := coverageManifest(state)
+	manifest.Migrations[0].Legacy.Before.Required = false
+	manifest.Migrations[0].Canonical.After.Required = false
+	return manifest
+}
+
 func coverageEmptyManifest() FlagMigrationManifest {
 	return FlagMigrationManifest{Version: FlagMigrationManifestVersion, Migrations: []FlagMigration{}}
 }

internal/interfacesnapshot/migrations_test.go

@@ -5,6 +5,7 @@ package interfacesnapshot
 
 import (
 	"errors"
+	"os"
 	"reflect"
 	"strings"
 	"testing"
@@ -37,6 +38,42 @@ const validFlagMigrationManifestJSON = `{
   ]
 }`
 
+func optionalFlagMigrationManifestJSON() string {
+	manifest := strings.Replace(
+		validFlagMigrationManifestJSON,
+		`"before": {"present": true, "type": "string", "required": true, "scope": "local"}`,
+		`"before": {"present": true, "type": "string", "scope": "local"}`,
+		1,
+	)
+	return strings.Replace(
+		manifest,
+		`"after": {"present": true, "type": "string", "required": true, "scope": "local"}`,
+		`"after": {"present": true, "type": "string", "scope": "local"}`,
+		1,
+	)
+}
+
+func hiddenCanonicalFlagMigrationManifestJSON() string {
+	return strings.Replace(
+		validFlagMigrationManifestJSON,
+		`"before": {"present": false}`,
+		`"before": {"present": true, "type": "string", "hidden": true, "scope": "local"}`,
+		1,
+	)
+}
+
+func TestApprovedFlagMigrationManifestRemainsValid(t *testing.T) {
+	manifest, err := os.Open("../../scripts/policy/interface-migrations/approved-flag-migrations-v1.json")
+	if err != nil {
+		t.Fatalf("open approved flag migration manifest: %v", err)
+	}
+	defer manifest.Close()
+
+	if _, err := ReadFlagMigrationManifest(manifest); err != nil {
+		t.Fatalf("approved flag migration manifest is invalid: %v", err)
+	}
+}
+
 func TestCrossPlatformCoverageReadFlagMigrationManifestRejectsUnknownFields(t *testing.T) {
 	_, err := ReadFlagMigrationManifest(strings.NewReader(`{
   "version": 1,
@@ -110,6 +147,12 @@ func TestCrossPlatformCoverageReadFlagMigrationManifestValidatesExactEntries(t *
 	if _, err := ReadFlagMigrationManifest(strings.NewReader(validFlagMigrationManifestJSON)); err != nil {
 		t.Fatalf("ReadFlagMigrationManifest(valid) error = %v", err)
 	}
+	if _, err := ReadFlagMigrationManifest(strings.NewReader(optionalFlagMigrationManifestJSON())); err != nil {
+		t.Fatalf("ReadFlagMigrationManifest(optional rename) error = %v", err)
+	}
+	if _, err := ReadFlagMigrationManifest(strings.NewReader(hiddenCanonicalFlagMigrationManifestJSON())); err != nil {
+		t.Fatalf("ReadFlagMigrationManifest(hidden canonical promotion) error = %v", err)
+	}
 
 	tests := []struct {
 		name    string
@@ -162,24 +205,34 @@ func TestCrossPlatformCoverageReadFlagMigrationManifestValidatesExactEntries(t *
 			wantErr: "canonical flag must remain visible",
 		},
 		{
-			name: "canonical remains optional",
+			name: "required legacy becomes optional canonical",
 			input: strings.Replace(
 				validFlagMigrationManifestJSON,
 				`"after": {"present": true, "type": "string", "required": true, "scope": "local"}`,
 				`"after": {"present": true, "type": "string", "scope": "local"}`,
 				1,
 			),
-			wantErr: "canonical flag must be required after migration",
+			wantErr: "requiredness must be preserved from legacy before to canonical after",
 		},
 		{
-			name: "canonical was already required",
+			name: "optional legacy becomes required canonical",
+			input: strings.Replace(
+				optionalFlagMigrationManifestJSON(),
+				`"after": {"present": true, "type": "string", "scope": "local"}`,
+				`"after": {"present": true, "type": "string", "required": true, "scope": "local"}`,
+				1,
+			),
+			wantErr: "requiredness must be preserved from legacy before to canonical after",
+		},
+		{
+			name: "existing canonical changes requiredness",
 			input: strings.Replace(
 				validFlagMigrationManifestJSON,
 				`"before": {"present": false}`,
-				`"before": {"present": true, "type": "string", "required": true, "scope": "local"}`,
+				`"before": {"present": true, "type": "string", "scope": "local"}`,
 				1,
 			),
-			wantErr: "canonical flag must be absent or optional before migration",
+			wantErr: "canonical flag requiredness must remain unchanged when already present",
 		},
 	}
 
@@ -215,9 +268,10 @@ func TestCrossPlatformCoverageFlagMigrationManifestRejectsDuplicateAndInexactCon
 	canonicalDrift := manifest
 	canonicalDrift.Migrations = append([]FlagMigration(nil), manifest.Migrations...)
 	canonicalDrift.Migrations[0].Canonical.Before = FlagMigrationState{
-		Present: true,
-		Type:    "string",
-		Scope:   "local",
+		Present:  true,
+		Type:     "string",
+		Required: true,
+		Scope:    "local",
 	}
 	canonicalDrift.Migrations[0].Canonical.After.Type = "stringSlice"
 	if err := canonicalDrift.Validate(); err == nil || !strings.Contains(err.Error(), "canonical flag type") {

internal/logging/redact.go

@@ -26,6 +26,8 @@ import (
 var sensitiveKeys = map[string]bool{
 	"authorization":       true,
 	"x-user-access-token": true,
+	"dws_agent_ext":       true,
+	"x-dws-agent-ext":     true,
 	"client_secret":       true,
 	"client-secret":       true,
 	"token":               true,

internal/logging/redact_test.go

@@ -30,6 +30,12 @@ func TestIsSensitiveKey(t *testing.T) {
 		{"authorization", true},
 		{"x-user-access-token", true},
 		{"X-User-Access-Token", true},
+		{"DWS_AGENT_EXT", true},
+		{"dws_agent_ext", true},
+		{"x-dws-agent-ext", true},
+		{"X-Dws-Agent-Ext", true},
+		{"DWS_AGENT_VER", false},
+		{"x-dws-agent-ver", false},
 		{"client_secret", true},
 		{"client-secret", true},
 		{"token", true},
@@ -128,17 +134,24 @@ func TestSanitizeArguments_Empty(t *testing.T) {
 
 func TestRedactHeaders(t *testing.T) {
 	t.Parallel()
-	headers := http.Header{
-		"Authorization": {"Bearer token123456"},
-		"Content-Type":  {"application/json"},
-	}
+	headers := make(http.Header)
+	headers.Set("Authorization", "Bearer test-credential-value")
+	headers.Set("Content-Type", "application/json")
+	headers.Set("DWS_AGENT_EXT", `{"umt":"test-umt-value"}`)
+	headers.Set("x-dws-agent-ext", `{"ua":"test-agent-value"}`)
 	attrs := RedactHeaders(headers)
-	if len(attrs) != 2 {
-		t.Fatalf("expected 2 attrs, got %d", len(attrs))
+	if len(attrs) != 4 {
+		t.Fatalf("expected 4 attrs, got %d", len(attrs))
 	}
 	for _, attr := range attrs {
-		if attr.Key == "header.authorization" && !strings.Contains(attr.Value.String(), "***") {
-			t.Fatalf("authorization should be redacted: %s", attr.Value.String())
+		switch attr.Key {
+		case "header.authorization", "header.dws_agent_ext", "header.x-dws-agent-ext":
+			if !strings.Contains(attr.Value.String(), "***") {
+				t.Fatalf("%s should be redacted: %s", attr.Key, attr.Value.String())
+			}
+			if strings.Contains(attr.Value.String(), "test-") {
+				t.Fatalf("%s leaked its original value: %s", attr.Key, attr.Value.String())
+			}
 		}
 		if attr.Key == "header.content-type" && attr.Value.String() != "application/json" {
 			t.Fatalf("content-type should not be redacted: %s", attr.Value.String())