feat(schema): govern conditional idempotent retries

feat: forward Agent version and extension context

.changes/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/85387314-chat-image-guide.md

@@ -0,0 +1,5 @@
+---
+category: Changed
+---
+
+- **Chat message send help** - Clarifies Markdown image syntax for inline mixed text and images.

.changes/961-drive-file-comments.md

@@ -0,0 +1,5 @@
+---
+category: Added
+---
+
+- **Drive file comments** (#961) — adds `dws drive comment list` and `dws drive comment create` for comments on ordinary preview files.

.changes/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.

.changes/README.md

@@ -0,0 +1,34 @@
+# Release fragments
+
+普通功能、修复和面向用户的行为变更不要再修改根目录 `CHANGELOG.md` 的
+`Unreleased` 区域。每个 PR 在本目录新增一个独立的 Markdown fragment，避免
+并行 PR 争用同一文件。
+
+文件名使用能唯一定位变更的短名，通常是 PR 号，例如
+`1234-chat-reply-mentions.md`。文件名必须匹配
+`^[a-z0-9][a-z0-9._-]*\.md$`，且必须是普通文件，不能是符号链接。本目录顶层
+只接受 `README.md`、`released/` 和符合该规则的 fragment：fragment 一律平铺在
+顶层，不接受任何其它子目录，本目录自身也不能被替换成文件或符号链接。其余条目
+会被 CI 直接拒绝而不是忽略，以免非法条目跳过校验后拖垮下一个 PR。文件格式
+严格如下：
+
+```markdown
+---
+category: Added
+---
+
+- **Chat reply mentions** (#1234) — supports mentioning selected members.
+```
+
+`category` 只能是 `Added`、`Changed`、`Deprecated`、`Removed`、`Fixed` 或
+`Security`。正文至少包含一个 Markdown 列表项，且不得包含 `TODO` 或 `TBD`。
+
+发布 beta 时，`scripts/release/prepare-changelog.sh` 会按分类和文件名稳定排序，
+将未归档 fragments 汇总为唯一的版本章节，并移动到
+`.changes/released/<version>/`。因此 release-seal PR 是唯一会修改
+`CHANGELOG.md` 的 PR；它同时归档已消费的 fragments，供审计追溯。
+归档只能在同一个 release-seal PR 中以原样移动完成；CI 会拒绝直接修改、
+删除或重写已归档文件。
+
+无需面向用户发布说明的改动不添加 fragment。评审者根据改动是否可见来判断该
+例外是否成立。

.changes/doc-drive-wiki-space-routing.md

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

.changes/idempotency-retry-governance.md

@@ -0,0 +1,5 @@
+---
+category: Changed
+---
+
+- **Agent retry safety** — adds a conditional idempotency contract and base-owned compatibility governance for deduplication-key-aware retries.

.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/PULL_REQUEST_TEMPLATE.md

@@ -19,8 +19,10 @@ repeat the entire CI suite locally only to fill this checklist: CI expands the
 selected tier from documentation checks, through affected-package tests, to
 the complete high-risk suite.
 
-- [ ] Exact in-place `CHANGELOG.md`-only check (otherwise `N/A`):
-  `./scripts/policy/check-changelog-pr.sh --fast-path "$(git merge-base HEAD origin/main)" HEAD`
+- [ ] Release fragment added for a user-visible behavior/interface change (otherwise `N/A`):
+  `.changes/<unique-name>.md`; ordinary PRs must not edit `CHANGELOG.md`.
+- [ ] Release-seal validation (otherwise `N/A`):
+  `./scripts/policy/check-changelog-pr.sh --content-only "$(git merge-base HEAD origin/main)" HEAD`
 - [ ] Targeted test/check commands and results:
 - [ ] Behavior evidence (test name, CLI output shape, or before/after result):
 - [ ] Documentation links/content/rendering checked (documentation-only, otherwise

.github/workflows/ci.yml

@@ -1288,6 +1288,12 @@ jobs:
           ./scripts/policy/check-changelog-pr.sh \
             "$mode" "$PR_BASE_SHA" HEAD
 
+      - name: Validate release fragment lifecycle
+        if: github.event_name == 'pull_request'
+        env:
+          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
         if: github.event_name == 'push' && needs.lint.outputs.changelog_only == 'true'
         env:
@@ -1408,10 +1414,17 @@ jobs:
       - name: Check complete Schema compatibility
         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') }}
         run: |
-          make schema-compatibility \
-            BASE_REF="$COMPATIBILITY_BASE_REF" \
-            STABLE_REF="$COMPATIBILITY_STABLE_REF" \
-            CANDIDATE_REF="$COMPATIBILITY_CANDIDATE_REF"
+          set -eu
+          authority_worktree="$RUNNER_TEMP/dws-schema-authority-$GITHUB_RUN_ID-$GITHUB_RUN_ATTEMPT"
+          cleanup_schema_authority() {
+            git worktree remove --force "$authority_worktree" >/dev/null 2>&1 || true
+          }
+          trap cleanup_schema_authority EXIT HUP INT TERM
+          git worktree add --detach "$authority_worktree" "$COMPATIBILITY_BASE_REF"
+          "$authority_worktree/scripts/policy/check-authoritative-schema-compatibility.sh" \
+            --base-ref "$COMPATIBILITY_BASE_REF" \
+            --stable-ref "$COMPATIBILITY_STABLE_REF" \
+            --candidate-ref "$COMPATIBILITY_CANDIDATE_REF"
 
       - name: Check skill command references
         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

@@ -2793,7 +2793,7 @@ jobs:
             fi
             if test "${{ needs.dispatch-contract.outputs.mode }}" = plan_release; then
               echo
-              echo "Plan only: no tag or package was created. Add the exact \`CHANGELOG.md\` section, merge it to main, then run publish."
+              echo "Plan only: no tag or package was created. Render pending \`.changes/*.md\` fragments into the exact \`CHANGELOG.md\` section, merge the release-seal PR to main, then run publish."
             fi
           } >> "$GITHUB_STEP_SUMMARY"
 

AGENTS.md

@@ -47,7 +47,7 @@ Schema contract) keep separate authorities — do not merge them with
 - Today: `helpers.LeafSpec` / `shortcut.Shortcut` → `corecmd.Spec` (+ optional `Contract`) → `corecmd.New`
 - **Declare = final Schema source**: `Flags` / `Constraints` / `Safety` / `ConstParams` / `Contract` (`corecmd.ContractDecl`; nested fields are `contract.*`)
 - Naming: `ContractDecl` is the authoring leaf declaration. "Schema" means Catalog / `ToolSpec` delivery — do not reintroduce `SchemaDecl`.
-- `Safety` uses `contract.SafetySpec` (`internal/corecmd/contract` only — no `cli.*` type alias). Its `confirmation` drives the runtime gate; `effect` / `risk` / `idempotency` are published unchanged. When `Contract` is set, convert once via `contractfinal.RegisterRuntimeContractFinal` (all callers — `corecmd.New` registers internally); assembly **pass-throughs** Final.
+- `Safety` uses `contract.SafetySpec` (`internal/corecmd/contract` only — no `cli.*` type alias). Its `confirmation` drives the runtime gate; `effect` / `risk` / `idempotency` are published unchanged. `idempotency=conditional` additionally requires `Contract.RetryPolicy`: reference a declared string parameter with an explicit interface property and require the same payload; never infer retry safety from a flag/property name. When `Contract` is set, convert once via `contractfinal.RegisterRuntimeContractFinal` (all callers — `corecmd.New` registers internally); assembly **pass-throughs** Final.
 - Package seam:
   - types / ProductDecl → `corecmd/contract` (DTO only; **no** Cobra-keyed ContractFinal store)
   - AnnotateRuntime* writers → `internal/corecmd/runtimeannotate` (framework-owned)
@@ -423,6 +423,13 @@ lower description, mapping, `effect`, `risk`, `confirmation`, or `idempotency`.
 Preserve all candidates and the selected source in provenance, and fail
 same-precedence conflicts rather than silently merging them.
 
+`conditional` is a static command classification, not an unconditional retry
+grant. It must carry a typed `retry_policy`; runtime computes effective
+idempotency from the actual invocation. A missing/empty/non-string
+deduplication key is `non_idempotent` for that invocation. Only the same key
+and same business payload may be replayed, and the transport/error
+`retryable` signal must fail closed when the invocation is not safe to replay.
+
 `required` is the exception. Cobra `MarkFlagRequired` is a hard floor: the
 final Agent projection must keep `required=true` and cannot be lowered by a
 lower-precedence source. A higher-precedence declaration may still raise an

CONTRIBUTING.md

@@ -83,7 +83,10 @@ coverage is additionally selected for platform-sensitive code.
    change.
 6. Run `./scripts/release/verify-package-managers.sh` when packaging or
    installer surfaces change (run `make package` first).
-7. Update docs and `CHANGELOG.md` for behavior/interface changes.
+7. Update docs and add one `.changes/<unique-name>.md` release fragment for
+   behavior/interface changes. Do not edit `CHANGELOG.md` in an ordinary PR;
+   the release-seal workflow renders and archives fragments into the versioned
+   changelog section.
 
 ## Submission Flow
 

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.3"
+  version "1.0.58-beta.4"
   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.3/dws-darwin-arm64.tar.gz"
-      sha256 "29b4fb9e081f36a699933c0919fe7530544f62de3e27c785d27626a575a2efc2"
+      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.58-beta.4/dws-darwin-arm64.tar.gz"
+      sha256 "5c2ac92e35b1f1dba80234af8b0c9505b2883f4a37c1e73892b8a1c3087b7702"
     else
-      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.58-beta.3/dws-darwin-amd64.tar.gz"
-      sha256 "a6b9c4ef212c533e02b414bd9c3be0b8d1874d4af983a7896072825bdfec1033"
+      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.58-beta.4/dws-darwin-amd64.tar.gz"
+      sha256 "93ef787770105fe1f0d27585adcac7b740aa6c37ff490275c4113814541ae095"
     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.3/dws-linux-arm64.tar.gz"
-      sha256 "ae3a9ebe151702fd05dee0c56d778a20789d98c390cf8c0a0b2ec695b57b5ec3"
+      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.58-beta.4/dws-linux-arm64.tar.gz"
+      sha256 "011ce16a73d8fd24275e34c3122d3d0832c60cde2480f496018eb654059b5c05"
     else
-      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.58-beta.3/dws-linux-amd64.tar.gz"
-      sha256 "544b480701e9ec9ec5366467ad4c855fca06dea887e3d577ff50e4b3eeb13ac2"
+      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.58-beta.4/dws-linux-amd64.tar.gz"
+      sha256 "847b17ff8a8d80dce38f0013eb35c77c102be16c9f98b955a632b983cd5ec104"
     end
   end
 
   resource "skills" do
-    url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.58-beta.3/dws-skills.zip"
-    sha256 "322f1840442ff183ad4b6d4f2a2b38825ff9f96a3fcde06ba57b8f80647468ae"
+    url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.58-beta.4/dws-skills.zip"
+    sha256 "f5e0c72cc92cb7e8886409319cf68bbbfc7740e969bd39a389b74af4befdbc66"
   end
 
   def install

README.md

@@ -210,7 +210,7 @@ The verifier uses isolated directories and does not replace the `dws` on the cur
 The upgrade process follows a two-phase atomic flow to ensure consistency:
 
 1. **Prepare** — downloads the platform-specific binary and skill packages to a temporary directory, verifies SHA256 checksums, and extracts/validates all files. If any step fails, the upgrade aborts without modifying the existing installation.
-2. **Apply** — only after all preparations succeed, the binary is replaced and skill packages are installed to all detected agent directories (`~/.agents/skills/dws`, `~/.claude/skills/dws`, `~/.cursor/skills/dws`, etc.).
+2. **Apply** — only after all preparations succeed, the binary is replaced and skills are flattened into detected agent-specific roots (for example `~/.codex/skills/dingtalk-chat`). `~/.agents/skills` is used only when no specific Agent is detected; once a specific root is active, older DWS-managed generic copies are backed up and retired so the same Skill is not discovered twice.
 
 A backup of the current version is automatically created before each upgrade. Use `dws upgrade --rollback` to restore the previous version if needed.
 
@@ -405,7 +405,7 @@ After installing, AI tools like Claude Code / Cursor can operate DingTalk direct
 curl -fsSL https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-workspace-cli/main/scripts/install-skills.sh | sh
 ```
 
-> `install.sh` installs under `$HOME/.agents/skills/` (global; multi layout is per-product siblings, mono is the `dws/` subdirectory); `install-skills.sh` installs under `./.agents/skills/` (current project).
+> Installers prefer detected agent-specific roots such as `$HOME/.codex/skills/`. They use `.agents/skills/` only as the generic fallback when no specific Agent is detected; multi layout is per-product siblings, while mono uses the `dws/` subdirectory.
 >
 > China users: prefix `DWS_GITEE_REPO` to use the Gitee mirror — see [China mirror](#china-mirror).
 
@@ -433,7 +433,7 @@ DWS_SKILL_SOURCE=/path/to/skills dws skill setup --mode multi
 | Flag | Values | Description |
 |------|--------|-------------|
 | `--mode` | `mono` \| `multi` | Skill layout; defaults to interactive prompt |
-| `--target` | `all` \| `claude` \| `cursor` \| `codex` \| `opencode` \| `qoder` | Where to install; `all` covers every detected agent home |
+| `--target` | `all` \| `claude` \| `cursor` \| `codex` \| `zcode` \| `opencode` \| `qoder` | Where to install; `all` covers every detected agent home, including ZCode at `~/.zcode/skills` |
 | `--source` | path | Local source directory (overrides bundled skills) |
 | `--yes` | — | Scripting-only: skip the confirmation prompt. Removals are still backed up to `~/.dws/skill-backups/` first |
 

README_zh.md

@@ -207,7 +207,7 @@ bash verify-all-channels.sh
 升级过程采用两阶段原子流程，确保一致性：
 
 1. **准备阶段** — 将平台对应的二进制文件和技能包下载到临时目录，校验 SHA256 校验和，解压并验证所有文件。任何步骤失败则立即中止，不会修改现有安装。
-2. **执行阶段** — 仅在所有准备工作成功后，替换二进制文件并将技能包安装到所有已检测到的 Agent 目录（`~/.agents/skills/dws`、`~/.claude/skills/dws`、`~/.cursor/skills/dws` 等）。
+2. **执行阶段** — 仅在所有准备工作成功后，替换二进制文件并将技能包平铺到已检测到的具体 Agent 目录（例如 `~/.codex/skills/dingtalk-chat`、`~/.claude/skills/dingtalk-chat`）。只有未检测到具体 Agent 时才使用 `~/.agents/skills`；检测到具体 Agent 后会备份迁走旧的 DWS 通用副本，避免同一 Skill 被重复发现。
 
 每次升级前自动备份当前版本，可通过 `dws upgrade --rollback` 随时回滚。
 
@@ -399,7 +399,7 @@ Schema 生成的叶子 safety/参数/选型文案由 Go 中的 ProductDecl / Con
 curl -fsSL https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-workspace-cli/main/scripts/install-skills.sh | sh
 ```
 
-> `install.sh` 安装到 `$HOME/.agents/skills/`（全局，multi 为按产品平铺，mono 为 `dws/` 子目录）；`install-skills.sh` 安装到 `./.agents/skills/`（当前项目）。
+> 安装器优先使用检测到的具体 Agent 根目录（如 `$HOME/.codex/skills/`）；仅在未检测到具体 Agent 时回退到 `.agents/skills/`。multi 为按产品平铺，mono 为 `dws/` 子目录。
 >
 > 国内用户加 `DWS_GITEE_REPO` 走 Gitee 镜像，见 [国内加速安装](#国内加速安装)。
 
@@ -427,7 +427,7 @@ DWS_SKILL_SOURCE=/path/to/skills dws skill setup --mode multi
 | 参数 | 取值 | 说明 |
 |------|------|------|
 | `--mode` | `mono` \| `multi` | skill 布局，不指定则交互式询问 |
-| `--target` | `all` \| `claude` \| `cursor` \| `codex` \| `opencode` \| `qoder` | 安装目标，`all` 表示铺到所有检测到的 Agent home |
+| `--target` | `all` \| `claude` \| `cursor` \| `codex` \| `zcode` \| `opencode` \| `qoder` | 安装目标；`all` 表示铺到检测到的具体 Agent home（ZCode 为 `~/.zcode/skills`），仅在未检测到具体 Agent 时回退到 `~/.agents/skills` |
 | `--source` | 路径 | 本地源目录（覆盖内置 skills） |
 | `--yes` | — | 仅供脚本使用：跳过确认提示。删除操作仍会先备份到 `~/.dws/skill-backups/` |
 

build/npm/install.js

@@ -17,6 +17,7 @@ const AGENT_DIRS = [
   ".qoderwork/skills",
   ".gemini/skills",
   ".codex/skills",
+  ".zcode/skills",
   ".github/skills",
   ".windsurf/skills",
   ".augment/skills",
@@ -233,6 +234,10 @@ function installSkillsToHomes(skillRoot) {
   let attempted = 0;
   let failed = 0;
 
+  const specificAgentDirs = AGENT_DIRS.slice(1).filter((agentDir) =>
+    fs.existsSync(path.dirname(path.join(homeDir, agentDir))),
+  );
+
   const installToBase = (baseDir) => {
     const victims = [path.join(baseDir, "dws")];
     if (fs.existsSync(baseDir)) {
@@ -252,6 +257,9 @@ function installSkillsToHomes(skillRoot) {
   };
 
   AGENT_DIRS.forEach((agentDir, index) => {
+    if (index === 0 && specificAgentDirs.length > 0) {
+      return;
+    }
     const baseDir = path.join(homeDir, agentDir);
     const parentGate = path.dirname(baseDir);
     if (index > 0 && !fs.existsSync(parentGate)) {
@@ -265,6 +273,15 @@ function installSkillsToHomes(skillRoot) {
     }
   });
 
+  if (specificAgentDirs.length > 0 && installed > 0) {
+    try {
+      retireGenericSkillRoot(homeDir, managedNames);
+    } catch (err) {
+      console.warn(`⚠️  通用 Skill 副本迁移失败: ${err.message}`);
+      failed += 1;
+    }
+  }
+
   if (attempted === 0) {
     if (installToBase(path.join(homeDir, ".agents", "skills"))) {
       installed += 1;
@@ -329,6 +346,40 @@ function isManagedMultiSkillDir(dir, managedNames) {
   return LEGACY_OFFICIAL_MULTI_SKILLS.has(name) || managedNames.has(name);
 }
 
+function retireGenericSkillRoot(homeDir, managedNames) {
+  const baseDir = path.join(homeDir, ".agents", "skills");
+  const victims = [path.join(baseDir, "dws")];
+  if (fs.existsSync(baseDir)) {
+    for (const entry of fs.readdirSync(baseDir, { withFileTypes: true })) {
+      if (entry.isDirectory() && isManagedMultiSkillDir(path.join(baseDir, entry.name), managedNames)) {
+        victims.push(path.join(baseDir, entry.name));
+      }
+    }
+  }
+  const backups = [];
+  try {
+    for (const victim of victims) {
+      if (!backupAndRemoveSkillDir(homeDir, victim, backups)) {
+        throw new Error(`failed to back up Skill directory ${victim}`);
+      }
+    }
+  } catch (err) {
+    const restoreErrors = [];
+    for (let i = backups.length - 1; i >= 0; i -= 1) {
+      try {
+        fs.mkdirSync(path.dirname(backups[i].original), { recursive: true });
+        fs.renameSync(backups[i].backup, backups[i].original);
+      } catch (restoreErr) {
+        restoreErrors.push(`${backups[i].original}: ${restoreErr.message}`);
+      }
+    }
+    if (restoreErrors.length > 0) {
+      throw new Error(`${err.message}; generic-root rollback failed: ${restoreErrors.join("; ")}`);
+    }
+    throw err;
+  }
+}
+
 function skillDirectoryDigest(dir) {
   const files = [];
   const visit = (current, prefix) => {
@@ -577,6 +628,10 @@ function installMultiSkillsToHomes(multiRoot) {
   let attempted = 0;
   let failed = 0;
 
+  const specificAgentDirs = AGENT_DIRS.slice(1).filter((agentDir) =>
+    fs.existsSync(path.dirname(path.join(homeDir, agentDir))),
+  );
+
   const installToBase = (baseDir) => {
     fs.mkdirSync(baseDir, { recursive: true });
     const victims = [path.join(baseDir, "dws")];
@@ -604,6 +659,9 @@ function installMultiSkillsToHomes(multiRoot) {
   };
 
   AGENT_DIRS.forEach((agentDir, index) => {
+    if (index === 0 && specificAgentDirs.length > 0) {
+      return;
+    }
     const baseDir = path.join(homeDir, agentDir);
     const parentGate = path.dirname(baseDir);
     if (index > 0 && !fs.existsSync(parentGate)) {
@@ -617,6 +675,15 @@ function installMultiSkillsToHomes(multiRoot) {
     }
   });
 
+  if (specificAgentDirs.length > 0 && installed > 0) {
+    try {
+      retireGenericSkillRoot(homeDir, managedNames);
+    } catch (err) {
+      console.warn(`⚠️  通用 Skill 副本迁移失败: ${err.message}`);
+      failed += 1;
+    }
+  }
+
   if (attempted === 0) {
     if (installToBase(path.join(homeDir, ".agents", "skills"))) {
       installed += 1;

docs/ci-pr-gates.md

@@ -48,8 +48,12 @@ It then runs:
   --fast-path "$PR_BASE_SHA" HEAD
 ```
 
-Because the verified PR diff contains only `CHANGELOG.md`, the validator and
-its policy dependencies in that merge tree are byte-for-byte the current base
+The exact fast path remains limited to historic one-file maintenance. A
+release-seal PR uses `--content-only`, which permits the generated
+`CHANGELOG.md` change together with archival moves from `.changes/` to
+`.changes/released/`; it receives the normal scoped admission instead of this
+fast path. Ordinary PRs must not modify `CHANGELOG.md`; they add a standalone
+release fragment instead. The validator and its policy dependencies in that merge tree are byte-for-byte the current base
 versions. Validation targets the synthetic merge tree, not the feature-branch
 tree, so a stale branch cannot supply an older validator or combine with newer
 base notes into an invalid final CHANGELOG.
@@ -79,10 +83,12 @@ to the complete main admission suite. A source change can therefore never
 inherit the CHANGELOG-only result.
 
 Any PR that touches `CHANGELOG.md` but also changes another file runs the same
-content contract in `Policy` with `--content-only`. That mode permits the
-second file but still rejects invalid dates or versions, missing bullets,
-placeholder `TODO`/`TBD`, unmanaged-section changes, and unsafe tree modes.
-Adding a second file therefore cannot bypass CHANGELOG validation.
+content contract in `Policy` with `--content-only`. That mode accepts only
+fragment archival moves (`.changes/<name>.md` to
+`.changes/released/<version>/<name>.md`) alongside the changelog; source and
+documentation changes are rejected. It still rejects invalid dates or
+versions, missing bullets, placeholder `TODO`/`TBD`, unmanaged-section
+changes, and unsafe tree modes.
 
 ## Risk tiers and downstream boundaries
 
@@ -184,11 +190,11 @@ Schema，并让 candidate 对两份历史 contract 独立执行检查；它只
 lifecycle 的 exact rename 规范化到当前历史副本，不会维护第二份 allowlist，也不会
 放宽其他 Schema 历史字段。
 
-For an exact CHANGELOG-only branch:
+For a release-seal branch that archives rendered fragments:
 
 ```sh
 base_ref=$(git merge-base HEAD origin/main)
-./scripts/policy/check-changelog-pr.sh --fast-path "$base_ref" HEAD
+./scripts/policy/check-changelog-pr.sh --content-only "$base_ref" HEAD
 ```
 
 `make coverage-gate` is an enforcement step, not a profile generator. For a
@@ -223,6 +229,52 @@ tool、parameter、mapping、positional execution、constraint 与 safety 语义
 等价证明；产品 PR 仍须证明 canonical 与 legacy 的最终运行 payload 等价并在 transport
 前拒绝冲突输入。当前迁移清单为空，不授权 PR #904。
 
+## 条件幂等与重试策略迁移
+
+静态 `idempotency` 描述命令级分类；当它是 `conditional` 时，再由实际调用参数计算
+本次调用的 effective idempotency。不能因为命令“存在一个可选 `--uuid` flag”就把
+整个命令从 `unknown` 改成无条件 `idempotent`。Schema 增加 `conditional` 状态以及
+与它配套的 `retry_policy`：
+
+```json
+{
+  "idempotency": "conditional",
+  "retry_policy": {
+    "mode": "deduplication_key",
+    "key_parameter": "uuid",
+    "same_payload_required": true
+  }
+}
+```
+
+只有调用实际提供 `uuid`，并且框架重用同一个 key 和同一份请求 payload 时，调用级
+有效幂等性才是 `idempotent`；未提供时仍是 `non_idempotent`。本契约没有发布后端
+未证明的去重时间窗。`conditional` 仅允许用于单 RPC 的 `mcp` leaf，key 必须对应
+一个存在且有非空 interface property 的真实参数。其余三种静态状态不得携带
+`retry_policy`。
+
+兼容迁移分三步治理：
+
+1. 独立治理 PR 在 Schema surface 不变时先加入契约、校验器和精确登记。本轮只登记
+   57 个 Chat 写命令：5 个 `unknown -> conditional`，52 个
+   `unknown -> non_idempotent`。
+2. 后续业务 PR 只消费这些已登记转换。5 个条件幂等命令必须逐字发布上面的策略；
+   PR #965 原先的 `unknown -> idempotent` 仍会失败。未登记工具、反向迁移、策略漂移
+   以及同一 PR 夹带的其它历史契约变化也仍会失败。
+3. 当 `main` 与当前 stable baseline 都已经覆盖迁移后，再由独立治理 PR 删除失效的
+   静态登记，避免把一次迁移审批永久留在规则中。
+
+Interface Integrity job 的兼容性 step 在 PR merge-base 建立独立 authority worktree，
+并从该 worktree 启动权威 wrapper；它不经过 candidate checkout 中的
+Makefile 或 wrapper。权威 wrapper 再从 merge-base 构建 `schema-compat` checker，
+分别比较 merge-base 和 stable。因此，在该 step 实际执行时，业务 candidate
+修改 candidate checkout 中的 Makefile、wrapper、checker 或登记表都不能给
+自己授权；只有先合入主干、经过独立评审的登记会被后续 PR 使用。
+
+CLI 评测和 Agent 消费方应把 `conditional` 与 `retry_policy` 作为一个整体读取：静态
+`conditional` 不是扣分意义上的“不知道”，也不是无条件可重试；评测应根据
+`key_parameter` 是否出现在实际调用中计算本次调用的有效幂等性。
+
 ## Required GitHub repository settings
 
 The `main` quality ruleset must enable strict required-status-check policy

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

@@ -0,0 +1,312 @@
+<!doctype html>
+<html lang="zh-CN">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <meta name="description" content="DWS Drive Shortcut 与 lark-cli 的业务能力、真实数据 E2E 证据和平台边界分析。">
+  <title>Drive Shortcut 能力全景｜业务评审版</title>
+  <style>
+    :root {
+      color-scheme: light;
+      --paper: #f4f6f2; --surface: #fffefa; --ink: #17251f; --muted: #66746d;
+      --line: #dce2dc; --forest: #154f3d; --green: #17765a; --mint: #dff4e8;
+      --blue: #265f86; --blue-soft: #e7f1f7; --amber: #8c5a09; --amber-soft: #fff2cf;
+      --red: #a43b32; --red-soft: #fde9e5; --shadow: 0 14px 40px rgba(28, 48, 38, .08);
+    }
+    * { box-sizing: border-box; }
+    html { scroll-behavior: smooth; }
+    body { margin: 0; color: var(--ink); background: var(--paper); font: 15px/1.65 -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; }
+    a { color: inherit; text-decoration: none; }
+    code { padding: .12rem .38rem; border: 1px solid #d6e0da; border-radius: 6px; color: #174f3e; background: #f1f7f3; font: 600 .88em/1.4 ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; white-space: nowrap; }
+    .wrap { width: min(1180px, calc(100% - 40px)); margin: auto; }
+    .hero { position: relative; overflow: hidden; padding: 64px 0 52px; color: #f7fff9; background: linear-gradient(125deg, #102b22 0%, #154c3c 57%, #1c6b54 100%); }
+    .hero::after { position: absolute; inset: -180px -100px auto auto; width: 540px; height: 540px; border: 1px solid rgba(255,255,255,.14); border-radius: 50%; box-shadow: 0 0 0 76px rgba(255,255,255,.035), 0 0 0 152px rgba(255,255,255,.025); content: ""; }
+    .hero-grid { position: relative; z-index: 1; display: grid; grid-template-columns: minmax(0, 1.35fr) minmax(300px, .65fr); gap: 32px; align-items: end; }
+    .eyebrow, .section-kicker { margin: 0 0 9px; color: #9fd6bd; font-size: 11px; font-weight: 900; letter-spacing: .16em; text-transform: uppercase; }
+    h1 { margin: 0; font-size: clamp(40px, 6vw, 68px); line-height: 1.03; letter-spacing: -.045em; }
+    .subtitle { max-width: 760px; margin: 19px 0 0; color: #d3e9de; font-size: 17px; }
+    .meta-row { display: flex; flex-wrap: wrap; gap: 8px; margin-top: 21px; }
+    .meta-pill { padding: 6px 10px; border: 1px solid rgba(255,255,255,.18); border-radius: 999px; color: #d5e9df; background: rgba(255,255,255,.07); font-size: 11px; font-weight: 750; }
+    .meta-pill.good { color: #bff2d5; border-color: rgba(139,232,179,.38); }
+    .hero-stats { display: grid; grid-template-columns: repeat(2, 1fr); gap: 10px; }
+    .hero-stat { padding: 17px 16px; border: 1px solid rgba(255,255,255,.17); border-radius: 15px; background: rgba(255,255,255,.075); backdrop-filter: blur(8px); }
+    .hero-stat strong { display: block; font-size: 30px; line-height: 1; }
+    .hero-stat span { display: block; margin-top: 7px; color: #cce2d7; font-size: 11px; }
+    .nav { position: sticky; top: 0; z-index: 20; border-bottom: 1px solid var(--line); background: rgba(255,254,250,.94); backdrop-filter: blur(12px); }
+    .nav .wrap { display: flex; overflow-x: auto; }
+    .nav a { flex: 0 0 auto; padding: 14px 15px; color: #5b6c64; font-size: 12px; font-weight: 800; }
+    .nav a:hover { color: var(--forest); background: #eaf3ee; }
+    main { padding: 38px 0 74px; }
+    section { margin-top: 50px; scroll-margin-top: 72px; }
+    section:first-child { margin-top: 0; }
+    .section-head { display: flex; justify-content: space-between; gap: 28px; align-items: end; margin-bottom: 19px; }
+    h2 { margin: 0; font-size: clamp(25px, 3.2vw, 36px); line-height: 1.16; letter-spacing: -.025em; }
+    h3 { margin: 0 0 7px; font-size: 18px; }
+    .section-desc { max-width: 660px; margin: 0; color: var(--muted); font-size: 13px; }
+    .callout { padding: 19px 21px; border: 1px solid #bdd8cb; border-left: 4px solid var(--green); border-radius: 13px; background: #ecf7f1; box-shadow: 0 6px 20px rgba(28,48,38,.04); }
+    .callout strong { color: #13513d; }
+    .callout.warn { border-color: #ead29a; border-left-color: #b67508; background: #fff8e7; }
+    .callout.warn strong { color: #784b00; }
+    .callout.danger { border-color: #e9b7b1; border-left-color: var(--red); background: var(--red-soft); }
+    .score-grid, .domain-grid, .evidence-grid, .review-grid { display: grid; gap: 13px; }
+    .score-grid { grid-template-columns: repeat(4, 1fr); margin-top: 16px; }
+    .score, .domain-card, .evidence-card, .review-card { border: 1px solid var(--line); border-radius: 15px; background: var(--surface); box-shadow: var(--shadow); }
+    .score { padding: 19px; }
+    .score strong { display: block; color: var(--forest); font-size: 29px; line-height: 1; }
+    .score span { display: block; margin-top: 8px; color: var(--muted); font-size: 12px; }
+    .domain-grid { grid-template-columns: repeat(4, 1fr); }
+    .domain-card { position: relative; padding: 21px; overflow: hidden; }
+    .domain-card .number { position: absolute; top: 12px; right: 17px; color: #d5e8de; font: 800 42px/1 ui-monospace, monospace; }
+    .domain-card p { min-height: 64px; margin: 8px 0 12px; color: var(--muted); font-size: 13px; }
+    .domain-card small { color: var(--green); font-weight: 800; }
+    .compare { overflow: hidden; border: 1px solid var(--line); border-radius: 16px; background: var(--surface); box-shadow: var(--shadow); }
+    .compare-top { display: grid; grid-template-columns: repeat(3, 1fr); }
+    .compare-column { padding: 21px; border-right: 1px solid var(--line); }
+    .compare-column:last-child { border-right: 0; }
+    .compare-column p, .compare-column li { color: var(--muted); font-size: 13px; }
+    .compare-column ul { margin: 9px 0 0; padding-left: 18px; }
+    .compare-column.covered { border-top: 5px solid var(--green); }
+    .compare-column.partial { border-top: 5px solid #c78b22; }
+    .compare-column.gap { border-top: 5px solid var(--red); }
+    .table-wrap { overflow-x: auto; }
+    table { width: 100%; border-collapse: collapse; }
+    th, td { padding: 12px 14px; border-bottom: 1px solid var(--line); text-align: left; vertical-align: top; }
+    th { color: #617069; background: #f7f8f5; font-size: 11px; font-weight: 900; letter-spacing: .03em; }
+    tr:last-child td { border-bottom: 0; }
+    tbody tr:hover { background: #f8fbf8; }
+    .verdict, .badge { display: inline-flex; align-items: center; padding: 3px 8px; border-radius: 999px; font-size: 10px; font-weight: 900; white-space: nowrap; }
+    .v-covered, .badge.read { color: #116045; background: var(--mint); }
+    .v-ahead, .badge.smart { color: #20577c; background: var(--blue-soft); }
+    .v-partial, .badge.write { color: #7b510a; background: var(--amber-soft); }
+    .v-gap, .badge.high { color: #8f3028; background: var(--red-soft); }
+    .truth-grid { display: grid; grid-template-columns: 1.1fr .9fr; gap: 14px; }
+    .truth-card { padding: 22px; border: 1px solid var(--line); border-radius: 15px; background: var(--surface); box-shadow: var(--shadow); }
+    .truth-step { display: grid; grid-template-columns: 30px 1fr; gap: 11px; margin-top: 13px; }
+    .truth-step b { display: grid; width: 28px; height: 28px; place-items: center; border-radius: 50%; color: #fff; background: var(--forest); font-size: 12px; }
+    .truth-step strong, .truth-step span { display: block; }
+    .truth-step span { color: var(--muted); font-size: 12px; }
+    .toolbar { display: grid; grid-template-columns: minmax(260px, 1fr) 180px 180px auto; gap: 10px; align-items: center; margin: 18px 0; padding: 13px; border: 1px solid var(--line); border-radius: 14px; background: var(--surface); }
+    input, select { width: 100%; min-height: 42px; padding: 9px 11px; border: 1px solid #ccd7d0; border-radius: 9px; color: var(--ink); background: #fff; font: inherit; }
+    input:focus, select:focus { outline: 3px solid rgba(23,118,90,.13); border-color: var(--green); }
+    .result-count { color: var(--muted); font-size: 12px; text-align: right; white-space: nowrap; }
+    .catalog { overflow: hidden; border: 1px solid var(--line); border-radius: 16px; background: var(--surface); box-shadow: var(--shadow); }
+    .shortcut-row { display: grid; grid-template-columns: 215px minmax(0, 1fr) 200px; gap: 16px; align-items: center; padding: 14px 17px; border-bottom: 1px solid var(--line); }
+    .shortcut-row:last-child { border-bottom: 0; }
+    .shortcut-row:hover { background: #f8fbf8; }
+    .command code { font-size: 12px; }
+    .row-main p { margin: 0; font-size: 13px; }
+    .row-main small { color: var(--muted); }
+    .badges { display: flex; justify-content: flex-end; flex-wrap: wrap; gap: 5px; }
+    .hidden-row { display: none; }
+    .evidence-grid { grid-template-columns: repeat(4, 1fr); }
+    .evidence-card { padding: 19px; }
+    .evidence-card strong { display: block; color: var(--forest); font-size: 23px; }
+    .evidence-card p { margin: 7px 0 0; color: var(--muted); font-size: 12px; }
+    .timeline { margin-top: 15px; border-left: 2px solid #bdd7ca; }
+    .event { position: relative; padding: 0 0 17px 22px; }
+    .event::before { position: absolute; left: -7px; top: 5px; width: 12px; height: 12px; border: 3px solid var(--paper); border-radius: 50%; background: var(--green); content: ""; }
+    .event b { display: block; }
+    .event span { color: var(--muted); font-size: 12px; }
+    .review-grid { grid-template-columns: repeat(3, 1fr); }
+    .review-card { position: relative; padding: 20px; }
+    .review-card .review-num { color: #b8d1c4; font: 800 12px/1 ui-monospace, monospace; letter-spacing: .1em; }
+    .review-card p { margin: 7px 0 0; color: var(--muted); font-size: 13px; }
+    footer { margin-top: 52px; padding: 23px 0; border-top: 1px solid var(--line); color: var(--muted); font-size: 11px; }
+    @media (max-width: 900px) { .hero-grid, .truth-grid { grid-template-columns: 1fr; } .score-grid, .domain-grid, .evidence-grid { grid-template-columns: repeat(2, 1fr); } .review-grid { grid-template-columns: 1fr 1fr; } .shortcut-row { grid-template-columns: 180px 1fr; } .badges { grid-column: 1 / -1; justify-content: flex-start; } }
+    @media (max-width: 620px) { .wrap { width: min(100% - 24px, 1180px); } .hero { padding: 44px 0 38px; } .hero-stats, .score-grid, .domain-grid, .evidence-grid, .review-grid, .compare-top { grid-template-columns: 1fr; } .compare-column { border-right: 0; border-bottom: 1px solid var(--line); } .toolbar { grid-template-columns: 1fr; } .result-count { text-align: left; } .shortcut-row { grid-template-columns: 1fr; } }
+    @media print { body { background: #fff; } .hero { color: var(--ink); background: #fff; border-bottom: 2px solid var(--ink); } .subtitle, .meta-pill, .hero-stat span { color: #425249; } .hero-stat { border-color: #aebbb3; } .nav, .toolbar { display: none; } .score, .domain-card, .compare, .truth-card, .catalog, .evidence-card, .review-card { box-shadow: none; break-inside: avoid; } }
+  </style>
+</head>
+<body>
+  <header class="hero">
+    <div class="wrap hero-grid">
+      <div>
+        <p class="eyebrow">Business Review · Drive</p>
+        <h1>Drive Shortcut<br>能力全景</h1>
+        <p class="subtitle">从 lark-cli 对齐出发，但不止于命令名：逐项审查输入、校验、多步编排、失败语义、真实字节和平台边界。</p>
+        <div class="meta-row">
+          <span class="meta-pill good">真实账号 E2E 已执行</span>
+          <span class="meta-pill">28 个公开入口</span>
+          <span class="meta-pill">统一 Result / Pagination</span>
+          <span class="meta-pill">报告已移除 PII / 凭证 / 业务正文</span>
+        </div>
+      </div>
+      <div class="hero-stats" aria-label="关键统计">
+        <div class="hero-stat"><strong>38</strong><span>lark-cli Drive 逐项审查</span></div>
+        <div class="hero-stat"><strong>26</strong><span>已覆盖或跨产品路由</span></div>
+        <div class="hero-stat"><strong>7</strong><span>部分对齐，边界已公开</span></div>
+        <div class="hero-stat"><strong>5</strong><span>客观不可对齐能力</span></div>
+      </div>
+    </div>
+  </header>
+
+  <nav class="nav"><div class="wrap"><a href="#overview">全景</a><a href="#compare">Lark 对齐</a><a href="#ahead">超越项</a><a href="#truth">真实语义</a><a href="#catalog">完整目录</a><a href="#e2e">E2E</a><a href="#review">评审</a></div></nav>
+
+  <main class="wrap">
+    <section id="overview">
+      <div class="section-head"><div><p class="section-kicker">Executive summary</p><h2>28 个公开入口，覆盖文件完整生命周期</h2></div><p class="section-desc">另有 <code>+publish-set</code> 已实现契约和读回逻辑，但真实普通文件与在线文档均被服务端拒绝，因此保持 unavailable，不进入 Agent 公开目录。</p></div>
+      <div class="callout"><strong>结论：</strong>Drive 已从 9 个偏原子入口扩展为 28 个可发现 Shortcut。它不仅补齐 Lark 的核心文件、版本和状态任务，还通过严格响应合同、真实落盘、写后读回、回收恢复和个人收藏形成更可审计的钉盘工作流。</div>
+      <div class="score-grid">
+        <article class="score"><strong>29</strong><span>已审查注册项（含 1 unavailable）</span></article>
+        <article class="score"><strong>25</strong><span>公开主能力 / 语义适配</span></article>
+        <article class="score"><strong>3</strong><span>公开兼容入口</span></article>
+        <article class="score"><strong>3</strong><span>高风险写入口，均需确认</span></article>
+      </div>
+    </section>
+
+    <section>
+      <div class="section-head"><div><p class="section-kicker">Capability map</p><h2>四个业务域</h2></div><p class="section-desc">目录按用户任务组织；兼容命令不重复计为新增能力。</p></div>
+      <div class="domain-grid">
+        <article class="domain-card"><span class="number">09</span><h3>发现与检查</h3><p>严格目录分页、搜索、最近访问，以及元数据、统计和封面聚合检查。</p><small>+list · +search · +recent · +inspect</small></article>
+        <article class="domain-card"><span class="number">09</span><h3>文件生命周期</h3><p>创建目录、上传下载、快捷方式、在线对象复制、移动重命名、删除与恢复。</p><small>+upload · +download · +rename · +recycle-restore</small></article>
+        <article class="domain-card"><span class="number">06</span><h3>个人与公开状态</h3><p>回收站清单、收藏闭环和互联网公开状态的独立安全域。</p><small>+star-list · +star-add · +publish-get</small></article>
+        <article class="domain-card"><span class="number">04</span><h3>历史版本</h3><p>版本列表、精确定位、真实字节下载与高风险回滚读回。</p><small>+version-history · +version-download · +version-revert</small></article>
+      </div>
+    </section>
+
+    <section id="compare">
+      <div class="section-head"><div><p class="section-kicker">Lark alignment</p><h2>对齐业务语义，不追求同名率</h2></div><p class="section-desc">38 项逐项核对。评论、导入导出和成员权限在 DWS 由更成熟的 Doc 或原子权限入口承接，不在 Drive 再复制一套。</p></div>
+      <div class="compare">
+        <div class="compare-top">
+          <article class="compare-column covered"><h3>26 · 已覆盖 / 路由</h3><p>上传下载、目录与快捷方式、版本、移动删除、状态、搜索、评论、导入导出和成员任务均有真实入口。</p></article>
+          <article class="compare-column partial"><h3>7 · 部分对齐</h3><p>预览、resolve/reaction、push/pull、权限申请与 setting 受对象模型或接口粒度约束，明确保留有限语义。</p></article>
+          <article class="compare-column gap"><h3>5 · 客观缺口</h3><p>删除评论恢复、普通文件版本删除、安全标签读写、可靠双向目录同步缺少必要下层接口。</p></article>
+        </div>
+        <div class="table-wrap"><table><thead><tr><th>Lark 任务组</th><th>DWS 主路径</th><th>结论</th><th>关键差异与交付决定</th></tr></thead><tbody>
+          <tr><td>upload / folder / shortcut / download</td><td><code>drive +upload</code> 等</td><td><span class="verdict v-ahead">增强</span></td><td>工作目录边界、OSS PUT、严格 commit、no-clobber、原子落盘、非零字节和读回验证。</td></tr>
+          <tr><td>preview / cover</td><td><code>drive +cover</code></td><td><span class="verdict v-partial">部分</span></td><td>封面/缩略图可读；没有等价的服务端多格式预览转换，不扩大宣称。</td></tr>
+          <tr><td>comments / replies</td><td><code>doc +comment-*</code> / <code>doc +review</code></td><td><span class="verdict v-covered">路由</span></td><td>评论归在线文档协作域；独立 resolve、reaction identity 与删除后恢复仍受接口限制。</td></tr>
+          <tr><td>export / import / task result</td><td><code>doc +export</code> / <code>doc +import</code></td><td><span class="verdict v-ahead">增强</span></td><td>提交、轮询、恢复、安全下载形成类型化闭环，不保留泛化下划线命令。</td></tr>
+          <tr><td>version history / get / revert</td><td><code>drive +version-*</code></td><td><span class="verdict v-ahead">增强</span></td><td>严格分页、精确版本、历史字节落盘、回滚前预检与终态读回；历史版本删除无接口。</td></tr>
+          <tr><td>status / inspect</td><td><code>drive +inspect</code></td><td><span class="verdict v-ahead">超越</span></td><td>元数据为必达结果，统计、公开状态和封面按需 fan-out；可选失败为 partial_success。</td></tr>
+          <tr><td>push / pull / sync</td><td><code>+upload</code> / <code>+download</code> 单文件</td><td><span class="verdict v-partial">部分</span></td><td>不在缺少稳定 hash、rename/delete journal 和冲突向量时制造危险目录同步。</td></tr>
+          <tr><td>member / permission</td><td><code>doc +access-*</code> / <code>drive permission</code></td><td><span class="verdict v-covered">路由</span></td><td>协作者权限与互联网公开是两个安全域；申请权限需真实上下文，未伪装为通用 Shortcut。</td></tr>
+          <tr><td>secure labels</td><td>无等价</td><td><span class="verdict v-gap">缺口</span></td><td>当前 DWS/钉钉下层没有 Drive 安全标签目录和写入接口，不能用普通权限代替。</td></tr>
+          <tr><td>search</td><td><code>drive +search</code> / <code>doc +search</code></td><td><span class="verdict v-ahead">增强</span></td><td>文件与在线文档按域路由；文件搜索严格验证数组、过滤和分页。</td></tr>
+        </tbody></table></div>
+      </div>
+      <div class="callout warn" style="margin-top:14px"><strong>普通文件 copy 边界：</strong>钉钉现有复制接口对普通文件产生 <code>.dlink</code>，不是字节独立副本。因此 <code>+copy</code> 只接受在线对象；普通文件快捷入口用 <code>+create-shortcut</code>，独立副本使用 <code>+download</code> 后 <code>+upload</code>。</div>
+    </section>
+
+    <section id="ahead">
+      <div class="section-head"><div><p class="section-kicker">Beyond parity</p><h2>DWS 可主推的八个差异化点</h2></div><p class="section-desc">价值来自正确性与完整闭环，而不是额外注册同义命令。</p></div>
+      <div class="domain-grid">
+        <article class="domain-card"><h3>严格目录语义</h3><p><code>+list</code> / <code>+recent</code> 只有服务端明确返回数组时才接受空集合。</p><small>缺字段 ≠ 空目录</small></article>
+        <article class="domain-card"><h3>聚合检查</h3><p><code>+inspect</code> 一次汇总身份、统计、公开状态和封面，并保留局部失败。</p><small>partial_success 可审计</small></article>
+        <article class="domain-card"><h3>真实文件传输</h3><p>上传执行完整事务；下载验证受控路径、覆盖策略、原子发布和字节。</p><small>不是只返回临时 URL</small></article>
+        <article class="domain-card"><h3>回收恢复闭环</h3><p>从 <code>recycleItemId</code> 恢复后读取真实节点，证明资源确实回到可访问状态。</p><small>恢复后读回</small></article>
+        <article class="domain-card"><h3>个人收藏闭环</h3><p>收藏、列表、取消收藏覆盖完整用户偏好过程，并保留分页。</p><small>add → list → remove</small></article>
+        <article class="domain-card"><h3>版本真实字节</h3><p>除元数据外可下载任意已知历史版本，并用本地字节核验回滚结果。</p><small>version-download</small></article>
+        <article class="domain-card"><h3>重命名终态</h3><p>处理服务端扩展名规则，再读取节点确认最终名称，避免重复扩展名。</p><small>write → read-back</small></article>
+        <article class="domain-card"><h3>公开域诚实降级</h3><p>查询和关闭可验证；开启在 eligible 节点闭环完成前保持 unavailable。</p><small>不把 notSupported 当成功</small></article>
+      </div>
+    </section>
+
+    <section id="truth">
+      <div class="section-head"><div><p class="section-kicker">Truthful execution</p><h2>空数组不再是“看起来成功”</h2></div><p class="section-desc">合法业务空集合可以成功，但必须先证明响应结构、元素类型和分页语义成立。内部错误、缺字段与坏投影必须失败。</p></div>
+      <div class="truth-grid">
+        <article class="truth-card"><h3>四层成功证据</h3>
+          <div class="truth-step"><b>1</b><div><strong>传输成功</strong><span>进程成功，MCP / HTTP 没有显式错误。</span></div></div>
+          <div class="truth-step"><b>2</b><div><strong>响应合同</strong><span>对象、数组、success 标志和元素类型与命令声明一致。</span></div></div>
+          <div class="truth-step"><b>3</b><div><strong>业务终态</strong><span>写命令必须获得新 ID、终态证据或后续元数据读回。</span></div></div>
+          <div class="truth-step"><b>4</b><div><strong>产物校验</strong><span>下载必须落盘、非零字节；关键链路比较大小和 SHA-256。</span></div></div>
+        </article>
+        <article class="truth-card"><h3>明确失败的情况</h3>
+          <ul><li>空响应、缺少预期集合字段或集合类型错误。</li><li>集合存在坏元素，不能投影时静默丢弃。</li><li><code>success=false</code>、写响应没有 ID 或读回不一致。</li><li>inspect 的可选分支失败却返回整体 success。</li><li>下载得到空文件、越界路径或覆盖既有文件。</li><li>普通文件 copy 返回快捷链接却声称独立副本。</li></ul>
+        </article>
+      </div>
+    </section>
+
+    <section id="catalog">
+      <div class="section-head"><div><p class="section-kicker">Full catalog</p><h2>28 个公开 Shortcut 完整目录</h2></div><p class="section-desc">16 个只读、9 个普通写、3 个高风险写；3 个历史入口保留兼容但不作为新 Agent 主路径。</p></div>
+      <div class="toolbar"><input id="q" type="search" placeholder="搜索命令或用途，例如 版本、回收、+inspect…" aria-label="搜索 Shortcut"><select id="domain"><option value="all">全部业务域</option><option value="discover">发现与检查</option><option value="lifecycle">文件生命周期</option><option value="personal">个人与公开</option><option value="version">历史版本</option></select><select id="risk"><option value="all">全部风险</option><option value="read">只读</option><option value="write">普通写</option><option value="high">高风险写</option></select><span id="result-count" class="result-count">显示 28 / 28</span></div>
+      <div class="catalog">
+        <article class="shortcut-row" data-tool data-domain="discover" data-risk="read"><div class="command"><code>dws drive +list</code></div><div class="row-main"><p>严格分页列出目录，保留游标，区分显式空目录和畸形响应。</p><small>发现与检查</small></div><div class="badges"><span class="badge read">READ</span></div></article>
+        <article class="shortcut-row" data-tool data-domain="discover" data-risk="read"><div class="command"><code>dws drive +inspect</code></div><div class="row-main"><p>聚合元数据与可选统计、公开状态、封面；局部失败如实报告。</p><small>发现与检查</small></div><div class="badges"><span class="badge read">READ</span><span class="badge smart">SMART</span></div></article>
+        <article class="shortcut-row" data-tool data-domain="discover" data-risk="read"><div class="command"><code>dws drive +info</code></div><div class="row-main"><p>历史元数据兼容入口；新场景优先使用 +inspect。</p><small>兼容入口</small></div><div class="badges"><span class="badge read">READ</span></div></article>
+        <article class="shortcut-row" data-tool data-domain="discover" data-risk="read"><div class="command"><code>dws drive +search</code></div><div class="row-main"><p>按关键词、类型、扩展名、创建人、时间和分页搜索钉盘文件。</p><small>发现与检查</small></div><div class="badges"><span class="badge read">READ</span></div></article>
+        <article class="shortcut-row" data-tool data-domain="discover" data-risk="read"><div class="command"><code>dws drive +find-file</code></div><div class="row-main"><p>历史文件搜索兼容入口；新场景优先使用 +search。</p><small>兼容入口</small></div><div class="badges"><span class="badge read">READ</span></div></article>
+        <article class="shortcut-row" data-tool data-domain="discover" data-risk="read"><div class="command"><code>dws drive +search-docs</code></div><div class="row-main"><p>历史跨域搜索入口；新的在线文档搜索路由 doc +search。</p><small>兼容入口</small></div><div class="badges"><span class="badge read">READ</span></div></article>
+        <article class="shortcut-row" data-tool data-domain="discover" data-risk="read"><div class="command"><code>dws drive +recent</code></div><div class="row-main"><p>读取最近访问或编辑列表，支持创建人筛选并保留分页。</p><small>发现与检查</small></div><div class="badges"><span class="badge read">READ</span></div></article>
+        <article class="shortcut-row" data-tool data-domain="discover" data-risk="read"><div class="command"><code>dws drive +stats</code></div><div class="row-main"><p>读取访问、编辑、评论、点赞、预览和下载统计。</p><small>发现与检查</small></div><div class="badges"><span class="badge read">READ</span></div></article>
+        <article class="shortcut-row" data-tool data-domain="discover" data-risk="read"><div class="command"><code>dws drive +cover</code></div><div class="row-main"><p>读取封面或缩略图；不宣称服务端多格式预览。</p><small>发现与检查</small></div><div class="badges"><span class="badge read">READ</span></div></article>
+
+        <article class="shortcut-row" data-tool data-domain="lifecycle" data-risk="write"><div class="command"><code>dws drive +upload</code></div><div class="row-main"><p>上传凭证、OSS PUT、严格提交和远端元数据读回的一体化事务。</p><small>文件生命周期</small></div><div class="badges"><span class="badge write">WRITE · CONFIRM</span><span class="badge smart">SMART</span></div></article>
+        <article class="shortcut-row" data-tool data-domain="lifecycle" data-risk="read"><div class="command"><code>dws drive +download</code></div><div class="row-main"><p>安全落盘、no-clobber、原子发布并验证非零字节。</p><small>文件生命周期</small></div><div class="badges"><span class="badge read">READ</span><span class="badge smart">SMART</span></div></article>
+        <article class="shortcut-row" data-tool data-domain="lifecycle" data-risk="write"><div class="command"><code>dws drive +create-folder</code></div><div class="row-main"><p>创建文件夹后要求新 ID，并读回名称验证。</p><small>文件生命周期</small></div><div class="badges"><span class="badge write">WRITE · CONFIRM</span></div></article>
+        <article class="shortcut-row" data-tool data-domain="lifecycle" data-risk="write"><div class="command"><code>dws drive +create-shortcut</code></div><div class="row-main"><p>创建快捷方式并读回，明确区别于独立副本。</p><small>文件生命周期</small></div><div class="badges"><span class="badge write">WRITE · CONFIRM</span></div></article>
+        <article class="shortcut-row" data-tool data-domain="lifecycle" data-risk="write"><div class="command"><code>dws drive +copy</code></div><div class="row-main"><p>复制在线对象；普通文件预检拒绝，避免把 .dlink 当副本。</p><small>文件生命周期</small></div><div class="badges"><span class="badge write">WRITE · CONFIRM</span><span class="badge smart">SMART</span></div></article>
+        <article class="shortcut-row" data-tool data-domain="lifecycle" data-risk="write"><div class="command"><code>dws drive +move</code></div><div class="row-main"><p>移动到指定文件夹或知识库位置，语义与 copy/shortcut 消歧。</p><small>文件生命周期</small></div><div class="badges"><span class="badge write">WRITE · CONFIRM</span></div></article>
+        <article class="shortcut-row" data-tool data-domain="lifecycle" data-risk="write"><div class="command"><code>dws drive +rename</code></div><div class="row-main"><p>重命名后读取真实节点，验证最终名称和扩展名。</p><small>文件生命周期</small></div><div class="badges"><span class="badge write">WRITE · CONFIRM</span><span class="badge smart">SMART</span></div></article>
+        <article class="shortcut-row" data-tool data-domain="lifecycle" data-risk="high"><div class="command"><code>dws drive +delete</code></div><div class="row-main"><p>将确认过的节点移入回收站，要求 success=true 终态证据。</p><small>文件生命周期</small></div><div class="badges"><span class="badge high">HIGH · CONFIRM</span></div></article>
+        <article class="shortcut-row" data-tool data-domain="lifecycle" data-risk="write"><div class="command"><code>dws drive +recycle-restore</code></div><div class="row-main"><p>按回收项 ID 恢复，并读回恢复后的节点。</p><small>文件生命周期</small></div><div class="badges"><span class="badge write">WRITE · CONFIRM</span><span class="badge smart">SMART</span></div></article>
+
+        <article class="shortcut-row" data-tool data-domain="personal" data-risk="read"><div class="command"><code>dws drive +recycle-list</code></div><div class="row-main"><p>严格分页列出回收项并稳定投影 recycleItemId。</p><small>个人与公开</small></div><div class="badges"><span class="badge read">READ</span></div></article>
+        <article class="shortcut-row" data-tool data-domain="personal" data-risk="read"><div class="command"><code>dws drive +star-list</code></div><div class="row-main"><p>严格分页列出当前用户收藏并保留游标。</p><small>个人与公开</small></div><div class="badges"><span class="badge read">READ</span></div></article>
+        <article class="shortcut-row" data-tool data-domain="personal" data-risk="write"><div class="command"><code>dws drive +star-add</code></div><div class="row-main"><p>以幂等用户偏好语义收藏指定节点。</p><small>个人与公开</small></div><div class="badges"><span class="badge write">WRITE</span></div></article>
+        <article class="shortcut-row" data-tool data-domain="personal" data-risk="write"><div class="command"><code>dws drive +star-remove</code></div><div class="row-main"><p>以幂等用户偏好语义取消收藏指定节点。</p><small>个人与公开</small></div><div class="badges"><span class="badge write">WRITE</span></div></article>
+        <article class="shortcut-row" data-tool data-domain="personal" data-risk="read"><div class="command"><code>dws drive +publish-get</code></div><div class="row-main"><p>只读查询互联网公开状态，不沿用错误的写风险标签。</p><small>个人与公开</small></div><div class="badges"><span class="badge read">READ</span></div></article>
+        <article class="shortcut-row" data-tool data-domain="personal" data-risk="high"><div class="command"><code>dws drive +publish-unset</code></div><div class="row-main"><p>关闭互联网公开并读回验证外链状态。</p><small>个人与公开</small></div><div class="badges"><span class="badge high">HIGH · CONFIRM</span><span class="badge smart">SMART</span></div></article>
+
+        <article class="shortcut-row" data-tool data-domain="version" data-risk="read"><div class="command"><code>dws drive +version-history</code></div><div class="row-main"><p>严格分页列出普通文件历史版本。</p><small>历史版本</small></div><div class="badges"><span class="badge read">READ</span></div></article>
+        <article class="shortcut-row" data-tool data-domain="version" data-risk="read"><div class="command"><code>dws drive +version-get</code></div><div class="row-main"><p>按正整数版本号精确匹配，零命中显式失败。</p><small>历史版本</small></div><div class="badges"><span class="badge read">READ</span><span class="badge smart">SMART</span></div></article>
+        <article class="shortcut-row" data-tool data-domain="version" data-risk="read"><div class="command"><code>dws drive +version-download</code></div><div class="row-main"><p>预检版本后安全下载历史字节，要求非零产物。</p><small>历史版本</small></div><div class="badges"><span class="badge read">READ</span><span class="badge smart">SMART</span></div></article>
+        <article class="shortcut-row" data-tool data-domain="version" data-risk="high"><div class="command"><code>dws drive +version-revert</code></div><div class="row-main"><p>验证版本存在后回滚，并读取当前节点终态。</p><small>历史版本</small></div><div class="badges"><span class="badge high">HIGH · CONFIRM</span><span class="badge smart">SMART</span></div></article>
+      </div>
+      <div class="callout warn" style="margin-top:14px"><strong>未公开入口：</strong><code>+publish-set</code> 的安全契约和 set→get 读回代码已存在，但真实后端返回 <code>operation.notSupported</code>。在找到 eligible 节点并完成 set→get→unset 闭环前，不进入公开 Agent catalog。</div>
+    </section>
+
+    <section id="e2e">
+      <div class="section-head"><div><p class="section-kicker">Real-data E2E</p><h2>真实数据验证，不用空结果证明成功</h2></div><p class="section-desc">测试在隔离目录创建临时资源，覆盖读取、写入、下载、版本、收藏、回收和清理。资源 ID、账号、URL、上传凭证、绝对路径和业务正文均未进入报告。</p></div>
+      <div class="evidence-grid">
+        <article class="evidence-card"><strong>39,838 B</strong><p>真实文件上传后下载字节数；与源文件 SHA-256 完全一致。</p></article>
+        <article class="evidence-card"><strong>2 versions</strong><p>覆盖写入生成两个版本；精确查询、历史下载和回滚全部读回。</p></article>
+        <article class="evidence-card"><strong>4 / 5</strong><p>隔离夹具中搜索命中 4 项、最近列表命中 5 项，证明非空投影链路。</p></article>
+        <article class="evidence-card"><strong>0 remain</strong><p>测试结束后隔离根目录无残留；临时资源进入回收站并完成本地清理。</p></article>
+      </div>
+      <div class="timeline">
+        <div class="event"><b>创建与发现</b><span>创建两个隔离目录并读回；+list 命中真实节点，由此发现并修复 dentryId 与 32 字符 fileId 混用。</span></div>
+        <div class="event"><b>上传与下载</b><span>真实 OSS 上传、远端元数据读回、下载、no-clobber 二次路径、大小与 SHA-256 一致性全部通过。</span></div>
+        <div class="event"><b>检查与个人状态</b><span>+inspect（含 stats / publish / cover）、+stats、+cover、收藏 add→list→remove 通过。</span></div>
+        <div class="event"><b>版本闭环</b><span>覆盖文件产生两个版本；history/get/download/revert 通过，回滚后最新字节与原始内容一致。</span></div>
+        <div class="event"><b>复制、移动与命名</b><span>在线文档 copy 通过；普通文件 .dlink 被修正为预检拒绝；move 往返、rename 扩展名规范化通过。</span></div>
+        <div class="event"><b>删除与恢复</b><span>delete→recycle-list→recycle-restore 通过，真实回收响应字段已按后端形态修正。</span></div>
+        <div class="event"><b>平台负向证据</b><span>publish-set 对普通文件和在线文档均明确返回不支持，因此保持 unavailable；没有把失败改写成空对象成功。</span></div>
+        <div class="event"><b>清理</b><span>隔离目录进入回收站，根目录残留计数为零；本地下载产物删除。</span></div>
+      </div>
+    </section>
+
+    <section id="review">
+      <div class="section-head"><div><p class="section-kicker">Review prompts</p><h2>建议业务评审重点确认</h2></div><p class="section-desc">这些是需要接受的产品边界，不是被空结果遮蔽的实现问题。</p></div>
+      <div class="review-grid">
+        <article class="review-card"><span class="review-num">01</span><h3>是否接受 26 / 7 / 5 结论？</h3><p>按用户任务计覆盖、部分与缺口，不用同名命令数量代替语义保真。</p></article>
+        <article class="review-card"><span class="review-num">02</span><h3>普通文件 copy 是否足够清晰？</h3><p>服务端无法提供原子独立副本；快捷方式与下载后上传两条替代路径已明确。</p></article>
+        <article class="review-card"><span class="review-num">03</span><h3>是否拒绝不可靠目录 sync？</h3><p>缺稳定 hash、删除/重命名日志和冲突向量时，不发布可能覆盖数据的双向同步。</p></article>
+        <article class="review-card"><span class="review-num">04</span><h3>跨产品路由是否合理？</h3><p>评论、导入导出和协作者权限优先复用 Doc 成熟入口，不在 Drive 制造同义表面。</p></article>
+        <article class="review-card"><span class="review-num">05</span><h3>publish-set 是否继续 unavailable？</h3><p>建议维持，直到真实 eligible 节点完成开启、查询、关闭的可恢复闭环。</p></article>
+        <article class="review-card"><span class="review-num">06</span><h3>下一批后端解锁优先级？</h3><p>建议依次评估普通文件原子 copy、同步所需版本信号、安全标签和评论恢复接口。</p></article>
+      </div>
+    </section>
+  </main>
+
+  <footer><div class="wrap">依据：DWS 最终 Shortcut catalog / Schema、Drive 实现与测试、真实账号 E2E、lark-cli Drive registrations 与实现。范围仅含 Drive Shortcut 及必要跨产品路由；不包含原子命令总表。所有业务标识、凭证、签名 URL、用户信息和正文均已脱敏。</div></footer>
+  <script>
+    const q = document.querySelector('#q');
+    const domain = document.querySelector('#domain');
+    const risk = document.querySelector('#risk');
+    const rows = [...document.querySelectorAll('[data-tool]')];
+    const count = document.querySelector('#result-count');
+    function filterTools() {
+      const needle = q.value.trim().toLocaleLowerCase('zh-CN');
+      let visible = 0;
+      rows.forEach((row) => {
+        const show = (!needle || row.textContent.toLocaleLowerCase('zh-CN').includes(needle)) && (domain.value === 'all' || row.dataset.domain === domain.value) && (risk.value === 'all' || row.dataset.risk === risk.value);
+        row.classList.toggle('hidden-row', !show);
+        if (show) visible += 1;
+      });
+      count.textContent = `显示 ${visible} / ${rows.length}`;
+    }
+    [q, domain, risk].forEach((control) => control.addEventListener('input', filterTools));
+  </script>
+</body>
+</html>

docs/drive-shortcut-lark-alignment.md

@@ -0,0 +1,82 @@
+# Drive Shortcut 对齐与超越 Lark CLI
+
+## 目标与判定口径
+
+本轮以 Lark CLI `drive` 的 38 个 shortcut 为对照，但不把“同名命令数量”当完成标准。对齐按用户任务判定：
+
+1. `drive +...` 有更稳定的 Agent 主入口时，提供 Shortcut，并发布 Selection、Safety、Result 与 Pagination。
+2. 钉钉已经在其他产品提供更成熟入口时，Skill 明确跨产品路由，不在 Drive 重复实现。
+3. 只有原子能力且 Shortcut 不增加校验、编排或投影价值时，保留 Runtime Schema leaf，不制造同义别名。
+4. 下层接口不存在或无法满足相同语义时，明确记录 gap；不得用空数组、空对象或只返回任务提交结果伪装完成。
+
+成功判定统一为：进程成功 + 统一结果 `ok=true/outcome=success` + 必要业务字段 + 真实数据读回或本地字节校验。服务端显式返回空数组可以是合法业务空结果；空响应、缺少数组、数组类型错误、坏元素、`success=false`、写入缺少终态证据都必须失败。
+
+## Lark 38 项映射
+
+| Lark Drive shortcut | DWS 路由 | 结论与原因 |
+|---|---|---|
+| `+upload` | `drive +upload` | 对齐并增强：工作目录边界、OSS PUT、严格 commit、元数据读回。 |
+| `+create-folder` | `drive +create-folder` | 对齐并增强：要求新 fileId 和名称读回。 |
+| `+create-shortcut` | `drive +create-shortcut` | 对齐并增强：明确 shortcut≠copy，创建后读回。 |
+| `+download` | `drive +download` | 对齐并增强：真实落盘、no-clobber、原子发布、非零字节。 |
+| `+preview` | `drive +cover`（有限） | 不完全对齐：钉钉当前只提供封面/缩略图读取，没有等价的服务端多格式预览转换接口。 |
+| `+cover` | `drive +cover` | 对齐：严格读取封面/缩略图对象。 |
+| `+add-comment` | `doc +comment-create` | 用户任务对齐；评论归在线文档协作域，Drive 不复制一套。 |
+| `+list-comments` | `doc +comment-list` | 用户任务对齐；Doc 已有类型、状态与分页。 |
+| `+batch-query-comments` | `doc +review` / `doc +comment-list` | 超越：可聚合未解决评论与确定性正文上下文；跨文档批量仍由调用方按节点编排。 |
+| `+resolve-comment` | `doc +comment-update`（有限） | 部分对齐：DWS 可更新评论，但当前下层未声明独立 resolve 状态接口。 |
+| `+restore-comment` | 无等价 | gap：钉钉当前下层未暴露恢复已删除评论的等价能力。 |
+| `+add-reply` | `doc +comment-reply` | 对齐。 |
+| `+list-replies` | `doc +comment-list` | 用户任务对齐：评论列表返回回复上下文；无独立 Drive reply 目录。 |
+| `+update-reply` | `doc +comment-update` | 对齐到评论/回复统一更新语义。 |
+| `+delete-reply` | `doc +comment-delete` | 对齐到评论/回复统一删除语义，高风险确认。 |
+| `+react-reply` | `doc +comment-reply`（有限） | 部分对齐：支持表情回复；不声称拥有 Lark 的独立 reaction identity。 |
+| `+export` | `doc +export` | 用户任务对齐并增强：提交、轮询、安全下载一体化。 |
+| `+export-download` | `doc +export` / `doc +export-get` | 超越：常规一体化，`+export-get` 仅作中断恢复。 |
+| `+import` | `doc +import` | 用户任务对齐并增强：转换白名单、上传 fallback、轮询终态。 |
+| `+version-history` | `drive +version-history` | 对齐并增强：严格空结果与分页。 |
+| `+version-get` | `drive +version-get` | 对齐并增强：精确版本号，零命中失败。 |
+| `+version-revert` | `drive +version-revert` | 对齐并增强：版本预检、高风险确认、节点读回。 |
+| `+version-delete` | 无等价 | gap：钉钉当前普通文件版本接口没有删除历史版本能力。 |
+| `+move` | `drive +move` | 对齐；与 copy/shortcut 明确消歧并发布确认。 |
+| `+delete` | `drive +delete` | 对齐；移入回收站、高风险确认、终态证据。 |
+| `+status` | `drive +inspect` | 超越：远端身份、统计、公开状态和封面按需聚合；不伪装成本地同步状态。 |
+| `+push` | `drive +upload`（单文件） | 部分对齐：单文件上传可靠；没有可靠的目录 diff、冲突和远端删除传播语义，因此不提供同名批量 push。 |
+| `+pull` | `drive +download`（单文件） | 部分对齐：单文件下载可靠；目录级增量拉取需稳定路径、hash 与冲突策略，当前接口不完整。 |
+| `+sync` | 无等价 | gap：在缺少稳定远端内容 hash、rename/delete journal 和冲突版本向量时，双向同步会有数据覆盖风险。 |
+| `+task_result` | `doc +export-get` / 导入任务恢复入口 | 用户任务对齐；DWS 按任务所属产品提供类型化恢复入口，不保留 Lark 的下划线泛化命令。 |
+| `+apply-permission` | `drive permission apply` raw leaf | 下层能力存在但未提升为 Shortcut：需要真实申请上下文和权限夹具，无法在通用 E2E 中安全创建。 |
+| `+member-add` | `doc +access-grant` | 用户任务对齐并增强：解析接收人、批量 ledger、首次写入前停止。 |
+| `+member-list` | `drive permission list` / `doc +inspect --include-permissions` | 对齐；常规 Agent 场景优先 Doc 聚合检查。 |
+| `+permission-get-setting` | `drive permission list` + `drive +publish-get` | 部分对齐：协作者与互联网公开是两个独立安全域，没有一个与 Lark setting 完全同构的钉钉接口。 |
+| `+secure-label-list` | 无等价 | gap：当前 DWS/钉钉下层没有可声明的 Drive 安全标签目录接口。 |
+| `+secure-label-update` | 无等价 | gap：没有安全标签写接口，不能用普通权限或公开状态替代。 |
+| `+search` | `drive +search` | 对齐并增强：过滤、严格数组和分页；在线文档搜索路由 `doc +search`。 |
+| `+inspect` | `drive +inspect` | 对齐并增强：必达元数据 + 可选聚合，部分失败不伪装成功。 |
+
+## DWS 超出 Lark Drive 的可挖掘能力
+
+- `+list`：严格目录分页，而不是把缺字段当空目录。
+- `+recent`：最近访问/编辑与创建人筛选。
+- `+stats`：阅读、编辑、评论、点赞、预览和下载统计。
+- `+recycle-list` / `+recycle-restore`：显式回收项身份与恢复后读回。
+- `+star-list` / `+star-add` / `+star-remove`：个人收藏完整闭环。
+- `+publish-get` / `+publish-unset`：互联网公开独立安全域与关闭后读回；`+publish-set` 保留为 unavailable 诊断入口。
+- `+version-download`：历史版本真实字节下载与本地 artifact 校验。
+- `+rename`：写后读回验证。
+
+普通钉盘文件的独立 `copy` 是额外确认出的部分 gap：钉钉当前 `doc/copy_document` 对该对象会生成 `.dlink`，不是字节独立副本。`drive +copy` 因此只接受在线对象；普通文件需要快捷入口时用 `+create-shortcut`，需要独立副本时用 `+download` 后 `+upload`。这不是完整的服务端原子 copy，对大文件也不能宣称完全等价。
+
+互联网公开开启也是账号/对象能力 gap：真实普通文件与在线文档夹具都由服务端返回 `operation.notSupported`。`+publish-get` 与关闭语义可验证，但 `+publish-set` 在找到 eligible 节点完成 set→get→unset 闭环前保持 `unavailable` 且不进入公开 Agent catalog。
+
+## 端到端门禁
+
+每个公开 Drive shortcut 必须至少覆盖：
+
+- Cobra 参数、静态确认、Shortcut Execute、MCP 调度和最终输出；
+- 明确业务空集合、空响应、缺字段、错误类型、坏元素、`success=false`；
+- 写入的 ID/终态证据与读回不一致；
+- 下载的本地路径边界、no-clobber、真实字节数；
+- 真实账号数据：读命令必须命中已知非空夹具或明确验证合法空集合；写命令必须创建隔离资源、读回、必要时下载比对字节并清理。
+
+发布前运行 `make build`、完整 Go 测试、Schema 生成/漂移/策略检查，并保存不含账号业务内容的结构化 E2E 汇总。

docs/flag-help-schema-homology.md

@@ -81,6 +81,7 @@ command/Leaf 不再写 `dws.schema.risk`；SafetySpec 走类型化 Final 载荷
 | `Flags[]`（`FlagSpec` / `LeafFlag`） | 用户可见参数面：名、类型、默认、必填、usage | 注册 cobra flag；装配 toolArgs | `dws.schema.property` / `type` / `required`；`--help` Flags |
 | `Constraints[]` | 跨 flag 关系：`at_least_one` / `exactly_one` / `mutually_exclusive`；`custom` 记录钩子校验 | 通用关系由 `ValidateConstraints` 执行；`custom` 由 `Validate` 执行 | `dws.schema.constraints`；`--help`「参数约束」 |
 | `Safety`（`contract.SafetySpec`） | effect/risk/confirmation/idempotency 四个独立事实 | `confirmation=user_required` 时 `ConfirmSafety`；`--yes` / `--dry-run` 跳过 | 同一个 SafetySpec 原样进入 Contract Final（`HOM-S1`） |
+| `Contract.RetryPolicy` | `idempotency=conditional` 时的调用级重试条件；当前仅支持显式去重 key | 结合实际参数计算 effective idempotency；缺 key 时禁止自动重试 | 与 `conditional` 成组进入 full/compact leaf 和 `ResolveMeta`；禁止按 flag 名推断 |
 | `ConstParams` | 固定载荷（不上 flag 表） | 并入 toolArgs；不满足 Required | **不**投影为用户 parameter |
 | `Use` / `Short` / `Long` / `Example` | 命令身份文案与示例 | cobra 自身 | help；identity 以 collector 收集的 `ContractFinal.Identity` 声明为准（reviewed registry 已退役） |
 
@@ -170,6 +171,7 @@ NewLeafCommand(LeafSpec{
 | Constraints | **声明** | `Constraints` |
 | Positionals | **声明** 或显式 annotate | 目标 `Args`；禁止推断 |
 | Safety.`effect/risk/confirmation/idempotency` | **声明**完整 `Safety`，或迁移期 `runtime_gate` / reviewed Safety | 四字段独立；不得互相推导 |
+| RetryPolicy | **声明**（仅 `idempotency=conditional`） | `ContractDecl.RetryPolicy`；key 必须引用显式映射到 RPC property 的 string `ParamDecl`，并要求相同 payload |
 | DryRun | 评审源 | dry-run capabilities registry |
 | Interface | 评审源 | MCP + 内存 inject 的 Agent metadata |
 | Selection | 声明（ContractFinal / ProductDecl） | `ContractDecl.Selection` / `ProductDecl` |

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

docs/releasing.md

@@ -17,7 +17,8 @@
 
 1. 在上述 `Release` 页面选择 `Run workflow`，分支必须是默认分支 `main`。
 2. `release_operation=plan`，选择 `release_channel=beta|stable`；仅在开始新 beta 线时选择 `release_bump=patch|minor|major`。
-3. workflow summary 会给出唯一的下一版本。把对应的精确 `CHANGELOG.md` 章节通过 PR 合入 `main`。
+3. workflow summary 会给出唯一的下一版本。运行 `prepare-changelog.sh` 将已合入的
+   release fragments 汇总成对应的精确 `CHANGELOG.md` 章节，并通过唯一的 release-seal PR 合入 `main`。
 4. 再次运行，改为 `release_operation=publish`。beta 会直接进入自动化发布；stable 会在封 tag 前等待管理员签收。
 
 `plan` 是纯只读操作，不创建 tag、预留版本号或生成包。CHANGELOG 合入期间若另一个发布先占用了该版本，`publish` 会重新分配并因 CHANGELOG 章节不匹配而拒绝，需要重新 plan。`publish` 会先再次确认 dispatch SHA 仍是当前 `main`、Code Admission 和平台治理均通过，再由唯一的 write job 使用 GitHub API 原子创建 annotated tag；同一次 run 随即进入既有的跨平台构建、GitHub/npm、可选 OSS/Gitee 发布和 Homebrew 直交付 DAG。内置 `GITHUB_TOKEN` 创建的 tag 不依赖第二条 workflow 被再次触发。
@@ -94,7 +95,8 @@ main 上的候选代码 + beta CHANGELOG
 dws-release v1.2.3-beta.1
 ```
 
-如果 CHANGELOG 尚不存在，该命令只生成模板并停止。补全内容、删除所有 `TODO`，提交后通过 PR 合入 `main`；然后重新运行完全相同的命令，它会执行完整预检：
+如果 CHANGELOG 尚不存在，该命令会从 `.changes/*.md` 生成 beta 章节并归档已消费的
+fragments，然后停止。审阅生成内容并通过唯一的 release-seal PR 合入 `main`；然后重新运行完全相同的命令，它会执行完整预检：
 
 ```bash
 dws-release v1.2.3-beta.1
@@ -132,6 +134,15 @@ dws-release v1.2.3 --from-beta v1.2.3-beta.1
 
 正式版使用 `## [1.2.3] - YYYY-MM-DD`。该章节会直接成为 GitHub Release Notes。
 
+### Release fragments
+
+普通 PR 不修改 `CHANGELOG.md` 的 `Unreleased` 区域。需要面向用户发布说明的改动在
+`.changes/<unique-name>.md` 中增加一个独立 fragment；格式和允许的分类见
+[`.changes/README.md`](../.changes/README.md)。预发封板时
+`scripts/release/prepare-changelog.sh prerelease <version>` 会稳定排序并汇总所有未归档
+fragment，写入唯一版本章节后移动到 `.changes/released/<version>/`。因此并发 PR 不会争用
+`CHANGELOG.md`；唯一的 release-seal PR 同时提交生成的章节与归档移动，供审计复核。
+
 ## CI/CD 保证
 
 - 只接受 `vX.Y.Z-beta.N` 和 `vX.Y.Z`，且新版本必须高于上一正式版。这里的“上一正式版”必须同时具备公开非草稿 GitHub Release 和同 tag/commit 的成功 Release workflow；只有 tag、没有交付成功的孤儿版本会阻断后续发布，要求走机器核验恢复补齐。云端 tag 会固定 `Release-Run`、requester、commit 和版本分配指纹，交付验证按该精确 run/attempt 及完整 job graph 取证，不接受任意 `workflow_dispatch`。历史版本若曾通过专用 recovery workflow 完成交付，只能使用仓库内 `delivered-stable-recoveries.json` 中精确到 tag、commit、run、workflow SHA 与 attempt 的 reviewed 证据。

docs/rfc-command-framework-convergence.md

@@ -357,7 +357,7 @@ Definition（仅声明；不可编译）
 | **Constraints** | `require_one_of`, `mutually_exclusive`, `require_together` | **声明** | `Constraints` → `AnnotateConstraints` | **是** |
 | **Positionals** | 位置参数名/必填/说明 | **声明** 或显式 annotate | 目标 `Args`/`PositionalSpec`；今日少量 cobra Args + 注解 | 受管命令应声明，禁止推断 |
 | **Safety** | `effect`, `risk`, `confirmation`, `idempotency` | **声明**（完整 `contract.SafetySpec`）**或标注**（`runtime_gate`） | `Safety` / `AnnotateRuntimeGate`（metadata 壳 `tools: {}`，不再承载 reviewed Safety） | 四字段独立；confirmation 单独驱动运行时 |
-| | `idempotency` | 评审源（或未来 Contract） | reviewed metadata | 今日非框架声明；不得推断 |
+| | `retry_policy` | **声明**（仅 `idempotency=conditional`） | `ContractDecl.RetryPolicy` + 显式 `ParamDecl.Property` + MCP `interface_ref` | 从实际调用参数计算 effective idempotency；缺 key 时失败闭合，禁止按参数名推断 |
 | | `effect_source` / provenance | 组装派生物 | resolver 写入 `FieldProvenance` | 派生，不手写 |
 | **DryRun** | `preview_kind`, `remote_reads` | 评审源 | `schema_dry_run_capabilities`（正能力声明） | 否；无条目 ≠ 推断「不支持」之外的假能力 |
 | **Interface** | `interface_mode`, `interface_ref`, `availability`, `reason` | 评审源 | MCP meta + agent metadata 解析 | 否；与 CLI Identity 分离 |
@@ -1167,7 +1167,7 @@ cmd.RunE = func(cmd *cobra.Command, args []string) error {
 | 非 Shortcut 受管定义的 Cobra 命令 Hidden | 可执行 Contract | 挂载的命令可见性与声明匹配 |
 | Shortcut 列表成员资格与语义 disposition | 经评审的 Shortcut 可见性解析器 | public/all 列表成员资格与经评审决策匹配 |
 | Runtime Schema / Agent 暴露 | identity collector 收集结果加精确排除 | 每个暴露叶子解析到活 Contract；排除显式且不重叠 |
-| Safety 与运行时确认 | 可执行 Contract 的完整 `contract.SafetySpec`，或迁移期显式 annotate（如 `runtime_gate`）；见 §5.0 | `confirmation` 单独驱动运行时门，`effect` / `risk` / `idempotency` 原样发布，禁止跨字段机械推导；任一 Safety 字段非空时四字段必须齐全，否则构造期 panic；`ConfirmFirst` 只在 `confirmation=user_required` 时合法 |
+| Safety、条件幂等与运行时确认 | 可执行 Contract 的完整 `contract.SafetySpec`，或迁移期显式 annotate（如 `runtime_gate`）；条件幂等另由 `ContractDecl.RetryPolicy` 声明；见 §5.0 | `confirmation` 单独驱动运行时门，`effect` / `risk` / `idempotency` 原样发布，禁止跨字段机械推导；任一 Safety 字段非空时四字段必须齐全，否则构造期 panic；`conditional` 必须引用显式映射到 RPC property 的 string 参数，并在缺 key 时禁用重试；`ConfirmFirst` 只在 `confirmation=user_required` 时合法 |
 | 后端 product/tool/载荷绑定 | mcpbind + 后端元数据 | 每个绑定引用真实的 flag/属性 |
 | Agent 选择文案（`use_when`、`avoid_when`、摘要） | 声明：`ContractDecl.Selection` / `ProductDecl`（交付 provenance `contract_final`）；`schema_hints/` 已退役，禁止回潮 | 身份解析到活契约；选择文案不得创建 CLI 表面 |
 

docs/rfc-skill-installation-and-upgrade.md

@@ -142,6 +142,9 @@ Agent 仍只需以 `SKILL.md` 发现和加载 Skill；统一元数据位于 Agen
 
 升级器对每个 Agent 目标执行：
 
+- 先探测具体 Agent home；只在没有任何具体 Agent 时使用 `~/.agents/skills` 通用 fallback；
+- 具体 Agent 安装成功后，将 `~/.agents/skills` 中旧的 DWS 受管副本可恢复地迁入备份，避免 Codex 等同时扫描两个根目录时重复发现同名 Skill；
+
 1. 只读计算对面布局、过期受管 Skill 和同名官方 Skill；
 2. 在目标文件系统的 staging 中复制完整新集合；
 3. staging 全部成功后，才将旧集合移入备份目录；

docs/shortcut-public-catalog.json

@@ -1,6 +1,6 @@
 {
-  "generated_at": "2026-08-10T17:25:46.245552",
-  "count": 378,
+  "generated_at": "2026-08-12T00:10:44.511794",
+  "count": 399,
   "results": [
     {
       "suite": "semantic",
@@ -2650,8 +2650,8 @@
       "command": "+history-list",
       "risk": "read",
       "status": "reviewed_available",
-      "disposition": "semantic_adapter",
-      "semantic_delta": "统一历史版本分页参数并返回可用于回滚的版本列表。",
+      "disposition": "alias_internal",
+      "semantic_delta": "保留既有历史列表路径及稳定 Schema identity；新的 Agent 场景统一使用 +version-list。",
       "availability": "available"
     },
     {
@@ -2660,8 +2660,8 @@
       "command": "+history-revert",
       "risk": "high-risk-write",
       "status": "reviewed_available",
-      "disposition": "primary_smart",
-      "semantic_delta": "先验证目标版本存在，再执行回滚并读回当前文档状态。",
+      "disposition": "alias_internal",
+      "semantic_delta": "保留既有历史回滚路径及稳定 Schema identity；新的 Agent 场景统一使用 +version-revert。",
       "availability": "available"
     },
     {
@@ -2670,8 +2670,8 @@
       "command": "+history-save",
       "risk": "write",
       "status": "reviewed_available",
-      "disposition": "semantic_adapter",
-      "semantic_delta": "以文档历史语义命名手动版本快照，避免暴露底层 RPC 命名。",
+      "disposition": "alias_internal",
+      "semantic_delta": "保留既有历史快照路径及稳定 Schema identity；新的 Agent 场景统一使用 +version-save。",
       "availability": "available"
     },
     {
@@ -2841,7 +2841,7 @@
       "risk": "read",
       "status": "reviewed_available",
       "disposition": "semantic_adapter",
-      "semantic_delta": "按名称检索模板并返回可继续创建的 templateId。",
+      "semantic_delta": "按名称或关键词检索模板并返回可消歧候选和 templateId。",
       "availability": "available"
     },
     {
@@ -2860,8 +2860,8 @@
       "command": "+version-list",
       "risk": "read",
       "status": "reviewed_available",
-      "disposition": "alias_internal",
-      "semantic_delta": "保留历史版本列表命令及其稳定 Schema identity；新场景优先使用 +history-list。",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "版本浏览的 Agent 主入口；统一分页参数并返回可用于回滚的版本号。",
       "availability": "available"
     },
     {
@@ -2870,8 +2870,8 @@
       "command": "+version-revert",
       "risk": "high-risk-write",
       "status": "reviewed_available",
-      "disposition": "alias_internal",
-      "semantic_delta": "保留历史版本回滚命令及其稳定 Schema identity；新场景优先使用 +history-revert。",
+      "disposition": "primary_smart",
+      "semantic_delta": "版本回滚的 Agent 主入口；先验证目标版本存在，再回滚并读回当前状态。",
       "availability": "available"
     },
     {
@@ -2880,58 +2880,289 @@
       "command": "+version-save",
       "risk": "write",
       "status": "reviewed_available",
-      "disposition": "alias_internal",
-      "semantic_delta": "保留历史版本快照命令及其稳定 Schema identity；新场景优先使用 +history-save。",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "版本快照的 Agent 主入口；只保存当前快照，不隐式修改正文。",
       "availability": "available"
     },
     {
-      "suite": "write",
+      "suite": "semantic",
       "service": "drive",
       "command": "+copy",
       "risk": "write",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "复制前预检在线对象类型；普通钉盘文件因下层只会生成 .dlink 而显式拒绝，避免把快捷方式伪装成独立副本。",
+      "availability": "available"
     },
     {
-      "suite": "read",
+      "suite": "semantic",
+      "service": "drive",
+      "command": "+cover",
+      "risk": "read",
+      "status": "reviewed_available",
+      "disposition": "schema_leaf",
+      "semantic_delta": "读取节点封面或缩略图地址；明确不声称服务端多格式预览转换。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "drive",
+      "command": "+create-folder",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "创建普通钉盘文件夹后要求 fileId，并读回名称验证。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "drive",
+      "command": "+create-shortcut",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "明确 shortcut 与 copy 语义差异，创建后读取新节点验证。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "drive",
+      "command": "+delete",
+      "risk": "high-risk-write",
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "将已确认节点移入回收站，要求高风险确认和 success=true 终态证据。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "drive",
+      "command": "+download",
+      "risk": "read",
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "不再只返回临时链接；使用受控相对路径、no-clobber、原子发布并验证非零本地字节。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
       "service": "drive",
       "command": "+find-file",
       "risk": "read",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "alias_internal",
+      "semantic_delta": "保留历史文件定位入口；新的 Agent 文件搜索统一使用 +search。",
+      "availability": "available"
     },
     {
-      "suite": "read",
+      "suite": "semantic",
       "service": "drive",
       "command": "+info",
       "risk": "read",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "alias_internal",
+      "semantic_delta": "保留历史元数据入口；新的 Agent 场景统一使用可扩展的 +inspect。",
+      "availability": "available"
     },
     {
-      "suite": "write",
+      "suite": "semantic",
+      "service": "drive",
+      "command": "+inspect",
+      "risk": "read",
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "以文件元数据为必达结果，按需聚合统计、公开状态和封面；可选读取失败显式报告 partial_success。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "drive",
+      "command": "+list",
+      "risk": "read",
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "严格区分显式空目录与缺失/畸形响应，稳定投影节点并完整保留分页游标。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
       "service": "drive",
       "command": "+move",
       "risk": "write",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "移动后原位置不保留，统一 folder/workspace 目标语义并发布静态确认。",
+      "availability": "available"
     },
     {
-      "suite": "read",
+      "suite": "semantic",
+      "service": "drive",
+      "command": "+publish-get",
+      "risk": "read",
+      "status": "reviewed_available",
+      "disposition": "schema_leaf",
+      "semantic_delta": "只读查询互联网公开状态和权限，不沿用原子命令错误的写风险标签。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "drive",
+      "command": "+publish-unset",
+      "risk": "high-risk-write",
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "高风险确认后关闭互联网公开，并读回状态验证外链已失效。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
       "service": "drive",
       "command": "+recent",
       "risk": "read",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "严格读取最近访问/编辑列表并保留 nextCursor/hasMore，防止嵌套响应被投影为空。",
+      "availability": "available"
     },
     {
-      "suite": "read",
+      "suite": "semantic",
+      "service": "drive",
+      "command": "+recycle-list",
+      "risk": "read",
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "严格分页列出回收项并稳定投影 recycleItemId，显式空数组才是空回收站。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "drive",
+      "command": "+recycle-restore",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "只要求列表可获得的 recycleItemId；恢复响应必须给出节点 ID，随后读回验证。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "drive",
+      "command": "+rename",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "重命名后读取真实节点元数据验证最终名称。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
       "service": "drive",
       "command": "+search",
       "risk": "read",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "统一关键词、文件类型、扩展名、创建者、时间和分页过滤，并拒绝缺失结果数组。",
+      "availability": "available"
     },
     {
-      "suite": "read",
+      "suite": "semantic",
       "service": "drive",
       "command": "+search-docs",
       "risk": "read",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "alias_internal",
+      "semantic_delta": "保留历史跨域文档搜索入口；新的在线文档搜索统一使用 doc +search。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "drive",
+      "command": "+star-add",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "schema_leaf",
+      "semantic_delta": "以幂等用户偏好语义收藏指定节点。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "drive",
+      "command": "+star-list",
+      "risk": "read",
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "严格分页列出当前用户收藏并保留游标。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "drive",
+      "command": "+star-remove",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "schema_leaf",
+      "semantic_delta": "以幂等用户偏好语义取消收藏指定节点。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "drive",
+      "command": "+stats",
+      "risk": "read",
+      "status": "reviewed_available",
+      "disposition": "schema_leaf",
+      "semantic_delta": "读取节点访问、编辑、评论、点赞、预览和下载统计的一对一入口。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "drive",
+      "command": "+upload",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "组合工作目录边界校验、上传凭证、OSS PUT、严格提交响应和远端元数据读回。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "drive",
+      "command": "+version-download",
+      "risk": "read",
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "预检版本存在后安全下载历史字节，受控相对路径原子发布且要求非零产物。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "drive",
+      "command": "+version-get",
+      "risk": "read",
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "按正整数版本号精确匹配元数据；零命中显式失败。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "drive",
+      "command": "+version-history",
+      "risk": "read",
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "严格分页列出普通文件版本，区分合法空历史与响应契约错误。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "drive",
+      "command": "+version-revert",
+      "risk": "high-risk-write",
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "先验证目标版本存在，再经高风险确认回滚并读取当前节点状态。",
+      "availability": "available"
     },
     {
       "suite": "read",
@@ -3180,7 +3411,7 @@
       "risk": "read",
       "status": "reviewed_available",
       "disposition": "primary_smart",
-      "semantic_delta": "Validated itemList parsing, deterministic title filtering, bounded cursor pagination, de-duplication and completeness ledger; +minutes-search is a compatibility alias.",
+      "semantic_delta": "Validated itemList parsing, deterministic title filtering, bounded cursor pagination, de-duplication and completeness ledger; replaces the deprecated +minutes-search discovery route.",
       "availability": "available"
     },
     {
@@ -3260,7 +3491,7 @@
       "risk": "write",
       "status": "reviewed_available",
       "disposition": "primary_smart",
-      "semantic_delta": "Owns local file validation, create-PUT-complete polling, cancellation compensation and final task read-back verification.",
+      "semantic_delta": "Owns local file validation, create-PUT-complete polling, pre-complete transfer cancellation compensation, unknown-completion recovery and final task read-back verification.",
       "availability": "available"
     },
     {

go.mod

@@ -14,7 +14,7 @@ require (
 	github.com/itchyny/gojq v0.12.18
 	github.com/mattn/go-isatty v0.0.20
 	github.com/muesli/termenv v0.16.0
-	github.com/open-dingtalk/dingtalk-stream-sdk-go v0.9.2-0.20260705041131-325e7c1049ad
+	github.com/open-dingtalk/dingtalk-stream-sdk-go v0.9.2-beta.1
 	github.com/spf13/cobra v1.10.2
 	github.com/zalando/go-keyring v0.2.8
 	golang.org/x/crypto v0.49.0

go.sum

@@ -88,8 +88,8 @@ github.com/muesli/cancelreader v0.2.2 h1:3I4Kt4BQjOR54NavqnDogx/MIoWBFa0StPA8ELU
 github.com/muesli/cancelreader v0.2.2/go.mod h1:3XuTXfFS2VjM+HTLZY9Ak0l6eUKfijIfMUZ4EgX0QYo=
 github.com/muesli/termenv v0.16.0 h1:S5AlUN9dENB57rsbnkPyfdGuWIlkmzJjbFf0Tf5FWUc=
 github.com/muesli/termenv v0.16.0/go.mod h1:ZRfOIKPFDYQoDFF4Olj7/QJbW60Ol/kL1pU3VfY/Cnk=
-github.com/open-dingtalk/dingtalk-stream-sdk-go v0.9.2-0.20260705041131-325e7c1049ad h1:Bb4I+suYd+ehQ8e22aimLLze+5XTN3+WTc/x2LafmH8=
-github.com/open-dingtalk/dingtalk-stream-sdk-go v0.9.2-0.20260705041131-325e7c1049ad/go.mod h1:ln3IqPYYocZbYvl9TAOrG/cxGR9xcn4pnZRLdCTEGEU=
+github.com/open-dingtalk/dingtalk-stream-sdk-go v0.9.2-beta.1 h1:5WwR5TV6A12taXMH7SggT8yCMMJMF9jWE7Wj+4AuHck=
+github.com/open-dingtalk/dingtalk-stream-sdk-go v0.9.2-beta.1/go.mod h1:ln3IqPYYocZbYvl9TAOrG/cxGR9xcn4pnZRLdCTEGEU=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
 github.com/rivo/uniseg v0.4.7 h1:WUdvkW8uEhrYfLC4ZzdpI2ztxP1I582+49Oc5Mq64VQ=

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

@@ -0,0 +1,308 @@
+// 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"
+	"errors"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"sync"
+	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/audit"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract"
+	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/executor"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/transport"
+)
+
+func retryGateTestRunner() *runtimeRunner {
+	client := transport.NewClient(nil)
+	return &runtimeRunner{
+		transport:   client,
+		globalFlags: &GlobalFlags{Token: "test-token"},
+		auditSink:   audit.NopSink{},
+	}
+}
+
+func TestCrossPlatformCoverageRuntimeRetryGateControlsTransportAndAPIHint(t *testing.T) {
+	testseam.Swap(t, &runnerPreflightDocDownload, func(*runtimeRunner, context.Context, *transport.Client, string, executor.Invocation) error {
+		return nil
+	})
+	testseam.Swap(t, &runnerCaptureRuntimeFailure, func(executor.Invocation, error, error) {})
+
+	tests := []struct {
+		name          string
+		decision      *contract.RetryDecision
+		wantRetries   int
+		wantRetryable bool
+	}{
+		{name: "missing contract fails closed", wantRetries: 0, wantRetryable: false},
+		{
+			name: "conditional contract without key fails closed",
+			decision: &contract.RetryDecision{
+				EffectiveIdempotency: "non_idempotent",
+				SafeToRetry:          false,
+				Reason:               "deduplication_key_missing",
+			},
+			wantRetries:   0,
+			wantRetryable: false,
+		},
+		{
+			name: "resolved idempotent contract preserves retry",
+			decision: &contract.RetryDecision{
+				EffectiveIdempotency: "idempotent",
+				SafeToRetry:          true,
+				Reason:               "deduplication_key_present",
+			},
+			wantRetries:   1,
+			wantRetryable: true,
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			gotRetries := -1
+			testseam.Swap(t, &runnerCallTool, func(client *transport.Client, _ context.Context, _, _ string, _ map[string]any) (transport.ToolCallResult, error) {
+				gotRetries = client.MaxRetries
+				return transport.ToolCallResult{}, apperrors.NewAPI(
+					"server unavailable",
+					apperrors.WithReason("http_503"),
+					apperrors.WithRetryable(true),
+					apperrors.WithRetryAfterSeconds(3),
+				)
+			})
+
+			runner := retryGateTestRunner()
+			_, err := runner.executeInvocation(context.Background(), "https://example.test", executor.Invocation{
+				CanonicalProduct: "chat",
+				Tool:             "send_message",
+				Params:           map[string]any{"uuid": "stable-key"},
+				Retry:            tt.decision,
+			})
+			if gotRetries != tt.wantRetries {
+				t.Fatalf("transport MaxRetries = %d, want %d", gotRetries, tt.wantRetries)
+			}
+			var typed *apperrors.Error
+			if !errors.As(err, &typed) {
+				t.Fatalf("error = %T %v, want typed API error", err, err)
+			}
+			if !typed.RetryableSet || typed.Retryable != tt.wantRetryable {
+				t.Fatalf("retryable = (%v, %v), want (true, %v)", typed.RetryableSet, typed.Retryable, tt.wantRetryable)
+			}
+			if tt.wantRetryable {
+				if typed.RetryAfterSeconds == nil || *typed.RetryAfterSeconds != 3 {
+					t.Fatalf("safe retry_after_seconds = %v, want 3", typed.RetryAfterSeconds)
+				}
+			} else if typed.RetryAfterSeconds != nil || typed.NextRetryAt != nil {
+				t.Fatalf("unsafe retry kept backoff hints: after=%v at=%v", typed.RetryAfterSeconds, typed.NextRetryAt)
+			}
+			if runner.transport.MaxRetries != 1 {
+				t.Fatalf("shared transport MaxRetries = %d, want unchanged 1", runner.transport.MaxRetries)
+			}
+		})
+	}
+}
+
+func TestCrossPlatformCoverageRuntimeRetryGateDoesNotClampAuthErrors(t *testing.T) {
+	testseam.Swap(t, &runnerPreflightDocDownload, func(*runtimeRunner, context.Context, *transport.Client, string, executor.Invocation) error {
+		return nil
+	})
+	testseam.Swap(t, &runnerCaptureRuntimeFailure, func(executor.Invocation, error, error) {})
+	authErr := apperrors.NewAuth("expired", apperrors.WithRetryable(true))
+	testseam.Swap(t, &runnerCallTool, func(*transport.Client, context.Context, string, string, map[string]any) (transport.ToolCallResult, error) {
+		return transport.ToolCallResult{}, authErr
+	})
+
+	_, err := retryGateTestRunner().executeInvocation(context.Background(), "https://example.test", executor.Invocation{
+		CanonicalProduct: "chat",
+		Tool:             "send_message",
+		Params:           map[string]any{},
+	})
+	var typed *apperrors.Error
+	if !errors.As(err, &typed) {
+		t.Fatalf("error = %T %v, want typed auth error", err, err)
+	}
+	if typed.Category != apperrors.CategoryAuth || !typed.RetryableSet || !typed.Retryable {
+		t.Fatalf("auth retryability was changed: %#v", typed)
+	}
+}
+
+func TestCrossPlatformCoverageRuntimeRetryDecisionPrecedesDryRun(t *testing.T) {
+	resolverCalls := 0
+	runner := retryGateTestRunner()
+	runner.globalFlags.DryRun = true
+	runner.resolveToolCallRetry = func(productID, rpcName string, args map[string]any) contract.RetryDecision {
+		resolverCalls++
+		if productID != "chat" || rpcName != "send_message" || args["uuid"] != "stable-key" {
+			t.Fatalf("resolver input = %q/%q %#v", productID, rpcName, args)
+		}
+		return contract.RetryDecision{
+			EffectiveIdempotency: "idempotent",
+			SafeToRetry:          true,
+			Reason:               "deduplication_key_present",
+		}
+	}
+
+	result, err := runner.Run(context.Background(), executor.NewHelperInvocation(
+		"chat send",
+		"chat",
+		"send_message",
+		map[string]any{"uuid": "stable-key"},
+	))
+	if err != nil {
+		t.Fatalf("Run() error = %v", err)
+	}
+	if resolverCalls != 1 || result.Invocation.Retry == nil || !result.Invocation.Retry.SafeToRetry {
+		t.Fatalf("dry-run retry decision = %#v, resolver calls = %d", result.Invocation.Retry, resolverCalls)
+	}
+	if got, ok := result.Response["retry"].(*contract.RetryDecision); !ok || !got.SafeToRetry || got.EffectiveIdempotency != "idempotent" {
+		t.Fatalf("dry-run response retry = %#v", result.Response["retry"])
+	}
+
+	explicit := contract.RetryDecision{EffectiveIdempotency: "unknown", SafeToRetry: false, Reason: "explicit"}
+	invocation := executor.NewHelperInvocation("chat send", "chat", "send_message", nil)
+	invocation.Retry = &explicit
+	result, err = runner.Run(context.Background(), invocation)
+	if err != nil {
+		t.Fatalf("Run(explicit) error = %v", err)
+	}
+	if resolverCalls != 1 || result.Invocation.Retry == nil || result.Invocation.Retry.Reason != "explicit" {
+		t.Fatalf("explicit retry decision was overwritten: %#v, resolver calls = %d", result.Invocation.Retry, resolverCalls)
+	}
+}
+
+func TestCrossPlatformCoverageExecuteInvocationDryRunIncludesRetryDecision(t *testing.T) {
+	decision := contract.RetryDecision{
+		EffectiveIdempotency: "idempotent",
+		SafeToRetry:          true,
+		Reason:               "deduplication_key_present",
+	}
+	result, err := retryGateTestRunner().executeInvocation(context.Background(), "https://example.test", executor.Invocation{
+		CanonicalProduct: "chat",
+		Tool:             "send_message",
+		DryRun:           true,
+		Retry:            &decision,
+	})
+	if err != nil {
+		t.Fatalf("executeInvocation() error = %v", err)
+	}
+	got, ok := result.Response["retry"].(*contract.RetryDecision)
+	if !ok || got != &decision || !got.SafeToRetry {
+		t.Fatalf("dry-run response retry = %#v, want original decision", result.Response["retry"])
+	}
+}
+
+func TestCrossPlatformCoverageToolCallerDryRunIncludesRetryDecision(t *testing.T) {
+	runner := retryGateTestRunner()
+	runner.resolveToolCallRetry = func(_ string, _ string, args map[string]any) contract.RetryDecision {
+		if key, _ := args["uuid"].(string); key == "" {
+			return contract.RetryDecision{
+				EffectiveIdempotency: "non_idempotent",
+				Reason:               "deduplication_key_missing",
+			}
+		}
+		return contract.RetryDecision{
+			EffectiveIdempotency: "idempotent",
+			SafeToRetry:          true,
+			Reason:               "deduplication_key_present",
+		}
+	}
+	var captured executor.Invocation
+	testseam.Swap(t, &toolCallerDryRun, func(ctx context.Context, invocation executor.Invocation) (executor.Result, error) {
+		captured = invocation
+		return (executor.EchoRunner{}).Run(ctx, invocation)
+	})
+
+	caller := newToolCallerAdapter(runner, &GlobalFlags{DryRun: true})
+	result, err := caller.CallTool(context.Background(), "chat", "send_message", map[string]any{"uuid": "stable-key"})
+	if err != nil {
+		t.Fatalf("CallTool() error = %v", err)
+	}
+	if captured.Retry == nil || !captured.Retry.SafeToRetry || captured.Retry.EffectiveIdempotency != "idempotent" {
+		t.Fatalf("captured retry decision = %#v", captured.Retry)
+	}
+	if len(result.Content) != 1 || !bytes.Contains([]byte(result.Content[0].Text), []byte(`"effective_idempotency":"idempotent"`)) {
+		t.Fatalf("ToolResult does not expose effective idempotency: %#v", result)
+	}
+
+	result, err = caller.CallTool(context.Background(), "chat", "send_message", map[string]any{"content": "hello"})
+	if err != nil {
+		t.Fatalf("CallTool(without uuid) error = %v", err)
+	}
+	if captured.Retry == nil || captured.Retry.SafeToRetry || captured.Retry.EffectiveIdempotency != "non_idempotent" {
+		t.Fatalf("missing-key retry decision = %#v", captured.Retry)
+	}
+	if len(result.Content) != 1 || !bytes.Contains([]byte(result.Content[0].Text), []byte(`"effective_idempotency":"non_idempotent"`)) {
+		t.Fatalf("ToolResult does not expose missing-key idempotency: %#v", result)
+	}
+}
+
+func TestCrossPlatformCoverageRuntimeSafeRetryReusesRequestBody(t *testing.T) {
+	var mu sync.Mutex
+	var bodies [][]byte
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		body, err := io.ReadAll(r.Body)
+		if err != nil {
+			t.Errorf("ReadAll(request) error = %v", err)
+			w.WriteHeader(http.StatusInternalServerError)
+			return
+		}
+		mu.Lock()
+		bodies = append(bodies, append([]byte(nil), body...))
+		attempt := len(bodies)
+		mu.Unlock()
+		w.Header().Set("Content-Type", "application/json")
+		if attempt == 1 {
+			w.WriteHeader(http.StatusServiceUnavailable)
+			return
+		}
+		_, _ = io.WriteString(w, `{"jsonrpc":"2.0","id":3,"result":{"content":{"messageId":"m1"}}}`)
+	}))
+	defer server.Close()
+
+	runner := retryGateTestRunner()
+	runner.transport = transport.NewClient(server.Client())
+	runner.transport.RetryDelay = 0
+	runner.transport.RetryMaxDelay = 0
+	runner.auditSink = audit.NopSink{}
+	decision := contract.RetryDecision{
+		EffectiveIdempotency: "idempotent",
+		SafeToRetry:          true,
+		Reason:               "deduplication_key_present",
+	}
+	result, err := runner.executeInvocation(context.Background(), server.URL, executor.Invocation{
+		CanonicalProduct: "chat",
+		Tool:             "send_message",
+		Params:           map[string]any{"uuid": "stable-key", "content": "hello"},
+		Retry:            &decision,
+	})
+	if err != nil {
+		t.Fatalf("executeInvocation() error = %v", err)
+	}
+	if !result.Invocation.Implemented {
+		t.Fatal("successful retry was not marked implemented")
+	}
+	mu.Lock()
+	defer mu.Unlock()
+	if len(bodies) != 2 {
+		t.Fatalf("request attempts = %d, want 2", len(bodies))
+	}
+	if !bytes.Equal(bodies[0], bodies[1]) {
+		t.Fatalf("retry body changed:\nfirst:  %s\nsecond: %s", bodies[0], bodies[1])
+	}
+}

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,34 @@ 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 查看迁移计划并确认")
+				}
+			}
 
 			authpkg.SetRuntimeProfile(flags.Profile)
 			// Apply OAuth credential overrides from CLI flags (highest priority).
@@ -772,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
@@ -786,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)
@@ -1750,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 {
@@ -1771,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/runner.go

@@ -30,6 +30,8 @@ import (
 
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/audit"
 	authpkg "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/auth"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/cli"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract"
 	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/executor"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/logging"
@@ -137,31 +139,34 @@ 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,
-		globalFlags:        flags,
-		scanner:            newRuntimeContentScanner(),
-		enforceContentScan: runtimeFlagEnabled(os.Getenv(runtimeContentScanEnforceEnv), false),
-		includeScanReport:  runtimeFlagEnabled(os.Getenv(runtimeContentScanReportOutputEnv), false),
+		transport:            transportClient,
+		globalFlags:          flags,
+		resolveToolCallRetry: cli.ResolveToolCallRetry,
+		scanner:              newRuntimeContentScanner(),
+		enforceContentScan:   runtimeFlagEnabled(os.Getenv(runtimeContentScanEnforceEnv), false),
+		includeScanReport:    runtimeFlagEnabled(os.Getenv(runtimeContentScanReportOutputEnv), false),
 	}
 }
 
 type runtimeRunner struct {
-	transport          *transport.Client
-	globalFlags        *GlobalFlags
-	fallback           executor.Runner
-	scanner            safety.Scanner
-	enforceContentScan bool
-	includeScanReport  bool
-	auditSink          audit.Sink
+	transport            *transport.Client
+	globalFlags          *GlobalFlags
+	fallback             executor.Runner
+	scanner              safety.Scanner
+	enforceContentScan   bool
+	includeScanReport    bool
+	auditSink            audit.Sink
+	agentMetadata        *agentMetadataSnapshot
+	resolveToolCallRetry func(productID, rpcName string, args map[string]any) contract.RetryDecision
 }
 
 var (
 	runnerResolveMultiProfileSelections = resolveMultiProfileSelections
 	runnerResolveProfile                = authpkg.ResolveProfile
 	runnerGetCachedRuntimeToken         = getCachedRuntimeToken
+	runnerResolveAuthToken              = (*runtimeRunner).resolveAuthToken
 	runnerPreflightDocDownload          = (*runtimeRunner).preflightDocDownload
 	runnerCallTool                      = (*transport.Client).CallTool
 	runnerStdioEnsureInitialized        = (*transport.StdioClient).EnsureInitialized
@@ -173,6 +178,7 @@ var (
 )
 
 func (r *runtimeRunner) Run(ctx context.Context, invocation executor.Invocation) (executor.Result, error) {
+	r.resolveInvocationRetry(&invocation)
 	// Global dry-run is an execution barrier, not merely a transport option.
 	// Return a deterministic local preview before profile resolution, catalog
 	// discovery, Keychain/token prefetch, auth, stateful preflight or transport.
@@ -215,6 +221,14 @@ func (r *runtimeRunner) Run(ctx context.Context, invocation executor.Invocation)
 	return r.runSingle(ctx, invocation, true)
 }
 
+func (r *runtimeRunner) resolveInvocationRetry(invocation *executor.Invocation) {
+	if invocation == nil || invocation.Retry != nil || r == nil || r.resolveToolCallRetry == nil {
+		return
+	}
+	decision := r.resolveToolCallRetry(invocation.CanonicalProduct, invocation.Tool, invocation.Params)
+	invocation.Retry = &decision
+}
+
 // RunReadOnly executes one already-classified read lookup for a semantic
 // Shortcut that is building a dry-run plan. It clones the runtime flags and
 // clears DryRun only on that clone: the process-wide caller and every ordinary
@@ -237,7 +251,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 {
@@ -500,6 +513,7 @@ func endpointNotResolvedError(productID, toolName, detail string) error {
 func (r *runtimeRunner) executeInvocation(ctx context.Context, endpoint string, invocation executor.Invocation) (result executor.Result, retErr error) {
 	// Route stdio:// endpoints to the local StdioClient — no HTTP, no auth.
 	if IsStdioEndpoint(endpoint) {
+		defer func() { enforceInvocationRetrySafety(invocation, retErr) }()
 		return r.executeStdioInvocationAtEndpoint(ctx, endpoint, invocation)
 	}
 
@@ -542,10 +556,13 @@ func (r *runtimeRunner) executeInvocation(ctx context.Context, endpoint string,
 			retErr == nil, time.Since(invokeStart), errCat, errReason)
 		emitAudit(auditSink, execID, invokeStart, invocation, endpoint, retErr, version)
 	}()
+	// Register this defer after the audit defer so the fail-closed safety value
+	// is what logging and audit observers see as well as what the caller gets.
+	defer func() { enforceInvocationRetrySafety(invocation, retErr) }()
 
-	// 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 +570,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)
 		}
@@ -575,14 +592,18 @@ func (r *runtimeRunner) executeInvocation(ctx context.Context, endpoint string,
 		if argsJSON, err := json.Marshal(invocation.Params); err == nil {
 			fmt.Fprintf(os.Stderr, "DRY-RUN Arguments: %s\n", argsJSON)
 		}
+		response := map[string]any{
+			"dry_run":  true,
+			"endpoint": transport.RedactURL(endpoint),
+			"request":  executor.ToolCallRequest(invocation.Tool, invocation.Params),
+			"note":     "execution skipped by --dry-run",
+		}
+		if invocation.Retry != nil {
+			response["retry"] = invocation.Retry
+		}
 		return executor.Result{
 			Invocation: invocation,
-			Response: map[string]any{
-				"dry_run":  true,
-				"endpoint": transport.RedactURL(endpoint),
-				"request":  executor.ToolCallRequest(invocation.Tool, invocation.Params),
-				"note":     "execution skipped by --dry-run",
-			},
+			Response:   response,
 		}, nil
 	}
 
@@ -603,9 +624,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 +638,23 @@ 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))
+		}
+	}
+	if invocation.Retry == nil || !invocation.Retry.SafeToRetry {
+		tc.MaxRetries = 0
 	}
 
 	callCtx := ctx
@@ -777,6 +810,24 @@ func (r *runtimeRunner) executeInvocation(ctx context.Context, endpoint string,
 	return executor.Result{Invocation: invocation, Response: response}, nil
 }
 
+// enforceInvocationRetrySafety intersects server/API retry hints with the
+// invocation's reviewed idempotency decision. Auth and PAT recovery have
+// independent one-shot retry protocols and are deliberately left untouched.
+func enforceInvocationRetrySafety(invocation executor.Invocation, err error) {
+	if invocation.Retry != nil && invocation.Retry.SafeToRetry {
+		return
+	}
+	var typed *apperrors.Error
+	if errors.As(err, &typed) && typed.Category == apperrors.CategoryAPI {
+		typed.Retryable = false
+		typed.RetryableSet = true
+		// Server backoff hints describe transience, not replay safety. Keeping
+		// them next to retryable=false invites an Agent to bypass the contract.
+		typed.RetryAfterSeconds = nil
+		typed.NextRetryAt = nil
+	}
+}
+
 func (r *runtimeRunner) executeStdioInvocationAtEndpoint(
 	ctx context.Context,
 	endpoint string,
@@ -1069,6 +1120,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/schema_shortcut_contract_test.go

@@ -16,12 +16,12 @@ import (
 )
 
 const (
-	publicShortcutCount = 378
+	publicShortcutCount = 399
 	// schemaPublishedShortcutCount counts every delivered *.shortcut_* tool,
 	// including the hidden historical minutes.shortcut_minutes_search contract.
-	schemaPublishedShortcutCount = 379
+	schemaPublishedShortcutCount = 401
 	// publiclyDeliveredShortcutCount is the public-catalog subset of that surface.
-	publiclyDeliveredShortcutCount = 378
+	publiclyDeliveredShortcutCount = 399
 )
 
 func TestDeliverySchemaCoversOrExactlyExcludesEveryPublicShortcutContract(t *testing.T) {

internal/app/server_failure_classifier_test.go

@@ -22,6 +22,7 @@ import (
 	"strings"
 	"testing"
 
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract"
 	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/executor"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/transport"
@@ -205,10 +206,16 @@ func TestCrossPlatformCoverageExecuteInvocationClassifiesObservedMCPMetadataFail
 		transport:   client,
 		globalFlags: &GlobalFlags{Token: "local-test-token"},
 	}
+	retry := contract.RetryDecision{
+		EffectiveIdempotency: "idempotent",
+		SafeToRetry:          true,
+		Reason:               "static_idempotent",
+	}
 	_, err := runner.executeInvocation(context.Background(), server.URL, executor.Invocation{
 		CanonicalProduct: "im",
 		Tool:             "list_conversations",
 		Params:           map[string]any{"pageSize": 100},
+		Retry:            &retry,
 	})
 	var typed *apperrors.Error
 	if !errors.As(err, &typed) {

internal/app/skill_command.go

@@ -126,6 +126,7 @@ var agentSkillPaths = map[string]string{
 	"claude":    ".claude/skills",
 	"cursor":    ".cursor/skills",
 	"codex":     ".codex/skills",
+	"zcode":     ".zcode/skills",
 	"opencode":  filepath.Join(".config", "opencode", "skills"),
 	// IDE / agent registries also probed by `dws skill setup --target all`.
 	"gemini":   ".gemini/skills",

internal/app/skill_command_test.go

@@ -452,7 +452,7 @@ func TestSupportedTargets(t *testing.T) {
 	// Should contain all predefined targets — including the agents/* sentinel
 	// and the IDE/agent registries we share with skillSetupAgentHomes.
 	expectedTargets := []string{
-		"agents", "claude", "cursor", "codex", "opencode", "qoder",
+		"agents", "claude", "cursor", "codex", "zcode", "opencode", "qoder",
 		"gemini", "github", "windsurf", "augment", "cline",
 		"amp", "kiro", "trae", "openclaw", "hermes",
 		".",

internal/app/skill_setup.go

@@ -29,6 +29,7 @@ var skillSetupAgentHomes = []string{
 	".qoderwork/skills",
 	".gemini/skills",
 	".codex/skills",
+	".zcode/skills",
 	".github/skills",
 	".windsurf/skills",
 	".augment/skills",
@@ -92,6 +93,7 @@ type skillSetupBackup struct {
 type skillSetupTargetPlan struct {
 	Destination string
 	Backups     []skillSetupBackup
+	CleanupOnly bool
 }
 
 type skillSetupPlan struct {
@@ -147,7 +149,8 @@ multi 模式支持按产品挑选：
     备份失败时保留原目录并跳过该目标，绝不静默删除。
   · 所有将被移除的目录都会在确认前逐条列出。
 
-不带 --mode 时进入交互式询问；不带 --target 时铺到所有检测到的 Agent 目录。
+不带 --mode 时进入交互式询问；不带 --target 时铺到检测到的具体 Agent 目录；
+未检测到具体 Agent 时才回退到 ~/.agents/skills，避免同一 Agent 扫描两份 Skill。
 skill 源默认取二进制内嵌的版本（升级二进制即升级 skill）；--source / DWS_SKILL_SOURCE 可显式覆盖。`,
 		Example: `  dws skill setup --mode multi --target claude --dry-run
   dws skill setup --mode multi --target claude`,
@@ -940,18 +943,79 @@ func agentHomeForMode(base, mode string) string {
 }
 
 func detectExistingAgentHomes(home, mode string) []string {
-	var out []string
+	var specific []string
 	for i, rel := range skillSetupAgentHomes {
+		if i == 0 {
+			continue
+		}
 		base := filepath.Join(home, rel)
 		parent := filepath.Dir(base)
-		if i > 0 {
-			if _, err := skillSetupStat(parent); errors.Is(err, os.ErrNotExist) {
+		if info, err := skillSetupStat(parent); err != nil || !info.IsDir() {
+			continue
+		}
+		specific = append(specific, agentHomeForMode(base, mode))
+	}
+	if len(specific) > 0 {
+		return specific
+	}
+	return []string{agentHomeForMode(filepath.Join(home, skillSetupAgentHomes[0]), mode)}
+}
+
+func genericSkillCleanupTarget(dests []string, managed map[string]bool) (*skillSetupTargetPlan, error) {
+	// Derive HOME from a concrete Agent destination instead of resolving it a
+	// second time. The destinations were already resolved from HOME by the
+	// caller, and a later/transient UserHomeDir failure must not turn an
+	// otherwise valid setup plan into an error. Direct/custom destinations that
+	// do not match a known concrete Agent root have no generic-root migration.
+	home := ""
+	for _, dest := range dests {
+		base := dest
+		if filepath.Base(dest) == "dws" {
+			base = filepath.Dir(dest)
+		}
+		base = filepath.Clean(base)
+		for i, rel := range skillSetupAgentHomes {
+			if i == 0 {
 				continue
 			}
+			suffix := filepath.Clean(filepath.FromSlash(rel))
+			needle := string(filepath.Separator) + suffix
+			if strings.HasSuffix(base, needle) {
+				home = strings.TrimSuffix(base, needle)
+				break
+			}
+		}
+		if home != "" {
+			break
 		}
-		out = append(out, agentHomeForMode(base, mode))
 	}
-	return out
+	if home == "" {
+		return nil, nil
+	}
+	genericBase := filepath.Join(home, ".agents", "skills")
+
+	target := &skillSetupTargetPlan{Destination: genericBase, CleanupOnly: true}
+	add := func(path, reason string) {
+		if info, statErr := skillSetupStat(path); statErr == nil && info.IsDir() {
+			target.Backups = append(target.Backups, skillSetupBackup{Path: path, Reason: reason})
+		}
+	}
+	add(filepath.Join(genericBase, "dws"), skillSetupBackupMutual)
+	entries, readErr := skillSetupReadDir(genericBase)
+	if readErr != nil && !errors.Is(readErr, os.ErrNotExist) {
+		return nil, fmt.Errorf("扫描通用 Skill 根目录失败 %s: %w", genericBase, readErr)
+	}
+	for _, entry := range entries {
+		path := filepath.Join(genericBase, entry.Name())
+		if entry.IsDir() && isManagedDWSMultiSkillDir(path, managed) {
+			target.Backups = append(target.Backups, skillSetupBackup{Path: path, Reason: skillSetupBackupStale})
+		}
+	}
+	if len(target.Backups) == 0 {
+		return nil, nil
+	}
+	sort.Slice(target.Backups, func(i, j int) bool { return target.Backups[i].Path < target.Backups[j].Path })
+	return target, nil
 }
 
 func buildSkillSetupPlan(mode, src string, dests, multiSkillNames []string, filtered bool) (*skillSetupPlan, error) {
@@ -1027,6 +1091,13 @@ func buildSkillSetupPlan(mode, src string, dests, multiSkillNames []string, filt
 		sort.Slice(target.Backups, func(i, j int) bool { return target.Backups[i].Path < target.Backups[j].Path })
 		plan.Targets = append(plan.Targets, target)
 	}
+	cleanupTarget, cleanupErr := genericSkillCleanupTarget(sortedDests, managedNames)
+	if cleanupErr != nil {
+		return nil, cleanupErr
+	}
+	if cleanupTarget != nil {
+		plan.Targets = append(plan.Targets, *cleanupTarget)
+	}
 	return plan, nil
 }
 
@@ -1079,7 +1150,11 @@ func renderSkillSetupPlan(out io.Writer, plan *skillSetupPlan) {
 	}
 	fmt.Fprintln(out, "  destinations:")
 	for _, target := range plan.Targets {
-		fmt.Fprintf(out, "    - %s\n", target.Destination)
+		if target.CleanupOnly {
+			fmt.Fprintf(out, "    - %s (仅迁移旧的通用 DWS 副本)\n", target.Destination)
+		} else {
+			fmt.Fprintf(out, "    - %s\n", target.Destination)
+		}
 	}
 	fmt.Fprintln(out, "  将备份并移除（先保存到 ~/.dws/skill-backups/）：")
 	count := 0
@@ -1676,6 +1751,21 @@ func executeSkillSetupPlan(plan *skillSetupPlan, out, errOut io.Writer) (install
 		perTarget = len(plan.MultiSkillNames)
 	}
 	for _, target := range plan.Targets {
+		if target.CleanupOnly {
+			if skipped > 0 {
+				continue
+			}
+			if homeErr != nil {
+				fmt.Fprintf(errOut, "  ✗ 无法解析 HOME，保留通用 Skill 副本 %s: %v\n", target.Destination, homeErr)
+				skipped++
+				continue
+			}
+			if _, cleanupErr := backupSkillSetupTarget(home, target.Backups, out); cleanupErr != nil {
+				fmt.Fprintf(errOut, "  ✗ 通用 Skill 副本迁移失败，已回滚 %s: %v\n", target.Destination, cleanupErr)
+				skipped++
+			}
+			continue
+		}
 		if len(target.Backups) > 0 && homeErr != nil {
 			if plan.Mode == skillSetupModeMono {
 				fmt.Fprintf(errOut, "  ✗ 无法解析 HOME，跳过刷新（保留原目录） %s: %v\n", target.Destination, homeErr)

internal/app/skill_setup_plan_test.go

@@ -146,6 +146,86 @@ func TestCrossPlatformCoverageSkillSetupMonoPlanIncludesSameNameTarget(t *testin
 	}
 }
 
+func TestCrossPlatformCoverageSkillSetupGenericCleanupDerivesHomeFromConcreteTarget(t *testing.T) {
+	home := t.TempDir()
+	dest := filepath.Join(home, ".codex", "skills")
+	genericMono := filepath.Join(home, ".agents", "skills", "dws")
+	if err := os.MkdirAll(genericMono, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	testseam.Swap(t, &skillSetupUserHomeDir, func() (string, error) {
+		return "", errors.New("transient HOME failure")
+	})
+
+	plan, err := buildSkillSetupPlan(skillSetupModeMulti, "source", []string{dest}, []string{"dingtalk-chat"}, true)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(plan.Targets) != 2 || !plan.Targets[1].CleanupOnly || plan.Targets[1].Destination != filepath.Dir(genericMono) {
+		t.Fatalf("generic cleanup target = %#v", plan.Targets)
+	}
+	if len(plan.Targets[1].Backups) != 1 || plan.Targets[1].Backups[0].Path != genericMono {
+		t.Fatalf("generic cleanup backups = %#v", plan.Targets[1].Backups)
+	}
+	var preview bytes.Buffer
+	renderSkillSetupPlan(&preview, plan)
+	if !strings.Contains(preview.String(), "仅迁移旧的通用 DWS 副本") {
+		t.Fatalf("generic cleanup preview missing: %s", preview.String())
+	}
+
+	t.Run("managed multi and scan failure", func(t *testing.T) {
+		managedDir := filepath.Join(home, ".agents", "skills", "dingtalk-chat")
+		if err := os.MkdirAll(managedDir, 0o755); err != nil {
+			t.Fatal(err)
+		}
+		target, targetErr := genericSkillCleanupTarget([]string{dest}, map[string]bool{"dingtalk-chat": true})
+		if targetErr != nil || target == nil || len(target.Backups) != 2 {
+			t.Fatalf("managed generic cleanup = %#v, %v", target, targetErr)
+		}
+		failure := errors.New("generic scan failure")
+		testseam.Swap(t, &skillSetupReadDir, func(string) ([]os.DirEntry, error) { return nil, failure })
+		if _, targetErr := genericSkillCleanupTarget([]string{dest}, nil); !errors.Is(targetErr, failure) {
+			t.Fatalf("generic scan error = %v", targetErr)
+		}
+		if _, planErr := buildSkillSetupPlan(skillSetupModeMulti, "source", []string{dest}, []string{"dingtalk-chat"}, true); !errors.Is(planErr, failure) {
+			t.Fatalf("generic cleanup plan error = %v", planErr)
+		}
+	})
+}
+
+func TestCrossPlatformCoverageSkillSetupCleanupOnlyExecutionBranches(t *testing.T) {
+	failure := errors.New("cleanup failure")
+	cleanup := skillSetupTargetPlan{Destination: "generic", CleanupOnly: true, Backups: []skillSetupBackup{{Path: "old"}}}
+
+	t.Run("prior skip suppresses cleanup", func(t *testing.T) {
+		testseam.Swap(t, &skillSetupUserHomeDir, func() (string, error) { return t.TempDir(), nil })
+		plan := &skillSetupPlan{Mode: skillSetupModeMono, Source: "missing", Targets: []skillSetupTargetPlan{{Destination: "install"}, cleanup}}
+		installed, skipped, err := executeSkillSetupPlan(plan, io.Discard, io.Discard)
+		if err != nil || installed != 0 || skipped != 1 {
+			t.Fatalf("cleanup after skip = (%d, %d, %v)", installed, skipped, err)
+		}
+	})
+
+	t.Run("home failure keeps generic copy", func(t *testing.T) {
+		testseam.Swap(t, &skillSetupUserHomeDir, func() (string, error) { return "", failure })
+		var stderr bytes.Buffer
+		_, skipped, err := executeSkillSetupPlan(&skillSetupPlan{Mode: skillSetupModeMono, Targets: []skillSetupTargetPlan{cleanup}}, io.Discard, &stderr)
+		if err != nil || skipped != 1 || !strings.Contains(stderr.String(), "保留通用 Skill 副本") {
+			t.Fatalf("cleanup HOME failure = (%d, %v, %q)", skipped, err, stderr.String())
+		}
+	})
+
+	t.Run("backup failure is reported", func(t *testing.T) {
+		testseam.Swap(t, &skillSetupUserHomeDir, func() (string, error) { return t.TempDir(), nil })
+		testseam.Swap(t, &skillSetupBackupAndRemove, func(string, string) (string, error) { return "", failure })
+		var stderr bytes.Buffer
+		_, skipped, err := executeSkillSetupPlan(&skillSetupPlan{Mode: skillSetupModeMono, Targets: []skillSetupTargetPlan{cleanup}}, io.Discard, &stderr)
+		if err != nil || skipped != 1 || !strings.Contains(stderr.String(), "迁移失败") {
+			t.Fatalf("cleanup backup failure = (%d, %v, %q)", skipped, err, stderr.String())
+		}
+	})
+}
+
 func TestCrossPlatformCoverageSkillSetupPlanDeduplicatesAndFailsClosed(t *testing.T) {
 	dest := filepath.Join(t.TempDir(), "skills")
 	if err := os.MkdirAll(filepath.Join(dest, "dws"), 0o755); err != nil {

internal/app/skill_setup_test.go

@@ -330,6 +330,50 @@ func TestResolveSkillSetupTargetsMultiOmitsDwsTail(t *testing.T) {
 	}
 }
 
+func TestCrossPlatformCoverageResolveSkillSetupTargetsPrefersSpecificAgentRoot(t *testing.T) {
+	home := t.TempDir()
+	testseam.Swap(t, &skillSetupUserHomeDir, func() (string, error) { return home, nil })
+	testseam.Swap(t, &skillSetupAgentHomes, []string{".agents/skills", ".codex/skills"})
+	if err := os.MkdirAll(filepath.Join(home, ".codex"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+
+	got, err := resolveSkillSetupTargets("all", skillSetupModeMulti)
+	if err != nil {
+		t.Fatal(err)
+	}
+	want := filepath.Join(home, ".codex", "skills")
+	if len(got) != 1 || filepath.Clean(got[0]) != filepath.Clean(want) {
+		t.Fatalf("targets = %v, want [%s]", got, want)
+	}
+}
+
+func TestCrossPlatformCoverageResolveSkillSetupTargetsDetectsZCode(t *testing.T) {
+	home := t.TempDir()
+	testseam.Swap(t, &skillSetupUserHomeDir, func() (string, error) { return home, nil })
+	if err := os.MkdirAll(filepath.Join(home, ".zcode"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+
+	got, err := resolveSkillSetupTargets("all", skillSetupModeMulti)
+	if err != nil {
+		t.Fatal(err)
+	}
+	want := filepath.Join(home, ".zcode", "skills")
+	if len(got) != 1 || filepath.Clean(got[0]) != filepath.Clean(want) {
+		t.Fatalf("targets = %v, want [%s]", got, want)
+	}
+
+	explicit, err := resolveSkillSetupTargets("zcode", skillSetupModeMono)
+	if err != nil {
+		t.Fatal(err)
+	}
+	wantMono := filepath.Join(want, "dws")
+	if len(explicit) != 1 || filepath.Clean(explicit[0]) != filepath.Clean(wantMono) {
+		t.Fatalf("explicit zcode targets = %v, want [%s]", explicit, wantMono)
+	}
+}
+
 func TestCrossPlatformCoverageInstallSkillToHomesEndToEnd(t *testing.T) {
 	src := t.TempDir()
 	if err := os.WriteFile(filepath.Join(src, "SKILL.md"), []byte("# test"), 0o644); err != nil {

internal/app/skill_startup_repair.go

@@ -0,0 +1,42 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0
+
+package app
+
+import (
+	"path/filepath"
+
+	"github.com/spf13/cobra"
+)
+
+// detectNestedMultiSkillLayout detects the compatibility gap where an older
+// running dws process replaces itself with a newer binary, but then installs
+// the new release bundle with its legacy mono copier. That produces the
+// impossible layout <agent>/dws/multi/<skill>/SKILL.md.
+//
+// Detection is deliberately read-only. Ordinary commands must not turn a
+// compatibility warning into an unconfirmed, cross-Agent Skill refresh.
+// A legitimate mono install has no dws/multi product tree and is ignored.
+func detectNestedMultiSkillLayout() (bool, error) {
+	home, err := skillSetupUserHomeDir()
+	if err != nil {
+		return false, err
+	}
+	for _, rel := range skillSetupAgentHomes {
+		nested := filepath.Join(home, rel, "dws", "multi")
+		if isSkillSourceRoot(nested, skillSetupModeMulti) {
+			return true, nil
+		}
+	}
+	return false, nil
+}
+
+func shouldDetectNestedSkillLayout(cmd *cobra.Command) bool {
+	if cmd == nil {
+		return true
+	}
+	if cmd.Name() == "upgrade" {
+		return false
+	}
+	return !(cmd.Name() == "setup" && cmd.Parent() != nil && cmd.Parent().Name() == "skill")
+}

internal/app/skill_startup_repair_test.go

@@ -0,0 +1,131 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0
+
+package app
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/skillstate"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam"
+	"github.com/spf13/cobra"
+)
+
+func TestCrossPlatformCoverageStartupDetectsNestedUpgradeLayoutWithoutMutation(t *testing.T) {
+	home := t.TempDir()
+	testseam.Swap(t, &skillSetupUserHomeDir, func() (string, error) { return home, nil })
+	testseam.Swap(t, &skillSetupAgentHomes, []string{".agents/skills", ".codex/skills"})
+	nested := filepath.Join(home, ".agents", "skills", "dws", "multi", "dingtalk-chat")
+	if err := os.MkdirAll(nested, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(nested, "SKILL.md"), []byte("old nested"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	found, err := detectNestedMultiSkillLayout()
+	if err != nil || !found {
+		t.Fatalf("detect nested layout = (%v, %v), want (true, nil)", found, err)
+	}
+	data, err := os.ReadFile(filepath.Join(nested, "SKILL.md"))
+	if err != nil || string(data) != "old nested" {
+		t.Fatalf("detection changed nested Skill: data=%q err=%v", data, err)
+	}
+	if _, err := os.Stat(filepath.Join(home, ".codex", "skills", "dingtalk-chat")); !os.IsNotExist(err) {
+		t.Fatalf("detection unexpectedly installed a canonical Skill: %v", err)
+	}
+}
+
+func TestCrossPlatformCoverageStartupDetectionIgnoresMonoAndReportsReadFailure(t *testing.T) {
+	home := t.TempDir()
+	testseam.Swap(t, &skillSetupUserHomeDir, func() (string, error) { return home, nil })
+	testseam.Swap(t, &skillSetupAgentHomes, []string{".agents/skills"})
+	mono := filepath.Join(home, ".agents", "skills", "dws")
+	if err := os.MkdirAll(mono, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(mono, "SKILL.md"), []byte("valid mono"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	found, err := detectNestedMultiSkillLayout()
+	if err != nil || found {
+		t.Fatalf("valid mono detection = (%v, %v), want (false, nil)", found, err)
+	}
+
+	failure := errors.New("HOME failure")
+	testseam.Swap(t, &skillSetupUserHomeDir, func() (string, error) { return "", failure })
+	found, err = detectNestedMultiSkillLayout()
+	if found || !errors.Is(err, failure) {
+		t.Fatalf("HOME failure detection = (%v, %v)", found, err)
+	}
+}
+
+func TestCrossPlatformCoverageStartupDetectionSkipsExplicitSkillManagers(t *testing.T) {
+	upgradeCmd := &cobra.Command{Use: "upgrade"}
+	if shouldDetectNestedSkillLayout(upgradeCmd) {
+		t.Fatal("upgrade must manage its own Skill lifecycle")
+	}
+	skillCmd := &cobra.Command{Use: "skill"}
+	setupCmd := &cobra.Command{Use: "setup"}
+	skillCmd.AddCommand(setupCmd)
+	if shouldDetectNestedSkillLayout(setupCmd) {
+		t.Fatal("skill setup must manage its own Skill lifecycle")
+	}
+	if !shouldDetectNestedSkillLayout(&cobra.Command{Use: "version"}) || !shouldDetectNestedSkillLayout(nil) {
+		t.Fatal("ordinary commands must trigger read-only detection")
+	}
+}
+
+func TestCrossPlatformCoverageStartupWarningIsReadOnlyAndDoesNotBypassConfirmation(t *testing.T) {
+	home := t.TempDir()
+	testseam.Swap(t, &skillSetupUserHomeDir, func() (string, error) { return home, nil })
+	testseam.Swap(t, &skillSetupAgentHomes, []string{".codex/skills"})
+	nested := filepath.Join(home, ".codex", "skills", "dws", "multi", "dingtalk-chat")
+	if err := os.MkdirAll(nested, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(nested, "SKILL.md"), []byte("old nested"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	// Any accidental return to startup mutation must fail this test before it
+	// can touch the fixture.
+	testseam.Swap(t, &skillSetupCopyDir, func(string, string) error {
+		t.Fatal("ordinary command attempted to copy Skills")
+		return nil
+	})
+	testseam.Swap(t, &skillSetupBackupAndRemove, func(string, string) (string, error) {
+		t.Fatal("ordinary command attempted to back up or remove Skills")
+		return "", nil
+	})
+	testseam.Swap(t, &skillSetupWriteState, func(string, skillstate.State) error {
+		t.Fatal("ordinary command attempted to write Skill state")
+		return nil
+	})
+
+	root := newRootCommandWithEngine(context.Background(), nil, false, true)
+	cmd := &cobra.Command{Use: "version"}
+	cmd.SetContext(context.Background())
+	var stderr bytes.Buffer
+	cmd.SetErr(&stderr)
+	if err := root.PersistentPreRunE(cmd, nil); err != nil {
+		t.Fatal(err)
+	}
+	warning := stderr.String()
+	if !strings.Contains(warning, "dws skill setup --mode multi") {
+		t.Fatalf("safe migration hint missing: %q", warning)
+	}
+	if strings.Contains(warning, "--yes") {
+		t.Fatalf("migration hint bypasses confirmation: %q", warning)
+	}
+	data, err := os.ReadFile(filepath.Join(nested, "SKILL.md"))
+	if err != nil || string(data) != "old nested" {
+		t.Fatalf("ordinary command changed nested Skill: data=%q err=%v", data, err)
+	}
+}

internal/app/tool_caller_adapter.go

@@ -44,6 +44,11 @@ func newToolCallerAdapter(runner executor.Runner, flags *GlobalFlags) edition.To
 
 func (a *toolCallerAdapter) CallTool(ctx context.Context, productID, toolName string, args map[string]any) (*edition.ToolResult, error) {
 	inv := executor.NewHelperInvocation("overlay."+productID+"."+toolName, productID, toolName, args)
+	if a != nil {
+		if runtime, ok := a.runner.(*runtimeRunner); ok {
+			runtime.resolveInvocationRetry(&inv)
+		}
+	}
 	// Defense in depth for direct helper callers: global dry-run must never
 	// reach an injected/real Runner, even if a command bypasses the normal
 	// Schema leaf wrapper. EchoRunner produces the same stable dry_run envelope

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

@@ -28,6 +28,8 @@ import (
 	"strings"
 	"sync"
 	"sync/atomic"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract"
 )
 
 // CommandMeta is the complete runtime metadata view for a single command.
@@ -56,8 +58,9 @@ type CommandSelection struct {
 }
 
 var (
-	metaByCLIPathOnce sync.Once
-	metaByCLIPath     map[string]CommandMeta
+	metaByCLIPathOnce        sync.Once
+	metaByCLIPath            map[string]CommandMeta
+	toolCallRetryByInterface map[InterfaceRefKey]toolCallRetryResolution
 )
 
 // Counter names retain "MetaIndex" for RuntimeSchemaMetadataLoadCounts
@@ -75,10 +78,12 @@ func installDeliveryCommandMeta(loaded loadedSchemaCatalog, err error) {
 	if err != nil {
 		runtimeDeliverySchemaMetaIndexErr = err
 		metaByCLIPath = nil
+		toolCallRetryByInterface = nil
 		metaByCLIPathOnce.Do(func() {})
 		return
 	}
 	metaByCLIPath = buildMetaByCLIPath(loaded)
+	toolCallRetryByInterface = buildToolCallRetryLookup(loaded)
 	runtimeDeliverySchemaMetaIndexErr = nil
 	metaByCLIPathOnce.Do(func() {})
 }
@@ -124,6 +129,7 @@ func buildMetaByCLIPathFromRegistry(registry SchemaRegistry) map[string]CommandM
 					Risk:         tool.Safety.Risk,
 					Confirmation: tool.Safety.Confirmation,
 					Idempotency:  tool.Safety.Idempotency,
+					RetryPolicy:  cloneRetryPolicy(tool.RetryPolicy),
 				},
 				Selection: CommandSelection{
 					AgentSummary: tool.Selection.AgentSummary,
@@ -163,6 +169,7 @@ func buildMetaByCLIPathFromSnapshotTools(tools map[string]map[string]any) map[st
 				Risk:         schemaString(tool["risk"]),
 				Confirmation: schemaString(tool["confirmation"]),
 				Idempotency:  schemaString(tool["idempotency"]),
+				RetryPolicy:  retryPolicyFromSchemaValue(tool["retry_policy"]),
 			},
 			Selection: CommandSelection{
 				AgentSummary: schemaString(tool["agent_summary"]),
@@ -212,3 +219,13 @@ func ResolveMeta(cliPath string) (CommandMeta, bool) {
 	m, ok := metaByCLIPath[cliPath]
 	return m, ok
 }
+
+// ResolveInvocationSafety returns the effective retry decision for one CLI
+// invocation. The arguments map is keyed by declared CLI parameter names.
+func ResolveInvocationSafety(cliPath string, arguments map[string]any) (contract.RetryDecision, bool) {
+	meta, ok := ResolveMeta(cliPath)
+	if !ok {
+		return contract.RetryDecision{}, false
+	}
+	return meta.Safety.Resolve(arguments), true
+}

internal/cli/command_safety.go

@@ -17,6 +17,7 @@ import (
 	"fmt"
 	"strings"
 
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract"
 	"github.com/spf13/cobra"
 )
 
@@ -30,7 +31,18 @@ type CommandSafety struct {
 	Effect       string // read / write / destructive
 	Risk         string // low / medium / high
 	Confirmation string // not_required / user_required
-	Idempotency  string // idempotent / non_idempotent
+	Idempotency  string // idempotent / non_idempotent / unknown / conditional
+	RetryPolicy  *contract.RetryPolicySpec
+}
+
+// Resolve derives invocation-scoped retry safety from reviewed metadata and
+// actual CLI arguments. It never changes the static Schema contract.
+func (s CommandSafety) Resolve(arguments map[string]any) contract.RetryDecision {
+	key := ""
+	if s.RetryPolicy != nil {
+		key = s.RetryPolicy.KeyParameter
+	}
+	return contract.ResolveRetryDecision(s.Idempotency, s.RetryPolicy, arguments, key)
 }
 
 // ShouldRender returns true when the safety metadata warrants a visible

internal/cli/command_safety_test.go

@@ -15,6 +15,7 @@ package cli
 
 import (
 	"fmt"
+	"reflect"
 	"strings"
 	"testing"
 )
@@ -79,7 +80,7 @@ func TestSafetyForCLIPathTrimsWhitespace(t *testing.T) {
 	if !ok2 {
 		t.Fatal("trimmed lookup failed; whitespace not trimmed")
 	}
-	if s1 != s2 {
+	if !reflect.DeepEqual(s1, s2) {
 		t.Errorf("whitespace-trimmed result differs: %+v vs %+v", s1, s2)
 	}
 }
@@ -161,7 +162,7 @@ func TestResolveMetaAliasLookup(t *testing.T) {
 	if aliased.Identity.CLIPath != primary.Identity.CLIPath || aliased.Identity.Canonical != primary.Identity.Canonical {
 		t.Fatalf("alias metadata = %+v, want same identity as primary %+v", aliased.Identity, primary.Identity)
 	}
-	if aliased.Safety != primary.Safety {
+	if !reflect.DeepEqual(aliased.Safety, primary.Safety) {
 		t.Fatalf("alias safety = %+v, want %+v", aliased.Safety, primary.Safety)
 	}
 }

internal/cli/contract_final_assembly_test.go

@@ -35,7 +35,13 @@ func TestCrossPlatformCoverageRuntimeToolSpecFromContractFinalPassThrough(t *tes
 	contractfinal.RegisterRuntimeContractFinal(cmd, contract.ContractFinalPayload{
 		Title: "Final Title",
 		Safety: &contract.SafetySpec{
-			Effect: "write", Confirmation: "user_required", Idempotency: "none",
+			Effect: "write", Confirmation: "user_required", Idempotency: "conditional",
+		},
+		RetryPolicy: &contract.RetryPolicySpec{Mode: contract.RetryModeDeduplicationKey, KeyParameter: "mode", SamePayloadRequired: true},
+		Parameters:  []contract.ParamDecl{{Name: "mode", Property: "mode"}},
+		Interface: &contract.InterfaceSpec{
+			Mode: contract.InterfaceModeMCP, Availability: contract.InterfaceAvailable,
+			Ref: &contract.InterfaceRefSpec{ProductID: "dev", RPCName: "create_thing"},
 		},
 		DryRun: &contract.DryRunSpec{PreviewKind: contract.DryRunPreviewInvocation},
 		Result: &contract.ResultSpec{
@@ -69,9 +75,12 @@ func TestCrossPlatformCoverageRuntimeToolSpecFromContractFinalPassThrough(t *tes
 	if spec.Title != "Final Title" {
 		t.Fatalf("title = %q", spec.Title)
 	}
-	if spec.Safety.Confirmation != "user_required" || spec.Safety.Idempotency != "none" {
+	if spec.Safety.Confirmation != "user_required" || spec.Safety.Idempotency != "conditional" {
 		t.Fatalf("safety = %#v", spec.Safety)
 	}
+	if spec.RetryPolicy == nil || spec.RetryPolicy.KeyParameter != "mode" {
+		t.Fatalf("retry_policy = %#v", spec.RetryPolicy)
+	}
 	if spec.DryRun == nil || spec.DryRun.PreviewKind != contract.DryRunPreviewInvocation {
 		t.Fatalf("dry_run = %#v", spec.DryRun)
 	}
@@ -89,6 +98,21 @@ func TestCrossPlatformCoverageRuntimeToolSpecFromContractFinalPassThrough(t *tes
 	}
 }
 
+func TestCrossPlatformCoverageRuntimeToolSpecRejectsInvalidRetryPolicy(t *testing.T) {
+	cmd := &cobra.Command{Use: "send"}
+	entry := runtimeSchemaEntry{
+		ProductID: "chat", ToolName: "send", CLIName: "send",
+		CLIPath: "chat send", PrimaryCLIPath: "chat send", ProductName: "Chat", Command: cmd,
+	}
+	_, err := runtimeToolSpecFromContractFinal(entry, contract.ContractFinalPayload{
+		Safety:      &contract.SafetySpec{Idempotency: "conditional"},
+		RetryPolicy: &contract.RetryPolicySpec{Mode: "inferred", KeyParameter: "uuid", SamePayloadRequired: true},
+	}, runtimeSchemaMetadataSources{})
+	if err == nil || !strings.Contains(err.Error(), "unsupported mode") {
+		t.Fatalf("invalid retry policy error = %v", err)
+	}
+}
+
 func TestRuntimeToolSpecHidesUnifiedResultForInactiveRollout(t *testing.T) {
 	for _, state := range []output.RolloutState{output.RolloutLegacyOnly, output.RolloutDualValidate} {
 		t.Run(string(state), func(t *testing.T) {

internal/cli/retry_policy_contract_test.go

@@ -0,0 +1,261 @@
+// 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 cli
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract"
+	"github.com/spf13/cobra"
+)
+
+func conditionalRetryTool() RuntimeToolSpecInput {
+	return RuntimeToolSpecInput{
+		Identity: contract.ToolIdentitySpec{ProductID: "chat", Name: "send", CLIPath: "chat send"},
+		Parameters: []ParameterSpec{{
+			Name: "uuid", Type: "string", Property: "requestUuid",
+			FieldProvenance: map[string]contract.FieldProvenance{
+				"property": resolvedFieldProvenance(
+					"requestUuid", "native_annotation", "contract.ParamDecl", "native_annotation",
+					"contract_pass_through", "explicit retry key property",
+				),
+			},
+		}},
+		Safety: contract.SafetySpec{Effect: "write", Risk: "medium", Confirmation: "not_required", Idempotency: "conditional"},
+		RetryPolicy: &contract.RetryPolicySpec{
+			Mode:                contract.RetryModeDeduplicationKey,
+			KeyParameter:        "uuid",
+			SamePayloadRequired: true,
+		},
+		Interface: contract.InterfaceSpec{
+			Mode:         contract.InterfaceModeMCP,
+			Availability: contract.InterfaceAvailable,
+			Ref:          &contract.InterfaceRefSpec{ProductID: "chat", RPCName: "send"},
+		},
+		FieldProvenance: map[string]contract.FieldProvenance{
+			"retry_policy": resolvedFieldProvenance(
+				contract.RetryPolicySpec{Mode: contract.RetryModeDeduplicationKey, KeyParameter: "uuid", SamePayloadRequired: true},
+				"corecmd.contract", "corecmd.ContractDecl", "contract_final", "contract_pass_through", "reviewed retry policy",
+			),
+		},
+	}
+}
+
+func TestCrossPlatformCoverageConditionalRetryPolicyValidatesAndProjects(t *testing.T) {
+	spec, err := ToolSpecFromRuntime(conditionalRetryTool())
+	if err != nil {
+		t.Fatalf("ToolSpecFromRuntime() error = %v", err)
+	}
+	full, err := spec.ToPayload()
+	if err != nil {
+		t.Fatalf("ToPayload() error = %v", err)
+	}
+	policy, ok := full["retry_policy"].(map[string]any)
+	if !ok || policy["mode"] != contract.RetryModeDeduplicationKey || policy["key_parameter"] != "uuid" || policy["same_payload_required"] != true {
+		t.Fatalf("retry_policy = %#v", full["retry_policy"])
+	}
+	compact := stripSchemaPayloadCompact(full)
+	if !schemaJSONEqual(compact["retry_policy"], full["retry_policy"]) {
+		t.Fatalf("compact retry_policy = %#v, want %#v", compact["retry_policy"], full["retry_policy"])
+	}
+	summary, err := spec.ToSummaryPayload()
+	if err != nil {
+		t.Fatalf("ToSummaryPayload() error = %v", err)
+	}
+	if _, exists := summary["retry_policy"]; exists {
+		t.Fatalf("navigation summary must omit retry_policy: %#v", summary)
+	}
+	wire, err := schemaToolWireFromPayload(full)
+	if err != nil {
+		t.Fatalf("schemaToolWireFromPayload() error = %v", err)
+	}
+	roundTrip, err := schemaToolSpecFromWire(wire)
+	if err != nil || roundTrip.RetryPolicy == nil || roundTrip.RetryPolicy.KeyParameter != "uuid" {
+		t.Fatalf("snapshot retry_policy = %#v, error = %v", roundTrip.RetryPolicy, err)
+	}
+
+	registry := SchemaRegistry{Products: []ProductSpec{{ID: "chat", Tools: []ToolSpec{spec}}}}
+	meta := buildMetaByCLIPathFromRegistry(registry)["chat send"]
+	if meta.Safety.RetryPolicy == nil || meta.Safety.RetryPolicy.KeyParameter != "uuid" {
+		t.Fatalf("ResolveMeta projection lost retry_policy: %#v", meta.Safety)
+	}
+	if decision := meta.Safety.Resolve(map[string]any{"uuid": "request-1"}); !decision.SafeToRetry || decision.EffectiveIdempotency != "idempotent" {
+		t.Fatalf("invocation decision = %#v", decision)
+	}
+	if decision := meta.Safety.Resolve(nil); decision.SafeToRetry || decision.EffectiveIdempotency != "non_idempotent" {
+		t.Fatalf("missing-key invocation decision = %#v", decision)
+	}
+	t.Cleanup(restorePackageCLISchemaDeliveryForTest)
+	storeSchemaSourceRootFn(func() *cobra.Command { return &cobra.Command{Use: "dws"} })
+	assembleDeliverySchemaCatalogFn = func(*cobra.Command) (loadedSchemaCatalog, error) {
+		return loadedSchemaCatalog{Registry: registry}, nil
+	}
+	resetSchemaDeliveryState()
+	decision, ok := ResolveInvocationSafety("chat send", map[string]any{"uuid": "request-1"})
+	if !ok || !decision.SafeToRetry || decision.EffectiveIdempotency != "idempotent" {
+		t.Fatalf("ResolveInvocationSafety() = %#v, ok=%v", decision, ok)
+	}
+	if _, ok := ResolveInvocationSafety("chat missing", nil); ok {
+		t.Fatal("ResolveInvocationSafety() must not invent missing commands")
+	}
+	transportDecision := ResolveToolCallRetry("chat", "send", map[string]any{"requestUuid": "request-1"})
+	if !transportDecision.SafeToRetry || transportDecision.EffectiveIdempotency != "idempotent" {
+		t.Fatalf("ResolveToolCallRetry() = %#v", transportDecision)
+	}
+	if missing := ResolveToolCallRetry("chat", "missing", nil); missing.SafeToRetry || missing.Reason != "interface_not_declared" {
+		t.Fatalf("missing interface decision = %#v", missing)
+	}
+	lookup := buildToolCallRetryLookup(loadedSchemaCatalog{Registry: registry})
+	resolution := lookup[retryInterfaceRefKey("chat", "send")]
+	resolvedDecision := contract.ResolveRetryDecision(resolution.idempotency, resolution.policy, map[string]any{"requestUuid": "request-1"}, resolution.argumentKey)
+	if !resolvedDecision.SafeToRetry {
+		t.Fatalf("interface retry decision = %#v", resolvedDecision)
+	}
+	fullTool, _ := spec.ToPayload()
+	metaSnapshot := SchemaCatalogSnapshot{Version: SchemaCatalogSnapshotVersion, SourceHash: "retry-source", Tools: map[string]map[string]any{"chat.send": fullTool}}
+	metaIndex, err := BuildSchemaMetaIndex(metaSnapshot)
+	if err != nil || len(metaIndex.Entries) != 1 || metaIndex.Entries[0].RetryPolicy == nil {
+		t.Fatalf("BuildSchemaMetaIndex() = %#v, error = %v", metaIndex, err)
+	}
+	encodedIndex, err := EncodeSchemaMetaIndex(metaIndex)
+	if err != nil {
+		t.Fatalf("EncodeSchemaMetaIndex() error = %v", err)
+	}
+	decodedIndex, err := DecodeSchemaMetaIndex(encodedIndex)
+	if err != nil || decodedIndex.Entries[0].RetryPolicy == nil || decodedIndex.Entries[0].RetryPolicy.KeyParameter != "uuid" {
+		t.Fatalf("DecodeSchemaMetaIndex() = %#v, error = %v", decodedIndex, err)
+	}
+	if err := ValidateSchemaMetaIndexAgainstSnapshot(metaIndex, metaSnapshot); err != nil {
+		t.Fatalf("ValidateSchemaMetaIndexAgainstSnapshot() error = %v", err)
+	}
+	snapshotLookup := buildToolCallRetryLookup(loadedSchemaCatalog{Snapshot: SchemaCatalogSnapshot{Tools: map[string]map[string]any{
+		"chat.send":  fullTool,
+		"chat.local": {"interface_mode": contract.InterfaceModeLocal},
+	}}})
+	snapshotResolution := snapshotLookup[retryInterfaceRefKey("chat", "send")]
+	if snapshotResolution.argumentKey != "requestUuid" || snapshotResolution.policy == nil {
+		t.Fatalf("snapshot retry resolution = %#v", snapshotResolution)
+	}
+	invalidSnapshot := map[string]any{
+		"interface_mode": contract.InterfaceModeMCP,
+		"interface_ref":  map[string]any{"product_id": "chat", "rpc_name": "invalid"},
+		"idempotency":    "conditional",
+		"retry_policy":   map[string]any{"mode": "inferred", "key_parameter": "uuid", "same_payload_required": true},
+	}
+	invalidLookup := buildToolCallRetryLookup(loadedSchemaCatalog{Snapshot: SchemaCatalogSnapshot{Tools: map[string]map[string]any{"chat.invalid": invalidSnapshot}}})
+	invalidResolution := invalidLookup[retryInterfaceRefKey("chat", "invalid")]
+	if invalidResolution.policy != nil || contract.ResolveRetryDecision(invalidResolution.idempotency, nil, nil, "").Reason != "invalid_retry_policy" {
+		t.Fatalf("invalid snapshot retry resolution = %#v", invalidResolution)
+	}
+	missingBindingSnapshot := map[string]any{
+		"interface_mode": contract.InterfaceModeMCP,
+		"interface_ref":  map[string]any{"product_id": "chat", "rpc_name": "missing_binding"},
+		"idempotency":    "conditional",
+		"retry_policy":   map[string]any{"mode": contract.RetryModeDeduplicationKey, "key_parameter": "uuid", "same_payload_required": true},
+		"parameters":     map[string]any{"uuid": map[string]any{"type": "string"}},
+	}
+	missingBindingLookup := buildToolCallRetryLookup(loadedSchemaCatalog{Snapshot: SchemaCatalogSnapshot{Tools: map[string]map[string]any{
+		"chat.missing_binding": missingBindingSnapshot,
+	}}})
+	missingBindingResolution := missingBindingLookup[retryInterfaceRefKey("chat", "missing_binding")]
+	missingBindingDecision := contract.ResolveRetryDecision(
+		missingBindingResolution.idempotency,
+		missingBindingResolution.policy,
+		map[string]any{"uuid": "request-1"},
+		missingBindingResolution.argumentKey,
+	)
+	if missingBindingDecision.SafeToRetry || missingBindingDecision.Reason != "deduplication_key_binding_missing" {
+		t.Fatalf("snapshot missing property inferred a key binding: %#v", missingBindingDecision)
+	}
+	if retryPolicyFromSchemaValue(func() {}) != nil || retryPolicyFromSchemaValue("invalid") != nil || retryPolicyFromSchemaValue(nil) != nil {
+		t.Fatal("invalid snapshot policy values must fail closed")
+	}
+
+	conflict := spec
+	conflict.Identity.Name = "reply"
+	conflict.Identity.CanonicalPath = "chat.reply"
+	conflict.Identity.CLIPath = "chat reply"
+	conflict.Identity.PrimaryCLIPath = "chat reply"
+	conflict.Safety.Idempotency = "unknown"
+	conflict.RetryPolicy = nil
+	conflict.FieldProvenance = nil
+	conflictRegistry := SchemaRegistry{Products: []ProductSpec{{ID: "chat", Tools: []ToolSpec{spec, conflict}}}}
+	assembleDeliverySchemaCatalogFn = func(*cobra.Command) (loadedSchemaCatalog, error) {
+		return loadedSchemaCatalog{Registry: conflictRegistry}, nil
+	}
+	resetSchemaDeliveryState()
+	conflictDecision := ResolveToolCallRetry("chat", "send", map[string]any{"requestUuid": "request-1"})
+	if conflictDecision.SafeToRetry || conflictDecision.Reason != "interface_retry_policy_conflict" {
+		t.Fatalf("conflicting interface decision = %#v", conflictDecision)
+	}
+}
+
+func TestCrossPlatformCoverageConditionalRetryPolicyFailsClosed(t *testing.T) {
+	for name, mutate := range map[string]func(*RuntimeToolSpecInput){
+		"missing policy":       func(in *RuntimeToolSpecInput) { in.RetryPolicy = nil },
+		"missing parameter":    func(in *RuntimeToolSpecInput) { in.Parameters = nil },
+		"missing property":     func(in *RuntimeToolSpecInput) { in.Parameters[0].Property = "" },
+		"non string parameter": func(in *RuntimeToolSpecInput) { in.Parameters[0].Type = "integer" },
+		"inferred property": func(in *RuntimeToolSpecInput) {
+			in.Parameters[0].FieldProvenance["property"] = resolvedFieldProvenance(
+				"requestUuid", "flag_name_inference", "cobra.flag", "inference", "fallback", "inferred",
+			)
+		},
+		"non MCP interface": func(in *RuntimeToolSpecInput) {
+			in.Interface = contract.InterfaceSpec{Mode: contract.InterfaceModeLocal, Availability: contract.InterfaceAvailable, Reason: "local"}
+		},
+		"policy on static idempotent": func(in *RuntimeToolSpecInput) { in.Safety.Idempotency = "idempotent" },
+		"invalid policy mode":         func(in *RuntimeToolSpecInput) { in.RetryPolicy.Mode = "inferred" },
+	} {
+		t.Run(name, func(t *testing.T) {
+			input := conditionalRetryTool()
+			mutate(&input)
+			if _, err := ToolSpecFromRuntime(input); err == nil {
+				t.Fatal("invalid retry contract must fail closed")
+			}
+		})
+	}
+}
+
+func TestCrossPlatformCoverageConditionalRetryPolicyRequiresFinalProvenance(t *testing.T) {
+	spec, err := ToolSpecFromRuntime(conditionalRetryTool())
+	if err != nil {
+		t.Fatalf("ToolSpecFromRuntime() error = %v", err)
+	}
+	delete(spec.FieldProvenance, "retry_policy")
+	err = validateFinalSchemaProvenanceCoverage(SchemaRegistry{Products: []ProductSpec{{
+		ID: "chat", Tools: []ToolSpec{spec},
+	}}})
+	if err == nil || !strings.Contains(err.Error(), "has no provenance for retry_policy") {
+		t.Fatalf("validateFinalSchemaProvenanceCoverage() error = %v", err)
+	}
+}
+
+func TestCrossPlatformCoverageInterfaceRetryPolicyConflictFailsClosed(t *testing.T) {
+	lookup := map[InterfaceRefKey]toolCallRetryResolution{}
+	key := retryInterfaceRefKey("chat", "send")
+	idempotent := toolCallRetryResolution{idempotency: "idempotent"}
+	mergeToolCallRetryResolution(lookup, key, idempotent)
+	mergeToolCallRetryResolution(lookup, key, idempotent)
+	mergeToolCallRetryResolution(lookup, key, toolCallRetryResolution{idempotency: "unknown"})
+	mergeToolCallRetryResolution(lookup, key, idempotent)
+	if got := lookup[key]; !got.conflict {
+		t.Fatalf("conflicting interface retry semantics = %#v", got)
+	}
+	decision := contract.RetryDecision{EffectiveIdempotency: "unknown", Reason: "interface_retry_policy_conflict"}
+	if decision.SafeToRetry || !strings.Contains(decision.Reason, "conflict") {
+		t.Fatalf("conflict decision = %#v", decision)
+	}
+}

internal/cli/retry_resolution.go

@@ -0,0 +1,135 @@
+// 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 cli
+
+import (
+	"encoding/json"
+	"reflect"
+	"strings"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract"
+)
+
+type toolCallRetryResolution struct {
+	idempotency string
+	policy      *contract.RetryPolicySpec
+	argumentKey string
+	conflict    bool
+}
+
+func retryInterfaceRefKey(productID, rpcName string) InterfaceRefKey {
+	return InterfaceRefKey{
+		ProductID: strings.TrimSpace(productID),
+		RPCName:   strings.TrimSpace(rpcName),
+	}
+}
+
+func buildToolCallRetryLookup(loaded loadedSchemaCatalog) map[InterfaceRefKey]toolCallRetryResolution {
+	if len(loaded.Registry.Products) == 0 {
+		return buildToolCallRetryLookupFromSnapshot(loaded.Snapshot.Tools)
+	}
+	lookup := make(map[InterfaceRefKey]toolCallRetryResolution)
+	for _, product := range loaded.Registry.Products {
+		for _, tool := range product.Tools {
+			if tool.Interface.Mode != contract.InterfaceModeMCP || tool.Interface.Ref == nil {
+				continue
+			}
+			resolution := toolCallRetryResolution{idempotency: tool.Safety.Idempotency, policy: cloneRetryPolicy(tool.RetryPolicy)}
+			if tool.RetryPolicy != nil {
+				for _, parameter := range tool.Parameters {
+					if parameter.Name == tool.RetryPolicy.KeyParameter {
+						resolution.argumentKey = parameter.Property
+						break
+					}
+				}
+			}
+			mergeToolCallRetryResolution(lookup, retryInterfaceRefKey(tool.Interface.Ref.ProductID, tool.Interface.Ref.RPCName), resolution)
+		}
+	}
+	return lookup
+}
+
+func buildToolCallRetryLookupFromSnapshot(tools map[string]map[string]any) map[InterfaceRefKey]toolCallRetryResolution {
+	lookup := make(map[InterfaceRefKey]toolCallRetryResolution)
+	for _, tool := range tools {
+		ref, _ := tool["interface_ref"].(map[string]any)
+		productID, rpcName := schemaString(ref["product_id"]), schemaString(ref["rpc_name"])
+		if schemaString(tool["interface_mode"]) != contract.InterfaceModeMCP || productID == "" || rpcName == "" {
+			continue
+		}
+		policy := retryPolicyFromSchemaValue(tool["retry_policy"])
+		resolution := toolCallRetryResolution{idempotency: schemaString(tool["idempotency"]), policy: policy}
+		if policy != nil {
+			parameters, _ := tool["parameters"].(map[string]any)
+			parameter, _ := parameters[policy.KeyParameter].(map[string]any)
+			resolution.argumentKey = schemaString(parameter["property"])
+		}
+		mergeToolCallRetryResolution(lookup, retryInterfaceRefKey(productID, rpcName), resolution)
+	}
+	return lookup
+}
+
+func mergeToolCallRetryResolution(lookup map[InterfaceRefKey]toolCallRetryResolution, key InterfaceRefKey, candidate toolCallRetryResolution) {
+	current, exists := lookup[key]
+	if !exists {
+		lookup[key] = candidate
+		return
+	}
+	if current.conflict || current.idempotency != candidate.idempotency || current.argumentKey != candidate.argumentKey || !reflect.DeepEqual(current.policy, candidate.policy) {
+		lookup[key] = toolCallRetryResolution{conflict: true}
+	}
+}
+
+func cloneRetryPolicy(in *contract.RetryPolicySpec) *contract.RetryPolicySpec {
+	if in == nil {
+		return nil
+	}
+	out := *in
+	return &out
+}
+
+func retryPolicyFromSchemaValue(value any) *contract.RetryPolicySpec {
+	if value == nil {
+		return nil
+	}
+	data, err := json.Marshal(value)
+	if err != nil {
+		return nil
+	}
+	var policy contract.RetryPolicySpec
+	if err := json.Unmarshal(data, &policy); err != nil {
+		return nil
+	}
+	normalized, err := contract.NormalizeRetryPolicySpec(&policy, "<snapshot>")
+	if err != nil {
+		return nil
+	}
+	return normalized
+}
+
+// ResolveToolCallRetry resolves transport retry safety from an exact reviewed
+// MCP interface identity and actual RPC arguments. Missing or conflicting
+// interface mappings fail closed; no command, flag, or property name is inferred.
+func ResolveToolCallRetry(productID, rpcName string, arguments map[string]any) contract.RetryDecision {
+	_ = deliverySchemaCatalog()
+	panicIfMetaIndexUnusable(runtimeDeliverySchemaMetaIndexErr)
+	resolution, ok := toolCallRetryByInterface[retryInterfaceRefKey(productID, rpcName)]
+	if !ok {
+		return contract.RetryDecision{EffectiveIdempotency: "unknown", Reason: "interface_not_declared"}
+	}
+	if resolution.conflict {
+		return contract.RetryDecision{EffectiveIdempotency: "unknown", Reason: "interface_retry_policy_conflict"}
+	}
+	return contract.ResolveRetryDecision(resolution.idempotency, resolution.policy, arguments, resolution.argumentKey)
+}

internal/cli/runtime_schema.go

@@ -1057,6 +1057,7 @@ var schemaCompactPayloadKeys = map[string]bool{
 	"canonical_path": true, "cli_path": true,
 	"agent_summary": true, "description": true,
 	"effect": true, "risk": true, "confirmation": true, "idempotency": true,
+	"retry_policy":   true,
 	"interface_mode": true, "availability": true, "interface_reason": true,
 	"parameters": true, "constraints": true, "positionals": true, "dry_run": true,
 	"result": true, "pagination": true,

internal/cli/schema_catalog_structure.go

@@ -81,6 +81,7 @@ var schemaCatalogToolOptionalKeys = []string{
 	"pagination",
 	"positionals",
 	"result",
+	"retry_policy",
 }
 
 var schemaCatalogToolEnums = map[string][]string{
@@ -89,6 +90,7 @@ var schemaCatalogToolEnums = map[string][]string{
 	"confirmation":   {"not_required", "user_required"},
 	"interface_mode": {contract.InterfaceModeMCP, contract.InterfaceModeComposite, contract.InterfaceModeLocal},
 	"availability":   {contract.InterfaceAvailable, contract.InterfaceUnavailable},
+	"idempotency":    {"idempotent", "non_idempotent", "unknown", "conditional"},
 }
 
 // schemaCatalogParamRequiredKeys is the required core of every parameter.
@@ -239,6 +241,7 @@ func validateCatalogToolEntry(toolID string, entry map[string]any, violations *[
 	}
 
 	validateCatalogInterface(toolID, entry, violations)
+	validateCatalogRetryPolicy(toolID, entry, parameters, paramsOK, violations)
 	if result, exists := entry["result"]; exists {
 		if _, ok := result.(map[string]any); !ok {
 			report("field %q must be an object", "result")
@@ -280,6 +283,66 @@ func validateCatalogToolEntry(toolID string, entry map[string]any, violations *[
 	}
 }
 
+func validateCatalogRetryPolicy(toolID string, entry, parameters map[string]any, paramsOK bool, violations *[]schemaCatalogStructureViolation) {
+	report := func(format string, args ...any) {
+		*violations = append(*violations, schemaCatalogStructureViolation{tool: toolID, message: fmt.Sprintf(format, args...)})
+	}
+	idempotency, _ := entry["idempotency"].(string)
+	raw, hasPolicy := entry["retry_policy"]
+	if idempotency == "conditional" && !hasPolicy {
+		report("idempotency=conditional requires retry_policy")
+		return
+	}
+	if idempotency != "conditional" && hasPolicy {
+		report("retry_policy requires idempotency=conditional")
+	}
+	if !hasPolicy {
+		return
+	}
+	policy, ok := raw.(map[string]any)
+	if !ok {
+		report("retry_policy must be an object")
+		return
+	}
+	for key := range policy {
+		if key != "mode" && key != "key_parameter" && key != "same_payload_required" {
+			report("retry_policy has unknown field %q", key)
+		}
+	}
+	if mode, _ := policy["mode"].(string); mode != contract.RetryModeDeduplicationKey {
+		report("retry_policy.mode = %q, want %q", mode, contract.RetryModeDeduplicationKey)
+	}
+	keyParameter, _ := policy["key_parameter"].(string)
+	if strings.TrimSpace(keyParameter) == "" {
+		report("retry_policy.key_parameter must be a non-empty string")
+	} else if paramsOK {
+		rawParameter, exists := parameters[keyParameter]
+		parameter, parameterOK := rawParameter.(map[string]any)
+		if !exists || !parameterOK {
+			report("retry_policy.key_parameter references missing parameter %q", keyParameter)
+		} else {
+			if property, _ := parameter["property"].(string); strings.TrimSpace(property) == "" {
+				report("retry_policy key parameter %q must have a non-empty property", keyParameter)
+			}
+			if parameterType, _ := parameter["type"].(string); parameterType != "string" {
+				report("retry_policy key parameter %q must have type string", keyParameter)
+			}
+			fieldProvenance, _ := parameter["field_provenance"].(map[string]any)
+			propertyProvenance, _ := fieldProvenance["property"].(map[string]any)
+			if source, _ := propertyProvenance["source"].(string); source != "native_annotation" {
+				report("retry_policy key parameter %q property must come from an explicit ParamDecl", keyParameter)
+			}
+		}
+	}
+	if required, ok := policy["same_payload_required"].(bool); !ok || !required {
+		report("retry_policy.same_payload_required must be true")
+	}
+	mode, _ := entry["interface_mode"].(string)
+	if mode != contract.InterfaceModeMCP || entry["interface_ref"] == nil {
+		report("retry_policy requires interface_mode=mcp with interface_ref")
+	}
+}
+
 func validateCatalogInterface(toolID string, entry map[string]any, violations *[]schemaCatalogStructureViolation) {
 	report := func(format string, args ...any) {
 		*violations = append(*violations, schemaCatalogStructureViolation{

internal/cli/schema_catalog_structure_test.go

@@ -102,6 +102,63 @@ func TestValidateCatalogStructureAcceptsValidEntry(t *testing.T) {
 	}
 }
 
+func TestCrossPlatformCoverageValidateCatalogStructureConditionalRetryPolicy(t *testing.T) {
+	valid := func() map[string]any {
+		entry := validCatalogToolEntry()
+		entry["idempotency"] = "conditional"
+		parameter := entry["parameters"].(map[string]any)["base-id"].(map[string]any)
+		parameter["property"] = "baseId"
+		parameter["field_provenance"].(map[string]any)["property"] = map[string]any{"source": "native_annotation"}
+		entry["retry_policy"] = map[string]any{
+			"mode":                  contract.RetryModeDeduplicationKey,
+			"key_parameter":         "base-id",
+			"same_payload_required": true,
+		}
+		return entry
+	}
+	entry := valid()
+	if err := ValidateCatalogStructure(catalogPayload(t, entry)); err != nil {
+		t.Fatalf("ValidateCatalogStructure() error = %v", err)
+	}
+	for _, test := range []struct {
+		name   string
+		mutate func(map[string]any)
+		want   string
+	}{
+		{name: "missing policy", mutate: func(entry map[string]any) { delete(entry, "retry_policy") }, want: "requires retry_policy"},
+		{name: "policy on non conditional", mutate: func(entry map[string]any) { entry["idempotency"] = "unknown" }, want: "retry_policy requires idempotency=conditional"},
+		{name: "non object", mutate: func(entry map[string]any) { entry["retry_policy"] = "invalid" }, want: "retry_policy must be an object"},
+		{name: "unknown field", mutate: func(entry map[string]any) { entry["retry_policy"].(map[string]any)["inferred"] = true }, want: "unknown field"},
+		{name: "bad mode", mutate: func(entry map[string]any) { entry["retry_policy"].(map[string]any)["mode"] = "always" }, want: "retry_policy.mode"},
+		{name: "empty key", mutate: func(entry map[string]any) { entry["retry_policy"].(map[string]any)["key_parameter"] = " " }, want: "key_parameter must be a non-empty string"},
+		{name: "missing key parameter", mutate: func(entry map[string]any) { entry["retry_policy"].(map[string]any)["key_parameter"] = "uuid" }, want: "references missing parameter"},
+		{name: "missing property", mutate: func(entry map[string]any) {
+			delete(entry["parameters"].(map[string]any)["base-id"].(map[string]any), "property")
+		}, want: "non-empty property"},
+		{name: "non string key", mutate: func(entry map[string]any) {
+			entry["parameters"].(map[string]any)["base-id"].(map[string]any)["type"] = "integer"
+		}, want: "must have type string"},
+		{name: "inferred property", mutate: func(entry map[string]any) {
+			entry["parameters"].(map[string]any)["base-id"].(map[string]any)["field_provenance"].(map[string]any)["property"].(map[string]any)["source"] = "flag_name_inference"
+		}, want: "must come from an explicit ParamDecl"},
+		{name: "same payload false", mutate: func(entry map[string]any) { entry["retry_policy"].(map[string]any)["same_payload_required"] = false }, want: "same_payload_required must be true"},
+		{name: "non MCP", mutate: func(entry map[string]any) {
+			entry["interface_mode"] = contract.InterfaceModeLocal
+			delete(entry, "interface_ref")
+			entry["interface_reason"] = "local"
+		}, want: "requires interface_mode=mcp"},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			entry := valid()
+			test.mutate(entry)
+			err := ValidateCatalogStructure(catalogPayload(t, entry))
+			if err == nil || !strings.Contains(err.Error(), test.want) {
+				t.Fatalf("ValidateCatalogStructure() error = %v, want %q", err, test.want)
+			}
+		})
+	}
+}
+
 func TestValidateCatalogStructureAcceptsOptionalResultObject(t *testing.T) {
 	entry := validCatalogToolEntry()
 	entry["result"] = map[string]any{

internal/cli/schema_contract_model.go

@@ -62,6 +62,7 @@ type ToolSpec struct {
 	DryRun          *contract.DryRunSpec
 	Result          *contract.ResultSpec
 	Pagination      *contract.PaginationSpec
+	RetryPolicy     *contract.RetryPolicySpec
 	Safety          contract.SafetySpec
 	Interface       contract.InterfaceSpec
 	Selection       contract.SelectionSpec
@@ -137,6 +138,7 @@ type RuntimeToolSpecInput struct {
 	DryRun          *contract.DryRunSpec
 	Result          *contract.ResultSpec
 	Pagination      *contract.PaginationSpec
+	RetryPolicy     *contract.RetryPolicySpec
 	Safety          contract.SafetySpec
 	Interface       contract.InterfaceSpec
 	Selection       contract.SelectionSpec
@@ -224,6 +226,8 @@ func (t ToolSpec) provenanceValue(field string) (any, bool) {
 		return t.Safety.Confirmation, true
 	case "idempotency":
 		return t.Safety.Idempotency, true
+	case "retry_policy":
+		return t.RetryPolicy, true
 	case "interface_ref":
 		return t.Interface.Ref, true
 	case "interface_mode":
@@ -556,6 +560,42 @@ func (t ToolSpec) Validate() error {
 			return fmt.Errorf("tool %s pagination cursor_parameter %q is not a declared parameter", id.CanonicalPath, pagination.CursorParameter)
 		}
 	}
+	retryPolicy, err := contract.NormalizeRetryPolicySpec(t.RetryPolicy, id.CanonicalPath)
+	if err != nil {
+		return err
+	}
+	if t.Safety.Idempotency == "conditional" {
+		if retryPolicy == nil {
+			return fmt.Errorf("tool %s idempotency=conditional requires retry_policy", id.CanonicalPath)
+		}
+	} else if retryPolicy != nil {
+		return fmt.Errorf("tool %s retry_policy requires idempotency=conditional", id.CanonicalPath)
+	}
+	if retryPolicy != nil {
+		if t.Interface.Mode != contract.InterfaceModeMCP || t.Interface.Ref == nil {
+			return fmt.Errorf("tool %s retry_policy requires an MCP interface_ref", id.CanonicalPath)
+		}
+		var keyProperty, keyType string
+		var keyPropertyProvenance contract.FieldProvenance
+		for _, parameter := range t.Parameters {
+			if parameter.Name == retryPolicy.KeyParameter {
+				keyProperty = strings.TrimSpace(parameter.Property)
+				keyType = strings.TrimSpace(parameter.Type)
+				keyPropertyProvenance = parameter.FieldProvenance["property"]
+				break
+			}
+		}
+		if keyProperty == "" {
+			return fmt.Errorf("tool %s retry_policy key_parameter %q must name a declared parameter with a non-empty interface property", id.CanonicalPath, retryPolicy.KeyParameter)
+		}
+		if keyType != "string" {
+			return fmt.Errorf("tool %s retry_policy key_parameter %q must be a string parameter", id.CanonicalPath, retryPolicy.KeyParameter)
+		}
+		if strings.TrimSpace(keyPropertyProvenance.Source) != "native_annotation" ||
+			strings.TrimSpace(keyPropertyProvenance.Precedence) != "native_annotation" {
+			return fmt.Errorf("tool %s retry_policy key_parameter %q property must come from an explicit ParamDecl", id.CanonicalPath, retryPolicy.KeyParameter)
+		}
+	}
 	if t.Interface.Mode != "" || t.Interface.Availability != "" || t.Interface.Reason != "" || t.Interface.Ref != nil {
 		if err := t.Interface.Validate(id.CanonicalPath); err != nil {
 			return err
@@ -756,6 +796,12 @@ func (t ToolSpec) normalized() ToolSpec {
 			out.Pagination = pagination
 		}
 	}
+	if t.RetryPolicy != nil {
+		retryPolicy := *t.RetryPolicy
+		retryPolicy.Mode = strings.TrimSpace(retryPolicy.Mode)
+		retryPolicy.KeyParameter = strings.TrimSpace(retryPolicy.KeyParameter)
+		out.RetryPolicy = &retryPolicy
+	}
 	out.Positionals = append([]contract.RuntimeSchemaPositional(nil), t.Positionals...)
 	sort.Slice(out.Positionals, func(i, j int) bool {
 		if out.Positionals[i].Index != out.Positionals[j].Index {
@@ -990,6 +1036,10 @@ func (t ToolSpec) ToPayload() (map[string]any, error) {
 		value, _ := typedJSONValue(t.Pagination)
 		payload["pagination"] = value
 	}
+	if t.RetryPolicy != nil {
+		value, _ := typedJSONValue(t.RetryPolicy)
+		payload["retry_policy"] = value
+	}
 	applySafetyPayload(payload, t.Safety)
 	applyInterfacePayload(payload, t.Interface)
 	applySelectionPayload(payload, t.Selection, true)
@@ -1013,7 +1063,7 @@ func (t ToolSpec) ToSummaryPayload() (map[string]any, error) {
 	}
 	for _, key := range []string{
 		"parameters", "has_parameters", "parameter_count", "constraints",
-		"positionals", "result", "examples", "effect_source", "agent_source_refs",
+		"positionals", "result", "retry_policy", "examples", "effect_source", "agent_source_refs",
 		"field_provenance", "path", "source", "product_id", "display", "is_alias",
 	} {
 		delete(payload, key)

internal/cli/schema_meta_index.go

@@ -21,6 +21,8 @@ import (
 	"reflect"
 	"sort"
 	"strings"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract"
 )
 
 // SchemaMetaIndexVersion is the CommandMeta summary index format used by CI
@@ -42,19 +44,20 @@ type SchemaMetaIndexSnapshot struct {
 // SchemaMetaIndexEntry is one primary-path CommandMeta record. Aliases are
 // expanded into the ResolveMeta lookup at decode time.
 type SchemaMetaIndexEntry struct {
-	CLIPath      string   `json:"cli_path"`
-	Canonical    string   `json:"canonical_path"`
-	Aliases      []string `json:"aliases,omitempty"`
-	ProductID    string   `json:"product_id,omitempty"`
-	Title        string   `json:"title,omitempty"`
-	Effect       string   `json:"effect,omitempty"`
-	Risk         string   `json:"risk,omitempty"`
-	Confirmation string   `json:"confirmation,omitempty"`
-	Idempotency  string   `json:"idempotency,omitempty"`
-	AgentSummary string   `json:"agent_summary,omitempty"`
-	UseWhen      []string `json:"use_when,omitempty"`
-	AvoidWhen    []string `json:"avoid_when,omitempty"`
-	Examples     []string `json:"examples,omitempty"`
+	CLIPath      string                    `json:"cli_path"`
+	Canonical    string                    `json:"canonical_path"`
+	Aliases      []string                  `json:"aliases,omitempty"`
+	ProductID    string                    `json:"product_id,omitempty"`
+	Title        string                    `json:"title,omitempty"`
+	Effect       string                    `json:"effect,omitempty"`
+	Risk         string                    `json:"risk,omitempty"`
+	Confirmation string                    `json:"confirmation,omitempty"`
+	Idempotency  string                    `json:"idempotency,omitempty"`
+	RetryPolicy  *contract.RetryPolicySpec `json:"retry_policy,omitempty"`
+	AgentSummary string                    `json:"agent_summary,omitempty"`
+	UseWhen      []string                  `json:"use_when,omitempty"`
+	AvoidWhen    []string                  `json:"avoid_when,omitempty"`
+	Examples     []string                  `json:"examples,omitempty"`
 }
 
 // BuildSchemaMetaIndex extracts the ResolveMeta summary from a full Catalog
@@ -91,6 +94,7 @@ func BuildSchemaMetaIndex(snapshot SchemaCatalogSnapshot) (SchemaMetaIndexSnapsh
 			Risk:         schemaString(tool["risk"]),
 			Confirmation: schemaString(tool["confirmation"]),
 			Idempotency:  schemaString(tool["idempotency"]),
+			RetryPolicy:  retryPolicyFromSchemaValue(tool["retry_policy"]),
 			AgentSummary: schemaString(tool["agent_summary"]),
 			UseWhen:      schemaStringSlice(tool["use_when"]),
 			AvoidWhen:    schemaStringSlice(tool["avoid_when"]),
@@ -203,6 +207,7 @@ func commandMetaLookupFromIndex(index SchemaMetaIndexSnapshot) (map[string]Comma
 				Risk:         entry.Risk,
 				Confirmation: entry.Confirmation,
 				Idempotency:  entry.Idempotency,
+				RetryPolicy:  cloneRetryPolicy(entry.RetryPolicy),
 			},
 			Selection: CommandSelection{
 				AgentSummary: entry.AgentSummary,
@@ -294,7 +299,7 @@ func commandMetaEqual(got, want CommandMeta) error {
 		!metaStringSlicesEqual(got.Identity.Aliases, want.Identity.Aliases) {
 		return fmt.Errorf("identity mismatch: got %+v want %+v", got.Identity, want.Identity)
 	}
-	if got.Safety != want.Safety {
+	if !reflect.DeepEqual(got.Safety, want.Safety) {
 		return fmt.Errorf("safety mismatch: got %+v want %+v", got.Safety, want.Safety)
 	}
 	if got.Selection.AgentSummary != want.Selection.AgentSummary ||

internal/cli/schema_runtime_registry.go

@@ -294,6 +294,10 @@ func runtimeToolSpecFromContractFinal(entry runtimeSchemaEntry, final contract.C
 	} else if gate, ok := RuntimeContractGate(entry.Command); ok {
 		safety = applyContractGateToSafety(safety, gate)
 	}
+	retryPolicy, err := contract.NormalizeRetryPolicySpec(final.RetryPolicy, canonicalPath)
+	if err != nil {
+		return ToolSpec{}, err
+	}
 
 	positionals := final.Positionals
 	if len(positionals) == 0 {
@@ -333,7 +337,7 @@ func runtimeToolSpecFromContractFinal(entry runtimeSchemaEntry, final contract.C
 	// part of the public ToolSpec / Schema wire contract.
 	selection.ExampleDispositions = nil
 
-	provenance := contractFinalProvenance(identity, title, description, titleProv, descriptionProv, safety, interfaceSpec, selection, final.DryRun)
+	provenance := contractFinalProvenance(identity, title, description, titleProv, descriptionProv, safety, retryPolicy, interfaceSpec, selection, final.DryRun)
 
 	result, pagination := final.Result, final.Pagination
 	if !output.UsesUnifiedResult(entry.Command) {
@@ -356,6 +360,7 @@ func runtimeToolSpecFromContractFinal(entry runtimeSchemaEntry, final contract.C
 		DryRun:          final.DryRun,
 		Result:          result,
 		Pagination:      pagination,
+		RetryPolicy:     retryPolicy,
 		Safety:          safety,
 		Interface:       interfaceSpec,
 		Selection:       selection,
@@ -402,7 +407,7 @@ func contractFinalTextProvenance(declared, cobra string, preferCobra bool) (stri
 // dry_run when present), so declared leaves must emit the full set, not only
 // the fields they happened to author. Title/description provenance must match
 // the real text winner (cobra_help vs contract_final).
-func contractFinalProvenance(identity contract.ToolIdentitySpec, title, description string, titleProv, descriptionProv contract.FieldProvenance, safety contract.SafetySpec, iface contract.InterfaceSpec, selection contract.SelectionSpec, dryRun *contract.DryRunSpec) map[string]contract.FieldProvenance {
+func contractFinalProvenance(identity contract.ToolIdentitySpec, title, description string, titleProv, descriptionProv contract.FieldProvenance, safety contract.SafetySpec, retryPolicy *contract.RetryPolicySpec, iface contract.InterfaceSpec, selection contract.SelectionSpec, dryRun *contract.DryRunSpec) map[string]contract.FieldProvenance {
 	prov := func(value any, sourceRef string) contract.FieldProvenance {
 		return resolvedFieldProvenance(
 			value,
@@ -454,6 +459,9 @@ func contractFinalProvenance(identity contract.ToolIdentitySpec, title, descript
 	if dryRun != nil {
 		out["dry_run"] = prov(*dryRun, "corecmd.ContractDecl")
 	}
+	if retryPolicy != nil {
+		out["retry_policy"] = prov(*retryPolicy, "corecmd.ContractDecl")
+	}
 	return out
 }
 
@@ -693,6 +701,9 @@ func validateFinalSchemaProvenanceCoverage(registry SchemaRegistry) error {
 			if tool.DryRun != nil {
 				require("tool "+canonical, "dry_run", tool.FieldProvenance)
 			}
+			if tool.RetryPolicy != nil {
+				require("tool "+canonical, "retry_policy", tool.FieldProvenance)
+			}
 			// interface_reason is part of the final interface contract only when
 			// the disposition requires or actually delivers a reason. An MCP or
 			// local available command with no reason has no resolver winner to

internal/cli/schema_snapshot_adapter.go

@@ -67,6 +67,7 @@ type schemaToolWire struct {
 	DryRun              *contract.DryRunSpec                `json:"dry_run"`
 	Result              *contract.ResultSpec                `json:"result"`
 	Pagination          *contract.PaginationSpec            `json:"pagination"`
+	RetryPolicy         *contract.RetryPolicySpec           `json:"retry_policy"`
 	Effect              string                              `json:"effect"`
 	EffectSource        string                              `json:"effect_source"`
 	Risk                string                              `json:"risk"`
@@ -271,6 +272,7 @@ func schemaToolSpecFromWire(wire schemaToolWire) (ToolSpec, error) {
 		DryRun:         wire.DryRun,
 		Result:         wire.Result,
 		Pagination:     wire.Pagination,
+		RetryPolicy:    wire.RetryPolicy,
 		Safety: contract.SafetySpec{
 			Effect:       wire.Effect,
 			EffectSource: wire.EffectSource,

internal/cli/schema_source_root.go

@@ -77,6 +77,7 @@ func resetDeliverySchemaCatalogState() {
 func resetSchemaDeliveryState() {
 	metaByCLIPathOnce = sync.Once{}
 	metaByCLIPath = nil
+	toolCallRetryByInterface = nil
 	runtimeDeliverySchemaMetaIndexErr = nil
 	runtimeDeliverySchemaMetaIndexLazyCount.Store(0)
 	resetDeliverySchemaCatalogState()

internal/corecmd/contract/final.go

@@ -32,6 +32,7 @@ type ContractFinalPayload struct {
 	DryRun      *DryRunSpec
 	Result      *ResultSpec
 	Pagination  *PaginationSpec
+	RetryPolicy *RetryPolicySpec
 	Interface   *InterfaceSpec
 	Selection   *SelectionSpec
 	Identity    *ToolIdentitySpec

internal/corecmd/contract/retry_policy.go

@@ -0,0 +1,93 @@
+// 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 contract
+
+import (
+	"fmt"
+	"strings"
+)
+
+const RetryModeDeduplicationKey = "deduplication_key"
+
+// RetryPolicySpec declares the reviewed condition that makes an otherwise
+// non-idempotent operation safe to retry. KeyParameter names the CLI parameter;
+// Schema assembly binds it to one explicit interface property before runtime.
+// No flag-name or request-property inference is permitted.
+type RetryPolicySpec struct {
+	Mode                string `json:"mode"`
+	KeyParameter        string `json:"key_parameter"`
+	SamePayloadRequired bool   `json:"same_payload_required"`
+}
+
+// RetryDecision is the invocation-scoped safety result consumed by Agent and
+// transport code. Static metadata remains unchanged; EffectiveIdempotency is
+// derived only from the reviewed policy and the actual invocation arguments.
+type RetryDecision struct {
+	EffectiveIdempotency string `json:"effective_idempotency"`
+	SafeToRetry          bool   `json:"safe_to_retry"`
+	Reason               string `json:"reason"`
+}
+
+// NormalizeRetryPolicySpec validates and defensively copies a retry policy.
+func NormalizeRetryPolicySpec(in *RetryPolicySpec, canonical string) (*RetryPolicySpec, error) {
+	if in == nil {
+		return nil, nil
+	}
+	canonical = defaultString(strings.TrimSpace(canonical), "<unknown>")
+	out := &RetryPolicySpec{
+		Mode:                strings.TrimSpace(in.Mode),
+		KeyParameter:        strings.TrimSpace(in.KeyParameter),
+		SamePayloadRequired: in.SamePayloadRequired,
+	}
+	if out.Mode != RetryModeDeduplicationKey {
+		return nil, fmt.Errorf("schema tool %s retry_policy has unsupported mode %q", canonical, out.Mode)
+	}
+	if out.KeyParameter == "" {
+		return nil, fmt.Errorf("schema tool %s retry_policy has no key_parameter", canonical)
+	}
+	if !out.SamePayloadRequired {
+		return nil, fmt.Errorf("schema tool %s retry_policy must require the same payload", canonical)
+	}
+	return out, nil
+}
+
+// ResolveRetryDecision derives invocation safety without mutating the static
+// command contract. argumentKey is the CLI parameter name for Agent calls or
+// the explicitly declared interface property for transport calls.
+func ResolveRetryDecision(idempotency string, policy *RetryPolicySpec, arguments map[string]any, argumentKey string) RetryDecision {
+	switch strings.TrimSpace(idempotency) {
+	case "idempotent":
+		return RetryDecision{EffectiveIdempotency: "idempotent", SafeToRetry: true, Reason: "static_idempotent"}
+	case "non_idempotent":
+		return RetryDecision{EffectiveIdempotency: "non_idempotent", Reason: "static_non_idempotent"}
+	case "unknown":
+		return RetryDecision{EffectiveIdempotency: "unknown", Reason: "idempotency_unknown"}
+	case "conditional":
+		normalized, err := NormalizeRetryPolicySpec(policy, "<invocation>")
+		if err != nil || normalized == nil {
+			return RetryDecision{EffectiveIdempotency: "unknown", Reason: "invalid_retry_policy"}
+		}
+		argumentKey = strings.TrimSpace(argumentKey)
+		if argumentKey == "" {
+			return RetryDecision{EffectiveIdempotency: "unknown", Reason: "deduplication_key_binding_missing"}
+		}
+		value, ok := arguments[argumentKey].(string)
+		if !ok || strings.TrimSpace(value) == "" {
+			return RetryDecision{EffectiveIdempotency: "non_idempotent", Reason: "deduplication_key_missing"}
+		}
+		return RetryDecision{EffectiveIdempotency: "idempotent", SafeToRetry: true, Reason: "deduplication_key_present"}
+	default:
+		return RetryDecision{EffectiveIdempotency: "unknown", Reason: "idempotency_unknown"}
+	}
+}

internal/corecmd/contract/retry_policy_test.go

@@ -0,0 +1,79 @@
+// 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 contract
+
+import "testing"
+
+func TestCrossPlatformCoverageNormalizeRetryPolicySpec(t *testing.T) {
+	if got, err := NormalizeRetryPolicySpec(nil, "chat.send"); err != nil || got != nil {
+		t.Fatalf("nil NormalizeRetryPolicySpec() = %#v, %v", got, err)
+	}
+	got, err := NormalizeRetryPolicySpec(&RetryPolicySpec{
+		Mode:                " deduplication_key ",
+		KeyParameter:        " uuid ",
+		SamePayloadRequired: true,
+	}, "chat.send")
+	if err != nil {
+		t.Fatalf("NormalizeRetryPolicySpec() error = %v", err)
+	}
+	if got.Mode != RetryModeDeduplicationKey || got.KeyParameter != "uuid" || !got.SamePayloadRequired {
+		t.Fatalf("NormalizeRetryPolicySpec() = %#v", got)
+	}
+	if _, err := NormalizeRetryPolicySpec(&RetryPolicySpec{Mode: RetryModeDeduplicationKey, SamePayloadRequired: true}, "chat.send"); err == nil {
+		t.Fatal("empty key_parameter must fail closed")
+	}
+	if _, err := NormalizeRetryPolicySpec(&RetryPolicySpec{Mode: RetryModeDeduplicationKey, KeyParameter: "uuid"}, "chat.send"); err == nil {
+		t.Fatal("same_payload_required=false must fail closed")
+	}
+	if _, err := NormalizeRetryPolicySpec(&RetryPolicySpec{Mode: "inferred", KeyParameter: "uuid", SamePayloadRequired: true}, "chat.send"); err == nil {
+		t.Fatal("unsupported retry mode must fail closed")
+	}
+}
+
+func TestCrossPlatformCoverageResolveRetryDecision(t *testing.T) {
+	policy := &RetryPolicySpec{Mode: RetryModeDeduplicationKey, KeyParameter: "uuid", SamePayloadRequired: true}
+	if got := ResolveRetryDecision("conditional", policy, map[string]any{"uuid": "request-1"}, "uuid"); !got.SafeToRetry || got.EffectiveIdempotency != "idempotent" {
+		t.Fatalf("conditional with key = %#v", got)
+	}
+	for name, args := range map[string]map[string]any{
+		"missing":    {},
+		"empty":      {"uuid": "  "},
+		"non-string": {"uuid": 123},
+	} {
+		t.Run(name, func(t *testing.T) {
+			got := ResolveRetryDecision("conditional", policy, args, "uuid")
+			if got.SafeToRetry || got.EffectiveIdempotency != "non_idempotent" {
+				t.Fatalf("decision = %#v", got)
+			}
+		})
+	}
+	if got := ResolveRetryDecision("idempotent", nil, nil, ""); !got.SafeToRetry || got.EffectiveIdempotency != "idempotent" {
+		t.Fatalf("static idempotent = %#v", got)
+	}
+	if got := ResolveRetryDecision("non_idempotent", nil, nil, ""); got.SafeToRetry || got.EffectiveIdempotency != "non_idempotent" {
+		t.Fatalf("static non-idempotent = %#v", got)
+	}
+	if got := ResolveRetryDecision("unknown", nil, nil, ""); got.SafeToRetry || got.EffectiveIdempotency != "unknown" {
+		t.Fatalf("unknown = %#v", got)
+	}
+	if got := ResolveRetryDecision("conditional", policy, map[string]any{"uuid": "request-1"}, ""); got.SafeToRetry || got.EffectiveIdempotency != "unknown" || got.Reason != "deduplication_key_binding_missing" {
+		t.Fatalf("missing key binding = %#v", got)
+	}
+	if got := ResolveRetryDecision("conditional", nil, nil, ""); got.SafeToRetry || got.Reason != "invalid_retry_policy" {
+		t.Fatalf("invalid conditional policy = %#v", got)
+	}
+	if got := ResolveRetryDecision("retryable", nil, nil, ""); got.SafeToRetry || got.EffectiveIdempotency != "unknown" {
+		t.Fatalf("unknown legacy value = %#v", got)
+	}
+}

internal/corecmd/contract_decl.go

@@ -44,12 +44,14 @@ type ContractDecl struct {
 	DryRun      *contract.DryRunSpec
 	Result      *contract.ResultSpec
 	Pagination  *contract.PaginationSpec
+	RetryPolicy *contract.RetryPolicySpec
 	Interface   *contract.InterfaceSpec
 	Selection   contract.SelectionSpec
 	Identity    contract.ToolIdentitySpec
 }
 
-// validateContractDecl enforces authoring-time homology for declared commands.
+// validateContractDecl enforces authoring-time homology for declared commands
+// and returns the normalized retry policy for the ContractFinal projection.
 // A declared Contract is the sole final source for its fields: downstream
 // catalog/Agent gates hard-require description and the selection prose for
 // every effective tool — so a declaration missing any of these fields could
@@ -61,9 +63,34 @@ type ContractDecl struct {
 // self-description: identity is collected from ContractFinal on the live
 // leaves, so an incomplete or inconsistent declared Identity fails collection,
 // binding, and policy downstream.
-func validateContractDecl(spec Spec) {
+func validateContractDecl(spec Spec) *contract.RetryPolicySpec {
+	idempotency := strings.TrimSpace(spec.Safety.Idempotency)
+	if idempotency == "conditional" && spec.Contract.RetryPolicy == nil {
+		panic(fmt.Sprintf("command %q Safety.Idempotency=conditional requires Contract.RetryPolicy", spec.Use))
+	}
+	if spec.Contract.RetryPolicy != nil && idempotency != "conditional" {
+		panic(fmt.Sprintf("command %q Contract.RetryPolicy requires Safety.Idempotency=conditional", spec.Use))
+	}
+	retryPolicy, err := contract.NormalizeRetryPolicySpec(spec.Contract.RetryPolicy, spec.Contract.Identity.CanonicalPath)
+	if err != nil {
+		panic(fmt.Sprintf("command %q has invalid Contract.RetryPolicy: %v", spec.Use, err))
+	}
+	if retryPolicy != nil {
+		declared := false
+		for _, parameter := range spec.Contract.Parameters {
+			if strings.TrimSpace(parameter.Name) == retryPolicy.KeyParameter && strings.TrimSpace(parameter.Property) != "" {
+				declared = true
+				break
+			}
+		}
+		if !declared {
+			panic(fmt.Sprintf(
+				"command %q Contract.RetryPolicy key_parameter %q requires Contract.Parameters with an explicit ParamDecl.Property",
+				spec.Use, retryPolicy.KeyParameter))
+		}
+	}
 	if spec.Contract.empty() {
-		return
+		return retryPolicy
 	}
 	missing := make([]string, 0, 8)
 	if strings.TrimSpace(spec.Contract.Description) == "" {
@@ -125,6 +152,7 @@ func validateContractDecl(spec Spec) {
 			"command %q Contract.Identity.CLIPath %q and PrimaryCLIPath %q must agree on the primary leaf path",
 			spec.Use, cliPath, primary))
 	}
+	return retryPolicy
 }
 
 // Empty reports whether no ContractDecl field was authored.
@@ -152,6 +180,9 @@ func (s ContractDecl) empty() bool {
 	if s.Pagination != nil {
 		return false
 	}
+	if s.RetryPolicy != nil {
+		return false
+	}
 	if s.Interface != nil {
 		iface := s.Interface
 		if strings.TrimSpace(iface.Mode) != "" || strings.TrimSpace(iface.Availability) != "" ||

internal/corecmd/contract_decl_test.go

@@ -14,6 +14,7 @@
 package corecmd
 
 import (
+	"fmt"
 	"strings"
 	"testing"
 
@@ -21,6 +22,43 @@ import (
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contractfinal"
 )
 
+func TestCrossPlatformCoverageContractRetryPolicyFailsFast(t *testing.T) {
+	if (ContractDecl{RetryPolicy: &contract.RetryPolicySpec{}}).Empty() {
+		t.Fatal("RetryPolicy-only ContractDecl must not be empty")
+	}
+	assertPanic := func(name, want string, spec Spec) {
+		t.Helper()
+		t.Run(name, func(t *testing.T) {
+			defer func() {
+				recovered := recover()
+				if recovered == nil || !strings.Contains(fmt.Sprint(recovered), want) {
+					t.Fatalf("panic = %v, want %q", recovered, want)
+				}
+			}()
+			validateContractDecl(spec)
+		})
+	}
+	assertPanic("conditional without contract", "requires Contract.RetryPolicy", Spec{
+		Use: "send", Safety: contract.SafetySpec{Idempotency: "conditional"},
+	})
+	minimal := ContractDecl{Description: "description"}
+	assertPanic("conditional without policy", "requires Contract.RetryPolicy", Spec{
+		Use: "send", Safety: contract.SafetySpec{Idempotency: "conditional"}, Contract: minimal,
+	})
+	minimal.RetryPolicy = &contract.RetryPolicySpec{Mode: contract.RetryModeDeduplicationKey, KeyParameter: "uuid", SamePayloadRequired: true}
+	assertPanic("policy without explicit ParamDecl property", "requires Contract.Parameters with an explicit ParamDecl.Property", Spec{
+		Use: "send", Safety: contract.SafetySpec{Idempotency: "conditional"}, Contract: minimal,
+	})
+	minimal.Parameters = []contract.ParamDecl{{Name: "uuid", Property: "requestUuid"}}
+	assertPanic("policy without conditional", "requires Safety.Idempotency=conditional", Spec{
+		Use: "send", Safety: contract.SafetySpec{Idempotency: "unknown"}, Contract: minimal,
+	})
+	minimal.RetryPolicy.SamePayloadRequired = false
+	assertPanic("invalid policy", "invalid Contract.RetryPolicy", Spec{
+		Use: "send", Safety: contract.SafetySpec{Idempotency: "conditional"}, Contract: minimal,
+	})
+}
+
 func TestCrossPlatformCoverageNewCommandEmbedsFullContractDeclAsFinalSource(t *testing.T) {
 	cmd := New(Spec{
 		Use:   "create",
@@ -35,11 +73,12 @@ func TestCrossPlatformCoverageNewCommandEmbedsFullContractDeclAsFinalSource(t *t
 		},
 		Safety: contract.SafetySpec{
 			Effect: "write", Risk: "medium",
-			Confirmation: "user_required", Idempotency: "retryable",
+			Confirmation: "user_required", Idempotency: "conditional",
 		},
 		Contract: ContractDecl{
 			Title:       "Create Title",
 			Description: "Create Desc",
+			Parameters:  []contract.ParamDecl{{Name: "mode", Property: "mode"}},
 			Positionals: []contract.RuntimeSchemaPositional{{Name: "id", Required: true, Index: 0}},
 			DryRun:      &contract.DryRunSpec{PreviewKind: "invocation", RemoteReads: true},
 			Result: &contract.ResultSpec{
@@ -47,6 +86,11 @@ func TestCrossPlatformCoverageNewCommandEmbedsFullContractDeclAsFinalSource(t *t
 				DataSchema: []byte(`{"type":"object"}`),
 			},
 			Pagination: &contract.PaginationSpec{Kind: contract.PaginationKindCursor, CursorParameter: "cursor"},
+			RetryPolicy: &contract.RetryPolicySpec{
+				Mode:                contract.RetryModeDeduplicationKey,
+				KeyParameter:        "mode",
+				SamePayloadRequired: true,
+			},
 			Interface: &contract.InterfaceSpec{
 				Mode:         "mcp",
 				Availability: "available",
@@ -78,7 +122,7 @@ func TestCrossPlatformCoverageNewCommandEmbedsFullContractDeclAsFinalSource(t *t
 	if final.Title != "Create Title" || final.Description != "Create Desc" {
 		t.Fatalf("title/desc = %q %q (payload stores declared Contract text; Catalog may prefer Cobra Long)", final.Title, final.Description)
 	}
-	if final.Safety == nil || final.Safety.Confirmation != "user_required" || final.Safety.Idempotency != "retryable" {
+	if final.Safety == nil || final.Safety.Confirmation != "user_required" || final.Safety.Idempotency != "conditional" {
 		t.Fatalf("safety = %#v", final.Safety)
 	}
 	if final.DryRun == nil || final.DryRun.PreviewKind != "invocation" || !final.DryRun.RemoteReads {
@@ -90,6 +134,14 @@ func TestCrossPlatformCoverageNewCommandEmbedsFullContractDeclAsFinalSource(t *t
 	if final.Pagination == nil || final.Pagination.CursorParameter != "cursor" || final.Pagination.MetaPath != contract.PaginationMetaPath {
 		t.Fatalf("pagination = %#v", final.Pagination)
 	}
+	if final.RetryPolicy == nil || final.RetryPolicy.KeyParameter != "mode" || !final.RetryPolicy.SamePayloadRequired {
+		t.Fatalf("retry_policy = %#v", final.RetryPolicy)
+	}
+	final.RetryPolicy.KeyParameter = "mutated"
+	again, ok := contractfinal.RuntimeContractFinal(cmd)
+	if !ok || again.RetryPolicy == nil || again.RetryPolicy.KeyParameter != "mode" {
+		t.Fatalf("stored retry_policy was not defensively copied: %#v", again.RetryPolicy)
+	}
 	if final.Interface == nil || final.Interface.Mode != "mcp" || final.Interface.Ref == nil || final.Interface.Ref.RPCName != "create_thing" {
 		t.Fatalf("interface = %#v", final.Interface)
 	}

internal/corecmd/contractfinal/store.go

@@ -85,6 +85,10 @@ func cloneContractFinalPayload(in contract.ContractFinalPayload) contract.Contra
 		value := *in.Pagination
 		out.Pagination = &value
 	}
+	if in.RetryPolicy != nil {
+		value := *in.RetryPolicy
+		out.RetryPolicy = &value
+	}
 	if in.Interface != nil {
 		value := *in.Interface
 		if in.Interface.Ref != nil {

internal/corecmd/corecmd.go

@@ -1364,7 +1364,7 @@ func AttachContract(cmd *cobra.Command, safety contract.SafetySpec, decl Contrac
 	_, _ = short, long
 	// Reuse NewCommand's completeness rules so bind-time attaches cannot ship
 	// a partial declaration that would only fail in generated artifacts.
-	validateContractDecl(Spec{Use: cmd.Name(), Safety: safety, Contract: decl})
+	retryPolicy := validateContractDecl(Spec{Use: cmd.Name(), Safety: safety, Contract: decl})
 	validateSafetySpec(Spec{Use: cmd.Name(), Safety: safety})
 
 	payload := contract.ContractFinalPayload{
@@ -1394,6 +1394,9 @@ func AttachContract(cmd *cobra.Command, safety contract.SafetySpec, decl Contrac
 		}
 		payload.Pagination = pagination
 	}
+	if retryPolicy != nil {
+		payload.RetryPolicy = retryPolicy
+	}
 	if decl.Interface != nil {
 		iface := &contract.InterfaceSpec{
 			Mode:         strings.TrimSpace(decl.Interface.Mode),

internal/executor/invocation.go

@@ -19,19 +19,21 @@ import (
 	"fmt"
 	"strings"
 
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract"
 	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
 )
 
 type Invocation struct {
-	Kind             string         `json:"kind"`
-	Stage            string         `json:"stage"`
-	Implemented      bool           `json:"implemented"`
-	DryRun           bool           `json:"dry_run,omitempty"`
-	CanonicalProduct string         `json:"canonical_product"`
-	Tool             string         `json:"tool"`
-	CanonicalPath    string         `json:"canonical_path"`
-	LegacyPath       string         `json:"legacy_path,omitempty"`
-	Params           map[string]any `json:"params"`
+	Kind             string                  `json:"kind"`
+	Stage            string                  `json:"stage"`
+	Implemented      bool                    `json:"implemented"`
+	DryRun           bool                    `json:"dry_run,omitempty"`
+	CanonicalProduct string                  `json:"canonical_product"`
+	Tool             string                  `json:"tool"`
+	CanonicalPath    string                  `json:"canonical_path"`
+	LegacyPath       string                  `json:"legacy_path,omitempty"`
+	Params           map[string]any          `json:"params"`
+	Retry            *contract.RetryDecision `json:"retry,omitempty"`
 }
 
 type Result struct {
@@ -47,13 +49,17 @@ type EchoRunner struct{}
 
 func (EchoRunner) Run(_ context.Context, invocation Invocation) (Result, error) {
 	if invocation.DryRun {
+		response := map[string]any{
+			"dry_run": true,
+			"request": ToolCallRequest(invocation.Tool, invocation.Params),
+			"note":    "execution skipped by --dry-run",
+		}
+		if invocation.Retry != nil {
+			response["retry"] = invocation.Retry
+		}
 		return Result{
 			Invocation: invocation,
-			Response: map[string]any{
-				"dry_run": true,
-				"request": ToolCallRequest(invocation.Tool, invocation.Params),
-				"note":    "execution skipped by --dry-run",
-			},
+			Response:   response,
 		}, nil
 	}
 	return Result{Invocation: invocation}, nil

internal/executor/invocation_test.go

@@ -4,19 +4,21 @@ import (
 	"context"
 	"reflect"
 	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract"
 )
 
 func TestCrossPlatformCoverageInvocationBuildersAndEchoRunner(t *testing.T) {
 	params := map[string]any{"name": "value"}
 	compat := NewCompatibilityInvocation("old path", "doc", "read", params)
-	if compat.Kind != "compat_invocation" || compat.CanonicalPath != "doc.read" || !reflect.DeepEqual(compat.Params, params) {
+	if compat.Kind != "compat_invocation" || compat.CanonicalPath != "doc.read" || compat.Retry != nil || !reflect.DeepEqual(compat.Params, params) {
 		t.Fatalf("unexpected compatibility invocation: %#v", compat)
 	}
 	if got := NewCompatibilityInvocation("old", "doc", "read", nil).Params; got == nil {
 		t.Fatal("nil compatibility params were not normalized")
 	}
 	help := NewHelperInvocation("old path", "chat", "send", params)
-	if help.Kind != "helper_invocation" || help.Stage != "helper_override" {
+	if help.Kind != "helper_invocation" || help.Stage != "helper_override" || help.Retry != nil {
 		t.Fatalf("unexpected helper invocation: %#v", help)
 	}
 	if got := NewHelperInvocation("old", "chat", "send", nil).Params; got == nil {
@@ -29,8 +31,10 @@ func TestCrossPlatformCoverageInvocationBuildersAndEchoRunner(t *testing.T) {
 		t.Fatalf("EchoRunner normal result = %#v, %v", result, err)
 	}
 	compat.DryRun = true
+	retry := contract.RetryDecision{EffectiveIdempotency: "idempotent", SafeToRetry: true, Reason: "static_idempotent"}
+	compat.Retry = &retry
 	result, err = runner.Run(context.Background(), compat)
-	if err != nil || result.Response["dry_run"] != true {
+	if err != nil || result.Response["dry_run"] != true || result.Response["retry"] != &retry {
 		t.Fatalf("EchoRunner dry-run result = %#v, %v", result, err)
 	}
 }

internal/helpers/chat.go

@@ -2799,6 +2799,8 @@ func newChatCommand() *cobra.Command {
 
 纯文本 / Markdown 消息（默认）：
   无需指定 --msg-type，直接传消息内容即可。推荐使用 --text flag 传递内容（尤其当内容含换行、引号等特殊字符时），也支持位置参数。可选 --title 作为消息标题。
+  图文混排时，公网图片 URL 需要写成 Markdown 图片语法：![图片标题](https://example.com/image.png)，才会以内联图片展示。
+  如果省略开头的 !，例如 [图片标题](https://example.com/image.png)，将按链接/URL 展示，不会渲染为图片。
 
 返回值与后续操作：
   发送后会返回 openTaskId。如需编辑或撤回刚发送的消息，使用
@@ -2816,6 +2818,8 @@ func newChatCommand() *cobra.Command {
   dws chat message send --user <userId> "请查收"
   dws chat message send --open-dingtalk-id <openDingTalkId> "请查收"
   dws chat message send --group <openconversation_id> --title "周报提醒" "请大家本周五前提交周报"
+  # 图文混排 Markdown：公网图片 URL 需要写成 ![图片标题](URL) 才会以内联图片展示
+  dws chat message send --group <openconversation_id> --text $'这是图文说明\n\n![这个是展示图片标题](https://down.dingtalk.com/media/lQLPM5jiBEiBNjswMLAKd_CTzm8eowpEWPT_7-cA_48_48.png)'
   # 发送本地图片或文件（图片会作为可下载的 file 附件发送）
   dws chat message send --group <openconversation_id> --msg-type file --file-path ./screenshot.png
   dws chat message send --group <openconversation_id> --msg-type file --file-path ./report.pdf

internal/helpers/drive.go

@@ -281,6 +281,85 @@ func parseDriveUploadInfo(text string) (resourceURL, uploadID string, headers ma
 	return
 }
 
+// DriveUploadRequest describes the reusable Drive upload transaction used by
+// the native leaf and the curated +upload shortcut. FilePath must already be
+// resolved and validated by the caller.
+type DriveUploadRequest struct {
+	FilePath      string
+	FileName      string
+	FileSize      int64
+	SpaceID       string
+	ParentID      string
+	OverwriteFile string
+	MIMEType      string
+}
+
+// UploadDriveFileData runs credentials -> OSS PUT -> commit exactly once and
+// returns the parsed commit response without rendering it. Unlike the legacy
+// leaf helper, this path fails when the commit has no non-empty JSON response;
+// the Shortcut can then require terminal success evidence and read back the
+// created node before reporting success.
+func UploadDriveFileData(ctx context.Context, request DriveUploadRequest) (map[string]any, error) {
+	if strings.TrimSpace(request.FilePath) == "" || strings.TrimSpace(request.FileName) == "" || request.FileSize <= 0 {
+		return nil, fmt.Errorf("invalid drive upload request")
+	}
+	step1Args := map[string]any{
+		"fileName": request.FileName,
+		"fileSize": float64(request.FileSize),
+	}
+	if request.SpaceID != "" {
+		step1Args["spaceId"] = request.SpaceID
+	}
+	if request.MIMEType != "" {
+		step1Args["mimeType"] = request.MIMEType
+	}
+	if request.OverwriteFile != "" {
+		step1Args["overwriteFileId"] = request.OverwriteFile
+	} else if request.ParentID != "" {
+		step1Args["parentId"] = request.ParentID
+	}
+
+	credentialText, err := callMCPToolReturnTextOnServer(ctx, "drive", "get_upload_info", step1Args)
+	if err != nil {
+		return nil, err
+	}
+	uploadID, err := driveUploadPut(ctx, credentialText, func(refreshCtx context.Context) (string, error) {
+		return callMCPToolReturnTextOnServer(refreshCtx, "drive", "get_upload_info", step1Args)
+	}, request.FilePath, request.FileSize)
+	if err != nil {
+		return nil, err
+	}
+
+	commitArgs := map[string]any{
+		"fileName": request.FileName,
+		"fileSize": float64(request.FileSize),
+		"uploadId": uploadID,
+	}
+	if request.SpaceID != "" {
+		commitArgs["spaceId"] = request.SpaceID
+	}
+	if request.OverwriteFile != "" {
+		commitArgs["overwriteFileId"] = request.OverwriteFile
+	} else if request.ParentID != "" {
+		commitArgs["parentId"] = request.ParentID
+	}
+	commitText, err := callMCPToolReturnTextOnServer(ctx, "drive", "commit_upload", commitArgs)
+	if err != nil {
+		return nil, err
+	}
+	if strings.TrimSpace(commitText) == "" {
+		return nil, 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 nil, fmt.Errorf("parse commit_upload response: %w", err)
+	}
+	if len(result) == 0 {
+		return nil, fmt.Errorf("commit_upload returned an empty JSON object; remote effect is unknown")
+	}
+	return result, nil
+}
+
 func newDriveCommand() *cobra.Command {
 	// Product-level Agent routing Decl (migrated from selection/drive.json
 	// products.drive). Catalog assembly stamps provenance contract_final.
@@ -3204,6 +3283,7 @@ func newDriveCommand() *cobra.Command {
 		driveListCmd,
 		driveListSpacesCmd,
 		driveInfoCmd,
+		newDriveFileCommentCmd(),
 		driveDownloadCmd,
 		driveDownloadVersionCmd,
 		driveMkdirCmd,

internal/helpers/drive_coverage_more_test.go

@@ -154,6 +154,88 @@ func TestCrossPlatformCoverageDriveUploadTransportCoverage(t *testing.T) {
 	})
 }
 
+func TestCrossPlatformCoverageUploadDriveFileDataStrictTransaction(t *testing.T) {
+	credential := `{"result":{"uploadType":"httpToCenterWithToken","resourceUrl":"https://c.example.com/u?upload_key=u1","uploadId":"u1","headers":{"dentry-token":"token"}}}`
+	request := DriveUploadRequest{FilePath: "fixture.bin", FileName: "fixture.bin", FileSize: 7, SpaceID: "space", ParentID: "folder", MIMEType: "application/octet-stream"}
+
+	t.Run("success with parent", func(t *testing.T) {
+		caller := &scriptedToolCaller{steps: []scriptedToolStep{{text: credential}, {text: `{"success":true,"result":{"fileId":"n1"}}`}}}
+		installScriptedCaller(t, caller)
+		SetHTTPPutFile(func(context.Context, string, map[string]string, string, int64) error { return nil })
+		t.Cleanup(func() { SetHTTPPutFile(nil) })
+		result, err := UploadDriveFileData(context.Background(), request)
+		if err != nil || result["success"] != true || caller.calls != 2 {
+			t.Fatalf("result=%v calls=%d error=%v", result, caller.calls, err)
+		}
+		if caller.args["spaceId"] != "space" || caller.args["parentId"] != "folder" {
+			t.Fatalf("commit args=%v", caller.args)
+		}
+	})
+
+	t.Run("success with overwrite", func(t *testing.T) {
+		caller := &scriptedToolCaller{steps: []scriptedToolStep{{text: credential}, {text: `{"success":true}`}}}
+		installScriptedCaller(t, caller)
+		SetHTTPPutFile(func(context.Context, string, map[string]string, string, int64) error { return nil })
+		t.Cleanup(func() { SetHTTPPutFile(nil) })
+		overwrite := request
+		overwrite.ParentID = "ignored"
+		overwrite.OverwriteFile = "existing"
+		if _, err := UploadDriveFileData(context.Background(), overwrite); err != nil {
+			t.Fatal(err)
+		}
+		if caller.args["overwriteFileId"] != "existing" {
+			t.Fatalf("commit args=%v", caller.args)
+		}
+	})
+
+	t.Run("credential refresh callback", func(t *testing.T) {
+		caller := &scriptedToolCaller{steps: []scriptedToolStep{{text: credential}, {text: credential}, {text: `{"success":true}`}}}
+		installScriptedCaller(t, caller)
+		putCalls := 0
+		SetHTTPPutFile(func(context.Context, string, map[string]string, string, int64) error {
+			putCalls++
+			if putCalls == 1 {
+				return &httpStatusError{StatusCode: 401, Body: "expired"}
+			}
+			return nil
+		})
+		t.Cleanup(func() { SetHTTPPutFile(nil) })
+		if _, err := UploadDriveFileData(context.Background(), request); err != nil {
+			t.Fatal(err)
+		}
+		if caller.calls != 3 || putCalls != 2 {
+			t.Fatalf("caller calls=%d put calls=%d", caller.calls, putCalls)
+		}
+	})
+
+	for _, tc := range []struct {
+		name    string
+		request DriveUploadRequest
+		steps   []scriptedToolStep
+		putErr  error
+		want    string
+	}{
+		{name: "invalid request", request: DriveUploadRequest{}, want: "invalid drive upload request"},
+		{name: "credential failure", request: request, steps: []scriptedToolStep{{err: errors.New("credentials")}}, want: "credentials"},
+		{name: "put failure", request: request, steps: []scriptedToolStep{{text: credential}}, putErr: errors.New("put failed"), want: "put failed"},
+		{name: "commit failure", request: request, steps: []scriptedToolStep{{text: credential}, {err: errors.New("commit failed")}}, want: "commit failed"},
+		{name: "empty commit", request: request, steps: []scriptedToolStep{{text: credential}, {text: "  "}}, want: "no business result"},
+		{name: "malformed commit", request: request, steps: []scriptedToolStep{{text: credential}, {text: "{"}}, want: "parse commit_upload response"},
+		{name: "empty object commit", request: request, steps: []scriptedToolStep{{text: credential}, {text: `{}`}}, want: "empty JSON object"},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			caller := &scriptedToolCaller{steps: tc.steps}
+			installScriptedCaller(t, caller)
+			SetHTTPPutFile(func(context.Context, string, map[string]string, string, int64) error { return tc.putErr })
+			t.Cleanup(func() { SetHTTPPutFile(nil) })
+			_, err := UploadDriveFileData(context.Background(), tc.request)
+			if err == nil || !strings.Contains(err.Error(), tc.want) {
+				t.Fatalf("error=%v, want %q", err, tc.want)
+			}
+		})
+	}
+}
+
 func TestCrossPlatformCoverageDriveCommandRemainingEdges(t *testing.T) {
 	file := filepath.Join(t.TempDir(), "fixture.txt")
 	_ = os.WriteFile(file, []byte("fixture"), 0o600)

internal/helpers/file_comment.go

@@ -0,0 +1,576 @@
+// 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 (
+	"context"
+	"encoding/json"
+	"fmt"
+	"strconv"
+	"strings"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/output"
+	"github.com/spf13/cobra"
+)
+
+const (
+	fileCommentServer           = "doc-comment"
+	listFileCommentsTool        = "list_file_comments"
+	createFileCommentTool       = "create_file_comment"
+	fileCommentMaxPageSize      = 200
+	fileCommentMaxAutoPages     = 10
+	fileCommentMaxContentLength = 2099
+)
+
+type fileCommentPage struct {
+	nodeID     string
+	total      any
+	hasMore    bool
+	nextCursor string
+	comments   []map[string]any
+}
+
+func fileCommentNodeFlag() LeafFlag {
+	return LeafFlag{Name: "node", Usage: "文件 ID (dentryUuid)、数字 dentry ID 或钉盘文件 URL", Required: true, Aliases: []string{"url", "id", "node-id", "file-id"}, Bind: "fileId", Trim: true}
+}
+
+func fileCommentSpaceIDFlag() LeafFlag {
+	return LeafFlag{Name: "space-id", Usage: "钉盘空间 ID；仅数字 dentry ID 必填", Bind: "spaceId", OmitEmpty: true, Trim: true, RequiredWhen: "--node is a numeric dentry ID"}
+}
+
+// newDriveFileCommentCmd follows the existing resource-first comment surface:
+// doc comment, sheet comment, and drive comment. The public command belongs to
+// Drive, while the implementation routes to the shared doc-comment MCP server.
+func newDriveFileCommentCmd() *cobra.Command {
+	commentCmd := &cobra.Command{
+		Use:   "comment",
+		Short: "普通文件评论管理",
+		Long:  "管理钉盘普通预览文件的评论：查询评论列表或创建全文纯文本评论。",
+		RunE:  groupRunE,
+	}
+
+	listCmd := NewLeafCommand(LeafSpec{
+		Use:   "list",
+		Short: "查询普通文件评论列表",
+		Long: `查询钉盘普通预览文件的评论。支持 dentryUuid、钉盘文件 URL，以及配合
+--space-id 使用的数字 dentry ID。支持的文件类型由服务端判定。
+
+默认返回一页；--all 固定按每页 200 条自动翻页，最多 10 页。--scope 在 CLI
+侧按服务端返回的统一 anchor 过滤；total 始终表示文件的全部有效评论数，count
+表示本次输出且符合 scope 的评论数。`,
+		Example: `  dws drive comment list --node <dentryUuid> --format json
+  dws drive comment list --node <dentryUuid> --all --format json`,
+		Tool: listFileCommentsTool,
+		Flags: []LeafFlag{
+			fileCommentNodeFlag(),
+			fileCommentSpaceIDFlag(),
+			{Name: "limit", Usage: "每页评论数，范围 1-200", Kind: LeafInt, Default: "200", Aliases: []string{"page-size"}, Bind: "maxResults"},
+			{Name: "cursor", Usage: "分页游标，取自上页 nextCursor", Bind: "nextToken", OmitEmpty: true, Trim: true},
+			{Name: "all", Usage: "自动拉取全部评论，最多 10 页 / 2000 条", Kind: LeafBool, Bind: "all"},
+			{Name: "scope", Usage: "评论范围: all(全部) / whole(全文) / partial(历史局部)", Default: "all", Bind: "scope", Trim: true, Enum: []string{"all", "whole", "partial"}},
+		},
+		Constraints: []LeafConstraint{
+			{Kind: LeafMutuallyExclusive, Flags: []string{"all", "cursor"}, Description: "--all 与 --cursor 互斥"},
+			{Kind: LeafMutuallyExclusive, Flags: []string{"all", "limit"}, Description: "--all 与显式 --limit/--page-size 互斥"},
+			{Kind: "custom", Flags: []string{"limit"}, Description: "--limit/--page-size 必须在 1-200 之间"},
+			{Kind: "custom", Flags: []string{"cursor"}, Description: "--cursor 必须是服务端返回的非负数字游标"},
+		},
+		Safety: contract.SafetySpec{
+			Effect: "read", Risk: "low",
+			Confirmation: "not_required", Idempotency: "idempotent",
+		},
+		Contract: LeafContract{
+			Identity: contract.ToolIdentitySpec{
+				ProductID:      "drive",
+				Name:           "list_file_comments",
+				CanonicalPath:  "drive.list_file_comments",
+				CLIPath:        "drive comment list",
+				PrimaryCLIPath: "drive comment list",
+			},
+			Description: "查询钉盘普通预览文件评论，支持安全分页聚合和全文/局部范围过滤",
+			DryRun:      &contract.DryRunSpec{PreviewKind: contract.DryRunPreviewRequest},
+			Interface: &contract.InterfaceSpec{
+				Mode:         "composite",
+				Availability: "available",
+				Reason:       "The CLI wraps doc-comment/list_file_comments with bounded auto-pagination, cursor anomaly guards, local anchor-scope filtering, and a stable output projection, so no single direct MCP interface represents the complete command contract.",
+			},
+			Selection: contract.SelectionSpec{
+				AgentSummary: "查询 PDF、DOCX、XLSX 等钉盘普通预览文件上的评论",
+				UseWhen: []string{
+					"用户要查看普通文件上的全文评论或历史高亮/矩形评论时",
+					"需要从评论列表取得 commentId、作者、时间和统一 anchor，或用 --all 拉取完整列表时",
+				},
+				AvoidWhen: []string{
+					"在线文字文档评论使用 dws doc comment list",
+					"在线表格单元格评论使用 dws sheet comment list",
+				},
+				Examples: []string{
+					"dws drive comment list --node <dentryUuid> --format json",
+					"dws drive comment list --node <dentryUuid> --all --format json",
+				},
+			},
+		},
+		Validate: validateFileCommentList,
+		Call:     runFileCommentList,
+	})
+
+	createCmd := NewLeafCommand(LeafSpec{
+		Use:   "create",
+		Short: "创建普通文件全文评论",
+		Long: `在钉盘普通预览文件上创建一条全文纯文本评论。当前不支持 @人、通知选项或
+局部锚点；content 按服务端规则使用 UTF-16 长度计数，最多 2099。`,
+		Example: `  dws drive comment create --node <dentryUuid> --content "请补充最终结论" --format json`,
+		Tool:    createFileCommentTool,
+		Flags: []LeafFlag{
+			fileCommentNodeFlag(),
+			fileCommentSpaceIDFlag(),
+			{Name: "content", Usage: "全文评论内容，纯文本且 UTF-16 长度不超过 2099", Required: true, Bind: "content"},
+		},
+		Constraints: []LeafConstraint{
+			{Kind: "custom", Flags: []string{"content"}, Description: "--content 去除首尾空白后必须非空，且 UTF-16 长度不超过 2099"},
+		},
+		Safety: contract.SafetySpec{
+			Effect: "write", Risk: "medium",
+			Confirmation: "user_required", Idempotency: "unknown",
+		},
+		Contract: LeafContract{
+			Identity: contract.ToolIdentitySpec{
+				ProductID:      "drive",
+				Name:           "create_file_comment",
+				CanonicalPath:  "drive.create_file_comment",
+				CLIPath:        "drive comment create",
+				PrimaryCLIPath: "drive comment create",
+			},
+			Description: "在钉盘普通预览文件上创建一条全文纯文本评论",
+			DryRun:      &contract.DryRunSpec{PreviewKind: contract.DryRunPreviewRequest},
+			Interface: &contract.InterfaceSpec{
+				Mode:         "composite",
+				Availability: "available",
+				Reason:       "The CLI wraps doc-comment/create_file_comment with exact local content validation, runtime confirmation, and a stable flattened output projection, so no single direct MCP interface represents the complete command contract.",
+			},
+			Selection: contract.SelectionSpec{
+				AgentSummary: "在 PDF、DOCX、XLSX 等钉盘普通预览文件上创建全文纯文本评论",
+				UseWhen: []string{
+					"用户明确要求在普通文件上留下不绑定具体位置的评论时",
+				},
+				AvoidWhen: []string{
+					"在线文字文档评论使用 dws doc comment create",
+					"在线表格单元格评论使用 dws sheet comment create；当前普通文件评论不支持 @人或局部锚点",
+				},
+				Examples: []string{
+					"dws drive comment create --node <dentryUuid> --content \"请补充最终结论\" --format json",
+				},
+			},
+		},
+		Validate: validateFileCommentCreate,
+		Call:     runFileCommentCreate,
+	})
+
+	commentCmd.AddCommand(listCmd, createCmd)
+	return commentCmd
+}
+
+func validateFileCommentList(cmd *cobra.Command, _ []string) error {
+	if err := validateFileCommentNodeSpace(cmd); err != nil {
+		return err
+	}
+	limit, _ := cmd.Flags().GetInt("limit")
+	if cmd.Flags().Changed("page-size") {
+		limit, _ = cmd.Flags().GetInt("page-size")
+	}
+	if limit < 1 || limit > fileCommentMaxPageSize {
+		return &CLIError{
+			Code:    CodeInvalidParam,
+			Message: fmt.Sprintf("--limit/--page-size 必须在 1-%d 之间", fileCommentMaxPageSize),
+		}
+	}
+	if cursor, _ := cmd.Flags().GetString("cursor"); strings.TrimSpace(cursor) != "" {
+		cursor = strings.TrimSpace(cursor)
+		if !allASCIIDigits(cursor) {
+			return &CLIError{Code: CodeInvalidParam, Message: "--cursor 必须是服务端返回的非负数字游标"}
+		}
+		if _, err := strconv.ParseInt(cursor, 10, 64); err != nil {
+			return &CLIError{Code: CodeInvalidParam, Message: "--cursor 超出 64 位整数范围"}
+		}
+	}
+	return nil
+}
+
+func validateFileCommentCreate(cmd *cobra.Command, _ []string) error {
+	if err := validateFileCommentNodeSpace(cmd); err != nil {
+		return err
+	}
+	content, _ := cmd.Flags().GetString("content")
+	if strings.TrimSpace(content) == "" {
+		return &CLIError{Code: CodeInvalidParam, Message: "--content 去除首尾空白后不能为空"}
+	}
+	length := fileCommentUTF16Length(content)
+	if length > fileCommentMaxContentLength {
+		return &CLIError{
+			Code:    CodeInputTooLarge,
+			Message: fmt.Sprintf("--content 最多 %d 个 UTF-16 代码单元，当前为 %d", fileCommentMaxContentLength, length),
+		}
+	}
+	return nil
+}
+
+func validateFileCommentNodeSpace(cmd *cobra.Command) error {
+	node := corecmd.EffectiveValue(cmd, fileCommentNodeFlag())
+	if !allASCIIDigits(node) {
+		return nil
+	}
+	if spaceID := corecmd.EffectiveValue(cmd, fileCommentSpaceIDFlag()); spaceID == "" {
+		return &CLIError{
+			Code:    CodeInvalidParam,
+			Message: "--node 为数字 dentry ID 时必须同时提供 --space-id",
+		}
+	}
+	return nil
+}
+
+func fileCommentUTF16Length(value string) int {
+	length := 0
+	for _, r := range value {
+		length++
+		if r > 0xffff {
+			length++
+		}
+	}
+	return length
+}
+
+func allASCIIDigits(value string) bool {
+	if value == "" {
+		return false
+	}
+	for _, r := range value {
+		if r < '0' || r > '9' {
+			return false
+		}
+	}
+	return true
+}
+
+func runFileCommentList(cmd *cobra.Command, tool string, args map[string]any) error {
+	fetchAll, _ := args["all"].(bool)
+	scope, _ := args["scope"].(string)
+	if scope == "" {
+		scope = "all"
+	}
+	request := fileCommentMCPArgs(args)
+	if fetchAll {
+		request["maxResults"] = fileCommentMaxPageSize
+		delete(request, "nextToken")
+	}
+	if deps != nil && deps.Caller != nil && deps.Caller.DryRun() {
+		return callMCPToolOnServer(fileCommentServer, tool, request)
+	}
+
+	if !fetchAll {
+		page, err := fetchFileCommentPage(tool, request)
+		if err != nil {
+			return err
+		}
+		if err := validateFileCommentNextCursor(page, stringArg(request, "nextToken")); err != nil {
+			return err
+		}
+		page.comments = filterFileCommentsByScope(page.comments, scope)
+		return output.WriteCommandPayload(cmd, fileCommentListPayload(page, scope), output.FormatJSON)
+	}
+
+	var aggregate fileCommentPage
+	aggregate.comments = make([]map[string]any, 0)
+	seenCursors := map[string]bool{}
+	currentCursor := ""
+	for pageNumber := 0; pageNumber < fileCommentMaxAutoPages; pageNumber++ {
+		if currentCursor == "" {
+			delete(request, "nextToken")
+		} else {
+			request["nextToken"] = currentCursor
+		}
+		page, err := fetchFileCommentPage(tool, request)
+		if err != nil {
+			return err
+		}
+		if pageNumber == 0 {
+			aggregate.nodeID = page.nodeID
+			aggregate.total = page.total
+		}
+		aggregate.comments = append(aggregate.comments, filterFileCommentsByScope(page.comments, scope)...)
+		if !page.hasMore {
+			aggregate.hasMore = false
+			aggregate.nextCursor = ""
+			return output.WriteCommandPayload(cmd, fileCommentListPayload(aggregate, scope), output.FormatJSON)
+		}
+		if err := validateFileCommentNextCursor(page, currentCursor); err != nil {
+			return err
+		}
+		if seenCursors[page.nextCursor] {
+			return fileCommentPaginationError("分页游标发生循环，结果可能不完整")
+		}
+		seenCursors[page.nextCursor] = true
+		currentCursor = page.nextCursor
+	}
+	return fileCommentPaginationError(fmt.Sprintf("自动翻页达到 %d 页上限但服务端仍返回 hasMore=true，结果可能不完整", fileCommentMaxAutoPages))
+}
+
+func runFileCommentCreate(cmd *cobra.Command, tool string, args map[string]any) error {
+	request := fileCommentMCPArgs(args)
+	if deps != nil && deps.Caller != nil && deps.Caller.DryRun() {
+		return callMCPToolOnServer(fileCommentServer, tool, request)
+	}
+	raw, err := callMCPToolReturnTextOnServer(context.Background(), fileCommentServer, tool, request)
+	if err != nil {
+		return err
+	}
+	payload, err := decodeFileCommentPayload(tool, raw)
+	if err != nil {
+		return err
+	}
+	nodeID, ok := nonEmptyStringField(payload, "fileId")
+	if !ok {
+		return invalidFileCommentResponse(tool, "缺少 fileId", nil)
+	}
+	comment, ok := payload["comment"].(map[string]any)
+	if !ok {
+		return invalidFileCommentResponse(tool, "缺少 comment 对象", nil)
+	}
+	if err := validateFileCommentItem(tool, "comment", comment); err != nil {
+		return err
+	}
+	out := map[string]any{"nodeId": nodeID}
+	for key, value := range projectFileComment(comment) {
+		out[key] = value
+	}
+	return output.WriteCommandPayload(cmd, out, output.FormatJSON)
+}
+
+func fileCommentMCPArgs(args map[string]any) map[string]any {
+	out := make(map[string]any, len(args))
+	for key, value := range args {
+		switch key {
+		case "all", "scope":
+			continue
+		default:
+			out[key] = value
+		}
+	}
+	return out
+}
+
+func fetchFileCommentPage(tool string, request map[string]any) (fileCommentPage, error) {
+	raw, err := callMCPToolReturnTextOnServer(context.Background(), fileCommentServer, tool, request)
+	if err != nil {
+		return fileCommentPage{}, err
+	}
+	payload, err := decodeFileCommentPayload(tool, raw)
+	if err != nil {
+		return fileCommentPage{}, err
+	}
+	nodeID, ok := nonEmptyStringField(payload, "fileId")
+	if !ok {
+		return fileCommentPage{}, invalidFileCommentResponse(tool, "缺少 fileId", nil)
+	}
+	total, ok := payload["total"]
+	if !ok {
+		return fileCommentPage{}, invalidFileCommentResponse(tool, "缺少 total", nil)
+	}
+	hasMore, ok := payload["hasMore"].(bool)
+	if !ok {
+		return fileCommentPage{}, invalidFileCommentResponse(tool, "缺少布尔字段 hasMore", nil)
+	}
+	nextCursor := ""
+	if value, exists := payload["nextToken"]; exists && value != nil {
+		var stringValue bool
+		nextCursor, stringValue = value.(string)
+		if !stringValue {
+			return fileCommentPage{}, invalidFileCommentResponse(tool, "nextToken 不是字符串", nil)
+		}
+	}
+	rawItems, exists := payload["items"]
+	if !exists {
+		return fileCommentPage{}, invalidFileCommentResponse(tool, "缺少 items", nil)
+	}
+	items, ok := rawItems.([]any)
+	if rawItems == nil {
+		items = []any{}
+		ok = true
+	}
+	if !ok {
+		return fileCommentPage{}, invalidFileCommentResponse(tool, "items 不是数组", nil)
+	}
+	comments := make([]map[string]any, 0, len(items))
+	for index, item := range items {
+		comment, ok := item.(map[string]any)
+		if !ok {
+			return fileCommentPage{}, invalidFileCommentResponse(tool, fmt.Sprintf("items[%d] 不是对象", index), nil)
+		}
+		if err := validateFileCommentItem(tool, fmt.Sprintf("items[%d]", index), comment); err != nil {
+			return fileCommentPage{}, err
+		}
+		comments = append(comments, projectFileComment(comment))
+	}
+	return fileCommentPage{
+		nodeID: nodeID, total: total, hasMore: hasMore,
+		nextCursor: strings.TrimSpace(nextCursor), comments: comments,
+	}, nil
+}
+
+func decodeFileCommentPayload(tool, raw string) (map[string]any, error) {
+	if strings.TrimSpace(raw) == "" {
+		return nil, invalidFileCommentResponse(tool, "返回为空", nil)
+	}
+	var payload map[string]any
+	if err := json.Unmarshal([]byte(raw), &payload); err != nil {
+		return nil, invalidFileCommentResponse(tool, "返回不是有效 JSON", err)
+	}
+	for depth := 0; depth < 2; depth++ {
+		if _, ok := payload["fileId"]; ok {
+			break
+		}
+		var nested map[string]any
+		for _, key := range []string{"result", "data"} {
+			if value, ok := payload[key].(map[string]any); ok {
+				nested = value
+				break
+			}
+		}
+		if nested == nil {
+			break
+		}
+		payload = nested
+	}
+	return payload, nil
+}
+
+func projectFileComment(comment map[string]any) map[string]any {
+	out := map[string]any{}
+	for _, key := range []string{"commentId", "parentCommentId", "content", "createdAt", "updatedAt", "options", "anchor"} {
+		if value, ok := comment[key]; ok {
+			out[key] = value
+		}
+	}
+	if value, ok := comment["commentCustomType"]; ok {
+		out["customType"] = value
+	}
+	creator := map[string]any{}
+	for source, target := range map[string]string{
+		"creatorId": "userId", "creatorName": "name", "creatorAvatar": "avatar",
+	} {
+		if value, ok := comment[source]; ok {
+			creator[target] = value
+		}
+	}
+	if len(creator) > 0 {
+		out["creator"] = creator
+	}
+	return out
+}
+
+func validateFileCommentItem(tool, path string, comment map[string]any) error {
+	if _, ok := nonEmptyStringField(comment, "commentId"); !ok {
+		return invalidFileCommentResponse(tool, path+" 缺少 commentId", nil)
+	}
+	if _, ok := comment["anchor"].(map[string]any); !ok {
+		return invalidFileCommentResponse(tool, path+" 缺少 anchor 对象", nil)
+	}
+	return nil
+}
+
+func filterFileCommentsByScope(comments []map[string]any, scope string) []map[string]any {
+	if scope == "" || scope == "all" {
+		return comments
+	}
+	out := make([]map[string]any, 0, len(comments))
+	for _, comment := range comments {
+		anchor, _ := comment["anchor"].(map[string]any)
+		commentScope, _ := anchor["scope"].(string)
+		if commentScope == scope {
+			out = append(out, comment)
+		}
+	}
+	return out
+}
+
+func fileCommentListPayload(page fileCommentPage, scope string) map[string]any {
+	comments := page.comments
+	if comments == nil {
+		comments = make([]map[string]any, 0)
+	}
+	nextCursor := any(nil)
+	if page.nextCursor != "" {
+		nextCursor = page.nextCursor
+	}
+	return map[string]any{
+		"nodeId":     page.nodeID,
+		"total":      page.total,
+		"count":      len(page.comments),
+		"hasMore":    page.hasMore,
+		"nextCursor": nextCursor,
+		"complete":   !page.hasMore,
+		"scope":      scope,
+		"comments":   comments,
+	}
+}
+
+func validateFileCommentNextCursor(page fileCommentPage, currentCursor string) error {
+	if !page.hasMore {
+		return nil
+	}
+	if page.nextCursor == "" {
+		return fileCommentPaginationError("服务端返回 hasMore=true 但 nextCursor 为空，结果可能不完整")
+	}
+	if !allASCIIDigits(page.nextCursor) {
+		return fileCommentPaginationError("服务端返回的 nextCursor 不是非负数字游标，结果可能不完整")
+	}
+	if _, err := strconv.ParseInt(page.nextCursor, 10, 64); err != nil {
+		return fileCommentPaginationError("服务端返回的 nextCursor 超出 64 位整数范围，结果可能不完整")
+	}
+	if page.nextCursor == currentCursor {
+		return fileCommentPaginationError("服务端分页游标未前进，结果可能不完整")
+	}
+	return nil
+}
+
+func fileCommentPaginationError(message string) error {
+	return &CLIError{
+		Code:       CodeContentTruncated,
+		Message:    message,
+		Suggestion: "请稍后重试，或去掉 --all 后使用服务端返回的 --cursor 分页读取",
+		Operation:  fileCommentServer + "/" + listFileCommentsTool,
+	}
+}
+
+func invalidFileCommentResponse(tool, reason string, cause error) error {
+	return &CLIError{
+		Code:       CodeMCPToolError,
+		Message:    fmt.Sprintf("%s 返回结构异常：%s", tool, reason),
+		Suggestion: "请确认 doc-comment MCP 与当前 DWS 契约一致",
+		Operation:  fileCommentServer + "/" + tool,
+		Cause:      cause,
+	}
+}
+
+func nonEmptyStringField(payload map[string]any, key string) (string, bool) {
+	value, ok := payload[key].(string)
+	value = strings.TrimSpace(value)
+	return value, ok && value != ""
+}
+
+func stringArg(args map[string]any, key string) string {
+	value, _ := args[key].(string)
+	return strings.TrimSpace(value)
+}

internal/helpers/file_comment_test.go

@@ -0,0 +1,647 @@
+// 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 (
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"reflect"
+	"strings"
+	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contractfinal"
+	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition"
+	"github.com/spf13/cobra"
+)
+
+type fileCommentTestCall struct {
+	server string
+	tool   string
+	args   map[string]any
+}
+
+type fileCommentTestCaller struct {
+	calls     []fileCommentTestCall
+	responses []string
+	err       error
+	dryRun    bool
+}
+
+func (c *fileCommentTestCaller) CallTool(_ context.Context, server, tool string, args map[string]any) (*edition.ToolResult, error) {
+	copied := make(map[string]any, len(args))
+	for key, value := range args {
+		copied[key] = value
+	}
+	c.calls = append(c.calls, fileCommentTestCall{server: server, tool: tool, args: copied})
+	if c.err != nil {
+		return nil, c.err
+	}
+	response := `{"result":{"fileId":"file-1","comment":{"commentId":"1","content":"ok","anchor":{"version":"v1","surface":"file","scope":"whole"}}}}`
+	if len(c.responses) > 0 {
+		response = c.responses[0]
+		c.responses = c.responses[1:]
+	}
+	return &edition.ToolResult{Content: []edition.ContentBlock{{Type: "text", Text: response}}}, nil
+}
+
+func (c *fileCommentTestCaller) Format() string { return "json" }
+func (c *fileCommentTestCaller) DryRun() bool   { return c.dryRun }
+func (c *fileCommentTestCaller) Fields() string { return "" }
+func (c *fileCommentTestCaller) JQ() string     { return "" }
+
+func executeFileCommentCommand(t *testing.T, caller *fileCommentTestCaller, stdin string, args ...string) ([]byte, error) {
+	t.Helper()
+	testseam.Protect(t, &deps)
+	InitDeps(caller)
+	var stdout bytes.Buffer
+	deps.Out.w = &stdout
+	deps.Out.errW = io.Discard
+
+	root := &cobra.Command{Use: "dws", SilenceErrors: true, SilenceUsage: true}
+	root.SetOut(&stdout)
+	root.SetErr(io.Discard)
+	root.SetIn(strings.NewReader(stdin))
+	root.PersistentFlags().Bool("yes", false, "")
+	root.PersistentFlags().Bool("dry-run", false, "")
+	root.PersistentFlags().String("format", "json", "")
+	drive := &cobra.Command{Use: "drive"}
+	drive.AddCommand(newDriveFileCommentCmd())
+	root.AddCommand(drive)
+	var setOutput func(*cobra.Command)
+	setOutput = func(command *cobra.Command) {
+		command.SetOut(&stdout)
+		command.SetErr(io.Discard)
+		for _, child := range command.Commands() {
+			setOutput(child)
+		}
+	}
+	setOutput(root)
+	root.SetArgs(args)
+	err := root.Execute()
+	return stdout.Bytes(), err
+}
+
+func decodeFileCommentTestOutput(t *testing.T, raw []byte) map[string]any {
+	t.Helper()
+	var payload map[string]any
+	if err := json.Unmarshal(raw, &payload); err != nil {
+		t.Fatalf("decode output %q: %v", raw, err)
+	}
+	return payload
+}
+
+func TestDriveFileCommentListMapsFiltersAndProjects(t *testing.T) {
+	caller := &fileCommentTestCaller{responses: []string{`{
+		"result": {
+			"fileId": "resolved-file",
+			"total": 2,
+			"count": 2,
+			"hasMore": false,
+			"nextToken": null,
+			"items": [
+				{
+					"commentId": "101",
+					"parentCommentId": null,
+					"content": "whole",
+					"creatorId": "user-1",
+					"creatorName": "Alice",
+					"creatorAvatar": "https://avatar/1",
+					"createdAt": 1785920000000,
+					"updatedAt": 1785920000100,
+					"commentCustomType": "common",
+					"anchor": {"version":"v1","surface":"file","scope":"whole"}
+				},
+				{
+					"commentId": "102",
+					"content": "partial",
+					"commentCustomType": "highlight",
+					"options": {"page":"1"},
+					"anchor": {"version":"v1","surface":"file","scope":"partial","selector":{"kind":"legacy-highlight"}}
+				}
+			]
+		}
+	}`}}
+
+	out, err := executeFileCommentCommand(t, caller, "",
+		"drive", "comment", "list",
+		"--node", "https://alidocs.dingtalk.com/i/drive/file",
+		"--space-id", "123", "--limit", "20", "--scope", "whole",
+	)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(caller.calls) != 1 {
+		t.Fatalf("calls = %#v", caller.calls)
+	}
+	call := caller.calls[0]
+	if call.server != fileCommentServer || call.tool != listFileCommentsTool {
+		t.Fatalf("target = %s/%s", call.server, call.tool)
+	}
+	wantArgs := map[string]any{
+		"fileId":     "https://alidocs.dingtalk.com/i/drive/file",
+		"spaceId":    "123",
+		"maxResults": 20,
+	}
+	if !reflect.DeepEqual(call.args, wantArgs) {
+		t.Fatalf("args = %#v, want %#v", call.args, wantArgs)
+	}
+
+	payload := decodeFileCommentTestOutput(t, out)
+	if payload["nodeId"] != "resolved-file" || payload["total"] != float64(2) ||
+		payload["count"] != float64(1) || payload["complete"] != true || payload["scope"] != "whole" {
+		t.Fatalf("list output = %#v", payload)
+	}
+	if payload["nextCursor"] != nil || payload["hasMore"] != false {
+		t.Fatalf("pagination output = %#v", payload)
+	}
+	comments := payload["comments"].([]any)
+	comment := comments[0].(map[string]any)
+	if comment["commentId"] != "101" || comment["customType"] != "common" {
+		t.Fatalf("comment projection = %#v", comment)
+	}
+	creator := comment["creator"].(map[string]any)
+	if creator["userId"] != "user-1" || creator["name"] != "Alice" || creator["avatar"] != "https://avatar/1" {
+		t.Fatalf("creator projection = %#v", creator)
+	}
+	if _, leaked := comment["creatorId"]; leaked {
+		t.Fatalf("raw creator fields leaked: %#v", comment)
+	}
+}
+
+func TestDriveFileCommentListKeepsEmptyCommentsAsArray(t *testing.T) {
+	caller := &fileCommentTestCaller{responses: []string{`{
+		"fileId":"file-1","total":0,"count":0,"hasMore":false,"nextToken":null,"items":[]
+	}`}}
+
+	out, err := executeFileCommentCommand(t, caller, "",
+		"drive", "comment", "list", "--node", "file-1",
+	)
+	if err != nil {
+		t.Fatal(err)
+	}
+	payload := decodeFileCommentTestOutput(t, out)
+	comments, ok := payload["comments"].([]any)
+	if !ok || len(comments) != 0 {
+		t.Fatalf("comments = %#v, want an empty JSON array", payload["comments"])
+	}
+	if payload["total"] != float64(0) || payload["count"] != float64(0) ||
+		payload["hasMore"] != false || payload["complete"] != true || payload["nextCursor"] != nil {
+		t.Fatalf("empty list output = %#v", payload)
+	}
+}
+
+func TestDriveFileCommentListAllAggregatesPages(t *testing.T) {
+	caller := &fileCommentTestCaller{responses: []string{
+		`{"fileId":"file-1","total":3,"count":2,"hasMore":true,"nextToken":"2","items":[
+			{"commentId":"1","anchor":{"scope":"whole"}},
+			{"commentId":"2","anchor":{"scope":"partial"}}
+		]}`,
+		`{"fileId":"file-1","total":3,"count":1,"hasMore":false,"nextToken":null,"items":[
+			{"commentId":"3","anchor":{"scope":"partial"}}
+		]}`,
+	}}
+
+	out, err := executeFileCommentCommand(t, caller, "",
+		"drive", "comment", "list", "--node", "file-1", "--all", "--scope", "partial",
+	)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(caller.calls) != 2 {
+		t.Fatalf("calls = %#v", caller.calls)
+	}
+	if caller.calls[0].args["maxResults"] != fileCommentMaxPageSize {
+		t.Fatalf("first args = %#v", caller.calls[0].args)
+	}
+	if _, ok := caller.calls[0].args["nextToken"]; ok {
+		t.Fatalf("first page unexpectedly has cursor: %#v", caller.calls[0].args)
+	}
+	if caller.calls[1].args["nextToken"] != "2" {
+		t.Fatalf("second args = %#v", caller.calls[1].args)
+	}
+	for _, call := range caller.calls {
+		if _, ok := call.args["all"]; ok {
+			t.Fatalf("local --all leaked to MCP: %#v", call.args)
+		}
+		if _, ok := call.args["scope"]; ok {
+			t.Fatalf("local --scope leaked to MCP: %#v", call.args)
+		}
+	}
+
+	payload := decodeFileCommentTestOutput(t, out)
+	if payload["total"] != float64(3) || payload["count"] != float64(2) ||
+		payload["hasMore"] != false || payload["complete"] != true || payload["nextCursor"] != nil {
+		t.Fatalf("aggregate output = %#v", payload)
+	}
+	comments := payload["comments"].([]any)
+	if comments[0].(map[string]any)["commentId"] != "2" || comments[1].(map[string]any)["commentId"] != "3" {
+		t.Fatalf("scope-filtered comments = %#v", comments)
+	}
+}
+
+func TestDriveFileCommentListRejectsPaginationAnomalies(t *testing.T) {
+	tests := []struct {
+		name     string
+		args     []string
+		response string
+		message  string
+	}{
+		{
+			name:     "missing cursor",
+			args:     []string{"drive", "comment", "list", "--node", "file-1", "--all"},
+			response: `{"fileId":"file-1","total":1,"count":1,"hasMore":true,"nextToken":null,"items":[]}`,
+			message:  "nextCursor 为空",
+		},
+		{
+			name:     "stalled cursor",
+			args:     []string{"drive", "comment", "list", "--node", "file-1", "--cursor", "2"},
+			response: `{"fileId":"file-1","total":2,"count":1,"hasMore":true,"nextToken":"2","items":[]}`,
+			message:  "游标未前进",
+		},
+		{
+			name:     "invalid server cursor",
+			args:     []string{"drive", "comment", "list", "--node", "file-1"},
+			response: `{"fileId":"file-1","total":2,"count":1,"hasMore":true,"nextToken":"next","items":[]}`,
+			message:  "不是非负数字游标",
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			caller := &fileCommentTestCaller{responses: []string{tt.response}}
+			_, err := executeFileCommentCommand(t, caller, "", tt.args...)
+			var cliErr *CLIError
+			if !errors.As(err, &cliErr) || cliErr.Code != CodeContentTruncated || !strings.Contains(cliErr.Message, tt.message) {
+				t.Fatalf("error = %#v", err)
+			}
+			if len(caller.calls) != 1 {
+				t.Fatalf("calls = %#v", caller.calls)
+			}
+		})
+	}
+}
+
+func TestDriveFileCommentListValidatesLocalParameters(t *testing.T) {
+	tests := []struct {
+		name string
+		args []string
+	}{
+		{"all with cursor", []string{"--all", "--cursor", "1"}},
+		{"all with limit", []string{"--all", "--limit", "20"}},
+		{"zero limit", []string{"--limit", "0"}},
+		{"large limit", []string{"--page-size", "201"}},
+		{"nonnumeric cursor", []string{"--cursor", "next"}},
+		{"overflow cursor", []string{"--cursor", "999999999999999999999999999999"}},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			caller := &fileCommentTestCaller{}
+			args := []string{"drive", "comment", "list", "--node", "file-1"}
+			args = append(args, tt.args...)
+			if _, err := executeFileCommentCommand(t, caller, "", args...); err == nil {
+				t.Fatal("invalid arguments unexpectedly succeeded")
+			}
+			if len(caller.calls) != 0 {
+				t.Fatalf("invalid arguments reached MCP: %#v", caller.calls)
+			}
+		})
+	}
+}
+
+func TestDriveFileCommentNumericNodeRequiresSpaceIDForListAndCreateAliases(t *testing.T) {
+	tests := []struct {
+		name string
+		args []string
+	}{
+		{
+			name: "list id alias",
+			args: []string{"drive", "comment", "list", "--id", "231773999335"},
+		},
+		{
+			name: "create file-id alias",
+			args: []string{"drive", "comment", "create", "--file-id", "231773999335", "--content", "test", "--yes"},
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			caller := &fileCommentTestCaller{}
+			_, err := executeFileCommentCommand(t, caller, "", tt.args...)
+			var cliErr *CLIError
+			if !errors.As(err, &cliErr) || cliErr.Code != CodeInvalidParam || !strings.Contains(cliErr.Message, "--space-id") {
+				t.Fatalf("error = %#v", err)
+			}
+			if len(caller.calls) != 0 {
+				t.Fatalf("numeric node without space-id reached MCP: %#v", caller.calls)
+			}
+		})
+	}
+
+	caller := &fileCommentTestCaller{responses: []string{`{
+		"fileId":"resolved-file","total":0,"count":0,"hasMore":false,"nextToken":null,"items":[]
+	}`}}
+	if _, err := executeFileCommentCommand(t, caller, "",
+		"drive", "comment", "list", "--url", "231773999335", "--space-id", "2402756201",
+	); err != nil {
+		t.Fatal(err)
+	}
+	if len(caller.calls) != 1 || caller.calls[0].args["fileId"] != "231773999335" || caller.calls[0].args["spaceId"] != "2402756201" {
+		t.Fatalf("numeric node with space-id args = %#v", caller.calls)
+	}
+	if allASCIIDigits("") {
+		t.Fatal("empty string unexpectedly accepted as numeric")
+	}
+}
+
+func TestDriveFileCommentCreateValidatesMapsAndProjects(t *testing.T) {
+	validContent := strings.Repeat("a", fileCommentMaxContentLength)
+	caller := &fileCommentTestCaller{responses: []string{`{"result":{"fileId":"resolved-file","comment":{
+		"commentId":"912345","parentCommentId":null,"content":"created","creatorId":"user-1",
+		"createdAt":1785920000000,"commentCustomType":"common",
+		"anchor":{"version":"v1","surface":"file","scope":"whole","selector":null}
+	}}}`}}
+	out, err := executeFileCommentCommand(t, caller, "",
+		"drive", "comment", "create", "--node", "file-1", "--space-id", "123",
+		"--content", validContent, "--yes",
+	)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(caller.calls) != 1 || caller.calls[0].server != fileCommentServer || caller.calls[0].tool != createFileCommentTool {
+		t.Fatalf("calls = %#v", caller.calls)
+	}
+	wantArgs := map[string]any{"fileId": "file-1", "spaceId": "123", "content": validContent}
+	if !reflect.DeepEqual(caller.calls[0].args, wantArgs) {
+		t.Fatalf("args = %#v, want %#v", caller.calls[0].args, wantArgs)
+	}
+	payload := decodeFileCommentTestOutput(t, out)
+	if payload["nodeId"] != "resolved-file" || payload["commentId"] != "912345" ||
+		payload["content"] != "created" || payload["customType"] != "common" {
+		t.Fatalf("create output = %#v", payload)
+	}
+	if _, nested := payload["comment"]; nested {
+		t.Fatalf("create output was not flattened: %#v", payload)
+	}
+
+	for _, tc := range []struct {
+		name    string
+		content string
+	}{
+		{"blank", "  \t"},
+		{"ascii over limit", strings.Repeat("a", fileCommentMaxContentLength+1)},
+		{"utf16 over limit", strings.Repeat("😀", 1050)},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			invalidCaller := &fileCommentTestCaller{}
+			_, err := executeFileCommentCommand(t, invalidCaller, "",
+				"drive", "comment", "create", "--node", "file-1", "--content", tc.content, "--yes",
+			)
+			if err == nil {
+				t.Fatal("invalid content unexpectedly succeeded")
+			}
+			if len(invalidCaller.calls) != 0 {
+				t.Fatalf("invalid content reached MCP: %#v", invalidCaller.calls)
+			}
+		})
+	}
+}
+
+func TestDriveFileCommentCreatePublishesAndEnforcesConfirmation(t *testing.T) {
+	group := newDriveFileCommentCmd()
+	create, remaining, err := group.Find([]string{"create"})
+	if err != nil || len(remaining) != 0 {
+		t.Fatalf("find create: remaining=%v err=%v", remaining, err)
+	}
+	final, ok := contractfinal.RuntimeContractFinal(create)
+	if !ok || final.Safety == nil {
+		t.Fatal("create command is missing ContractFinal Safety")
+	}
+	if safety := *final.Safety; safety.Effect != "write" || safety.Risk != "medium" ||
+		safety.Confirmation != "user_required" || safety.Idempotency != "unknown" {
+		t.Fatalf("create safety = %#v", safety)
+	}
+
+	caller := &fileCommentTestCaller{}
+	_, err = executeFileCommentCommand(t, caller, "",
+		"drive", "comment", "create", "--node", "file-1", "--content", "需要确认",
+	)
+	var appErr *apperrors.Error
+	if !errors.As(err, &appErr) || appErr.Reason != "confirmation_required" {
+		t.Fatalf("closed-stdin error = %#v", err)
+	}
+	if len(caller.calls) != 0 {
+		t.Fatalf("unconfirmed create reached MCP: %#v", caller.calls)
+	}
+}
+
+func TestDriveFileCommentRejectsMalformedResponseInsteadOfReturningEmpty(t *testing.T) {
+	caller := &fileCommentTestCaller{responses: []string{`{"result":{"fileId":"file-1","total":0,"hasMore":false}}`}}
+	_, err := executeFileCommentCommand(t, caller, "", "drive", "comment", "list", "--node", "file-1")
+	var cliErr *CLIError
+	if !errors.As(err, &cliErr) || cliErr.Code != CodeMCPToolError || !strings.Contains(cliErr.Message, "缺少 items") {
+		t.Fatalf("error = %#v", err)
+	}
+}
+
+func TestDriveFileCommentDryRunAndCallErrors(t *testing.T) {
+	for _, tt := range []struct {
+		name string
+		args []string
+		tool string
+	}{
+		{
+			name: "list dry run",
+			args: []string{"drive", "comment", "list", "--node", "file-1"},
+			tool: listFileCommentsTool,
+		},
+		{
+			name: "create dry run",
+			args: []string{"drive", "comment", "create", "--node", "file-1", "--content", "test", "--yes"},
+			tool: createFileCommentTool,
+		},
+	} {
+		t.Run(tt.name, func(t *testing.T) {
+			caller := &fileCommentTestCaller{dryRun: true}
+			out, err := executeFileCommentCommand(t, caller, "", tt.args...)
+			if err != nil {
+				t.Fatal(err)
+			}
+			if len(caller.calls) != 0 || !strings.Contains(string(out), `"tool": "`+tt.tool+`"`) {
+				t.Fatalf("calls = %#v, output = %s", caller.calls, out)
+			}
+		})
+	}
+
+	sentinel := errors.New("mcp unavailable")
+	for _, tt := range []struct {
+		name string
+		args []string
+	}{
+		{
+			name: "list call error",
+			args: []string{"drive", "comment", "list", "--node", "file-1", "--all"},
+		},
+		{
+			name: "create call error",
+			args: []string{"drive", "comment", "create", "--node", "file-1", "--content", "test", "--yes"},
+		},
+	} {
+		t.Run(tt.name, func(t *testing.T) {
+			caller := &fileCommentTestCaller{err: sentinel}
+			_, err := executeFileCommentCommand(t, caller, "", tt.args...)
+			if !errors.Is(err, sentinel) {
+				t.Fatalf("error = %#v", err)
+			}
+		})
+	}
+}
+
+func TestDriveFileCommentListResponseValidationBranches(t *testing.T) {
+	tests := []struct {
+		name     string
+		response string
+		message  string
+	}{
+		{name: "empty", response: "", message: "返回为空"},
+		{name: "invalid json", response: "{", message: "不是有效 JSON"},
+		{name: "missing file id", response: `{}`, message: "缺少 fileId"},
+		{name: "missing total", response: `{"fileId":"file-1","hasMore":false,"items":[]}`, message: "缺少 total"},
+		{name: "missing has more", response: `{"fileId":"file-1","total":0,"items":[]}`, message: "缺少布尔字段 hasMore"},
+		{name: "next token type", response: `{"fileId":"file-1","total":1,"hasMore":true,"nextToken":2,"items":[]}`, message: "nextToken 不是字符串"},
+		{name: "items type", response: `{"fileId":"file-1","total":0,"hasMore":false,"items":{}}`, message: "items 不是数组"},
+		{name: "item type", response: `{"fileId":"file-1","total":1,"hasMore":false,"items":[1]}`, message: "items[0] 不是对象"},
+		{name: "missing comment id", response: `{"fileId":"file-1","total":1,"hasMore":false,"items":[{"anchor":{}}]}`, message: "缺少 commentId"},
+		{name: "missing anchor", response: `{"fileId":"file-1","total":1,"hasMore":false,"items":[{"commentId":"1"}]}`, message: "缺少 anchor 对象"},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			caller := &fileCommentTestCaller{responses: []string{tt.response}}
+			_, err := executeFileCommentCommand(t, caller, "", "drive", "comment", "list", "--node", "file-1")
+			var cliErr *CLIError
+			if !errors.As(err, &cliErr) || cliErr.Code != CodeMCPToolError || !strings.Contains(cliErr.Message, tt.message) {
+				t.Fatalf("error = %#v", err)
+			}
+		})
+	}
+
+	caller := &fileCommentTestCaller{responses: []string{`{
+		"data":{"fileId":"file-1","total":0,"hasMore":false,"nextToken":null,"items":null}
+	}`}}
+	out, err := executeFileCommentCommand(t, caller, "", "drive", "comment", "list", "--node", "file-1")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if comments := decodeFileCommentTestOutput(t, out)["comments"].([]any); len(comments) != 0 {
+		t.Fatalf("comments = %#v", comments)
+	}
+}
+
+func TestDriveFileCommentCreateResponseValidationBranches(t *testing.T) {
+	tests := []struct {
+		name     string
+		response string
+		message  string
+	}{
+		{name: "invalid json", response: "{", message: "不是有效 JSON"},
+		{name: "missing file id", response: `{"comment":{"commentId":"1","anchor":{}}}`, message: "缺少 fileId"},
+		{name: "missing comment", response: `{"fileId":"file-1"}`, message: "缺少 comment 对象"},
+		{name: "missing comment id", response: `{"fileId":"file-1","comment":{"anchor":{}}}`, message: "缺少 commentId"},
+		{name: "missing anchor", response: `{"fileId":"file-1","comment":{"commentId":"1"}}`, message: "缺少 anchor 对象"},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			caller := &fileCommentTestCaller{responses: []string{tt.response}}
+			_, err := executeFileCommentCommand(t, caller, "",
+				"drive", "comment", "create", "--node", "file-1", "--content", "test", "--yes",
+			)
+			var cliErr *CLIError
+			if !errors.As(err, &cliErr) || cliErr.Code != CodeMCPToolError || !strings.Contains(cliErr.Message, tt.message) {
+				t.Fatalf("error = %#v", err)
+			}
+		})
+	}
+}
+
+func TestDriveFileCommentPaginationCycleLimitAndPartialPage(t *testing.T) {
+	cycleCaller := &fileCommentTestCaller{responses: []string{
+		`{"fileId":"file-1","total":0,"hasMore":true,"nextToken":"2","items":[]}`,
+		`{"fileId":"file-1","total":0,"hasMore":true,"nextToken":"3","items":[]}`,
+		`{"fileId":"file-1","total":0,"hasMore":true,"nextToken":"2","items":[]}`,
+	}}
+	_, err := executeFileCommentCommand(t, cycleCaller, "", "drive", "comment", "list", "--node", "file-1", "--all")
+	var cliErr *CLIError
+	if !errors.As(err, &cliErr) || cliErr.Code != CodeContentTruncated || !strings.Contains(cliErr.Message, "发生循环") {
+		t.Fatalf("cycle error = %#v", err)
+	}
+
+	limitResponses := make([]string, 0, fileCommentMaxAutoPages)
+	for index := 0; index < fileCommentMaxAutoPages; index++ {
+		limitResponses = append(limitResponses, fmt.Sprintf(
+			`{"fileId":"file-1","total":0,"hasMore":true,"nextToken":"%d","items":[]}`,
+			index+1,
+		))
+	}
+	limitCaller := &fileCommentTestCaller{responses: limitResponses}
+	_, err = executeFileCommentCommand(t, limitCaller, "", "drive", "comment", "list", "--node", "file-1", "--all")
+	if !errors.As(err, &cliErr) || cliErr.Code != CodeContentTruncated || !strings.Contains(cliErr.Message, "10 页上限") {
+		t.Fatalf("page limit error = %#v", err)
+	}
+
+	partialCaller := &fileCommentTestCaller{responses: []string{`{
+		"fileId":"file-1","total":1,"hasMore":true,"nextToken":"2",
+		"items":[{"commentId":"1","anchor":{"scope":"whole"}}]
+	}`}}
+	out, err := executeFileCommentCommand(t, partialCaller, "", "drive", "comment", "list", "--node", "file-1")
+	if err != nil {
+		t.Fatal(err)
+	}
+	payload := decodeFileCommentTestOutput(t, out)
+	if payload["nextCursor"] != "2" || payload["complete"] != false || payload["hasMore"] != true {
+		t.Fatalf("partial page = %#v", payload)
+	}
+
+	overflowCaller := &fileCommentTestCaller{responses: []string{`{
+		"fileId":"file-1","total":0,"hasMore":true,
+		"nextToken":"999999999999999999999999999999","items":[]
+	}`}}
+	_, err = executeFileCommentCommand(t, overflowCaller, "", "drive", "comment", "list", "--node", "file-1")
+	if !errors.As(err, &cliErr) || cliErr.Code != CodeContentTruncated || !strings.Contains(cliErr.Message, "超出 64 位整数范围") {
+		t.Fatalf("overflow cursor error = %#v", err)
+	}
+}
+
+func TestDriveFileCommentInternalDefaults(t *testing.T) {
+	caller := &fileCommentTestCaller{responses: []string{`{
+		"fileId":"file-1","total":0,"hasMore":false,"nextToken":null,"items":[]
+	}`}}
+	testseam.Protect(t, &deps)
+	InitDeps(caller)
+	var stdout bytes.Buffer
+	cmd := &cobra.Command{Use: "list"}
+	cmd.SetOut(&stdout)
+	if err := runFileCommentList(cmd, listFileCommentsTool, map[string]any{"fileId": "file-1", "maxResults": 200}); err != nil {
+		t.Fatal(err)
+	}
+	payload := decodeFileCommentTestOutput(t, stdout.Bytes())
+	if payload["scope"] != "all" {
+		t.Fatalf("scope = %#v", payload["scope"])
+	}
+	if comments := fileCommentListPayload(fileCommentPage{}, "all")["comments"].([]map[string]any); len(comments) != 0 {
+		t.Fatalf("nil comments projection = %#v", comments)
+	}
+}

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())

internal/shortcut/builtin/drive_semantic_catalog_test.go

@@ -0,0 +1,83 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0
+
+package builtin_test
+
+import (
+	"encoding/json"
+	"os"
+	"sort"
+	"strings"
+	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/output"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut"
+)
+
+func TestCrossPlatformCoverageDriveSemanticCatalogExactlyCoversRegisteredSurface(t *testing.T) {
+	raw, err := os.ReadFile("../semantic_catalog_drive.json")
+	if err != nil {
+		t.Fatal(err)
+	}
+	var source chatSemanticCatalogFixture
+	if err := json.Unmarshal(raw, &source); err != nil {
+		t.Fatal(err)
+	}
+	if source.Service != "drive" {
+		t.Fatalf("semantic catalog service = %q", source.Service)
+	}
+	registered := map[string]shortcut.Shortcut{}
+	for _, item := range shortcut.All() {
+		if item.Service != "drive" {
+			continue
+		}
+		if _, duplicate := registered[item.Command]; duplicate {
+			t.Fatalf("duplicate registered Drive Shortcut %s", item.Command)
+		}
+		registered[item.Command] = item
+	}
+	if len(registered) != 29 || len(source.Shortcuts) != 29 {
+		t.Fatalf("registered/catalog = %d/%d, want 29/29", len(registered), len(source.Shortcuts))
+	}
+	var missing, stale []string
+	for command, item := range registered {
+		record, ok := source.Shortcuts[command]
+		if !ok {
+			missing = append(missing, command)
+			continue
+		}
+		if !record.Reviewed || !item.SemanticReviewed {
+			t.Errorf("%s: reviewed delivery mismatch", command)
+		}
+		if got := shortcut.InPublicCatalog("drive", command); got != record.Public || item.Hidden == record.Public {
+			t.Errorf("%s: public/hidden mismatch: catalog=%v runtimeHidden=%v", command, record.Public, item.Hidden)
+		}
+		if strings.TrimSpace(record.SemanticDelta) == "" || item.SemanticDelta != record.SemanticDelta || item.Disposition != record.Disposition {
+			t.Errorf("%s: semantic catalog facts drifted", command)
+		}
+		if item.Risk != record.Risk {
+			t.Errorf("%s: risk = %q, want %q", command, item.Risk, record.Risk)
+		}
+		if item.Contract.Empty() || strings.TrimSpace(item.Safety.Effect) == "" || strings.TrimSpace(item.Safety.Confirmation) == "" {
+			t.Errorf("%s: incomplete explicit contract/safety", command)
+		}
+		if command != "+find-file" && record.Public {
+			if item.OutputRollout != output.RolloutUnifiedActive {
+				t.Errorf("%s: output rollout = %q", command, item.OutputRollout)
+			}
+			if item.Contract.Result == nil {
+				t.Errorf("%s: public Drive shortcut lacks Result declaration", command)
+			}
+		}
+	}
+	for command := range source.Shortcuts {
+		if _, ok := registered[command]; !ok {
+			stale = append(stale, command)
+		}
+	}
+	sort.Strings(missing)
+	sort.Strings(stale)
+	if len(missing) > 0 || len(stale) > 0 {
+		t.Fatalf("semantic catalog mismatch: missing=%v stale=%v", missing, stale)
+	}
+}

internal/shortcut/chat/chat_conversation.go

@@ -313,17 +313,17 @@ var ConversationList = shortcut.Shortcut{
 			Examples:     []string{"dws chat +conversation-list --limit 50"},
 		},
 	},
-	Flags: []shortcut.Flag{
+	Flags: append([]shortcut.Flag{
 		{Name: "limit", Type: shortcut.FlagInt, Default: "100", Desc: "每页数量；--limit 必须在 1-100"},
 		{Name: "cursor", Type: shortcut.FlagInt, Desc: "分页游标（首次不传或 0）"},
 		{Name: "exclude-muted", Type: shortcut.FlagBool, Desc: "排除已免打扰会话"},
-		{Name: "page-all", Type: shortcut.FlagBool, Desc: "自动读取全部分页；--page-limit 仅与 --page-all 一起使用且范围 1-500"},
+		{Name: "page-all", Type: shortcut.FlagBool, Desc: "自动读取全部分页；--page-limit 仅与 --page-all 一起使用且范围 1-500；--max-items/--page-delay 仅与 --page-all 一起使用；值必须大于等于 0"},
 		{Name: "page-limit", Type: shortcut.FlagInt, Default: "50", Desc: "--page-limit 仅与 --page-all 一起使用且范围 1-500"},
-	},
-	Constraints: []shortcut.Constraint{
+	}, shortcut.AutoPageControlFlags()...),
+	Constraints: append([]shortcut.Constraint{
 		{Kind: shortcut.ConstraintCustom, Flags: []string{"limit"}, Description: "--limit 必须在 1-100"},
 		{Kind: shortcut.ConstraintCustom, Flags: []string{"page-all", "page-limit"}, Description: "--page-limit 仅与 --page-all 一起使用且范围 1-500"},
-	},
+	}, shortcut.AutoPageControlConstraints()...),
 	Tips: []string{
 		`dws chat +conversation-list --limit 50`,
 		`dws chat +conversation-list --page-all --limit 100`,
@@ -338,6 +338,9 @@ var ConversationList = shortcut.Shortcut{
 		if pageLimit := rt.Int("page-limit"); pageLimit < 1 || pageLimit > 500 {
 			return apperrors.NewValidation("--page-limit 必须在 1-500 之间")
 		}
+		if err := shortcut.ValidateAutoPageControls(rt); err != nil {
+			return apperrors.NewValidation(err.Error())
+		}
 		return nil
 	},
 	Execute: func(rt *shortcut.RuntimeContext) error {
@@ -353,9 +356,20 @@ var ConversationList = shortcut.Shortcut{
 		complete := false
 		hasMore := false
 		nextCursor := int64(0)
+		stopReason := "source_complete"
+		truncatedByPageLimit := false
+		truncatedByResultLimit := false
+		unsafeResultContinuation := false
 		failures := make([]map[string]any, 0)
 		for pagesFetched < pageLimit {
-			params := map[string]any{"limit": rt.Int("limit")}
+			if pagesFetched > 0 {
+				if err := shortcut.WaitAutoPageDelay(rt); err != nil {
+					failures = append(failures, map[string]any{"stage": "conversation-page-delay", "cursor": cursor, "error": err.Error()})
+					stopReason = "delay_interrupted"
+					break
+				}
+			}
+			params := map[string]any{"limit": shortcut.AutoPageRequestSize(rt, rt.Int("limit"), len(convs))}
 			if cursor > 0 {
 				params["cursor"] = cursor
 			}
@@ -371,6 +385,7 @@ var ConversationList = shortcut.Shortcut{
 				break
 			}
 			pagesFetched++
+			overflowOnPage := false
 			for _, conversation := range conversationListProject(data) {
 				id := strings.TrimSpace(fmt.Sprint(conversation["openConversationId"]))
 				if id != "" && id != "<nil>" {
@@ -379,6 +394,11 @@ var ConversationList = shortcut.Shortcut{
 					}
 					seenConversations[id] = true
 				}
+				if maxItems := rt.Int("max-items"); maxItems > 0 && len(convs) >= maxItems {
+					truncatedByResultLimit = true
+					overflowOnPage = true
+					continue
+				}
 				convs = append(convs, conversation)
 			}
 			page := chatmsg.Pagination(data)
@@ -388,6 +408,14 @@ var ConversationList = shortcut.Shortcut{
 				failures = append(failures, map[string]any{"stage": "conversation-pagination", "error": "下层未返回 hasMore，无法证明结果完整"})
 				break
 			}
+			if overflowOnPage {
+				hasMore = true
+				nextCursor = 0
+				unsafeResultContinuation = true
+				failures = append(failures, map[string]any{"stage": "conversation-pagination", "error": "下层返回条数超过请求的剩余额度，无法生成不跳项的安全续页游标"})
+				stopReason = "pagination_error"
+				break
+			}
 			if !hasMore {
 				complete = true
 				break
@@ -398,27 +426,56 @@ var ConversationList = shortcut.Shortcut{
 				break
 			}
 			if !rt.Bool("page-all") {
+				stopReason = "single_page"
+				break
+			}
+			if maxItems := rt.Int("max-items"); maxItems > 0 && len(convs) >= maxItems {
+				truncatedByResultLimit = true
+				stopReason = "result_limit"
 				break
 			}
 			seenCursors[nextCursor] = true
 			cursor = nextCursor
 		}
-		if rt.Bool("page-all") && hasMore && pagesFetched == pageLimit {
-			failures = append(failures, map[string]any{"stage": "conversation-page-limit", "error": fmt.Sprintf("达到 --page-limit=%d，仍有更多会话", pageLimit)})
+		if rt.Bool("page-all") && hasMore && pagesFetched == pageLimit && !truncatedByResultLimit {
+			truncatedByPageLimit = true
+			stopReason = "page_limit"
 		}
 		payload := map[string]any{
-			"count":           len(convs),
-			"conversations":   convs,
-			"pagesFetched":    pagesFetched,
-			"complete":        complete,
-			"hasMore":         hasMore,
-			"nextCursor":      nextCursor,
-			"paginationKnown": len(failures) == 0 || hasMore,
-			"failedCount":     len(failures),
-			"failures":        failures,
-			"partial":         len(failures) > 0,
+			"count":                  len(convs),
+			"conversations":          convs,
+			"pagesFetched":           pagesFetched,
+			"complete":               complete,
+			"hasMore":                hasMore,
+			"nextCursor":             nextCursor,
+			"paginationKnown":        len(failures) == 0 || hasMore,
+			"stopReason":             stopReason,
+			"truncatedByPageLimit":   truncatedByPageLimit,
+			"truncatedByResultLimit": truncatedByResultLimit,
+			"failedCount":            len(failures),
+			"failures":               failures,
+			"partial":                len(failures) > 0,
 		}
-		return rt.Output(payload)
+		chatmsg.ApplyTruncation(payload)
+		if err := rt.Output(payload); err != nil {
+			return err
+		}
+		if stopReason == "delay_interrupted" && rt.Command().Context().Err() != nil {
+			return rt.Command().Context().Err()
+		}
+		if unsafeResultContinuation {
+			return apperrors.NewAPI(
+				fmt.Sprintf("会话列表分页未完成：成功读取 %d 页，存在 %d 个失败项", pagesFetched, len(failures)),
+				apperrors.WithOperation("im/list_all_conversations"),
+				apperrors.WithReason("conversation_list_incomplete"),
+				apperrors.WithOrigin("mcp_gateway"),
+				apperrors.WithFailureStage("pagination"),
+				apperrors.WithExecutionStarted(true),
+				apperrors.WithRetryable(true),
+				apperrors.WithHint("请根据 failures 和 nextCursor 重试"),
+			)
+		}
+		return nil
 	},
 }
 

internal/shortcut/chat/chat_conversation_projection_test.go

@@ -15,7 +15,9 @@ package chat
 
 import (
 	"bytes"
+	"context"
 	"encoding/json"
+	"errors"
 	"reflect"
 	"testing"
 
@@ -148,6 +150,96 @@ func TestCrossPlatformCoverageConversationListSinglePagePreservesTypedCursor(t *
 	}
 }
 
+func TestCrossPlatformCoverageConversationListMaxItemsPublishesStableTruncation(t *testing.T) {
+	fake := &larkAlignmentCaller{responses: map[string]string{
+		"im/list_all_conversations": `{"result":{"conversationList":[{"openConversationId":"cid-1"}],"hasMore":true,"nextCursor":2}}`,
+	}}
+	helpers.InitDeps(fake)
+	root := newPlatformCoverageRoot()
+	var output bytes.Buffer
+	root.SetOut(&output)
+	root.SetArgs([]string{"chat", "+conversation-list", "--page-all", "--max-items", "1", "--page-delay", "0"})
+	if err := root.Execute(); err != nil {
+		t.Fatal(err)
+	}
+	var payload map[string]any
+	if err := json.Unmarshal(output.Bytes(), &payload); err != nil {
+		t.Fatal(err)
+	}
+	if payload["count"] != float64(1) || payload["truncated"] != true ||
+		payload["truncatedByResultLimit"] != true || payload["stopReason"] != "result_limit" {
+		t.Fatalf("payload = %#v", payload)
+	}
+	if len(fake.calls) != 1 || fake.calls[0].args["limit"] != 1 || payload["nextCursor"] != float64(2) {
+		t.Fatalf("unsafe continuation: calls=%#v payload=%#v", fake.calls, payload)
+	}
+}
+
+func TestCrossPlatformCoverageConversationListRejectsOversizedLimitPage(t *testing.T) {
+	fake := &larkAlignmentCaller{responses: map[string]string{
+		"im/list_all_conversations": `{"result":{"conversationList":[{"openConversationId":"cid-1"},{"openConversationId":"cid-2"}],"hasMore":true,"nextCursor":2}}`,
+	}}
+	helpers.InitDeps(fake)
+	root := newPlatformCoverageRoot()
+	var output bytes.Buffer
+	root.SetOut(&output)
+	root.SetArgs([]string{"chat", "+conversation-list", "--page-all", "--max-items", "1"})
+	if err := root.Execute(); err == nil {
+		t.Fatal("oversized lower page unexpectedly published a safe continuation")
+	}
+	var payload map[string]any
+	if err := json.Unmarshal(output.Bytes(), &payload); err != nil {
+		t.Fatal(err)
+	}
+	if payload["stopReason"] != "pagination_error" || payload["failedCount"] != float64(1) || payload["nextCursor"] != float64(0) {
+		t.Fatalf("payload = %#v", payload)
+	}
+}
+
+func TestCrossPlatformCoverageConversationListPropagatesDelayCancellation(t *testing.T) {
+	fake := &larkAlignmentCaller{responses: map[string]string{
+		"im/list_all_conversations": `{"result":{"conversationList":[{"openConversationId":"cid-1"}],"hasMore":true,"nextCursor":2}}`,
+	}}
+	helpers.InitDeps(fake)
+	root := newPlatformCoverageRoot()
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+	root.SetContext(ctx)
+	var output bytes.Buffer
+	root.SetOut(&output)
+	root.SetArgs([]string{"chat", "+conversation-list", "--page-all", "--page-delay", "1"})
+	if err := root.Execute(); err == nil || err != context.Canceled {
+		t.Fatalf("delay cancellation error = %v, want context.Canceled", err)
+	}
+	var payload map[string]any
+	if err := json.Unmarshal(output.Bytes(), &payload); err != nil {
+		t.Fatal(err)
+	}
+	if payload["stopReason"] != "delay_interrupted" || payload["failedCount"] != float64(1) {
+		t.Fatalf("payload = %#v", payload)
+	}
+}
+
+func TestCrossPlatformCoverageConversationListAutoPageValidationAndOutputFailure(t *testing.T) {
+	helpers.InitDeps(&larkAlignmentCaller{})
+	root := newPlatformCoverageRoot()
+	root.SetArgs([]string{"chat", "+conversation-list", "--max-items", "1"})
+	if err := root.Execute(); err == nil {
+		t.Fatal("max-items without page-all unexpectedly succeeded")
+	}
+
+	fake := &larkAlignmentCaller{responses: map[string]string{
+		"im/list_all_conversations": `{"result":{"conversationList":[],"hasMore":false}}`,
+	}}
+	helpers.InitDeps(fake)
+	root = newPlatformCoverageRoot()
+	root.SetOut(chatOutputErrorWriter{err: errors.New("fixture output")})
+	root.SetArgs([]string{"chat", "+conversation-list"})
+	if err := root.Execute(); err == nil {
+		t.Fatal("output error was swallowed")
+	}
+}
+
 func TestCrossPlatformCoverageConversationListDeduplicatesStableIDs(t *testing.T) {
 	fake := &larkAlignmentCaller{responses: map[string]string{
 		"im/list_all_conversations": `{"result":{"conversationList":[{"openConversationId":"cid-1","title":"一"},{"openConversationId":"cid-1","title":"重复"}],"hasMore":false}}`,

internal/shortcut/chat/chat_group.go

@@ -878,16 +878,16 @@ var ChatListAll = shortcut.Shortcut{
 			Examples:     []string{"dws chat +chat-list-all --limit 50"},
 		},
 	},
-	Flags: []shortcut.Flag{
+	Flags: append([]shortcut.Flag{
 		{Name: "limit", Type: shortcut.FlagInt, Default: "100", Desc: "每页返回数量；--limit 必须在 1-200 之间"},
 		{Name: "cursor", Type: shortcut.FlagString, Desc: "分页游标，翻页传 nextCursor"},
-		{Name: "page-all", Type: shortcut.FlagBool, Desc: "沿 nextCursor 自动读取全部已加入群；--page-limit 仅与 --page-all 一起使用且范围 1-500"},
+		{Name: "page-all", Type: shortcut.FlagBool, Desc: "沿 nextCursor 自动读取全部已加入群；--page-limit 仅与 --page-all 一起使用且范围 1-500；--max-items/--page-delay 仅与 --page-all 一起使用；值必须大于等于 0"},
 		{Name: "page-limit", Type: shortcut.FlagInt, Default: "50", Desc: "--page-limit 仅与 --page-all 一起使用且范围 1-500"},
-	},
-	Constraints: []shortcut.Constraint{
+	}, shortcut.AutoPageControlFlags()...),
+	Constraints: append([]shortcut.Constraint{
 		{Kind: shortcut.ConstraintCustom, Flags: []string{"limit"}, Description: "--limit 必须在 1-200 之间"},
 		{Kind: shortcut.ConstraintCustom, Flags: []string{"page-all", "page-limit"}, Description: "--page-limit 仅与 --page-all 一起使用且范围 1-500"},
-	},
+	}, shortcut.AutoPageControlConstraints()...),
 	Tips: []string{
 		`dws chat +chat-list-all --limit 50`,
 		`dws chat +chat-list-all --limit 200 --page-all --page-limit 50`,
@@ -908,6 +908,9 @@ func validateChatListAll(rt *shortcut.RuntimeContext) error {
 			return apperrors.NewValidation("--page-limit 必须在 1-500 之间")
 		}
 	}
+	if err := shortcut.ValidateAutoPageControls(rt); err != nil {
+		return apperrors.NewValidation(err.Error())
+	}
 	return nil
 }
 
@@ -958,10 +961,21 @@ func readAllChatListAll(rt *shortcut.RuntimeContext, baseParams map[string]any)
 	hasMore := false
 	stopReason := "source_complete"
 	truncatedByPageLimit := false
+	truncatedByResultLimit := false
 	var nextCursor any
 
 	for pagesFetched < pageLimit {
-		params := map[string]any{"limit": baseParams["limit"]}
+		if pagesFetched > 0 {
+			if err := shortcut.WaitAutoPageDelay(rt); err != nil {
+				failures = append(failures, map[string]any{
+					"page": pagesFetched + 1, "stage": "delay", "cursor": cursorKey, "error": err.Error(),
+				})
+				stopReason = "delay_interrupted"
+				break
+			}
+		}
+		pageSize, _ := baseParams["limit"].(int)
+		params := map[string]any{"limit": shortcut.AutoPageRequestSize(rt, pageSize, len(allGroups))}
 		if cursorKey != "0" {
 			params["cursor"] = cursorValue
 		}
@@ -978,6 +992,7 @@ func readAllChatListAll(rt *shortcut.RuntimeContext, baseParams map[string]any)
 		}
 		pagesFetched++
 		pageGroups := chatListAllProject(data)
+		overflowOnPage := false
 		for _, group := range pageGroups {
 			id := strings.TrimSpace(fmt.Sprint(group["openConversationId"]))
 			if id == "<nil>" {
@@ -989,6 +1004,11 @@ func readAllChatListAll(rt *shortcut.RuntimeContext, baseParams map[string]any)
 			if id != "" {
 				seenGroups[id] = true
 			}
+			if maxItems := rt.Int("max-items"); maxItems > 0 && len(allGroups) >= maxItems {
+				truncatedByResultLimit = true
+				overflowOnPage = true
+				continue
+			}
 			allGroups = append(allGroups, group)
 		}
 
@@ -1003,6 +1023,16 @@ func readAllChatListAll(rt *shortcut.RuntimeContext, baseParams map[string]any)
 			break
 		}
 		hasMore = pageHasMore
+		if overflowOnPage {
+			hasMore = true
+			nextCursor = nil
+			failures = append(failures, map[string]any{
+				"page": pagesFetched, "stage": "pagination",
+				"error": "已加入群列表下层返回条数超过请求的剩余额度，无法生成不跳项的安全续页游标",
+			})
+			stopReason = "pagination_error"
+			break
+		}
 		if !hasMore {
 			complete = true
 			nextCursor = nil
@@ -1022,8 +1052,13 @@ func readAllChatListAll(rt *shortcut.RuntimeContext, baseParams map[string]any)
 		seenCursors[nextKey] = true
 		cursorKey = nextKey
 		cursorValue = nextCursor
+		if maxItems := rt.Int("max-items"); maxItems > 0 && len(allGroups) >= maxItems {
+			truncatedByResultLimit = true
+			stopReason = "result_limit"
+			break
+		}
 	}
-	if !complete && hasMore && len(failures) == 0 && pagesFetched >= pageLimit {
+	if !complete && hasMore && len(failures) == 0 && pagesFetched >= pageLimit && !truncatedByResultLimit {
 		truncatedByPageLimit = true
 		stopReason = "page_limit"
 	}
@@ -1033,9 +1068,11 @@ func readAllChatListAll(rt *shortcut.RuntimeContext, baseParams map[string]any)
 		"pagesFetched": pagesFetched, "paginationKnown": true,
 		"complete": complete && len(failures) == 0, "hasMore": hasMore,
 		"stopReason": stopReason, "truncatedByPageLimit": truncatedByPageLimit,
-		"failedCount": len(failures), "failures": failures,
+		"truncatedByResultLimit": truncatedByResultLimit,
+		"failedCount":            len(failures), "failures": failures,
 		"partial": len(failures) > 0 && len(allGroups) > 0,
 	}
+	chatmsg.ApplyTruncation(payload)
 	if hasMore && nextCursor != nil {
 		payload["nextCursor"] = nextCursor
 	}

internal/shortcut/chat/chat_message.go

@@ -634,6 +634,7 @@ func readAllDirectMessages(rt *shortcut.RuntimeContext, params map[string]any) (
 	payload["hasMore"] = hasMore
 	payload["stopReason"] = stopReason
 	payload["truncatedByPageLimit"] = truncatedByPageLimit
+	chatmsg.ApplyTruncation(payload)
 	payload["failedCount"] = len(failures)
 	payload["failures"] = failures
 	payload["partial"] = len(failures) > 0 && len(messages) > 0

internal/shortcut/chat/flag_list_pagination_test.go

@@ -5,6 +5,7 @@ package chat
 
 import (
 	"bytes"
+	"context"
 	"encoding/json"
 	"errors"
 	"testing"
@@ -73,11 +74,115 @@ func TestCrossPlatformCoverageFlagListPageTokenAndPageLimit(t *testing.T) {
 	if err := json.Unmarshal(output.Bytes(), &payload); err != nil {
 		t.Fatal(err)
 	}
-	if payload["complete"] != false || payload["nextCursor"] != float64(9) || payload["truncatedByPageLimit"] != true || payload["stopReason"] != "page_limit" {
+	if payload["complete"] != false || payload["nextCursor"] != float64(9) || payload["truncated"] != true || payload["truncatedByPageLimit"] != true || payload["stopReason"] != "page_limit" {
 		t.Fatalf("payload = %#v", payload)
 	}
 }
 
+func TestCrossPlatformCoverageFlagListMaxItemsPublishesStableTruncation(t *testing.T) {
+	fake := &larkAlignmentCaller{responses: map[string]string{
+		"im/list_message_favorites": `{"result":{"items":[{"openMessageId":"msg-1"}],"hasMore":true,"nextCursor":9}}`,
+	}}
+	helpers.InitDeps(fake)
+	root := newPlatformCoverageRoot()
+	var output bytes.Buffer
+	root.SetOut(&output)
+	root.SetArgs([]string{"chat", "+flag-list", "--page-all", "--max-items", "1", "--page-delay", "0"})
+	if err := root.Execute(); err != nil {
+		t.Fatal(err)
+	}
+	var payload map[string]any
+	if err := json.Unmarshal(output.Bytes(), &payload); err != nil {
+		t.Fatal(err)
+	}
+	if payload["count"] != float64(1) || payload["truncated"] != true ||
+		payload["truncatedByResultLimit"] != true || payload["stopReason"] != "result_limit" {
+		t.Fatalf("payload = %#v", payload)
+	}
+	if len(fake.calls) != 1 || fake.calls[0].args["size"] != "1" || payload["nextCursor"] != float64(9) {
+		t.Fatalf("unsafe continuation: calls=%#v payload=%#v", fake.calls, payload)
+	}
+}
+
+func TestCrossPlatformCoverageFlagListLegacyFullRemainingPageFailsClosed(t *testing.T) {
+	fake := &larkAlignmentCaller{sequenceResponses: map[string][]string{
+		"im/list_message_favorites": {
+			`{"result":{"items":[{"openMessageId":"m1"},{"openMessageId":"m2"}],"hasMore":true,"nextCursor":7}}`,
+			`{"result":{"items":[{"openMessageId":"m3"}]}}`,
+		},
+	}}
+	helpers.InitDeps(fake)
+	root := newPlatformCoverageRoot()
+	var output bytes.Buffer
+	root.SetOut(&output)
+	root.SetArgs([]string{"chat", "+flag-list", "--page-size", "2", "--page-all", "--max-items", "3"})
+	if err := root.Execute(); err == nil {
+		t.Fatal("full remaining-budget legacy page unexpectedly declared a complete result")
+	}
+	if len(fake.calls) != 2 || fake.calls[0].args["size"] != "2" || fake.calls[1].args["size"] != "1" {
+		t.Fatalf("request sizes = %#v", fake.calls)
+	}
+	var payload map[string]any
+	if err := json.Unmarshal(output.Bytes(), &payload); err != nil {
+		t.Fatal(err)
+	}
+	if payload["count"] != float64(3) || payload["complete"] != false ||
+		payload["paginationKnown"] != false || payload["stopReason"] != "pagination_error" ||
+		payload["failedCount"] != float64(1) || payload["nextCursor"] != float64(0) {
+		t.Fatalf("payload = %#v", payload)
+	}
+}
+
+func TestCrossPlatformCoverageFlagListFailsClosedOnOversizeAndCanceledDelay(t *testing.T) {
+	t.Run("oversized lower page", func(t *testing.T) {
+		fake := &larkAlignmentCaller{responses: map[string]string{
+			"im/list_message_favorites": `{"result":{"items":[{"openMessageId":"m1"},{"openMessageId":"m2"}],"hasMore":true,"nextCursor":9}}`,
+		}}
+		helpers.InitDeps(fake)
+		root := newPlatformCoverageRoot()
+		var output bytes.Buffer
+		root.SetOut(&output)
+		root.SetArgs([]string{"chat", "+flag-list", "--page-all", "--max-items", "1"})
+		if err := root.Execute(); err == nil {
+			t.Fatal("oversized lower page unexpectedly published a continuation")
+		}
+		var payload map[string]any
+		if err := json.Unmarshal(output.Bytes(), &payload); err != nil {
+			t.Fatal(err)
+		}
+		if payload["stopReason"] != "pagination_error" || payload["failedCount"] != float64(1) || payload["nextCursor"] != float64(0) {
+			t.Fatalf("payload = %#v", payload)
+		}
+		if len(fake.calls) != 1 || fake.calls[0].args["size"] != "1" {
+			t.Fatalf("calls = %#v", fake.calls)
+		}
+	})
+
+	t.Run("canceled delay", func(t *testing.T) {
+		fake := &larkAlignmentCaller{responses: map[string]string{
+			"im/list_message_favorites": `{"result":{"items":[{"openMessageId":"m1"}],"hasMore":true,"nextCursor":9}}`,
+		}}
+		helpers.InitDeps(fake)
+		root := newPlatformCoverageRoot()
+		ctx, cancel := context.WithCancel(context.Background())
+		cancel()
+		root.SetContext(ctx)
+		var output bytes.Buffer
+		root.SetOut(&output)
+		root.SetArgs([]string{"chat", "+flag-list", "--page-all", "--page-delay", "1"})
+		if err := root.Execute(); err == nil {
+			t.Fatal("canceled delay unexpectedly succeeded")
+		}
+		var payload map[string]any
+		if err := json.Unmarshal(output.Bytes(), &payload); err != nil {
+			t.Fatal(err)
+		}
+		if payload["stopReason"] != "delay_interrupted" || payload["failedCount"] != float64(1) {
+			t.Fatalf("payload = %#v", payload)
+		}
+	})
+}
+
 func TestCrossPlatformCoverageFlagListFailureModes(t *testing.T) {
 	t.Run("later read failure keeps partial result", func(t *testing.T) {
 		fake := &larkAlignmentCaller{
@@ -137,7 +242,11 @@ func TestCrossPlatformCoverageFlagListPaginationValidation(t *testing.T) {
 		{"--size", "31"},
 		{"--page-token", "not-a-number"},
 		{"--page-limit", "2"},
+		{"--max-items", "1"},
+		{"--page-delay", "1"},
 		{"--page-all", "--page-limit", "0"},
+		{"--page-all", "--max-items", "-1"},
+		{"--page-all", "--page-delay", "-1"},
 		{"--page-all", "--page-limit", "501"},
 		{"--cursor", "1", "--page-token", "2"},
 	} {

internal/shortcut/chat/lark_alignment.go

@@ -510,21 +510,21 @@ var FlagList = shortcut.Shortcut{
 	Description: "分页查询当前用户收藏的消息，支持有界自动翻页",
 	Intent:      "当你要查看当前用户的 DingTalk message favorite 列表时使用；默认读取一页，明确要求全部收藏时加 --page-all，并用 --page-limit 保持有界。底层实际使用数字 cursor，结果按 openMessageId 去重并公开 complete、hasMore、nextCursor、stopReason 和 failures；它不把 message favorite 与 Pin、会话置顶或 Lark feed-layer thread flag 混为一谈。",
 	Risk:        shortcut.RiskRead,
-	Flags: []shortcut.Flag{
+	Flags: append([]shortcut.Flag{
 		{Name: "page-size", Type: shortcut.FlagInt, Default: "20", Desc: "每页数量；下游真实上限为 30，显式页大小必须在 1-30 之间"},
 		{Name: "size", Type: shortcut.FlagInt, Default: "20", Desc: "--page-size 的兼容别名；下游真实上限为 30，显式页大小必须在 1-30 之间"},
 		{Name: "page-token", Type: shortcut.FlagString, Desc: "Lark 对齐的起始分页参数；起始 cursor 必须是非负整数"},
 		{Name: "cursor", Type: shortcut.FlagInt, Default: "0", Desc: "钉钉数字分页游标；起始 cursor 必须是非负整数"},
-		{Name: "page-all", Type: shortcut.FlagBool, Desc: "自动读取全部收藏分页；--page-limit 仅与 --page-all 一起使用且范围 1-500"},
+		{Name: "page-all", Type: shortcut.FlagBool, Desc: "自动读取全部收藏分页；--page-limit 仅与 --page-all 一起使用且范围 1-500；--max-items/--page-delay 仅与 --page-all 一起使用；值必须大于等于 0"},
 		{Name: "page-limit", Type: shortcut.FlagInt, Default: "20", Desc: "--page-limit 仅与 --page-all 一起使用且范围 1-500"},
-	},
-	Constraints: []shortcut.Constraint{
+	}, shortcut.AutoPageControlFlags()...),
+	Constraints: append([]shortcut.Constraint{
 		{Kind: shortcut.ConstraintMutuallyExclusive, Flags: []string{"page-size", "size"}},
 		{Kind: shortcut.ConstraintMutuallyExclusive, Flags: []string{"page-token", "cursor"}},
 		{Kind: shortcut.ConstraintCustom, Flags: []string{"page-size", "size"}, Description: "显式页大小必须在 1-30 之间"},
 		{Kind: shortcut.ConstraintCustom, Flags: []string{"page-token", "cursor"}, Description: "起始 cursor 必须是非负整数"},
 		{Kind: shortcut.ConstraintCustom, Flags: []string{"page-all", "page-limit"}, Description: "--page-limit 仅与 --page-all 一起使用且范围 1-500"},
-	},
+	}, shortcut.AutoPageControlConstraints()...),
 	Tips: []string{
 		`dws chat +flag-list --cursor 0 --page-size 20`,
 		`dws chat +flag-list --page-size 30 --page-all --page-limit 20`,
@@ -548,6 +548,9 @@ func validateFlagList(rt *shortcut.RuntimeContext) error {
 			return apperrors.NewValidation("--page-limit 必须在 1-500 之间")
 		}
 	}
+	if err := shortcut.ValidateAutoPageControls(rt); err != nil {
+		return apperrors.NewValidation(err.Error())
+	}
 	return nil
 }
 
@@ -598,9 +601,20 @@ func executeFlagList(rt *shortcut.RuntimeContext) error {
 	var cursorErr error
 	stopReason := "source_complete"
 	truncatedByPageLimit := false
+	truncatedByResultLimit := false
 
 	for pagesFetched < pageLimit {
-		data, callErr := rt.CallMCPData("im", "list_message_favorites", flagListRequestParams(cursor, pageSize))
+		if pagesFetched > 0 {
+			if err := shortcut.WaitAutoPageDelay(rt); err != nil {
+				failures = append(failures, map[string]any{
+					"page": pagesFetched + 1, "stage": "delay", "cursor": cursor, "error": err.Error(),
+				})
+				stopReason = "delay_interrupted"
+				break
+			}
+		}
+		requestPageSize := shortcut.AutoPageRequestSize(rt, pageSize, len(items))
+		data, callErr := rt.CallMCPData("im", "list_message_favorites", flagListRequestParams(cursor, requestPageSize))
 		if callErr != nil {
 			if pagesFetched == 0 {
 				return callErr
@@ -613,6 +627,7 @@ func executeFlagList(rt *shortcut.RuntimeContext) error {
 		}
 		pagesFetched++
 		pageItems := flagListItems(data)
+		overflowOnPage := false
 		for _, item := range pageItems {
 			messageID := firstNonEmptyMapString(item, "openMessageId", "messageId", "itemId", "id")
 			if messageID != "" && seenMessages[messageID] {
@@ -621,6 +636,11 @@ func executeFlagList(rt *shortcut.RuntimeContext) error {
 			if messageID != "" {
 				seenMessages[messageID] = true
 			}
+			if maxItems := rt.Int("max-items"); maxItems > 0 && len(items) >= maxItems {
+				truncatedByResultLimit = true
+				overflowOnPage = true
+				continue
+			}
 			items = append(items, item)
 		}
 
@@ -631,7 +651,7 @@ func executeFlagList(rt *shortcut.RuntimeContext) error {
 			switch {
 			case nextCursor > 0:
 				pageHasMore = true
-			case len(pageItems) < pageSize:
+			case len(pageItems) < requestPageSize:
 				paginationKnown = false
 				complete = true
 				hasMore = false
@@ -649,6 +669,16 @@ func executeFlagList(rt *shortcut.RuntimeContext) error {
 			}
 		}
 		hasMore = pageHasMore
+		if overflowOnPage {
+			hasMore = true
+			nextCursor = 0
+			failures = append(failures, map[string]any{
+				"page": pagesFetched, "stage": "pagination",
+				"error": "收藏列表下层返回条数超过请求的剩余额度，无法生成不跳项的安全续页游标",
+			})
+			stopReason = "pagination_error"
+			break
+		}
 		if !hasMore {
 			complete = true
 			nextCursor = 0
@@ -669,28 +699,35 @@ func executeFlagList(rt *shortcut.RuntimeContext) error {
 		}
 		seenCursors[nextCursor] = true
 		cursor = nextCursor
+		if maxItems := rt.Int("max-items"); maxItems > 0 && len(items) >= maxItems {
+			truncatedByResultLimit = true
+			stopReason = "result_limit"
+			break
+		}
 	}
 
-	if !complete && hasMore && len(failures) == 0 && pagesFetched >= pageLimit {
+	if !complete && hasMore && len(failures) == 0 && pagesFetched >= pageLimit && !truncatedByResultLimit {
 		truncatedByPageLimit = rt.Bool("page-all")
 		if truncatedByPageLimit {
 			stopReason = "page_limit"
 		}
 	}
 	payload := map[string]any{
-		"count":                len(items),
-		"items":                items,
-		"pagesFetched":         pagesFetched,
-		"paginationKnown":      paginationKnown,
-		"complete":             complete && len(failures) == 0,
-		"hasMore":              hasMore,
-		"nextCursor":           nextCursor,
-		"stopReason":           stopReason,
-		"truncatedByPageLimit": truncatedByPageLimit,
-		"failedCount":          len(failures),
-		"failures":             failures,
-		"partial":              len(failures) > 0 && len(items) > 0,
+		"count":                  len(items),
+		"items":                  items,
+		"pagesFetched":           pagesFetched,
+		"paginationKnown":        paginationKnown,
+		"complete":               complete && len(failures) == 0,
+		"hasMore":                hasMore,
+		"nextCursor":             nextCursor,
+		"stopReason":             stopReason,
+		"truncatedByPageLimit":   truncatedByPageLimit,
+		"truncatedByResultLimit": truncatedByResultLimit,
+		"failedCount":            len(failures),
+		"failures":               failures,
+		"partial":                len(failures) > 0 && len(items) > 0,
 	}
+	chatmsg.ApplyTruncation(payload)
 	if outputErr := rt.Output(payload); outputErr != nil {
 		return outputErr
 	}

internal/shortcut/chat/remaining_read_pagination_test.go

@@ -5,12 +5,14 @@ package chat
 
 import (
 	"bytes"
+	"context"
 	"encoding/json"
 	"errors"
 	"testing"
 	"time"
 
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/helpers"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut"
 )
 
 func TestCrossPlatformCoverageChatListAllPageAllUsesNumericCursorAndDeduplicates(t *testing.T) {
@@ -95,11 +97,86 @@ func TestCrossPlatformCoverageDirectMessagesPageLimitPublishesExecutableContinua
 		t.Fatal(err)
 	}
 	if payload["complete"] != false || payload["hasMore"] != true ||
-		payload["truncatedByPageLimit"] != true || payload["stopReason"] != "page_limit" || payload["nextPage"] == nil {
+		payload["truncated"] != true || payload["truncatedByPageLimit"] != true || payload["stopReason"] != "page_limit" || payload["nextPage"] == nil {
 		t.Fatalf("payload = %#v", payload)
 	}
 }
 
+func TestCrossPlatformCoverageChatListAllMaxItemsPublishesStableTruncation(t *testing.T) {
+	fake := &larkAlignmentCaller{responses: map[string]string{
+		"im/list_my_groups_pagination": `{"result":{"groups":[{"openConversationId":"g1"}],"hasMore":true,"nextCursor":88}}`,
+	}}
+	helpers.InitDeps(fake)
+	root := newPlatformCoverageRoot()
+	var output bytes.Buffer
+	root.SetOut(&output)
+	root.SetArgs([]string{"chat", "+chat-list-all", "--page-all", "--max-items", "1", "--page-delay", "0"})
+	if err := root.Execute(); err != nil {
+		t.Fatal(err)
+	}
+	var payload map[string]any
+	if err := json.Unmarshal(output.Bytes(), &payload); err != nil {
+		t.Fatal(err)
+	}
+	if payload["count"] != float64(1) || payload["truncated"] != true ||
+		payload["truncatedByResultLimit"] != true || payload["stopReason"] != "result_limit" {
+		t.Fatalf("payload = %#v", payload)
+	}
+	if len(fake.calls) != 1 || fake.calls[0].args["limit"] != 1 || payload["nextCursor"] != float64(88) {
+		t.Fatalf("unsafe continuation: calls=%#v payload=%#v", fake.calls, payload)
+	}
+}
+
+func TestCrossPlatformCoverageChatListAllFailsClosedOnOversizeAndCanceledDelay(t *testing.T) {
+	t.Run("oversized lower page", func(t *testing.T) {
+		fake := &larkAlignmentCaller{responses: map[string]string{
+			"im/list_my_groups_pagination": `{"result":{"groups":[{"openConversationId":"g1"},{"openConversationId":"g2"}],"hasMore":true,"nextCursor":88}}`,
+		}}
+		helpers.InitDeps(fake)
+		root := newPlatformCoverageRoot()
+		var output bytes.Buffer
+		root.SetOut(&output)
+		root.SetArgs([]string{"chat", "+chat-list-all", "--page-all", "--max-items", "1"})
+		if err := root.Execute(); err == nil {
+			t.Fatal("oversized lower page unexpectedly published a continuation")
+		}
+		var payload map[string]any
+		if err := json.Unmarshal(output.Bytes(), &payload); err != nil {
+			t.Fatal(err)
+		}
+		if payload["stopReason"] != "pagination_error" || payload["failedCount"] != float64(1) {
+			t.Fatalf("payload = %#v", payload)
+		}
+		if len(fake.calls) != 1 || fake.calls[0].args["limit"] != 1 || payload["nextCursor"] != nil {
+			t.Fatalf("unsafe continuation: calls=%#v payload=%#v", fake.calls, payload)
+		}
+	})
+
+	t.Run("canceled delay", func(t *testing.T) {
+		fake := &larkAlignmentCaller{responses: map[string]string{
+			"im/list_my_groups_pagination": `{"result":{"groups":[{"openConversationId":"g1"}],"hasMore":true,"nextCursor":88}}`,
+		}}
+		helpers.InitDeps(fake)
+		root := newPlatformCoverageRoot()
+		ctx, cancel := context.WithCancel(context.Background())
+		cancel()
+		root.SetContext(ctx)
+		var output bytes.Buffer
+		root.SetOut(&output)
+		root.SetArgs([]string{"chat", "+chat-list-all", "--page-all", "--page-delay", "1"})
+		if err := root.Execute(); err == nil {
+			t.Fatal("canceled delay unexpectedly succeeded")
+		}
+		var payload map[string]any
+		if err := json.Unmarshal(output.Bytes(), &payload); err != nil {
+			t.Fatal(err)
+		}
+		if payload["stopReason"] != "delay_interrupted" || payload["failedCount"] != float64(1) {
+			t.Fatalf("payload = %#v", payload)
+		}
+	})
+}
+
 func TestCrossPlatformCoverageDirectMessagesPageAllFailsClosedWithoutMillisecondCursor(t *testing.T) {
 	fake := &larkAlignmentCaller{responses: map[string]string{
 		"chat/list_individual_chat_message": `{"result":{"messages":[{"openMessageId":"m1"}],"hasMore":true}}`,
@@ -163,6 +240,17 @@ func TestCrossPlatformCoverageChatRemainingPaginationValidation(t *testing.T) {
 			t.Fatalf("invalid args succeeded: %v", args)
 		}
 	}
+	root := newPlatformCoverageRoot()
+	cmd, _, err := root.Find([]string{"chat", "+chat-list-all"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := cmd.Flags().Set("max-items", "1"); err != nil {
+		t.Fatal(err)
+	}
+	if err := validateChatListAll(shortcut.RuntimeContextForTest(cmd, ChatListAll)); err == nil {
+		t.Fatal("direct auto-page validation unexpectedly succeeded")
+	}
 }
 
 func TestCrossPlatformCoverageChatListAllAdditionalEdges(t *testing.T) {

internal/shortcut/chatmsg/chatmsg.go

@@ -86,6 +86,7 @@ var messageResultContractV1 = MessageResultContract{
 		"hasMore",
 		"nextPage",
 		"stopReason",
+		"truncated",
 		"truncatedByPageLimit",
 		"truncatedByResultLimit",
 		"failedCount",
@@ -122,9 +123,21 @@ func NewMessageListPayload(messages []map[string]any) map[string]any {
 		"failedCount":     0,
 		"failures":        []map[string]any{},
 		"partial":         false,
+		"truncated":       false,
 	}
 }
 
+// ApplyTruncation publishes the stable aggregate bit while preserving the
+// established reason-specific fields for compatibility and diagnosis.
+func ApplyTruncation(payload map[string]any) {
+	if payload == nil {
+		return
+	}
+	byPage, _ := payload["truncatedByPageLimit"].(bool)
+	byItems, _ := payload["truncatedByResultLimit"].(bool)
+	payload["truncated"] = byPage || byItems
+}
+
 // ListMessageItems returns message rows from the common list response envelopes.
 func ListMessageItems(data map[string]any) []map[string]any {
 	if data == nil {

internal/shortcut/chatmsg/chatmsg_test.go

@@ -441,6 +441,7 @@ func TestCrossPlatformCoverageReactionsNormalizesEmotionReplyList(t *testing.T)
 }
 
 func TestCrossPlatformCoverageApplyPaginationReadsNestedEnvelope(t *testing.T) {
+	ApplyTruncation(nil)
 	payload := map[string]any{"count": 98}
 	ApplyPagination(payload, map[string]any{
 		"result": map[string]any{

internal/shortcut/drive/catalog_operations.go

@@ -0,0 +1,538 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0
+
+package drive
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+	"time"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/helpers"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut"
+)
+
+var uploadDriveFile = helpers.UploadDriveFileData
+
+var driveRestoreWait = time.Sleep
+
+var (
+	driveGetwd        = os.Getwd
+	driveEvalSymlinks = filepath.EvalSymlinks
+	driveRel          = filepath.Rel
+	driveStat         = os.Stat
+)
+
+var RecycleList = shortcut.Shortcut{
+	Service: "drive", Command: "+recycle-list", Product: "drive",
+	Description: "严格分页列出钉盘回收站",
+	Intent:      "查找可恢复的回收项并获取 recycleItemId 时使用。",
+	Risk:        shortcut.RiskRead,
+	Safety:      contract.SafetySpec{Effect: "read", Risk: "low", Confirmation: "not_required", Idempotency: "idempotent"},
+	Contract: driveContract(
+		"+recycle-list", "严格分页列出钉盘回收站",
+		"查找可恢复的回收项并获取 recycleItemId 时使用。",
+		[]string{"恢复前必须先确认具体回收项；普通目录浏览使用 drive +list"},
+		[]string{`dws drive +recycle-list --limit 20`},
+		driveCollectionResult("items", "严格校验的回收站条目页"), driveCursorPagination(),
+		contract.ParamDecl{Name: "cursor", Property: "nextCursor"},
+	),
+	Flags: []shortcut.Flag{
+		{Name: "space-id", Type: shortcut.FlagString, Desc: "钉盘空间 ID"},
+		{Name: "limit", Type: shortcut.FlagInt, Default: "20", Desc: "每页数量"},
+		{Name: "cursor", Type: shortcut.FlagString, Desc: "分页游标"},
+	},
+	Tips: []string{`dws drive +recycle-list --limit 20`},
+	Execute: func(rt *shortcut.RuntimeContext) error {
+		params := map[string]any{"maxResults": rt.Int("limit")}
+		if rt.Str("space-id") != "" {
+			params["spaceId"] = rt.Str("space-id")
+		}
+		if rt.Str("cursor") != "" {
+			params["nextCursor"] = rt.Str("cursor")
+		}
+		data, err := rt.CallMCPData("drive", "list_recycle_items", params)
+		if err != nil {
+			return err
+		}
+		items, page, err := requireDriveCollection(data, "drive/list_recycle_items", "recycleItems")
+		if err != nil {
+			return err
+		}
+		rows := projectDriveRows(items, map[string][]string{
+			"recycleItemId": {"recycleItemId", "id"},
+			"originalName":  {"originalName", "name", "fileName", "title"},
+			"originalPath":  {"originalPath", "path"},
+			"type":          {"type", "fileType", "nodeType", "contentType"},
+			"deleteTime":    {"operatorTime", "deleteTime", "deletedTime", "recycleTime"},
+			"fileSize":      {"fileSize", "size"},
+		})
+		out := map[string]any{"count": len(rows), "items": rows}
+		addDrivePagination(out, page)
+		return rt.Output(out)
+	},
+}
+
+var RecycleRestore = shortcut.Shortcut{
+	Service: "drive", Command: "+recycle-restore", Product: "drive",
+	Description: "恢复已确认的回收站条目并读回节点",
+	Intent:      "已经通过 drive +recycle-list 确认回收项，并明确要求恢复时使用。",
+	Risk:        shortcut.RiskWrite,
+	Safety:      contract.SafetySpec{Effect: "write", Risk: "medium", Confirmation: "user_required", Idempotency: "unknown"},
+	Contract: driveContract(
+		"+recycle-restore", "恢复已确认的回收站条目并读回节点",
+		"已经通过 drive +recycle-list 确认回收项，并明确要求恢复时使用。",
+		[]string{"尚未确认回收项时先列表；不要把原节点 ID 当 recycleItemId"},
+		[]string{`dws drive +recycle-restore --id <recycleItemId>`},
+		driveObjectResult("恢复并读回验证后的节点"), nil,
+		contract.ParamDecl{Name: "id", Property: "recycleItemId"},
+	),
+	Flags: []shortcut.Flag{
+		{Name: "id", Type: shortcut.FlagString, Desc: "回收项 ID", Required: true},
+	},
+	Tips: []string{`dws drive +recycle-restore --id <recycleItemId>`},
+	Execute: func(rt *shortcut.RuntimeContext) error {
+		recycleItem, err := findDriveRecycleItem(rt, rt.Str("id"))
+		if err != nil {
+			return err
+		}
+		written, err := rt.CallMCPWriteDataStrict("drive", "restore_recycle_item", map[string]any{"recycleItemId": rt.Str("id")})
+		if err != nil {
+			return err
+		}
+		if _, err := requireDriveWrite(written, "drive/restore_recycle_item"); err != nil {
+			return err
+		}
+		nodeID := nestedString(written, "fileId", "nodeId", "dentryUuid", "id")
+		if nodeID == "" {
+			nodeID, err = findRestoredDriveNode(rt, recycleItem)
+			if err != nil {
+				return err
+			}
+		}
+		verified, err := rt.CallMCPData("drive", "get_file_info", map[string]any{"fileId": nodeID})
+		if err != nil {
+			return err
+		}
+		verified, err = requireDriveObject(verified, "drive/get_file_info")
+		if err != nil {
+			return err
+		}
+		return rt.Output(map[string]any{"success": true, "nodeId": nodeID, "file": verified})
+	},
+}
+
+func findDriveRecycleItem(rt *shortcut.RuntimeContext, recycleItemID string) (map[string]any, error) {
+	params := map[string]any{"maxResults": 50}
+	for pageNumber := 0; pageNumber < 20; pageNumber++ {
+		data, err := rt.CallMCPData("drive", "list_recycle_items", params)
+		if err != nil {
+			return nil, err
+		}
+		items, page, err := requireDriveCollection(data, "drive/list_recycle_items", "recycleItems")
+		if err != nil {
+			return nil, err
+		}
+		for _, item := range items {
+			entry := item.(map[string]any)
+			if nestedString(entry, "recycleItemId", "id") == recycleItemID {
+				return entry, nil
+			}
+		}
+		nextCursor := nestedString(page, "nextCursor", "nextToken", "nextPageToken")
+		hasMore, hasMorePresent := boolField(page, "hasMore")
+		if nextCursor == "" || (hasMorePresent && !hasMore) {
+			break
+		}
+		params["nextCursor"] = nextCursor
+	}
+	return nil, driveResponseError("drive/list_recycle_items", "recycle_item_not_found", "回收站中没有找到指定 recycleItemId；未执行恢复")
+}
+
+func findRestoredDriveNode(rt *shortcut.RuntimeContext, recycleItem map[string]any) (string, error) {
+	name := nestedString(recycleItem, "originalName", "name", "fileName", "title")
+	if name == "" {
+		return "", driveResponseError("drive/restore_recycle_item", "missing_restored_identity", "恢复响应没有节点 ID，且恢复前回收项没有名称，无法安全读回终态")
+	}
+	searchName := name
+	if extension := filepath.Ext(name); extension != "" {
+		searchName = strings.TrimSuffix(name, extension)
+	}
+	originalPath := nestedString(recycleItem, "originalPath", "path")
+	for attempt := 0; attempt < 4; attempt++ {
+		if attempt > 0 {
+			driveRestoreWait(750 * time.Millisecond)
+		}
+		if originalPath != "" {
+			if nodeID, found, err := findRestoredDriveNodeAtOriginalPath(rt, originalPath, name); err != nil {
+				return "", err
+			} else if found {
+				return nodeID, nil
+			}
+		}
+		data, err := rt.CallMCPData("drive", "search_files", map[string]any{"keyword": searchName, "pageSize": 30})
+		if err != nil {
+			return "", err
+		}
+		items, _, err := requireDriveCollection(data, "drive/search_files", "items", "files", "dentries", "entries", "nodes", "list")
+		if err != nil {
+			return "", err
+		}
+		candidates := make([]string, 0, 1)
+		for _, item := range items {
+			entry := item.(map[string]any)
+			entryName := nestedString(entry, "name", "fileName", "dentryName", "title")
+			entryExtension := strings.TrimPrefix(nestedString(entry, "extension", "fileExtension", "ext"), ".")
+			fullEntryName := entryName
+			if entryExtension != "" && filepath.Ext(entryName) == "" {
+				fullEntryName += "." + entryExtension
+			}
+			if entryName != name && fullEntryName != name && entryName != searchName {
+				continue
+			}
+			if originalPath != "" {
+				path := nestedString(entry, "path", "originalPath")
+				if path != "" && path != originalPath {
+					continue
+				}
+			}
+			if id := nestedString(entry, "fileId", "dentryUuid", "nodeId", "id"); id != "" {
+				candidates = append(candidates, id)
+			}
+		}
+		if len(candidates) == 1 {
+			return candidates[0], nil
+		}
+		if len(candidates) > 1 {
+			return "", driveResponseError("drive/restore_recycle_item", "restored_node_ambiguous", "服务端已接受恢复，但按原名称找到多个节点，无法唯一确认恢复终态；请用 +list 核对")
+		}
+	}
+	return "", driveResponseError("drive/restore_recycle_item", "restored_node_not_found", "服务端已接受恢复，但没有返回节点 ID，且在有界等待后仍按原名称搜索不到恢复后的节点；远端效果未知，请先用 +list 确认")
+}
+
+func findRestoredDriveNodeAtOriginalPath(rt *shortcut.RuntimeContext, originalPath, name string) (string, bool, error) {
+	parentName := filepath.Base(filepath.Dir(originalPath))
+	if parentName == "." || parentName == string(filepath.Separator) || parentName == "" {
+		return "", false, nil
+	}
+	data, err := rt.CallMCPData("drive", "search_files", map[string]any{"keyword": parentName, "pageSize": 30})
+	if err != nil {
+		return "", false, err
+	}
+	items, _, err := requireDriveCollection(data, "drive/search_files", "items", "files", "dentries", "entries", "nodes", "list")
+	if err != nil {
+		return "", false, err
+	}
+	parentIDs := make([]string, 0, 1)
+	for _, item := range items {
+		entry := item.(map[string]any)
+		if nestedString(entry, "name", "fileName", "dentryName", "title") != parentName {
+			continue
+		}
+		if id := nestedString(entry, "fileId", "dentryUuid", "nodeId", "id"); id != "" {
+			parentIDs = append(parentIDs, id)
+		}
+	}
+	if len(parentIDs) != 1 {
+		return "", false, nil
+	}
+	data, err = rt.CallMCPData("drive", "list_files", map[string]any{"parentId": parentIDs[0], "maxResults": 50})
+	if err != nil {
+		return "", false, err
+	}
+	items, _, err = requireDriveCollection(data, "drive/list_files", "items", "files", "dentries", "entries", "nodes", "list")
+	if err != nil {
+		return "", false, err
+	}
+	var nodeID string
+	for _, item := range items {
+		entry := item.(map[string]any)
+		if nestedString(entry, "name", "fileName", "dentryName", "title") != name {
+			continue
+		}
+		if nodeID != "" {
+			return "", false, driveResponseError("drive/list_files", "restored_node_ambiguous", "恢复后的原目录中存在多个同名节点，无法唯一确认终态")
+		}
+		nodeID = nestedString(entry, "fileId", "dentryUuid", "nodeId", "id")
+	}
+	return nodeID, nodeID != "", nil
+}
+
+var StarList = shortcut.Shortcut{
+	Service: "drive", Command: "+star-list", Product: "drive",
+	Description: "严格分页列出当前用户收藏",
+	Intent:      "浏览当前用户收藏并获取后续可操作节点 ID 时使用。",
+	Risk:        shortcut.RiskRead,
+	Safety:      contract.SafetySpec{Effect: "read", Risk: "low", Confirmation: "not_required", Idempotency: "idempotent"},
+	Contract: driveContract(
+		"+star-list", "严格分页列出当前用户收藏",
+		"浏览当前用户收藏并获取后续可操作节点 ID 时使用。",
+		[]string{"最近访问使用 drive +recent；目录浏览使用 drive +list"},
+		[]string{`dws drive +star-list --limit 20`},
+		driveCollectionResult("items", "严格校验的收藏条目页"), driveCursorPagination(),
+		contract.ParamDecl{Name: "cursor", Property: "cursor"},
+	),
+	Flags: []shortcut.Flag{
+		{Name: "limit", Type: shortcut.FlagInt, Default: "20", Desc: "每页数量"},
+		{Name: "cursor", Type: shortcut.FlagString, Desc: "分页游标"},
+		{Name: "content-types", Type: shortcut.FlagStringSlice, Desc: "内容类型过滤"},
+	},
+	Tips: []string{`dws drive +star-list --limit 20`},
+	Execute: func(rt *shortcut.RuntimeContext) error {
+		params := map[string]any{"limit": rt.Int("limit")}
+		if rt.Str("cursor") != "" {
+			params["cursor"] = rt.Str("cursor")
+		}
+		if values := rt.StrSlice("content-types"); len(values) > 0 {
+			params["contentTypes"] = values
+		}
+		data, err := rt.CallMCPData("drive", "get_star_list", params)
+		if err != nil {
+			return err
+		}
+		items, page, err := requireDriveCollection(data, "drive/get_star_list", "starList")
+		if err != nil {
+			return err
+		}
+		rows := projectDriveRows(items, map[string][]string{
+			"nodeId":     {"nodeId", "fileId", "dentryUuid", "id"},
+			"name":       {"name", "fileName", "title"},
+			"type":       {"type", "contentType", "nodeType"},
+			"createTime": {"createTime", "starTime"},
+		})
+		out := map[string]any{"count": len(rows), "items": rows}
+		addDrivePagination(out, page)
+		return rt.Output(out)
+	},
+}
+
+var StarAdd = starMutationShortcut("+star-add", "收藏指定节点", "mark_star", "将指定文件或文档加入当前用户收藏。")
+var StarRemove = starMutationShortcut("+star-remove", "取消收藏指定节点", "unmark_star", "将指定文件或文档从当前用户收藏移除。")
+
+func starMutationShortcut(command, description, tool, useWhen string) shortcut.Shortcut {
+	return shortcut.Shortcut{
+		Service: "drive", Command: command, Product: "drive", Description: description, Intent: useWhen,
+		Risk: shortcut.RiskWrite, Safety: contract.SafetySpec{Effect: "write", Risk: "low", Confirmation: "not_required", Idempotency: "idempotent"},
+		Contract: driveContract(command, description, useWhen,
+			[]string{"查看收藏状态和列表使用 drive +star-list"},
+			[]string{fmt.Sprintf("dws drive %s --node <dentryUuid>", command)},
+			driveObjectResult(description+"的终态证据"), nil, contract.ParamDecl{Name: "node", Property: "nodeId"}),
+		Flags: []shortcut.Flag{{Name: "node", Type: shortcut.FlagString, Desc: "节点 ID", Required: true}},
+		Tips:  []string{fmt.Sprintf("dws drive %s --node <dentryUuid>", command)},
+		Execute: func(rt *shortcut.RuntimeContext) error {
+			written, err := rt.CallMCPWriteDataStrict("drive", tool, map[string]any{"nodeId": rt.Str("node")})
+			if err != nil {
+				return err
+			}
+			written, err = requireDriveWrite(written, "drive/"+tool)
+			if err != nil {
+				return err
+			}
+			return rt.Output(map[string]any{"success": true, "nodeId": rt.Str("node"), "result": written})
+		},
+	}
+}
+
+var PublishGet = shortcut.Shortcut{
+	Service: "drive", Command: "+publish-get", Product: "drive",
+	Description: "查询文件互联网公开状态",
+	Intent:      "查询文件当前互联网公开状态和权限时使用。",
+	Risk:        shortcut.RiskRead,
+	Safety:      contract.SafetySpec{Effect: "read", Risk: "low", Confirmation: "not_required", Idempotency: "idempotent"},
+	Contract: driveContract(
+		"+publish-get", "查询文件互联网公开状态", "查询文件当前互联网公开状态和权限时使用。",
+		[]string{"开启或关闭公开分别使用 drive +publish-set / +publish-unset"},
+		[]string{`dws drive +publish-get --node <dentryUuid>`}, driveObjectResult("互联网公开状态"), nil,
+		contract.ParamDecl{Name: "node", Property: "fileId"},
+	),
+	Flags: []shortcut.Flag{{Name: "node", Type: shortcut.FlagString, Desc: "文件 ID", Required: true}},
+	Tips:  []string{`dws drive +publish-get --node <dentryUuid>`},
+	Execute: func(rt *shortcut.RuntimeContext) error {
+		data, err := rt.CallMCPData("drive", "get_file_publish_status", map[string]any{"fileId": rt.Str("node")})
+		if err != nil {
+			return err
+		}
+		data, err = requireDriveObject(data, "drive/get_file_publish_status")
+		if err != nil {
+			return err
+		}
+		return rt.Output(data)
+	},
+}
+
+var PublishSet = publishMutationShortcut("+publish-set", true)
+var PublishUnset = publishMutationShortcut("+publish-unset", false)
+
+func publishMutationShortcut(command string, published bool) shortcut.Shortcut {
+	description := "开启文件互联网公开发布"
+	useWhen := "用户明确同意任何持链接者可访问，并已确认公开权限时使用。"
+	if !published {
+		description = "关闭文件互联网公开发布"
+		useWhen = "用户明确要求让现有互联网公开链接失效时使用。"
+	}
+	flags := []shortcut.Flag{{Name: "node", Type: shortcut.FlagString, Desc: "文件 ID", Required: true}}
+	if published {
+		flags = append(flags, shortcut.Flag{Name: "permission", Type: shortcut.FlagString, Default: "DOWNLOADER", Desc: "公开权限", Enum: []string{"READER", "DOWNLOADER", "EDITOR"}})
+	}
+	return shortcut.Shortcut{
+		Service: "drive", Command: command, Product: "drive", Description: description, Intent: useWhen,
+		Risk: shortcut.RiskHighWrite, Safety: contract.SafetySpec{Effect: "write", Risk: "high", Confirmation: "user_required", Idempotency: "unknown"},
+		Contract: driveContract(command, description, useWhen,
+			[]string{"只查询状态使用 drive +publish-get；企业内部协作者权限使用 doc +access-grant"},
+			[]string{fmt.Sprintf("dws drive %s --node <dentryUuid>", command)},
+			driveObjectResult(description+"并读回验证的状态"), nil, contract.ParamDecl{Name: "node", Property: "fileId"}),
+		Flags: flags,
+		Tips:  []string{fmt.Sprintf("dws drive %s --node <dentryUuid>", command)},
+		Execute: func(rt *shortcut.RuntimeContext) error {
+			params := map[string]any{"fileId": rt.Str("node"), "published": published}
+			if published {
+				params["publishPermission"] = rt.Str("permission")
+			}
+			written, err := rt.CallMCPWriteDataStrict("drive", "set_file_publish", params)
+			if err != nil {
+				return err
+			}
+			if _, err := requireDriveWrite(written, "drive/set_file_publish"); err != nil {
+				return err
+			}
+			verified, err := rt.CallMCPData("drive", "get_file_publish_status", map[string]any{"fileId": rt.Str("node")})
+			if err != nil {
+				return err
+			}
+			verified, err = requireDriveObject(verified, "drive/get_file_publish_status")
+			if err != nil {
+				return err
+			}
+			actual, ok := boolField(verified, "published", "isPublished", "publish")
+			if !ok || actual != published {
+				return driveResponseError("drive/set_file_publish", "readback_mismatch", "公开状态写入后读回不一致")
+			}
+			return rt.Output(map[string]any{"success": true, "nodeId": rt.Str("node"), "publish": verified})
+		},
+	}
+}
+
+func boolField(data map[string]any, keys ...string) (bool, bool) {
+	for _, key := range keys {
+		if value, ok := data[key].(bool); ok {
+			return value, true
+		}
+	}
+	return false, false
+}
+
+var Upload = shortcut.Shortcut{
+	Service: "drive", Command: "+upload", Product: "drive",
+	Description: "从工作目录上传本地文件并读回验证",
+	Intent:      "把工作目录内普通文件上传到钉盘，并要求验证远端文件 ID、名称和大小时使用。",
+	Risk:        shortcut.RiskWrite,
+	Safety:      contract.SafetySpec{Effect: "write", Risk: "medium", Confirmation: "user_required", Idempotency: "unknown"},
+	Contract: driveContract(
+		"+upload", "从工作目录上传本地文件并读回验证",
+		"把工作目录内普通文件上传到钉盘，并要求验证远端文件 ID、名称和大小时使用。",
+		[]string{"在线文档导入转换使用 doc +import；作为正文附件使用 doc +media-insert；覆盖已有文件必须显式 --node"},
+		[]string{`dws drive +upload --file report.pdf`, `dws drive +upload --file report.pdf --folder <dentryUuid>`},
+		driveObjectResult("上传并读回验证后的远端文件"), nil,
+		contract.ParamDecl{Name: "folder", Property: "parentId"},
+		contract.ParamDecl{Name: "node", Property: "overwriteFileId"},
+	),
+	Flags: []shortcut.Flag{
+		{Name: "file", Type: shortcut.FlagString, Desc: "工作目录内的相对文件路径", Required: true},
+		{Name: "file-name", Type: shortcut.FlagString, Desc: "远端显示名称，默认使用本地文件名"},
+		{Name: "mime-type", Type: shortcut.FlagString, Desc: "MIME 类型"},
+		{Name: "space-id", Type: shortcut.FlagString, Desc: "钉盘空间 ID"},
+		{Name: "folder", Type: shortcut.FlagString, Desc: "父文件夹 ID"},
+		{Name: "node", Type: shortcut.FlagString, Desc: "覆盖目标文件 ID"},
+	},
+	Constraints: []shortcut.Constraint{{Kind: shortcut.ConstraintMutuallyExclusive, Flags: []string{"folder", "node"}}},
+	Tips:        []string{`dws drive +upload --file report.pdf`, `dws drive +upload --file report.pdf --folder <dentryUuid>`},
+	Execute: func(rt *shortcut.RuntimeContext) error {
+		path, info, err := resolveDriveUploadInput(rt.Str("file"))
+		if err != nil {
+			return err
+		}
+		name := rt.Str("file-name")
+		if name == "" {
+			name = info.Name()
+		}
+		if rt.DryRun() {
+			return rt.Output(map[string]any{"dry_run": true, "executed": false, "operation": "drive.upload", "file": rt.Str("file"), "fileName": name, "sizeBytes": info.Size()})
+		}
+		committed, err := uploadDriveFile(rt.Command().Context(), helpers.DriveUploadRequest{
+			FilePath: path, FileName: name, FileSize: info.Size(), SpaceID: rt.Str("space-id"), ParentID: rt.Str("folder"), OverwriteFile: rt.Str("node"), MIMEType: rt.Str("mime-type"),
+		})
+		if err != nil {
+			return err
+		}
+		committed, err = requireDriveWrite(committed, "drive/commit_upload")
+		if err != nil {
+			return err
+		}
+		nodeID := rt.Str("node")
+		if nodeID == "" {
+			nodeID = nestedString(committed, "fileId", "dentryUuid", "nodeId", "id")
+		}
+		if nodeID == "" {
+			return driveResponseError("drive/commit_upload", "missing_created_id", "上传提交没有返回文件 ID；远端效果未知")
+		}
+		verified, err := rt.CallMCPData("drive", "get_file_info", map[string]any{"fileId": nodeID})
+		if err != nil {
+			return err
+		}
+		verified, err = requireDriveObject(verified, "drive/get_file_info")
+		if err != nil {
+			return err
+		}
+		remoteID := firstString(verified, "fileId", "dentryUuid", "nodeId", "id")
+		if remoteID == "" {
+			return driveResponseError("drive/commit_upload", "readback_missing_id", "上传后读回缺少文件 ID；无法证明读回的是已提交文件")
+		}
+		if remoteID != nodeID {
+			return driveResponseError("drive/commit_upload", "readback_id_mismatch", fmt.Sprintf("上传后读回文件 ID %q 与提交 ID %q 不一致", remoteID, nodeID))
+		}
+		if remoteName := firstString(verified, "name", "fileName"); !driveReadbackNameMatches(verified, name) {
+			return driveResponseError("drive/commit_upload", "readback_mismatch", fmt.Sprintf("上传后读回名称 %q 与请求 %q 不一致", remoteName, name))
+		}
+		remoteSize, ok := firstInt64(verified, "fileSize", "size", "byteSize", "length")
+		if !ok {
+			return driveResponseError("drive/commit_upload", "readback_missing_size", "上传后读回缺少有效文件大小；无法证明远端文件完整")
+		}
+		if remoteSize != info.Size() {
+			return driveResponseError("drive/commit_upload", "readback_size_mismatch", fmt.Sprintf("上传后读回大小 %d 与本地文件大小 %d 不一致", remoteSize, info.Size()))
+		}
+		return rt.Output(map[string]any{"success": true, "nodeId": nodeID, "sizeBytes": info.Size(), "file": verified})
+	},
+}
+
+func resolveDriveUploadInput(raw string) (string, os.FileInfo, error) {
+	if strings.TrimSpace(raw) == "" || filepath.IsAbs(raw) {
+		return "", nil, fmt.Errorf("--file 只接受工作目录内的相对文件路径")
+	}
+	cwd, err := driveGetwd()
+	if err != nil {
+		return "", nil, err
+	}
+	base, err := driveEvalSymlinks(cwd)
+	if err != nil {
+		return "", nil, err
+	}
+	path, err := driveEvalSymlinks(filepath.Join(base, filepath.Clean(raw)))
+	if err != nil {
+		return "", nil, fmt.Errorf("读取上传文件失败: %w", err)
+	}
+	rel, err := driveRel(base, path)
+	if err != nil || rel == ".." || strings.HasPrefix(filepath.ToSlash(rel), "../") {
+		return "", nil, fmt.Errorf("--file 不能逃逸工作目录")
+	}
+	info, err := driveStat(path)
+	if err != nil {
+		return "", nil, err
+	}
+	if info.IsDir() || info.Size() <= 0 {
+		return "", nil, fmt.Errorf("--file 必须是非空普通文件")
+	}
+	return path, info, nil
+}

internal/shortcut/drive/common.go

@@ -0,0 +1,270 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0
+
+package drive
+
+import (
+	"encoding/json"
+	"fmt"
+	"math"
+	"strconv"
+	"strings"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract"
+	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
+)
+
+const driveCompositeInterfaceReason = "Reviewed Drive Shortcut composite: the executable CLI owns strict response validation, optional multi-step orchestration, local I/O, read-back verification, output projection, and confirmation; no single MCP interface represents the complete command contract."
+
+func driveContract(command, description, useWhen string, avoidWhen, examples []string, result *contract.ResultSpec, pagination *contract.PaginationSpec, params ...contract.ParamDecl) corecmd.ContractDecl {
+	name := "shortcut_" + strings.ReplaceAll(strings.TrimPrefix(command, "+"), "-", "_")
+	cliPath := "drive " + command
+	return corecmd.ContractDecl{
+		Description: description,
+		Parameters:  params,
+		Result:      result,
+		Pagination:  pagination,
+		Interface: &contract.InterfaceSpec{
+			Mode:         contract.InterfaceModeComposite,
+			Availability: contract.InterfaceAvailable,
+			Reason:       driveCompositeInterfaceReason,
+		},
+		Selection: contract.SelectionSpec{
+			AgentSummary: description,
+			UseWhen:      []string{useWhen},
+			AvoidWhen:    avoidWhen,
+			Examples:     examples,
+		},
+		Identity: contract.ToolIdentitySpec{
+			ProductID:      "drive",
+			Name:           name,
+			CanonicalPath:  "drive." + name,
+			CLIPath:        cliPath,
+			PrimaryCLIPath: cliPath,
+		},
+	}
+}
+
+func driveObjectResult(description string) *contract.ResultSpec {
+	return &contract.ResultSpec{
+		Outcomes: []contract.ResultOutcome{contract.ResultOutcomeSuccess},
+		DataSchema: json.RawMessage(fmt.Sprintf(
+			`{"type":"object","description":%q,"additionalProperties":true}`,
+			description,
+		)),
+	}
+}
+
+func driveCollectionResult(collection, description string) *contract.ResultSpec {
+	return &contract.ResultSpec{
+		Outcomes: []contract.ResultOutcome{contract.ResultOutcomeSuccess},
+		DataSchema: json.RawMessage(fmt.Sprintf(
+			`{"type":"object","description":%q,"properties":{"count":{"type":"integer","description":"本页有效结果数量"},%q:{"type":"array","description":%q,"items":{"type":"object","description":"Drive 资源条目","additionalProperties":true}},"nextCursor":{"type":"string","description":"下一页游标"},"hasMore":{"type":"boolean","description":"服务端是否仍有下一页"}},"required":["count",%q],"additionalProperties":true}`,
+			description, collection, description, collection,
+		)),
+	}
+}
+
+func driveCursorPagination() *contract.PaginationSpec {
+	return &contract.PaginationSpec{
+		Kind:                  contract.PaginationKindCursor,
+		CursorParameter:       "cursor",
+		MetaPath:              contract.PaginationMetaPath,
+		EndpointExhaustedPath: contract.PaginationExhaustedPath,
+		NextTokenPath:         contract.PaginationNextTokenPath,
+	}
+}
+
+func requireDriveResponse(data map[string]any, operation string) (map[string]any, error) {
+	if len(data) == 0 {
+		return nil, driveResponseError(operation, "empty_tool_response", "服务返回空响应，无法证明操作成功")
+	}
+	if success, present := data["success"]; present {
+		value, ok := success.(bool)
+		if !ok {
+			return nil, driveResponseError(operation, "malformed_success", "响应 success 字段不是布尔值")
+		}
+		if !value {
+			message := firstString(data, "errorMsg", "message", "error")
+			if message == "" {
+				message = "服务明确返回 success=false"
+			}
+			return nil, driveResponseError(operation, "remote_failure", message)
+		}
+	}
+	return data, nil
+}
+
+func requireDriveObject(data map[string]any, operation string) (map[string]any, error) {
+	data, err := requireDriveResponse(data, operation)
+	if err != nil {
+		return nil, err
+	}
+	if value, present := data["result"]; present {
+		result, ok := value.(map[string]any)
+		if !ok || len(result) == 0 {
+			return nil, driveResponseError(operation, "malformed_result", "响应 result 缺失有效对象")
+		}
+		return result, nil
+	}
+	if value, present := data["data"]; present {
+		result, ok := value.(map[string]any)
+		if !ok || len(result) == 0 {
+			return nil, driveResponseError(operation, "malformed_data", "响应 data 缺失有效对象")
+		}
+		return result, nil
+	}
+	if len(data) == 1 {
+		return nil, driveResponseError(operation, "missing_business_result", "响应没有可验证的业务对象")
+	}
+	return data, nil
+}
+
+func requireDriveWrite(data map[string]any, operation string) (map[string]any, error) {
+	data, err := requireDriveResponse(data, operation)
+	if err != nil {
+		return nil, err
+	}
+	success, ok := data["success"].(bool)
+	if !ok || !success {
+		return nil, driveResponseError(operation, "missing_terminal_success", "写操作响应没有 success=true 终态证据")
+	}
+	return data, nil
+}
+
+func requireDriveCollection(data map[string]any, operation string, keys ...string) ([]any, map[string]any, error) {
+	data, err := requireDriveResponse(data, operation)
+	if err != nil {
+		return nil, nil, err
+	}
+	containers := []map[string]any{data}
+	for _, wrapper := range []string{"result", "data"} {
+		if value, present := data[wrapper]; present {
+			inner, ok := value.(map[string]any)
+			if !ok {
+				return nil, nil, driveResponseError(operation, "malformed_envelope", fmt.Sprintf("响应 %s 字段不是对象", wrapper))
+			}
+			containers = append(containers, inner)
+		}
+	}
+	for _, container := range containers {
+		for _, key := range keys {
+			value, present := container[key]
+			if !present {
+				continue
+			}
+			items, ok := value.([]any)
+			if !ok {
+				return nil, nil, driveResponseError(operation, "malformed_collection", fmt.Sprintf("响应 %s 字段不是数组", key))
+			}
+			for index, item := range items {
+				if _, ok := item.(map[string]any); !ok {
+					return nil, nil, driveResponseError(operation, "malformed_collection_item", fmt.Sprintf("响应 %s[%d] 不是对象", key, index))
+				}
+			}
+			return items, container, nil
+		}
+	}
+	return nil, nil, driveResponseError(operation, "missing_collection", "响应缺少声明的业务数组；不能把缺字段投影成空结果")
+}
+
+func projectDriveRows(items []any, aliases map[string][]string) []map[string]any {
+	rows := make([]map[string]any, 0, len(items))
+	for _, item := range items {
+		source := item.(map[string]any)
+		row := make(map[string]any)
+		for canonical, candidates := range aliases {
+			for _, candidate := range candidates {
+				if value, ok := source[candidate]; ok && value != nil {
+					row[canonical] = value
+					break
+				}
+			}
+		}
+		rows = append(rows, row)
+	}
+	return rows
+}
+
+func addDrivePagination(out map[string]any, container map[string]any) {
+	for _, pair := range [][2]string{{"nextCursor", "nextCursor"}, {"nextToken", "nextCursor"}, {"nextPageToken", "nextCursor"}, {"hasMore", "hasMore"}} {
+		if value, ok := container[pair[0]]; ok && value != nil {
+			out[pair[1]] = value
+		}
+	}
+}
+
+func firstString(data map[string]any, keys ...string) string {
+	for _, key := range keys {
+		if value, ok := data[key].(string); ok && strings.TrimSpace(value) != "" {
+			return strings.TrimSpace(value)
+		}
+	}
+	return ""
+}
+
+func nestedString(data map[string]any, keys ...string) string {
+	if value := firstString(data, keys...); value != "" {
+		return value
+	}
+	for _, wrapper := range []string{"result", "data"} {
+		if inner, ok := data[wrapper].(map[string]any); ok {
+			if value := firstString(inner, keys...); value != "" {
+				return value
+			}
+		}
+	}
+	return ""
+}
+
+func driveReadbackNameMatches(data map[string]any, requested string) bool {
+	remoteName := firstString(data, "name", "fileName")
+	if remoteName == requested {
+		return true
+	}
+	extension := strings.TrimLeft(firstString(data, "extension", "fileExtension", "ext"), ".")
+	return extension != "" && remoteName+"."+extension == requested
+}
+
+func firstInt64(data map[string]any, keys ...string) (int64, bool) {
+	for _, key := range keys {
+		value, present := data[key]
+		if !present {
+			continue
+		}
+		switch typed := value.(type) {
+		case int:
+			return int64(typed), true
+		case int32:
+			return int64(typed), true
+		case int64:
+			return typed, true
+		case float64:
+			if !math.IsNaN(typed) && !math.IsInf(typed, 0) && typed == math.Trunc(typed) && typed >= math.MinInt64 && typed < math.MaxInt64 {
+				return int64(typed), true
+			}
+		case json.Number:
+			parsed, err := strconv.ParseInt(typed.String(), 10, 64)
+			if err == nil {
+				return parsed, true
+			}
+		case string:
+			parsed, err := strconv.ParseInt(strings.TrimSpace(typed), 10, 64)
+			if err == nil {
+				return parsed, true
+			}
+		}
+	}
+	return 0, false
+}
+
+func driveResponseError(operation, reason, message string) error {
+	return apperrors.NewAPI(message,
+		apperrors.WithOperation(operation),
+		apperrors.WithOrigin("mcp"),
+		apperrors.WithFailureStage("response_validation"),
+		apperrors.WithRetryable(false),
+		apperrors.WithReason(reason),
+	)
+}

internal/shortcut/drive/drive.go

@@ -20,11 +20,18 @@
 package drive
 
 import (
+	"fmt"
+	"strings"
+
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/localio"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/output"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut"
 )
 
+var driveDownload = localio.Download
+
 // ── 钉盘文件（drive MCP server）────────────────────────────────
 
 // List → list_files
@@ -32,9 +39,20 @@ var List = shortcut.Shortcut{
 	Service:     "drive",
 	Command:     "+list",
 	Product:     "drive",
-	Description: "列出钉盘文件/文件夹",
-	Intent:      "当你想浏览钉盘某个空间或文件夹下有哪些文件和子文件夹、需要拿到文件的 dentryUuid 以便后续下载/移动/删除时使用；可指定 space-id、folder 逐层进入，支持分页和按创建/修改时间、名称排序，返回文件列表（含 ID、名称、类型等）。",
+	Description: "严格分页列出钉盘文件和文件夹",
+	Intent:      "浏览钉盘根目录或已知文件夹时使用；服务端明确空数组才表示空目录，缺字段、坏元素或空响应都会失败。",
 	Risk:        shortcut.RiskRead,
+	Safety:      contract.SafetySpec{Effect: "read", Risk: "low", Confirmation: "not_required", Idempotency: "idempotent"},
+	Contract: driveContract(
+		"+list", "严格分页列出钉盘文件和文件夹",
+		"浏览钉盘根目录或已知文件夹时使用；服务端明确空数组才表示空目录，缺字段、坏元素或空响应都会失败。",
+		[]string{"按关键词定位文件改用 drive +search；查看单个节点详情改用 drive +inspect"},
+		[]string{`dws drive +list --limit 20`, `dws drive +list --folder <dentryUuid> --limit 20`},
+		driveCollectionResult("files", "严格校验并投影的钉盘目录页"), driveCursorPagination(),
+		contract.ParamDecl{Name: "space-id", Property: "spaceId"},
+		contract.ParamDecl{Name: "folder", Property: "parentId"},
+		contract.ParamDecl{Name: "cursor", Property: "nextToken"},
+	),
 	Flags: []shortcut.Flag{
 		{Name: "space-id", Type: shortcut.FlagString, Desc: "钉盘空间 ID (纯数字)，不传则使用「我的文件」"},
 		{Name: "folder", Type: shortcut.FlagString, Desc: "父节点 ID (dentryUuid)，不传则列出空间根目录"},
@@ -72,68 +90,23 @@ var List = shortcut.Shortcut{
 		if err != nil {
 			return err
 		}
-		files := listFilesProject(data)
-		return rt.Output(map[string]any{"count": len(files), "files": files})
+		items, page, err := requireDriveCollection(data, "drive/list_files", "items", "files", "dentries", "entries", "nodes", "list")
+		if err != nil {
+			return err
+		}
+		files := projectDriveRows(items, map[string][]string{
+			"name":     {"name", "fileName", "dentryName", "title"},
+			"type":     {"type", "dentryType", "fileType", "spaceType"},
+			"nodeId":   {"fileId", "dentryUuid", "nodeId", "id"},
+			"dentryId": {"dentryId"},
+			"fileSize": {"fileSize", "size", "byteSize", "length"},
+		})
+		out := map[string]any{"count": len(files), "files": files}
+		addDrivePagination(out, page)
+		return rt.Output(out)
 	},
 }
 
-// listFilesProject reshapes the raw list_files response into a clean,
-// stable 钉盘 file/folder list ({name,type,dentryId,fileSize}) — the
-// output-projection fidelity applied to every list shortcut. Both the list
-// container and each field are probed defensively across candidate keys, so a
-// missing container or unknown alias simply yields an empty list rather than a
-// fabricated value.
-func listFilesProject(data map[string]any) []map[string]any {
-	raw := listFilesContainer(data)
-	out := make([]map[string]any, 0, len(raw))
-	for _, item := range raw {
-		m, ok := item.(map[string]any)
-		if !ok {
-			continue
-		}
-		row := map[string]any{}
-		listFilesPick(row, m, "name", "name", "fileName", "dentryName", "title")
-		listFilesPick(row, m, "type", "type", "dentryType", "fileType", "spaceType")
-		listFilesPick(row, m, "dentryId", "dentryId", "dentryUuid", "id", "fileId", "nodeId")
-		listFilesPick(row, m, "fileSize", "fileSize", "size", "byteSize", "length")
-		if len(row) > 0 {
-			out = append(out, row)
-		}
-	}
-	return out
-}
-
-// listFilesContainer locates the file list array inside the response by trying
-// the common container keys emitted across drive backends; the payload itself
-// may also already be the array.
-func listFilesContainer(data map[string]any) []any {
-	for _, k := range []string{"result", "data", "list", "items", "files", "dentries", "entries", "nodes"} {
-		if v, ok := data[k].([]any); ok {
-			return v
-		}
-		// The container may be nested one level (e.g. {"data":{"list":[...]}}).
-		if inner, ok := data[k].(map[string]any); ok {
-			for _, ik := range []string{"list", "items", "files", "dentries", "entries", "nodes", "result"} {
-				if v, ok := inner[ik].([]any); ok {
-					return v
-				}
-			}
-		}
-	}
-	return nil
-}
-
-// listFilesPick copies the first matching alias from src into dst under the
-// canonical key, leaving dst untouched when no alias is present.
-func listFilesPick(dst, src map[string]any, canonical string, aliases ...string) {
-	for _, a := range aliases {
-		if v, ok := src[a]; ok {
-			dst[canonical] = v
-			return
-		}
-	}
-}
-
 // Info → get_file_info
 var Info = shortcut.Shortcut{
 	Service:     "drive",
@@ -177,7 +150,15 @@ var Info = shortcut.Shortcut{
 		if rt.Changed("space-id") {
 			params["spaceId"] = rt.Str("space-id")
 		}
-		return rt.CallMCP("get_file_info", params)
+		data, err := rt.CallMCPData("drive", "get_file_info", params)
+		if err != nil {
+			return err
+		}
+		result, err := requireDriveObject(data, "drive/get_file_info")
+		if err != nil {
+			return err
+		}
+		return rt.Output(result)
 	},
 }
 
@@ -186,20 +167,55 @@ var Download = shortcut.Shortcut{
 	Service:     "drive",
 	Command:     "+download",
 	Product:     "drive",
-	Description: "获取钉盘文件下载链接",
-	Intent:      "当你需要把钉盘里某个文件下载到本地或转给他人时使用；输入文件的 dentryUuid，返回带签名的临时下载 URL 和请求头，用它去真正拉取文件内容（本命令本身只取链接、不落盘）。",
+	Description: "安全下载钉盘文件到工作目录",
+	Intent:      "下载普通钉盘文件并要求验证本地字节产物时使用；不是只返回临时 URL。",
 	Risk:        shortcut.RiskRead,
+	Safety:      contract.SafetySpec{Effect: "read", Risk: "low", Confirmation: "not_required", Idempotency: "idempotent"},
+	Contract: driveContract(
+		"+download", "安全下载钉盘文件到工作目录",
+		"下载普通钉盘文件并要求验证本地字节产物时使用；不是只返回临时 URL。",
+		[]string{"在线文档导出为 docx/pdf 使用 doc +export；只查元数据使用 drive +inspect"},
+		[]string{`dws drive +download --node <dentryUuid> --output downloads/report.pdf`},
+		driveObjectResult("已验证的本地下载产物"), nil,
+		contract.ParamDecl{Name: "node", Property: "fileId"},
+	),
 	Flags: []shortcut.Flag{
 		{Name: "node", Type: shortcut.FlagString, Desc: "文件 ID (dentryUuid)", Required: true},
 		{Name: "space-id", Type: shortcut.FlagString, Desc: "文件所属空间 ID"},
+		{Name: "output", Shorthand: "o", Type: shortcut.FlagString, Desc: "工作目录内的相对输出路径", Required: true},
 	},
-	Tips: []string{`dws drive +download --node <dentryUuid>`},
+	Tips: []string{`dws drive +download --node <dentryUuid> --output downloads/report.pdf`},
 	Execute: func(rt *shortcut.RuntimeContext) error {
 		params := map[string]any{"fileId": rt.Str("node")}
 		if rt.Changed("space-id") {
 			params["spaceId"] = rt.Str("space-id")
 		}
-		return rt.CallMCP("download_file", params)
+		data, err := rt.CallMCPData("drive", "download_file", params)
+		if err != nil {
+			return err
+		}
+		payload, err := requireDriveObject(data, "drive/download_file")
+		if err != nil {
+			return err
+		}
+		url, preferredName, headers, err := driveDownloadPayload(payload, "drive/download_file")
+		if err != nil {
+			return err
+		}
+		cwd, err := driveGetwd()
+		if err != nil {
+			return err
+		}
+		artifact, err := driveDownload(rt.Command().Context(), url, localio.DownloadOptions{
+			BaseDir: cwd, Output: rt.Str("output"), PreferredName: preferredName, Headers: headers,
+		})
+		if err != nil {
+			return err
+		}
+		if artifact.SizeBytes <= 0 {
+			return driveResponseError("drive/download_file", "empty_download_artifact", "下载完成但本地产物为 0 字节")
+		}
+		return rt.Output(map[string]any{"success": true, "nodeId": rt.Str("node"), "savedPath": artifact.RelativePath, "sizeBytes": artifact.SizeBytes})
 	},
 }
 
@@ -296,68 +312,24 @@ var Search = shortcut.Shortcut{
 		if err != nil {
 			return err
 		}
-		files := searchFilesProject(data)
-		return rt.Output(map[string]any{"count": len(files), "files": files})
+		items, page, err := requireDriveCollection(data, "drive/search_files", "items", "files", "dentries", "entries", "nodes", "list")
+		if err != nil {
+			return err
+		}
+		files := projectDriveRows(items, map[string][]string{
+			"name":      {"name", "fileName", "dentryName", "title"},
+			"type":      {"type", "dentryType", "fileType", "spaceType"},
+			"nodeId":    {"fileId", "dentryUuid", "nodeId", "id"},
+			"dentryId":  {"dentryId"},
+			"fileSize":  {"fileSize", "size", "byteSize", "length"},
+			"creatorId": {"creatorId", "creatorUserId", "creator", "creatorUid"},
+		})
+		out := map[string]any{"count": len(files), "files": files}
+		addDrivePagination(out, page)
+		return rt.Output(out)
 	},
 }
 
-// searchFilesProject reshapes the raw search_files response into a clean,
-// stable 钉盘 file list ({name,type,dentryId,fileSize,creatorId}) — the
-// output-projection fidelity applied to every list/search shortcut. Both the
-// list container and each field are probed defensively across candidate keys,
-// so a missing container or unknown alias yields an empty list rather than a
-// fabricated value.
-func searchFilesProject(data map[string]any) []map[string]any {
-	raw := searchFilesContainer(data)
-	out := make([]map[string]any, 0, len(raw))
-	for _, item := range raw {
-		m, ok := item.(map[string]any)
-		if !ok {
-			continue
-		}
-		row := map[string]any{}
-		searchFilesPick(row, m, "name", "name", "fileName", "dentryName", "title")
-		searchFilesPick(row, m, "type", "type", "dentryType", "fileType", "spaceType")
-		searchFilesPick(row, m, "dentryId", "dentryId", "dentryUuid", "id", "fileId", "nodeId")
-		searchFilesPick(row, m, "fileSize", "fileSize", "size", "byteSize", "length")
-		searchFilesPick(row, m, "creatorId", "creatorId", "creatorUserId", "creator", "creatorUid")
-		if len(row) > 0 {
-			out = append(out, row)
-		}
-	}
-	return out
-}
-
-// searchFilesContainer locates the file list array inside the response by
-// trying the common container keys emitted across drive backends; the payload
-// itself may also already wrap the array one level deeper.
-func searchFilesContainer(data map[string]any) []any {
-	for _, k := range []string{"result", "data", "list", "items", "files", "dentries", "entries", "nodes"} {
-		if v, ok := data[k].([]any); ok {
-			return v
-		}
-		if inner, ok := data[k].(map[string]any); ok {
-			for _, ik := range []string{"list", "items", "files", "dentries", "entries", "nodes", "result"} {
-				if v, ok := inner[ik].([]any); ok {
-					return v
-				}
-			}
-		}
-	}
-	return nil
-}
-
-// searchFilesPick copies the first matching alias from src into dst under the
-// canonical key, leaving dst untouched when no alias is present.
-func searchFilesPick(dst, src map[string]any, canonical string, aliases ...string) {
-	for _, a := range aliases {
-		if v, ok := src[a]; ok {
-			dst[canonical] = v
-			return
-		}
-	}
-}
-
 // RecycleList → list_recycle_items
 // RecycleRestore → restore_recycle_item
 // PublishSet → set_file_publish (published=true)
@@ -413,66 +385,22 @@ var SearchDocs = shortcut.Shortcut{
 		if err != nil {
 			return err
 		}
-		docs := searchDocsProject(data)
-		return rt.Output(map[string]any{"count": len(docs), "docs": docs})
+		items, page, err := requireDriveCollection(data, "doc/search_documents", "documents", "docs", "nodes", "items", "list")
+		if err != nil {
+			return err
+		}
+		docs := projectDriveRows(items, map[string][]string{
+			"name":   {"name", "title", "docName", "nodeName", "fileName"},
+			"nodeId": {"nodeId", "id", "docId", "dentryUuid", "fileId"},
+			"type":   {"type", "docType", "nodeType", "fileType"},
+			"url":    {"url", "docUrl", "link", "webUrl"},
+		})
+		out := map[string]any{"count": len(docs), "docs": docs}
+		addDrivePagination(out, page)
+		return rt.Output(out)
 	},
 }
 
-// searchDocsProject reshapes the raw search_documents response into a clean,
-// stable document list ({name,nodeId,type,url}) — the output-projection
-// fidelity applied to every list/search shortcut. Both the list container and
-// each field are probed defensively across candidate keys, so a missing
-// container or unknown alias yields an empty list rather than fabricated data.
-func searchDocsProject(data map[string]any) []map[string]any {
-	raw := searchDocsContainer(data)
-	out := make([]map[string]any, 0, len(raw))
-	for _, item := range raw {
-		m, ok := item.(map[string]any)
-		if !ok {
-			continue
-		}
-		row := map[string]any{}
-		searchDocsPick(row, m, "name", "name", "title", "docName", "nodeName", "fileName")
-		searchDocsPick(row, m, "nodeId", "nodeId", "id", "docId", "dentryUuid", "fileId")
-		searchDocsPick(row, m, "type", "type", "docType", "nodeType", "fileType")
-		searchDocsPick(row, m, "url", "url", "docUrl", "link", "webUrl")
-		if len(row) > 0 {
-			out = append(out, row)
-		}
-	}
-	return out
-}
-
-// searchDocsContainer locates the document list array inside the response by
-// trying the common container keys; the payload may also wrap the array one
-// level deeper under a common envelope.
-func searchDocsContainer(data map[string]any) []any {
-	for _, k := range []string{"result", "data", "list", "items", "documents", "docs", "nodes"} {
-		if v, ok := data[k].([]any); ok {
-			return v
-		}
-		if inner, ok := data[k].(map[string]any); ok {
-			for _, ik := range []string{"list", "items", "documents", "docs", "nodes", "result"} {
-				if v, ok := inner[ik].([]any); ok {
-					return v
-				}
-			}
-		}
-	}
-	return nil
-}
-
-// searchDocsPick copies the first matching alias from src into dst under the
-// canonical key, leaving dst untouched when no alias is present.
-func searchDocsPick(dst, src map[string]any, canonical string, aliases ...string) {
-	for _, a := range aliases {
-		if v, ok := src[a]; ok {
-			dst[canonical] = v
-			return
-		}
-	}
-}
-
 // Delete → delete_document (doc)
 // Copy → copy_document (doc)
 var Copy = shortcut.Shortcut{
@@ -514,6 +442,17 @@ var Copy = shortcut.Shortcut{
 	},
 	Tips: []string{`dws drive +copy --node <nodeId> --folder <targetFolderId>`},
 	Execute: func(rt *shortcut.RuntimeContext) error {
+		preflight, err := rt.CallMCPData("doc", "get_document_info", map[string]any{"nodeId": rt.Str("node")})
+		if err != nil {
+			return err
+		}
+		preflight, err = requireDriveObject(preflight, "doc/get_document_info")
+		if err != nil {
+			return err
+		}
+		if !isOnlineDriveObject(preflight) {
+			return driveResponseError("doc/copy_document", "ordinary_file_copy_unsupported", "普通钉盘文件当前没有独立副本接口；doc/copy_document 会生成 .dlink 快捷方式。需要快捷入口请用 +create-shortcut；需要独立副本请先 +download 再 +upload")
+		}
 		params := map[string]any{"nodeId": rt.Str("node")}
 		if rt.Changed("folder") {
 			params["targetFolderId"] = rt.Str("folder")
@@ -521,7 +460,27 @@ var Copy = shortcut.Shortcut{
 		if rt.Changed("workspace") {
 			params["workspaceId"] = rt.Str("workspace")
 		}
-		return rt.CallMCP("copy_document", params)
+		written, err := rt.CallMCPWriteDataStrict("doc", "copy_document", params)
+		if err != nil {
+			return err
+		}
+		written, err = requireDriveWrite(written, "doc/copy_document")
+		if err != nil {
+			return err
+		}
+		createdID := nestedString(written, "nodeId", "fileId", "dentryUuid", "id")
+		if createdID == "" {
+			return driveResponseError("doc/copy_document", "missing_created_id", "复制响应没有新节点 ID；远端效果未知")
+		}
+		verified, err := rt.CallMCPData("doc", "get_document_info", map[string]any{"nodeId": createdID})
+		if err != nil {
+			return err
+		}
+		verified, err = requireDriveObject(verified, "doc/get_document_info")
+		if err != nil {
+			return err
+		}
+		return rt.Output(map[string]any{"success": true, "sourceNodeId": rt.Str("node"), "nodeId": createdID, "copy": verified})
 	},
 }
 
@@ -572,7 +531,48 @@ var Move = shortcut.Shortcut{
 		if rt.Changed("workspace") {
 			params["workspaceId"] = rt.Str("workspace")
 		}
-		return rt.CallMCP("move_document", params)
+		written, err := rt.CallMCPWriteDataStrict("doc", "move_document", params)
+		if err != nil {
+			return err
+		}
+		written, err = requireDriveWrite(written, "doc/move_document")
+		if err != nil {
+			return err
+		}
+		verified, err := rt.CallMCPData("doc", "get_document_info", map[string]any{"nodeId": rt.Str("node")})
+		if err != nil {
+			return err
+		}
+		verified, err = requireDriveObject(verified, "doc/get_document_info")
+		if err != nil {
+			return err
+		}
+		remoteID := firstString(verified, "nodeId", "fileId", "dentryUuid", "id")
+		if remoteID == "" {
+			return driveResponseError("doc/move_document", "readback_missing_id", "移动后读回缺少节点 ID；无法证明读回的是已移动节点")
+		}
+		if remoteID != rt.Str("node") {
+			return driveResponseError("doc/move_document", "readback_id_mismatch", fmt.Sprintf("移动后读回节点 %q 与请求节点 %q 不一致", remoteID, rt.Str("node")))
+		}
+		if rt.Changed("folder") {
+			remoteFolder := firstString(verified, "folderId", "targetFolderId", "parentId")
+			if remoteFolder == "" {
+				return driveResponseError("doc/move_document", "readback_missing_folder", "移动后读回缺少目标文件夹 ID；无法证明移动已到达请求位置")
+			}
+			if remoteFolder != rt.Str("folder") {
+				return driveResponseError("doc/move_document", "readback_folder_mismatch", fmt.Sprintf("移动后读回文件夹 %q 与请求 %q 不一致", remoteFolder, rt.Str("folder")))
+			}
+		}
+		if rt.Changed("workspace") {
+			remoteWorkspace := firstString(verified, "workspaceId", "spaceId")
+			if remoteWorkspace == "" {
+				return driveResponseError("doc/move_document", "readback_missing_workspace", "移动后读回缺少目标知识库 ID；无法证明移动已到达请求位置")
+			}
+			if remoteWorkspace != rt.Str("workspace") {
+				return driveResponseError("doc/move_document", "readback_workspace_mismatch", fmt.Sprintf("移动后读回知识库 %q 与请求 %q 不一致", remoteWorkspace, rt.Str("workspace")))
+			}
+		}
+		return rt.Output(map[string]any{"success": true, "nodeId": rt.Str("node"), "file": verified})
 	},
 }
 
@@ -647,65 +647,57 @@ var Recent = shortcut.Shortcut{
 		if err != nil {
 			return err
 		}
-		return rt.Output(recentListProject(data))
+		items, page, err := requireDriveCollection(data, "doc/get_recent_list", "recentItems")
+		if err != nil {
+			return err
+		}
+		rows := projectDriveRows(items, map[string][]string{
+			"name":        {"name"},
+			"nodeType":    {"nodeType"},
+			"contentType": {"contentType"},
+			"accessTime":  {"accessTime"},
+			"docUrl":      {"docUrl"},
+			"nodeId":      {"nodeId"},
+		})
+		out := map[string]any{"count": len(rows), "items": rows}
+		addDrivePagination(out, page)
+		return rt.Output(out)
 	},
 }
 
-// recentListProject reshapes a get_recent_list response into a clean paginated
-// document list, dropping transport noise (logId) while keeping the pagination
-// cursor.
-func recentListProject(data map[string]any) map[string]any {
-	// get_recent_list nests its payload under result.recentItems; earlier this
-	// read data["recentItems"] at the top level only, so the whole list silently
-	// projected to empty. Resolve the payload container (top-level or one level
-	// under result/data) before reading recentItems / pagination fields.
-	payload := data
-	if inner, ok := recentListPayload(data); ok {
-		payload = inner
-	}
-	items := []map[string]any{}
-	raw, _ := payload["recentItems"].([]any)
-	for _, it := range raw {
-		m, ok := it.(map[string]any)
-		if !ok {
-			continue
-		}
-		items = append(items, map[string]any{
-			"name":        m["name"],
-			"nodeType":    m["nodeType"],
-			"contentType": m["contentType"],
-			"accessTime":  m["accessTime"],
-			"docUrl":      m["docUrl"],
-			"nodeId":      m["nodeId"],
-		})
-	}
-	out := map[string]any{"count": len(items), "items": items}
-	if nc, ok := payload["nextCursor"]; ok && nc != nil {
-		out["nextCursor"] = nc
-	}
-	if hm, ok := payload["hasMore"]; ok {
-		out["hasMore"] = hm
-	}
-	return out
-}
-
-// recentListPayload returns the map that actually holds recentItems, tolerating
-// a {result|data:{recentItems:[...]}} envelope as well as a bare top-level shape.
-func recentListPayload(data map[string]any) (map[string]any, bool) {
-	if _, ok := data["recentItems"]; ok {
-		return data, true
-	}
-	for _, k := range []string{"result", "data"} {
-		if inner, ok := data[k].(map[string]any); ok {
-			if _, ok := inner["recentItems"]; ok {
-				return inner, true
-			}
-		}
-	}
-	return nil, false
-}
-
 func init() {
+	Copy.Description = "复制在线文档到指定位置并读回验证"
+	Copy.Intent = "复制钉钉在线文档到新位置并保留原件时使用；先验证对象类型，普通文件不伪装成复制成功。"
+	Copy.Contract = driveContract(
+		"+copy", Copy.Description,
+		"复制钉钉在线文档到新位置并保留原件时使用；先验证对象类型，普通文件不伪装成复制成功。",
+		[]string{"普通钉盘文件独立复制当前无等价接口：需要快捷入口用 +create-shortcut，需要独立字节副本用 +download 后 +upload；移动原件用 +move"},
+		[]string{`dws drive +copy --node <ONLINE_DOC_ID> --folder <TARGET_FOLDER_ID>`},
+		driveObjectResult("在线文档复制并读回后的新节点"), nil,
+		// Preserve the historical public Schema properties. Execute translates
+		// these CLI concepts to nodeId/targetFolderId/workspaceId for the RPC.
+		contract.ParamDecl{Name: "node", Property: "node"},
+		contract.ParamDecl{Name: "folder", Property: "folder"},
+		contract.ParamDecl{Name: "workspace", Property: "workspace"},
+	)
+	Copy.Tips = []string{`dws drive +copy --node <ONLINE_DOC_ID> --folder <TARGET_FOLDER_ID>`}
+	Info.Contract.Result = driveObjectResult("钉盘节点元数据")
+	Search.Contract.Result = driveCollectionResult("files", "严格校验并投影的钉盘搜索结果页")
+	Search.Contract.Pagination = driveCursorPagination()
+	SearchDocs.Contract.Result = driveCollectionResult("docs", "兼容入口的在线文档搜索结果页")
+	Copy.Contract.Result = driveObjectResult("复制操作的终态证据")
+	Move.Contract.Result = driveObjectResult("移动操作的终态证据")
+	Recent.Contract.Result = driveCollectionResult("items", "严格校验的最近访问或编辑结果页")
+	Recent.Contract.Pagination = driveCursorPagination()
+	for _, declaration := range []*shortcut.Shortcut{
+		&List, &Info, &Download, &Search, &SearchDocs, &Copy, &Move, &Recent,
+		&Inspect, &Upload, &CreateFolder, &CreateShortcut, &Rename, &Delete, &Stats,
+		&RecycleList, &RecycleRestore, &StarList, &StarAdd, &StarRemove,
+		&PublishGet, &PublishSet, &PublishUnset, &Cover,
+		&VersionHistory, &VersionGet, &VersionDownload, &VersionRevert,
+	} {
+		declaration.OutputRollout = output.RolloutUnifiedActive
+	}
 	shortcut.Register(
 		List,
 		Info,
@@ -715,5 +707,35 @@ func init() {
 		Copy,
 		Move,
 		Recent,
+		Inspect,
+		Upload,
+		CreateFolder,
+		CreateShortcut,
+		Rename,
+		Delete,
+		Stats,
+		RecycleList,
+		RecycleRestore,
+		StarList,
+		StarAdd,
+		StarRemove,
+		PublishGet,
+		PublishSet,
+		PublishUnset,
+		Cover,
+		VersionHistory,
+		VersionGet,
+		VersionDownload,
+		VersionRevert,
 	)
 }
+
+func isOnlineDriveObject(info map[string]any) bool {
+	extension := strings.ToLower(firstString(info, "extension", "fileExtension", "ext"))
+	switch extension {
+	case "adoc", "axls", "able", "amind", "adraw":
+		return true
+	}
+	contentType := strings.ToUpper(firstString(info, "contentType", "docType"))
+	return contentType == "DOC" || contentType == "SHEET" || contentType == "TABLE" || contentType == "MIND" || contentType == "DRAW"
+}

internal/shortcut/drive/operations.go

@@ -0,0 +1,335 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0
+
+package drive
+
+import (
+	"fmt"
+	"strings"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract"
+	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut"
+)
+
+var Inspect = shortcut.Shortcut{
+	Service: "drive", Command: "+inspect", Product: "drive",
+	Description: "聚合检查节点元数据及可选统计、公开状态和封面",
+	Intent:      "已知节点 ID，需要一次确认名称、类型、路径，并可附带统计、公开状态或封面时使用。",
+	Risk:        shortcut.RiskRead,
+	Safety:      contract.SafetySpec{Effect: "read", Risk: "low", Confirmation: "not_required", Idempotency: "idempotent"},
+	Contract: driveContract(
+		"+inspect", "聚合检查节点元数据及可选统计、公开状态和封面",
+		"已知节点 ID，需要一次确认名称、类型、路径，并可附带统计、公开状态或封面时使用。",
+		[]string{"读取在线文档正文使用 doc +fetch；浏览目录使用 drive +list"},
+		[]string{`dws drive +inspect --node <dentryUuid>`, `dws drive +inspect --node <dentryUuid> --include-stats --include-publish`},
+		driveObjectResult("Drive 节点聚合检查结果"), nil,
+		contract.ParamDecl{Name: "node", Property: "fileId"},
+	),
+	Flags: []shortcut.Flag{
+		{Name: "node", Type: shortcut.FlagString, Desc: "节点 ID", Required: true},
+		{Name: "space-id", Type: shortcut.FlagString, Desc: "钉盘空间 ID"},
+		{Name: "include-stats", Type: shortcut.FlagBool, Desc: "附带阅读、编辑、下载等统计"},
+		{Name: "include-publish", Type: shortcut.FlagBool, Desc: "附带互联网公开状态"},
+		{Name: "include-cover", Type: shortcut.FlagBool, Desc: "附带封面或缩略图地址"},
+	},
+	Tips: []string{`dws drive +inspect --node <dentryUuid>`, `dws drive +inspect --node <dentryUuid> --include-stats --include-publish`},
+	Execute: func(rt *shortcut.RuntimeContext) error {
+		node := rt.Str("node")
+		params := map[string]any{"fileId": node}
+		if rt.Str("space-id") != "" {
+			params["spaceId"] = rt.Str("space-id")
+		}
+		data, err := rt.CallMCPData("drive", "get_file_info", params)
+		if err != nil {
+			return err
+		}
+		info, err := requireDriveObject(data, "drive/get_file_info")
+		if err != nil {
+			return err
+		}
+		result := map[string]any{"file": info}
+		steps := []map[string]any{{"tool": "get_file_info", "status": "success"}}
+		reads := []struct {
+			flag, key, tool string
+			params          map[string]any
+		}{
+			{"include-stats", "stats", "get_node_stats", map[string]any{"nodeId": node}},
+			{"include-publish", "publish", "get_file_publish_status", map[string]any{"fileId": node}},
+			{"include-cover", "cover", "get_cover", map[string]any{"nodeId": node}},
+		}
+		failures := []map[string]any{}
+		for _, read := range reads {
+			if !rt.Bool(read.flag) {
+				continue
+			}
+			value, callErr := rt.CallMCPReadData("drive", read.tool, read.params)
+			if callErr == nil {
+				value, callErr = requireDriveObject(value, "drive/"+read.tool)
+			}
+			if callErr != nil {
+				steps = append(steps, map[string]any{"tool": read.tool, "status": "failed"})
+				failures = append(failures, map[string]any{"tool": read.tool, "error": callErr.Error()})
+				continue
+			}
+			result[read.key] = value
+			steps = append(steps, map[string]any{"tool": read.tool, "status": "success"})
+		}
+		if len(failures) > 0 {
+			return apperrors.NewAPI("Drive 聚合检查只完成了部分读取",
+				apperrors.WithOperation("drive.inspect"),
+				apperrors.WithReason("drive_inspect_partial"),
+				apperrors.WithFailureStage("optional_reads"),
+				apperrors.WithExecutionStarted(false),
+				apperrors.WithRetryable(true),
+				apperrors.WithDetails(map[string]any{"status": "partial_success", "complete": false, "data": result, "steps": steps, "failures": failures}),
+			)
+		}
+		return rt.Output(map[string]any{"status": "success", "complete": true, "data": result, "steps": steps})
+	},
+}
+
+var CreateFolder = shortcut.Shortcut{
+	Service: "drive", Command: "+create-folder", Product: "drive",
+	Description: "创建钉盘文件夹并读回验证",
+	Intent:      "在钉盘中创建普通文件夹并需要拿到经过读回验证的 fileId 时使用。",
+	Risk:        shortcut.RiskWrite,
+	Safety:      contract.SafetySpec{Effect: "write", Risk: "medium", Confirmation: "not_required", Idempotency: "unknown"},
+	Contract: driveContract(
+		"+create-folder", "创建钉盘文件夹并读回验证",
+		"在钉盘中创建普通文件夹并需要拿到经过读回验证的 fileId 时使用。",
+		[]string{"知识库目录使用 wiki node create；创建在线文档使用 doc +create"},
+		[]string{`dws drive +create-folder --name "项目资料"`, `dws drive +create-folder --name "子目录" --folder <dentryUuid>`},
+		driveObjectResult("创建并验证后的文件夹"), nil,
+		contract.ParamDecl{Name: "folder", Property: "parentId"},
+	),
+	Flags: []shortcut.Flag{
+		{Name: "name", Type: shortcut.FlagString, Desc: "文件夹名称", Required: true},
+		{Name: "space-id", Type: shortcut.FlagString, Desc: "钉盘空间 ID"},
+		{Name: "folder", Type: shortcut.FlagString, Desc: "父文件夹 ID"},
+	},
+	Tips: []string{`dws drive +create-folder --name "项目资料"`, `dws drive +create-folder --name "子目录" --folder <dentryUuid>`},
+	Execute: func(rt *shortcut.RuntimeContext) error {
+		params := map[string]any{"name": rt.Str("name")}
+		if rt.Str("space-id") != "" {
+			params["spaceId"] = rt.Str("space-id")
+		}
+		if rt.Str("folder") != "" {
+			params["parentId"] = rt.Str("folder")
+		}
+		created, err := rt.CallMCPWriteDataStrict("drive", "create_folder", params)
+		if err != nil {
+			return err
+		}
+		created, err = requireDriveWrite(created, "drive/create_folder")
+		if err != nil {
+			return err
+		}
+		nodeID := nestedString(created, "fileId", "dentryUuid", "nodeId", "id")
+		if nodeID == "" {
+			return driveResponseError("drive/create_folder", "missing_created_id", "创建响应没有文件夹 fileId；远端效果未知")
+		}
+		verified, err := rt.CallMCPData("drive", "get_file_info", map[string]any{"fileId": nodeID})
+		if err != nil {
+			return err
+		}
+		verified, err = requireDriveObject(verified, "drive/get_file_info")
+		if err != nil {
+			return err
+		}
+		if name := firstString(verified, "name", "fileName"); name != rt.Str("name") {
+			return driveResponseError("drive/create_folder", "readback_mismatch", fmt.Sprintf("创建后读回名称 %q 与请求 %q 不一致", name, rt.Str("name")))
+		}
+		return rt.Output(map[string]any{"success": true, "nodeId": nodeID, "folder": verified})
+	},
+}
+
+var CreateShortcut = shortcut.Shortcut{
+	Service: "drive", Command: "+create-shortcut", Product: "drive",
+	Description: "为已有节点创建快捷方式并验证新节点",
+	Intent:      "给已有文件或文档创建快捷入口，并需要区分 shortcut 与独立副本时使用。",
+	Risk:        shortcut.RiskWrite,
+	Safety:      contract.SafetySpec{Effect: "write", Risk: "medium", Confirmation: "not_required", Idempotency: "non_idempotent"},
+	Contract: driveContract(
+		"+create-shortcut", "为已有节点创建快捷方式并验证新节点",
+		"给已有文件或文档创建快捷入口，并需要区分 shortcut 与独立副本时使用。",
+		[]string{"需要独立副本使用 drive +copy；需要迁移原节点使用 drive +move"},
+		[]string{`dws drive +create-shortcut --node <SOURCE_NODE> --folder <TARGET_FOLDER>`},
+		driveObjectResult("创建并验证后的快捷方式节点"), nil,
+		contract.ParamDecl{Name: "node", Property: "nodeId"},
+		contract.ParamDecl{Name: "folder", Property: "targetFolderId"},
+		contract.ParamDecl{Name: "workspace", Property: "workspaceId"},
+	),
+	Flags: []shortcut.Flag{
+		{Name: "node", Type: shortcut.FlagString, Desc: "源节点 ID", Required: true},
+		{Name: "folder", Type: shortcut.FlagString, Desc: "目标文件夹 ID"},
+		{Name: "workspace", Type: shortcut.FlagString, Desc: "目标知识库 ID"},
+	},
+	Tips: []string{`dws drive +create-shortcut --node <SOURCE_NODE> --folder <TARGET_FOLDER>`},
+	Execute: func(rt *shortcut.RuntimeContext) error {
+		params := map[string]any{"nodeId": rt.Str("node")}
+		if rt.Str("folder") != "" {
+			params["targetFolderId"] = rt.Str("folder")
+		}
+		if rt.Str("workspace") != "" {
+			params["workspaceId"] = rt.Str("workspace")
+		}
+		created, err := rt.CallMCPWriteDataStrict("drive", "create_shortcut", params)
+		if err != nil {
+			return err
+		}
+		created, err = requireDriveWrite(created, "drive/create_shortcut")
+		if err != nil {
+			return err
+		}
+		nodeID := nestedString(created, "fileId", "dentryUuid", "nodeId", "id")
+		if nodeID == "" {
+			return driveResponseError("drive/create_shortcut", "missing_created_id", "创建快捷方式未返回新节点 ID")
+		}
+		verified, err := rt.CallMCPData("drive", "get_file_info", map[string]any{"fileId": nodeID})
+		if err != nil {
+			return err
+		}
+		verified, err = requireDriveObject(verified, "drive/get_file_info")
+		if err != nil {
+			return err
+		}
+		return rt.Output(map[string]any{"success": true, "nodeId": nodeID, "shortcut": verified})
+	},
+}
+
+var Rename = shortcut.Shortcut{
+	Service: "drive", Command: "+rename", Product: "doc",
+	Description: "重命名文件或文件夹并读回验证",
+	Intent:      "改变已有节点名称并要求验证最终名称时使用。",
+	Risk:        shortcut.RiskWrite,
+	Safety:      contract.SafetySpec{Effect: "write", Risk: "medium", Confirmation: "user_required", Idempotency: "unknown"},
+	Contract: driveContract(
+		"+rename", "重命名文件或文件夹并读回验证",
+		"改变已有节点名称并要求验证最终名称时使用。",
+		[]string{"改变位置使用 drive +move；替换文件内容使用 drive +upload --node"},
+		[]string{`dws drive +rename --node <dentryUuid> --name "新名称"`},
+		driveObjectResult("重命名后的节点元数据"), nil,
+		contract.ParamDecl{Name: "node", Property: "nodeId"},
+		contract.ParamDecl{Name: "name", Property: "newName"},
+	),
+	Flags: []shortcut.Flag{
+		{Name: "node", Type: shortcut.FlagString, Desc: "节点 ID", Required: true},
+		{Name: "name", Type: shortcut.FlagString, Desc: "新名称", Required: true},
+	},
+	Tips: []string{`dws drive +rename --node <dentryUuid> --name "新名称"`},
+	Execute: func(rt *shortcut.RuntimeContext) error {
+		preflight, err := rt.CallMCPData("drive", "get_file_info", map[string]any{"fileId": rt.Str("node")})
+		if err != nil {
+			return err
+		}
+		preflight, err = requireDriveObject(preflight, "drive/get_file_info")
+		if err != nil {
+			return err
+		}
+		requestName, expectedNames := normalizedDriveRename(rt.Str("name"), preflight)
+		written, err := rt.CallMCPWriteDataStrict("doc", "rename_document", map[string]any{"nodeId": rt.Str("node"), "newName": requestName})
+		if err != nil {
+			return err
+		}
+		if _, err := requireDriveWrite(written, "doc/rename_document"); err != nil {
+			return err
+		}
+		verified, err := rt.CallMCPData("drive", "get_file_info", map[string]any{"fileId": rt.Str("node")})
+		if err != nil {
+			return err
+		}
+		verified, err = requireDriveObject(verified, "drive/get_file_info")
+		if err != nil {
+			return err
+		}
+		name := firstString(verified, "name", "fileName")
+		if name == "" || !expectedNames[name] {
+			return driveResponseError("doc/rename_document", "readback_mismatch", fmt.Sprintf("重命名读回名称 %q 与请求 %q 不一致", name, rt.Str("name")))
+		}
+		return rt.Output(map[string]any{"success": true, "nodeId": rt.Str("node"), "file": verified})
+	},
+}
+
+func normalizedDriveRename(name string, info map[string]any) (string, map[string]bool) {
+	name = strings.TrimSpace(name)
+	expected := map[string]bool{name: true}
+	nodeType := strings.ToLower(firstString(info, "type", "nodeType", "fileType"))
+	if nodeType == "folder" || nodeType == "dir" || nodeType == "directory" {
+		return name, expected
+	}
+	extension := strings.TrimLeft(strings.ToLower(firstString(info, "extension", "fileExtension", "ext")), ".")
+	if extension == "" {
+		return name, expected
+	}
+	suffix := "." + extension
+	if len(name) > len(suffix) && strings.EqualFold(name[len(name)-len(suffix):], suffix) {
+		return name[:len(name)-len(suffix)], expected
+	}
+	expected[name+suffix] = true
+	return name, expected
+}
+
+var Delete = shortcut.Shortcut{
+	Service: "drive", Command: "+delete", Product: "doc",
+	Description: "将已确认节点移入回收站",
+	Intent:      "用户明确要求删除已确认钉盘节点，并理解它会进入回收站时使用。",
+	Risk:        shortcut.RiskHighWrite,
+	Safety:      contract.SafetySpec{Effect: "destructive", Risk: "high", Confirmation: "user_required", Idempotency: "unknown"},
+	Contract: driveContract(
+		"+delete", "将已确认节点移入回收站",
+		"用户明确要求删除已确认钉盘节点，并理解它会进入回收站时使用。",
+		[]string{"只是调整位置使用 drive +move；目标不明确时先 drive +inspect"},
+		[]string{`dws drive +delete --node <dentryUuid>`},
+		driveObjectResult("删除到回收站的终态证据"), nil,
+		contract.ParamDecl{Name: "node", Property: "nodeId"},
+	),
+	Flags: []shortcut.Flag{{Name: "node", Type: shortcut.FlagString, Desc: "节点 ID", Required: true}},
+	Tips:  []string{`dws drive +delete --node <dentryUuid>`},
+	Execute: func(rt *shortcut.RuntimeContext) error {
+		written, err := rt.CallMCPWriteDataStrict("doc", "delete_document", map[string]any{"nodeId": rt.Str("node")})
+		if err != nil {
+			return err
+		}
+		written, err = requireDriveWrite(written, "doc/delete_document")
+		if err != nil {
+			return err
+		}
+		return rt.Output(map[string]any{"success": true, "nodeId": rt.Str("node"), "result": written})
+	},
+}
+
+var Stats = driveReadObjectShortcut(
+	"+stats", "读取节点访问和协作统计", "get_node_stats", "nodeId",
+	"用户要查看指定节点阅读、编辑、评论、点赞、预览或下载统计时使用。",
+	[]string{"只要文件名称和类型使用 drive +inspect"},
+)
+
+var Cover = driveReadObjectShortcut(
+	"+cover", "读取节点封面或缩略图地址", "get_cover", "nodeId",
+	"用户需要节点封面、首图或缩略图 URL 时使用。",
+	[]string{"这是封面资源，不等于 Lark 服务端多格式预览转换"},
+)
+
+func driveReadObjectShortcut(command, description, tool, property, useWhen string, avoidWhen []string) shortcut.Shortcut {
+	return shortcut.Shortcut{
+		Service: "drive", Command: command, Product: "drive", Description: description, Intent: useWhen,
+		Risk: shortcut.RiskRead, Safety: contract.SafetySpec{Effect: "read", Risk: "low", Confirmation: "not_required", Idempotency: "idempotent"},
+		Contract: driveContract(command, description, useWhen, avoidWhen,
+			[]string{fmt.Sprintf("dws drive %s --node <dentryUuid>", command)},
+			driveObjectResult(description), nil, contract.ParamDecl{Name: "node", Property: property}),
+		Flags: []shortcut.Flag{{Name: "node", Type: shortcut.FlagString, Desc: "节点 ID", Required: true}},
+		Tips:  []string{fmt.Sprintf("dws drive %s --node <dentryUuid>", command)},
+		Execute: func(rt *shortcut.RuntimeContext) error {
+			data, err := rt.CallMCPData("drive", tool, map[string]any{property: rt.Str("node")})
+			if err != nil {
+				return err
+			}
+			data, err = requireDriveObject(data, "drive/"+tool)
+			if err != nil {
+				return err
+			}
+			return rt.Output(data)
+		},
+	}
+}

internal/shortcut/drive/recent_list_projection_test.go

@@ -1,66 +0,0 @@
-// 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 drive
-
-import (
-	"encoding/json"
-	"testing"
-)
-
-// TestRecentListProjectResultWrapper guards against projection-data-loss:
-// get_recent_list nests its payload under result.recentItems; the projection
-// must descend into result or +recent silently returns empty despite backend
-// records.
-func TestRecentListProjectResultWrapper(t *testing.T) {
-	const raw = `{"result":{"hasMore":true,"nextCursor":"c2","recentItems":[
-		{"name":"weekly report","nodeType":"doc","nodeId":"n1","docUrl":"https://x/1"},
-		{"name":"budget sheet","nodeType":"sheet","nodeId":"n2","docUrl":"https://x/2"}
-	]}}`
-	var data map[string]any
-	if err := json.Unmarshal([]byte(raw), &data); err != nil {
-		t.Fatalf("unmarshal fixture: %v", err)
-	}
-	out := recentListProject(data)
-	if got, _ := out["count"].(int); got != 2 {
-		t.Fatalf("lower/upper mismatch: result.recentItems has 2 entries, projection count=%v (%v)", out["count"], out)
-	}
-	if out["hasMore"] != true || out["nextCursor"] != "c2" {
-		t.Fatalf("pagination fields lost from result wrapper: %v", out)
-	}
-}
-
-// TestRecentListProjectNoItems covers the no-recentItems branch (payload not
-// found under any wrapper), which must yield an empty list, not a panic.
-func TestRecentListProjectNoItems(t *testing.T) {
-	const raw = `{"result":{"totalCount":0},"success":true}`
-	var data map[string]any
-	if err := json.Unmarshal([]byte(raw), &data); err != nil {
-		t.Fatalf("unmarshal fixture: %v", err)
-	}
-	if out := recentListProject(data); out["count"].(int) != 0 {
-		t.Fatalf("no recentItems: want count 0, got %v", out["count"])
-	}
-}
-
-// TestRecentListProjectTopLevel covers the already-unwrapped shape.
-func TestRecentListProjectTopLevel(t *testing.T) {
-	const raw = `{"recentItems":[{"name":"weekly report","nodeId":"n1"}],"hasMore":false}`
-	var data map[string]any
-	if err := json.Unmarshal([]byte(raw), &data); err != nil {
-		t.Fatalf("unmarshal fixture: %v", err)
-	}
-	if out := recentListProject(data); out["count"].(int) != 1 {
-		t.Fatalf("top-level recentItems: want count 1, got %v", out["count"])
-	}
-}

internal/shortcut/drive/version_operations.go

@@ -0,0 +1,292 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0
+
+package drive
+
+import (
+	"fmt"
+	"strings"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/localio"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut"
+)
+
+var VersionHistory = shortcut.Shortcut{
+	Service: "drive", Command: "+version-history", Product: "drive",
+	Description: "严格分页列出普通文件历史版本",
+	Intent:      "普通文件需要浏览历史版本并获取明确版本号时使用。",
+	Risk:        shortcut.RiskRead,
+	Safety:      contract.SafetySpec{Effect: "read", Risk: "low", Confirmation: "not_required", Idempotency: "idempotent"},
+	Contract: driveContract(
+		"+version-history", "严格分页列出普通文件历史版本",
+		"普通文件需要浏览历史版本并获取明确版本号时使用。",
+		[]string{"在线文档版本使用 doc +version-list；在线表格版本使用 sheet version"},
+		[]string{`dws drive +version-history --node <dentryUuid> --limit 20`},
+		driveCollectionResult("versions", "严格校验的普通文件历史版本页"), driveCursorPagination(),
+		contract.ParamDecl{Name: "node", Property: "nodeId"},
+		contract.ParamDecl{Name: "cursor", Property: "nextCursor"},
+	),
+	Flags: []shortcut.Flag{
+		{Name: "node", Type: shortcut.FlagString, Desc: "普通文件节点 ID", Required: true},
+		{Name: "limit", Type: shortcut.FlagInt, Default: "20", Desc: "每页数量"},
+		{Name: "cursor", Type: shortcut.FlagString, Desc: "分页游标"},
+	},
+	Tips: []string{`dws drive +version-history --node <dentryUuid> --limit 20`},
+	Execute: func(rt *shortcut.RuntimeContext) error {
+		page, err := versionPage(rt, rt.Str("node"), rt.Int("limit"), rt.Str("cursor"))
+		if err != nil {
+			return err
+		}
+		return rt.Output(page)
+	},
+}
+
+var VersionGet = shortcut.Shortcut{
+	Service: "drive", Command: "+version-get", Product: "drive",
+	Description: "按版本号精确读取普通文件版本元数据",
+	Intent:      "已知普通文件版本号，需要确认该版本存在并读取其元数据时使用。",
+	Risk:        shortcut.RiskRead,
+	Safety:      contract.SafetySpec{Effect: "read", Risk: "low", Confirmation: "not_required", Idempotency: "idempotent"},
+	Contract: driveContract(
+		"+version-get", "按版本号精确读取普通文件版本元数据",
+		"已知普通文件版本号，需要确认该版本存在并读取其元数据时使用。",
+		[]string{"尚未确定版本号时使用 drive +version-history；需要版本字节使用 drive +version-download"},
+		[]string{`dws drive +version-get --node <dentryUuid> --version 3`},
+		driveObjectResult("精确匹配的普通文件版本元数据"), nil,
+		contract.ParamDecl{Name: "node", Property: "nodeId"},
+	),
+	Flags: []shortcut.Flag{
+		{Name: "node", Type: shortcut.FlagString, Desc: "普通文件节点 ID", Required: true},
+		{Name: "version", Type: shortcut.FlagInt, Desc: "版本号；--version 必须为正整数", Required: true},
+	},
+	Constraints: []shortcut.Constraint{{Kind: shortcut.ConstraintCustom, Flags: []string{"version"}, Description: "--version 必须为正整数"}},
+	Validate: func(rt *shortcut.RuntimeContext) error {
+		if rt.Int("version") <= 0 {
+			return fmt.Errorf("--version 必须为正整数")
+		}
+		return nil
+	},
+	Tips: []string{`dws drive +version-get --node <dentryUuid> --version 3`},
+	Execute: func(rt *shortcut.RuntimeContext) error {
+		version, err := findVersion(rt, rt.Str("node"), rt.Int("version"))
+		if err != nil {
+			return err
+		}
+		return rt.Output(map[string]any{"nodeId": rt.Str("node"), "version": version})
+	},
+}
+
+var VersionDownload = shortcut.Shortcut{
+	Service: "drive", Command: "+version-download", Product: "drive",
+	Description: "安全下载普通文件指定历史版本",
+	Intent:      "已确认普通文件版本号，需要安全落盘并验证实际字节时使用。",
+	Risk:        shortcut.RiskRead,
+	Safety:      contract.SafetySpec{Effect: "read", Risk: "low", Confirmation: "not_required", Idempotency: "idempotent"},
+	Contract: driveContract(
+		"+version-download", "安全下载普通文件指定历史版本",
+		"已确认普通文件版本号，需要安全落盘并验证实际字节时使用。",
+		[]string{"下载最新版本使用 drive +download；在线文档版本使用 doc +version-list/+export"},
+		[]string{`dws drive +version-download --node <dentryUuid> --version 3 --output downloads/report-v3.pdf`},
+		driveObjectResult("已验证的历史版本本地产物"), nil,
+		contract.ParamDecl{Name: "node", Property: "nodeId"},
+	),
+	Flags: []shortcut.Flag{
+		{Name: "node", Type: shortcut.FlagString, Desc: "普通文件节点 ID", Required: true},
+		{Name: "version", Type: shortcut.FlagInt, Desc: "版本号；--version 必须为正整数", Required: true},
+		{Name: "output", Type: shortcut.FlagString, Desc: "工作目录内相对输出路径", Required: true},
+	},
+	Constraints: []shortcut.Constraint{{Kind: shortcut.ConstraintCustom, Flags: []string{"version"}, Description: "--version 必须为正整数"}},
+	Validate: func(rt *shortcut.RuntimeContext) error {
+		if rt.Int("version") <= 0 {
+			return fmt.Errorf("--version 必须为正整数")
+		}
+		return nil
+	},
+	Tips: []string{`dws drive +version-download --node <dentryUuid> --version 3 --output downloads/report-v3.pdf`},
+	Execute: func(rt *shortcut.RuntimeContext) error {
+		if _, err := findVersion(rt, rt.Str("node"), rt.Int("version")); err != nil {
+			return err
+		}
+		data, err := rt.CallMCPData("drive", "download_file_version", map[string]any{"nodeId": rt.Str("node"), "version": rt.Int("version")})
+		if err != nil {
+			return err
+		}
+		payload, err := requireDriveObject(data, "drive/download_file_version")
+		if err != nil {
+			return err
+		}
+		url, name, headers, err := driveDownloadPayload(payload, "drive/download_file_version")
+		if err != nil {
+			return err
+		}
+		cwd, err := driveGetwd()
+		if err != nil {
+			return err
+		}
+		artifact, err := driveDownload(rt.Command().Context(), url, localio.DownloadOptions{BaseDir: cwd, Output: rt.Str("output"), PreferredName: name, Headers: headers})
+		if err != nil {
+			return err
+		}
+		if artifact.SizeBytes <= 0 {
+			return driveResponseError("drive/download_file_version", "empty_download_artifact", "历史版本下载产物为 0 字节")
+		}
+		return rt.Output(map[string]any{"success": true, "nodeId": rt.Str("node"), "version": rt.Int("version"), "savedPath": artifact.RelativePath, "sizeBytes": artifact.SizeBytes})
+	},
+}
+
+var VersionRevert = shortcut.Shortcut{
+	Service: "drive", Command: "+version-revert", Product: "drive",
+	Description: "预检并回滚普通文件到指定历史版本",
+	Intent:      "用户明确选定普通文件历史版本并要求回滚时使用。",
+	Risk:        shortcut.RiskHighWrite,
+	Safety:      contract.SafetySpec{Effect: "write", Risk: "high", Confirmation: "user_required", Idempotency: "non_idempotent"},
+	Contract: driveContract(
+		"+version-revert", "预检并回滚普通文件到指定历史版本",
+		"用户明确选定普通文件历史版本并要求回滚时使用。",
+		[]string{"尚未确认版本号时先 drive +version-history；在线文档使用 doc +version-revert"},
+		[]string{`dws drive +version-revert --node <dentryUuid> --version 3`},
+		driveObjectResult("版本回滚终态及节点读回"), nil,
+		contract.ParamDecl{Name: "node", Property: "nodeId"},
+	),
+	Flags: []shortcut.Flag{
+		{Name: "node", Type: shortcut.FlagString, Desc: "普通文件节点 ID", Required: true},
+		{Name: "version", Type: shortcut.FlagInt, Desc: "版本号；--version 必须为正整数", Required: true},
+	},
+	Constraints: []shortcut.Constraint{{Kind: shortcut.ConstraintCustom, Flags: []string{"version"}, Description: "--version 必须为正整数"}},
+	Validate: func(rt *shortcut.RuntimeContext) error {
+		if rt.Int("version") <= 0 {
+			return fmt.Errorf("--version 必须为正整数")
+		}
+		return nil
+	},
+	Tips: []string{`dws drive +version-revert --node <dentryUuid> --version 3`},
+	Execute: func(rt *shortcut.RuntimeContext) error {
+		if _, err := findVersion(rt, rt.Str("node"), rt.Int("version")); err != nil {
+			return err
+		}
+		written, err := rt.CallMCPWriteDataStrict("drive", "revert_file_version", map[string]any{"nodeId": rt.Str("node"), "version": rt.Int("version")})
+		if err != nil {
+			return err
+		}
+		if _, err := requireDriveWrite(written, "drive/revert_file_version"); err != nil {
+			return err
+		}
+		verified, err := rt.CallMCPData("drive", "get_file_info", map[string]any{"fileId": rt.Str("node")})
+		if err != nil {
+			return err
+		}
+		verified, err = requireDriveObject(verified, "drive/get_file_info")
+		if err != nil {
+			return err
+		}
+		return rt.Output(map[string]any{"success": true, "nodeId": rt.Str("node"), "revertedTo": rt.Int("version"), "file": verified})
+	},
+}
+
+func versionPage(rt *shortcut.RuntimeContext, nodeID string, limit int, cursor string) (map[string]any, error) {
+	params := map[string]any{"nodeId": nodeID, "maxResults": limit}
+	if cursor != "" {
+		params["nextCursor"] = cursor
+	}
+	data, err := rt.CallMCPData("drive", "list_file_versions", params)
+	if err != nil {
+		return nil, err
+	}
+	items, page, err := requireDriveCollection(data, "drive/list_file_versions", "versions", "versionList", "items")
+	if err != nil {
+		return nil, err
+	}
+	versions := projectDriveRows(items, map[string][]string{
+		"version":    {"version", "versionNumber", "versionNum"},
+		"createTime": {"createTime", "createdTime"},
+		"creatorId":  {"creatorId", "creatorUserId", "operatorId"},
+		"fileSize":   {"fileSize", "size"},
+		"name":       {"name", "fileName"},
+	})
+	out := map[string]any{"count": len(versions), "versions": versions}
+	addDrivePagination(out, page)
+	return out, nil
+}
+
+func findVersion(rt *shortcut.RuntimeContext, nodeID string, target int) (map[string]any, error) {
+	const maxPages = 20
+	cursor := ""
+	seenCursors := map[string]bool{}
+	for pageNumber := 1; pageNumber <= maxPages; pageNumber++ {
+		page, err := versionPage(rt, nodeID, 50, cursor)
+		if err != nil {
+			return nil, err
+		}
+		for _, version := range page["versions"].([]map[string]any) {
+			if number, ok := versionNumber(version); ok && number == target {
+				return version, nil
+			}
+		}
+
+		nextCursor := strings.TrimSpace(nestedString(page, "nextCursor", "nextToken", "nextPageToken"))
+		hasMore, hasMoreKnown := boolField(page, "hasMore")
+		if hasMoreKnown && !hasMore {
+			return nil, driveResponseError("drive/list_file_versions", "version_not_found", fmt.Sprintf("完整版本历史中不存在版本 %d", target))
+		}
+		if nextCursor == "" {
+			if hasMoreKnown && hasMore {
+				return nil, versionPaginationError("missing_next_cursor", pageNumber, cursor)
+			}
+			return nil, driveResponseError("drive/list_file_versions", "version_not_found", fmt.Sprintf("完整版本历史中不存在版本 %d", target))
+		}
+		if seenCursors[nextCursor] {
+			return nil, versionPaginationError("stalled_cursor", pageNumber, nextCursor)
+		}
+		seenCursors[nextCursor] = true
+		cursor = nextCursor
+	}
+	return nil, versionPaginationError("max_pages", maxPages, cursor)
+}
+
+func versionPaginationError(reason string, page int, cursor string) error {
+	return driveResponseError(
+		"drive/list_file_versions",
+		"version_pagination_"+reason,
+		fmt.Sprintf("版本预检无法证明分页已经完整，已停止操作（page=%d, cursor=%q）", page, cursor),
+	)
+}
+
+func versionNumber(version map[string]any) (int, bool) {
+	switch value := version["version"].(type) {
+	case float64:
+		return int(value), value == float64(int(value))
+	case int:
+		return value, true
+	case string:
+		var number int
+		if _, err := fmt.Sscanf(value, "%d", &number); err == nil {
+			return number, true
+		}
+	}
+	return 0, false
+}
+
+func driveDownloadPayload(payload map[string]any, operation string) (string, string, map[string]string, error) {
+	url := firstString(payload, "downloadUrl", "resourceUrl", "url")
+	if url == "" {
+		if resources, ok := payload["resourceUrls"].([]any); ok && len(resources) > 0 {
+			if first, ok := resources[0].(map[string]any); ok {
+				url = firstString(first, "url", "downloadUrl", "resourceUrl")
+				payload = first
+			}
+		}
+	}
+	if url == "" {
+		return "", "", nil, driveResponseError(operation, "missing_download_url", "下载响应没有有效 URL")
+	}
+	headers := map[string]string{}
+	if raw, ok := payload["headers"].(map[string]any); ok {
+		for key, value := range raw {
+			if text, ok := value.(string); ok {
+				headers[key] = text
+			}
+		}
+	}
+	return url, firstString(payload, "fileName", "name"), headers, nil
+}