fix(ci): enforce stable Schema compatibility

ci(schema): allow reviewed parameter type migrations

.github/reviewer-routing.js

@@ -0,0 +1,285 @@
+'use strict';
+
+// 评审归属是受保护分支上的声明式规则；未知路径不猜测，交给工作流负载均衡兜底。
+const REVIEWER_POOL = ['wxianfeng', 'typefield', 'haofeng0705', 'hlzjsong'];
+
+const PRODUCT_GROUPS = [
+  {
+    primary: 'wxianfeng',
+    backup: 'typefield',
+    products: ['chat', 'contact', 'ding', 'event', 'mail', 'live', 'conference', 'dev', 'devapp', 'mcp', 'aiapp'],
+  },
+  {
+    primary: 'typefield',
+    backup: 'wxianfeng',
+    products: ['doc', 'drive', 'wiki', 'markdown', 'docparse', 'aidesign', 'devdoc', 'blackboard', 'finance', 'law', 'credit'],
+  },
+  {
+    primary: 'haofeng0705',
+    backup: 'typefield',
+    products: ['minutes', 'sheet', 'aitable', 'calendar', 'todo', 'oa', 'attendance', 'report', 'agoal', 'aisearch', 'yida', 'hrbrain'],
+  },
+];
+
+const pathStartsWith = (prefixes) => (path) => prefixes.some((prefix) => path.startsWith(prefix));
+
+const MODULES = [
+  {
+    id: 'security',
+    label: '登录、认证、权限、安全',
+    primary: 'hlzjsong',
+    backup: 'typefield',
+    requiresSecondary: true,
+    matches: pathStartsWith([
+      'internal/auth/',
+      'internal/keychain/',
+      'internal/audit/',
+      'internal/pat/',
+      'internal/security/',
+      'internal/safety/',
+      'pkg/edition/',
+    ]),
+  },
+  {
+    id: 'delivery',
+    label: 'CI、测试、发布、安装',
+    primary: 'haofeng0705',
+    backup: 'wxianfeng',
+    requiresSecondary: true,
+    matches: (path) =>
+      path.startsWith('.github/') ||
+      path.startsWith('scripts/release/') ||
+      path.startsWith('scripts/policy/') ||
+      path.startsWith('scripts/dev/') ||
+      path.startsWith('scripts/install') ||
+      path.startsWith('Formula/') ||
+      path.startsWith('build/') ||
+      path.startsWith('internal/upgrade/') ||
+      path.startsWith('internal/app/upgrade') ||
+      path.startsWith('test/') ||
+      path.startsWith('verify/') ||
+      path.startsWith('.workflow/') ||
+      path === 'coverage.txt' ||
+      path === 'coverage-base.txt' ||
+      path === '.goreleaser.yaml' ||
+      path === 'package.json' ||
+      path === 'package-lock.json' ||
+      path === 'docs/releasing.md',
+  },
+  {
+    id: 'architecture',
+    label: 'DWS 架构、公共内核',
+    primary: 'wxianfeng',
+    backup: 'typefield',
+    requiresSecondary: true,
+    matches: pathStartsWith([
+      'cmd/',
+      'internal/apiclient/',
+      'internal/app/',
+      'internal/cli/',
+      'internal/cobracmd/',
+      'internal/corecmd/',
+      'internal/errors/',
+      'internal/executor/',
+      'internal/generator/',
+      'internal/i18n/',
+      'internal/interfacesnapshot/',
+      'internal/jsonutil/',
+      'internal/localio/',
+      'internal/logging/',
+      'internal/output/',
+      'internal/pipeline/',
+      'internal/plugin/',
+      'internal/profilectx/',
+      'internal/registry/',
+      'internal/syncdata/',
+      'internal/testseam/',
+      'internal/transport/',
+      'pkg/',
+    ]),
+  },
+  {
+    id: 'compatibility',
+    label: '兼容性',
+    primary: 'wxianfeng',
+    backup: 'typefield',
+    requiresSecondary: true,
+    matches: (path) =>
+      /(?:^|[/_.-])compat(?:ibility)?(?=$|[/_.-])/.test(path) ||
+      path.includes('schema_compat'),
+  },
+];
+
+function productMatches(path, product) {
+  const aliases = product === 'blackboard' ? ['blackboard', 'whiteboard'] : [product];
+  return aliases.some((alias) => new RegExp(`(?:^|[/_.-])${alias}(?=$|[/_.-])`).test(path));
+}
+
+const PRODUCT_MODULES = PRODUCT_GROUPS.flatMap((group) =>
+  group.products.map((product) => ({
+    id: `product:${product}`,
+    label: `产品：${product}`,
+    primary: group.primary,
+    backup: group.backup,
+    requiresSecondary: false,
+    matches: (path) => productMatches(path, product),
+  })),
+);
+
+const ALL_MODULES = [MODULES[0], MODULES[1], ...PRODUCT_MODULES, MODULES[2], MODULES[3]];
+
+function normalizedPaths(file) {
+  return [file?.filename, file?.previous_filename]
+    .filter((path) => typeof path === 'string' && path !== '')
+    .map((path) => path.toLowerCase());
+}
+
+function compareStats(left, right) {
+  return right.files - left.files || left.module.order - right.module.order || left.module.id.localeCompare(right.module.id);
+}
+
+function classifyFiles(files) {
+  const counts = new Map();
+  for (const file of files || []) {
+    const matchingModules = new Set();
+    for (const path of normalizedPaths(file)) {
+      const matches = ALL_MODULES.filter((module) => module.matches(path));
+      const securityOrDelivery = matches.filter(
+        (module) => module.id === 'security' || module.id === 'delivery',
+      );
+      const effectiveMatches = securityOrDelivery.length > 0
+        ? [...securityOrDelivery, ...matches.filter((module) => module.id === 'compatibility')]
+        : matches;
+      for (const match of effectiveMatches) {
+        matchingModules.add(match.id);
+      }
+      if (
+        effectiveMatches.length === 0 &&
+        (path.startsWith('internal/helpers/') || path.startsWith('internal/shortcut/'))
+      ) {
+        matchingModules.add('architecture');
+      }
+    }
+    for (const moduleID of matchingModules) {
+      counts.set(moduleID, (counts.get(moduleID) || 0) + 1);
+    }
+  }
+
+  return [...counts.entries()]
+    .map(([id, files]) => {
+      const index = ALL_MODULES.findIndex((module) => module.id === id);
+      return {module: {...ALL_MODULES[index], order: index}, files};
+    })
+    .sort(compareStats);
+}
+
+function chooseModuleReviewer(module, unavailable) {
+  return [module.primary, module.backup].find(
+    (reviewer) => REVIEWER_POOL.includes(reviewer) && !unavailable.has(reviewer),
+  );
+}
+
+function addReviewer(reviewers, reviewer) {
+  if (reviewer && !reviewers.includes(reviewer)) {
+    reviewers.push(reviewer);
+  }
+}
+
+function reviewerCandidates({preferredReviewers, fallbackReviewers, eligibleReviewers}) {
+  const eligible = new Set(eligibleReviewers.map((reviewer) => reviewer.toLowerCase()));
+  const candidates = [];
+  for (const reviewer of [...preferredReviewers, ...fallbackReviewers]) {
+    if (
+      eligible.has(reviewer.toLowerCase()) &&
+      !candidates.some((candidate) => candidate.toLowerCase() === reviewer.toLowerCase())
+    ) {
+      candidates.push(reviewer);
+    }
+  }
+  return candidates;
+}
+
+async function requestReviewersWithFallback({
+  candidates,
+  requiredReviewers,
+  satisfiedReviewers = [],
+  requestReviewer,
+  onFailure = () => {},
+}) {
+  const alreadySatisfied = new Set(
+    satisfiedReviewers.map((reviewer) => reviewer.toLowerCase()),
+  );
+  const satisfied = new Set();
+  const requested = [];
+
+  for (const reviewer of candidates) {
+    if (satisfied.size >= requiredReviewers) {
+      break;
+    }
+    const normalizedReviewer = reviewer.toLowerCase();
+    if (alreadySatisfied.has(normalizedReviewer)) {
+      satisfied.add(normalizedReviewer);
+      continue;
+    }
+
+    try {
+      const shouldContinue = await requestReviewer(reviewer);
+      if (shouldContinue === false) {
+        return {requested, satisfiedReviewers: [...satisfied], aborted: true};
+      }
+      requested.push(reviewer);
+      satisfied.add(normalizedReviewer);
+    } catch (error) {
+      onFailure(reviewer, error);
+    }
+  }
+
+  return {requested, satisfiedReviewers: [...satisfied], aborted: false};
+}
+
+function resolveReviewRouting({files, author, latestPusher, fallbackReviewers = REVIEWER_POOL}) {
+  const modules = classifyFiles(files);
+  const unavailable = new Set([author, latestPusher].filter(Boolean).map((login) => login.toLowerCase()));
+  const reviewers = [];
+  const primaryModule = modules[0];
+
+  if (!primaryModule) {
+    return {modules: [], reviewers, requiredReviewers: 1, reason: 'unknown_paths'};
+  }
+
+  addReviewer(reviewers, chooseModuleReviewer(primaryModule.module, unavailable));
+
+  const requiresSecondary =
+    modules.length > 1 || modules.some(({module}) => module.requiresSecondary);
+  const secondaryModule = modules.find(({module}) => module.id !== primaryModule.module.id) || primaryModule;
+  if (requiresSecondary) {
+    addReviewer(
+      reviewers,
+      chooseModuleReviewer(secondaryModule.module, new Set([...unavailable, ...reviewers])),
+    );
+  }
+
+  for (const reviewer of fallbackReviewers) {
+    if (reviewers.length >= (requiresSecondary ? 2 : 1)) {
+      break;
+    }
+    if (REVIEWER_POOL.includes(reviewer) && !unavailable.has(reviewer)) {
+      addReviewer(reviewers, reviewer);
+    }
+  }
+
+  return {
+    modules: modules.map(({module, files}) => ({id: module.id, label: module.label, files})),
+    reviewers,
+    requiredReviewers: requiresSecondary ? 2 : 1,
+    reason: requiresSecondary ? 'cross_or_sensitive' : 'single_module',
+  };
+}
+
+module.exports = {
+  REVIEWER_POOL,
+  classifyFiles,
+  requestReviewersWithFallback,
+  resolveReviewRouting,
+  reviewerCandidates,
+};

.github/reviewer-routing.test.js

@@ -0,0 +1,148 @@
+'use strict';
+
+const assert = require('node:assert/strict');
+const {
+  requestReviewersWithFallback,
+  resolveReviewRouting,
+  reviewerCandidates,
+} = require('./reviewer-routing');
+
+function route(files, author = 'author', latestPusher = author) {
+  return resolveReviewRouting({files: files.map((filename) => ({filename})), author, latestPusher});
+}
+
+{
+  const result = route(['internal/helpers/chat_toolbar.go']);
+  assert.deepEqual(result.reviewers, ['wxianfeng']);
+  assert.equal(result.requiredReviewers, 1);
+  assert.deepEqual(result.modules.map((module) => module.id), ['product:chat']);
+}
+
+{
+  const result = route(['internal/helpers/chat_toolbar.go', 'internal/helpers/doc_style.go']);
+  assert.deepEqual(result.reviewers, ['wxianfeng', 'typefield']);
+  assert.equal(result.requiredReviewers, 2);
+}
+
+{
+  const result = route(['.github/workflows/ci.yml']);
+  assert.deepEqual(result.reviewers, ['haofeng0705', 'wxianfeng']);
+  assert.equal(result.requiredReviewers, 2);
+  assert.equal(result.reason, 'cross_or_sensitive');
+}
+
+{
+  const result = route(['internal/auth/login.go'], 'hlzjsong');
+  assert.deepEqual(result.reviewers, ['typefield', 'wxianfeng']);
+  assert.equal(result.requiredReviewers, 2);
+}
+
+{
+  const result = route(['internal/upgrade/downloader.go']);
+  assert.deepEqual(result.reviewers, ['haofeng0705', 'wxianfeng']);
+  assert.equal(result.requiredReviewers, 2);
+}
+
+{
+  const result = route(['internal/app/upgrade.go', 'scripts/dev/test-release.sh']);
+  assert.deepEqual(result.reviewers, ['haofeng0705', 'wxianfeng']);
+  assert.equal(result.requiredReviewers, 2);
+}
+
+{
+  const result = route(['pkg/edition/edition.go']);
+  assert.deepEqual(result.reviewers, ['hlzjsong', 'typefield']);
+  assert.equal(result.requiredReviewers, 2);
+}
+
+{
+  const result = route(['internal/shortcut/chat/compatibility_coverage_test.go']);
+  assert.deepEqual(result.reviewers, ['wxianfeng', 'typefield']);
+  assert.equal(result.requiredReviewers, 2);
+  assert.deepEqual(result.modules.map((module) => module.id), ['product:chat', 'compatibility']);
+}
+
+{
+  const result = route(['internal/helpers/leaf_dispatch.go']);
+  assert.deepEqual(result.reviewers, ['wxianfeng', 'typefield']);
+  assert.equal(result.requiredReviewers, 2);
+}
+
+{
+  const result = route(['docs/unknown-area.md']);
+  assert.deepEqual(result.reviewers, []);
+  assert.equal(result.reason, 'unknown_paths');
+}
+
+async function testSingleReviewerFallback() {
+  const candidates = reviewerCandidates({
+    preferredReviewers: ['wxianfeng'],
+    fallbackReviewers: ['wxianfeng', 'typefield', 'haofeng0705'],
+    eligibleReviewers: ['wxianfeng', 'typefield', 'haofeng0705'],
+  });
+  const attempts = [];
+  const result = await requestReviewersWithFallback({
+    candidates,
+    requiredReviewers: 1,
+    requestReviewer: async (reviewer) => {
+      attempts.push(reviewer);
+      if (reviewer === 'wxianfeng') {
+        throw Object.assign(new Error('cannot request primary'), {status: 422});
+      }
+      return true;
+    },
+  });
+  assert.deepEqual(attempts, ['wxianfeng', 'typefield']);
+  assert.deepEqual(result.requested, ['typefield']);
+  assert.equal(result.satisfiedReviewers.length, 1);
+}
+
+async function testTwoReviewerFallback() {
+  const candidates = reviewerCandidates({
+    preferredReviewers: ['haofeng0705', 'wxianfeng'],
+    fallbackReviewers: ['haofeng0705', 'wxianfeng', 'typefield', 'hlzjsong'],
+    eligibleReviewers: ['haofeng0705', 'wxianfeng', 'typefield', 'hlzjsong'],
+  });
+  const attempts = [];
+  const result = await requestReviewersWithFallback({
+    candidates,
+    requiredReviewers: 2,
+    requestReviewer: async (reviewer) => {
+      attempts.push(reviewer);
+      if (reviewer === 'wxianfeng') {
+        throw Object.assign(new Error('temporary failure'), {status: 503});
+      }
+      return true;
+    },
+  });
+  assert.deepEqual(attempts, ['haofeng0705', 'wxianfeng', 'typefield']);
+  assert.deepEqual(result.requested, ['haofeng0705', 'typefield']);
+  assert.equal(result.satisfiedReviewers.length, 2);
+}
+
+async function testLowerPriorityExistingRequestDoesNotReplaceOwner() {
+  const attempts = [];
+  const result = await requestReviewersWithFallback({
+    candidates: ['wxianfeng', 'typefield'],
+    requiredReviewers: 1,
+    satisfiedReviewers: ['typefield'],
+    requestReviewer: async (reviewer) => {
+      attempts.push(reviewer);
+      return true;
+    },
+  });
+  assert.deepEqual(attempts, ['wxianfeng']);
+  assert.deepEqual(result.requested, ['wxianfeng']);
+  assert.deepEqual(result.satisfiedReviewers, ['wxianfeng']);
+}
+
+Promise.all([
+  testSingleReviewerFallback(),
+  testTwoReviewerFallback(),
+  testLowerPriorityExistingRequestDoesNotReplaceOwner(),
+])
+  .then(() => console.log('reviewer routing policy tests passed'))
+  .catch((error) => {
+    console.error(error);
+    process.exitCode = 1;
+  });

.github/workflows/ci.yml

@@ -111,6 +111,7 @@ jobs:
                 filename.startsWith('internal/app/') ||
                 filename.startsWith('internal/cli/') ||
                 filename.startsWith('internal/cobracmd/') ||
+                filename.startsWith('internal/corecmd/') ||
                 filename.startsWith('internal/helpers/') ||
                 filename.startsWith('internal/i18n/') ||
                 filename.startsWith('internal/interfacesnapshot/') ||
@@ -152,7 +153,6 @@ jobs:
                 filename.startsWith('internal/interfacesnapshot/') ||
                 filename.startsWith('internal/app/upgrade') ||
                 filename.startsWith('internal/transport/') ||
-                filename.startsWith('internal/recovery/') ||
                 filename.startsWith('internal/syncdata/') ||
                 filename.includes('/testdata/') ||
                 filename.startsWith('testdata/') ||
@@ -433,6 +433,10 @@ jobs:
         if: steps.classify.outputs.changelog_only != 'true' && steps.classify.outputs.docs_only != 'true'
         run: go run github.com/rhysd/actionlint/cmd/actionlint@v1.7.12
 
+      - name: Test reviewer routing policy
+        if: steps.classify.outputs.changelog_only != 'true' && steps.classify.outputs.docs_only != 'true'
+        run: node .github/reviewer-routing.test.js
+
   test-focused:
     name: Test (changed packages)
     needs: lint
@@ -490,7 +494,8 @@ jobs:
     needs: lint
     if: ${{ needs.lint.outputs.changelog_only != 'true' && needs.lint.outputs.docs_only != 'true' && needs.lint.outputs.full_suite == 'true' }}
     runs-on: ubuntu-latest
-    timeout-minutes: 15
+    # cli/smoke shards need headroom beyond go test -timeout for setup + assembly.
+    timeout-minutes: 20
     strategy:
       fail-fast: false
       matrix:
@@ -498,6 +503,8 @@ jobs:
           - app
           - generators
           - helpers
+          - cli
+          - smoke
           - remaining
     steps:
       - name: Check out repository
@@ -523,7 +530,13 @@ jobs:
           test -n "$package_output"
           mapfile -t packages <<< "$package_output"
           test "${#packages[@]}" -gt 0
-          go test -v -race -count=1 -timeout=12m "${packages[@]}"
+          # cli/smoke own heavy NewRootCommand / Schema assembly under -race; give
+          # them a dedicated budget so remaining is not SIGTERM'd by OOM/timeout.
+          timeout_budget=12m
+          if [ "$TEST_SHARD" = "cli" ] || [ "$TEST_SHARD" = "smoke" ]; then
+            timeout_budget=15m
+          fi
+          go test -v -race -count=1 -timeout="$timeout_budget" "${packages[@]}"
 
   test-release-scripts:
     name: Test (workflow and release contracts)
@@ -693,8 +706,11 @@ jobs:
         with:
           go-version-file: go.mod
 
-      - name: Test macOS auth and Keychain paths with Race Detection
-        run: go test -v -race -count=1 -timeout=10m ./internal/keychain ./internal/auth ./internal/app
+      - name: Test macOS auth and Keychain packages with Race Detection
+        run: go test -v -race -count=1 -timeout=6m ./internal/keychain ./internal/auth
+
+      - name: Test macOS auth migration, Keychain diagnostics, and upgrade self-heal with Race Detection
+        run: go test -v -race -count=1 -timeout=5m ./internal/app -run '^(TestValidateNewBinary_RecoversFromUnsignedDarwin|Test(CrossPlatformCoverage)?Auth(MigrateKeychain|StatusDiagnosticReportsCiphertextKeyMismatch))'
 
   test-windows:
     name: Test (Windows)
@@ -805,6 +821,7 @@ jobs:
         run: ./scripts/policy/run-platform-coverage-gate.sh --base-ref "$COVERAGE_BASE_REF" --profile coverage-windows.txt
 
       - name: Upload Windows coverage artifact
+        if: always()
         uses: actions/upload-artifact@v4
         with:
           name: coverage-windows
@@ -1163,7 +1180,7 @@ jobs:
           FULL_SUITE: ${{ needs.lint.outputs.full_suite }}
           COVERAGE_TARGET: "100"
           COVERAGE_ENFORCE_OVERALL: "false"
-          COVERAGE_OVERALL_TOLERANCE: "0"
+          COVERAGE_OVERALL_TOLERANCE: "0.1"
         run: |
           policy_profile=coverage-policy.txt
           if [ "$FULL_SUITE" != true ]; then
@@ -1353,29 +1370,47 @@ jobs:
           if [ -z "$base_ref" ] || [ "$base_ref" = "0000000000000000000000000000000000000000" ]; then
             base_ref="$(git rev-parse HEAD^)"
           fi
+          candidate_ref="$(git rev-parse 'HEAD^{commit}')"
+          if [ "$GITHUB_EVENT_NAME" = "pull_request" ] && [ "$candidate_ref" != "$PR_HEAD_SHA" ]; then
+            echo "Compatibility checkout $candidate_ref does not match PR head $PR_HEAD_SHA" >&2
+            exit 1
+          fi
           git rev-parse --verify "${base_ref}^{commit}" >/dev/null
-          stable_ref="$(git tag --merged "$base_ref" --list 'v[0-9]*' --sort=-version:refname | awk 'index($0, "-") == 0 { print; exit }')"
+          . ./scripts/release/release-lib.sh
+          stable_ref=""
+          for tag in $(git tag --merged "$base_ref" --list 'v*' --sort=-version:refname); do
+            release_is_stable_version "$tag" || continue
+            if git rev-parse --verify --quiet "refs/tags/withdrawn/$tag" >/dev/null; then
+              continue
+            fi
+            stable_ref="$tag"
+            break
+          done
           if [ -z "$stable_ref" ]; then
             echo "No stable release tag is reachable from compatibility base $base_ref" >&2
             exit 1
           fi
           git rev-parse --verify "${stable_ref}^{commit}" >/dev/null
-          echo "COMPATIBILITY_BASE_REF=$base_ref" >> "$GITHUB_ENV"
-          echo "COMPATIBILITY_STABLE_REF=$stable_ref" >> "$GITHUB_ENV"
+          printf '%s\n' \
+            "COMPATIBILITY_BASE_REF=$base_ref" \
+            "COMPATIBILITY_STABLE_REF=$stable_ref" \
+            "COMPATIBILITY_CANDIDATE_REF=$candidate_ref" >> "$GITHUB_ENV"
 
-      - name: Check historical commands and help compatibility
+      - name: Check historical commands, help, and complete CLI 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 authoritative-interface-integrity \
-            BASE_REF="$COMPATIBILITY_BASE_REF"
-          if [ "$(git rev-parse "${COMPATIBILITY_BASE_REF}^{commit}")" != "$(git rev-parse "${COMPATIBILITY_STABLE_REF}^{commit}")" ]; then
-            make authoritative-interface-integrity \
-              BASE_REF="$COMPATIBILITY_STABLE_REF"
-          fi
+            BASE_REF="$COMPATIBILITY_BASE_REF" \
+            STABLE_REF="$COMPATIBILITY_STABLE_REF" \
+            CANDIDATE_REF="$COMPATIBILITY_CANDIDATE_REF"
 
       - 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"
+        run: |
+          make schema-compatibility \
+            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/reviewer-router.yml

@@ -21,6 +21,11 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 5
     steps:
+      - name: Check out trusted routing policy
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          ref: ${{ github.event.pull_request.base.sha }}
+          persist-credentials: false
       - name: Route review and enable auto-merge
         uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b # v7.1.0
         with:
@@ -29,12 +34,13 @@ jobs:
             const repo = context.repo.repo;
             const pullNumber = context.payload.pull_request.number;
             const eventHeadSha = context.payload.pull_request.head.sha;
-            const reviewerPool = [
-              'sczheng189',
-              'shangguanxuan633-lab',
-              'audanye-sudo',
-              'wxianfeng',
-            ];
+            const {
+              REVIEWER_POOL,
+              requestReviewersWithFallback,
+              resolveReviewRouting,
+              reviewerCandidates,
+            } = require('./.github/reviewer-routing.js');
+            const reviewerPool = REVIEWER_POOL;
 
             async function getReadyEventPull(phase) {
               const {data: currentPull} = await github.rest.pulls.get({
@@ -67,6 +73,21 @@ jobs:
                 : author;
 
             async function routeReview() {
+              let changedFiles;
+              try {
+                changedFiles = await github.paginate(github.rest.pulls.listFiles, {
+                  owner,
+                  repo,
+                  pull_number: pullNumber,
+                  per_page: 100,
+                });
+              } catch (error) {
+                core.warning(
+                  `Could not inspect changed files for PR #${pullNumber}; using load-balanced fallback (${error.status || 'unknown status'}).`,
+                );
+                changedFiles = [];
+              }
+
               const eligible = reviewerPool.filter(
                 reviewer =>
                   reviewer.toLowerCase() !== author &&
@@ -77,13 +98,9 @@ jobs:
                 return;
               }
 
-              const alreadyRequested =
-                (pullRequest.requested_reviewers || []).length > 0 ||
-                (pullRequest.requested_teams || []).length > 0;
-              if (alreadyRequested) {
-                core.info(`PR #${pullNumber} already has a requested reviewer; leaving it unchanged.`);
-                return;
-              }
+              const existingRequestedReviewers = new Set(
+                (pullRequest.requested_reviewers || []).map(({login}) => login.toLowerCase()),
+              );
 
               let reviews;
               try {
@@ -116,22 +133,18 @@ jobs:
                   latestDecisionByLogin.set(login, review);
                 }
               }
-              const currentHeadDecision = [...latestDecisionByLogin.values()].find(
-                review =>
-                  review.commit_id === headSha &&
-                  eligible.some(
-                    reviewer =>
-                      reviewer.toLowerCase() ===
-                      review.user.login.toLowerCase(),
-                  ) &&
-                  ['APPROVED', 'CHANGES_REQUESTED'].includes(review.state),
+              const currentHeadReviewers = new Set(
+                [...latestDecisionByLogin.values()]
+                  .filter(
+                    review =>
+                      review.commit_id === headSha &&
+                      eligible.some(
+                        reviewer => reviewer.toLowerCase() === review.user.login.toLowerCase(),
+                      ) &&
+                      ['APPROVED', 'CHANGES_REQUESTED'].includes(review.state),
+                  )
+                  .map(review => review.user.login.toLowerCase()),
               );
-              if (currentHeadDecision) {
-                core.info(
-                  `PR #${pullNumber} already has a ${currentHeadDecision.state} review on its current head; leaving review ownership unchanged.`,
-                );
-                return;
-              }
 
               const loads = new Map(eligible.map(reviewer => [reviewer, 0]));
               try {
@@ -178,20 +191,42 @@ jobs:
                   tieOrder.get(left) - tieOrder.get(right),
               );
 
-              for (const reviewer of ranked) {
-                try {
+              const routing = resolveReviewRouting({
+                files: changedFiles,
+                author,
+                latestPusher,
+                fallbackReviewers: ranked,
+              });
+              const candidates = reviewerCandidates({
+                preferredReviewers: routing.reviewers,
+                fallbackReviewers: ranked,
+                eligibleReviewers: eligible,
+              });
+              const desiredReviewers = candidates.slice(0, routing.requiredReviewers);
+              if (routing.reason === 'unknown_paths' && currentHeadReviewers.size > 0) {
+                core.info(
+                  `PR #${pullNumber} has a current-head review for unknown paths; leaving manual ownership unchanged.`,
+                );
+                return;
+              }
+              core.info(
+                `PR #${pullNumber} routing: ${routing.reason}; modules=${routing.modules.map(module => module.id).join(',') || 'unknown'}; reviewers=${desiredReviewers.join(',') || 'load-balanced fallback'}.`,
+              );
+
+              const satisfiedReviewers = new Set([
+                ...currentHeadReviewers,
+                ...[...existingRequestedReviewers].filter((reviewer) =>
+                  candidates.some((candidate) => candidate.toLowerCase() === reviewer),
+                ),
+              ]);
+              const requestResult = await requestReviewersWithFallback({
+                candidates,
+                requiredReviewers: routing.requiredReviewers,
+                satisfiedReviewers: [...satisfiedReviewers],
+                requestReviewer: async (reviewer) => {
                   const currentPull = await getReadyEventPull('review request');
                   if (!currentPull) {
-                    return;
-                  }
-                  if (
-                    (currentPull.requested_reviewers || []).length > 0 ||
-                    (currentPull.requested_teams || []).length > 0
-                  ) {
-                    core.info(
-                      `PR #${pullNumber} received a reviewer while routing; leaving it unchanged.`,
-                    );
-                    return;
+                    return false;
                   }
                   await github.rest.pulls.requestReviewers({
                     owner,
@@ -202,15 +237,23 @@ jobs:
                   core.info(
                     `Requested @${reviewer} for PR #${pullNumber} (open request load: ${loads.get(reviewer)}).`,
                   );
-                  return;
-                } catch (error) {
+                  return true;
+                },
+                onFailure: (reviewer, error) => {
                   core.warning(
                     `Could not request @${reviewer} for PR #${pullNumber}; trying the next candidate (${error.status || 'unknown status'}).`,
                   );
-                }
+                },
+              });
+              if (requestResult.aborted) {
+                return;
               }
 
-              core.warning(`No reviewer request could be created for PR #${pullNumber}.`);
+              if (requestResult.satisfiedReviewers.length < routing.requiredReviewers) {
+                core.warning(
+                  `Only ${requestResult.satisfiedReviewers.length} of ${routing.requiredReviewers} required reviewers could be satisfied for PR #${pullNumber}.`,
+                );
+              }
             }
 
             async function enableAutoMerge() {

AGENTS.md

@@ -5,21 +5,75 @@ unrelated work, and use `gofmt` for every modified Go file.
 
 ## Build and test
 
-- Build: `go build ./cmd`
+- Build: `make build` (wraps `scripts/dev/build.sh` → `go build -o dws ./cmd`; bare `go build ./cmd` fails because output name `cmd` collides with the directory)
 - Full test suite: `DWS_PACKAGE_VERSION=0.0.0-test go test ./...`
-- Generate Schema assets: `go generate ./internal/cli` (entry point: `internal/cli/gen.go`)
-- Refresh pinned MCP metadata: `make fetch-mcp-metadata` (requires `dws auth login`)
-- Check generated drift: `./scripts/policy/check-generated-drift.sh`
+- Param aliases generate: `go generate ./internal/cli` (entry point: `internal/cli/gen.go`; Catalog is not generated)
+- Optional diagnostic MCP dump (not a Schema pin): `make fetch-mcp-metadata` (requires `dws auth login`; writes under `artifacts/`)
+- Check generated drift + assembly determinism: `./scripts/policy/check-generated-drift.sh`
 - Check the Schema contract: `./scripts/policy/check-schema-catalog.sh`
+- Coverage-gate test naming: tests that carry coverage for the macOS platform
+  gate must be named `TestCrossPlatformCoverage*` (or `TestAllShortcuts*`);
+  `scripts/policy/run-platform-coverage-gate.sh` only selects those prefixes,
+  so a covering test with any other name silently leaves its target uncovered.
+- Package-var injection seams (e.g. `pipelineBuildEffectiveRegistry`): swap
+  them in tests only via `testseam.Swap(t, &seam, stub)` from
+  `internal/testseam` — it restores the previous value through `t.Cleanup`
+  structurally. Like the manual pattern it replaces, Swap mutates global state
+  and is **not** safe for `t.Parallel` tests.
+- Cross-package test helpers (e.g. `StoreProductDeclRawForTest`) live in
+  per-package `fortest.go` files, never scattered through production files;
+  the `ForTest` suffix is the boundary and production code must not call them.
 
-Generated Schema JSON is committed. Change its source inputs and generators,
-then regenerate; do not hand-edit generated Catalog or Agent metadata files.
-`internal/cli/schema_command_registry.json` is different: it is a reviewed
-`CommandRegistry` source, not a generated snapshot. It is the single reviewed
-source of stable canonical identity,
-primary paths, aliases, and navigation. Edit it only when reviewed exposure,
-identity, primary path, or aliases change; parameter, Skill, and metadata-only
-changes must not rewrite it mechanically.
+Schema Catalog delivery is **声明即 Catalog**: production assembles via
+`RegisterSchemaSourceRoot` → `ResolveSchemaBuild` (factory registered in
+`internal/app`). There is no
+`cmd_schema_catalog` `//go:generate` delivery step. `dws schema -f json` remains
+the wire projection. `cmd_schema_catalog` produces CI/local dumps only;
+`internal/cli/schema_catalog/`, `internal/cli/schema_meta_index.gob`, and
+`internal/cli/schema_meta_index.json` must not be committed. `schema_agent_metadata/` is retired: if that directory
+(or `schema_agent_metadata_audit.json`) is present, policy fails.
+Command identity is no longer a file input: it is collected from
+`ContractFinal.Identity` on the live Cobra leaves
+(`internal/cli/schema_identity_collect.go` → `BuildEffectiveCommandRegistry`).
+The reviewed `schema_command_registry/` was retired together with that
+switchover and must not reappear; identity changes happen by editing the leaf
+declaration. The remaining **reviewed inputs** under `internal/cli` (see Agent
+Schema contract) keep separate authorities — do not merge them with
+`param_concepts.json` or promote any of them into Catalog declaration.
+
+## Command framework declaration
+
+- Framework definition: `docs/rfc-command-framework-convergence.md` **§5.0**
+- 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.
+- Package seam:
+  - types / ProductDecl → `corecmd/contract` (DTO only; **no** Cobra-keyed ContractFinal store)
+  - AnnotateRuntime* writers → `internal/corecmd/runtimeannotate` (framework-owned)
+  - ContractFinal cobra store + Register → `internal/corecmd/contractfinal` (framework-owned)
+  - homology gates → `internal/cli/homology`
+  - Catalog assembly / `ResolveMeta` (`RegisterSchemaSourceRoot` → `ResolveSchemaBuild`); go:embed only for reviewed inputs → `internal/cli` root (package-local aliases for annotate/store APIs live in `runtime_schema_seam.go`; the former `cli/runtimeannotate` / `cli/contractfinal` shim packages are removed — import `corecmd/*` directly)
+  - **Hard rule**: `internal/corecmd` (and its subpackages) must **not** import any `internal/cli` package
+- Authoring tiers (current, not aspirational):
+  - **Tier1** — `corecmd.New` / `helpers.NewLeafCommand` (fully managed declare + execute)
+  - **Tier2** — `DeclareLeafMetadata` (helpers migration; **Shortcut may also use this path — acceptable**)
+  - **Tier3** — bare Cobra (should shrink over time; reviewed exclusions where needed)
+  - Long-term outlook only: broader mcpbind / fewer hand-written `Execute` bodies. **Not** a current hard requirement to delete `Shortcut.Execute` or force mcpbind.
+- Description declare vs delivery: construction requires `ContractDecl.Description` (evidence). Catalog delivery prefers Cobra Long → provenance `cobra_help`; without Long, declared text → `contract_final`. Title: declared first, then Short, then MCP. Do **not** read this as "declare = wire final" or dual authority.
+- **Execute** = hooks (`Validate` / `Call` / `RunE` / `PostMount`) — not a second surface authority
+- Declaration path has **no reviewed parallel fields**; migration-only `runtime_gate` annotate until `Safety` is declared
+- **Do not add** new production `AnnotateRuntimeRisk` / `AnnotateRuntimeGate`
+  (`runtime_gate`) call sites; migrate leaves to declared `Safety` /
+  `ContractDecl` instead. Existing annotate sites may remain until migrated.
+
+## flag / help / schema homology
+
+- Decision (path A — Contract/LeafSpec is CLI-surface authority **and must embed into Schema**): `docs/flag-help-schema-homology.md`
+- Hard rule: every help/Schema fact is **declared** **or** **annotated**; never inference-only (§1.1–§1.3; framework §5.0).
+- Embed path: `corecmd.New` → `dws.schema.*` annotations → Schema catalog assembly
+- MCP metadata must not create CLI flags; optional 1:1 passthrough is a gated subset only.
+- Gate IDs: `HOM-P*`, `HOM-S*`, `HOM-I1`, `HOM-D1` (see that doc §3–§4). `HOM-P1`/`HOM-D1`/`HOM-S1`/`HOM-S2` are on the `check-schema-catalog.sh` policy whitelist; remaining IDs land incrementally.
 
 ## Agent Schema contract
 
@@ -28,90 +82,115 @@ The Schema data flow is one way:
 ```text
 1. app.NewRootCommand()
    └─ builds the real Cobra command tree and flags
+   └─ leaf Safety / Contract / contract.ParamDecl declare ContractFinal (declare-or-annotate)
 
-2. schema_command_registry.json
-   + schema_hints/metadata/<product>.json tool parameters (+ cli_path)
+2. CollectIdentitySpecs (ContractFinal.Identity on live Cobra leaves)
    └─ forms EffectiveCommandRegistry
       └─ binds exactly to real Cobra leaves and aliases
 
 3. Parameter resolution
    Cobra flags
-   + schema_parameter_bindings.json
-   + metadata tool parameters
+   + contract.ParamDecl.Property / native annotations (primary property authority)
+   + schema_parameter_mapping_ledger.go (mapping_exclusions / removals only;
+     active bindings JSON retired after Track 1 Phase 2)
    └─ produces ParameterSpec and constraints
 
 4. Agent and interface semantics
-   schema_hints/selection/<product>.json   (selection prose)
-   + schema_hints/metadata/<product>.json  (safety/interface/runtime_gate)
-   + pinned MCP metadata
+   ProductDecl + leaf ContractFinal Selection / Safety / Interface
+   + contract.ParamDecl (interface_type / property)
    └─ resolves Agent metadata by source precedence
       Markdown is evidence only; it is not concatenated into final prose
+   └─ schema_hints/ and schema_mcp_metadata.json are fully retired
 
-5. One typed hub
+  5. One typed hub
    BoundCommandRegistry
    + ParameterSpec
    + Agent metadata
    + Interface metadata
    └─ resolves every command exactly once into ToolSpec
-      └─ aggregates SchemaRegistry + SchemaIndex
+   └─ aggregates SchemaRegistry + SchemaIndex
+   └─ ResolveSchemaBuild assembles at runtime; deliverySchemaCatalog wraps it (lazy, sync.Once)
 
-6. One-way publication
+  6. Runtime delivery (no generate-written Catalog authority)
    SchemaRegistry
-   └─ internal/cli/schema_catalog/
-      (catalog.json + tools/<product>.json; split per product so
-       concurrent feature PRs only rewrite their own shard)
-      └─ dws schema list/product/group/leaf/--all
-
-7. Runtime consumption (unified API)
-   ResolveMeta(cliPath) → CommandMeta{Identity, Safety, Selection}
-   └─ internal/cli/command_meta.go
-   └─ all consumers (help, schema, agent, skill-gen) call this one function
-   └─ backed by embedded catalog (sync.Once lazy map, O(1) lookup)
+   └─ dws schema list/product/group/leaf/--all (-f json wire)
+   └─ ResolveMeta projects Identity/Safety/Selection from the same registry
+   └─ CI may dump Catalog via cmd_schema_catalog for jq gates / determinism
 ```
 
-Parameter overlays from metadata are merged into `EffectiveCommandRegistry`
-*before* Cobra binding; after that point there is no second identity source and
-no identity precedence winner. The binder must reject a missing/non-runnable
-Cobra path, an alias collision, and any native identity annotation that
-disagrees with the effective registry. A missing native identity annotation is
-allowed because annotations are implementation-side assertions, not identity
-fallbacks.
+**Reviewed inputs / 评审输入** (organizational family under `internal/cli`;
+parallel peers, not one merged authority). These are assembly inputs only —
+never Catalog declaration authority, never leaf `Contract` / `ProductDecl`
+substitutes. Keep them side-by-side; do **not** fold one into another:
+
+| Input | Path | Owns |
+|---|---|---|
+| Command identity | collected from `ContractFinal.Identity` on live Cobra leaves (`schema_identity_collect.go`; not a file input) | stable identity, primary CLI path, aliases, navigation |
+| Param concepts | `param_concepts.json` (+ `.schema.json`) | argv synonym / concept dictionary (reduced to `param_aliases_generated.go`) |
+| Exclusions | `schema_command_exclusions.go` | exact reviewed CLI paths excluded from Schema (non-empty reason) |
+| Mapping ledger | `schema_parameter_mapping_ledger.go` | `mapping_exclusions` / removals (CLI flags with no direct RPC property); active bindings JSON retired |
+
+`schema_mcp_metadata.json` is retired and must not reappear. Interface facts
+(`interface_ref`, `interface_type`, …) declare on leaf `Contract` /
+`contract.ParamDecl`. Retiring the pin cleared MCP-sourced `interface_type`
+values from the wire; schema-compat deliberately accepts clearing (missing =
+unknown for consumers) while still rejecting any change to a different
+non-empty value. Re-populating a value requires an explicit `ParamDecl`
+declaration, not a new pin.
+
+**Aliases are three distinct layers** (do not conflate):
+
+| Layer | Owns |
+|---|---|
+| `FlagSpec.Aliases` / Cobra flag aliases | executable flag synonyms on a leaf |
+| `ContractFinal.Identity` `aliases` | reviewed CLI-path aliases for the same command identity |
+| `param_concepts.json` | argv synonym / concept dictionary (central preparse normalization) |
+
+**Visibility vs exclusions:** collected identity `visibility` is dormant (all
+entries default `public`); “runnable but not Agent-visible” belongs in
+`schema_command_exclusions.go`, not new `visibility` values. Native identity
+annotations are consistency assertions only — they must agree with the
+collected identity and never materialize or override it.
+
+Leaf declare (`Contract` / `ParamDecl` / `Safety` / `ProductDecl`) and the live
+Cobra tree remain separate from this table: declare owns semantics; Cobra owns
+executability and flags.
+
+After binding there is no second identity source and no identity precedence
+winner. The binder must reject a missing/non-runnable Cobra path, an alias
+collision, and any native identity annotation that disagrees with the effective
+registry. A missing native identity annotation is allowed because annotations
+are implementation-side assertions, not identity fallbacks.
 
 The assembler resolves every bound command exactly once into one `ToolSpec`.
-Build-time gates and the snapshot serializer consume that source-resolved typed
-registry/index. Runtime projections and delivery gates consume the typed
-registry/index returned by the production snapshot loader. Neither path may
-reopen annotations, merge source records, or use a previous Catalog or other
-generated JSON as a source. `schema_catalog/` (catalog.json + per-product
-tools/<product>.json shards) is output-only in the
-generation graph. The production loader decoding the embedded published
-snapshot is a delivery boundary, not source resolution; it must never create or
-repair a Cobra command, flag, registry entry, or later Catalog generation.
+CI determinism (`check-schema-assembly.sh`) and policy jq gates consume a
+fresh assembly dump; runtime consumes the same `ResolveSchemaBuild` path via
+`RegisterSchemaSourceRoot`. Neither path may reopen annotations, merge source
+records, or use a previous Catalog JSON as a source.
 
-### Generation vs consumption separation
+### Assembly vs consumption
 
-The Schema system has two physically separated processes:
+**Assembly** (declare → typed registry; CI + runtime):
+- Runtime entry: `RegisterSchemaSourceRoot` (`internal/app`) →
+  `ResolveSchemaBuild` / `deliverySchemaCatalog` (lazy, sync.Once).
+- CI tool: `cmd_schema_catalog` dumps an assembled Catalog for jq/determinism;
+  it is **not** a `//go:generate` or committed delivery step.
+- `gen.go` only generates `param_aliases_generated.go`.
+- Inputs: **reviewed inputs** (param_concepts / exclusions / mapping ledger —
+  see table above) + ProductDecl/ContractFinal (identity is collected from
+  `ContractFinal.Identity`) + live Cobra tree.
+  `schema_hints/`, `schema_agent_metadata/`, `schema_command_registry/`, and
+  `schema_mcp_metadata.json` must not reappear.
+- Gates: `make generate-schema` (param aliases + assembly determinism),
+  `check-generated-drift.sh`, `check-schema-catalog.sh`.
 
-**Generation** (build-time, slow, reviewed, one-way):
-- Entry point: `internal/cli/gen.go` (all `//go:generate` pragmas isolated here,
-  not in business code).
-- Tools: `internal/generator/cmd_schema_agent_metadata` + `cmd_schema_catalog` +
-  `cmd_param_aliases` (standalone Go mains).
-- Inputs: 7 authored source groups (registry + hints metadata + hints selection +
-  MCP metadata + parameter bindings + reviewed parameter concepts + cobra tree).
-- Output: `schema_catalog/` (per-product shards) + `schema_agent_metadata/` +
-  `param_aliases_generated.go`.
-- Refresh MCP metadata: `make fetch-mcp-metadata` (iterates 26 MCP server
-  endpoints, merges with previous data for cross-server interface_ref).
-- Gates: `make generate-schema` (byte guards on inputs), `check-generated-drift.sh`,
-  `check-command-surface.sh` (catalog structure).
-
-**Consumption** (runtime, fast, read-only, unified API):
+**Consumption** (runtime, unified API):
 - Entry point: `ResolveMeta(cliPath) → CommandMeta{Identity, Safety, Selection}`
-  in `internal/cli/command_meta.go`.
-- Backed by embedded catalog (`embeddedSchemaCatalog()`, sync.Once, O(1) map).
+  in `internal/cli/command_meta.go` — projected from the assembled registry
+  when the app factory is registered.
 - Consumers: `--help` (Safety annotation via `RenderSafetyAnnotation`),
-  `dws schema`, agent selection, future skill generation.
+  agent selection, future skill generation; `dws schema` uses the same
+  assembled Catalog (`-f json` wire unchanged).
 - `SafetyForCLIPath` delegates to `ResolveMeta` (backward compatible).
 
 This split is architecturally isomorphic to Lark's typed metadata registry,
@@ -119,16 +198,17 @@ navigation catalog, and schema renderer. DWS intentionally preserves its
 existing flat JSON wire contract for compatibility; do not treat architectural
 alignment as permission to make an unversioned wire-format change.
 
-The reviewed `CommandRegistry` is the sole source of stable command identity
-and navigation. The executable Cobra tree remains the source of truth for
-whether a CLI path exists, is runnable, and which flags it accepts. Schema
-coverage is bidirectional:
+The identity collected from `ContractFinal.Identity` (via
+`CollectIdentitySpecs`) is the sole source of stable command identity and
+navigation. The executable Cobra tree remains the source of truth for whether
+a CLI path exists, is runnable, and which flags it accepts. Schema coverage is
+bidirectional:
 
 1. Every final `SchemaRegistry` tool, including its serialized Catalog
    projection, must resolve to an executable Cobra command.
 2. Every public runnable Cobra leaf must either resolve to Schema or appear as
    an exact, reviewed exclusion with a non-empty reason in
-   `internal/cli/schema_command_exclusions.json`.
+   `internal/cli/schema_command_exclusions.go` (central Go groups; not JSON).
 
 Do not use prefix or wildcard exclusions: they can silently hide future
 commands. Remove an exclusion when its command enters Schema; stale, invalid,
@@ -136,115 +216,117 @@ or duplicate exclusions must fail generation and CI.
 
 When adding or changing an Agent-visible command, review all relevant inputs:
 
-- `internal/cli/schema_command_registry.json` for the reviewed
-  `CommandRegistry`: canonical identity, primary CLI path, aliases, and stable
-  navigation. It is the identity source and is not a generated artifact.
-- `internal/cli/schema_command_registry.schema.json` is its closed,
-  machine-readable editing contract. Preserve the local `$schema` reference;
-  unknown fields, invalid visibility values, stale paths, and collisions fail
-  Go validation and policy.
-- `internal/cli/schema_hints/metadata/<product>.json` for safety, interface,
-  `runtime_gate`, and optional parameter overlays (`parameters` / `cli_path`).
-- `internal/cli/schema_hints/selection/<product>.json` for reviewed Agent
-  selection prose (`agent_summary`, `use_when`, `avoid_when`, `examples`).
-- `internal/cli/schema_hints/index.json` only maps product IDs to those files.
+- Leaf `ContractFinal.Identity` for canonical identity, primary CLI path,
+  aliases, and stable navigation. Identity is collected from the live Cobra
+  leaves (`CollectIdentitySpecs`); there is no separate identity file. Invalid
+  canonical paths, alias collisions, stale paths, and drift fail collection,
+  binding, and policy.
+- Leaf `Safety` / `Contract` (`corecmd.ContractDecl`) / `contract.ParamDecl`
+  (helpers `LeafSpec` or shortcut `Contract`) for parameter facts, interface
+  disposition, safety, and Agent selection prose. Delivered provenance is
+  `contract_final` from `corecmd.contract` (description may stamp `cobra_help`
+  when Cobra Long wins). Product routing uses `ProductDecl`
+  (`internal/corecmd/contract`; provenance label remains `cli.product_decl`).
+- `internal/cli/schema_hints/` is fully retired. Do not reintroduce HintFiles,
+  audit JSON, or `imported/` baselines; declare on ProductDecl / the owning
+  leaf instead.
 - Native Runtime Schema identity annotations, when present, as consistency
   assertions against `EffectiveCommandRegistry`. They must agree exactly and
   must never materialize, infer, or override registry identity.
 - Flag-to-interface property mappings and required/default semantics.
-- Generated files under `internal/cli/schema_agent_metadata/` and
-  `internal/cli/schema_catalog/` (catalog.json + tools/<product>.json) after
-  running generation.
+- Do not expect generate-written Catalog delivery. Run
+  `make generate-schema` only to refresh param aliases and prove assembly
+  determinism. Do not expect or commit `schema_agent_metadata/`.
 
 Run the reverse-completeness tests whenever the Cobra tree changes. A command
 that works through `dws <path>` but cannot be found through the matching
 `dws schema` lookup is a contract failure unless it has a reviewed exact
 exclusion.
 
-Metadata parameter overlays must reference an exact public runnable Cobra leaf
-and real flags. They may override Schema description, interface-property/type
-mapping, `required`, and `required_when`; they must not create commands or
-flags, define an interface, or advertise an unknown RPC. Every authored entry
-requires `reviewed: true` and a non-empty review reason.
+`RegisterSchemaHints` / `ToolSchemaHint` overlays are fully removed. Parameter
+and selection facts must be declared on the owning leaf (`contract.ParamDecl` /
+`Contract`) or via `ProductDecl`; do not reintroduce overlay registries.
 
-For Agent-authored metadata or selection edits:
+For Agent-authored selection edits:
 
 1. Confirm the exact command and flag names in the current Cobra tree.
-2. Edit only the owning block (`metadata/` or `selection/`); do not mix fields.
-3. Add the smallest possible entry; do not copy generated Catalog fields into
-   the input.
-4. Describe user-visible semantics in `review_reason` and parameter
-   descriptions.
-5. Run generation, drift, Schema policy, and the focused CLI tests before
+2. Declare selection prose on the owning leaf (`Contract.Selection` /
+   `DeclareLeafMetadata`) and product routing via `ProductDecl`; declare
+   safety / parameters / interface on the same leaf.
+3. Do not copy generated Catalog fields into source inputs.
+4. Run generation, drift, Schema policy, and the focused CLI tests before
    proposing the change.
 
-## Agent curation workflow (Schema hints)
+## Agent curation workflow
 
 Use this workflow when refreshing Agent selection prose and confirmation
 alignment. Prefer **agent-authored review** over bulk merge scripts that dump
-`selection-review.json` or Skill Markdown into Catalog fields.
+Skill Markdown into Catalog fields.
 
-Human-authored inputs are split into two blocks:
+Human-authored inputs:
 
 | Block | Path | Owns |
 |---|---|---|
-| **metadata** | `internal/cli/schema_hints/metadata/<product>.json` | `effect` / `risk` / `confirmation` / `idempotency` / `interface_*` / `runtime_gate` / optional `parameters` |
-| **selection** | `internal/cli/schema_hints/selection/<product>.json` | `agent_summary` / `use_when` / `avoid_when` / `examples` (+ product routing) |
+| **declaration** | helpers / shortcut `Safety` + `Contract` / `contract.ParamDecl` + `ProductDecl` | `effect` / `risk` / `confirmation` / `idempotency` / `interface_*` / parameter facts / selection prose (`contract_final`) |
 
-`index.json` only maps product IDs to those files. Do not mix selection fields
-into metadata files or metadata fields into selection files.
+`schema_hints/` is fully retired. Do not reintroduce HintFiles or audit JSON.
 
 ### Goals
 
 1. **Selection prose** is decision-oriented (Feishu/Lark style): trigger intent,
    sibling-command routing, and outcome shape — not a restatement of the
-   summary. Delivered Catalog provenance is `reviewed_explicit` from
-   `selection/`.
-2. **Safety** follows Runtime: `confirmation=user_required` iff the tool's
-   metadata `runtime_gate != none` (for example `confirm_delete`, `typed_yes`,
-   `confirm_dangerous`).
-3. **Parameter overrides** (former Manual `commands`) live on metadata tools as
-   `parameters` (+ `cli_path`) and are applied into EffectiveCommandRegistry.
+   summary. Delivered Catalog provenance is `contract_final` from leaf
+   `Contract.Selection` / `ProductDecl`.
+2. **Safety** follows Runtime: `confirmation=user_required` when the leaf
+   Contract/Safety (or remaining `runtime_gate` annotate) requires a user gate
+   (for example `confirm_delete`, `typed_yes`, `confirm_dangerous`).
+3. **Parameter facts** are declared on the leaf (`contract.ParamDecl` /
+   `Contract.Parameters` / FlagSpec). Do not reintroduce HintFile or
+   `RegisterSchemaHints` overlays.
 
 ### Authoring
 
 For every curated tool:
 
-1. Edit `metadata/<product>.json` for safety/interface/gates/parameters.
-2. Edit `selection/<product>.json` for selection prose (`reviewed: true`,
-   `review_reason`, `source_refs`).
-3. Run `make generate-schema`. Do not hand-edit generated
-   `schema_agent_metadata/` or `schema_catalog/`.
+1. Declare safety/interface/parameters/selection on the owning leaf
+   (`DeclareLeafMetadata` / `Shortcut.Contract` / `contract.ParamDecl`) and product routing
+   via `ProductDecl` when needed.
+2. Run `make generate-schema` (param aliases + assembly determinism). Do not
+   create or commit `schema_catalog/` or Schema meta-index fixtures.
 
 ### Pull live MCP descriptions (personal token)
 
-Pinned `internal/cli/schema_mcp_metadata.json` is a sanitized baseline. Prefer
-live Schema from a logged-in personal session:
+Schema delivery no longer embeds a pinned MCP JSON. Prefer live Schema from a
+logged-in personal session when reviewing interface facts before declaring them
+on the leaf:
 
 ```bash
 dws auth status                 # token_valid should be true
-dws cache refresh               # refresh discovery / tools cache
-dws schema <mcp-canonical> -f json
-# or CLI path: dws schema --cli-path "drive copy" -f json
+dws schema <mcp-canonical> --jq '{canonical_path,interface_ref,parameters}' -f json
+# or CLI path: dws schema --cli-path "drive copy" --jq '{canonical_path,interface_ref,parameters}' -f json
 ```
 
-Resolve MCP identity via `interface_ref` when CLI canonical ≠ MCP path
+Resolve MCP identity via declared `interface_ref` when CLI canonical ≠ MCP path
 (example: CLI `drive.copy_document` → live `doc.copy_document`). On pull
-failure, fall back to Skill + Cobra Help + pinned MCP, and record evidence
+failure, fall back to Skill + Cobra Help, and record evidence
 (for example `live-dws-schema:<path>#FAILED`). Never print or commit tokens.
+`make fetch-mcp-metadata` writes an optional diagnostic dump under `artifacts/`
+only — do not commit it as a Schema pin.
 
-Precedence when sources disagree: **Runtime/Cobra > live MCP > pinned MCP >
+Precedence when sources disagree: **Runtime/Cobra / leaf Contract > live MCP >
 Skill (evidence only)**.
 
 ### Parallel product agents
 
 Split work by product groups. Each agent must:
 
-- Read Skill, Cobra/`--help`, Runtime confirmation sites, and live `dws schema`
-  for its tools.
-- Hand-write selection + metadata; forbid wholesale JSON merges from review
-  dumps.
-- Edit only its `metadata/<product>.json` and `selection/<product>.json`.
+- Read Skill, Cobra/`--help`, Runtime confirmation sites, and live
+  `dws schema <leaf> --compact` for its tools. Mapping/interface/provenance
+  audits may query the full leaf only through a narrow `--jq` / `--fields`
+  projection; do not load an entire full leaf into Agent context.
+- Hand-write selection prose and leaf Contract / ProductDecl declarations;
+  forbid wholesale JSON merges from review dumps.
+- Edit only its product’s leaf declarations (and `ProductDecl` when needed).
 - **Never** `git checkout` unrelated product files to “clean scope”.
 
 ### Regenerate and gates
@@ -255,23 +337,24 @@ make generate-schema
 go test ./internal/app -run '^TestSheetFinalSchemaConfirmationMatchesRuntimeGuards$' -count=1
 ```
 
+`check-runtime-confirmation-truth.sh` compares live ContractFinal.Safety with the assembled ToolSpec `confirmation=user_required` and probes the runtime gate.
+`schema_hints/` must stay absent.
+
 Example rules (fail generation otherwise):
 
 - At most two examples per tool; no `--yes` in stored examples.
 - Examples must match live Cobra argv (path, flags, required groups).
 - No shell comments in examples.
 
-After generation, spot-check Catalog: selection provenance is
-`reviewed_explicit` from `selection/`, and `user_required` count equals
-metadata `runtime_gate != none`.
+After generation, spot-check Catalog: selection and safety/interface
+provenance are `contract_final` from ProductDecl / leaf declarations
+(`user_required` must match Runtime confirmation gates).
 
-`make generate-schema` is a full deterministic snapshot rebuild, not an
-incremental patch over the previous Catalog. It rereads every reviewed input,
-removes stale generated product metadata, and rewrites the exact metadata and
-Catalog projections. Incremental work happens only when an Agent or human
-edits selected `metadata/` or `selection/` entries; the next publication still
-recomputes all outputs. Generated files must never be read back as merge input,
-and byte guards fail generation if it changes the hint inputs or CommandRegistry.
+`make generate-schema` refreshes `param_aliases_generated.go` and runs
+assembly determinism (`check-schema-assembly.sh`). It does not rewrite a
+committed Catalog as delivery authority — runtime reassembles from
+declarations. Byte guards fail if generation mutates parameter-concept
+inputs; policy fails if the retired `schema_command_registry/` reappears.
 
 Selection prose may choose a more or less restrictive recommendation. It cannot
 create a Cobra command or flag, change parameter facts, invent an
@@ -317,7 +400,7 @@ proves natural-language understanding.
 
 Semantic selection is an explicit opt-in live-model check. Run the smoke set
 (one positive and one negative scenario per product) with
-`DWS_AGENT_SELECTION_LIVE=1 ARK_API_KEY=... ARK_BASE_URL=... ARK_MODEL=... go test ./internal/app -run TestManualAgentSelectionArkLive -count=1`.
+`DWS_AGENT_SELECTION_LIVE=1 ARK_API_KEY=... ARK_BASE_URL=... ARK_MODEL=... go test ./internal/app -run TestAgentSelectionArkLive -count=1`.
 Add `DWS_AGENT_SELECTION_FULL=1` to evaluate every committed tool scenario, or
 set `DWS_AGENT_SELECTION_CASES` to comma-separated fixture case IDs. Normal CI
 never calls a model; its blockers remain the reproducible fixture, binding,
@@ -341,14 +424,21 @@ Preserve all candidates and the selected source in provenance, and fail
 same-precedence conflicts rather than silently merging them.
 
 `required` is the exception. Cobra `MarkFlagRequired` is a hard floor: the
-final Agent projection must keep `required=true` and cannot be lowered by
-manual/hint overlays. Overlays may still raise an optional flag to required.
-`cli_required` continues to mirror the executable Cobra marker.
+final Agent projection must keep `required=true` and cannot be lowered by a
+lower-precedence source. A higher-precedence declaration may still raise an
+optional flag to required. `cli_required` continues to mirror the executable
+Cobra marker.
 
-For command text, reviewed `ToolSchemaHint` wins first, then command-specific
-Cobra Help, then MCP metadata. Generic RPC prose may remain an unselected
-provenance candidate (and parameter-level `interface_description`); it must not
-overwrite a specialized leaf's title or description.
+For command-level description: **declare required, delivery Long may win**.
+`ContractDecl.Description` is mandatory at construction (declaration evidence).
+Catalog delivery prefers Cobra Long when present (provenance `cobra_help`,
+resolution `cobra_help_preferred`); without Long, the declared Description is
+delivered as `contract_final`. Title keeps declared ContractDecl /
+ContractFinal first, then Cobra Short, then MCP metadata. This is one authority
+chain with an explicit delivery preference — not two competing sources.
+Generic RPC prose may remain an unselected provenance candidate (and
+parameter-level `interface_description`); it must not overwrite a specialized
+leaf's title or description.
 
 For every delivered `ToolSpec` and `ParameterSpec` field, the provenance
 winner value must exactly equal the delivered value. Checking only source,
@@ -382,13 +472,15 @@ path; a generator unit test or JSON count alone is insufficient.
   `parameters` object for commands without flags. Keep it suitable for the #602
   compatibility baseline and fail rather than silently emitting a partial
   export.
-- `schema --all` is not normal command discovery. Use overview -> product/group
-  -> leaf for routine Agent work. `--compact` is supported for context-saving
-  projections, but a compact full export is not a complete compatibility
-  baseline.
+- `schema --all` is not normal command discovery. Use overview -> compact
+  product/group -> compact leaf for routine Agent work. `--compact` is the
+  reviewed positive-field allowlist for Agent context: new full/audit fields
+  must not appear there until explicitly reviewed. A compact full export is not
+  a complete compatibility baseline.
 - `dws <path> --help` defines whether Cobra exposes a path and which flags the
-  executable accepts. A leaf Schema defines Agent selection, parameter mapping
-  and constraints, and safety/confirmation semantics. A conflict is contract
-  drift, not permission to guess.
+  executable accepts. A compact leaf defines Agent selection, CLI parameters,
+  constraints, and safety/confirmation semantics. Full leaf fields such as
+  `property`, `interface_ref`, and provenance are audit facts. A conflict is
+  contract drift, not permission to guess.
 - Schema and Help describe commands; neither returns DingTalk business data.
   After discovery, execute the real read/search/list command to obtain data.

CHANGELOG.md

@@ -6,6 +6,293 @@ The format is inspired by [Keep a Changelog](https://keepachangelog.com/) and th
 
 ## [Unreleased]
 
+### Added
+
+- **Streaming-card mentions** — `chat +messages-send-card` now accepts
+  `--at-open-dingtalk-ids` and `--at-all` for group cards, passing mention
+  targets to the initial card-creation request and prepending its returned
+  `atTag` to the automatic streaming update.
+
+## [1.0.58-beta.2] - 2026-08-10
+
+### Added
+
+- **`dws sheet create-with-data`（新命令）** — 建表并写入初始数据与样式：`--values`（二维数组写默认表）/ `--sheets`（typed table 多工作表，二者必须给一个）/ `--styles`（`cell_styles` / `row_sizes` / `col_sizes` / `cell_merges`，顶层键对齐飞书 snake_case、列表项内字段兼容 camelCase）。所有结构、字段类型与枚举在创建文档之前校验，非法配置不会留下白建的空文档：`--sheets` 按 `table_put` 的输入契约逐字段校验（`columns` 必填且列名非空不重复、`data` 为二维且行宽与 `columns` 一致、单元格仅限字符串/数字/布尔/null、`dtypes`/`formats` 的键须是列名、`mode`/`header`/`allowOverwrite`/`startCell` 类型与取值、单表 30000 单元格上限），并拒绝未知键、snake_case 变体、`{"sheets":"bad"}` 这类畸形包装与 `sheetId`（服务端会静默丢弃写错的键，导致"只写了表头却报成功"的静默丢数据）；`--values` 校验单元格为标量并受 30000 单元格 / 2000000 字符上限约束；`--styles` 的顶层键与列表项内字段同样拒绝未知键，避免样式只应用一半。写入后回读校验按 `startCell` / `header` / `mode` 推算的首个预期非空单元格，而非固定 A1。该命令是多步编排（建文档 → 探活 → 定位默认工作表 → 写数据 → 回读 → 可选样式），因此如实声明为独立叶子 `sheet.create_with_data` + `interface_mode: composite`（附评审 reason，按契约不带 `interface_ref`）；**`dws sheet create` 保持原样不变**——仍是一次 `create_workspace_sheet` 直连（`interface_mode: mcp`），不新增 flag，避免让 Schema 消费者把编排步骤的参数误当成该 RPC 的入参。
+- **`dws sheet export-csv`（新命令）** — 同步导出单个工作表为 RFC4180 CSV，支持 `--sheet-id` 选表、`--range` 限定范围、`--value-render-option` 选取值模式；`--output` 落盘（为目录时按 `sheet-export.csv` 命名，落盘走 `AtomicWrite` 原子替换，写入失败时已有文件保持原样；父目录不存在按错误处理，不会自动创建），不传则把纯 CSV 打到 stdout（警告只走 stderr）。数据超出单次读取上限时默认报错、既不输出也不写文件，需 `--allow-truncated` 显式接受不完整结果。响应缺 `csv` 字段或类型不对一律报错，不会用 0 字节覆盖已有文件。该分支读的是 `get_range_as_csv`、与 xlsx 的异步导出任务毫无关系，因此独立成叶子 `sheet.export_csv` 并如实声明 `interface_mode: mcp` + `interface_ref: get_range_as_csv`；**`dws sheet export` 保持原样不变**——仍只导 xlsx（`interface_ref: submit_export_job`），flag 面仍是 `--node` / `--output`，csv 专属 flag 不会出现在它上面（此前挂在同一条命令上时，漏写 `--export-format csv` 会让 `--range` 被静默丢弃而导出整篇工作簿）。
+- **`sheet update-dimension --size-type`** — `pixel` / `standard`（恢复默认行高列宽）/ `auto`（按内容自适应行高，仅 ROWS）。
+- **`sheet replace --match-formula`** — 在公式文本中查找替换。
+- **`sheet range set-style` 扩展样式维度** — 新增 `--font-style`（斜体）/ `--font-line`（下划线、删除线）/ `--font-family` / `--border-styles-json`（四边边框；每条边只接受 `style` / `color`，未知键与非字符串 `color` 直接报错，不再静默忽略而画出无颜色的边框，`set-style` / `batch-set-style` / `create-with-data --styles` 三条路径同源校验）。
+- **`sheet range batch-set-style --ranges`** — 一组样式刷多个带工作表前缀的区域，组装为一次原子 `batch_update`。
+
+### Changed
+
+- **Chat message post-send ID handoff** (#897) — CLI Help and bundled Skills
+  now document the `send` → `query-send-status` → `edit`/`recall` workflow,
+  so callers can reuse returned task, message, and conversation IDs instead
+  of searching message history by content.
+- **Sheet mono/multi Skill alignment** — replaces the oversized mono Sheet
+  reference with the progressive routing layout, aligns all 20 Sheet topic
+  references across the mono and multi bundles, and adds a content-policy guard
+  that prevents the paired topic trees from drifting again.
+- **`sheet range set-style` 后端切换为 `set_cell_range`** — 样式统一走 cellStyles 路径（仅设样式、保留原值），这是斜体/下划线删除线/字体族/边框唯一可用的通道。`interface_ref` 由 `update_range` 变为 `set_cell_range`，12 个样式 flag 改为 reviewed mapping exclusion。CLI 用法向后兼容、无 flag 删除；schema-compatibility 经 reviewed 豁免判定为兼容（0 changed fields）。
+- **`sheet range batch-set-style` 改为单次原子提交** — 由本地循环多次 `update_range` 改为一次 `batch_update`，任一项失败默认整批回滚；`--continue-on-error` 由本地控制改为透传服务端。新增批量上限：最多 100 个区域且累计不超过 200000 个单元格。
+- **`sheet range batch-clear` / `batch-set-style` 的 `--ranges` 拒绝空白工作表前缀**（用户可见行为变更）— 此前只按原始串里 `!` 的位置判断，`" !A1:B2"` 修剪后工作表名成了空串，操作却照样带着 `sheetId: ""` 提交：服务端要么让整批 `batch_update` 失败，要么更糟——落到默认工作表而不是用户指定的那张表，且命令报成功。现在工作表名与范围都必须在修剪之后仍非空，否则在发起任何请求之前报错。`batch-set-style --batch` 的纯空白 `sheetId` / `range` 同样拒绝（此前只挡空字符串）；`--batch` 下发仍用原值不替用户修剪，因为 `sheetId` 可以是允许带首尾空格的工作表**名**。两条 `--ranges` 路径现在共用同一个拆分器。
+- **`sheet insert-dimension` / `delete-dimension` / `update-dimension` 的 `--length` 严格校验**（用户可见行为变更）— 解析由 `fmt.Sscanf("%d")` 改为 `strconv.Atoi`。此前只消费前缀数字，`--length 2x` / `3foo` 会被静默当成 `2` / `3` 并对错误的行列数执行操作（删除方向不可回滚）；现在整个值必须是合法正整数，否则报错「`--length` 必须为正整数（>= 1）」且不发起任何请求。**升级影响**：原先依赖这种宽松解析、在传畸形 `--length` 的脚本会开始报错，请把参数修正为纯数字。合法数字值行为不变，上限仍为 5000。`add-dimension` 的 `--length` 是 `Int` 类型 flag，一直由 cobra 严格校验，不受影响。
+- **CLI 接口兼容门禁支持 reviewed flag 类型豁免**（无用户可见变更）— `authoritative-interface-integrity` 与 `check-command-compatibility.sh` 此前一律拒绝历史命令的 flag 类型变更，即使新类型只是把同一套校验从 RunE 前移到解析期，也没有任何评审通道。现在两道门禁各带一张精确豁免表：命令路径 + flag 名 + 旧类型 → 新类型四元组全等才命中、方向敏感（`string`→`int` 与 `int`→`string` 是两个不同的键，只有被评审的方向可用），且仅当该 flag 的其他契约（shorthand / required / hidden / no-opt / scope）纹丝不动时才放行，因此豁免夹带不了别的破坏。首条也是目前唯一一条登记的是 `dws minutes permission apply --policy` 的 `string` → `int`（配合 #912）：旧实现在 RunE 里做 `strconv.ParseInt(v, 10, 64)` 再校验 `[2,4]`，新实现由 pflag 以 `strconv.ParseInt(s, 0, 64)` 解析后仍校验 `[2,4]`，**历史上能成功的调用集是新调用集的子集**（base 0 额外接受 `0x3` 这类写法，只放宽不收紧），非法值依然失败、只是报错文案与时机前移；flag 默认值由 `""` 变 `"0"` 是类型的必然结果，两道门禁都不比较默认值，且该 flag 必须显式给出、默认值不可达。两张表必须逐字一致并有守卫测试锚定漂移——重复是被迫的而非选择：`check-authoritative-interface-baselines.sh` 会把整个 `scripts/policy/interface-baseline` 目录复制进检出历史版本的 worktree 再编译，那份拷贝不能 import 本分支新增的包。
+- **Schema 兼容门禁支持 reviewed 参数类型豁免**（无用户可见变更）— 接上一条。`schema-compatibility` 是同一个 `Interface Integrity` job 里排在两道 CLI 接口门禁之后的第三道检查，此前也一律拒绝已发布参数的 `type` 变更。由于前两道先失败、`set -e` 让它从未在 CI 上暴露，上一条豁免只解决了三分之二。现在 `checkParameterCompatibility` 也带一张精确豁免表：`<product>/<tool id>` + 参数名 + 旧类型 + 新类型四元组全等才命中、方向敏感，且仅当该参数**除 `type` 外的全部已发布字段逐字段相等**时才放行。这里刻意用相等性比较而非「没有产生其他兼容性错误」：放宽 `required` / `cli_required`、清空 `required_when`、扩宽 `enum`、清空 `interface_type`、经 reviewed mapping exclusion 清空 `property`——这些变化单独看都是兼容的、根本不产生错误，若以错误列表代替相等性检查，它们就能搭着一次已评审的类型迁移一起蒙混过关。结构体整体比较还意味着将来给 `parameterSchema` 新增字段时会自动纳入守卫，而不是悄悄放宽每一条既有条目。唯一条目是 `minutes/minutes.apply_minutes_permission` 的 `policy` 由 `"string"` 迁移到 `"integer"`（配合 #912）：该 `type` 由 Cobra flag 类型投影而来（provenance `cobra_flag_type`），描述的是 CLI 如何接受取值；消费方据此拼装的是命令行，而 `--policy 4` 在两种声明下是同一个 argv，加引号的 `--policy "4"` 到 pflag 仍是 4，RunE 也仍校验 `[2,4]`——而且该参数映射的 property `policyId` 一直以数字上报，新声明比旧声明更贴近真实请求。表里的类型值必须是 `schemaType` 实际产出的带引号形态（`"string"` 而非裸 `string`），守卫测试用 `schemaType` 复算并校验类型名属于 JSON Schema 的封闭取值集合——`reviewedInterfaceRefRedirect` 曾因键的书写形态错误两次静默失效，这里不重犯。
+
+## [1.0.58-beta.1] - 2026-08-07
+
+### Added
+
+- **Robot image and file messages** (#867) — `dws chat message send-by-bot`
+  now supports image URLs and local-file uploads through explicit message
+  types, while retaining Markdown as the default and preserving its existing
+  title and text requirements.
+- **Conversation shortcut-bar management** (#877) — adds `dws chat toolbar`
+  commands to list, add, hide, sort, and manage custom conversation shortcuts,
+  with validation and confirmation for destructive removal.
+- **Complete AI Table Shortcut surface** (#901) — makes all 92 supported
+  AI Table Shortcuts discoverable through Runtime Schema and adds reliable
+  Base, table, record, attachment, view, dashboard, and workflow operations
+  with explicit confirmation and result-verification semantics for writes.
+
+### Changed
+
+- **Doc import upload fallback** — `dws doc import` no longer fails on file
+  formats outside the conversion whitelist (html, pdf, zip, extensionless,
+  and any future format): it now hands the file to the document-space upload
+  chain (the same primitive as `dws drive upload --workspace`), stores the
+  original file at the requested `--folder`/`--workspace` target, and prints
+  an explicit stderr notice with the supported-format list and the
+  convert-to-md alternative. The fallback shares the import file checks
+  (20MB cap, empty-file guard), keeps `--format json` / `--dry-run` output as
+  a single JSON document, and marks the machine-readable result with
+  `fallback: "upload"` and `converted: false` so agents never mistake the
+  stored file for a converted online document. The fallback fails closed
+  unless the commit response parses as JSON and carries a file identity
+  (exposed as `dentry_id`); empty or unverifiable responses surface as
+  errors instead of fabricated success. Importable formats and
+  `dws sheet import` validation are unchanged.
+- **IM natural-target and history alignment** — Chat shortcuts can resolve natural user/group targets before execution, and message-history workflows expose bounded time ranges, ordering, explicit all-page controls, continuation ledgers, safe local export, and thread-reply pagination without treating empty or incomplete reads as successful results. Bundled mono/multi Skills and intent routing now describe the same executable surface.
+- **Sheet CSV formula writes** — `dws sheet csv-put` and batch `csv-put` now expose the service contract that CSV fields beginning with `=` are written as formulas. Prefix the field with an apostrophe to write literal text beginning with `=`; CSV content continues to pass through unchanged.
+- **Release-equivalent PR compatibility gate** (#889) — pull-request
+  admission now runs command-surface compatibility checks against the current
+  release baseline before code reaches `main`.
+- **Reviewer routing governance** (#903) — updates the Reviewer Router pool
+  used for new ready PRs while retaining the existing current-head review and
+  required-check gates.
+
+### Fixed
+
+- **Fail-closed IM pagination and audit evidence** — `+chat-messages`, `+search-msg`, `+thread-replies`, `+at-me`, `+my-groups`, conversation lists, and favorites preserve partial-read failures, reject missing or stalled continuation state, deduplicate page boundaries, and publish completion evidence. The live-audit regression suite now rejects empty projections and incomplete reads instead of promoting them to passing results.
+- **Sheet formula verification** (#873) — `dws sheet formula-verify` now calls
+  the registered remote tool name `verify_formula`; the previous
+  `formula_verify` name failed at gateway dispatch.
+- **CLI and parameter recovery boundaries** (#864) — command and parameter
+  recovery now fail closed when an Agent-provided path or flag cannot be
+  reconciled with the executable CLI surface, reducing unsafe hallucinated
+  retries.
+
+## [1.0.57-beta.4] - 2026-08-06
+
+### Added
+
+- **Expanded open CLI workflows** (#887) — adds calendar event-instance
+  queries, Drive latest-file selection, Markdown diff, Mail calendar/export/
+  share-to-chat workflows, and Minutes hot-word, permission, and audio-memo
+  operations, with matching Schema and cross-platform coverage.
+
+### Changed
+
+- **Multi-skill framework alignment** (#887) — folds long-tail skills into
+  `dingtalk-misc`, renames the shared package to `dingtalk-shared`, removes
+  stale Preview guidance, and reorganizes shared recipes and routing for more
+  predictable Agent selection.
+- **Bounded Agent Schema delivery** (#887) — keeps compact and wire projections
+  focused on executable contract facts, retires stale MCP metadata candidates,
+  and teaches Agents to prefer `dws schema --compact` for bounded context.
+
+### Deprecated
+
+- **Recovery and discovery-cache compatibility surfaces** (#887) — keeps
+  visible Deprecated `dws recovery` and `dws cache` compatibility stubs while
+  retiring their former recovery engine and dynamic discovery-cache behavior.
+  Recovery plan/execute/finalize now return an explicit “不再支持” notice, and
+  Skills no longer teach either retired workflow.
+
+### Fixed
+
+- **Mail share-to-chat confirmation** (#887) — requires explicit confirmation
+  before the first remote write, while preserving the confirmed sign-retry
+  flow and covering both direct-success and retry responses.
+
+## [1.0.57] - 2026-08-06
+
+This stable release promotes the fully delivered `v1.0.57-beta.4` baseline.
+It includes the v1.0.57 beta-line command-contract, document, chat, OA, Wiki,
+and compatibility improvements, plus the multi-skill framework alignment and
+expanded calendar, Drive, Markdown, Mail, and Minutes workflows validated in
+the final prerelease.
+
+- **Promote v1.0.57-beta.4** — publishes the final validated prerelease
+  baseline as stable `v1.0.57` without adding post-beta product changes.
+
+## [1.0.57-beta.3] - 2026-08-06
+
+### Added
+
+- **Reviewed document shortcuts** (#880) — adds public document shortcuts for
+  safe local downloads, content and history, review, media and style, and
+  document access/sharing workflows, while retaining reviewed compatibility
+  identities and confirmation safeguards for writes.
+- **Mentions in chat replies** (#881) — `chat message reply` now supports
+  `--at-open-dingtalk-ids` and `--at-all`, forwarding reply mention fields and
+  adding any required mention placeholders without changing existing send
+  behavior.
+
+## [1.0.57-beta.2] - 2026-08-05
+
+### Fixed
+
+- **Stable Chat command compatibility** (#876) — restores the hidden migration
+  entries for `chat send`, `chat history`, and their `im` aliases, preserving
+  the v1.0.56 command surface while directing callers to the supported
+  `chat message send/list` commands. Legacy flags now reach the same migration
+  hints instead of failing during flag parsing.
+- **Drive download cancellation-test stability** (#876) — replaces a
+  timing-sensitive worker-cancellation coverage test with a deterministic seam,
+  reducing flaky CI without changing download behavior.
+
+## [1.0.57-beta.1] - 2026-08-05
+
+This beta starts the v1.0.57 line on top of v1.0.56. It packages the unified
+command-contract and runtime Schema architecture, complete Multi IM Chat
+coverage, document whiteboard and OA approval workflows, Wiki activity feeds,
+and compatibility and CI reliability fixes.
+
+### Added
+
+- **Contact personal-status updates** (#872) — adds `contact user update-ownness`
+  (alias `set-ownness`) for updating a user's personal status text. The write
+  operation maps reviewed `userId` and `ownnessText` parameters to the service
+  contract and requires confirmation unless `--yes` is explicitly supplied.
+- **Document whiteboard workflows** (#861) — adds `doc whiteboard insert`,
+  `whiteboard query/update`, and `doc media upload`. These commands support
+  confirmed document-embedded whiteboard creation and updates, structured
+  OpenNodes reads, and preparation of node-bound Vector/SVG resources.
+- **Complete Multi IM Chat coverage** (#860) — hardens deterministic group and
+  stable-ID resolution, sending, querying, downloading, pagination, and JSON
+  export. The remaining reviewed Chat Shortcuts enter Schema coverage, with
+  destructive delete and clear operations aligned to confirmation gates.
+- **OA approval form workflows** (#853) — adds OA form-schema lookup,
+  process forecast, and confirmed approval-instance creation, supporting both
+  simple flags and complete `--request` payloads.
+- **Wiki activity-feed queries** (#862) — adds `wiki feed list` to retrieve
+  workspace document activity, with cursor paging and optional file exclusion.
+
+### Changed
+
+- **Unified command and Schema contract framework** (#830) — Leaf commands and
+  Shortcuts now use the shared typed `corecmd` base for flags, constraints,
+  confirmation, Help, and runtime Schema projection. Schema delivery assembles
+  from leaf Contract declarations at runtime; the retired hint overlays,
+  pinned MCP metadata, and committed Catalog artifacts are no longer delivery
+  authorities.
+- **Faster macOS CI without reducing native coverage** (#857) — narrows the
+  macOS race suite to Keychain, codesign, and Darwin-only tests while adding a
+  reachability contract that prevents native-only tests from being silently
+  excluded.
+
+### Fixed
+
+- **Chat media-download JSON compatibility** (#854) — restores parseable
+  `success`, `downloadUrl`, and `output` fields for
+  `chat message download-media --format json` after a successful download,
+  without progress output corrupting JSON stdout.
+
+### Added
+
+- **Document-embedded whiteboard workflows** — adds `doc whiteboard insert` for confirmed creation and part-ID verification, `whiteboard query/update` for structured OpenNodes reads and confirmed writes, and `doc media upload` for preparing node-bound Vector/SVG resources. The public adapter uses an explicit helper-only whiteboard endpoint, validates update envelopes locally, decodes `resultJson`, and publishes the full command, Schema, Skill, and safety contract migrated from `dws-wukong@e2da8ab947c6`.
+- **Robot image and file messages** — extends `chat message send-by-bot` with public image URL delivery through `--msg-type image --image-url` and local-file upload/send through `--msg-type file --file-path`, while preserving Markdown as the default message type.
+
+### Changed
+
+- **Chat reply mentions** — `dws chat message reply` can @ specified group members with `--at-open-dingtalk-ids` or @ everyone with `--at-all`, forwarding the existing `send_personal_message` mention fields and automatically adding missing current-user `<@id>` / `<@all>` placeholders.
+- **Pinned MCP metadata retired** — deletes `internal/cli/schema_mcp_metadata.json` and removes its embed/loader/fallback role from Schema assembly. Catalog now assembles from Contract/ParamDecl/Interface + Cobra only; `make fetch-mcp-metadata` remains an optional diagnostic dump under `artifacts/` and refuses the retired pin path. Policy bans the pin from reappearing.
+- **MCP service review retired** — deletes `schema_mcp_service_review.json` and removes its policy jq / outputguard / test disposition gate (`notify` → `out_of_surface`, snapshot hash pin). No replacement ledger.
+- **Hints retired; ContractDecl is the leaf Schema source** (#830) — `schema_hints/`, Manual/Schema hint overlays, and `schema_agent_metadata/` delivery are removed. Selection, safety, parameters, and interface facts declare on ProductDecl / leaf `Contract` (`corecmd.ContractDecl` + `contract.ParamDecl` / `Safety`). Authoring renamed `SchemaDecl` → `ContractDecl`; nested fields reuse `contract.*` directly.
+- **Contract package seam** (#830) — types / ProductDecl live under `internal/corecmd/contract` (DTO only). Annotate writers live in `internal/corecmd/runtimeannotate`; Cobra-keyed ContractFinal store + Register live in `internal/corecmd/contractfinal`; homology gates in `internal/cli/homology`. All packages import `corecmd/*` directly; the former `cli/runtimeannotate` / `cli/contractfinal` shim packages are removed, and the `cli` root keeps only package-local aliases (`runtime_schema_seam.go`). Catalog/`ResolveMeta` stay on the `cli` delivery root. `internal/corecmd` must not import any `internal/cli` package.
+- **CommandMeta cache for ResolveMeta** — production `ResolveMeta` / leaf `--help` Safety project from the runtime-assembled `SchemaRegistry` into a `map[cli_path]CommandMeta` installed during `deliverySchemaCatalog` sync.Once. Steady-state lookups are O(1); full Catalog wire maps stay deferred. Registry `Source` stamps `runtime-assembled`.
+
+### Fixed
+
+- **Fail-closed IM pagination and audit evidence** — `+chat-messages`, `+search-msg`, `+thread-replies`, `+at-me`, `+my-groups`, conversation lists, and favorites preserve partial-read failures, reject missing or stalled continuation state, deduplicate page boundaries, and publish completion evidence. The live-audit regression suite now rejects empty projections and incomplete reads instead of promoting them to passing results.
+- **Unified command safety and Shortcut runtime (H0)** — Shortcut leaves now execute through `corecmd.New`, sharing the same typed Safety confirmation gate as Leaf commands. EOF / closed stdin returns `confirmation_required`, and interactive `no` returns the existing non-zero cancellation validation error instead of reporting success for an operation that did not run. Pass `--yes` or `--dry-run` to skip the prompt.
+- **Constraint "provided" for `at_least_one` / `exactly_one` (H0)** — a flag set to an empty string (`--flag ""`) no longer counts as provided; previously bare Cobra `Changed` satisfied the constraint. Pass a non-blank value for a member of the group.
+- **Chat media download JSON compatibility** — `dws chat message download-media --format json` once again returns a clean `{success, downloadUrl, output}` result after the file is saved, preserving the temporary URL and resolved local path without progress text corrupting JSON stdout.
+
+## [1.0.56] - 2026-08-04
+
+This stable release promotes the fully delivered `v1.0.56-beta.4` baseline.
+It includes PR #852's resilient multipart Drive download implementation,
+together with the v1.0.56 beta-line command, Schema, Skill, and runtime
+improvements already validated through the prerelease channel.
+
+### Added
+
+- **Resilient multipart Drive downloads** (#852) — `drive download` and
+  `drive download-version` support parallel chunk transfer, Range probing,
+  fingerprint-validated checkpoint resume, automatic 401/403 credential
+  refresh, and graceful interruption with checkpoint preservation.
+
+## [1.0.56-beta.4] - 2026-08-04
+
+This beta adds PR #852 on top of v1.0.56-beta.3. It makes Drive downloads
+resilient for large files through parallel transfer, validated resumable
+checkpoints, and automatic credential refresh.
+
+### Added
+
+- **Multipart Drive downloads** (#852) — adds `--part-size`, `--parallel`, and
+  `--no-resume` to `drive download` and `drive download-version`. Files above
+  the part-size threshold use a Range probe and parallel chunks, resume from a
+  fingerprint-validated checkpoint, refresh credentials on 401/403, and keep
+  the checkpoint when Ctrl+C interrupts a transfer.
+
+## [1.0.56-beta.3] - 2026-08-03
+
+This beta adds PRs #846 and #851 on top of v1.0.56-beta.2. It adds a
+service-provided Aitable workflow-editing reference command and makes local
+event-bus IPC reliable on shared filesystems by placing Unix sockets in a
+validated private runtime directory.
+
+### Added
+
+- **Aitable workflow editing reference** (#851) — adds `dws aitable workflow edit-example`, a parameter-free read command that returns the service-provided workflow editing documentation and `workflow-dsl/v1` examples through `aitable/edit_workflow_example`.
+
+### Fixed
+
+- **Event bus sockets on shared filesystems** (#846) — Unix event buses now place their local IPC socket in a private per-user runtime directory (`XDG_RUNTIME_DIR` when available, otherwise a `0700` per-UID directory under the system temporary directory) while retaining locks, metadata, logs, and subscription state in the configured Workdir. Listener and dial paths validate directory ownership and permissions before use. This prevents `dws event consume` from failing with `bind: errno 524` when `~/.dws` is hosted on NFS, CSI, FUSE, or another filesystem that does not support Unix Domain Sockets without exposing the socket directly in a shared `/tmp` root. When `XDG_RUNTIME_DIR` is unavailable, the per-UID directory name is deterministic: ownership validation prevents endpoint hijacking, but another local user can pre-create the directory to deny service; multi-user deployments should provide a private `XDG_RUNTIME_DIR`.
+
+## [1.0.56-beta.2] - 2026-07-30
+
+This beta adds PRs #831 and #835 on top of v1.0.56-beta.1. It separates
+Agent Product observability and IM display identity from the stable
+edition-owned PAT and routing identity, and reduces common-path Skill context
+loading without changing the public command or Runtime Schema surface.
+
+### Changed
+
+- **Agent Product identity separation** (#831) — sends `DWS_AGENT_PRODUCT` through the new `x-dws-agent-product` observability Header and uses a valid non-empty value for the IM `clawType` display label whenever `--ai-tag` is enabled. Because `--ai-tag` defaults to `true`, callers that set `DWS_AGENT_PRODUCT` change the displayed label by default. With `--ai-tag=false`, native `chat message send` / `reply` calls preserve their existing wire shape by sending an empty IM `clawType`, while shortcut calls omit the argument. Unset or empty Product values omit the Header and preserve the active edition's IM display default.
+- **Agent Host dimension convention** (#831) — new integrations should send the runtime form (`cloud` or `desktop`) through `DWS_AGENT_HOST` and report the product separately through `DWS_AGENT_PRODUCT`. Legacy combined labels such as `qwenwork_cloud` remain syntactically valid for compatibility.
+- **Reduced common-path Skill context** (#835) — keeps the complete 97-command Chat Shortcut inventory in Runtime Catalog and leaf Schema while routing common intents through compact Skill tables and references. When an exact command path is already known, the mono Skill no longer requires eager loading of a complete product reference. The generated Skill policy now detects drift, forced full-reference loading, and context-budget regressions; the common Chat plus shared activation estimate drops from 7,301 to 4,771 `o200k_base` tokens without changing the 845-tool Schema surface.
+
+### Fixed
+
+- **Stable PAT/routing identity** (#831) — restores the CLI-emitted open-source HTTP `claw-type` and PAT `hostControl.clawType` to the edition-fixed `openClaw` value. `DWS_AGENT_PRODUCT` no longer changes those wire values, and the client continues to derive PAT, authentication, routing, and Discovery behaviour from the existing independent signals.
+- **Portable generated Skill validation** (#835) — resolves the mono Skill name by scanning upward from the generated target, keeping `--check` independent of the repository checkout path and preventing false drift failures when an ancestor directory resembles a Skill name.
+
 ## [1.0.56-beta.1] - 2026-07-30
 
 This beta starts the v1.0.56 line on top of v1.0.55 and packages PRs #817,

CONTRIBUTING.md

@@ -68,9 +68,17 @@ coverage is additionally selected for platform-sensitive code.
 3. Include both the commands/results and user-visible or contract-level
    behavior evidence in the PR description.
 4. Run `./scripts/policy/check-command-surface.sh --strict` when command
-   paths/flags change. CI also runs
-   `./scripts/policy/check-command-compatibility.sh --base-ref <main-ref> --stable-ref <latest-GA-tag>`
-   against both the target branch and latest stable release.
+   paths/flags change. CI resolves the exact merge-base, latest reachable
+   non-withdrawn stable GA tag, and committed candidate SHA, then enters the single compatibility
+   decision seam through
+   `make authoritative-interface-integrity BASE_REF=<merge-base> STABLE_REF=<latest-GA-tag> CANDIDATE_REF=<candidate-sha>`.
+   The Make target delegates to the authoritative wrapper; CI does not invoke a
+   second comparator or the legacy fixture checker. See
+   [CLI flag compatibility migration governance](docs/cli-interface-flag-migrations.md)
+   for the reviewed two-stage `pending` → `consumed` lifecycle.
+   Agent-visible flag migrations must also run
+   `make schema-compatibility BASE_REF=<merge-base> STABLE_REF=<latest-GA-tag> CANDIDATE_REF=<candidate-sha>`;
+   it consumes the same base-owned ledger rather than a second exception list.
 5. Run `./scripts/policy/check-generated-drift.sh` when generated artifacts may
    change.
 6. Run `./scripts/release/verify-package-managers.sh` when packaging or

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.56-beta.1"
+  version "1.0.58-beta.2"
   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.56-beta.1/dws-darwin-arm64.tar.gz"
-      sha256 "26b696a7807f87cf9c6a24634e08008bac0501f2664a85a8355904309068d55e"
+      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.58-beta.2/dws-darwin-arm64.tar.gz"
+      sha256 "1b2b6953f7f1ae1ca6ecb0702424ac0e1a976a6a5ff91e8ffc3b5ae495d98c7c"
     else
-      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.56-beta.1/dws-darwin-amd64.tar.gz"
-      sha256 "28daa9fa1fc8131e3567a39042d5f34efc61d5901bf7d88a67f075a4ff366be6"
+      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.58-beta.2/dws-darwin-amd64.tar.gz"
+      sha256 "a1c1b3c58b48e04c0ae520062f9d6ab0dc961eddb635497bdb9b4345316e45f6"
     end
   end
 
   on_linux do
     if Hardware::CPU.arm?
-      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.56-beta.1/dws-linux-arm64.tar.gz"
-      sha256 "5f9ead9b939d2db31354797cc7b7431f27aaca41f171d256d4d4e9269cc66d51"
+      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.58-beta.2/dws-linux-arm64.tar.gz"
+      sha256 "7f35e3c4734f17b125a8c32f3c95e05d1410f683cf6956be857ee9349f8e4d36"
     else
-      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.56-beta.1/dws-linux-amd64.tar.gz"
-      sha256 "06b950676cefdd8e054c76af32cd9758c4c7786908d654281d9c65e7a3d575cf"
+      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.58-beta.2/dws-linux-amd64.tar.gz"
+      sha256 "37beb9e39790563cf0584ac23376f713bf2eb2c50cff4222965e831ac9adbb0e"
     end
   end
 
   resource "skills" do
-    url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.56-beta.1/dws-skills.zip"
-    sha256 "7448ccfc8e189b3d76b3e8f11f5dedc4f5a5b53380f9059e6af4c63a38e38f28"
+    url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.58-beta.2/dws-skills.zip"
+    sha256 "7e10fead4192059c98d596c5b1886f77fd550526de5cd18c425cdad6fd64cd3a"
   end
 
   def install

Formula/dingtalk-workspace-cli.rb

@@ -1,33 +1,33 @@
 class DingtalkWorkspaceCli < Formula
   desc "Automate DingTalk workspace tasks from the terminal"
   homepage "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli"
-  version "1.0.55"
+  version "1.0.57"
   license "Apache-2.0"
 
 
   on_macos do
     if Hardware::CPU.arm?
-      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.55/dws-darwin-arm64.tar.gz"
-      sha256 "dd753bbd051e5dd007cf433b8aa211c4a221dd73dfcb0b3783fa924d09f12351"
+      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.57/dws-darwin-arm64.tar.gz"
+      sha256 "c01c28dc13948a70fca905207073dc8dbd22f7ba7fc90e68b3316eb9a9c98e88"
     else
-      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.55/dws-darwin-amd64.tar.gz"
-      sha256 "f465eb7ac38a8a84eac4eb821fd15424bfc6f6245a60fa695ba97a639970dd77"
+      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.57/dws-darwin-amd64.tar.gz"
+      sha256 "d7baa218beefc851c6a933b456055195f8272984ce008d7e0122bdfc5dad94ea"
     end
   end
 
   on_linux do
     if Hardware::CPU.arm?
-      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.55/dws-linux-arm64.tar.gz"
-      sha256 "5961be0fd551ec8e69b6fff2b1609f73486f7e6c3ffe8eb4bb99fa1ed691b401"
+      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.57/dws-linux-arm64.tar.gz"
+      sha256 "0bbe9c233a3ff585077bae1ac5000937c32d967846d14cc44c46f98d49b95ae2"
     else
-      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.55/dws-linux-amd64.tar.gz"
-      sha256 "051ba404a5f6a8fb15def0e0f5d9d273cf9d63f881df2fffe159f2c4ea3366e7"
+      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.57/dws-linux-amd64.tar.gz"
+      sha256 "f113ce3654f21d1f9ecc7c196f815aeafbca54d377a347b244a15116c5cba698"
     end
   end
 
   resource "skills" do
-    url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.55/dws-skills.zip"
-    sha256 "bd35f674f184001f5a03c7b5fa6029ebcda54f0054e15cd608b5b5e213ce2d05"
+    url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.57/dws-skills.zip"
+    sha256 "0c9667209cf30761427a8f9348149cbbf1e397aa3c25587e99f205bc7525e101"
   end
 
   def install

Makefile

@@ -5,10 +5,12 @@ PUBLISH ?= 0
 YES ?= 0
 DWS_POLICY_TMPDIR ?= $(CURDIR)/.worktrees/policy-tmp
 POLICY_GOTMPDIR ?= $(DWS_POLICY_TMPDIR)/go
+SCHEMA_CATALOG_OUTPUT ?= artifacts/schema_catalog
+SCHEMA_META_INDEX_OUTPUT ?= artifacts/schema_meta_index.gob
 POLICY_ENV = DWS_POLICY_TMPDIR="$(DWS_POLICY_TMPDIR)" GOTMPDIR="$(POLICY_GOTMPDIR)"
 GO_SOURCE_LIST = git ls-files -z --cached --others --exclude-standard -- '*.go'
 
-.PHONY: all help build rebuild test test-plan test-auth-legacy-compat lint format-check fmt policy edition-test interface-integrity authoritative-interface-integrity coverage-gate coverage-gate-platform update-interface-baseline reset-interface-baseline schema-compatibility skill-command-integrity skill-context-budget cli-smoke mock-mcp-smoke test-schema-agent-examples generate-schema generate-schema-agent-metadata fetch-mcp-metadata generate-schema-catalog package release release-pre release-stable changelog-pre changelog-stable publish-homebrew-formula setup-hooks
+.PHONY: all help build rebuild test test-plan test-auth-legacy-compat lint format-check fmt policy edition-test interface-integrity authoritative-interface-integrity coverage-gate coverage-gate-platform update-interface-baseline reset-interface-baseline schema-compatibility skill-command-integrity skill-context-budget multi-im-skill-chain-integrity cli-smoke mock-mcp-smoke test-schema-agent-examples generate-schema fetch-mcp-metadata generate-schema-catalog package release release-pre release-stable changelog-pre changelog-stable publish-homebrew-formula setup-hooks
 
 all: setup-hooks fmt lint build test rebuild
 
@@ -22,21 +24,21 @@ help:
 	@printf "  make format-check  - Check all repository Go source files with gofmt\n"
 	@printf "  make fmt           - Format all repository Go source files\n"
 	@printf "  make policy        - Check the built dws plus open-source and Schema policies\n"
-	@printf "  make interface-integrity - Check historical commands and help contracts still work\n"
-	@printf "  make authoritative-interface-integrity BASE_REF=<ref> - Check the Git-owned PR merge-base\n"
+	@printf "  make interface-integrity [BASE_REF=<ref>] [STABLE_REF=<tag>] [CANDIDATE_REF=<ref>] - Check authoritative CLI history\n"
+	@printf "  make authoritative-interface-integrity BASE_REF=<ref> [STABLE_REF=<tag>] [CANDIDATE_REF=<ref>] - Check Git-owned CLI history\n"
 	@printf "  make coverage-gate BASE_REF=<ref> - Enforce overall non-regression and 100%% changed-code coverage\n"
 	@printf "  make coverage-gate-platform BASE_REF=<ref> PROFILE=<file> - Enforce 100%% native changed-code coverage\n"
-	@printf "  make update-interface-baseline - Add new CLI contracts without removing history\n"
-	@printf "  make reset-interface-baseline - DANGEROUS: replace all CLI compatibility history\n"
-	@printf "  make schema-compatibility BASE_REF=<ref> - Check the complete Schema contract against the PR merge-base\n"
+	@printf "  make update-interface-baseline - Update the non-authoritative CLI smoke fixture\n"
+	@printf "  make reset-interface-baseline - DANGEROUS: replace the non-authoritative CLI smoke fixture\n"
+	@printf "  make schema-compatibility BASE_REF=<ref> [STABLE_REF=<tag>] [CANDIDATE_REF=<ref>] - Check the authoritative Schema history\n"
 	@printf "  make skill-command-integrity - Check dws commands referenced by skills exist\n"
 	@printf "  make skill-context-budget - Check generated Skill drift and common-path context budgets\n"
+	@printf "  make multi-im-skill-chain-integrity - Check reviewed IM intents keep one default Skill route\n"
 	@printf "  make cli-smoke     - Verify help for every public top-level command\n"
 	@printf "  make mock-mcp-smoke - Verify HTTP and stdio MCP request/response transport\n"
 	@printf "  make test-schema-agent-examples - Contract-check all Agent examples and dry-run the eligible subset\n"
-	@printf "  make generate-schema - Regenerate embedded Agent metadata and the release Catalog\n"
-	@printf "  make generate-schema-agent-metadata - Regenerate versioned Agent metadata\n"
-	@printf "  make generate-schema-catalog - Regenerate the embedded release Catalog\n"
+	@printf "  make generate-schema - Refresh param_aliases + verify Schema assembly determinism\n"
+	@printf "  make generate-schema-catalog - Optional assembled Catalog dump under artifacts/ (not a delivery step)\n"
 	@printf "  make package       - Build all release artifacts locally\n"
 	@printf "  make changelog-pre VERSION=vX.Y.Z-beta.N - Prepare prerelease notes\n"
 	@printf "  make changelog-stable VERSION=vX.Y.Z FROM_BETA=vX.Y.Z-beta.N - Prepare stable notes\n"
@@ -86,7 +88,8 @@ policy: test-auth-legacy-compat
 	@mkdir -p "$(POLICY_GOTMPDIR)"
 	@$(POLICY_ENV) ./scripts/policy/check-open-source-assets.sh
 	@$(POLICY_ENV) ./scripts/policy/check-skill-context-budget.sh
-	@$(POLICY_ENV) ./scripts/policy/check-schema-command-registry.sh
+	@$(POLICY_ENV) ./scripts/policy/check-multi-im-skill-chain.sh
+	@python3 scripts/run_chat_shortcut_live_audit_test.py
 	@$(POLICY_ENV) ./scripts/policy/check-command-surface.sh --strict
 	@$(POLICY_ENV) ./scripts/policy/check-generated-drift.sh
 	@$(POLICY_ENV) ./scripts/policy/check-param-concepts.sh
@@ -100,10 +103,22 @@ edition-test:
 	$(GO) test -v -count=1 ./pkg/editiontest/...
 
 interface-integrity:
-	@./scripts/policy/check-interface-baseline.sh
+	@base_ref="$(BASE_REF)"; \
+	candidate_ref="$(CANDIDATE_REF)"; \
+	if [ -z "$$base_ref" ]; then base_ref="origin/main"; fi; \
+	if [ -z "$$candidate_ref" ]; then candidate_ref="HEAD"; fi; \
+	./scripts/policy/check-authoritative-interface-baselines.sh \
+		--base-ref "$$base_ref" \
+		--stable-ref "$(STABLE_REF)" \
+		--candidate-ref "$$candidate_ref"
 
 authoritative-interface-integrity:
-	@./scripts/policy/check-authoritative-interface-baselines.sh --base-ref "$(BASE_REF)"
+	@candidate_ref="$(CANDIDATE_REF)"; \
+	if [ -z "$$candidate_ref" ]; then candidate_ref="HEAD"; fi; \
+	./scripts/policy/check-authoritative-interface-baselines.sh \
+		--base-ref "$(BASE_REF)" \
+		--stable-ref "$(STABLE_REF)" \
+		--candidate-ref "$$candidate_ref"
 
 coverage-gate:
 	@./scripts/policy/check-coverage-gate.sh --base-ref "$(BASE_REF)" --scope-buildable
@@ -118,7 +133,12 @@ reset-interface-baseline:
 	@./scripts/policy/check-interface-baseline.sh --reset
 
 schema-compatibility:
-	@./scripts/policy/check-authoritative-schema-compatibility.sh --base-ref "$(BASE_REF)"
+	@candidate_ref="$(CANDIDATE_REF)"; \
+	if [ -z "$$candidate_ref" ]; then candidate_ref="HEAD"; fi; \
+	./scripts/policy/check-authoritative-schema-compatibility.sh \
+		--base-ref "$(BASE_REF)" \
+		--stable-ref "$(STABLE_REF)" \
+		--candidate-ref "$$candidate_ref"
 
 skill-command-integrity:
 	@./scripts/policy/check-skill-commands.sh
@@ -126,6 +146,12 @@ skill-command-integrity:
 skill-context-budget:
 	@./scripts/policy/check-skill-context-budget.sh
 
+multi-im-skill-chain-integrity:
+	@./scripts/policy/check-multi-im-skill-chain.sh
+
+skill-mono-multi-content:
+	@./scripts/policy/check-mono-multi-skill-content.sh
+
 cli-smoke:
 	@./scripts/policy/check-cli-smoke.sh
 
@@ -133,26 +159,30 @@ mock-mcp-smoke:
 	$(GO) test -v -count=1 -run '^(TestHTTPClientEndToEnd|TestStdioClientEndToEnd)$$' ./internal/transport
 
 test-schema-agent-examples:
-	DWS_AGENT_EXAMPLES_DRY_RUN=1 $(GO) test -v -count=1 ./internal/app -run '^TestManualAgentExamplesDryRun$$'
+	DWS_AGENT_EXAMPLES_DRY_RUN=1 $(GO) test -v -count=1 ./internal/app -run '^TestAgentExamplesDryRun$$'
 
+# generate-schema refreshes param_aliases_generated.go and verifies that
+# ResolveSchemaBuild assembly is deterministic. Catalog is runtime-assembled
+# (声明即 Catalog); cmd_schema_catalog is not a committed delivery step.
+# schema_agent_metadata/ and schema_hints/ must stay absent.
 generate-schema:
 	@set -e; \
-	registry_guard=$$(mktemp -d); \
 	concepts_guard=$$(mktemp); \
 	concepts_schema_guard=$$(mktemp); \
-	metadata_guard=$$(mktemp -d); \
-	selection_guard=$$(mktemp -d); \
-	trap 'rm -rf "$$registry_guard" "$$concepts_guard" "$$concepts_schema_guard" "$$metadata_guard" "$$selection_guard"' EXIT HUP INT TERM; \
-	cp -R internal/cli/schema_command_registry/ "$$registry_guard/"; \
+	command_fallbacks_guard=$$(mktemp); \
+	command_fallbacks_schema_guard=$$(mktemp); \
+	trap 'rm -f "$$concepts_guard" "$$concepts_schema_guard" "$$command_fallbacks_guard" "$$command_fallbacks_schema_guard"' EXIT HUP INT TERM; \
 	cp internal/cli/param_concepts.json "$$concepts_guard"; \
 	cp internal/cli/param_concepts.schema.json "$$concepts_schema_guard"; \
-	cp -R internal/cli/schema_hints/metadata/. "$$metadata_guard/"; \
-	cp -R internal/cli/schema_hints/selection/. "$$selection_guard/"; \
+	cp internal/cli/command_path_fallbacks.json "$$command_fallbacks_guard"; \
+	cp internal/cli/command_path_fallbacks.schema.json "$$command_fallbacks_schema_guard"; \
 	$(GO) generate ./internal/cli; \
-	diff -qr internal/cli/schema_command_registry "$$registry_guard" >/dev/null || { \
-		printf '%s\n' 'generation modified reviewed input internal/cli/schema_command_registry/' >&2; \
+	rm -rf internal/cli/schema_agent_metadata internal/cli/schema_agent_metadata_audit.json; \
+	rm -f internal/cli/schema_meta_index.json; \
+	if [ -e internal/cli/schema_command_registry ]; then \
+		printf '%s\n' 'retired schema_command_registry/ must not reappear after generation' >&2; \
 		exit 1; \
-	}; \
+	fi; \
 	cmp -s internal/cli/param_concepts.json "$$concepts_guard" || { \
 		printf '%s\n' 'generation modified reviewed input internal/cli/param_concepts.json' >&2; \
 		exit 1; \
@@ -161,37 +191,35 @@ generate-schema:
 		printf '%s\n' 'generation modified reviewed input internal/cli/param_concepts.schema.json' >&2; \
 		exit 1; \
 	}; \
-	cmp -s internal/cli/param_concepts.json "$$concepts_guard" || { \
-		printf '%s\n' 'generation modified reviewed input internal/cli/param_concepts.json' >&2; \
+	cmp -s internal/cli/command_path_fallbacks.json "$$command_fallbacks_guard" || { \
+		printf '%s\n' 'generation modified reviewed input internal/cli/command_path_fallbacks.json' >&2; \
 		exit 1; \
 	}; \
-	cmp -s internal/cli/param_concepts.schema.json "$$concepts_schema_guard" || { \
-		printf '%s\n' 'generation modified reviewed input internal/cli/param_concepts.schema.json' >&2; \
+	cmp -s internal/cli/command_path_fallbacks.schema.json "$$command_fallbacks_schema_guard" || { \
+		printf '%s\n' 'generation modified reviewed input internal/cli/command_path_fallbacks.schema.json' >&2; \
 		exit 1; \
 	}; \
-	diff -qr internal/cli/schema_hints/metadata "$$metadata_guard" >/dev/null || { \
-		printf '%s\n' 'generation modified reviewed input internal/cli/schema_hints/metadata' >&2; \
+	if [ -e internal/cli/schema_hints ]; then \
+		printf '%s\n' 'retired schema_hints/ must not reappear after generation' >&2; \
 		exit 1; \
-	}; \
-	diff -qr internal/cli/schema_hints/selection "$$selection_guard" >/dev/null || { \
-		printf '%s\n' 'generation modified reviewed input internal/cli/schema_hints/selection' >&2; \
+	fi; \
+	if [ -e internal/cli/schema_meta_index.json ]; then \
+		printf '%s\n' 'retired schema_meta_index.json must not remain after generation' >&2; \
 		exit 1; \
-	}
-
-generate-schema-agent-metadata:
-	$(GO) run ./internal/generator/cmd_schema_agent_metadata \
-		-root . \
-		-registry internal/cli/schema_command_registry \
-		-output-dir internal/cli/schema_agent_metadata \
-		-audit-output internal/cli/schema_agent_metadata_audit.json
+	fi; \
+	./scripts/policy/check-schema-assembly.sh
 
+# Optional local/CI dump of an assembled Catalog under artifacts/ by default.
+# Override SCHEMA_CATALOG_OUTPUT and SCHEMA_META_INDEX_OUTPUT as needed. This
+# is not a go:generate or production delivery step.
 generate-schema-catalog:
 	$(GO) run -a ./internal/generator/cmd_schema_catalog \
 		-root . \
-		-output internal/cli/schema_catalog
+		-output "$(SCHEMA_CATALOG_OUTPUT)" \
+		-meta-index "$(SCHEMA_META_INDEX_OUTPUT)"
 
 fetch-mcp-metadata:
-	@printf '  %sRefreshing MCP metadata from live server%s\n' "$(COLOR_RUN)" "$(COLOR_RESET)"
+	@printf '  %sFetching diagnostic MCP dump (not a Schema pin)%s\n' "$(COLOR_RUN)" "$(COLOR_RESET)"
 	@./scripts/dev/fetch_mcp_metadata.sh
 
 package:

README.md

@@ -71,9 +71,7 @@ The installer ships skills in one of two layouts. CLI commands (`dws aitable ...
 | Mode | What gets installed | Best for |
 |------|----------------------|----------|
 | **mono** (stable, default) | One `dws` skill covering all products | Cross-product workflows; single entry point |
-| **multi** 🧪 **EXPERIMENTAL** | Per-product skills (`dingtalk-aitable`, `dingtalk-calendar`, `dingtalk-chat`, ...) | Single-product tasks; smaller context per call |
-
-> 🧪 **`multi` is currently EXPERIMENTAL / preview.** All product-scoped skills pass the dispatch verifier, but interface, naming and cross-skill references may change in future releases. For production / shared environments, prefer `mono`. File issues if you hit problems.
+| **multi** | Per-product skills (`dingtalk-aitable`, `dingtalk-calendar`, `dingtalk-chat`, ...) | Single-product tasks; smaller context per call |
 
 How to pick:
 
@@ -371,7 +369,7 @@ dws contact user get-self --jq '.result[0].orgEmployeeModel | {name: .orgUserNam
 Use Cobra help and Schema for different parts of the command contract:
 
 - `dws <path> --help` is the source of truth for whether a command exists and which flags the binary accepts.
-- `dws schema "<path>"` is the Agent contract for command selection, parameter mappings and constraints, risk, and confirmation semantics.
+- `dws schema "<path>" --compact` is the normative Agent view for command selection, CLI parameters and constraints, risk, and confirmation; use a full leaf with a narrow `--jq` projection for mapping or provenance audits.
 - If Help and Schema disagree, treat it as contract drift: pass only flags accepted by Cobra and use the more conservative safety semantics.
 - Schema describes commands; it does not read or search DingTalk business data. Execute the real product command after discovery.
 
@@ -380,23 +378,23 @@ Use Cobra help and Schema for different parts of the command contract:
 dws aitable record query --help
 
 # Discover within a product, then inspect the selected leaf contract
-dws schema aitable
-dws schema "aitable record query"
+dws schema aitable --compact
+dws schema "aitable record query" --compact
 
 # Execute the real business query
 dws aitable record query --base-id BASE_ID --table-id TABLE_ID --limit 10
 ```
 
-`dws schema --all` exports the complete contract for tooling, CI, audits, and compatibility baselines. Agents should prefer product/group discovery followed by a leaf query to avoid loading the full Catalog into context.
+`dws schema --all` exports the complete contract for tooling, CI, audits, and compatibility baselines. Agents should query progressively with `--compact`; its positive field allowlist prevents new full/audit fields from silently expanding Agent context.
 
 ### Agent Skills
 
 The repo ships a complete Agent Skill system under `skills/`, organized into two layouts:
 
 - `skills/mono/` — single-skill layout (one `SKILL.md` + `references/products/`), recommended default.
-- `skills/multi/` — per-product skills (`dingtalk-aitable/`, `dingtalk-calendar/`, `dingtalk-chat/`, ...), each with its own `SKILL.md`. 🧪 **EXPERIMENTAL / preview — see banner in each multi `SKILL.md` for caveats.**
+- `skills/multi/` — per-product skills (`dingtalk-aitable/`, `dingtalk-calendar/`, `dingtalk-chat/`, ...), each with its own `SKILL.md`.
 
-Shared reviewed inputs for Schema generation live separately under `internal/cli/schema_hints/`. They are not Agent Skills and are excluded from binaries and release skill bundles.
+Leaf safety/parameters/selection prose for Schema generation come from ProductDecl / ContractFinal declarations in Go. The former `internal/cli/schema_hints/` HintFile tree is fully retired and must not reappear.
 
 After installing, AI tools like Claude Code / Cursor can operate DingTalk directly through natural language:
 
@@ -443,7 +441,6 @@ Env vars: `DWS_SKILL_MODE=mono|multi` (also honored by `install.sh` / `install.p
 | Intent guide | `skills/mono/references/intent-guide.md` | Disambiguation for confusing scenarios (e.g. report vs todo) |
 | Global reference | `skills/mono/references/global-reference.md` | Auth, output formats, global flags |
 | Error codes | `skills/mono/references/error-codes.md` | Error codes + debugging workflows |
-| Recovery guide | `skills/mono/references/recovery-guide.md` | `RECOVERY_EVENT_ID` handling |
 | Ready-made scripts | `skills/mono/scripts/*.py` | 13 batch operation scripts (see below) |
 
 <details>
@@ -539,7 +536,7 @@ For one-to-one and specified-sender events, use exactly one target identity: `--
 | Observability | `status` shows remote subscriptions, the personal bus, and local consumers |
 | Cross-platform | Unix Socket on macOS/Linux, Windows Named Pipe on Windows |
 
-See `skills/multi/dingtalk-event/SKILL.md` for the Agent workflow and supported event parameters.
+See `skills/multi/dingtalk-misc/references/event.md` for the Agent workflow and supported event parameters.
 
 </details>
 
@@ -624,7 +621,7 @@ dws aitable record query --base-id BASE_ID --tabel-id TABLE_ID       # --tabel-i
 ```bash
 # Built-in jq expressions
 dws aitable record query --base-id BASE_ID --table-id TABLE_ID --jq '.invocation.params'
-dws schema "dev app create" --jq '.tool.required'
+dws schema "dev app create" --jq '.parameters'
 
 # Return only specific fields
 dws aitable record query --base-id BASE_ID --table-id TABLE_ID --fields invocation,response
@@ -636,9 +633,9 @@ dws aitable record query --base-id BASE_ID --table-id TABLE_ID --fields invocati
 <summary><strong>Schema Introspection</strong> — Agent command discovery and execution contracts</summary>
 
 ```bash
-dws schema aitable                                      # discover product commands
-dws schema "aitable record query"                       # view the selected leaf contract
-dws schema "aitable record query" --jq '.tool.required' # view required fields
+dws schema aitable --compact                            # discover product commands
+dws schema "aitable record query" --compact             # view the selected Agent leaf contract
+dws schema "aitable record query" --jq '[.parameters | to_entries[] | select(.value.required)]' # view required fields
 dws schema --all                                        # full export for CI/audit/baselines
 ```
 

README_zh.md

@@ -71,9 +71,7 @@ irm https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-workspace-cli/ma
 | 模式 | 安装内容 | 适合场景 |
 |------|----------|----------|
 | **mono**（稳定，默认） | 一个 `dws` skill，覆盖全部产品 | 跨产品组合操作；单一入口召唤 |
-| **multi** 🧪 **试验版 / Preview** | 按产品拆分的独立 skill（`dingtalk-aitable` / `dingtalk-calendar` / `dingtalk-chat` ...） | 单产品任务；每次召唤上下文更小 |
-
-> 🧪 **multi 模式当前为 EXPERIMENTAL（试验版 / Preview）**。全部独立 skill 均通过 dispatch verifier，但接口、命名、跨 skill 引用后续可能调整。生产 / 共享环境建议优先用 `mono`。问题请提 issue 反馈。
+| **multi** | 按产品拆分的独立 skill（`dingtalk-aitable` / `dingtalk-calendar` / `dingtalk-chat` ...） | 单产品任务；每次召唤上下文更小 |
 
 怎么选：
 
@@ -365,7 +363,7 @@ dws contact user get-self --jq '.result[0].orgEmployeeModel | {name: .orgUserNam
 命令帮助和 Schema 分别负责命令契约的不同部分：
 
 - `dws <path> --help` 是命令是否存在、当前二进制接受哪些 flags 的事实源。
-- `dws schema "<path>"` 是 Agent 选命令、参数映射与约束、风险和确认语义的契约。
+- `dws schema "<path>" --compact` 是 Agent 选命令、CLI 参数与约束、风险和确认语义的规范视图；映射或 provenance 审计使用 full leaf 配合 `--jq` 精确投影。
 - Help 与 Schema 冲突时视为契约漂移：执行只传 Cobra 接受的参数，安全语义取更保守值。
 - Schema 只描述命令，不读取或搜索钉钉业务数据；发现命令后仍需执行真实产品命令。
 
@@ -374,23 +372,23 @@ dws contact user get-self --jq '.result[0].orgEmployeeModel | {name: .orgUserNam
 dws aitable record query --help
 
 # 先在产品内发现命令，再查看选中 leaf 的契约
-dws schema aitable
-dws schema "aitable record query"
+dws schema aitable --compact
+dws schema "aitable record query" --compact
 
 # 执行真实业务查询
 dws aitable record query --base-id BASE_ID --table-id TABLE_ID --limit 10
 ```
 
-`dws schema --all` 会完整导出命令契约，供工具、CI、审计和兼容性基线使用。Agent 应优先按产品/分组发现后查询 leaf，避免把整个 Catalog 加载进上下文。
+`dws schema --all` 会完整导出命令契约，供工具、CI、审计和兼容性基线使用。Agent 应使用 `--compact` 渐进查询；该视图采用正向字段白名单，full 新增的审计字段不会自动进入 Agent 上下文。
 
 ### Agent Skills
 
 仓库内置完整的 Agent Skill 体系（`skills/` 目录），分为两套布局：
 
 - `skills/mono/` — 单 skill 布局（一个 `SKILL.md` + `references/products/`），默认推荐。
-- `skills/multi/` — 每个产品一个独立 skill（`dingtalk-aitable/` / `dingtalk-calendar/` / `dingtalk-chat/` ...），每个 skill 自带 `SKILL.md`。🧪 **试验版 / Preview — 各 multi `SKILL.md` 头部有详细注意事项。**
+- `skills/multi/` — 每个产品一个独立 skill（`dingtalk-aitable/` / `dingtalk-calendar/` / `dingtalk-chat/` ...），每个 skill 自带 `SKILL.md`。
 
-Schema 生成共享的 reviewed 输入单独位于 `internal/cli/schema_hints/`。它们不是 Agent Skill，也不会进入二进制或发布 skill 包。
+Schema 生成的叶子 safety/参数/选型文案由 Go 中的 ProductDecl / ContractFinal 声明驱动。原 `internal/cli/schema_hints/` HintFile 目录已完全退役，不得重新引入。
 
 安装之后，Claude Code / Cursor 等 AI 工具就能通过自然语言直接操作钉钉：
 
@@ -437,7 +435,6 @@ DWS_SKILL_SOURCE=/path/to/skills dws skill setup --mode multi
 | 意图指南 | `skills/mono/references/intent-guide.md` | 易混淆场景消歧（如 report vs todo） |
 | 全局参考 | `skills/mono/references/global-reference.md` | 认证、输出格式、全局 flag |
 | 错误码 | `skills/mono/references/error-codes.md` | 错误码 + 调试流程 |
-| Recovery 指南 | `skills/mono/references/recovery-guide.md` | `RECOVERY_EVENT_ID` 处理 |
 | 现成脚本 | `skills/mono/scripts/*.py` | 13 个批量操作脚本（见下方） |
 
 <details>
@@ -533,7 +530,7 @@ dws event stop <subscribe_id>
 | 状态可观测 | `status` 同时显示服务端订阅、personal bus 和本地 consumers |
 | 跨平台 | macOS/Linux 使用 Unix Socket，Windows 使用 Named Pipe |
 
-Agent 工作流和事件参数详见 `skills/multi/dingtalk-event/SKILL.md`。
+Agent 工作流和事件参数详见 `skills/multi/dingtalk-misc/references/event.md`。
 
 </details>
 
@@ -618,7 +615,7 @@ dws aitable record query --base-id BASE_ID --tabel-id TABLE_ID       # --tabel-i
 ```bash
 # 内置 jq 表达式
 dws aitable record query --base-id BASE_ID --table-id TABLE_ID --jq '.invocation.params'
-dws schema "dev app create" --jq '.tool.required'
+dws schema "dev app create" --jq '.parameters'
 
 # 只返回指定字段
 dws aitable record query --base-id BASE_ID --table-id TABLE_ID --fields invocation,response
@@ -630,9 +627,9 @@ dws aitable record query --base-id BASE_ID --table-id TABLE_ID --fields invocati
 <summary><strong>Schema 自省</strong> — Agent 命令发现与执行契约</summary>
 
 ```bash
-dws schema aitable                                      # 发现产品命令
-dws schema "aitable record query"                       # 查看选中 leaf 契约
-dws schema "aitable record query" --jq '.tool.required' # 查看必填字段
+dws schema aitable --compact                            # 发现产品命令
+dws schema "aitable record query" --compact             # 查看 Agent leaf 契约
+dws schema "aitable record query" --jq '[.parameters | to_entries[] | select(.value.required)]' # 定向查看必填字段
 dws schema --all                                        # CI/审计/基线的全量导出
 ```
 

cmd/fetch_mcp_metadata/main.go

@@ -1,15 +1,16 @@
 // Command fetch_mcp_metadata pulls tools/list from ALL live MCP server endpoints
-// and writes a refreshed schema_mcp_metadata.json. This is DWS's equivalent of
-// lark-cli's scripts/fetch_meta.py.
+// and writes a local diagnostic dump. It is NOT a Schema delivery refresh:
+// schema_mcp_metadata.json is retired; production Catalog assembles from
+// Contract/ParamDecl/Interface + Cobra only.
 //
 // Usage:
 //
 //	dws auth login                     # ensure valid auth
-//	make fetch-mcp-metadata             # runs this tool
+//	make fetch-mcp-metadata             # writes artifacts/mcp_metadata_diagnostic.json
 //
-// The tool loads auth from the DWS keychain, iterates all 26 static server
-// endpoints (internal/syncdata.StaticServers), calls tools/list on each,
-// merges results, and writes schema_mcp_metadata.json.
+// The tool loads auth from the DWS keychain, iterates static server endpoints
+// (internal/syncdata.StaticServers), calls tools/list on each, merges results,
+// and writes the requested -output path (refuses the retired pin path).
 package main
 
 import (
@@ -24,6 +25,7 @@ import (
 	"strings"
 	"time"
 
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/app"
 	"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/syncdata"
@@ -38,14 +40,15 @@ type toolLister interface {
 
 // Injection points so run() is fully testable without network/keychain/exit.
 var (
-	osExit           = os.Exit
-	getenv           = os.Getenv
-	loadTokenData    = auth.LoadTokenDataKeychain
-	staticServers    = syncdata.StaticServers
-	registrySource   = cli.EmbeddedCommandRegistryMergedJSON
-	listToolsTimeout = 30 * time.Second
-	gitHeadPath      = ".git/HEAD"
-	newToolLister    = func(token string) toolLister {
+	osExit               = os.Exit
+	getenv               = os.Getenv
+	loadTokenData        = auth.LoadTokenDataKeychain
+	staticServers        = syncdata.StaticServers
+	registrySource       = collectedIdentityInterfaceRefs
+	collectIdentitySpecs = cli.CollectIdentitySpecs
+	listToolsTimeout     = 30 * time.Second
+	gitHeadPath          = ".git/HEAD"
+	newToolLister        = func(token string) toolLister {
 		return transport.NewClient(&http.Client{Timeout: 60 * time.Second}).WithAuth(token, nil)
 	}
 )
@@ -57,10 +60,14 @@ func main() {
 func run(args []string, stderr io.Writer) int {
 	flags := flag.NewFlagSet("fetch_mcp_metadata", flag.ContinueOnError)
 	flags.SetOutput(stderr)
-	output := flags.String("output", "internal/cli/schema_mcp_metadata.json", "output file path")
+	output := flags.String("output", "artifacts/mcp_metadata_diagnostic.json", "diagnostic dump path (not a Schema pin)")
 	if err := flags.Parse(args); err != nil {
 		return 2
 	}
+	if retiredPinnedMCPMetadataPath(*output) {
+		fmt.Fprintln(stderr, "fetch_mcp_metadata: refusing to write retired Schema pin internal/cli/schema_mcp_metadata.json")
+		return 2
+	}
 
 	token := resolveToken(stderr)
 	if token == "" {
@@ -74,11 +81,11 @@ func run(args []string, stderr io.Writer) int {
 	servers := staticServers()
 	fmt.Fprintf(stderr, "fetch_mcp_metadata: querying %d server endpoints\n", len(servers))
 
-	// Load CLI registry to build tool_name → interface_ref mapping.
+	// Collect command identity to build tool_name → interface_ref mapping.
 	registryMap := loadRegistryInterfaceRefs(stderr)
 	fmt.Fprintf(stderr, "fetch_mcp_metadata: registry mapping: %d entries\n", len(registryMap))
 
-	// Load the previous schema_mcp_metadata.json to preserve hand-curated
+	// Load a previous diagnostic dump (if any) to preserve hand-curated
 	// cross-server interface_ref mappings that automated matching can't derive.
 	prevData, prevErr := os.ReadFile(*output)
 	prevTools := map[string]map[string]any{}
@@ -310,48 +317,51 @@ func buildCrossServerRefs(prevTools map[string]map[string]any, registryMap map[s
 	return index
 }
 
-// loadRegistryInterfaceRefs loads the reviewed split CommandRegistry through
-// the cli package's reassembly API and builds a canonical_path →
-// {product_id, rpc_name} mapping for interface_ref injection.
-func loadRegistryInterfaceRefs(stderr io.Writer) map[string]map[string]string {
-	data, err := registrySource()
+// collectedIdentityInterfaceRefs collects command identity from the live
+// command tree — the replacement for the retired reviewed CommandRegistry —
+// and derives the canonical_path → {product_id, rpc_name} mapping used for
+// interface_ref injection.
+func collectedIdentityInterfaceRefs() (map[string]map[string]string, error) {
+	root := app.NewSchemaSourceRootCommand()
+	specs, _, err := collectIdentitySpecs(root)
 	if err != nil {
-		fmt.Fprintf(stderr, "fetch_mcp_metadata: warning: cannot load registry: %v\n", err)
-		return map[string]map[string]string{}
+		return nil, fmt.Errorf("collect command identity: %w", err)
 	}
-	var reg struct {
-		Products []struct {
-			ID    string `json:"id"`
-			Tools []struct {
-				CanonicalPath string `json:"canonical_path"`
-			} `json:"tools"`
-		} `json:"products"`
-	}
-	if err := json.Unmarshal(data, &reg); err != nil {
-		// 与读文件失败同等告警：静默返回空映射会让所有 live tool 被丢弃、
-		// 产出 stub-only 快照且零提示（P1#1 的故障模式）。
-		fmt.Fprintf(stderr, "fetch_mcp_metadata: warning: cannot parse registry: %v\n", err)
-		return map[string]map[string]string{}
-	}
-	out := make(map[string]map[string]string)
-	for _, prod := range reg.Products {
-		for _, tool := range prod.Tools {
-			cp := strings.TrimSpace(tool.CanonicalPath)
-			if cp == "" || !strings.Contains(cp, ".") {
-				continue
-			}
-			parts := strings.SplitN(cp, ".", 2)
-			out[cp] = map[string]string{
-				"product_id": parts[0],
-				"rpc_name":   parts[1],
-			}
+	out := make(map[string]map[string]string, len(specs))
+	for _, spec := range specs {
+		cp := strings.TrimSpace(spec.CanonicalPath)
+		if cp == "" || !strings.Contains(cp, ".") {
+			continue
+		}
+		parts := strings.SplitN(cp, ".", 2)
+		out[cp] = map[string]string{
+			"product_id": parts[0],
+			"rpc_name":   parts[1],
 		}
 	}
-	return out
+	return out, nil
+}
+
+// loadRegistryInterfaceRefs builds the canonical_path → interface_ref mapping
+// from the collected command identity. 与旧实现同等告警：静默返回空映射会让
+// 所有 live tool 被丢弃、产出 stub-only 快照且零提示（P1#1 的故障模式）。
+func loadRegistryInterfaceRefs(stderr io.Writer) map[string]map[string]string {
+	refs, err := registrySource()
+	if err != nil {
+		fmt.Fprintf(stderr, "fetch_mcp_metadata: warning: cannot collect command identity: %v\n", err)
+		return map[string]map[string]string{}
+	}
+	return refs
+}
+
+func retiredPinnedMCPMetadataPath(path string) bool {
+	cleaned := strings.ReplaceAll(strings.TrimSpace(path), "\\", "/")
+	return cleaned == "internal/cli/schema_mcp_metadata.json" ||
+		strings.HasSuffix(cleaned, "/internal/cli/schema_mcp_metadata.json")
 }
 
 // extractParams converts a JSON Schema inputSchema (from MCP tools/list) into
-// the flat param-name → metadata map used by schema_mcp_metadata.json.
+// the flat param-name → metadata map used by diagnostic dumps.
 func extractParams(inputSchema map[string]any) map[string]map[string]any {
 	if inputSchema == nil {
 		return nil

cmd/fetch_mcp_metadata/main_test.go

@@ -16,24 +16,66 @@ import (
 	"testing"
 
 	"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/syncdata"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/transport"
+	"github.com/spf13/cobra"
 )
 
-func TestLoadRegistryInterfaceRefsUsesSplitRegistry(t *testing.T) {
+func TestCrossPlatformCoverageLoadRegistryInterfaceRefsCollectsIdentity(t *testing.T) {
 	var stderr bytes.Buffer
 	refs := loadRegistryInterfaceRefs(&stderr)
 	if len(refs) == 0 {
-		t.Fatal("loadRegistryInterfaceRefs() returned no reviewed commands")
+		t.Fatal("loadRegistryInterfaceRefs() returned no collected commands")
 	}
 
 	got, ok := refs["calendar.list_calendars"]
 	if !ok {
-		t.Fatal("calendar.list_calendars missing from reassembled split registry")
+		t.Fatal("calendar.list_calendars missing from collected command identity")
 	}
 	if got["product_id"] != "calendar" || got["rpc_name"] != "list_calendars" {
 		t.Fatalf("calendar.list_calendars ref = %#v", got)
 	}
+
+	direct, err := collectedIdentityInterfaceRefs()
+	if err != nil {
+		t.Fatalf("collectedIdentityInterfaceRefs() error = %v", err)
+	}
+	if len(direct) == 0 || direct["calendar.list_calendars"]["rpc_name"] != "list_calendars" {
+		t.Fatalf("collectedIdentityInterfaceRefs() = %#v", direct["calendar.list_calendars"])
+	}
+
+	prevRegistry := registrySource
+	prevCollect := collectIdentitySpecs
+	t.Cleanup(func() {
+		registrySource = prevRegistry
+		collectIdentitySpecs = prevCollect
+	})
+	registrySource = func() (map[string]map[string]string, error) {
+		return nil, errors.New("collect boom")
+	}
+	stderr.Reset()
+	if got := loadRegistryInterfaceRefs(&stderr); len(got) != 0 || !strings.Contains(stderr.String(), "cannot collect command identity") {
+		t.Fatalf("loadRegistryInterfaceRefs error path = %#v stderr=%q", got, stderr.String())
+	}
+
+	collectIdentitySpecs = func(*cobra.Command) ([]cli.CommandSpec, cli.IdentityCollectionReport, error) {
+		return nil, cli.IdentityCollectionReport{}, errors.New("walk boom")
+	}
+	if _, err := collectedIdentityInterfaceRefs(); err == nil || !strings.Contains(err.Error(), "collect command identity") {
+		t.Fatalf("collectedIdentityInterfaceRefs wrap error = %v", err)
+	}
+	collectIdentitySpecs = func(*cobra.Command) ([]cli.CommandSpec, cli.IdentityCollectionReport, error) {
+		return []cli.CommandSpec{
+			{CanonicalPath: ""},
+			{CanonicalPath: "nodot"},
+			{CanonicalPath: "doc.create"},
+		}, cli.IdentityCollectionReport{}, nil
+	}
+	gotRefs, err := collectedIdentityInterfaceRefs()
+	if err != nil || len(gotRefs) != 1 || gotRefs["doc.create"]["rpc_name"] != "create" {
+		t.Fatalf("collectedIdentityInterfaceRefs skip = %#v err=%v", gotRefs, err)
+	}
 }
 
 func TestBuildCrossServerRefs(t *testing.T) {
@@ -91,8 +133,11 @@ func TestBuildCrossServerRefsSkipsMalformedRefs(t *testing.T) {
 }
 
 func TestRunRefreshesCrossServerTools(t *testing.T) {
-	registry := func() ([]byte, error) {
-		return []byte(`{"version":1,"products":[{"id":"aitable","tools":[{"canonical_path":"aitable.advperm_enable"},{"canonical_path":"aitable.advperm_disable"}]}]}`), nil
+	registry := func() (map[string]map[string]string, error) {
+		return map[string]map[string]string{
+			"aitable.advperm_enable":  {"product_id": "aitable", "rpc_name": "advperm_enable"},
+			"aitable.advperm_disable": {"product_id": "aitable", "rpc_name": "advperm_disable"},
+		}, nil
 	}
 	servers := []syncdata.ServerInfo{{ID: "aitable-helper", Endpoint: "https://helper.example"}}
 	lister := &fakeLister{
@@ -147,8 +192,10 @@ func TestRunRefreshesCrossServerTools(t *testing.T) {
 // 跨 server 身份时，另一 server 上恰好同名的工具不得直连覆盖其元数据——
 // 数据源只能是评审身份指向的 live 工具。
 func TestRunCrossOwnedCanonicalIgnoresNameCoincidence(t *testing.T) {
-	registry := func() ([]byte, error) {
-		return []byte(`{"version":1,"products":[{"id":"aitable","tools":[{"canonical_path":"aitable.advperm_enable"}]}]}`), nil
+	registry := func() (map[string]map[string]string, error) {
+		return map[string]map[string]string{
+			"aitable.advperm_enable": {"product_id": "aitable", "rpc_name": "advperm_enable"},
+		}, nil
 	}
 	servers := []syncdata.ServerInfo{
 		{ID: "aitable", Endpoint: "https://aitable.example"},
@@ -298,7 +345,7 @@ func (f *fakeLister) ListTools(_ context.Context, endpoint string) (transport.To
 }
 
 // stubDeps swaps every injection point for the duration of one test.
-func stubDeps(t *testing.T, token string, keychain func() (*auth.TokenData, error), servers []syncdata.ServerInfo, lister toolLister, registry func() ([]byte, error)) {
+func stubDeps(t *testing.T, token string, keychain func() (*auth.TokenData, error), servers []syncdata.ServerInfo, lister toolLister, registry func() (map[string]map[string]string, error)) {
 	t.Helper()
 	origGetenv, origLoad, origServers, origNew, origRegistry := getenv, loadTokenData, staticServers, newToolLister, registrySource
 	t.Cleanup(func() {
@@ -316,12 +363,32 @@ func stubDeps(t *testing.T, token string, keychain func() (*auth.TokenData, erro
 	registrySource = registry
 }
 
-func testRegistryJSON() ([]byte, error) {
-	return []byte(`{"version":1,"products":[{"id":"doc","tools":[{"canonical_path":"doc.copy_document"},{"canonical_path":"doc.get_document"},{"canonical_path":"bad-entry"}]}]}`), nil
+func testRegistryRefs() (map[string]map[string]string, error) {
+	return map[string]map[string]string{
+		"doc.copy_document": {"product_id": "doc", "rpc_name": "copy_document"},
+		"doc.get_document":  {"product_id": "doc", "rpc_name": "get_document"},
+	}, nil
+}
+
+func TestCrossPlatformCoverageRunRefusesRetiredPinnedMCPMetadataPath(t *testing.T) {
+	stubDeps(t, "env-token", nil, nil, &fakeLister{}, testRegistryRefs)
+	var stderr bytes.Buffer
+	code := run([]string{"--output", "internal/cli/schema_mcp_metadata.json"}, &stderr)
+	if code != 2 {
+		t.Fatalf("run(retired pin) = %d, want 2", code)
+	}
+	if !strings.Contains(stderr.String(), "refusing to write retired Schema pin") {
+		t.Fatalf("stderr = %q, want retired-pin refusal", stderr.String())
+	}
+	if !retiredPinnedMCPMetadataPath("internal/cli/schema_mcp_metadata.json") ||
+		!retiredPinnedMCPMetadataPath("/tmp/repo/internal/cli/schema_mcp_metadata.json") ||
+		retiredPinnedMCPMetadataPath("artifacts/mcp_metadata_diagnostic.json") {
+		t.Fatal("retiredPinnedMCPMetadataPath classification is incorrect")
+	}
 }
 
 func TestRunNoTokenFails(t *testing.T) {
-	stubDeps(t, "", func() (*auth.TokenData, error) { return nil, errors.New("no keychain") }, nil, &fakeLister{}, testRegistryJSON)
+	stubDeps(t, "", func() (*auth.TokenData, error) { return nil, errors.New("no keychain") }, nil, &fakeLister{}, testRegistryRefs)
 	var stderr bytes.Buffer
 	if code := run(nil, &stderr); code != 1 {
 		t.Fatalf("run() = %d, want 1", code)
@@ -332,7 +399,7 @@ func TestRunNoTokenFails(t *testing.T) {
 }
 
 func TestRunInvalidFlagFails(t *testing.T) {
-	stubDeps(t, "tok", nil, nil, &fakeLister{}, testRegistryJSON)
+	stubDeps(t, "tok", nil, nil, &fakeLister{}, testRegistryRefs)
 	var stderr bytes.Buffer
 	if code := run([]string{"--nonexistent"}, &stderr); code != 2 {
 		t.Fatalf("run() = %d, want 2", code)
@@ -342,7 +409,7 @@ func TestRunInvalidFlagFails(t *testing.T) {
 func TestResolveTokenKeychainFallback(t *testing.T) {
 	stubDeps(t, "", func() (*auth.TokenData, error) {
 		return &auth.TokenData{AccessToken: "kc-token"}, nil
-	}, nil, &fakeLister{}, testRegistryJSON)
+	}, nil, &fakeLister{}, testRegistryRefs)
 	var stderr bytes.Buffer
 	if got := resolveToken(&stderr); got != "kc-token" {
 		t.Fatalf("resolveToken() = %q, want kc-token", got)
@@ -353,14 +420,14 @@ func TestResolveTokenKeychainFallback(t *testing.T) {
 }
 
 func TestResolveTokenEmptyKeychainToken(t *testing.T) {
-	stubDeps(t, "", func() (*auth.TokenData, error) { return &auth.TokenData{}, nil }, nil, &fakeLister{}, testRegistryJSON)
+	stubDeps(t, "", func() (*auth.TokenData, error) { return &auth.TokenData{}, nil }, nil, &fakeLister{}, testRegistryRefs)
 	var stderr bytes.Buffer
 	if got := resolveToken(&stderr); got != "" {
 		t.Fatalf("resolveToken() = %q, want empty", got)
 	}
 }
 
-func TestRunWritesSnapshotWithHonestCoverage(t *testing.T) {
+func TestCrossPlatformCoverageRunWritesSnapshotWithHonestCoverage(t *testing.T) {
 	servers := []syncdata.ServerInfo{
 		{ID: "doc", Endpoint: "https://doc.example"},
 		{ID: "sheet", Endpoint: "https://sheet.example"},
@@ -383,7 +450,7 @@ func TestRunWritesSnapshotWithHonestCoverage(t *testing.T) {
 		},
 		errs: map[string]error{"https://sheet.example": errors.New("boom")},
 	}
-	stubDeps(t, "env-token", nil, servers, lister, testRegistryJSON)
+	stubDeps(t, "env-token", nil, servers, lister, testRegistryRefs)
 
 	dir := t.TempDir()
 	output := filepath.Join(dir, "snapshot.json")
@@ -446,7 +513,7 @@ func TestRunWritesSnapshotWithHonestCoverage(t *testing.T) {
 }
 
 func TestRunIgnoresCorruptPreviousSnapshot(t *testing.T) {
-	stubDeps(t, "env-token", nil, nil, &fakeLister{}, testRegistryJSON)
+	stubDeps(t, "env-token", nil, nil, &fakeLister{}, testRegistryRefs)
 	output := filepath.Join(t.TempDir(), "snapshot.json")
 	if err := os.WriteFile(output, []byte("{corrupt"), 0o600); err != nil {
 		t.Fatal(err)
@@ -457,32 +524,20 @@ func TestRunIgnoresCorruptPreviousSnapshot(t *testing.T) {
 	}
 }
 
-func TestRunRegistryLoadFailureStillWritesStublessSnapshot(t *testing.T) {
-	stubDeps(t, "env-token", nil, nil, &fakeLister{}, func() ([]byte, error) { return nil, errors.New("no registry") })
+func TestCrossPlatformCoverageRunRegistryLoadFailureStillWritesStublessSnapshot(t *testing.T) {
+	stubDeps(t, "env-token", nil, nil, &fakeLister{}, func() (map[string]map[string]string, error) { return nil, errors.New("no identity") })
 	output := filepath.Join(t.TempDir(), "snapshot.json")
 	var stderr bytes.Buffer
 	if code := run([]string{"--output", output}, &stderr); code != 0 {
 		t.Fatalf("run() = %d, stderr=%s", code, stderr.String())
 	}
-	if !strings.Contains(stderr.String(), "cannot load registry") {
-		t.Fatalf("stderr = %q, want registry warning", stderr.String())
-	}
-}
-
-func TestRunUnparsableRegistryYieldsNoRefs(t *testing.T) {
-	var stderr bytes.Buffer
-	stubDeps(t, "env-token", nil, nil, &fakeLister{}, func() ([]byte, error) { return []byte("{bad"), nil })
-	if refs := loadRegistryInterfaceRefs(&stderr); len(refs) != 0 {
-		t.Fatalf("refs = %v, want empty for unparsable registry", refs)
-	}
-	// 解析失败必须有告警，不得静默产出空映射。
-	if !strings.Contains(stderr.String(), "cannot parse registry") {
-		t.Fatalf("stderr = %q, want parse warning", stderr.String())
+	if !strings.Contains(stderr.String(), "cannot collect command identity") {
+		t.Fatalf("stderr = %q, want identity collection warning", stderr.String())
 	}
 }
 
 func TestRunWriteFailure(t *testing.T) {
-	stubDeps(t, "env-token", nil, nil, &fakeLister{}, testRegistryJSON)
+	stubDeps(t, "env-token", nil, nil, &fakeLister{}, testRegistryRefs)
 	var stderr bytes.Buffer
 	badPath := filepath.Join(t.TempDir(), "missing-dir", "snapshot.json")
 	if code := run([]string{"--output", badPath}, &stderr); code != 1 {
@@ -498,7 +553,7 @@ func TestWriteMetadataMarshalFailure(t *testing.T) {
 }
 
 func TestMainDelegatesToRun(t *testing.T) {
-	stubDeps(t, "env-token", nil, nil, &fakeLister{}, testRegistryJSON)
+	stubDeps(t, "env-token", nil, nil, &fakeLister{}, testRegistryRefs)
 	origExit, origArgs := osExit, os.Args
 	t.Cleanup(func() { osExit, os.Args = origExit, origArgs })
 	exitCode := -1
@@ -519,14 +574,14 @@ func TestExtractParamsNilAndNonObjectSchemas(t *testing.T) {
 	}
 }
 
-func TestNewToolListerBuildsAuthedClient(t *testing.T) {
+func TestCrossPlatformCoverageNewToolListerBuildsAuthedClient(t *testing.T) {
 	if lister := newToolLister("tok"); lister == nil {
 		t.Fatal("newToolLister returned nil")
 	}
 }
 
 func TestRunRecordsSourceRevision(t *testing.T) {
-	stubDeps(t, "env-token", nil, nil, &fakeLister{}, testRegistryJSON)
+	stubDeps(t, "env-token", nil, nil, &fakeLister{}, testRegistryRefs)
 	dir := t.TempDir()
 	head := filepath.Join(dir, "HEAD")
 	if err := os.WriteFile(head, []byte("ref: refs/heads/feature\n"), 0o600); err != nil {

cmd/interface-snapshot/main.go

@@ -17,18 +17,23 @@
 package main
 
 import (
+	"bytes"
 	"encoding/json"
 	"flag"
 	"fmt"
 	"io"
 	"os"
 	"path/filepath"
+	"strings"
 
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/app"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/i18n"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/interfacesnapshot"
+	"github.com/spf13/cobra"
 )
 
+var newRootCommand = func() *cobra.Command { return app.NewRootCommand() }
+
 func main() {
 	os.Exit(run(os.Args[1:], os.Stdout, os.Stderr))
 }
@@ -112,7 +117,11 @@ func runGenerate(args []string, stdout, stderr io.Writer) error {
 	defer i18n.SetLang(previousLang)
 	i18n.SetLang("en")
 
-	snapshot := interfacesnapshot.Capture(app.NewRootCommand())
+	root := newRootCommand()
+	snapshot := interfacesnapshot.Capture(root)
+	if err := validateHelpRendering(root, snapshot); err != nil {
+		return err
+	}
 	if *output == "-" {
 		return interfacesnapshot.Write(stdout, snapshot)
 	}
@@ -138,6 +147,16 @@ func runCompare(args []string, stdout, stderr io.Writer) (bool, error) {
 	currentPath := flags.String("current", "", "candidate snapshot path")
 	basePath := flags.String("base", "", "target main/development baseline snapshot path")
 	stablePath := flags.String("stable", "", "latest stable GA snapshot path")
+	approvedMigrationsPath := flags.String(
+		"approved-flag-migrations",
+		"",
+		"merge-base-owned approved flag migration manifest",
+	)
+	candidateMigrationsPath := flags.String(
+		"candidate-flag-migrations",
+		"",
+		"candidate flag migration manifest",
+	)
 	if err := flags.Parse(args); err != nil {
 		return false, err
 	}
@@ -150,6 +169,14 @@ func runCompare(args []string, stdout, stderr io.Writer) (bool, error) {
 	if *basePath == "" && *stablePath == "" {
 		return false, fmt.Errorf("compare requires --base, --stable, or both")
 	}
+	if (*approvedMigrationsPath == "") != (*candidateMigrationsPath == "") {
+		return false, fmt.Errorf(
+			"--approved-flag-migrations and --candidate-flag-migrations must be provided together",
+		)
+	}
+	if *approvedMigrationsPath != "" && (*basePath == "" || *stablePath == "") {
+		return false, fmt.Errorf("flag migration compare requires both --base and --stable")
+	}
 
 	current, err := readSnapshot(*currentPath)
 	if err != nil {
@@ -170,6 +197,25 @@ func runCompare(args []string, stdout, stderr io.Writer) (bool, error) {
 	}
 
 	report := interfacesnapshot.CompareAll(current, references)
+	if *approvedMigrationsPath != "" {
+		approved, readErr := readFlagMigrationManifest(*approvedMigrationsPath)
+		if readErr != nil {
+			return false, fmt.Errorf("read approved flag migrations: %w", readErr)
+		}
+		candidate, readErr := readFlagMigrationManifest(*candidateMigrationsPath)
+		if readErr != nil {
+			return false, fmt.Errorf("read candidate flag migrations: %w", readErr)
+		}
+		report, err = interfacesnapshot.CompareAllWithFlagMigrations(
+			current,
+			references,
+			approved,
+			candidate,
+		)
+		if err != nil {
+			return false, fmt.Errorf("validate flag migration lifecycle: %w", err)
+		}
+	}
 	encoder := json.NewEncoder(stdout)
 	encoder.SetEscapeHTML(false)
 	encoder.SetIndent("", "  ")
@@ -179,6 +225,49 @@ func runCompare(args []string, stdout, stderr io.Writer) (bool, error) {
 	return report.Compatible, nil
 }
 
+func readFlagMigrationManifest(path string) (interfacesnapshot.FlagMigrationManifest, error) {
+	file, err := os.Open(filepath.Clean(path))
+	if err != nil {
+		return interfacesnapshot.FlagMigrationManifest{}, err
+	}
+	defer file.Close()
+	return interfacesnapshot.ReadFlagMigrationManifest(file)
+}
+
+func validateHelpRendering(root *cobra.Command, snapshot interfacesnapshot.Snapshot) error {
+	for _, command := range snapshot.Commands {
+		path := strings.TrimPrefix(command.Path, "dws")
+		resolved, remaining, err := root.Find(strings.Fields(path))
+		if err != nil || len(remaining) != 0 || resolved == nil {
+			return fmt.Errorf("resolve %q before help rendering: remaining=%v error=%v", command.Path, remaining, err)
+		}
+		if err := renderCommandHelp(resolved); err != nil {
+			return fmt.Errorf("render %q help: %w", command.Path, err)
+		}
+	}
+	return nil
+}
+
+func renderCommandHelp(command *cobra.Command) (err error) {
+	var stdout, stderr bytes.Buffer
+	command.InitDefaultHelpFlag()
+	command.SetOut(&stdout)
+	command.SetErr(&stderr)
+	defer func() {
+		if recovered := recover(); recovered != nil {
+			err = fmt.Errorf("help renderer panicked: %v", recovered)
+		}
+	}()
+	command.HelpFunc()(command, []string{})
+	if stderr.Len() > 0 {
+		return fmt.Errorf("help renderer wrote an error: %s", strings.TrimSpace(stderr.String()))
+	}
+	if stdout.Len() == 0 {
+		return fmt.Errorf("help renderer produced empty output")
+	}
+	return nil
+}
+
 func readSnapshot(path string) (interfacesnapshot.Snapshot, error) {
 	file, err := os.Open(filepath.Clean(path))
 	if err != nil {
@@ -191,5 +280,5 @@ func readSnapshot(path string) (interfacesnapshot.Snapshot, error) {
 func printUsage(w io.Writer) {
 	fmt.Fprintln(w, "usage:")
 	fmt.Fprintln(w, "  interface-snapshot generate [--output FILE]")
-	fmt.Fprintln(w, "  interface-snapshot compare --current FILE [--base FILE] [--stable FILE]")
+	fmt.Fprintln(w, "  interface-snapshot compare --current FILE [--base FILE] [--stable FILE] [--approved-flag-migrations FILE --candidate-flag-migrations FILE]")
 }

cmd/interface-snapshot/main_test.go

@@ -15,11 +15,16 @@ package main
 
 import (
 	"bytes"
+	"errors"
+	"io"
 	"os"
 	"path/filepath"
+	"strings"
 	"testing"
 
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/interfacesnapshot"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam"
+	"github.com/spf13/cobra"
 )
 
 func TestCrossPlatformCoverageRunGenerateCapturesActualRootOffline(t *testing.T) {
@@ -56,6 +61,24 @@ func TestCrossPlatformCoverageRunGenerateCapturesActualRootOffline(t *testing.T)
 	}
 }
 
+func TestCrossPlatformCoverageRunGenerateRejectsHelpRenderingFailure(t *testing.T) {
+	testseam.Swap(t, &newRootCommand, func() *cobra.Command {
+		root := &cobra.Command{Use: "dws"}
+		root.SetHelpFunc(func(command *cobra.Command, _ []string) {
+			_, _ = io.WriteString(command.ErrOrStderr(), "injected help failure")
+		})
+		return root
+	})
+
+	var stdout, stderr bytes.Buffer
+	if exitCode := run([]string{"generate"}, &stdout, &stderr); exitCode != 2 {
+		t.Fatalf("run(generate) exit=%d stderr=%s", exitCode, stderr.String())
+	}
+	if !strings.Contains(stderr.String(), "injected help failure") {
+		t.Fatalf("run(generate) stderr=%q", stderr.String())
+	}
+}
+
 func TestCrossPlatformCoverageRunCompareUsesBothSnapshotInputsAndExitCode(t *testing.T) {
 	current := commandSnapshot("dws")
 	mergeBase := commandSnapshot("dws")
@@ -83,6 +106,368 @@ func TestCrossPlatformCoverageRunCompareUsesBothSnapshotInputsAndExitCode(t *tes
 	}
 }
 
+func TestCrossPlatformCoverageRunCompareEnforcesBaseOwnedFlagMigrationLifecycle(t *testing.T) {
+	dir := t.TempDir()
+	before := flagMigrationSnapshot(false)
+	after := flagMigrationSnapshot(true)
+	currentPath := writeSnapshot(t, dir, "current.json", after)
+	basePath := writeSnapshot(t, dir, "base.json", before)
+	stablePath := writeSnapshot(t, dir, "stable.json", before)
+	approvedPath := writeManifest(t, dir, "approved.json", flagMigrationManifestJSON("pending"))
+	candidatePath := writeManifest(t, dir, "candidate.json", flagMigrationManifestJSON("consumed"))
+
+	var stdout, stderr bytes.Buffer
+	exitCode := run([]string{
+		"compare",
+		"--current", currentPath,
+		"--base", basePath,
+		"--stable", stablePath,
+		"--approved-flag-migrations", approvedPath,
+		"--candidate-flag-migrations", candidatePath,
+	}, &stdout, &stderr)
+	if exitCode != 0 {
+		t.Fatalf("exact base-owned migration exit=%d stderr=%s", exitCode, stderr.String())
+	}
+	if !bytes.Contains(stdout.Bytes(), []byte(`"compatible": true`)) {
+		t.Fatalf("exact migration report is not compatible:\n%s", stdout.String())
+	}
+
+	stdout.Reset()
+	stderr.Reset()
+	emptyApproved := writeManifest(t, dir, "empty-approved.json", `{"version":1,"migrations":[]}`)
+	exitCode = run([]string{
+		"compare",
+		"--current", currentPath,
+		"--base", basePath,
+		"--stable", stablePath,
+		"--approved-flag-migrations", emptyApproved,
+		"--candidate-flag-migrations", candidatePath,
+	}, &stdout, &stderr)
+	if exitCode != 2 || !strings.Contains(stderr.String(), "must start pending") {
+		t.Fatalf("candidate self-approval exit=%d stdout=%s stderr=%s", exitCode, stdout.String(), stderr.String())
+	}
+}
+
+func TestCrossPlatformCoverageRunCompareRequiresBothFlagMigrationInputs(t *testing.T) {
+	dir := t.TempDir()
+	currentPath := writeSnapshot(t, dir, "current.json", commandSnapshot("dws"))
+	basePath := writeSnapshot(t, dir, "base.json", commandSnapshot("dws"))
+	approvedPath := writeManifest(t, dir, "approved.json", `{"version":1,"migrations":[]}`)
+
+	var stdout, stderr bytes.Buffer
+	exitCode := run([]string{
+		"compare",
+		"--current", currentPath,
+		"--base", basePath,
+		"--approved-flag-migrations", approvedPath,
+	}, &stdout, &stderr)
+	if exitCode != 2 || !strings.Contains(stderr.String(), "must be provided together") {
+		t.Fatalf("one-sided migration input exit=%d stdout=%s stderr=%s", exitCode, stdout.String(), stderr.String())
+	}
+}
+
+func TestCrossPlatformCoverageRunCompareRequiresBothReferencesForFlagMigrations(t *testing.T) {
+	dir := t.TempDir()
+	currentPath := writeSnapshot(t, dir, "current.json", commandSnapshot("dws"))
+	basePath := writeSnapshot(t, dir, "base.json", commandSnapshot("dws"))
+	stablePath := writeSnapshot(t, dir, "stable.json", commandSnapshot("dws"))
+	approvedPath := writeManifest(t, dir, "approved.json", `{"version":1,"migrations":[]}`)
+	candidatePath := writeManifest(t, dir, "candidate.json", `{"version":1,"migrations":[]}`)
+
+	tests := []struct {
+		name string
+		args []string
+	}{
+		{
+			name: "missing stable",
+			args: []string{"--base", basePath},
+		},
+		{
+			name: "missing base",
+			args: []string{"--stable", stablePath},
+		},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			args := []string{"compare", "--current", currentPath}
+			args = append(args, test.args...)
+			args = append(args,
+				"--approved-flag-migrations", approvedPath,
+				"--candidate-flag-migrations", candidatePath,
+			)
+			var stdout, stderr bytes.Buffer
+			exitCode := run(args, &stdout, &stderr)
+			if exitCode != 2 || !strings.Contains(stderr.String(), "requires both --base and --stable") {
+				t.Fatalf("one-reference migration compare exit=%d stdout=%s stderr=%s", exitCode, stdout.String(), stderr.String())
+			}
+		})
+	}
+}
+
+func TestCrossPlatformCoverageRunPrintsUsageForMissingAndUnknownCommands(t *testing.T) {
+	tests := []struct {
+		name       string
+		args       []string
+		wantStderr []string
+	}{
+		{
+			name:       "missing command",
+			args:       nil,
+			wantStderr: []string{"usage:", "interface-snapshot generate", "--approved-flag-migrations"},
+		},
+		{
+			name:       "unknown command",
+			args:       []string{"unknown"},
+			wantStderr: []string{`unknown command "unknown"`, "usage:", "interface-snapshot compare"},
+		},
+	}
+
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			var stdout, stderr bytes.Buffer
+			if exitCode := run(test.args, &stdout, &stderr); exitCode != 2 {
+				t.Fatalf("run(%v) exit=%d, want 2", test.args, exitCode)
+			}
+			if stdout.Len() != 0 {
+				t.Fatalf("run(%v) unexpectedly wrote stdout: %s", test.args, stdout.String())
+			}
+			for _, want := range test.wantStderr {
+				if !strings.Contains(stderr.String(), want) {
+					t.Errorf("run(%v) stderr missing %q:\n%s", test.args, want, stderr.String())
+				}
+			}
+		})
+	}
+}
+
+func TestCrossPlatformCoverageRunRejectsInvalidSubcommandArguments(t *testing.T) {
+	tests := []struct {
+		name string
+		args []string
+		want string
+	}{
+		{name: "generate unknown flag", args: []string{"generate", "--unknown"}, want: "flag provided but not defined"},
+		{name: "generate positional", args: []string{"generate", "unexpected"}, want: "generate accepts no positional arguments"},
+		{name: "compare unknown flag", args: []string{"compare", "--unknown"}, want: "flag provided but not defined"},
+		{name: "compare positional", args: []string{"compare", "unexpected"}, want: "compare accepts no positional arguments"},
+		{name: "compare missing current", args: []string{"compare", "--base", "base.json"}, want: "compare requires --current"},
+		{name: "compare missing reference", args: []string{"compare", "--current", "current.json"}, want: "compare requires --base, --stable, or both"},
+	}
+
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			var stdout, stderr bytes.Buffer
+			if exitCode := run(test.args, &stdout, &stderr); exitCode != 2 {
+				t.Fatalf("run(%v) exit=%d, want 2", test.args, exitCode)
+			}
+			if !strings.Contains(stderr.String(), test.want) {
+				t.Fatalf("run(%v) stderr missing %q:\n%s", test.args, test.want, stderr.String())
+			}
+		})
+	}
+}
+
+func TestCrossPlatformCoverageRunGenerateRejectsUnsafeOutputPath(t *testing.T) {
+	outputDirectory := t.TempDir()
+	var stdout, stderr bytes.Buffer
+	exitCode := run([]string{"generate", "--output", outputDirectory}, &stdout, &stderr)
+	if exitCode != 2 || !strings.Contains(stderr.String(), "create snapshot") {
+		t.Fatalf("directory output exit=%d stdout=%s stderr=%s", exitCode, stdout.String(), stderr.String())
+	}
+}
+
+func TestCrossPlatformCoverageRunGenerateReportsTemporaryDirectoryFailure(t *testing.T) {
+	missingTempRoot := filepath.Join(t.TempDir(), "missing")
+	for _, name := range []string{"TMPDIR", "TMP", "TEMP"} {
+		t.Setenv(name, missingTempRoot)
+	}
+
+	var stdout, stderr bytes.Buffer
+	exitCode := run([]string{"generate"}, &stdout, &stderr)
+	if exitCode != 2 || !strings.Contains(stderr.String(), "create isolated home") {
+		t.Fatalf("invalid temporary root exit=%d stdout=%s stderr=%s", exitCode, stdout.String(), stderr.String())
+	}
+}
+
+func TestCrossPlatformCoverageRunCompareReportsSnapshotReadFailures(t *testing.T) {
+	dir := t.TempDir()
+	validPath := writeSnapshot(t, dir, "valid.json", commandSnapshot("dws"))
+	missingPath := filepath.Join(dir, "missing.json")
+	tests := []struct {
+		name string
+		args []string
+		want string
+	}{
+		{
+			name: "current",
+			args: []string{"compare", "--current", missingPath, "--base", validPath},
+			want: "read current snapshot",
+		},
+		{
+			name: "main",
+			args: []string{"compare", "--current", validPath, "--base", missingPath},
+			want: "read main/development baseline snapshot",
+		},
+		{
+			name: "stable",
+			args: []string{"compare", "--current", validPath, "--stable", missingPath},
+			want: "read stable snapshot",
+		},
+	}
+
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			var stdout, stderr bytes.Buffer
+			if exitCode := run(test.args, &stdout, &stderr); exitCode != 2 {
+				t.Fatalf("run(compare) exit=%d, want 2", exitCode)
+			}
+			if !strings.Contains(stderr.String(), test.want) {
+				t.Fatalf("stderr missing %q:\n%s", test.want, stderr.String())
+			}
+		})
+	}
+}
+
+func TestCrossPlatformCoverageRunCompareReportsEachManifestReadFailure(t *testing.T) {
+	dir := t.TempDir()
+	snapshotPath := writeSnapshot(t, dir, "snapshot.json", commandSnapshot("dws"))
+	validManifest := writeManifest(t, dir, "valid-manifest.json", `{"version":1,"migrations":[]}`)
+	invalidManifest := writeManifest(t, dir, "invalid-manifest.json", `{`)
+	tests := []struct {
+		name      string
+		approved  string
+		candidate string
+		want      string
+	}{
+		{
+			name:      "approved manifest",
+			approved:  invalidManifest,
+			candidate: validManifest,
+			want:      "read approved flag migrations",
+		},
+		{
+			name:      "candidate manifest",
+			approved:  validManifest,
+			candidate: invalidManifest,
+			want:      "read candidate flag migrations",
+		},
+	}
+
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			var stdout, stderr bytes.Buffer
+			exitCode := run([]string{
+				"compare",
+				"--current", snapshotPath,
+				"--base", snapshotPath,
+				"--stable", snapshotPath,
+				"--approved-flag-migrations", test.approved,
+				"--candidate-flag-migrations", test.candidate,
+			}, &stdout, &stderr)
+			if exitCode != 2 || !strings.Contains(stderr.String(), test.want) {
+				t.Fatalf("%s exit=%d stdout=%s stderr=%s", test.name, exitCode, stdout.String(), stderr.String())
+			}
+		})
+	}
+}
+
+func TestCrossPlatformCoverageRunCompareReportsOutputFailure(t *testing.T) {
+	dir := t.TempDir()
+	snapshotPath := writeSnapshot(t, dir, "snapshot.json", commandSnapshot("dws"))
+	var stderr bytes.Buffer
+	exitCode := run([]string{
+		"compare",
+		"--current", snapshotPath,
+		"--base", snapshotPath,
+	}, failingWriter{}, &stderr)
+	if exitCode != 2 || !strings.Contains(stderr.String(), "write comparison report") {
+		t.Fatalf("comparison output failure exit=%d stderr=%s", exitCode, stderr.String())
+	}
+}
+
+func TestCrossPlatformCoverageReadHelpersRejectMissingAndInvalidInputs(t *testing.T) {
+	dir := t.TempDir()
+	missingPath := filepath.Join(dir, "missing.json")
+	invalidPath := filepath.Join(dir, "invalid.json")
+	if err := os.WriteFile(invalidPath, []byte(`{`), 0o600); err != nil {
+		t.Fatalf("write invalid fixture: %v", err)
+	}
+
+	if _, err := readSnapshot(missingPath); err == nil {
+		t.Fatal("readSnapshot(missing) unexpectedly succeeded")
+	}
+	if _, err := readSnapshot(invalidPath); err == nil {
+		t.Fatal("readSnapshot(invalid) unexpectedly succeeded")
+	}
+	if _, err := readFlagMigrationManifest(missingPath); err == nil {
+		t.Fatal("readFlagMigrationManifest(missing) unexpectedly succeeded")
+	}
+	if _, err := readFlagMigrationManifest(invalidPath); err == nil {
+		t.Fatal("readFlagMigrationManifest(invalid) unexpectedly succeeded")
+	}
+}
+
+func TestCrossPlatformCoverageValidateHelpRenderingReportsResolveError(t *testing.T) {
+	root := &cobra.Command{Use: "dws"}
+	err := validateHelpRendering(root, commandSnapshot("dws missing"))
+	if err == nil || !strings.Contains(err.Error(), `resolve "dws missing" before help rendering`) {
+		t.Fatalf("validateHelpRendering resolve error = %v", err)
+	}
+}
+
+func TestCrossPlatformCoverageValidateHelpRenderingReportsTemplateError(t *testing.T) {
+	root := &cobra.Command{Use: "dws"}
+	root.SetHelpTemplate(`{{index .Commands 99}}`)
+	err := validateHelpRendering(root, commandSnapshot("dws"))
+	if err == nil || !strings.Contains(err.Error(), `render "dws" help`) {
+		t.Fatalf("validateHelpRendering template error = %v", err)
+	}
+}
+
+func TestCrossPlatformCoverageValidateHelpRenderingRecoversTemplatePanic(t *testing.T) {
+	root := &cobra.Command{Use: "dws"}
+	root.SetHelpTemplate("{{")
+	err := validateHelpRendering(root, commandSnapshot("dws"))
+	if err == nil || !strings.Contains(err.Error(), `render "dws" help`) {
+		t.Fatalf("validateHelpRendering template panic = %v", err)
+	}
+}
+
+func TestCrossPlatformCoverageValidateHelpRenderingRejectsCustomHelpStderr(t *testing.T) {
+	root := &cobra.Command{Use: "dws"}
+	root.SetHelpFunc(func(command *cobra.Command, _ []string) {
+		_, _ = io.WriteString(command.ErrOrStderr(), "injected help failure")
+	})
+	err := validateHelpRendering(root, commandSnapshot("dws"))
+	if err == nil || !strings.Contains(err.Error(), "injected help failure") {
+		t.Fatalf("validateHelpRendering custom stderr = %v", err)
+	}
+}
+
+func TestCrossPlatformCoverageValidateHelpRenderingRejectsEmptyOutput(t *testing.T) {
+	root := &cobra.Command{Use: "dws"}
+	root.SetHelpFunc(func(*cobra.Command, []string) {})
+	err := validateHelpRendering(root, commandSnapshot("dws"))
+	if err == nil || !strings.Contains(err.Error(), "empty") {
+		t.Fatalf("validateHelpRendering empty output = %v", err)
+	}
+}
+
+func TestCrossPlatformCoverageValidateHelpRenderingAcceptsNormalOutput(t *testing.T) {
+	root := &cobra.Command{Use: "dws", Short: "root command"}
+	if err := validateHelpRendering(root, commandSnapshot("dws")); err != nil {
+		t.Fatalf("validateHelpRendering normal output: %v", err)
+	}
+}
+
+type failingWriter struct{}
+
+func (failingWriter) Write([]byte) (int, error) {
+	return 0, errors.New("injected write failure")
+}
+
+var _ io.Writer = failingWriter{}
+
 func commandSnapshot(paths ...string) interfacesnapshot.Snapshot {
 	commands := make([]interfacesnapshot.Command, 0, len(paths))
 	for _, path := range paths {
@@ -120,6 +505,68 @@ func writeSnapshot(t *testing.T, dir, name string, snapshot interfacesnapshot.Sn
 	return path
 }
 
+func writeManifest(t *testing.T, dir, name, contents string) string {
+	t.Helper()
+	path := filepath.Join(dir, name)
+	if err := os.WriteFile(path, []byte(contents), 0o600); err != nil {
+		t.Fatalf("write %s: %v", path, err)
+	}
+	return path
+}
+
+func flagMigrationSnapshot(after bool) interfacesnapshot.Snapshot {
+	legacy := interfacesnapshot.Flag{
+		Name:      "legacy-id",
+		Shorthand: "l",
+		Type:      "string",
+		Default:   "",
+		NoOpt:     "auto",
+		Required:  true,
+	}
+	flags := []interfacesnapshot.Flag{legacy}
+	if after {
+		legacy.Required = false
+		legacy.Hidden = true
+		legacy.AliasOf = "message-id"
+		flags = []interfacesnapshot.Flag{
+			legacy,
+			{Name: "message-id", Type: "string", Default: "", Required: true},
+		}
+	}
+	return interfacesnapshot.Snapshot{
+		SchemaVersion: interfacesnapshot.SchemaVersion,
+		Rules: interfacesnapshot.Rules{
+			ExcludedCommandSubtrees: []string{},
+			ExcludedFlags:           []string{},
+		},
+		Commands: []interfacesnapshot.Command{
+			{Path: "dws", Runnable: true, Aliases: []string{}, LocalFlags: []interfacesnapshot.Flag{}, InheritedFlags: []interfacesnapshot.Flag{}},
+			{Path: "dws chat send", Runnable: true, Aliases: []string{}, LocalFlags: flags, InheritedFlags: []interfacesnapshot.Flag{}},
+		},
+	}
+}
+
+func flagMigrationManifestJSON(state string) string {
+	return strings.Replace(`{
+  "version": 1,
+  "migrations": [{
+    "command": "dws chat send",
+    "legacy": {
+      "name": "legacy-id",
+      "before": {"present": true, "type": "string", "required": true, "shorthand": "l", "no_opt": "auto", "scope": "local"},
+      "after": {"present": true, "type": "string", "hidden": true, "shorthand": "l", "no_opt": "auto", "scope": "local", "alias_of": "message-id"}
+    },
+    "canonical": {
+      "name": "message-id",
+      "before": {"present": false},
+      "after": {"present": true, "type": "string", "required": true, "scope": "local"}
+    },
+    "state": "STATE",
+    "reason": "reviewed exact migration"
+  }]
+}`, "STATE", state, 1)
+}
+
 func hasFlag(flags []interfacesnapshot.Flag, name, flagType string) bool {
 	for _, flag := range flags {
 		if flag.Name == name && flag.Type == flagType {

docs/architecture.md

@@ -1,6 +1,6 @@
 # Architecture
 
-`dws` is a Go CLI with a versioned, static command surface for DingTalk MCP capabilities. Cobra help serves humans; the embedded Command Catalog serves AI agents.
+`dws` is a Go CLI with a versioned, static command surface for DingTalk MCP capabilities. Cobra help serves humans; runtime-assembled Schema (`ResolveSchemaBuild`) serves AI agents.
 
 ## High-Level Flow
 
@@ -9,8 +9,8 @@
 3. `internal/helpers` contains the main command handlers for all product surfaces (`dev`, `chat`, `calendar`, `contact`, `aitable`, etc.).
 4. `internal/executor` and `internal/transport` execute MCP JSON-RPC calls; `internal/output` formats responses.
 5. `internal/auth` manages login state, PAT tokens, and agent-code detection.
-6. Schema generation starts from the reviewed `CommandRegistry`, binds each identity to the exact current Cobra leaf, and then resolves typed constraints, sanitized MCP snapshots, Agent hints, and Skills into one `SchemaRegistry`. Startup and Schema queries do not call MCP `tools/list`.
-7. The embedded Catalog is a downstream release artifact and never backfills identity or participates in regeneration. Stable flag-to-interface property bindings come from the reviewed, content-addressed v3 manifest in `schema_parameter_bindings.json`; its exact active tuples, corrections, removals, and mapping exclusions are validated against the final bound `SchemaRegistry`. CLI `required` and constraints come from the resolved typed contract, while MCP `required` remains interface-only metadata.
+6. Schema assembly (`ResolveSchemaBuild`) starts from the reviewed `CommandRegistry`, binds each identity to the exact current Cobra leaf, and then resolves typed constraints, sanitized MCP snapshots, and leaf ContractFinal / ProductDecl into one `SchemaRegistry`. Startup and Schema queries do not call MCP `tools/list`. There is no generate-written Catalog delivery step.
+7. Production Catalog / `ResolveMeta` consume the lazily assembled registry via `RegisterSchemaSourceRoot` → `ResolveSchemaBuild` / `deliverySchemaCatalog` (声明即 Catalog; lazy `sync.Once`). `ResolveMeta` projects Identity/Safety/Selection from that assembly into an in-process map cache — not a committed `schema_catalog/` or `schema_meta_index.*` fixture. Flag-to-interface property delivery is owned by leaf `ParamDecl.Property` (native annotations). `schema_parameter_mapping_ledger.go` holds reviewed `mapping_exclusions` / `removals` (the empty `schema_parameter_bindings.json` audit table is retired). CLI `required` and constraints come from the resolved typed contract, while MCP `required` remains interface-only metadata.
 8. Agent selection results are fixed in versioned review inputs. Every public tool has explicit use/avoid/example and interface disposition metadata; Skill references that are not current leaves require an explicit alias/group/stale/out-of-surface review instead of fuzzy runtime matching.
 
 ## Repository Structure
@@ -19,8 +19,8 @@
 - `internal/app`: root command wiring, static utility commands, and plugin loading
 - `internal/helpers`: product command handlers (dev, chat, calendar, contact, etc.)
 - `internal/plugin`: versioned plugin manifest, hook, skill, and transport descriptor loading
-- `internal/cli`: embedded Agent Command Catalog, static schema query, and catalog contracts
-- `internal/generator`: deterministic Agent metadata and Command Catalog generators
+- `internal/cli`: Schema assembly, `dws schema` query, and catalog contracts
+- `internal/generator`: CI/determinism tools (`cmd_schema_catalog` dump) and param-alias generate
 - `internal/executor`: invocation dispatch and result handling
 - `internal/transport`: MCP HTTP client and request signing
 - `internal/auth`: login, token management, agent-code detection, identity
@@ -30,11 +30,16 @@
 - `internal/security`: endpoint allowlist and domain trust
 - `internal/safety`: runtime safety checks (confirm prompts, dry-run guards)
 - `internal/cobracmd`: shared Cobra command builders
+- `internal/corecmd`: dispatch-agnostic leaf-command base — flag registration,
+  alias/env/default value resolution, required and cross-flag constraint
+  validation, Risk write confirmation, toolArgs assembly, Runtime Schema
+  projection. Distinct from `internal/cobracmd` (generic tree helpers): it owns
+  the declarative leaf contract (`corecmd.Spec`) that the LeafSpec framework is
+  built on and that the Shortcut adapter projects into.
 - `internal/pat`: PAT (Personal Access Token) authorization flow
 - `internal/output`: response formatting (json, table, raw, pretty)
 - `internal/logging`: structured logging and argument sanitization
 - `internal/tui`: terminal UI helpers
-- `internal/recovery`: panic recovery and graceful degradation
 - `pkg/configmeta`: environment variable registry and documentation
 - `pkg/config`: configuration constants and paths
 - `pkg/edition`: edition detection (oss vs enterprise)

docs/automation.md

@@ -43,7 +43,7 @@ repository root while preserving repo-local guidance for automation.
 - Error message or category issues: inspect `internal/errors`
 - Audit log issues: inspect `internal/audit`
 - Plugin loading or command surface: inspect `internal/plugin`
-- Failure or degraded mode: inspect `internal/errors`, `internal/recovery`
+- Failure or degraded mode: inspect `internal/errors`
 
 ## Policy Checks
 

docs/ci-pr-gates.md

@@ -157,15 +157,33 @@ expected to repeat every CI job locally:
 ```sh
 make build
 make policy
-make interface-integrity
-make authoritative-interface-integrity BASE_REF=<merge-base>
-make schema-compatibility BASE_REF=<merge-base>
+make interface-integrity BASE_REF=<merge-base> STABLE_REF=<stable-tag> CANDIDATE_REF=<candidate-sha>
+make schema-compatibility BASE_REF=<merge-base> STABLE_REF=<stable-tag> CANDIDATE_REF=<candidate-sha>
 make skill-command-integrity
 make cli-smoke
 make mock-mcp-smoke
 go test -v -count=1 ./pkg/editiontest/...
 ```
 
+CI 先解析并核对精确的 merge-base、最近可达且未撤回的 stable GA tag 和已提交的 candidate
+SHA，再调用 `make authoritative-interface-integrity`。本地 `make interface-integrity`
+与该 CI target 都只委托给同一个 modern authoritative wrapper，不存在第二个比较
+入口。省略 `BASE_REF` 时本地 target 默认比较 `origin/main`，省略 `STABLE_REF` 时自动
+选择该 base 可达且未撤回的最近 stable GA tag，省略 `CANDIDATE_REF` 时比较已提交的 `HEAD`。
+需要逐字复现某次 CI 时，应显式传入该次运行记录的 merge-base、stable tag 和
+candidate SHA。
+
+`make update-interface-baseline` / `make reset-interface-baseline` 只维护
+`test/fixtures/cli-interface-baseline.txt` 这一份非权威 CLI Smoke fixture。底层旧
+`check-interface-baseline.sh` 不再作为本地或 CI 的兼容性审批入口，也不能用于批准
+flag 迁移。
+
+Schema compatibility 使用同一组 base、stable、candidate refs 和同一份 base-owned flag
+migration ledger。merge-base-owned checker 分别规范化 merge-base 与 stable 的完整
+Schema，并让 candidate 对两份历史 contract 独立执行检查；它只把已通过 Interface
+lifecycle 的 exact rename 规范化到当前历史副本，不会维护第二份 allowlist，也不会
+放宽其他 Schema 历史字段。
+
 For an exact CHANGELOG-only branch:
 
 ```sh
@@ -186,11 +204,24 @@ are evaluated by the same block-deduplicating checker; supporting policy and
 shortcut profiles contribute to changed-code coverage only. The checked-in
 badge is presentation only and is never read as a gate input.
 
-Compatibility checks derive authoritative Interface snapshots from the PR
-merge-base and the latest reachable stable release. The candidate cannot bless
-a breaking change by editing a fixture. Schema additions are allowed;
-historical products, tools, parameters, mappings, positional execution fields,
-constraints, and safety semantics remain protected.
+CLI 兼容检查只使用 modern Interface Snapshot 这一处权威比较 seam，并从 PR
+merge-base 和最近的可达 stable release 生成权威快照。本治理机制合入后，
+merge-base 拥有生成器、比较器和已审批迁移清单，因此 candidate 不能通过修改
+helper、fixture 或在同一 PR 新增 self-approval 记录来放行 breaking change。首次
+bootstrap 仍由 merge-base 已有的 modern helper 做无豁免比较，并只接受 candidate
+提交中的规范空清单；完整边界见下方治理文档。
+
+精确的两阶段 flag 迁移生命周期见
+[CLI flag 兼容迁移治理](cli-interface-flag-migrations.md)。治理 PR 只能在
+surface 未变化时新增 `pending`；后续产品 PR 达到审批的精确 surface 后，才能
+消费 base-owned 记录并改为 `consumed`。在 main 与 stable 都达到 after 状态前
+必须保留该回执，之后再由单独 PR 清理。机制只放行记录中的 legacy
+visible-to-hidden，以及 canonical required 新增或提升；删除、type、scope、
+shorthand、no-opt 和任何无关漂移仍然阻塞。Schema 可以新增；历史 product、
+tool、parameter、mapping、positional execution、constraint 与 safety 语义继续
+受保护。`alias_of` 只是一项由 `FlagSpec.Aliases` 产生的框架关系证据，不是 payload
+等价证明；产品 PR 仍须证明 canonical 与 legacy 的最终运行 payload 等价并在 transport
+前拒绝冲突输入。当前迁移清单为空，不授权 PR #904。
 
 ## Required GitHub repository settings
 

docs/cli-interface-flag-migrations.md

@@ -0,0 +1,176 @@
+# CLI flag 兼容迁移治理
+
+本文定义一种受控迁移：保留旧 flag 的可执行兼容性，但把它从 Help 与 Agent Schema 中隐藏，并将新的规范 flag 提升为必填。它只解决这一种精确变更，不是通用 breaking-change 豁免。
+
+同名 flag 的精确类型迁移属于另一类评审机制，只能进入
+`internal/interfacesnapshot/reviewed.go` 与 legacy smoke helper 的镜像表；flag rename
+只能进入本文的 JSON lifecycle ledger。一项迁移不得跨两种机制组合授权。
+
+## 唯一比较入口与信任边界
+
+PR 与本地兼容性审批的唯一权威比较入口是 modern Interface Snapshot：
+
+- `cmd/interface-snapshot` 生成和比较快照；
+- `internal/interfacesnapshot` 实现兼容规则和迁移生命周期；
+- `scripts/policy/check-command-compatibility.sh` 组装 candidate、PR merge-base 和最近可达且未撤回的 stable GA 三份快照；
+- `scripts/policy/check-authoritative-interface-baselines.sh` 只保留为 Makefile 的兼容包装，不再维护第二套判断逻辑。
+
+紧随其后的 Schema compatibility 不是第二份审批清单。它从同一 merge-base-owned
+ledger 和同一组三方 Interface Snapshot 取得已经完成 lifecycle 校验的
+authorization。merge-base-owned checker 会分别规范化 merge-base 与 stable 的完整
+Schema，并让 candidate 对两份历史 contract 独立执行检查；授权的 flag rename 只会
+精确投影到当前被检查的历史副本。candidate 不能为 CLI 与 Schema 分别提供两套例外。
+
+`make interface-integrity` 也调用上述 authoritative wrapper；默认 base 为
+`origin/main`，stable 可由包装脚本自动解析，candidate 默认为已提交的 `HEAD`。旧
+`scripts/policy/check-interface-baseline.sh` 只供
+`make update-interface-baseline` / `make reset-interface-baseline` 维护非权威 CLI
+Smoke fixture，不参与迁移审批。
+
+直接调用 `interface-snapshot compare` 时，只要提供 migration manifest 参数，就必须
+同时提供 `--base` 与 `--stable`；核心 lifecycle 也拒绝缺失 stable 的非空清单，避免
+调用方因漏传历史参考而提前清理 consumed receipt。
+
+PR merge-base 同时拥有快照生成器、比较器和已审批清单。门禁用这套 base-owned helper 检查同一个已提交 candidate revision、merge-base 与 stable，candidate 不能通过修改自己的 Go 比较 helper 来放宽规则。candidate 中的清单只参与迁移状态流转，不能批准同一个 PR 引入的接口变化。首次引入本机制时，merge-base 尚无迁移解析器；bootstrap 会用 merge-base 已有的 modern Interface Snapshot 做不带豁免的普通比较，并只接受 candidate 中逐字匹配的空清单，不会让 candidate 新增的 comparator 决定本 PR 是否兼容。bootstrap 无法让旧 helper 证明新治理实现本身正确，因此本治理 PR 的新 parser、lifecycle、launcher 与 hostile tests 仍是必须由真人评审的受保护策略变更；它们合入后才成为后续 PR 的 base-owned authority。
+
+这条边界保护比较规则和审批数据，不是任意代码沙箱。GitHub workflow / launcher 的变更仍由仓库保护规则和真人评审负责；candidate Cobra 构建也会执行 candidate 代码，因此对同一 runner 上的主动恶意代码，需要独立进程或文件系统隔离，不能把本门禁描述成已经解决。
+
+已审批清单固定为：
+
+```text
+scripts/policy/interface-migrations/approved-flag-migrations-v1.json
+```
+
+清单使用严格 JSON 解析：版本、字段名大小写、JSON 值类型、命令路径和 flag 名都必须精确；拒绝重复键、未知键、scalar `null` 与尾随 JSON 值，`reason` 不能为空；禁止 `*`、`?`、前缀规则或其他 wildcard。当前清单为空，因此本治理 PR **不授权 PR #904 或任何产品接口变化**。
+
+## 两阶段迁移与回执清理
+
+每条迁移以 `(command, legacy flag, canonical flag)` 为唯一精确键，并经历以下生命周期：
+
+| 阶段 | PR 可以做什么 | 必须满足的快照状态 |
+|---|---|---|
+| 1. 治理审批 | 新增 `state: pending` 的精确记录；不得在同一个 PR 修改产品 surface | candidate 和 merge-base 都与记录中的 `before` 完全一致；该记录不改变 stable 的判断 |
+| 2. 产品迁移 | merge-base 已拥有 `pending` 后，按记录一次性切到精确 `after`，并把记录改为 `state: consumed` | legacy 仍存在但由 visible 变 hidden，且声明 `alias_of`；canonical 达到记录的必填状态 |
+| 3. 保留回执 | 产品 PR 合入后，如果 stable 仍是 `before`，继续保留 `consumed` | merge-base 或 stable 仍有任一份尚未达到 `after` |
+| 4. 单独清理 | 当 merge-base 和 stable 都已经是 `after`，在后续 PR 删除该记录 | 两份参考快照均精确匹配 `after`；继续保留过期回执会被门禁拒绝 |
+
+因此，新增 `pending` 和修改产品 surface 不能发生在同一个 PR；candidate 自己新增的记录不能 self-approve。迁移也不能部分执行：legacy、canonical、`alias_of` 或状态只要有一项不匹配，门禁即失败。
+
+下面只是清单结构示例，不代表已审批命令；实际字段必须从 Interface Snapshot 核对：
+
+```json
+{
+  "version": 1,
+  "migrations": [
+    {
+      "command": "dws chat message recall",
+      "legacy": {
+        "name": "msg-id",
+        "before": {
+          "present": true,
+          "type": "string",
+          "required": true,
+          "scope": "local"
+        },
+        "after": {
+          "present": true,
+          "type": "string",
+          "hidden": true,
+          "scope": "local",
+          "alias_of": "message-id"
+        }
+      },
+      "canonical": {
+        "name": "message-id",
+        "before": { "present": false },
+        "after": {
+          "present": true,
+          "type": "string",
+          "required": true,
+          "scope": "local"
+        }
+      },
+      "state": "pending",
+      "reason": "保留旧 argv 兼容性，并将规范 flag 设为唯一可见入口"
+    }
+  ]
+}
+```
+
+产品迁移 PR 必须保持同一条记录的命令、flag、before/after 和 reason 不变，只把 `pending` 改成 `consumed`。
+
+## `alias_of` 是框架来源的受评审关系证据
+
+`alias_of` 不是 Schema 同义词、参数概念词典或任意文字声明。它只能由 `FlagSpec.Aliases` 写入，并与内部 origin `corecmd.flag_spec_aliases.v1` 成对出现；每次 Interface Integrity 都会在已提交的 detached candidate 上执行源码门禁，禁止其他生产文件写入或复刻这些 evidence token。Interface Snapshot 会验证：
+
+- legacy 与 canonical 位于同一个可执行命令；
+- canonical flag 确实存在；
+- legacy 与 canonical 类型一致；
+- legacy 不是指向自身，也不存在 alias chain；
+- legacy 的 after 状态精确指向该记录中的 canonical flag。
+
+通过命令框架声明 `FlagSpec.Aliases` 时，框架会自动注册隐藏的兼容 flag，并写入两项 relation annotation；仅手写 `alias_of`、伪造 origin、重复值或不精确值都会让快照生成失败。不要用 Schema overlay、迁移清单或手写 Cobra annotation 伪造关系。
+
+这项关系证据只证明 legacy/canonical 经过受控框架路径建立关系，不证明最终 transport payload 等价，也不会替产品代码实现命令特有的值同步。当前框架还禁止把
+`MarkRequired` 与 `FlagSpec.Aliases` 直接组合，因为 Cobra 的 hard-required
+校验只识别 canonical spelling。若产品迁移同时需要 canonical 的 Cobra required
+标记和 legacy spelling，产品 PR 必须提供明确的运行时方案，并通过 canonical / legacy
+最终 payload 等价、同值输入一致、冲突输入在 transport 前失败、legacy 仍可调用但 Help 隐藏等测试；迁移清单和 relation evidence 都不能替代这些证明。
+
+## 豁免边界
+
+一条 base-owned、状态正确且前后快照精确匹配的记录，只会从普通兼容报告中移除以下两类预期 finding：
+
+1. legacy flag 的 `flag_became_hidden`（visible → hidden）；
+2. canonical flag 的 `required_flag_added`（新增时即必填）或 `flag_became_required`（已有 flag 从可选变必填）。
+
+以下变化仍按普通兼容规则阻塞，不能被迁移记录掩盖：
+
+- 删除 legacy、canonical、命令或其他 flag；
+- flag 类型或迁移记录中的 scope、shorthand、`no_opt` 漂移；
+- `alias_of` 缺失、指向变化或 alias chain；
+- 命令路径及任何无关的阻塞性接口变化；
+- 不精确、部分完成、超出记录范围的 surface 变化。
+
+## Schema 投影边界
+
+Agent-visible command 会把 visible Cobra flag 投影为 Schema parameter，因此合法的
+legacy hidden 迁移会同时表现为历史 parameter 消失，constraint member 也可能从
+legacy 名改为 canonical 名。Schema adapter 只接受已经由三方 Interface Snapshot
+判定为 authorized 的迁移，并按 tool 的精确 `primary_cli_path` 绑定：
+
+- reference 仍处于 `before` 且该 flag 有 Schema surface 时，baseline legacy parameter
+  必须存在，candidate legacy parameter 必须消失，candidate canonical parameter 必须存在；
+  如果 baseline 只有 canonical、没有 legacy，则 adapter 不得借 CLI ledger 提升
+  `required` / `cli_required` 或重写 constraint；
+- rename 前后的 `type`、`property`、`interface_type`、default、format、enum 与
+  `required_when` 必须完全一致；
+- `required` / `cli_required` 只能保持不变或按审批从 `false` 提升为 `true`，禁止降低；
+- constraint 只允许在同一 tool 内按已枚举的 legacy → canonical map 做 member 替换、
+  排序与去重；group kind、非迁移 member 或 group 增删仍然阻塞；
+- 多个 legacy 指向同一 canonical 时，所有历史 parameter signature 必须一致，否则
+  fail closed。
+
+adapter 先构造经过上述验证的历史 contract 副本，再调用原 Schema checker；它不会按
+错误字符串删除 finding。这样既能处理纯 rename，也能阻止“旧 required 参数改名后意外
+变为 optional”或 property 漂移等伪兼容。`consumed` 回执在 merge-base Schema 已经处于
+canonical-only `after` 状态时不需要再次投影；adapter 保持 baseline 不变，由原 checker
+验证 candidate 是否仍与该 canonical contract 兼容。
+
+## 本地验证
+
+先确保 merge-base 和 stable tag 已在本地，然后运行与 CI 相同的权威门禁：
+
+```sh
+make interface-integrity \
+  BASE_REF=<merge-base> \
+  STABLE_REF=<stable-tag> \
+  CANDIDATE_REF=<candidate-sha>
+
+make schema-compatibility \
+  BASE_REF=<merge-base> \
+  STABLE_REF=<stable-tag> \
+  CANDIDATE_REF=<candidate-sha>
+```
+
+`STABLE_REF` 必须解析到从该 merge-base 可达的最高未撤回 stable GA tag；primary checker 会按 release contract 独立核对，不能用任意 after commit 或已撤回版本提前清理回执。包装脚本可以在省略时自动解析。`CANDIDATE_REF` 省略时固定为命令启动时的已提交 `HEAD`；评审和复现 CI 时应显式传入 candidate SHA，避免 surface 与清单来自不同 revision。

docs/command-domain-model.md

@@ -0,0 +1,209 @@
+# command 领域模型
+
+本文档描述 `internal/corecmd` 包的领域模型——类型、概念及其关系。
+
+## 核心模型图
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                         corecmd.Spec                                  │
+│                    (一个叶子命令的完整契约)                             │
+├─────────────────────────────────────────────────────────────────────┤
+│                                                                     │
+│  ┌─── CLI 表面 ───┐   ┌─── 参数声明 ───────────────────────────┐   │
+│  │ Use            │   │ FlagSpec[]                              │   │
+│  │ Short          │   │  ├─ Name / Kind / Default              │   │
+│  │ Long           │   │  ├─ Required / MarkRequired            │   │
+│  │ Example        │   │  ├─ Aliases[] / EnvVar (回退链)         │   │
+│  └────────────────┘   │  ├─ Bind / Transform / OmitEmpty       │   │
+│                       │  └─ Enum / Format / SchemaDescription  │   │
+│                       │                                        │   │
+│                       │ Constraint[]                            │   │
+│                       │  ├─ at_least_one                       │   │
+│                       │  ├─ exactly_one                        │   │
+│                       │  └─ mutually_exclusive                 │   │
+│                       │                                        │   │
+│                       │ ConstParams map[string]any             │   │
+│                       └────────────────────────────────────────┘   │
+│                                                                     │
+│  ┌─── 安全模型 ──────────────────────────────────────────────────┐  │
+│  │  Safety contract.SafetySpec                                       │  │
+│  │  ├─ Effect       (read / write / destructive)                │  │
+│  │  ├─ Risk         (low / medium / high)                       │  │
+│  │  ├─ Confirmation (not_required / user_required) ──▶ 运行时门 │  │
+│  │  └─ Idempotency  (idempotent / retryable / …)                │  │
+│  │                                                               │  │
+│  │  四字段彼此独立；同一值同时供运行时与 Schema 使用              │  │
+│  │  ConfirmFirst: bool (只控制确认门顺序)                         │  │
+│  └───────────────────────────────────────────────────────────────┘  │
+│                                                                     │
+│  ┌─── Contract 声明 (Agent 可见的元数据) ────────────────────────┐  │
+│  │  ContractDecl                                                   │  │
+│  │  ├─ Title / Description                                      │  │
+│  │  ├─ contract.DryRunSpec     {PreviewKind, RemoteReads}       │  │
+│  │  ├─ contract.InterfaceSpec  {Mode, Availability, Reason, Ref}│  │
+│  │  ├─ contract.SelectionSpec  {AgentSummary, UseWhen, AvoidWhen│  │
+│  │  │                          Prerequisites, Tips, Examples}    │  │
+│  │  ├─ contract.ToolIdentitySpec {ProductID, CanonicalPath, …}  │  │
+│  │  └─ Positionals[]  {Name, Type, Required, Variadic}          │  │
+│  └───────────────────────────────────────────────────────────────┘  │
+│                                                                     │
+│  ┌─── 执行体 (恰好一个) ─────────────────────────────────────────┐  │
+│  │  Invoke(Ctx, toolArgs)     ← #830 过渡：单步派发（目标 mcpbind）│  │
+│  │  Orchestrate(Ctx)          ← #830 过渡：多步编排（目标 Handler）│  │
+│  │  RunE(cmd, args)           ← 逃生舱：完全自定义               │  │
+│  └───────────────────────────────────────────────────────────────┘  │
+│                                                                     │
+│  ┌─── 钩子 ─────────────────────────────────────────────────────┐  │
+│  │  Validate(cmd, args)   ← 条件式业务校验（约束表达不了的）      │  │
+│  │  PostMount(cmd)        ← 挂载收尾（设置 Args 等 cobra 属性）   │  │
+│  └───────────────────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+## 构建与执行流
+
+```
+corecmd.Spec ──── corecmd.New() ────▶ cobra.Command ──── 用户执行 ────▶ Ctx
+                     │                    │                            │
+              构建时检查:              注册产物:                    执行上下文:
+              • validateDispatchDecl   • Flags + Aliases            • Str(name)
+              • validateSafetySpec     • Annotations (Schema)       • Int(name)
+              • validateContractDecl     • Long (约束 help)           • Bool(name)
+              • RegisterFlags          • RunE (管线)                • StrSlice(name)
+              • ValidateConstraintDecls                            • Changed(name)
+              • embedContractIntoSchema                            • DryRun() / Yes()
+              • AnnotateConstraints
+              • PostMount
+```
+
+## 领域概念
+
+| 概念 | 类型 | 职责 |
+|------|------|------|
+| **corecmd.Spec** | struct | 一个命令的完整契约（声明 + 执行） |
+| **FlagSpec** | struct | 一个参数的注册、回退链、绑定规则 |
+| **Constraint** | struct | 参数间的关系约束 |
+| **Safety** | contract.SafetySpec | 运行时与 Schema 共用的安全契约 |
+| **ContractDecl** | struct | Agent 可见的完整工具规格声明 |
+| **contract.SelectionSpec** | struct | Agent 选择该工具的语义指引 |
+| **contract.InterfaceSpec** | struct | 工具的接口模式与可用性 |
+| **contract.DryRunSpec** | struct | dry-run 能力声明 |
+| **contract.ToolIdentitySpec** | struct | 工具在注册表中的身份标识 |
+| **contract.RuntimeSchemaPositional** | struct | 有序位置参数声明 |
+| **Ctx** | struct | 执行上下文（类型安全的 flag 读取） |
+| **New** | func | 统一构建器（`corecmd.Spec` → `*cobra.Command`） |
+
+## SafetySpec
+
+`corecmd.Spec.Safety` 使用 `corecmd/contract.SafetySpec`（无 cli 类型别名），没有 command 自定义 Risk/Safety 枚举，也没有 `SafetyDecl` 覆盖层：
+
+```go
+Safety: contract.SafetySpec{
+    Effect:       "write",
+    Risk:         "high",
+    Confirmation: "user_required",
+    Idempotency:  "unknown",
+}
+```
+
+- `Confirmation == "user_required"` 时执行确认；`--yes` 和 `--dry-run` 可跳过交互。
+- `Effect`、`Risk`、`Idempotency` 不参与确认决策，也不会改写 `Confirmation`。
+- 任意一个字段非空时，四个字段必须全部显式声明；构建时拒绝部分声明。
+- 完全空值仅作为历史只读默认，最终发布为 `read/low/not_required/idempotent`。
+
+## FlagSpec 有效值回退链
+
+框架统一的 flag 值解析顺序：
+
+```
+显式主 flag (Changed)
+    │ 空?
+    ▼
+隐藏别名 (Changed, 按声明序)
+    │ 空?
+    ▼
+环境变量 (EnvVar)
+    │ 空?
+    ▼
+注册默认值 (Default)
+    │ 空?
+    ▼
+ArgDefault (兜底)
+```
+
+各 Kind 的特殊行为：
+
+| Kind | 入参条件 | 回退链 |
+|------|----------|--------|
+| KindString | 有效值非空（或 !OmitEmpty） | 完整参与 |
+| KindInt | 值 ≠ 0（putInt 语义） | 完整参与 |
+| KindBool | Changed 时入参（显式 false 也下发） | 不参与别名/env 回退 |
+| KindStringSlice | 存在非空元素 | 仅 Changed 的主 flag/alias |
+
+## Constraint 约束
+
+声明式跨 flag 关系，构建时校验合法性，运行时统一执行：
+
+| Kind | 语义 | 错误文案示例 |
+|------|------|-------------|
+| `at_least_one` | 至少提供一个 | "请至少指定 --a、--b 之一" |
+| `exactly_one` | 恰好提供一个 | "请指定 --a、--b 之一" / "只能指定其一" |
+| `mutually_exclusive` | 最多提供一个 | "参数 --a、--b 互斥，只能指定其一" |
+
+"是否提供"的判定复用有效值回退链（显式主 flag → 别名 → env），注册默认值不算作已提供。
+
+## ContractDecl 子结构
+
+### contract.SelectionSpec（Agent 选择指引）
+
+```go
+contract.SelectionSpec{
+    AgentSummary: "一句话描述工具做什么",
+    UseWhen:      []string{"在什么场景下应该选择这个工具"},
+    AvoidWhen:    []string{"什么场景不应该用，应该用什么替代"},
+    Prerequisites: []string{"使用前提条件"},
+    Tips:          []string{"使用技巧"},
+    Examples:      []string{"dws dev app create --name Bot --dry-run"},
+}
+```
+
+### contract.InterfaceSpec（接口模式）
+
+```go
+contract.InterfaceSpec{
+    Mode:         "composite",  // local / mcp / composite
+    Availability: "available",  // available / unavailable
+    Reason:       "...",        // composite/unavailable 时的原因
+    Ref: &contract.InterfaceRefSpec{ // mcp 时的 ref
+        ProductID: "...",
+        RPCName:   "...",
+    },
+}
+```
+
+### contract.DryRunSpec（dry-run 能力）
+
+```go
+contract.DryRunSpec{
+    PreviewKind: "invocation",  // invocation / request / plan
+    RemoteReads: false,         // dry-run 时是否发起远端读
+}
+```
+
+## 执行体三选一
+
+| 执行体 | 适用场景 | 框架做了什么 |
+|--------|----------|-------------|
+| **Invoke** | #830 过渡单步派发（生产仍用；目标 mcpbind） | 框架完成 required→constraint→validate→buildArgs→confirm，传入装配好的 toolArgs |
+| **Orchestrate** | #830 过渡多步编排（生产仍用；目标 Handler） | 框架完成 required→constraint→validate→confirm，传入 Ctx 自行组装调用 |
+| **RunE** | 逃生舱 | 框架仍执行 Safety 确认，具体业务执行完全自定义 |
+
+## 设计不变量
+
+1. **一个 corecmd.Spec = 一个叶子命令的全部事实**
+2. **声明面绝不调用后端**——command 是 dispatch-agnostic
+3. **执行面绝不发明 CLI 表面**——业务 flag 必须在 Flags 声明
+4. **构建时拦截 > 运行时报错**——声明错误 panic 在注册阶段
+5. **SafetySpec 是单一事实源**——Confirmation 驱动运行时，其余字段原样进入 Schema
+6. **声明即 review**——代码中的 Schema 经 code review 后直接投影，不依赖外部 hint 文件

docs/command-framework-architecture.md

@@ -0,0 +1,286 @@
+# 命令框架架构
+
+本文档描述 `internal/corecmd` 统一命令框架的当前架构，面向框架使用者和维护者。
+
+## 概览
+
+```
+用户输入 → cobra 命令树 → corecmd.New() → 运行时管线 → 后端派发
+```
+
+命令框架将 CLI 命令的**声明**与**执行**分离：
+
+- **声明面** — 数据字段描述命令是什么（flag、约束、SafetySpec、Contract 元数据）
+- **执行面** — 钩子函数描述命令做什么（校验、派发、编排）
+
+框架负责：flag 注册、有效值回退链、required/约束校验、SafetySpec 确认、toolArgs 装配、Agent Runtime Schema 投影。
+
+## 核心类型
+
+### corecmd.Spec
+
+统一的类型化命令规格，是框架的核心数据结构：
+
+```go
+type Spec struct {
+    // 声明面
+    Use         string
+    Short       string
+    Long        string
+    Example     string
+    Flags       []FlagSpec
+    Constraints []Constraint
+    Safety      contract.SafetySpec // 运行时与 Schema 的单一安全来源
+    ConfirmFirst bool         // 确认门先于参数校验
+    ConstParams map[string]any
+    Contract   ContractDecl    // 叶子 Contract 声明（非 Catalog Schema）
+
+    // 执行面（恰好一个；Invoke/Orchestrate 为 #830 过渡派发 API，目标 mcpbind+Handler）
+    Invoke      func(c *Ctx, toolArgs map[string]any) error  // 过渡：单步
+    Orchestrate func(c *Ctx) error                           // 过渡：多步
+    RunE        func(cmd *cobra.Command, args []string) error // 逃生舱
+
+    // 钩子
+    Validate    func(cmd *cobra.Command, args []string) error
+    PostMount   func(cmd *cobra.Command)
+}
+```
+
+### SafetySpec（单一安全来源）
+
+`Spec.Safety` 使用 `corecmd/contract.SafetySpec`：
+
+| 字段 | 职责 |
+|------|------|
+| `Effect` | 操作影响：read / write / destructive |
+| `Risk` | 风险等级：low / medium / high |
+| `Confirmation` | 是否需要用户确认：not_required / user_required |
+| `Idempotency` | 幂等性：idempotent / retryable / non_idempotent / unknown |
+
+四个字段彼此独立。框架只读取 `Confirmation` 决定运行时确认，其余字段原样发布到 Schema，不从一个字段机械推导另一个。非空 SafetySpec 必须一次声明完整：
+
+```go
+Safety: contract.SafetySpec{
+    Effect:       "write",
+    Risk:         "high",
+    Confirmation: "user_required",
+    Idempotency:  "unknown",
+},
+```
+
+完全空值保留历史只读默认 `read/low/not_required/idempotent`；不存在 Risk/Safety 枚举或覆盖优先级链。
+
+### FlagSpec
+
+声明一个 flag 的注册方式、有效值回退链、到 toolArgs 的绑定：
+
+```go
+type FlagSpec struct {
+    Name     string       // flag 名（kebab-case）
+    Usage    string       // --help 文案
+    Kind     FlagKind     // String / Int / Bool / StringSlice
+    Default  string       // 注册默认值
+    Required bool         // 框架校验非空
+    Aliases  []string     // 隐藏别名
+    EnvVar   string       // 环境变量回退
+    Bind     string       // toolArgs 键名（空则用 Name）
+    Transform func(string) (any, error)  // 值转换
+    // ...更多字段见源码
+}
+```
+
+### Constraint
+
+跨 flag 关系约束：
+
+```go
+type Constraint struct {
+    Kind  ConstraintKind  // at_least_one / exactly_one / mutually_exclusive
+    Flags []string
+}
+```
+
+## 有效值回退链
+
+flag 解析按以下顺序取值（先命中先生效）：
+
+```
+显式主 flag (Changed) → 隐藏别名 (Changed) → 环境变量 → 注册默认值
+                                                            │
+                                              ArgDefault ←──┘ (兜底)
+```
+
+- KindBool：仅 Changed 时生效，不参与回退链
+- KindStringSlice：仅主 flag / alias Changed 时生效，元素恒 TrimSpace
+- KindInt：非零才入 toolArgs（putInt 语义）
+
+## 构建时流程
+
+`corecmd.New(spec)` 执行以下构建时检查（失败则 panic）：
+
+1. **validateDispatchDecl** — 恰好一个执行体（Invoke/Orchestrate/RunE）
+2. **validateSafetySpec** — 非空 SafetySpec 的四个独立字段必须完整
+3. **validateContractDecl** — Contract 声明完整性（Description、AgentSummary、UseWhen、AvoidWhen、Examples、Interface）
+4. **RegisterFlags** — flag + alias 注册到 cobra
+5. **ValidateConstraintDecls** — 约束引用的 flag 必须存在
+6. **embedContractIntoSchema** — 投影到 dws.schema.* annotations
+7. **AnnotateConstraints** — 约束渲染到 --help
+8. **PostMount** — 调用方的挂载收尾钩子
+
+## 运行时流程
+
+生成的 `RunE` 按以下顺序执行：
+
+```
+[ConfirmFirst? → ConfirmSafety]      ← 可选：先确认后校验
+  │
+  ▼
+ValidateRequired                     ← 有效值回退链校验
+  │
+  ▼
+ValidateConstraints                  ← 互斥/至少一个/恰好一个
+  │
+  ▼
+Validate hook                        ← 条件式业务校验（可选）
+  │
+  ▼
+BuildArgs                            ← flag → toolArgs 装配
+  │
+  ▼
+ConstParams 合并
+  │
+  ▼
+[!ConfirmFirst? → ConfirmSafety]     ← 默认顺序：校验后确认
+  │
+  ▼
+Invoke(ctx, toolArgs)                ← #830 过渡：单步派发
+  或 Orchestrate(ctx)                ← #830 过渡：多步编排
+```
+
+## 消费方式
+
+### LeafSpec（MCP 直连叶子命令）
+
+```go
+func newDevAppCreateCommand(runner executor.Runner) *cobra.Command {
+    return NewLeafCommand(LeafSpec{
+        Use:     "create",
+        Short:   "创建开放平台企业内部应用",
+        Tool:    devAppCreateTool,
+        Safety: contract.SafetySpec{
+            Effect: "write", Risk: "high",
+            Confirmation: "user_required", Idempotency: "unknown",
+        },
+        ConfirmFirst: true,
+        Flags: []LeafFlag{
+            {Name: "name", Usage: "应用名称 (必填)", Bind: "name",
+             Trim: true, Required: true, RequiredHint: "--name 为必填"},
+        },
+        Contract: ContractDecl{
+            Description: "创建开放平台企业内部应用",
+            DryRun:      &contract.DryRunSpec{PreviewKind: "invocation"},
+            Interface:   &contract.InterfaceSpec{Mode: "composite", Availability: "available", Reason: "create then configure"},
+            Selection: contract.SelectionSpec{
+                AgentSummary: "创建钉钉开放平台应用",
+                UseWhen:      []string{"需要新建企业内部应用"},
+                AvoidWhen:    []string{"应用已存在时用 update"},
+                Examples:     []string{`dws dev app create --name "Bot" --dry-run`},
+            },
+        },
+        Call: devAppCall(runner),
+    })
+}
+```
+
+`NewLeafCommand` 经 `FromLeafSpec()` 归一为 `corecmd.Spec`，再交 `corecmd.New()` 构建。这是**完全托管模式**：声明 + 执行都归 command。
+
+### 声明元数据模式（既有命令补 Contract）
+
+执行体必须冻结时，用同一套 `LeafSpec` 词汇只声明元数据，写在命令字面量旁：
+
+```go
+baseListCmd := &cobra.Command{
+    Use: "list", Short: "获取 AI 表格列表",
+    RunE: func(cmd *cobra.Command, args []string) error { /* 原执行体不动 */ },
+}
+DeclareLeafMetadata(baseListCmd, LeafSpec{
+    Safety: aitableSafetyRead(),
+    Contract: ContractDecl{
+        Description: "列出最近访问的 AI 表格 Base。",
+        Interface:   aitableMCPInterface("list_bases"),
+        Selection: contract.SelectionSpec{
+            AgentSummary: "列出最近访问的 AI 表格 Base。",
+            UseWhen:      []string{"只需浏览最近打开过的 Base 时"},
+            AvoidWhen:    []string{"按名称查找优先 base search"},
+            Examples:     []string{"dws aitable base list"},
+        },
+    },
+})
+```
+
+`DeclareLeafMetadata` 调用 `corecmd.AttachContract` 挂 Safety+Contract；不注册 flag、不接管参数投影。可选 `Validate` 与 `ConfirmSafety` 同挂在 **RunE 包装器**内（不是 PreRunE）。当 `Safety.Confirmation=user_required` 时，用**同一份** SafetySpec 包一层 `ConfirmSafety`，保证执行门禁与 Catalog 同源；无 Validate 时确认推迟到 gated `CallTool`，成功返回却未确认则 fail-closed。迁移态入口；新命令仍应走 `NewLeafCommand`。
+
+### 三档路径（当前可接受）
+
+| 档 | 入口 | 说明 |
+|---|---|---|
+| **Tier1** | `corecmd.New` / `NewLeafCommand` | 完全托管：声明 + 执行都归框架 |
+| **Tier2** | `DeclareLeafMetadata` | helpers 迁移态；**Shortcut 也可采用，可接受** |
+| **Tier3** | 裸 Cobra | 应逐步收；新增裸叶需补声明或精确排除 |
+
+长期展望（非当前硬要求）：更多 Shortcut 可收敛到 mcpbind / 减少仅为参数装配的 `Execute`。**不要**把「Shortcut 必须去掉 Execute / 必须 mcpbind」当作当前门禁；也不要否定 Shortcut + `DeclareLeafMetadata`。
+
+### Shortcut（智能快捷方式，已接入 live mount）
+
+```go
+func mount(s Shortcut) *cobra.Command {
+    return corecmd.New(FromShortcut(s))
+}
+
+spec := FromShortcut(Shortcut{
+    Service: "chat",
+    Command: "+demo",
+    Risk:    RiskHighWrite,
+    Flags:   []Flag{...},
+    Execute: func(rt *RuntimeContext) error { ... },
+})
+```
+
+Shortcut 当前仍保留自身的 `Risk`，adapter 只在边界将它展开成完整
+`contract.SafetySpec`；command/Leaf 不再保留该枚举。Shortcut 的 Cobra
+type/default/usage provenance 保持不变，command 统一补充 Required、Enum 和关系约束投影。
+需要补 Agent Schema 且执行体暂不迁入时，Shortcut 也可走 Tier2
+`DeclareLeafMetadata`（与 helpers 同一路径）。
+
+## 文件结构
+
+| 文件 / 包 | 职责 |
+|------|------|
+| `internal/corecmd/corecmd.go` | 核心类型 + `New` 构建器 + 运行时管线 |
+| `internal/corecmd/contract_decl.go` | ContractDecl 载荷类型 + 声明完整性守卫 |
+| `internal/corecmd/contract/` | 契约 DTO（`SafetySpec` / `ParamDecl` / `ProductDecl` / `ContractFinalPayload`）；**无** Cobra-keyed Final store |
+| `internal/corecmd/runtimeannotate/` | `AnnotateRuntime*` 写注解（框架侧；`cli` 薄 re-export） |
+| `internal/corecmd/contractfinal/` | ContractFinal Cobra store + `RegisterRuntimeContractFinal`（框架侧；`cli` 薄 re-export） |
+| `internal/cli/homology/` | flag/help/schema 同源门禁（`HOM-*`） |
+| `internal/helpers/leaf.go` | LeafSpec 门面：`NewLeafCommand`（完全托管）+ `DeclareLeafMetadata`（声明元数据） |
+| `internal/shortcut/adapter.go` | FromShortcut 完整映射与 Risk 兼容边界 |
+| `internal/shortcut/runner.go` | RuntimeContext；live mount 委托 `corecmd.New(FromShortcut(s))` |
+
+## Schema 投影
+
+声明即 review：代码中的 Contract 声明经过 code review 后直接投影为：
+
+- **Agent Runtime Schema**（`dws.schema.*` Cobra annotations；经 `runtimeannotate` / ContractFinal 嵌入）
+- **运行时组装的 SchemaRegistry / Catalog ToolSpec wire**（`RegisterSchemaSourceRoot` → `ResolveSchemaBuild`；`dws schema` / `--all` / 完整 leaf 载荷）
+- **CommandMeta 投影**（装配 Once 同步缓存 `map[cli_path]CommandMeta`；`ResolveMeta` / `SafetyForCLIPath` / leaf `--help` Safety 稳态 O(1) 读缓存，与 SchemaRegistry 同源）
+- **Dry-run Capabilities**（声明自动索引为 reviewed 能力）
+
+生产权威是 leaf `ContractFinal` / `ProductDecl`（经 `RegisterSchemaSourceRoot` → `ResolveSchemaBuild` 装配进 Catalog）；`InstallBuildTimeAgentMetadataJSON` 仅用于 `cmd_schema_catalog` 的 CI/local dump inject，不是生产交付路径。`schema_agent_metadata/` 与 `schema_hints/` 已退役。不再需要外部 hint 文件维护 selection/metadata/dry-run 信息。Catalog/meta-index 路径不得提交。
+
+## 设计原则
+
+1. **声明 vs 执行分离** — Flags/Constraints/Safety/Contract 是声明；Invoke/Validate/PostMount 是执行
+2. **单一数据源** — 一份声明驱动 --help、Schema、catalog、runtime 校验
+3. **安全字段不互推** — Confirmation 单独驱动确认，Effect/Risk/Idempotency 原样发布
+4. **构建时拦截 > 运行时报错** — 声明不完整在命令注册时 panic，不等到用户触发
+5. **边界兼容** — Shortcut 暂由 adapter 转换，Leaf 直接声明 SafetySpec

docs/command-framework-comparison.md

@@ -0,0 +1,236 @@
+# 命令框架对比：DWS command vs lark-cli vs GWS
+
+本文档对比 DWS（钉钉工作区 CLI）、lark-cli（飞书 CLI）和 GWS（Google Workspace CLI / gcloud）三套命令框架的设计差异。
+
+## 总览对比
+
+| 维度 | DWS (command) | lark-cli | GWS (gcloud) |
+|------|---------------|----------|--------------|
+| 语言 | Go | Go | Python (gcloud) / Go (部分) |
+| CLI 框架 | cobra | cobra | argparse + calliope |
+| 调用底座 | MCP JSON-RPC | Lark REST SDK (`CallAPITyped`) | Google API Client |
+| 命令层次 | 2 层：LeafSpec + Shortcut | 3 层：Shortcuts + API Commands + Raw API | 2 层：surface commands + raw |
+| Schema 来源 | 代码声明投影 | 代码声明 + 运行时 introspection | API Discovery 文档自动生成 |
+| Agent 适配 | 内建 (dws.schema.*) | 内建 (--print-schema) | 外挂 (MCP adapter) |
+
+## 架构对比
+
+### DWS command
+
+```
+corecmd.Spec (声明) → corecmd.New() → cobra.Command
+     │
+     ├── contract.SafetySpec (运行时 + Schema 单一安全来源)
+     ├── FlagSpec[] (参数 + 回退链 + 绑定)
+     ├── Constraint[] (互斥/至少一个)
+     ├── ContractDecl (Agent Selection/DryRun/Interface)
+     │
+     └── Invoke / Orchestrate / RunE (执行)
+```
+
+**核心特点**：
+- 声明与执行严格分离
+- SafetySpec 四个独立字段直接对齐 Agent Runtime Schema
+- 有效值回退链：flag → alias → env → default
+- 框架统一校验、装配、确认、投影
+- Schema 从代码声明直接投影，无外部 hint 文件
+
+### lark-cli
+
+```
+Shortcut (声明) → runner.Mount() → cobra.Command
+     │
+     ├── Risk string (确认行为)
+     ├── Scopes / ConditionalScopes (OAuth 权限)
+     ├── Flag[] (参数 + Enum + Input sources)
+     ├── AuthTypes (user/bot)
+     │
+     ├── DryRun hook → DryRunAPI
+     ├── Validate hook
+     └── Execute hook → RuntimeContext → CallAPITyped
+```
+
+**核心特点**：
+- Execute 内直接调 REST API (`CallAPITyped`)
+- DryRun 是独立 hook（返回结构化 API 计划）
+- 内建 OAuth scope 声明与预检
+- `--print-schema --flag-name` 运行时 introspection
+- 无 Schema 投影层，Agent 通过 introspection 动态发现
+
+### GWS (gcloud 风格)
+
+```
+API Discovery → 代码生成 → surface command
+     │
+     ├── arguments (从 JSON Schema 自动生成)
+     ├── request/response 映射
+     └── 自定义 action hook (少量)
+```
+
+**核心特点**：
+- Schema-first：从 API Discovery 文档自动生成命令
+- 参数直接映射 API 字段（flat schema）
+- 人工 surface command 是 thin wrapper
+- Agent 适配通过 MCP 外部 adapter
+
+## 核心设计差异
+
+### 1. 声明粒度
+
+| 能力 | DWS command | lark-cli | GWS |
+|------|-------------|----------|-----|
+| 参数别名 + 环境变量回退 | ✅ FlagSpec.Aliases + EnvVar | ❌ 无 | ❌ 无 |
+| 声明式约束 (互斥/至少一个) | ✅ Constraint[] | ❌ 只有 Validate hook | ✅ argparse group |
+| 安全契约 | ✅ SafetySpec（effect/risk/confirmation/idempotency） | Risk | 无 |
+| Schema 投影 (Agent metadata) | ✅ ContractDecl 内建 | ⚠️ 运行时 introspection | ❌ 外挂 |
+| 参数绑定 (flag name → API key) | ✅ FlagSpec.Bind | ❌ 手写 | ✅ 自动映射 |
+| ConstParams (固定载荷) | ✅ | ❌ 手写在 Execute | ✅ 隐式 |
+| 确认门顺序可配 (ConfirmFirst) | ✅ | ❌ 固定顺序 | ❌ 无确认机制 |
+
+### 2. 执行模型
+
+| 维度 | DWS command | lark-cli | GWS |
+|------|-------------|----------|-----|
+| 参数装配 | 框架自动 (BuildArgs) | 手写 (`runtime.Str()/Bool()`) | 自动映射 |
+| 派发方式 | Invoke(ctx, toolArgs) | Execute(ctx, runtime) | 自动调用 |
+| 多步编排 | Orchestrate(ctx) | Execute 内链式 CallAPITyped | 不支持 |
+| DryRun | 框架统一 (--dry-run flag) | 独立 DryRun hook 返回 API 计划 | 部分命令支持 |
+| 错误分类 | apperrors 类型化 | errs.Problem 类型化 | HTTP status 映射 |
+
+### 3. Agent 适配
+
+| 维度 | DWS command | lark-cli | GWS |
+|------|-------------|----------|-----|
+| 工具发现 | `dws schema --all` (静态 catalog) | `--print-schema` (运行时) | API Discovery |
+| 选择指引 | contract.SelectionSpec (UseWhen/AvoidWhen) | Description + Tips | 无 |
+| 安全声明 | contract.SafetySpec 直接声明 | Risk string | 无 |
+| dry-run 能力声明 | contract.DryRunSpec (reviewed) | DryRun hook 存在性 | 无 |
+| 接口模式 | contract.InterfaceSpec (local/mcp/composite) | 隐式 (全部 REST) | 隐式 (全部 REST) |
+
+### 4. Schema 生命周期
+
+```
+DWS:      代码声明 → code review → cobra annotation → catalog/metadata JSON
+          (单一数据源，构建时验证完整性)
+
+lark-cli: 代码声明 → 运行时 introspection → Agent 动态发现
+          (无离线 catalog，Agent 必须执行命令才能发现)
+
+GWS:      API Discovery JSON → 代码生成 → surface command
+          (Schema-first，但命令行体验受限于 API 形状)
+```
+
+## 设计哲学对比
+
+### DWS command 的选择
+
+| 选择 | 理由 | 对比 |
+|------|------|------|
+| 框架装配参数 | 消除 N 个命令各写一份 toolArgs 装配 | lark-cli 每个 Execute 手动取 flag 值 |
+| SafetySpec 单一来源 | confirmation 驱动运行时，其余字段原样发布且互不推导 | lark-cli 只有 Risk 一个维度 |
+| 声明式约束 | 构建时校验合法性 + 投影到 Schema + 渲染帮助 | lark-cli 约束隐藏在 Validate 逻辑里 |
+| Schema 构建时投影 | 离线 catalog 支持 Agent 批量发现 | lark-cli 需要逐个命令 introspection |
+| 有效值回退链 | flag → alias → env 统一语义 | lark-cli 别名是独立 Flag 手动关联 |
+| ConfirmFirst | 精确建模遗留语义 | lark-cli 确认始终在 Execute 内 |
+
+### lark-cli 的选择
+
+| 选择 | 理由 | 对比 |
+|------|------|------|
+| 直连 REST API | 精确控制请求/响应，可处理分页/重试 | DWS 通过 MCP 间接调用 |
+| DryRun 返回 API 计划 | Agent 可预览将要发出的真实 HTTP 请求 | DWS dry-run 只展示参数 |
+| OAuth scope 声明 | 框架预检权限，失败提前 | DWS 依赖 MCP 层鉴权 |
+| `--print-schema` introspection | 运行时发现，无需维护离线 catalog | DWS 需要 re-generate |
+| Input sources (file/@path/stdin) | 丰富的输入方式声明 | DWS 无此抽象 |
+| PrintFlagSchema | 单 flag 级别的 JSON Schema 暴露 | DWS 只在 catalog 级别 |
+
+### GWS (gcloud) 的选择
+
+| 选择 | 理由 | 对比 |
+|------|------|------|
+| API Discovery 驱动 | 一份 Schema 生成所有：SDK/CLI/文档 | DWS/lark 手写 |
+| Flat parameter 映射 | API 字段 = CLI flag，零转换 | DWS 需要 Bind 映射 |
+| 无 shortcut 层 | API 粒度即用户粒度 | DWS/lark 有精选层 |
+
+## 代码量对比
+
+| 框架 | 核心框架代码 | 单命令声明开销 | 备注 |
+|------|-------------|---------------|------|
+| DWS command | ~1400 行 (command.go + contract_decl.go) | ~20-30 行 (纯声明) | 框架重、单命令轻 |
+| lark-cli | ~800 行 (runner.go + types.go + common.go) | ~50-150 行 (声明 + Execute 逻辑) | 框架轻、单命令重 |
+| GWS gcloud | ~5000+ 行 (calliope 框架) | ~10 行 (多数自动生成) | 框架最重、单命令最轻 |
+
+## DWS 命令声明示例 vs lark-cli
+
+### DWS (command / LeafSpec)
+
+```go
+NewLeafCommand(LeafSpec{
+    Use:    "create",
+    Short:  "创建应用",
+    Tool:   "create_dev_app",
+    Safety: contract.SafetySpec{
+        Effect: "write", Risk: "high",
+        Confirmation: "user_required", Idempotency: "unknown",
+    },
+    ConfirmFirst: true,
+    Flags: []LeafFlag{
+        {Name: "name", Usage: "应用名称", Bind: "name",
+         Trim: true, Required: true, RequiredHint: "--name 为必填"},
+    },
+    Contract: ContractDecl{
+        Description: "创建开放平台企业内部应用",
+        DryRun:    &contract.DryRunSpec{PreviewKind: "invocation"},
+        Interface: &contract.InterfaceSpec{Mode: "composite", Availability: "available", Reason: "create then configure"},
+        Selection: contract.SelectionSpec{
+            AgentSummary: "创建钉钉开放平台应用",
+            UseWhen:      []string{"需要新建企业内部应用"},
+            AvoidWhen:    []string{"应用已存在时用 update"},
+            Examples:     []string{`dws dev app create --name "Bot" --dry-run`},
+        },
+    },
+    Call: devAppCall(runner),
+})
+```
+
+### lark-cli (Shortcut)
+
+```go
+var CalendarCreate = common.Shortcut{
+    Service:     "calendar",
+    Command:     "+create",
+    Description: "Create a new calendar event",
+    Risk:        "write",
+    Scopes:      []string{"calendar:calendar"},
+    Flags: []common.Flag{
+        {Name: "summary", Desc: "Event title", Required: true},
+        {Name: "start", Desc: "Start time (RFC3339)", Required: true},
+        {Name: "end", Desc: "End time (RFC3339)", Required: true},
+        {Name: "attendees", Type: "string_slice", Desc: "Attendee emails"},
+    },
+    DryRun: func(ctx context.Context, rt *common.RuntimeContext) *common.DryRunAPI {
+        return &common.DryRunAPI{
+            Method: "POST",
+            Path:   "/open-apis/calendar/v4/calendars/{id}/events",
+            Body:   buildEventBody(rt),
+        }
+    },
+    Execute: func(ctx context.Context, rt *common.RuntimeContext) error {
+        body := buildEventBody(rt)
+        data, err := rt.CallAPITyped("POST",
+            "/open-apis/calendar/v4/calendars/{id}/events", nil, body)
+        if err != nil { return err }
+        return rt.Output(data)
+    },
+}
+```
+
+## 适用场景总结
+
+| 场景 | 最适合 | 原因 |
+|------|--------|------|
+| MCP 后端 + Agent Schema 投影 | **DWS command** | 内建 Schema 声明、SafetySpec 契约、离线 catalog |
+| REST API 直连 + OAuth scope 管理 | **lark-cli** | CallAPITyped + scope 预检 + DryRun API 计划 |
+| API-first 大规模 surface 生成 | **GWS gcloud** | Discovery 驱动，一份 Schema 生成一切 |
+| 多步编排 (跨服务链式调用) | **lark-cli** / DWS Orchestrate | lark 的 CallAPITyped 链式 + DWS 的 Orchestrate |
+| 遗留系统迁移 (保持行为等价) | **DWS command** | ConfirmFirst + 回退链 + catalog 漂移门禁 |

docs/command-index.md

@@ -40,7 +40,7 @@ Every command inherits these flags (documented here once, not repeated per comma
 - [`dws doc` — DingTalk Doc](#dws-doc) · 21 commands
 - [`dws drive` — DingTalk Drive](#dws-drive) · 6 commands
 - [`dws minutes` — AI Minutes](#dws-minutes) · 19 commands
-- [`dws oa` — OA Approval](#dws-oa) · 9 commands
+- [`dws oa` — OA Approval](#dws-oa) · 12 commands
 - [`dws report` — Reports](#dws-report) · 7 commands
 - [`dws todo` — Todo Tasks](#dws-todo) · 6 commands
 
@@ -277,14 +277,17 @@ _AI meeting notes: listing, summary, todos, transcription, recording control, mi
 
 ## `dws oa` — OA Approval
 
-_OA approval workflows: list, approve, reject, revoke, records._
+_OA approval workflows: inspect forms, forecast routes, create instances, approve, reject, revoke, and audit records._
 
-**9 commands**
+**12 commands**
 
 | Command | Description | When to use |
 |---|---|---|
 | `dws oa approval approve` | Approve a pending approval process instance (task) as the current user. | When the agent acts on a pending approval the user has delegated it to handle. |
+| `dws oa approval create-instance` | Create a real approval process instance from validated form values or a complete request payload. | After the agent has inspected the form Schema, forecast the route, resolved any selectable approvers, and obtained explicit user confirmation. |
 | `dws oa approval detail` | Retrieve full details of an approval process instance, including form fields, attachments, and state. | When the agent needs to read the content of an approval ticket before deciding on it or summarizing it. |
+| `dws oa approval form-schema` | Retrieve the form Schema for an approval template by processCode. | Before collecting or validating values for a new approval instance. |
+| `dws oa approval forecast-process` | Forecast the approval route for a template and its proposed form values. | Before creating an instance, especially when the route contains user-selectable approver or notifier nodes. |
 | `dws oa approval list-forms` | List approval process templates (forms) the current user is allowed to initiate. | When the agent needs to pick the right approval form before submitting a new request. |
 | `dws oa approval list-initiated` | List approval process instances the current user has initiated. | When the agent reviews the status of approvals the user submitted. |
 | `dws oa approval list-pending` | List approval process instances currently awaiting action from the current user. | When the agent surfaces "needs your approval" items in the user's inbox. |

docs/dev-agent-test-cases.md

@@ -1,7 +1,7 @@
 # dws dev 命令集 · Agent 人肉手工评测集（10 条复合用例）
 
 > 性质：**人肉手工评测集**——由测评人逐条手工跑、肉眼核对、人工判分，不是自动化脚本。
-> 用途：评测 agent（加载 `dingtalk-dev` 技能后）能否正确处理开放平台 dev 任务。
+> 用途：评测 agent（加载 `dingtalk-misc` 的 `references/devapp.md` 后）能否正确处理开放平台 dev 任务。
 > 特点：10 条**复合用例**，每条串多个子任务，一条覆盖一类完整场景；10 条合起来覆盖全部 34 个子命令 + 8 类横切行为。
 > 约定：所有命令应带 `--format json`；写操作应先 `--dry-run` 预览、用户确认后再 `--yes`；应用定位只用 `--unified-app-id`。
 

docs/devapp-agent-install-guide.md

@@ -6,7 +6,7 @@
 
 ## 一键安装
 
-`dws dev` 能力已经合入主干并随正式版发布。专用安装脚本会下载预编译二进制 + `dingtalk-dev` skill，**只需要 curl + tar，不需要 git / go / make**。
+`dws dev` 能力已经合入主干并随正式版发布。专用安装脚本会下载预编译二进制 + `dingtalk-misc` skill（开放平台应用文档落在 misc），**只需要 curl + tar，不需要 git / go / make**。
 
 ### macOS / Linux
 
@@ -24,7 +24,7 @@ irm https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-workspace-cli/ma
 
 1. 从 `DingTalk-Real-AI/dingtalk-workspace-cli` 的最新 Release 下载对应平台的预编译二进制。
 2. 安装 `dws` 到默认目录 `~/.local/bin`。
-3. 从 Release 的 skills 包里安装 `dingtalk-dev` skill 到本机已检测到的 Agent 目录。
+3. 从 Release 的 skills 包里安装 `dingtalk-misc` skill 到本机已检测到的 Agent 目录。
 
 支持这些环境变量（全部可选）：
 
@@ -33,7 +33,7 @@ irm https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-workspace-cli/ma
 | `DEVAPP_REPO` | 覆盖发布仓库，默认 `DingTalk-Real-AI/dingtalk-workspace-cli` |
 | `DEVAPP_VERSION` | 钉某个 release tag，默认取最新 release |
 | `DWS_INSTALL_DIR` | 二进制安装目录，默认 `~/.local/bin` |
-| `DWS_NO_SKILLS` | 设为 `1` 跳过 `dingtalk-dev` skill 安装 |
+| `DWS_NO_SKILLS` | 设为 `1` 跳过 `dingtalk-misc` skill 安装 |
 
 > `dws dev` 已在正式版里，所以你也可以直接用标准安装脚本 `install.sh`，二者都会带上 `dws dev`。
 

docs/flag-help-schema-homology.md

@@ -0,0 +1,269 @@
+# flag / help / schema 同源
+
+- **状态**：已决策（路径 A + Contract 嵌入 Schema）
+- **相关**：[`rfc-command-framework-convergence.md`](rfc-command-framework-convergence.md)、[`schema-dynamic-endpoint-design.md`](schema-dynamic-endpoint-design.md)
+- **实现门面**：`LeafSpec` → `corecmd.Spec` → `corecmd.New`
+
+## 1. 决策
+
+采用 **路径 A：Contract / LeafSpec 为 CLI 表面权威**，并且 **Contract 必须嵌入进 Schema**。
+
+「同源」的含义是：同一份 Contract（今日经 LeafSpec / `corecmd.Spec` 表达）同时决定——且门禁能证明——
+
+1. cobra 实际注册的 flags / required / defaults；
+2. `--help` 的 Flags 与「参数约束」段；
+3. 运行时**组装后的** Schema 交付中的 parameters、关系约束和 SafetySpec：
+   - **SchemaRegistry / Catalog ToolSpec wire** 供 `dws schema` / `--all` / 完整 leaf 载荷（lazy；首次 `dws schema` 触发完整装配）。
+   - **`ResolveMeta` / `SafetyForCLIPath` / leaf `--help` Safety** 与装配同源：`deliverySchemaCatalog` sync.Once 装配后同步物化 `map[cli_path]CommandMeta`；稳态为 O(1) map lookup，不为 Meta 单独重做全量 ToolSpec/wire 投影。
+   Agent metadata 在组装期间经内存 inject，不落盘、不 embed；`schema_agent_metadata/` 已退役，若存在则 policy 失败。
+
+嵌入机制（已落地）：
+
+```text
+corecmd.Spec
+  → RegisterFlags + embedContractIntoSchema
+  → cobra annotations:
+       dws.schema.contract=command
+       dws.schema.property / type / required  (per flag)
+       dws.schema.constraints
+  → RegisterRuntimeContractFinal(SafetySpec + ContractDecl)
+  → Schema 组装透传 Contract Final
+    （组装时内存 inject Agent metadata）
+  → RegisterSchemaSourceRoot → ResolveSchemaBuild
+  → SchemaRegistry (+ Meta cache map) / dws schema wire projection
+```
+
+command/Leaf 不再写 `dws.schema.risk`；SafetySpec 走类型化 Final 载荷，不使用字符串枚举注解。
+
+### 1.1 硬规则：声明 = 最终数据源（Schema 透传）
+
+受管命令进入 Schema 的叶子数据由 **Contract 声明**定义最终值；框架（`corecmd.New`）做**类型转换**并注册，Schema 组装**透传**，不得：
+
+- 把声明序列化成 JSON 注解再解析；
+- 在声明体系里再挂「评审字段」并行权威；
+- 用 hints/registry 盖写已声明字段。
+
+**declare-vs-delivery 例外（Title / Description）**：构造期 `ContractDecl.Description` **必填**（声明证据），但这不是「declare = wire 最终值」。Catalog **交付**时：
+
+- **description**：有 Cobra Long → 交付 Long（provenance `cobra_help` / `cobra_help_preferred`）；无 Long → 交付声明（`contract_final`）。**Short 不进入 description**。
+- **title**：声明 `ContractDecl.Title` 优先，否则 Cobra Short，再 MCP；组装 stamp 真实 winner。
+
+这是一条权威链上的显式交付偏好，不是双权威（见 RFC §5.0.4）。
+
+迁移期未迁完的叶子可暂走旧组装路径；**新声明面不含 review_reason / reviewed 字段**。写命令未设 `Safety` 时，过渡期仍可用 `runtime_gate` annotate（`HOM-S2`）。
+
+**不采用**路径 B（以 MCP meta / 已退役的 `schema_mcp_metadata` 生成全部 CLI flag/help/schema）作为主权威。钉钉 MCP meta 不是飞书 OAPI：粒度与 CLI 特有语义（二选一、OmitEmpty、ConstParams、write guard）无法从裸 meta 推出；强行生成会违反「Schema 描述 CLI，不制造 CLI」。
+
+路径 B 仅允许作为 **可选的 1:1 MCP 透传叶子通道**（见 §5），不得覆盖 LeafSpec / Shortcut 主路径。
+
+对外叙事：与飞书 **分层单权威** 同构——API/透传叶可用平台事实，产品 CLI / Shortcut 用手写契约 + 执行体——而不是「全家只有平台 meta」。
+
+### 1.2 声明（declare）：写什么、写在哪、投影到哪
+
+**定义**：声明 = 在 Contract 结构体的**数据字段**上写出事实；`corecmd.New` 据此注册 cobra、渲染 help、写入 `dws.schema.*`。钩子闭包（`Validate` / `Call` / `PostMount` / `RunE`）里的逻辑**不算**声明——即使行为正确，也不能单靠钩子让 Schema/help「猜出」该事实。
+
+命令框架边界与今日/目标对应见 RFC [`rfc-command-framework-convergence.md`](rfc-command-framework-convergence.md) **§5.0**（框架上的「声明」定义）；本节给字段级表与示例。
+
+**唯一写入面**（三选一，语义相同）：
+
+| 入口 | 类型 | 归一 |
+|---|---|---|
+| Leaf 命令 | `helpers.LeafSpec` | `FromLeafSpec` → `corecmd.Spec` |
+| Shortcut | Shortcut 声明（经 `FromShortcut`） | → `corecmd.Spec` |
+| 直接基座 | `corecmd.Spec` | `corecmd.New` |
+
+今日产品 CLI 叶子以 **`LeafSpec` 为声明门面**；字段与 `corecmd.Spec` 契约面一一对应。
+
+#### 1.2.1 契约字段（算声明）
+
+| 字段 | 声明什么 | 运行时 | 嵌入 Schema / help |
+|---|---|---|---|
+| `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`） |
+| `ConstParams` | 固定载荷（不上 flag 表） | 并入 toolArgs；不满足 Required | **不**投影为用户 parameter |
+| `Use` / `Short` / `Long` / `Example` | 命令身份文案与示例 | cobra 自身 | help；identity 以 collector 收集的 `ContractFinal.Identity` 声明为准（reviewed registry 已退役） |
+
+`FlagSpec` 子字段（声明细节）：
+
+| 子字段 | 作用 | 是否进 Schema parameters |
+|---|---|---|
+| `Name`, `Usage`, `Kind`, `Default` | 注册名/说明/类型/DefValue | 是（name/type；default 与 cobra 对齐） |
+| `Required` / `MarkRequired` | 非空校验 / cobra 硬必填 | 是（`required`） |
+| `RequiredHint`, `Aliases`, `EnvVar` | 校验提示、隐藏别名、环境回退 | 否（执行细节；别名不上主 parameter 表） |
+| `ArgDefault`, `Bind`, `OmitEmpty`, `Trim`, `Transform` | toolArgs 装配语义 | 否（载荷细节；`Bind` 可进 property 映射，但不另造 flag） |
+
+#### 1.2.2 编排 / 执行字段（不算声明）
+
+| 字段 | 角色 | 禁止用来「冒充」的声明 |
+|---|---|---|
+| `Validate` | 条件式/领域校验钩子 | 不得在此 `Flags().String(...)` 注册业务 flag；不得只靠钩子表达「必填/互斥」而不写 `Flags`/`Constraints` |
+| `Call` / `Invoke` / `Orchestrate` | 执行体 | 不得 `params[k]=…` 装配业务参数（应在 `Flags`/`ConstParams`） |
+| `PostMount` | 挂载后收尾（annotate、领域工具注入） | 不得注册业务 flag；分页等横切由领域工具注入并可走 annotate |
+| `RunE` | 逃生舱（整段手写） | 表面事实仍须 Flags 声明；框架仍按 Safety 执行确认 |
+| `Server` / `Tool` | MCP 路由 | 不构成 CLI parameter 声明 |
+
+#### 1.2.3 最小声明示例
+
+```go
+// 读：Safety 四字段显式对齐 Schema
+NewLeafCommand(LeafSpec{
+    Use: "get", Short: "…", Tool: "…",
+    Safety: contract.SafetySpec{
+        Effect: "read", Risk: "low",
+        Confirmation: "not_required", Idempotency: "idempotent",
+    },
+    Flags: []LeafFlag{
+        {Name: "unified-app-id", Usage: "…", Bind: "unifiedAppId", Trim: true, Required: true},
+    },
+    Call: devAppCall(runner), PostMount: devAppMeta(tool),
+})
+
+// 写：同一个 SafetySpec 同时驱动确认与 Schema
+NewLeafCommand(LeafSpec{
+    Use: "publish", Short: "…", Tool: "…",
+    Flags: []LeafFlag{ /* … */ },
+    Safety: contract.SafetySpec{
+        Effect: "write", Risk: "medium",
+        Confirmation: "user_required", Idempotency: "unknown",
+    },
+    Call: devAppCall(runner), PostMount: devAppMeta(tool),
+})
+
+// 迁移期旧写命令：确认走 annotate，见 §1.3 —— 不是新声明面
+NewLeafCommand(LeafSpec{
+    Use: "create", /* Flags… */,
+    Validate: func(cmd *cobra.Command, _ []string) error {
+        return devAppRequireWriteGuard(cmd, "create") // 执行守卫，不是 Contract 声明
+    },
+    Call: devAppCall(runner),
+    PostMount: devAppMetaWrite(tool), // 人工标注 runtime_gate
+})
+```
+
+**空 `Safety` 的含义**：command 为兼容旧只读叶保留 `read/low/not_required/idempotent` 默认。因此「会改状态却留空 Safety」**不是**合法声明；新 Leaf 必须写完整 SafetySpec，未迁移旧路径则按 §1.3 标注 gate。
+
+### 1.3 人工标注（annotate）：声明的补充通道
+
+当事实无法或不愿放进 Contract 字段时，必须**显式**落注解 / 评审源，禁止组装期推断：
+
+| 标注手段 | 典型值 | 何时用 |
+|---|---|---|
+| `cli.AnnotateRuntimeGate` / `devAppMetaWrite` | `dws.schema.runtime_gate=devAppRequireWriteGuard` | 尚未迁移到 SafetySpec 的旧写命令（`HOM-S2`） |
+| `cli.AnnotateRuntimeRisk` | `dws.schema.risk=…` | Shortcut 暂存的旧兼容路径；command/Leaf 禁止新增 |
+| `cli.AnnotateRuntimeFlag` / Constraints | 与 embed 同形 | 手写 cobra 叶补齐表面（长期应迁入 Contract） |
+| reviewed `schema_hints/metadata` Safety（已退役） | effect/risk/confirmation | 已删：`schema_hints/` 不得重现；受管命令以 Contract.Safety / gate 为准 |
+
+标注与声明冲突时：**Contract 声明胜**（路径 A）。标注不得发明未注册的 CLI flag。
+
+### 1.4 Schema 全覆盖（`ToolSpec` 无空洞）
+
+`dws schema` 叶子模型是 `cli.ToolSpec`。命令框架必须为**每一个字段组**指定权威；完整矩阵在 RFC **§5.0.4**，摘要：
+
+| ToolSpec 组 | 权威类 | 框架声明字段 / 其它源 |
+|---|---|---|
+| Identity | 声明源（identity collector 收集 `ContractFinal.Identity`；reviewed `schema_command_registry` 已退役） | `ContractDecl.Identity` 声明 |
+| Display / Title / Description | 声明证据 + 交付偏好（非双权威） | **title**：ContractDecl 优先，否则 Cobra Short，再 MCP；**description**：构造期 Description 必填；Catalog 交付 Long→`cobra_help`，无 Long→`contract_final`；**Short 不进 description**（RFC §5.0.4） |
+| Parameters.`name/type/required/default/property` | **声明**（或同形 annotate） | `Flags` / `Bind` |
+| Parameters.`description` | 声明 usage（`FlagSpec.Usage` / ParamDecl） | `schema_hints/` 已退役；不得用 overlay 改 type/required/default |
+| Parameters.`interface_*` | 评审源 | MCP meta / bindings；**不造 flag** |
+| Constraints | **声明** | `Constraints` |
+| Positionals | **声明** 或显式 annotate | 目标 `Args`；禁止推断 |
+| Safety.`effect/risk/confirmation/idempotency` | **声明**完整 `Safety`，或迁移期 `runtime_gate` / reviewed Safety | 四字段独立；不得互相推导 |
+| DryRun | 评审源 | dry-run capabilities registry |
+| Interface | 评审源 | MCP + 内存 inject 的 Agent metadata |
+| Selection | 声明（ContractFinal / ProductDecl） | `ContractDecl.Selection` / `ProductDecl` |
+| FieldProvenance / Extensions | 组装派生或评审扩展 | 组装器；与 delivered value 一致 |
+| （非 Schema parameter）ConstParams | **声明** | 载荷；不上 parameters 表 |
+
+验收：新增 Schema 字段必须同步改 RFC §5.0.4 + 本表；受管写命令 Safety 不得无主。
+
+## 2. 字段归属（每一类恰好一个写入者）
+
+| 字段类 | 权威 | 投影到 |
+|---|---|---|
+| flags / defaults / required / enum / 关系约束 / 运行时 Risk | Contract（LeafSpec / `corecmd.Spec` 门面） | cobra、`--help`、Schema `parameters` / constraints / confirmation |
+| ConstParams、Bind、OmitEmpty、Transform | 同上（载荷声明，不上 flag 表） | toolArgs；Schema 不把 ConstParams 伪装成用户 flag |
+| canonical path / aliases / navigation / exposure | identity collector 收集的 `ContractFinal.Identity` 声明（reviewed `schema_command_registry` 已退役） | Schema identity |
+| use_when / avoid_when / examples / agent_summary 文案 | `ContractDecl.Selection` / `ProductDecl` | Schema selection |
+| RPC tool 形状、`interface_ref`、interface 描述 | leaf `Contract.Interface` + `ParamDecl`（`schema_parameter_mapping_ledger.go` 仅 mapping_exclusions / removals；`schema_mcp_metadata` 已退役） | Schema `interface_*` 字段；**不得创建 flag** |
+| 参数描述 overlay（可选） | 生产 metadata 壳为空；参数事实走 ParamDecl / FlagSpec | **Contract/cobra 胜** |
+| 遗留 Safety 文案（迁移期） | 生产 metadata 壳为空；Safety 走 Contract | 以 Contract.Safety / runtime_gate 为准（见 §4） |
+| dry-run 正能力 | reviewed dry-run registry | Schema `dry_run` |
+| positionals | Contract Args / 显式 annotate | Schema `positionals` |
+| FieldProvenance | 组装派生 | Schema provenance（与值一致） |
+
+Selection **刻意不**由单命令 Contract 取代（RFC 决策 8 / schema 设计硬规则）；identity 的历史决策是不进 Contract、归 reviewed `CommandRegistry`，该 registry 已退役，现由 identity collector 收集 `ContractFinal.Identity` 声明（声明即 identity）。**完整无空洞表见 RFC §5.0.4。**
+
+## 3. 当前缺口与目标闭环
+
+已具备：
+
+- Flags / ConstParams / Constraints → 注册、校验与 `ConstraintHelp`；SafetySpec → 运行时 `ConfirmSafety`（command）；
+- Call / Execute 作为执行体；业务参数不得在 Call 内装配（helpers 门禁）；
+- **Contract → Schema 嵌入**：参数/约束写原生 annotation，SafetySpec 与 ContractDecl 注册为类型化 Contract Final 并由 Schema 组装透传；
+- Selection 权威为 `ContractDecl.Selection` / `ProductDecl`（`contract_final`）；`schema_hints/` 已退役。
+
+已进 CI（`make policy` → `check-schema-catalog.sh` / `check-runtime-confirmation-truth.sh`）：
+
+| Gate ID | CI 入口（`-run` 白名单 / 脚本） |
+|---|---|
+| `HOM-P1` / `HOM-D1` | `./internal/app`：`TestFinalSchemaParametersMatchExecutableHelpFlags`、`TestDeliverySchemaParametersMatchExecutableHelpFlags` |
+| `HOM-P2`（参数映射/bindings 子集） | `./internal/cli`：`TestSchemaParameterBindingsMatchReviewedBaselineAndDeliveryCatalog`、`TestDeliveryCatalogMCPParameterMappingsAreComplete` 等 bindings 门禁 |
+| `HOM-S1` / `HOM-S2`（confirmation 同源） | `./internal/cli/homology`：`TestUserRequiredSafetyHomologyWithRuntimeGate` + `check-runtime-confirmation-truth.sh`；`./internal/app`：`TestSheetFinalSchemaConfirmationMatchesRuntimeGuards` |
+| 词汇/决策钉扎 | `./internal/cli/homology`：`TestHomologyDecisionDocPinsPathAAndGateIDs`、`TestMCPPassthroughAdmissionExcludesLeafAndShortcut`、`TestHomologyCIEntrypointsPinned` |
+
+仍缺（未宣称全量 CI 覆盖）：
+
+1. 独立可执行的 `HOM-P3`（constraints ≡ AnnotateConstraints）与 `HOM-S3`（read 不得误投影 user_required）全量 gate；
+2. `HOM-I1` 作为单独 gate ID 的显式用例（MCP bindings ⊆ Contract flags 已有映射审计子集，但未钉 `HOM-I1` 标签）。
+
+已落地（写命令确认语义，`HOM-S2`）：
+
+- `AnnotateRuntimeGate` / `dws.schema.runtime_gate`；Leaf `PostMount: devAppMetaWrite`；手写 delete/robot 等同路径显式标注；
+- Schema 组装在无 Contract Safety 但有 gate 时 overlay `confirmation=user_required`（`applyContractGateToSafety`）；
+- AST/mount 测试：新 Leaf 须声明完整 SafetySpec；尚未迁移的旧路径须有 runtime_gate。
+
+## 4. Schema 投影与 Safety 门禁规划
+
+以下门禁 ID 稳定，便于 CI 认领。§3 表标明哪些已挂入 `check-schema-catalog.sh`。
+
+| Gate ID | 断言 | 范围 | CI |
+|---|---|---|---|
+| `HOM-P1` | 受管 leaf 的 schema `parameters[].name` 集合 ≡ cobra 本地 flag 名集合（排除全局 persistent） | LeafSpec / Contract 编译命令 | **已进**（app help↔schema） |
+| `HOM-P2` | schema parameter `type` / `required` / `default` 与 cobra DefValue / MarkFlagRequired / FlagSpec 一致；不得用已退役 hints overlay 改写这三项 | 同上 | **部分**（bindings/mapping 门禁） |
+| `HOM-P3` | schema 关系约束（require_one_of / mutually_exclusive）≡ Contract/Leaf `Constraints` 投影（与 `AnnotateConstraints` 同构） | 声明了 Constraints 的命令 | 规划 |
+| `HOM-S1` | Contract/Leaf `user_required` Safety 与运行时 Confirm/gate 同源，且 help Safety 行同语义 | 受管写/破坏性命令 | **已进** |
+| `HOM-S2` | 若命令走显式 write guard（如 `devAppRequireWriteGuard`）而非完整 SafetySpec，则必须人工标注 `dws.schema.runtime_gate`；Schema 不得呈 `confirmation=not_required`；符合 §1.1 declare OR annotate | 今日 devapp 写命令 | **已进**（同源测试含 gate 路径） |
+| `HOM-S3` | `Risk=read`（或空→read）不得投影为 `user_required`，除非有 reviewed exclusion reason | 受管读命令 | 规划 |
+| `HOM-I1` | `interface_ref` 存在时，bindings 覆盖的 CLI flag ⊆ Contract flags；MCP meta **不**引入额外 CLI flag | 有 MCP 绑定的命令 | **部分**（mapping 审计） |
+| `HOM-D1` | `dws <path> --help` Flags 段与 schema leaf parameters 零未解释增量 | 受管公开 leaf | **已进**（与 HOM-P1 同测） |
+
+落地顺序建议：
+
+1. 保持 `HOM-P1`/`HOM-D1`/`HOM-S1`/`HOM-S2` 在 `check-schema-catalog.sh` 白名单中（勿再只靠词汇钉扎）；
+2. 补独立 `HOM-P3` / `HOM-S3` 可执行 gate，并把 `HOM-P2`/`HOM-I1` 从「部分」升到全量标签；
+3. 新 Leaf 继续走 Contract 嵌入；禁止 `schema_hints/` 回潮。
+
+## 5. 路径 B 子通道：1:1 MCP 透传叶（可选，非主路径）
+
+仅当同时满足以下条件时，才允许「从 MCP meta 生成 flag/help/schema 参数」：
+
+1. CLI path ↔ 单一 MCP tool **严格 1:1**，无多步、无按名解析、无本地 effect；
+2. 无不在 MCP input schema 中的 CLI 特有 flag（含 guard 专用语义 flag 除外的全局 `--yes`/`--dry-run`）；
+3. 无 ConstParams / Transform / 跨 flag 约束 / Call 内业务逻辑；
+4. Risk/confirmation 在 meta 或并列 reviewed Safety 中有显式来源，不靠生成器猜测；
+5. 在 identity 声明面标记 `surface_kind=mcp_passthrough`（名称可调整；原计划标在 reviewed registry，该 registry 已退役），且 **不得**与 LeafSpec/Shortcut 手写定义双注册同一 `cli_path`；
+6. 文档与门禁写明：该通道是子集优化，失败时回退/禁止扩张到产品 CLI。
+
+显式排除（永远走路径 A / Shortcut）：
+
+- 全部 `LeafSpec` 命令（含 `dws dev app …`）；
+- 全部 `+shortcut` 与 smart 编排；
+- 任何需要 `devAppRequireWriteGuard`、cursor 工具注入、或响应投影的命令。
+
+## 6. 非目标
+
+- ~~不把 canonical identity / 导航塞进 Contract（仍归 reviewed `CommandRegistry`）~~ —— 该非目标已被后续演进取代：reviewed `CommandRegistry` 已退役，identity 现由 collector 收集 `ContractFinal.Identity` 声明（声明即 identity，不再是独立评审文件）。selection 文案已由 `ContractDecl.Selection` / `ProductDecl` 声明（非 hints）。
+- 不要求删除 LeafSpec 门面。
+- 不把「生成 catalog 字节一致」当作运行时同源的充分条件（仍需 `HOM-*` 与差分门禁）。

docs/reference.md

@@ -5,8 +5,8 @@
 | Variable | Purpose / 用途 |
 |---------|---------|
 | `DWS_CONFIG_DIR` | Override default config directory / 覆盖默认配置目录 |
-| `DWS_AGENT_PRODUCT` | Optional, caller-declared Agent product sent through the existing HTTP `claw-type` header (for example `qwenwork`). 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 preserve the edition default (`openClaw` in the open-source build). / 可选、由调用方声明的 Agent 产品标识，经校验后覆盖 HTTP `claw-type` 请求头；未设置或为空时保持当前发行版默认值 |
-| `DWS_AGENT_HOST` | Optional, caller-declared Agent runtime form sent as `x-dws-agent-host` (for example `cloud` or `desktop`). 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. / 可选、由调用方声明的 Agent 运行形态，经校验后作为 `x-dws-agent-host` 发送；未设置时省略 |
+| `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_<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,23 +14,36 @@
 | `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 Product and Host trust model / Agent 产品与运行形态的信任模型
+### Agent Product, Host, and `claw-type` / Agent 产品、运行形态与 `claw-type`
 
-`DWS_AGENT_PRODUCT` and `DWS_AGENT_HOST` are caller-declared selection and
-observation signals. They are not credentials, attestations, or proof of the
-calling host's identity. DingTalk services may record them for logs/BI and may
-combine supported values with separately authenticated context for PAT
-compatibility, PAT identity/source derivation, or Discovery eligibility. A
-service must allowlist supported values and must never grant access, bypass
-authentication, or skip authorization solely because either Header claims a
-particular product or runtime form. They are not used to select ordinary MCP
-tool endpoints.
+`DWS_AGENT_PRODUCT` and `DWS_AGENT_HOST` are caller-declared observation
+signals. They are not credentials, attestations, or proof of the calling
+host's identity. The CLI validates and emits `x-dws-agent-product` and
+`x-dws-agent-host`, but does not use either value to derive its authentication,
+PAT mode, Discovery behaviour, or ordinary MCP endpoint selection. Downstream
+services own and must document their own contracts for these caller-declared
+Headers.
 
-`DWS_AGENT_PRODUCT` controls only the HTTP `claw-type` Header. The similarly
-named `clawType` tool argument on IM send operations is an independent
-message-display axis used for the “Send from AI” label. It remains controlled
-by the active edition's `ClawTypeValue` and `--ai-tag`; changing
-`DWS_AGENT_PRODUCT` does not change that message label.
+Service integrators should treat both Headers as untrusted input, allowlist
+expected values, and should not grant access, bypass authentication, or skip
+authorization solely because a Header claims a particular Product or Host.
+
+The HTTP `claw-type` Header is a separate, edition-fixed PAT/routing label:
+`openClaw` in the open-source build. `DWS_AGENT_PRODUCT` never changes it or
+PAT `hostControl.clawType`. On IM send/reply operations with `--ai-tag`,
+however, a valid non-empty Product value is used as the `clawType` tool
+argument so the delivered message carries the matching “Send from AI” label.
+Because `--ai-tag` defaults to `true`, this display change is enabled by
+default for callers that set Product. With `--ai-tag=false`, native
+`chat message send` / `reply` calls serialize `clawType: ""`, while shortcut
+calls omit the argument; this client does not assume downstream services treat
+an empty value and an absent key as equivalent. The display-value precedence
+when the tag is enabled is valid non-empty `DWS_AGENT_PRODUCT`, then the active
+edition's `ClawTypeValue`, then `openClaw`.
+
+Do not set arbitrary Product values that the target downstream and IM services
+have not explicitly enabled; an unknown value may be ignored or may not render
+the expected label.
 
 For QwenWork, report the dimensions separately:
 
@@ -39,16 +52,25 @@ DWS_AGENT_PRODUCT=qwenwork
 DWS_AGENT_HOST=cloud       # or desktop
 ```
 
-Do not set arbitrary product values that the target service has not explicitly
-enabled. Older combined Host labels such as `qwenwork_cloud` still satisfy the
-generic syntax for compatibility, but new integrations should use the
-two-dimensional convention above.
+Older combined Host labels such as `qwenwork_cloud` still satisfy the generic
+syntax for compatibility, but new integrations should use the two-dimensional
+convention above.
 
 `DWS_AGENT_PRODUCT` 和 `DWS_AGENT_HOST` 均由调用方声明，不是认证凭据，也不能证明
-真实宿主身份。服务端可以在独立认证上下文中将受支持值用于日志/BI、PAT 兼容策略、
-PAT 身份/来源派生或 Discovery 准入，但不得仅凭这两个 Header 放权、绕过认证或跳过
-授权。HTTP `claw-type` 与 IM 消息发送参数 `clawType` 是两个独立维度；后者仅控制
-“Send from AI”展示，仍由发行版 `ClawTypeValue` 和 `--ai-tag` 决定。
+真实宿主身份。CLI 只负责校验并发送 `x-dws-agent-product` 与 `x-dws-agent-host`，
+不会用它们派生本客户端的鉴权、PAT 模式、Discovery 行为或 MCP 端点；下游服务的
+使用契约由对应服务自行定义和说明。HTTP `claw-type` 是发行版固定的 PAT/路由标签，
+开源版固定为 `openClaw`，不受 `DWS_AGENT_PRODUCT` 影响。
+
+服务集成方应将这两个请求头视为不可信输入并对白名单值做校验，不应仅因请求头声明了
+某个 Product 或 Host 就授予访问、绕过认证或跳过鉴权。
+
+`--ai-tag` 默认为 `true`，因此配置合法非空 Product 后，默认发送的 IM 工具参数
+`clawType` 及小尾巴会随之改变。传入 `--ai-tag=false` 时，原生
+`chat message send` / `reply` 会发送 `clawType: ""`，shortcut 调用则省略该参数；
+本客户端不假定下游会将空值与键缺失等价处理。启用小尾巴时，展示值优先级依次为
+`DWS_AGENT_PRODUCT`、当前发行版的 `ClawTypeValue`、`openClaw`。不要传入目标下游及
+IM 服务未明确支持的 Product 值，否则可能被忽略或无法展示预期标签。
 
 ## Exit Codes / 退出码
 
@@ -72,7 +94,7 @@ With `-f json`, error responses include structured payloads: `category`, `reason
 dws contact user search --query "Alice" -f table   # Table (default, human-friendly / 表格，默认)
 dws contact user search --query "Alice" -f json    # JSON (for agents and piping / 适合 agent)
 dws contact user search --query "Alice" -f raw     # Raw API response / 原始响应
-dws schema -f pretty "calendar event create"         # Pretty Agent schema view / Agent Schema 彩色查看
+dws schema -f pretty "calendar event create" --compact # Pretty Agent schema view / Agent Schema 彩色查看
 ```
 
 ## Dry Run / 试运行
@@ -89,35 +111,36 @@ dws contact user search --query "Alice" -o result.json
 
 ## Schema Introspection / Schema 查询
 
-`--help` 展示当前二进制的 Cobra 命令和可接受 flag，`dws schema` 查询同版本内嵌的 Agent 命令契约。Schema 查询不访问 MCP endpoint、不执行 `tools/list`，也不搜索钉钉文档或任何业务数据。
+`--help` 展示当前二进制的 Cobra 命令和可接受 flag，`dws schema` 查询同版本运行时组装的 Agent 命令契约。Schema 查询不访问 MCP endpoint、不执行 `tools/list`，也不搜索钉钉文档或任何业务数据。
 
-Schema 的稳定 `canonical_path`、主 CLI 路径和 aliases 来自 reviewed `CommandRegistry`，并在发布时逐项绑定当前 Cobra tree。编辑 `internal/cli/schema_command_registry.json` 时必须遵守同目录的 `schema_command_registry.schema.json`；普通生成流程只校验该 reviewed input，不会覆盖它。Native annotation 只做实现一致性校验；Catalog 是该统一强类型契约的发布输出，不作为命令发现或下一轮生成的输入。
+Schema 的稳定 `canonical_path`、主 CLI 路径和 aliases 收集自命令树叶节点上的 `ContractFinal.Identity`（`CollectIdentitySpecs`），并在发布时逐项绑定当前 Cobra tree。原 reviewed `schema_command_registry/` 已退役，身份变化通过编辑叶节点声明完成。Native annotation 只做实现一致性校验；Catalog 是该统一强类型契约的发布输出，不作为命令发现或下一轮生成的输入。
 
 ### 路径写法
 
 ```bash
 dws schema                                      # 当前公开产品面的紧凑概览
-dws schema calendar                             # 展开一个产品
-dws schema "calendar event"                     # 展开一个命令分组
-dws schema "calendar event create"              # 按 CLI 空格路径查询工具
-dws schema calendar.create_calendar_event       # 按 canonical path 查询工具
-dws schema --cli-path "calendar event create"   # 显式 CLI path
-dws schema "calendar event create" --compact    # 支持：省略 provenance/debug 字段
+dws schema calendar --compact                   # Agent 产品视图
+dws schema "calendar event" --compact          # Agent 分组视图
+dws schema "calendar event create" --compact   # Agent leaf（CLI 空格路径）
+dws schema calendar.create_calendar_event --compact     # Agent leaf（canonical path）
+dws schema --cli-path "calendar event create" --compact # Agent leaf（显式 CLI path）
+dws schema "calendar event create"             # full leaf，仅用于映射/provenance 审计
 dws schema --all                                # 全部工具的完整 leaf Schema，用于审计/CI/baseline
 ```
 
 兼容入口 `dws schema list` 等价于根概览。`schema --all` 是完整导出：每个工具都包含完整 leaf 参数、约束和安全语义。它输出很大，只用于明确要求的全量导出、审计、CI 或参数 baseline；普通 Agent 任务应按概览、产品/分组、leaf 渐进查询，不要把 `--all` 直接注入上下文。`schema --all --compact` 虽受支持，但会裁掉 provenance 和接口映射字段，不能作为完整 baseline。
 
-Leaf 查询、`--all` 中对应工具和 Catalog full tool 均由同一个 resolved `ToolSpec` 投影，内容必须一致；概览、产品/分组和 Catalog summary 也由该 `ToolSpec` 的统一 summary 投影生成。通过 alias 查询时，只允许 `cli_path` 和 `is_alias` 发生视图变化，参数、安全和接口契约不得变化。
+省略 `--compact` 的 full leaf、`--all` 中对应工具和 Catalog full tool 均由同一个 resolved `ToolSpec` 投影，内容必须一致；compact leaf 仅做字段白名单投影，不重新解析语义。概览、产品/分组和 Catalog summary 也来自同一 `ToolSpec`。通过 alias 查询时，只允许路径视图发生变化，参数、安全和接口契约不得变化。
 
-`--compact` 是 Schema 的展示选项。当前版本支持该 flag；若兼容旧二进制时收到 `unknown_flag: --compact`，用同一个 Schema 查询去掉 `--compact` 重试。这只降低输出裁剪能力，不表示 leaf 不存在，也不能改用 Schema 查询业务数据。
+`--compact` 是 Schema 的稳定 Agent 字段白名单，也是普通 Agent 查询的规范选项。它保留 CLI 参数、组合约束、选择和安全语义，但有意省略 `interface_ref`、参数 `property/interface_type` 与 provenance。检查这些映射/审计字段时，使用 full leaf 并通过 `--jq` / `--fields` 精确投影。若兼容旧二进制时收到 `unknown_flag: --compact`，用同一个 Schema 查询去掉 `--compact` 重试；这只降低输出裁剪能力，不表示 leaf 缺失。
 
 ### Schema、Help 与业务数据的边界
 
 | 问题 | 事实源 |
 |------|--------|
 | 命令是否由当前二进制暴露、Cobra 接受哪些 flags | `dws <path> --help` |
-| Agent 选哪个命令、参数映射与组合约束、risk/confirmation | 对应的 leaf `dws schema "<path>"` |
+| Agent 选哪个命令、CLI 参数与组合约束、risk/confirmation | 对应的 Agent leaf `dws schema "<path>" --compact` |
+| CLI↔RPC 参数映射、接口绑定与 provenance | full leaf 配合 `--jq` / `--fields` 精确投影 |
 | 当前钉钉中的文档、文件、日程、消息等业务数据 | 实际执行 `dws doc read`、`dws drive search` 等 read/search/list 命令 |
 
 Schema 与 Help 冲突表示发布契约漂移，不能静默猜测。执行参数必须以 Cobra 实际接受的 flag 为准；安全语义冲突时采用更保守的处理（例如先确认）或停止执行并报告漂移。完成命令发现后，仍必须执行真实业务命令；`dws schema` 本身不会读取或搜索业务内容。

docs/robot-quickstart.md

@@ -6,7 +6,7 @@
 
 ## 第一步：安装 dws
 
-一键脚本会自动下载最新版二进制 + `dingtalk-dev` skill，只需要 curl（无需 go / git）。
+一键脚本会自动下载最新版二进制 + `dingtalk-misc` skill（开放平台应用文档落在 misc），只需要 curl（无需 go / git）。
 
 ### macOS / Linux
 

docs/schema-dynamic-endpoint-design.md

@@ -6,17 +6,21 @@ DWS Schema 是当前二进制公开 CLI 的版本化 Agent 执行契约。它描
 
 设计遵循三条硬规则：
 
-1. **Schema 描述 CLI，不制造 CLI。** `CommandRegistry`、manual hint、metadata 和 Catalog 都不能凭空创建 Cobra 命令或 flag；registry 中的每个路径都必须精确绑定真实 runnable Cobra leaf。
+1. **Schema 描述 CLI，不制造 CLI。** `CommandRegistry`、ProductDecl / leaf `Contract`、metadata 和 Catalog 都不能凭空创建 Cobra 命令或 flag；registry 中的每个路径都必须精确绑定真实 runnable Cobra leaf。interface 事实由 leaf `Contract` / `ParamDecl` 声明（`schema_mcp_metadata` 已退役），**不得**从 MCP meta 生成 CLI flag（见 §4.1 同源决策）。
 2. **所有来源只解析一次。** 来源经过统一 resolver 进入 typed `SchemaRegistry`，所有查询、导出和门禁都消费同一个 `SchemaRegistry/SchemaIndex`。
-3. **Registry-first，Catalog 只出不进。** reviewed `CommandRegistry` 是稳定 command identity/navigation 的唯一事实源；`schema_catalog/`（`catalog.json` + 每产品 `tools/<product>.json`）和其他生成 JSON 只是下游发布物，不能成为命令、metadata 或下一轮 Catalog 的来源。运行时 production loader 解码 embedded snapshot 只是交付边界，不是 source resolution。
+3. **Collector-first，Catalog 只出不进。** identity collector（`CollectIdentitySpecs`，遍历携带 `ContractFinal.Identity` 的 live Cobra leaves）是稳定 command identity/navigation 的唯一事实源；reviewed `schema_command_registry/` 已退役，identity 由声明（Contract）即代码提供，不再有独立的 reviewed identity 文件。production 通过 `RegisterSchemaSourceRoot` → `ResolveSchemaBuild` 组装 `SchemaRegistry`，并从它投影 ToolSpec wire 与 `ResolveMeta`。`cmd_schema_catalog` 只能生成 CI/local dump，`internal/cli/schema_catalog/`、`schema_meta_index.gob` 和 `schema_meta_index.json` 不得提交或成为运行时来源。`schema_agent_metadata/` / `schema_hints/` / `schema_command_registry/` 已退役；若存在则 policy 失败。生产 Agent selection / safety / interface 权威为 leaf `ContractFinal` 与 `ProductDecl`；`agent_metadata_inject.go` / `InstallBuildTimeAgentMetadataJSON` 仅作 `cmd_schema_catalog` CI/local dump 辅助，不得作为生产权威。
 
 Schema 不调用 MCP `tools/list`，不访问网络，也不读取用户本地 discovery cache。
 
+**flag / help / schema 参数面同源**（已决策）：Contract / LeafSpec 为 CLI 表面权威；分层字段归属与门禁 ID 见 [`flag-help-schema-homology.md`](flag-help-schema-homology.md)。
+
 ## 2. 单向数据流
 
 ```text
-schema_command_registry.json           (reviewed CommandRegistry source)
-  + reviewed manual command additions
+identity collector (CollectIdentitySpecs)
+  walks live Cobra leaves carrying ContractFinal.Identity;
+  reviewed exclusions applied; single identity source
+  (reviewed schema_command_registry/ retired)
                          |
                          v
              EffectiveCommandRegistry
@@ -28,26 +32,13 @@ schema_command_registry.json           (reviewed CommandRegistry source)
                          v
                BoundCommandRegistry
                          |
-                         +----------------------+
-                                                |
-skills/mono Markdown + internal/cli/schema_hints/*.json |
-  + schema_mcp_metadata.json                     |
-                         |                       |
-                         v                       |
-             Agent-metadata normalization       |
-                         |                       |
-                         v                       |
-             schema_agent_metadata/*.json       |
-               (generated normalized input)     |
-                         |                       |
-                         +-----------------------+
-                         |
+                         v
 live Cobra flag facts / typed parameter metadata
-  + schema_hints/metadata/*.json      (reviewed parameter overlay + safety)
-  + schema_hints/selection/*.json     (reviewed Agent selection prose)
-  + schema_parameter_bindings.json    (reviewed flag -> RPC property)
-  + schema_mcp_metadata.json          (pinned, sanitized interface facts)
-  + normalized Agent metadata
+  + leaf Contract (Safety / ContractDecl / ParamDecl → contract_final)
+  + ProductDecl (product routing prose; production Agent authority)
+  + schema_parameter_mapping_ledger.go (reviewed mapping exclusions / removals)
+  + leaf Contract.Interface / ParamDecl (declared interface facts)
+  + skills/mono Markdown              (evidence only; not concatenated)
                          |
                          v
               source adapters + resolvers
@@ -60,18 +51,14 @@ live Cobra flag facts / typed parameter metadata
              +-----------+-----------+
              |                       |
              v                       v
-     build-time typed gates    snapshot serializer
-                                     |
-                                     v
-                              schema_catalog/
-                              (catalog.json + tools/<product>.json,
-                               release output only)
-                                     |
-                                     v
-                           go:embed -> typed loader
+     build-time typed gates   RegisterSchemaSourceRoot
+                              -> ResolveSchemaBuild
+                              (runtime assembly; lazy Once)
                                      |
                                      v
                          SchemaRegistry + SchemaIndex
+                         + ResolveMeta projection cache
+                           (in-process map; not gob/json fixture)
                                      |
                +---------------------+------------------+
                |                     |                  |
@@ -82,9 +69,12 @@ live Cobra flag facts / typed parameter metadata
                                      |
                                      v
                          runtime query + delivery gates
+                         (cmd_schema_catalog = CI/local dump only;
+                          InstallBuildTimeAgentMetadataJSON = dump helper,
+                          not production Agent authority)
 ```
 
-`--help` 是 Cobra 自身的人类可读投影，不从 Catalog 生成。Schema projections 和 `--help` 共享同一真实 Cobra 命令面，但承担不同职责。Binder 之后不得再从 annotation、manual hint 或生成 JSON 重新解析 command identity。
+`--help` 是 Cobra 自身的人类可读投影，不从 Catalog 生成。Schema projections 和 `--help` 共享同一真实 Cobra 命令面，但承担不同职责。Binder 之后不得再从 annotation、已退役 hint overlay 或生成 JSON 重新解析 command identity。
 
 ## 3. 与 Lark 的关系
 
@@ -95,8 +85,10 @@ DWS 与 Lark 保持**架构同构**，而不是强行复制字段：
 | typed command/metadata registry | `EffectiveCommandRegistry`、`BoundCommandRegistry` 与最终 `SchemaRegistry` |
 | navigation catalog/index | 从同一 `ToolSpec` 派生的 `SchemaIndex` |
 | schema renderer/envelope | overview、product/group、leaf、`--all` projections |
+| API Commands ← 平台 OAPI meta | **不**作为 DWS 主路径；可选 1:1 MCP 透传子集见同源文档 §5 |
+| Shortcuts ← 手写声明 + Execute | LeafSpec / Shortcut + Contract 表面（路径 A） |
 
-共同点是：强类型 registry 持有已审核、已绑定、已解析的事实，index 只负责确定性导航，renderer 只投影，不重新读取来源或做 precedence。DWS 的 base Registry 与 reviewed manual command additions 在绑定前合并为唯一的 `EffectiveCommandRegistry`，因此不存在 “native-first”、“legacy registry fallback” 或 Catalog fallback。
+共同点是：强类型 registry 持有已审核、已绑定、已解析的事实，index 只负责确定性导航，renderer 只投影，不重新读取来源或做 precedence。DWS 的 identity collector 从携带 `ContractFinal.Identity` 的 live Cobra leaves 收集 identity，绑定前生成唯一的 `EffectiveCommandRegistry`（reviewed `schema_command_registry/` 已退役），因此不存在 “native-first”、“legacy registry fallback” 或 Catalog fallback。飞书也是**分层单权威**（API 用平台 meta，Shortcut 用手写契约），不是全家只有 meta——DWS 对齐的是这一分层，而不是「用 MCP meta 生成全部 CLI」。
 
 DWS 内部 resolved model 为：
 
@@ -121,26 +113,38 @@ DWS 当前对外仍保留兼容 wire：leaf 使用 flat `parameters`，安全和
 
 | 来源 | 负责内容 | 明确不负责 |
 |---|---|---|
-| `schema_command_registry.json` | reviewed `CommandRegistry`：稳定 canonical identity、primary CLI path、alias、exposure 和导航 | 创建 Cobra 命令/flag、参数、安全、endpoint/token |
-| reviewed manual command additions | 将一个精确存在的 runnable Cobra leaf 合并进 `EffectiveCommandRegistry`；必须 reviewed 且带 reason | 运行时 fallback、覆盖冲突 identity、创建命令 |
-| Go/Cobra | 路径是否真实可执行、Cobra 接受的 flag、CLI 类型/默认值、执行校验、help 文本 | 稳定 canonical identity、Agent 场景选择、虚构 RPC |
+| Contract / LeafSpec / `corecmd.Spec` | **CLI 表面权威**：flags、defaults、required、enum、关系约束、运行时 Risk；编译为 cobra 与 help | canonical identity、selection 文案、虚构 RPC |
+| identity collector（`CollectIdentitySpecs`） | 从 live Cobra leaves 的 `ContractFinal.Identity` 声明收集稳定 canonical identity、primary CLI path、alias、exposure 和导航（reviewed `schema_command_registry/` 已退役） | 创建 Cobra 命令/flag、参数、安全、endpoint/token |
+| reviewed exclusions（`ReviewedRuntimeSchemaExclusions`） | exact、reviewed、带 reason 地将指定 public runnable leaf 排除出 effective 表面 | 运行时 fallback、prefix/wildcard 排除、创建命令 |
+| Go/Cobra | Contract 编译后的可执行投影：路径是否真实可执行、Cobra 接受的 flag、DefValue、help 文本 | 稳定 canonical identity、Agent 场景选择、虚构 RPC；**不得**成为与 Contract 平行的第二套 flag 权威 |
 | native Schema identity annotations | implementation-side consistency evidence；存在时必须与 `EffectiveCommandRegistry` 精确一致 | 提供、补全、推断或覆盖 identity |
-| `schema_hints/metadata/*.json` parameter overlays | 精确覆盖现有 flag 的描述、映射、类型和 required 语义；并承载 safety / `runtime_gate` / interface | 创建命令/flag、绕过 completeness、虚构 RPC |
-| typed parameter metadata / constraints | `required_when`、one-of、互斥、联动、格式、枚举、位置参数 | 命令 identity |
-| `schema_parameter_bindings.json` | 稳定 CLI flag 到 RPC property 的映射 | 命令发现、risk 推断 |
-| `schema_mcp_metadata.json` | pinned RPC identity、接口描述和脱敏参数事实 | CLI identity、运行时路由、risk 推断 |
-| `schema_hints/selection/*.json` | reviewed selection prose（summary / use_when / avoid_when / examples） | 创建 Cobra 命令或参数、改写 safety |
+| typed parameter metadata / constraints | 由 Contract 约束投影而来的 `require_one_of` / 互斥等；以及仍需 reviewed 的 `required_when` 等 | 命令 identity |
+| `schema_parameter_mapping_ledger.go` | CLI flag 无直接 RPC property 的 exclusions / removals | 命令发现、risk 推断、创建 CLI flag；property 交付归 ParamDecl.Property |
+| leaf `Contract.Interface` / `ParamDecl` | 声明的 RPC identity 与 interface_* 事实（`schema_mcp_metadata.json` 已退役） | CLI identity、运行时路由、**创建 CLI flag**、risk 推断 |
+| ProductDecl + leaf `Contract.Selection` | reviewed selection / product routing prose（`contract_final`） | 创建 Cobra 命令或参数、改写 safety；`schema_hints/` 已退役 |
 | Skills/Markdown | 产品路由、工作流和使用建议 | 命令存在性和 flag 事实 |
-| `schema_catalog/`（catalog.json + tools/<product>.json）及其他 generated JSON | resolved registry 的兼容发布序列化；运行时由 production loader 解回 typed registry/index | generation/source resolution 输入、identity fallback、手工修复源 |
+| `cmd_schema_catalog` CI/local dump（可选 `schema_catalog/` / meta-index） | resolved registry 的兼容序列化快照，仅供 jq/determinism；不得提交为 runtime 来源 | production delivery、`ResolveMeta` 权威、identity fallback、手工修复源 |
 
-`schema_command_registry.json` 承载 reviewed `CommandRegistry`。Manual command addition 先以确定性规则合并进 effective registry；从 binder 开始，下游只看到一个稳定 identity/navigation 模型。旧 wire 中的 `surface_hash` / `surface_tools` 字段仅为兼容名称，语义已经是 effective Registry hash/coverage，不构成第二事实源。
+identity collector 从 live Cobra leaves 的 `ContractFinal.Identity` 声明生成 `CommandSpec`，应用 reviewed exclusions 后按确定性规则索引为 effective registry；从 binder 开始，下游只看到一个稳定 identity/navigation 模型。reviewed `schema_command_registry/` 已退役，其历史角色（稳定 canonical identity/navigation 事实源）由 collector 承接。旧 wire 中的 `surface_hash` / `surface_tools` 字段仅为兼容名称，语义已经是 effective Registry hash/coverage，不构成第二事实源。
+
+### 4.1 flag / help / schema 同源（路径 A + 嵌入）
+
+完整决策、字段归属表、`HOM-*` 门禁规划与可选 MCP 透传准入条件见 [`flag-help-schema-homology.md`](flag-help-schema-homology.md)。
+
+摘要：
+
+- **同源面**：Contract → cobra flags ≡ `--help` Flags ≡ **嵌入注解后的** schema `parameters` / 关系约束；显式 `Risk` 经 `dws.schema.risk` overlay 进 Schema Safety。
+- **嵌入点**：`command.embedContractIntoSchema` 写入 `dws.schema.contract` / property / type / required；`AnnotateConstraints` 写入 constraints；Schema 组装（`runtimeToolSpecFromMetadata` / `ResolveSchemaBuild`）消费这些注解进入 typed `SchemaRegistry`（runtime assembly；非 `go:embed` catalog 交付）。
+- **硬规则**：CLI 表面事实 = **声明（Contract 数据字段）OR 人工标注**；禁止纯推断。非 CLI 表面字段（identity / selection / interface）必须有**评审源**。声明写法见同源文档 §1.2；标注见 §1.3；**`ToolSpec` 全字段权威见 RFC §5.0.4 / 同源 §1.4**。
+- **非同源面（有意）**：identity（collector）、selection 文案（ProductDecl / leaf `Contract.Selection`）、RPC 形状（MCP meta 仅 `interface_*`）、dry-run 正能力 registry。
+- **禁止**：以 MCP meta 为主通道生成 Leaf/Shortcut 的 flag；已退役的 hint overlay 改写 type/required/default；Schema 字段无权威归属。
 
 ## 5. 统一解析与 precedence
 
 ### 5.1 Identity
 
-- Reviewed base `CommandRegistry` 是 stable canonical identity、primary path、alias 和 navigation 的唯一基础事实源。
-- Reviewed manual command addition 只能引用精确存在的 runnable Cobra leaf；它在绑定前合并进 `EffectiveCommandRegistry`。若与 base Registry 的 identity/path/alias 冲突，生成失败，不能按 precedence 静默覆盖。
+- identity collector（`CollectIdentitySpecs`）是 stable canonical identity、primary path、alias 和 navigation 的唯一基础事实源：每个携带 `ContractFinal.Identity` 的 runnable Cobra leaf（含 Hidden deprecated/migration shims）贡献一条 identity，reviewed exclusions 精确应用；reviewed `schema_command_registry/` 已退役，其历史角色由 collector 承接。
+- Collector 输出的 `CommandSpec` 在索引时 fail-closed 校验 canonical/product/path/alias/visibility 的合法性与唯一性；重复 identity、alias 复用 primary path 或 alias collision 全部失败，不能按 precedence 静默覆盖。
 - Binder 必须把 effective entry 的 primary path 和每个 alias 精确解析到同一个真实 executable leaf；stale path、phantom path、重复 identity 或 alias collision 全部失败。
 - Native identity annotation 是可选的一致性证据：存在时必须与 effective entry 精确一致；缺失不触发补写、推断或 fallback。
 - Public runnable Cobra leaf 未进入 effective registry 时，必须存在 exact、reviewed、带 reason 的 exclusion；不得用 prefix/wildcard 排除。
@@ -154,30 +158,35 @@ DWS 当前对外仍保留兼容 wire：leaf 使用 flat `parameters`，安全和
 constraint、Cobra help 和 interface resolver 提供，因此删除该过渡层没有数据迁移缺口。
 CI 同时禁止重新加入 generated native contracts 或 materialization 入口。
 
-#### CommandRegistry 输入审计
+#### Identity 输入审计（registry 已退役）
 
-`schema_command_registry.json` 是 reviewed source，不是生成快照。它必须保留
-`$schema: ./schema_command_registry.schema.json`。该 JSON Schema 对 root、product
-和 CommandSpec 全部使用 `additionalProperties: false`，并约束：
+历史上 identity 来自 reviewed `schema_command_registry/`（`registry.json` +
+`products/*.json`，由随附 JSON Schema 校验）。该 reviewed registry 已退役，
+改由 identity collector 承接：identity 现在由 `CollectIdentitySpecs` 从 live
+Cobra 树的 `ContractFinal.Identity` 声明收集，输入契约即声明本身。严格 Go
+索引（`indexCommandSpecs`）继续 fail-closed 校验：
 
 - canonical identity、`source_product_id` 和精确 CLI path 的格式；
 - `aliases` 唯一且不能复用 primary path；
 - `visibility` 只允许 `public | compat | internal`，省略时明确归一化为
   `public`；
-- primary path、alias、canonical 和 product 之间无法由 JSON Schema 表达的
-  交叉约束，继续由 Go strict loader 和 Cobra binder fail-closed 校验。
+- primary path、alias、canonical 和 product 之间的交叉唯一性约束。
 
-Registry semantic hash 覆盖 canonical、primary CLI path、alias 集合、
+Registry semantic hash 仍覆盖 canonical、primary CLI path、alias 集合、
 `source_product_id` 和 normalized visibility。格式、顺序以及省略的等价默认值
 不改变 hash；上述任一稳定契约字段变化都必须改变 hash。测试逐字段验证这一点，
 不使用当前命令数量作为常量。
 
-普通 `go generate ./internal/cli` 只把 Registry 作为 validation-only 输入并生成
-Agent metadata/Catalog 等单向下游资产，不生成或覆盖 Registry。drift policy 在生成
-前后对 reviewed Registry 做 byte-for-byte guard；独立的
-`check-schema-command-registry.sh` 在 interface/provenance/Catalog policy 之前检查
-JSON 输入契约、禁用旧 native materialization 符号，并从 Registry 动态计算审计
-数量，不能硬编码某次快照的 tool count。
+普通 `go generate ./internal/cli` 只生成
+`param_aliases_generated.go`；production Catalog / `ResolveMeta` 由 runtime
+`ResolveSchemaBuild` 装配（`deliverySchemaCatalog` Once 后缓存 Meta 投影）。
+`cmd_schema_catalog` 仅按需打 CI/local dump；其 `InstallBuildTimeAgentMetadataJSON`
+inject 仅服务 dump，生产 Agent 权威仍是 leaf `ContractFinal` / `ProductDecl`。
+不写也不 embed `schema_agent_metadata/`。drift policy 禁止已退役的
+`schema_command_registry/` 在生成前后重新出现；原独立脚本
+`check-schema-command-registry.sh` 的 registry-agnostic side guards（禁用旧
+native materialization 符号、go:generate 单轨、lazy loader 纪律）已迁入
+`check-schema-catalog.sh`。
 
 ### 5.2 Parameter
 
@@ -186,15 +195,17 @@ JSON 输入契约、禁用旧 native materialization 符号，并从 Registry
 实现中的参数字段顺序固定为：
 
 ```text
-reviewed manual > versioned binding > command constraint > typed metadata
-                > native/Cobra contract > ToolSchemaHint > MCP metadata
-                > inference/default
+versioned binding > command constraint > typed metadata
+                > native/Cobra contract (ParamDecl / ContractFinal)
+                > MCP metadata > inference/default
 ```
 
 命令 `title` / `description` 使用独立但同样确定的文本顺序：
 
 ```text
-reviewed ToolSchemaHint > command-specific Cobra Help > MCP metadata > inference
+description: Cobra Long > ContractDecl description (contract_final) > MCP metadata > inference
+             (Long 胜出时 provenance = cobra_help / cobra_help_preferred)
+title:       ContractDecl / ContractFinal > Cobra Short > MCP metadata > inference
 ```
 
 因此多个 CLI leaf 复用同一个 RPC 时，通用 RPC 文案只能作为未选中的
@@ -220,7 +231,8 @@ Cobra hard-required 是独立的 executable fact，并通过 `cli_required`/prov
 | 问题 | 事实源 |
 |---|---|
 | 当前二进制是否暴露命令、Cobra 接受哪些 flags | `dws <path> --help` |
-| Agent 选哪个命令、参数映射/required/约束、risk/confirmation | 对应 leaf `dws schema "<path>"` |
+| Agent 选哪个命令、CLI 参数/required/约束、risk/confirmation | Agent leaf `dws schema "<path>" --compact` |
+| CLI↔RPC 参数映射、接口绑定、provenance | full leaf 配合 `--jq` / `--fields` 精确投影 |
 | 钉钉中的文档、文件、日程、消息等实际数据 | 真正执行 `dws doc read`、`dws drive search` 等 read/search/list 命令 |
 
 Schema 和 Help 冲突是契约漂移，不能静默猜测：
@@ -235,10 +247,10 @@ Schema 和 Help 冲突是契约漂移，不能静默猜测：
 
 ```bash
 dws schema                                      # 产品紧凑概览
-dws schema calendar                             # 产品摘要
-dws schema "calendar event"                    # 分组摘要
-dws schema "calendar event create"             # 完整 leaf
-dws schema "calendar event create" --compact   # 支持：裁掉 provenance/debug 字段
+dws schema calendar --compact                   # Agent 产品摘要
+dws schema "calendar event" --compact          # Agent 分组摘要
+dws schema "calendar event create" --compact   # Agent leaf
+dws schema "calendar event create"             # full leaf，仅用于映射/provenance 审计
 dws schema --all                               # 所有工具的完整 leaf 导出
 ```
 
@@ -246,37 +258,30 @@ dws schema --all                               # 所有工具的完整 leaf 导
 
 `schema --all` 必须包含最终 `SchemaIndex` 中每个 tool 的完整 leaf 参数、约束和安全语义；无业务参数的命令也要包含空 `parameters` 对象。它用于审计、CI 和参数防丢 baseline，但输出很大，普通 Agent 命令发现不得使用，应按 overview -> product/group -> leaf 渐进查询。
 
-`--compact` 当前受支持，适合减少常规 leaf 查询上下文。`schema --all --compact` 也可执行，但会移除 provenance/debug 和接口映射字段，不能作为完整兼容性 baseline。
+`--compact` 是普通 Agent 查询的规范视图：通过正向字段白名单保留选参、约束与安全语义，full 新增字段不会自动进入 Agent 上下文。省略它的 leaf 包含参数 property、接口绑定和 provenance，只用于定向审计；`schema --all --compact` 也可执行，但不能作为完整兼容性 baseline。
 
 兼容旧二进制时，如果 Schema 查询返回 `unknown_flag: --compact`，只去掉 `--compact` 重试同一个查询。这是展示能力降级，不代表 leaf 缺失，也不能改用 Schema 查询业务数据。
 
 ## 8. 生成与发布
 
-当 Cobra、flag、identity、binding、manual hint、Agent hint 或 Skill 发生变化时：
+当 Cobra、flag、identity、binding、leaf `Contract` / ProductDecl 或 Skill 发生变化时：
 
-1. 审核真实 Cobra 变化，确认命令和 flag 已实际存在。新增或修改稳定 command identity、primary CLI path 或 alias 时，精确编辑 reviewed `CommandRegistry`（当前持久化文件为 `schema_command_registry.json`）。参数、Skill 或 metadata 单独变化时不要机械改写 Registry，也不要从旧 Catalog 反向生成它。
-2. 仅对明确例外使用 reviewed manual command addition；它必须精确引用现有 runnable leaf、带 reason，并在生成时归一化进 `EffectiveCommandRegistry`。Native identity annotation 若存在，应作为与 Registry 一致的实现断言维护，而不是用来 materialize identity。
-3. 生成 Agent metadata：
-
-   ```bash
-   make generate-schema-agent-metadata
-   ```
-
-4. 从统一 typed registry 生成最终 Catalog：
+1. 审核真实 Cobra 变化，确认命令和 flag 已实际存在。新增或修改稳定 command identity、primary CLI path 或 alias 现在通过 leaf Contract 的 `ContractFinal.Identity` 声明完成（identity collector 据此收集；reviewed `schema_command_registry/` 已退役）。参数、Skill 或 metadata 单独变化时不要机械改写 identity 声明，也不要从旧 Catalog 反向生成它。
+2. 不应进入稳定 Agent 契约的 public runnable leaf 使用 reviewed exclusions（exact path、带 reason）。Native identity annotation 若存在，应作为与 identity 声明一致的实现断言维护，而不是用来 materialize identity。
+3. 生成参数别名并验证运行时 Schema 组装。`go generate ./internal/cli` 只运行 `cmd_param_aliases`；`cmd_schema_catalog` 仅按需生成 CI/local dump。生产权威为 leaf `ContractFinal` / `ProductDecl`；CI dump 可经 `agent_metadata_inject.go` / `InstallBuildTimeAgentMetadataJSON` 在内存中注入 Agent metadata，不写 `schema_agent_metadata/`：
 
    ```bash
+   make generate-schema
+   go generate ./internal/cli
+   # 可选：生成 artifacts/ 下的 CI/local dump
    make generate-schema-catalog
    ```
 
-也可以运行 `go generate ./internal/cli` 生成正常发布资产。生成文件包括：
+`cmd_schema_agent_metadata` 可保留为非交付工具/测试，但不是 `go:generate` 入口，也不应再作为发布步骤。
 
-- `internal/cli/schema_agent_metadata/index.json`
-- `internal/cli/schema_agent_metadata/<product>.json`
-- `internal/cli/schema_agent_metadata_audit.json`
-- `internal/cli/schema_catalog/catalog.json`（全局信封 + Catalog）
-- `internal/cli/schema_catalog/tools/<product>.json`（每产品 leaf ToolSpecs，按产品分片以免并发 PR 冲突）
+生成文件只有 `internal/cli/param_aliases_generated.go`（参数别名生成物）。`cmd_schema_catalog` 的 Catalog 和 meta-index 是可选 CI/local dump，不是交付物，且不得写入或提交到 `internal/cli/`。
 
-只编辑来源；不要手工编辑 Agent metadata 或 Catalog 输出。
+`schema_agent_metadata/`、`schema_agent_metadata_audit.json` 与 `schema_hints/` 已退役；若存在则 policy 失败。只编辑来源；不要手工编辑或提交 Catalog / meta-index dump。
 
 ## 9. Completeness 与 final-delivery invariant
 
@@ -284,19 +289,19 @@ dws schema --all                               # 所有工具的完整 leaf 导
 
 - 每个 public runnable Cobra leaf 要么能通过最终 embedded `SchemaIndex` 查询，要么有 exact、reviewed、带 reason 的 exclusion。
 - 每个最终 canonical path、primary CLI path 和 alias 都必须解析到同一个可执行 leaf；不得有 phantom path 或 collision。
-- `EffectiveCommandRegistry`、`SchemaRegistry/SchemaIndex`、Agent metadata 和 Catalog canonical sets 必须精确一致，不能只比较 count。
+- `EffectiveCommandRegistry`、`SchemaRegistry/SchemaIndex` 与 Catalog canonical sets 必须精确一致（含组装时内存 inject 的 Agent metadata 语义），不能只比较 count。
 - Leaf payload、`--all` 中对应 tool 和 Catalog full tool 必须是同一个 resolved `ToolSpec` 的内容级等价投影，并通过 production loader round-trip。
 - overview/product/group summary 与 Catalog summary 必须等于同一个 `ToolSpec.ToSummaryPayload()`；alias 查询只允许 `cli_path` 和 `is_alias` 这两个视图字段变化。
 - 每个最终字段及 parameter field 的 provenance winner value 必须与 delivered value 精确一致；不能只验证 provenance source、count 或字段是否存在。
 - 每个 MCP `interface_ref` 必须在 pinned interface registry 精确存在；local/composite/unavailable 必须满足同一 conflict matrix。
 - `--all` 的 tool set 必须与最终 index 一对一，且每个工具包含完整参数契约。
 - 连续两次生成必须字节稳定，提交的生成物不得漂移。
+- **同源门禁（规划，见同源文档 §4）**：受管命令逐步满足 `HOM-P1`–`P3`（parameters ≡ cobra/Contract）、`HOM-S1`–`S3`（Safety/Risk 对齐）、`HOM-I1`（interface 不创建 flag）、`HOM-D1`（help ≡ schema parameters）。hints 不得作为 type/required/default 的 winner。
 
 推荐本地验证：
 
 ```bash
-make generate-schema-agent-metadata
-make generate-schema-catalog
+make generate-schema
 ./scripts/policy/check-generated-drift.sh
 ./scripts/policy/check-schema-catalog.sh
 go test ./internal/cli ./internal/app ./internal/generator/... -count=1
@@ -306,8 +311,12 @@ go test ./internal/cli ./internal/app ./internal/generator/... -count=1
 
 - 运行时调用 MCP `tools/list` 或访问网络生成 Schema。
 - 从 `schema_catalog/` 等生成 JSON 反向创建/补齐 Cobra leaf、flag、CommandRegistry 或下一轮 Catalog。
+- 重新引入 `schema_agent_metadata/`（或 audit JSON）作为交付物、`go:embed` 目标，或把它写回 `go:generate` 入口。
+- 从 MCP meta / 已退役的 `schema_mcp_metadata` **生成或补齐** LeafSpec/Shortcut 主路径的 CLI flag（interface overlay 除外）；未满足同源文档 §5 准入条件时启用「MCP 透传生成通道」。
 - 把 native annotation、legacy registry 或 Catalog 当作 identity fallback；或在 `EffectiveCommandRegistry` 之后再次选择 identity winner。
 - renderer、query 或 gate 在 `SchemaRegistry` 之后重新读取 source 并做第二次 merge。
 - 用 prefix/wildcard exclusion 隐藏未来命令。
-- 让 manual hint、CommandRegistry 或 interface metadata 宣称一个不存在的命令、flag 或 RPC 可用。
+- 让 ProductDecl / leaf `Contract`、CommandRegistry 或 interface metadata 宣称一个不存在的命令、flag 或 RPC 可用。
+- 重新引入 `schema_hints/`（含 selection/metadata/imported/audit JSON）或任何 HintFile overlay，并在与 Contract/cobra 冲突时赢得 type/required/default。
 - 把 `schema --all` 当作普通业务数据查询，或把其完整结果无条件注入 Agent 上下文。
+- 将 LeafSpec、`+shortcut` 或 write-guard/cursor/多步命令注册为 `mcp_passthrough` 表面。

docs/shortcut-lark-alignment.md

@@ -63,23 +63,24 @@
 |---|:---:|---|
 | covered-1to1 | 144 | lark 组合在钉钉塌缩成 1:1，封装层已覆盖 |
 | no-dingtalk-tool | 127 | 钉钉无对应工具，客观不可对齐 |
-| **gap-buildable** | **42** | 钉钉有工具、值得补成智能 shortcut（**建设目标**）；已建 minutes `+detail`/`+replace-batch`、base `+record-share-links`/`+resolve-base`、im `+thread-replies`/`+chat-messages`、task `+related-tasks` |
-| covered-smart | 48 | 已建智能 shortcut / 部分覆盖 |
+| **gap-buildable** | **41** | 钉钉有工具、值得补成智能 shortcut（**建设目标**）；已建 minutes `+detail`/`+replace-batch`、base `+record-share-links`/`+resolve-base`、im `+thread-replies`/`+chat-messages`/`+chat-list`、task `+related-tasks` |
+| covered-smart | 49 | 已建智能 shortcut / 部分覆盖 |
 
-## 🎯 gap-buildable 目标清单（原 49 条，已建 7 → 剩 42，按服务）
+## 🎯 gap-buildable 目标清单（原 49 条，已建 8 → 剩 41，按服务）
 
-> 已落地：minutes `+detail`（✅ smart `+detail`）、minutes `+word-replace`（✅ smart `+replace-batch`，批量+去重）、base `+record-share-link-create`（✅ smart `+record-share-links`，>20 去重+分片+合并）、im `+threads-messages-list`（✅ smart `chat +thread-replies`，list_topic_replies + 投影）、task `+get-related-tasks`（✅ smart `todo +related-tasks`，三角色并集+去重+投影）。
+> 已落地：minutes `+detail`（✅ smart `+detail`）、minutes `+word-replace`（✅ smart `+replace-batch`，批量+去重）、base `+record-share-link-create`（✅ smart `+record-share-links`，>20 去重+分片+合并）、im `+threads-messages-list`（✅ smart `chat +thread-replies`，list_topic_replies + 投影）、im `+chat-list`（✅ smart `chat +chat-list`）、task `+get-related-tasks`（✅ smart `todo +related-tasks`，三角色并集+去重+投影）。
 
-### im → chat（6）
+### im → chat（7）
 
 | lark 命令 | risk | 保真度差距（钉钉有 tool，缺什么智能） |
 |---|---|---|
-| `+chat-list` | read | dws 有 list-my-groups/list-all-conversations 原子 tool，但无 types 枚举+bot剥p2p降级、无 exclude-muted 客户端过滤、无字段投影 |
-| `+chat-messages-list` ✅ | read | **已建 smart `chat +chat-messages`**：群/单聊 list_conversation_message_v2 / list_individual_chat_message 互斥 + sender/text/time 投影。剩余未做：reactions 富化、资源下载 |
-| `+chat-search` | read | dws 无群名模糊搜索v2对应 tool(search_common_groups/find 语义不同)，缺 query规范化、mode映射、mute过滤、meta投影 |
+| `+chat-list` ✅ | read | **已建 smart `chat +chat-list`**：`list_all_conversations` + 默认仅群聊 + `--types group/p2p` + `--exclude-muted` + page-size/page-token 别名 + `--page-all/--page-limit` 数字 cursor 自动翻页、跨页去重、合并后类型过滤和完整性 ledger。剩余未做：sort/sort-type、bot 身份 p2p 剥离（DWS 无对应身份模型） |
+| `+chat-messages-list` ✅ | read | **已建 smart `chat +chat-messages`**：群/单聊互斥解析、时间范围、asc/desc、时间边界全量翻页、reaction、资源下载与完整性 ledger |
+| `+chat-search` ✅ | read | **已建 smart `chat +chat-search`**：真实 `search_groups` 关键词搜索 + page-size/page-token 别名 + `--page-all/--page-limit` 不透明 cursor 自动翻页、跨页去重和完整性 ledger。Lark v2 的 member/type/mode/manager/sort 过滤没有可验证的钉钉对应参数，未伪造 |
+| `+flag-list` ✅ | read | **已建 smart `chat +flag-list`**：真实 `list_message_favorites` 的 `items + hasMore + 数字 nextCursor`，支持 page-size/page-token、`--page-all/--page-limit`、跨页去重和完整性 ledger；仅对齐 message favorite，不模拟 Lark Feed thread flag |
 | `+messages-resources-download` | write | dws download-media 走 get_resource_download_url 拿URL，缺分片Range下载/重试/扩展名推断/安全落盘路径校验 |
-| `+messages-search` | read | dws 有 search_messages_by_keyword/by_time_range/by_sender/at_me 多个原子 tool，但各自单点，缺统一多维filter编排+mget+chat上下文富化+跨字段Validate |
-| `+threads-messages-list` ✅ | read | **已建 smart `chat +thread-replies`**：list_topic_replies + sender/text/time 投影。剩余未做：reactions 富化、资源下载 |
+| `+messages-search` ✅ | read | **已建 smart `chat +search-msg`**：统一多维过滤、精确时间范围、asc/desc、cursor 全量翻页、mget 富化、reaction、资源下载与完整性 ledger。剩余差异是 Lark chat 上下文和部分 sender/attachment 类型过滤 |
+| `+threads-messages-list` ✅ | read | **已建 smart `chat +thread-replies`**：支持主消息 ID 自动只读解析 conversation/thread，也支持显式 group + thread/topic ID；list_topic_replies + sender/text/time/reaction/resource 投影 + 下层毫秒级 nextCursor 有界自动翻页、跨页去重、完整性 ledger，以及全量结果 asc/desc。与 Lark 的剩余差异是钉钉底层没有服务端 asc 单页，因此 DWS 的 asc 明确要求 `--page-all`，避免伪全局排序 |
 
 ### task → todo（3）
 
@@ -176,7 +177,7 @@
 
 ## 已建智能 shortcut（covered-smart，48）— 可继续升级保真度
 
-- **im**: +chat-members-list +messages-send +threads-messages-list
+- **im**: +chat-members-list +chat-list +messages-send +threads-messages-list
 - **task**: +complete +assign +get-my-tasks +get-related-tasks
 - **contact**: +search-user
 - **calendar**: +agenda +create +update +freebusy +suggestion

docs/skill-content-framework.md

@@ -0,0 +1,105 @@
+# DWS Skill 内容框架合同
+
+> 本分支权威合同：`skills/mono` / `skills/multi` 的**内容组织**与 zip 内容树形状。  
+> 不做安装/升级行为约定。质检见 [skill-mono-multi-qa.md](skill-mono-multi-qa.md)。  
+> 对齐调研：[skill-wukong-align-plan.md](skill-wukong-align-plan.md)。
+
+## 1. 两棵内容树
+
+| 树 | 路径 | 角色 |
+|---|---|---|
+| **mono**（单 skill） | `skills/mono/` | 单一 `SKILL.md` 入口 + `references/products/*` 产品面 + 全局协议 |
+| **multi**（多 skill） | `skills/multi/` | 平铺 `dingtalk-*` 产品 skill + 必选 `dingtalk-shared` |
+
+Agent / 安装面选哪棵树由**行为分支**决定；本文件只规定树内合同。
+
+## 2. Multi 目录合同（如何新增一个产品 skill）
+
+新建 `skills/multi/<name>/` 时必须满足：
+
+1. **命名**
+   - 产品 skill：`dingtalk-<product>`（小写、连字符）
+   - 共享 skill：仅允许 `dingtalk-shared`
+2. **根文件**
+   - 必有 `SKILL.md`（YAML frontmatter + 正文）
+   - `references/` 推荐；无 reference 的 skill（如极简 profile）须在质检 omit 表登记
+   - `scripts/` 可选；脚本须被本 skill 树内某 `.md` 引用，或进入 orphan allowlist
+3. **Frontmatter 最小集**（产品 / shared）
+   - `name`：与目录名一致
+   - `description`：非空，含触发意图与边界
+   - `metadata.category`：`product` 或 `shared`（允许历史写法把 `cli_version` 放在 frontmatter 顶层）
+   - `metadata.requires.bins`：含 `dws`
+4. **契约块**
+   - 产品 skill 推荐内嵌 `<!-- DWS_RUNTIME_CONTRACT_START -->…END -->` **或** 明确 PREREQUISITE 指向 `dingtalk-shared`
+   - `dingtalk-shared` 承载跨产品路由与全局协议落点
+5. **与 mono 映射**
+   - 每个 mono `references/products/<stem>`（文件或目录）必须在
+     `skills/content-qa/mono-multi-coverage.yaml` 有 `coverage` 或 `omit_coverage` 行
+
+### 2.1 推荐骨架
+
+```text
+skills/multi/dingtalk-example/
+├── SKILL.md
+├── references/
+│   ├── example.md          # 主产品面
+│   └── …                   # 子章节 / 意图表
+└── scripts/                # 可选；须被 md 引用
+    └── example_helper.py
+```
+
+## 3. Mono 目录合同（质检对照基准）
+
+```text
+skills/mono/
+├── SKILL.md
+├── references/
+│   ├── products/           # 覆盖质检主源
+│   ├── error-codes.md      # 全局协议示例
+│   ├── error-codes.md
+│   └── …
+└── scripts/
+```
+
+- `references/products/` 下每个顶层 stem（`.md` 去后缀或子目录名）计入覆盖索引。
+- 同 stem 的 `.md` + 子目录视为同一产品面（如 `doc.md` + `doc/`）。
+
+## 4. 共享内容（`dingtalk-shared`）
+
+| 职责 | 落点 |
+|---|---|
+| 跨产品路由 / 工作流 | `references/routing.md`、`workflow-routing.md`、`intent-guide.md` |
+| 运行时最小契约长文 | `references/runtime-contract.md`（受 context-budget 约束） |
+| 全局协议（确认门禁 / Schema 教学等） | `references/`；见质检基线 |
+| 与 mono 全局文同名迁移 | `error-codes`、`url-patterns`、`capability-limits`、`channel-login`、`global-reference`、`recipes/`（`conventions.md`、`meta.md`、`lite-catalog.md`） |
+
+产品专属规则（如 AI 表格 `field-rules`）允许下沉到对应 `dingtalk-*`，须在覆盖表注明。
+
+## 5. Zip 内容布局合同（形状，非安装默认）
+
+发布物 `dws-skills.zip`（及 embed 同源）内容树形状：
+
+| Zip 路径 | 含义 |
+|---|---|
+| `<root>/` | mono 内容副本（兼容旧面） |
+| `<root>/mono/` | 与 `skills/mono/` 同构 |
+| `<root>/multi/` | 与 `skills/multi/` 同构 |
+
+质检可断言源树形状；**不**断言安装器默认解压哪棵。
+
+## 6. 与悟空 `dingtalk-skills/` 对照（组织概念 only）
+
+| 维度 | DWS `skills/multi` | 悟空 `dingtalk-skills/`（develop） |
+|---|---|---|
+| 布局 | flat `dingtalk-*` + `dingtalk-shared` | 同构 flat |
+| 集合 | 产品 skill + shared（含 event/profile/…；dev/skill 等长尾落在 misc） | 更小产品集（如 attendance/report 独立目录） |
+| 质检权威 | **mono 单 skill 树** | 不作为 DWS 覆盖基准 |
+| 不移植 | `_install.sh` / bundle / dual / Qwen overlay | — |
+
+悟空独有命名（如 `dingtalk-attendance`）在 DWS 中由 `dingtalk-misc` 承接对应 mono `attendance*` / `report` / `oa` / `sheet` / `dev` 等面——见覆盖表。
+
+## 7. 变更流程
+
+1. 改 / 增内容 → 更新 `skills/content-qa/mono-multi-coverage.yaml`（coverage 或 omit）  
+2. 跑 `make skill-mono-multi-content`（该独立门禁不包含在默认 `make policy` 中）
+3. 失败则修内容或更新 reviewed omit（disposition + 原因），**禁止**用安装默认值绕过  

docs/skill-mono-multi-qa.md

@@ -0,0 +1,76 @@
+# Mono↔Multi Skill 内容质检规格
+
+> 对照基准：`skills/mono`（单 skill）。被测主体：`skills/multi`。  
+> 机读合同：`skills/content-qa/mono-multi-coverage.yaml`。  
+> 执行：`make skill-mono-multi-content`（独立门禁；默认 `make policy` 按设计不包含该检查）。
+
+## 1. 质检矩阵
+
+| ID | 类型 | 输入 | 通过准则 |
+|---|---|---|---|
+| **G1 形状** | 结构 | `skills/multi/*` | 仅 `dingtalk-*`（含必选 `dingtalk-shared`）；每目录有 `SKILL.md` |
+| **G2 结构** | 结构 | 各 `SKILL.md` frontmatter | `name`==目录名；非空 `description`；`category`∈{product,shared}；`requires.bins` 含 `dws` |
+| **G3 覆盖** | 覆盖 | mono `references/products/*` 顶层 stem | 每 stem ∈ `coverage` 或 `omit_coverage`；coverage 目标 skill/refs 存在 |
+| **G4 漂移** | 漂移 | scripts、成对文件、全局协议 | orphan 脚本 ∈ allowlist；paired 内容一致（允许合同声明的布局链接替换）；全局协议存在或 ∈ `omit_global` |
+| **G5 链接** | 可达性 | 合同覆盖的 paired Markdown | 内联相对链接目标文件或目录存在且不逃出仓库；外链、纯锚点和锚点内容不在检查范围 |
+
+已有门禁（继续复用，不替代本矩阵）：`check-skill-commands`、`check-skill-context-budget`、`check-multi-im-skill-chain`、`skill_docs_policy`、whiteboard 成对测试。
+
+## 2. 有意省略 / 延期登记格式
+
+YAML（见 coverage 文件）：
+
+```yaml
+omit_coverage:
+  - mono: simple
+    disposition: covered_by   # covered_by | defer | wontfix
+    via: dingtalk-misc        # optional
+    reason: "拆入 oa/devdoc…"
+
+omit_global:
+  - id: field-rules-global
+    mono_path: references/field-rules.md
+    expected_multi: dingtalk-aitable/references/field-rules.md
+    disposition: covered_by
+    reason: "AI 表格字段规则已下沉到 dingtalk-aitable；G3/coverage 不强制全局同名"
+
+orphan_scripts_allowlist:
+  - path: dingtalk-misc/scripts/report_received_today.py
+    disposition: defer
+    reason: "pending report.md reference"
+
+paired_files:
+  - mono: references/products/sheet.md
+    multi: dingtalk-misc/references/sheet.md
+    mode: link-normalized
+    link_substitutions:
+      - mono: "../url-patterns.md"
+        multi: "../../dingtalk-shared/references/url-patterns.md"
+      - mono: "../intent-guide.md"
+        multi: "sheet-intent-guide.md"
+```
+
+**处置原则**：质检失败 → 修**内容**或更新 reviewed omit；**不**改安装/升级默认。
+
+## 3. 缺口基线（相对 mono）
+
+| ID | 项 | disposition | 说明 |
+|---|---|---|---|
+| M1 | recovery-guide / RECOVERY_EVENT_ID 闭环 | **removed** | 已从 mono/multi skill 文档删除；不做移植 |
+| M2 | confirmation_required 全局协议 | **done** | `dingtalk-shared/references/confirmation.md` + SKILL 导航 |
+| M3 | Schema 渐进查询教学 | **done** | `dingtalk-shared/references/schema-usage.md` |
+| M4 | `report_inbox_today.py` | `defer` / orphan 侧 | 验证后迁 misc 或删 |
+| M5 | multi LICENSE/NOTICE | `defer` | 内容或打包注入 |
+| M6 | aiapp 路由 vs orphan 脚本 | **done（标明未产品化）** | mono 死链移除；`unsupported-scripts.md` |
+| X1 | yida/finance/aiapp orphan scripts | **done（登记）** | 由 unsupported-scripts 具名引用 |
+| X2 | chat 死链 `extract_media_id.py` | n/a | 现仅为反模式提及 |
+| X3 | routing → markdown 错路径 | **done** | 已指 `dingtalk-misc/references/markdown.md`；drive 尾链已修 |
+| X4 | event 缺 metadata | **done** | |
+| X5 | multi skill 横幅 /「优先 mono」文案 | **done** | 横幅已全部移除 |
+| X6 | SAFETY_PREAMBLE_INJECT 无注入器 | **done** | 标记已移除 |
+
+产品面覆盖：见 YAML `coverage`——mono products 均有 multi 承接（misc 聚合 attendance/oa/sheet/…）。
+
+## 4. 与悟空
+
+借鉴 frontmatter / 断链 / requires 等**检查维度**；不运行悟空 bundle zip 校验脚本。覆盖权威始终是 DWS mono。

docs/skill-wukong-align-plan.md

@@ -0,0 +1,272 @@
+# DWS multi-skill **内容框架**对齐方案（相对 dws-wukong develop）
+
+> 状态：**执行中** — Phase 1–3 已落地；M2/M3 已补；**M1 recovery 闭环已从 skill 删除（不做移植）**。  
+> 合同短文：[skill-content-framework.md](skill-content-framework.md)  
+> 质检规格：[skill-mono-multi-qa.md](skill-mono-multi-qa.md)  
+> 机读合同：`skills/content-qa/mono-multi-coverage.yaml`  
+> 门禁：`make skill-mono-multi-content`（独立门禁；默认 `make policy` 按设计不包含该检查）
+>
+> 撰写 / 收窄 / 质检增补 / 执行：2026-08-05  
+> 工作树：`/Users/john/GolandProjects/open-source/dws-multi-skill-align`  
+> 分支：`feat/multi-skill-framework-align`（自 `origin/main` @ `a37e6e68`）  
+> **本分支范围：只做 skill 内容的这个框架**（目录布局、文档契约、共享内容约定、zip 内容树合同、**相对 mono 的内容质检**）。  
+> **不做**安装/升级引擎、agent-home、脚本 skill-install 行为翻转。
+>
+> 对照仓：
+>
+> | 仓 | 路径 | 基线 |
+> |---|---|---|
+> | DWS OSS CLI（本工作树） | `dws-multi-skill-align` | `origin/main` |
+> | dws-wukong | `~/GolandProjects/open-source/dws-wukong` | `origin/develop` @ `ab76629a`（调研时） |
+> | 行为参考（**另一分支**） | `dws-skill-mode-migration` @ `402429ac`/`d5c8982c` | 安装默认 multi / upgrade 强制 multi —— **不在本分支排期** |
+> | 内容缺口留档（参考） | 同迁移分支 `docs/skill-capability-completion.md`（M1–M6 / X1 等） | **仅作质检目标线索**，非本分支权威 |
+
+---
+
+## 0. TL;DR
+
+1. **本分支 = skill 内容框架 + 相对 mono 的内容质检**：固化 `skills/multi` 组织合同，并用 **mono 单 skill 布局作对照基准**做覆盖/结构/漂移门禁（文档 + CI 内容护栏）。
+2. **对齐悟空**：只取内容树组织概念；质检以 **DWS-native** 设计为主（已有 policy/测试可复用）。悟空 `validate-multiskill-bundle.py` 仅借鉴「frontmatter / 断链 / requires」类检查思路，**不**移植 bundle/安装校验。
+3. **安装/升级行为**与 `402429ac`/`d5c8982c` → **单独 follow-up 分支**，本方案只登记。
+4. 质检 **不改**默认安装哪棵树；只保证 multi 内容相对 mono **可解释、可覆盖、可回归**。
+
+### 0.1 IN SCOPE
+
+| 类别 | 包含 |
+|---|---|
+| 内容树结构 | `skills/mono/` 与 `skills/multi/<name>/` 目录合同 |
+| 单 skill 约定 | `SKILL.md` frontmatter / 契约块 / Golden Route；`references/`；可选 `scripts/` |
+| 共享内容 | `dingtalk-shared` 职责与被引用方式；与 mono 全局文映射（文档级） |
+| 命名与集合 | `dingtalk-*` + `dingtalk-shared`；相对悟空的共有/独有清单（文档） |
+| Zip **内容布局合同** | `mono/` / `multi/` / 根 mono 副本的内容含义与树形状；不改安装默认 |
+| **Mono↔multi 内容质检** | 覆盖、结构、漂移三类门禁；复用/扩展现有 policy 与测试；缺口修复属内容编辑（另批或同分支内容 Phase） |
+| 内容架构文档 | 本文件 + 可选短文（架构合同 + 质检矩阵） |
+
+### 0.2 OUT OF SCOPE
+
+| 类别 | 去向 |
+|---|---|
+| 安装默认 multi、upgrade always-multi | Follow-up 分支（`402429ac`/`d5c8982c`） |
+| `LocateSkillsRoot` / `skill_setup` / `paths.go` / `skillhome` / install 脚本行为 | 同上 |
+| 安装/运行时 manifest、state.json、mode 切换、telemetry header | 拒绝或行为分支 |
+| 悟空 `_install.sh` / dual / Qwen / RewindDesktop / pod | 拒绝 |
+| 非 skill 内容的 CLI 功能（schema/shortcut 代码等） | 拒绝 |
+| 把质检做成「改安装默认值」的后门 | 拒绝 |
+
+---
+
+## 1. 内容现状盘点
+
+### 1.1 DWS `skills/mono`（质检对照基准 · 单 skill）
+
+```text
+skills/mono/
+├── SKILL.md
+├── references/
+│   ├── products/<area>.md|…/   # 产品能力面（质检「覆盖」主源）
+│   ├── error-codes.md、…  # 全局协议（无 recovery 闭环）
+│   └── best_practices/…
+└── scripts/
+```
+
+### 1.2 DWS `skills/multi`（内容主体）
+
+```text
+skills/multi/
+├── dingtalk-shared/     # 跨产品契约 / routing / 全局协议应落点
+└── dingtalk-*/     # 19 产品 + 各 references、scripts
+```
+
+仅 DWS 有（悟空无）：dev, event, hrbrain, markdown, pat, profile, skill。
+
+### 1.3 悟空 `dingtalk-skills/`（内容组织对照，非质检权威）
+
+Flat `dingtalk-*` + `dingtalk-shared`；单 skill 骨架同构。**不作为 mono 覆盖基准**（集合更小、不同源）。
+
+### 1.4 Zip 内容布局合同
+
+| Zip 路径 | 内容含义 |
+|---|---|
+| `<root>/` | mono 副本（兼容） |
+| `<root>/mono/` | 显式 mono 内容源 |
+| `<root>/multi/` | 与 `skills/multi/` 同构 |
+
+质检可断言「源树形状」；**不**断言安装面默认选哪棵。
+
+### 1.5 现有 DWS skill 内容质检资产（复用清单）
+
+| 资产 | 作用 | 与 mono↔multi 质检关系 |
+|---|---|---|
+| `scripts/policy/check-skill-commands.sh` + `skill-command-check/` | Skill 文内 `dws …` 命令路径存在性 | **复用**（命令真实性）；非覆盖映射 |
+| `scripts/policy/check-skill-context-budget.sh` | chat/event/mono/`dingtalk-shared` 上下文预算与冷启动约束 | **复用**（结构/预算）；可扩展 shared 引用规则 |
+| `scripts/policy/check-multi-im-skill-chain.sh` + `multi-im-skill-chain/` | IM 意图单默认路由、retired scripts、handoff | **复用**（chat/event 链）；面窄 |
+| `test/unit/skill_docs_policy_test.go` | 退役命令、event 扁平输出契约等 | **复用**；可加 mono↔multi 断言 |
+| `test/unit/whiteboard_skill_docs_test.go` | mono/multi whiteboard recipes **字节一致** | **样板**：产品面「同源文件」门禁范式 |
+| `test/skill_static`（`-tags skill_verify`） | 文内命令 vs Cobra；multi 查 flag | **复用**（opt-in 深度）；非 CI 默认全量时可保持 tags |
+| `test/skill_e2e` / `test/run_skill_tests.py` | 执行层 / 用例驱动 | **偏行为**；本分支质检默认不依赖 e2e |
+| `Makefile` → `policy` 含 context-budget、multi-im-skill-chain；`skill-command-integrity` 独立 | 已有 CI 钩子 | 新门禁优先挂同类 policy / `test/unit` |
+
+**缺口（尚无的门禁）**：系统的「mono `references/products/*` → multi 目录/文」覆盖表；frontmatter 全集完备性；orphan scripts。全局协议中 **确认门禁 / Schema 教学已补**；**recovery 闭环已从 skill 移除（不再作为缺口）**。
+
+### 1.6 悟空侧类比质检
+
+| 悟空 | 说明 | 本分支 |
+|---|---|---|
+| `scripts/validate-multiskill-bundle.py` | 校验 **已打好的 bundle zip**：frontmatter keys/category、`requires`、markdown 断链、scenario 编排 | **Adapt 思路** → DWS 源树（`skills/multi` + 对照 mono），不跑 zip 安装语义 |
+| `sync-monolith-to-multiskill.py` | mono→multi 派生 | **不**作默认质检手段；DWS 直接维护 multi |
+
+结论：**DWS-native mono↔multi 质检**；悟空仅参考检查维度。
+
+---
+
+## 2. Diff（内容组织 + 质检视角）
+
+### 2.1 已同构
+
+Flat `dingtalk-*` + `dingtalk-shared`；`SKILL.md` + `references/`（+ 可选 `scripts/`）。
+
+### 2.2 分叉与已知内容风险（质检要盯的）
+
+| 风险 ID | 现象（线索） | 质检类型 |
+|---|---|---|
+| **C-cov** | mono `products/*` 能力面在 multi 无对应 skill/reference，或未登记「有意省略」 | 覆盖 |
+| **C-struct** | multi 缺 frontmatter 字段、`references/`、`DWS_RUNTIME_CONTRACT`、对 `dingtalk-shared` 引用不一致 | 结构 |
+| **C-drift-global** | 曾关注 recovery / 确认 / Schema；现确认与 Schema 已在 `dingtalk-shared`，**recovery skill 文档已删除** | 漂移（协议） |
+| **C-drift-orphan** | multi（或 mono）scripts/refs 无文档引用；或 routing 指向无索引产品（留档 X1/M6） | 漂移（孤儿） |
+| **C-pair** | 应对齐的成对文件（如 whiteboard recipes）内容不一致 | 漂移（成对） |
+
+### 2.3 Reject
+
+悟空安装包校验整文件照搬、内容集 19→12 砍产品、安装行为门禁冒充内容质检。
+
+---
+
+## 3. Goals / Non-goals
+
+### 3.1 Goals
+
+1. 固化 multi **内容目录合同**与 mono↔multi **映射说明**。  
+2. 建立 **质检矩阵**（覆盖 / 结构 / 漂移）并以 mono 为对照基准；有意省略必须 reviewed 登记。  
+3. **复用** §1.5 资产；新增门禁走 `scripts/policy` 或 `test/unit`，内容-only。  
+4. （可选）纯内容元数据；**禁止**被安装引擎读取改行为。  
+5. 质检失败 → 修 **内容**或更新「有意省略」表，不改 setup/upgrade。
+
+### 3.2 Non-goals
+
+安装/升级翻转；cherry-pick 行为提交；取消产品；悟空客户端；非 skill CLI 功能；用质检驱动默认 multi 安装。
+
+---
+
+## 4. 分期（内容框架 + 质检 · 均无安装引擎）
+
+> 批准前 **零编码**（含不实现新 gates）。**已执行**：Phase 1–3 见文首状态。
+
+### Phase 0 — 方案冻结（本文）
+
+| | |
+|---|---|
+| **范围** | 本文件；§7（含质检轨）勾选 |
+| **验收** | owner 重新批准 → ✅「现在开始执行」 |
+
+### Phase 1 — Multi 内容目录合同 + 架构短文 ✅
+
+| | |
+|---|---|
+| **范围** | `skills/multi` 目录合同；与悟空内容树对照表；zip `multi/` 同构合同 |
+| **触达** | `docs/skill-content-framework.md` |
+| **验收** | 可指导「如何新增 dingtalk-* 内容目录」 |
+
+### Phase 2 — Mono↔multi **内容质检规格**（矩阵 + 缺口基线） ✅
+
+| | |
+|---|---|
+| **范围** | 质检规格 + 覆盖/omit 机读表 + 缺口 disposition |
+| **触达** | `docs/skill-mono-multi-qa.md`、`skills/content-qa/mono-multi-coverage.yaml` |
+| **验收** | 矩阵可人工抽查；缺口均有 disposition |
+
+### Phase 3 — 质检落地：CI 内容护栏（复用 + 新 gate） ✅
+
+| | |
+|---|---|
+| **范围** | G1–G4 自动门禁 |
+| **触达** | `test/unit/mono_multi_skill_content_test.go`、`scripts/policy/check-mono-multi-skill-content.sh`、`Makefile` |
+| **验收** | `make skill-mono-multi-content` 绿；已知缺口走 reviewed omit |
+
+### Phase 4 — 可选：内容包元数据 + 缺口修复波次
+
+| | |
+|---|---|
+| **范围 A** | 纯内容 layout/skill 列表元数据（人不读安装器） |
+| **范围 B** | 按 Phase 2 disposition **修内容**：确认 / Schema 已补；**recovery skill 文档已删除（wontfix 移植）**；orphan 脚本仍走 allowlist（M4 等） |
+| **验收** | 元数据不驱动安装；修复项关闭对应质检失败或转入 omit |
+
+### 延期登记（非本分支）
+
+| 主题 | 载体 |
+|---|---|
+| 默认 multi + upgrade always-multi | 行为分支 ← `402429ac`/`d5c8982c` |
+| skillhome / 安装面 bootstrap | 行为分支 |
+
+---
+
+## 5. Port / Adapt / Reject
+
+| 项 | 决策 | 说明 |
+|---|---|---|
+| flat + `dingtalk-shared` 内容模型 | **Port** | 已有；合同 + 质检加固 |
+| 悟空 bundle frontmatter/断链/requires 检查维度 | **Adapt** | 做成 DWS 源树门禁，不校验 bundle zip/安装 |
+| whiteboard 式 mono/multi 成对一致 | **Port（范式）** | 推广到 reviewed 文件对 |
+| `validate-multiskill-bundle.py` 整脚本 | **Reject** | 绑定悟空 zip/Qwen 语义 |
+| `_install.sh` / dual / overlay | **Reject** | 非内容 |
+| 行为 cherry-pick | **Defer** | 另分支 |
+
+---
+
+## 6. 与 `402429ac` / `d5c8982c`
+
+| | |
+|---|---|
+| 本分支 cherry-pick？ | **否** |
+| 质检是否替代行为翻转？ | **否** |
+| 行为分支 | 另开；可与内容/质检并行 |
+
+---
+
+## 7. 批准清单（请重新勾选）
+
+**范围**
+
+- [x] 本分支 = skill **内容**框架 + **mono↔multi 内容质检**（§0.1）；无安装/升级引擎  
+- [x] `402429ac`/`d5c8982c` 及 setup/paths/install 脚本行为 **不在本分支**  
+- [x] 取消产品与悟空客户端链路仍拒绝  
+
+**内容框架 Phase**
+
+- [x] **Phase 1**：multi 目录合同 + 悟空内容树对照短文  
+
+**质检轨 Phase**
+
+- [x] **Phase 2**：质检矩阵 + mono↔multi 覆盖/缺口基线规格（先文档，可执行）  
+- [x] **Phase 3**：CI 内容护栏（G1–G4）—— 本迭代做 / 拆 PR / 只要规格暂不落地  
+- [x] 质检失败处置原则：修内容或 reviewed omit，**不**改安装默认  
+
+**可选**
+
+- [ ] **Phase 4A** 纯内容元数据：做 / 不做 / 以后  
+- [x] **Phase 4B** recovery skill 文档 **removed/wontfix**；确认/Schema 已补；剩余 orphan（M4 等）仍 defer / allowlist  
+
+**Follow-up 知悉**
+
+- [ ] 安装默认 multi + upgrade always-multi → **另一分支**  
+
+---
+
+## 8. 下一步
+
+**Phase 1–3 已落地**（合同短文 + 质检规格 + `skills/content-qa` + CI 门禁）。  
+Phase 4B：recovery 已删除（不做移植）；确认/Schema 已补。剩余 defer：orphan scripts（M4 等）、LICENSE/NOTICE（M5）、Phase 4A 元数据。  
+安装默认 multi 等行为仍走 **另一分支**。
+
+---
+
+*锚点：`skills/mono`、`skills/multi`、§1.5 policy/测试、wukong `dingtalk-skills/`（组织对照 only）。*

go.mod

@@ -12,6 +12,7 @@ require (
 	github.com/google/uuid v1.6.0
 	github.com/gorilla/websocket v1.5.0
 	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/spf13/cobra v1.10.2
@@ -40,7 +41,6 @@ require (
 	github.com/itchyny/timefmt-go v0.1.7 // indirect
 	github.com/lucasb-eyer/go-colorful v1.2.0 // indirect
 	github.com/mattn/go-colorable v0.1.13 // indirect
-	github.com/mattn/go-isatty v0.0.20 // indirect
 	github.com/mattn/go-localereader v0.0.1 // indirect
 	github.com/mattn/go-runewidth v0.0.19 // indirect
 	github.com/mitchellh/hashstructure/v2 v2.0.2 // indirect

internal/app/agent_host.go

@@ -33,7 +33,7 @@ func init() {
 	configmeta.Register(configmeta.ConfigItem{
 		Name:        envDWSAgentHost,
 		Category:    configmeta.CategoryExternal,
-		Description: "调用 DWS 的 Agent 运行形态标识；服务端可结合产品用于观测和 PAT 兼容策略",
+		Description: "调用 DWS 的 Agent 运行形态标识；作为 x-dws-agent-host 发送供下游观测，本客户端不使用该值改变 PAT、鉴权或路由",
 		Example:     "cloud",
 	})
 }

internal/app/agent_product.go

@@ -24,8 +24,8 @@ func init() {
 	configmeta.Register(configmeta.ConfigItem{
 		Name:         agentproduct.EnvName,
 		Category:     configmeta.CategoryExternal,
-		Description:  "调用方声明的 Agent 产品标识；覆盖 HTTP claw-type，但不是认证凭据",
-		DefaultValue: "由当前发行版决定",
+		Description:  "调用方声明的 Agent 产品标识；作为 x-dws-agent-product 发送并用于 IM 小尾巴，本客户端不使用该值改变 HTTP claw-type/PAT",
+		DefaultValue: "未设置（请求头省略，IM 使用当前发行版默认值）",
 		Example:      "qwenwork",
 	})
 }
@@ -47,25 +47,26 @@ func invalidAgentProductError() error {
 	)
 }
 
-// resolveEffectiveAgentProduct resolves the request-header identity with one
-// shared precedence rule: a valid non-empty runtime override wins, otherwise
-// the edition's MergeHeaders value wins, otherwise the OSS default is used.
-// Invalid runtime input falls back here for library callers that bypass root
-// validation; normal CLI execution rejects it before network access.
-func resolveEffectiveAgentProduct(headers map[string]string) string {
-	fallback := edition.DefaultOSSClawType
-	if value := headers[agentproduct.HeaderName]; value != "" {
-		fallback = value
+// resolveEditionClawType resolves the fixed routing/PAT identity supplied by
+// the active edition. DWS_AGENT_PRODUCT is deliberately not consulted.
+func resolveEditionClawType(headers map[string]string) string {
+	if value := headers["claw-type"]; value != "" {
+		return value
 	}
-	value, err := agentproduct.ResolveFromEnv(fallback)
-	if err != nil {
-		return fallback
-	}
-	return value
+	return edition.DefaultOSSClawType
 }
 
-func applyAgentProductOverride(headers map[string]string) map[string]string {
-	value := resolveEffectiveAgentProduct(headers)
+// applyAgentProductHeader injects only a valid, non-empty caller-declared
+// product. Invalid values are omitted on library paths that bypass root
+// validation; normal CLI execution rejects them before network access.
+func applyAgentProductHeader(headers map[string]string) map[string]string {
+	value, err := agentproduct.ResolveFromEnv("")
+	if err != nil || value == "" {
+		if headers != nil {
+			delete(headers, agentproduct.HeaderName)
+		}
+		return headers
+	}
 	if headers == nil {
 		headers = make(map[string]string)
 	}

internal/app/agent_product_test.go

@@ -26,13 +26,16 @@ import (
 	"github.com/spf13/cobra"
 )
 
-func TestUnsetAgentProductKeepsOpenSourceDefault(t *testing.T) {
+func TestUnsetAgentProductOmitsHeaderAndKeepsOpenSourceClawType(t *testing.T) {
 	t.Setenv("DWS_CONFIG_DIR", t.TempDir())
 	t.Setenv(agentproduct.EnvName, "")
 
 	headers := resolveIdentityHeaders()
-	if got := headers[agentproduct.HeaderName]; got != edition.DefaultOSSClawType {
-		t.Fatalf("%s = %q, want %q", agentproduct.HeaderName, got, edition.DefaultOSSClawType)
+	if got := headers["claw-type"]; got != edition.DefaultOSSClawType {
+		t.Fatalf("claw-type = %q, want %q", got, edition.DefaultOSSClawType)
+	}
+	if _, ok := headers[agentproduct.HeaderName]; ok {
+		t.Fatalf("unset Product must omit %s", agentproduct.HeaderName)
 	}
 }
 
@@ -59,38 +62,46 @@ func TestParseAgentProductReturnsStableValidationError(t *testing.T) {
 	}
 }
 
-func TestResolveIdentityHeadersAgentProductPrecedence(t *testing.T) {
+func TestResolveIdentityHeadersSeparatesAgentProductFromClawType(t *testing.T) {
 	t.Setenv("DWS_CONFIG_DIR", t.TempDir())
 
 	oldEdition := edition.Get()
 	t.Cleanup(func() { edition.Override(oldEdition) })
 	edition.Override(&edition.Hooks{
 		MergeHeaders: func(headers map[string]string) map[string]string {
-			headers[agentproduct.HeaderName] = "wukong"
+			headers["claw-type"] = "wukong"
+			headers[agentproduct.HeaderName] = "merge-product-must-not-win"
 			headers["x-edition-header"] = "preserved"
 			return headers
 		},
 		EnterpriseCredentialHeaders: func(headers map[string]string) map[string]string {
-			headers[agentproduct.HeaderName] = "enterprise-default"
+			headers["claw-type"] = "credential-must-not-win"
+			headers[agentproduct.HeaderName] = "credential-product-must-not-win"
 			headers["x-enterprise-header"] = "preserved"
 			return headers
 		},
 	})
 
-	t.Run("unset keeps edition default", func(t *testing.T) {
+	t.Run("unset omits Product and keeps edition claw-type", func(t *testing.T) {
 		t.Setenv(agentproduct.EnvName, "")
 		headers := resolveIdentityHeaders()
-		if got := headers[agentproduct.HeaderName]; got != "wukong" {
-			t.Fatalf("%s = %q, want wukong", agentproduct.HeaderName, got)
+		if got := headers["claw-type"]; got != "wukong" {
+			t.Fatalf("claw-type = %q, want wukong", got)
+		}
+		if _, ok := headers[agentproduct.HeaderName]; ok {
+			t.Fatalf("unset Product must omit %s", agentproduct.HeaderName)
 		}
 	})
 
-	t.Run("valid override is final", func(t *testing.T) {
+	t.Run("valid Product is final without changing claw-type", func(t *testing.T) {
 		t.Setenv(agentproduct.EnvName, " qwenwork ")
 		headers := resolveIdentityHeaders()
 		if got := headers[agentproduct.HeaderName]; got != "qwenwork" {
 			t.Fatalf("%s = %q, want qwenwork", agentproduct.HeaderName, got)
 		}
+		if got := headers["claw-type"]; got != "wukong" {
+			t.Fatalf("claw-type = %q, want wukong", got)
+		}
 		if got := headers["x-edition-header"]; got != "preserved" {
 			t.Fatalf("edition header = %q, want preserved", got)
 		}
@@ -102,21 +113,48 @@ func TestResolveIdentityHeadersAgentProductPrecedence(t *testing.T) {
 		}
 	})
 
-	t.Run("invalid library input falls back to edition", func(t *testing.T) {
+	t.Run("invalid library input omits Product and keeps edition claw-type", func(t *testing.T) {
 		t.Setenv(agentproduct.EnvName, "qwen work")
 		headers := resolveIdentityHeaders()
-		if got := headers[agentproduct.HeaderName]; got != "wukong" {
-			t.Fatalf("%s = %q, want wukong", agentproduct.HeaderName, got)
+		if got := headers["claw-type"]; got != "wukong" {
+			t.Fatalf("claw-type = %q, want wukong", got)
+		}
+		if _, ok := headers[agentproduct.HeaderName]; ok {
+			t.Fatalf("invalid Product must omit %s", agentproduct.HeaderName)
 		}
 	})
 }
 
-func TestApplyAgentProductOverrideAllocatesHeaders(t *testing.T) {
-	t.Setenv(agentproduct.EnvName, "qwenwork")
+func TestApplyAgentProductHeader(t *testing.T) {
+	t.Run("valid value allocates headers", func(t *testing.T) {
+		t.Setenv(agentproduct.EnvName, "qwenwork")
 
-	headers := applyAgentProductOverride(nil)
-	if got := headers[agentproduct.HeaderName]; got != "qwenwork" {
-		t.Fatalf("%s = %q, want qwenwork", agentproduct.HeaderName, got)
+		headers := applyAgentProductHeader(nil)
+		if got := headers[agentproduct.HeaderName]; got != "qwenwork" {
+			t.Fatalf("%s = %q, want qwenwork", agentproduct.HeaderName, got)
+		}
+	})
+
+	for _, tc := range []struct {
+		name  string
+		value string
+	}{
+		{name: "empty value", value: ""},
+		{name: "invalid value", value: "qwen work"},
+	} {
+		t.Run(tc.name+" removes inherited header", func(t *testing.T) {
+			t.Setenv(agentproduct.EnvName, tc.value)
+			headers := applyAgentProductHeader(map[string]string{
+				agentproduct.HeaderName: "must-not-leak",
+				"x-preserved":           "yes",
+			})
+			if _, ok := headers[agentproduct.HeaderName]; ok {
+				t.Fatalf("%s must be omitted", agentproduct.HeaderName)
+			}
+			if got := headers["x-preserved"]; got != "yes" {
+				t.Fatalf("x-preserved = %q, want yes", got)
+			}
+		})
 	}
 }
 
@@ -167,17 +205,17 @@ func TestEffectiveClawTypeDoesNotInvokeEnterpriseCredentialHeaders(t *testing.T)
 	hookCalled := false
 	edition.Override(&edition.Hooks{
 		MergeHeaders: func(headers map[string]string) map[string]string {
-			headers[agentproduct.HeaderName] = "wukong"
+			headers["claw-type"] = "wukong"
 			return headers
 		},
 		EnterpriseCredentialHeaders: func(headers map[string]string) map[string]string {
 			hookCalled = true
-			headers[agentproduct.HeaderName] = "enterprise-default"
+			headers["claw-type"] = "enterprise-default"
 			return headers
 		},
 	})
 
-	t.Setenv(agentproduct.EnvName, "")
+	t.Setenv(agentproduct.EnvName, "qwenwork")
 	if got := effectiveClawType(); got != "wukong" {
 		t.Fatalf("effectiveClawType() = %q, want wukong", got)
 	}
@@ -186,7 +224,7 @@ func TestEffectiveClawTypeDoesNotInvokeEnterpriseCredentialHeaders(t *testing.T)
 	}
 }
 
-func TestAgentProductHeaderIsSeparateFromMessageClawType(t *testing.T) {
+func TestAgentProductControlsObservabilityHeaderAndMessageClawTypeOnly(t *testing.T) {
 	t.Setenv("DWS_CONFIG_DIR", t.TempDir())
 	t.Setenv(agentproduct.EnvName, "qwenwork")
 
@@ -195,20 +233,24 @@ func TestAgentProductHeaderIsSeparateFromMessageClawType(t *testing.T) {
 	edition.Override(&edition.Hooks{
 		ClawTypeValue: "message-brand",
 		MergeHeaders: func(headers map[string]string) map[string]string {
-			headers[agentproduct.HeaderName] = "wukong"
+			headers["claw-type"] = "wukong"
 			return headers
 		},
 	})
 
-	if got := resolveIdentityHeaders()[agentproduct.HeaderName]; got != "qwenwork" {
+	headers := resolveIdentityHeaders()
+	if got := headers[agentproduct.HeaderName]; got != "qwenwork" {
 		t.Fatalf("HTTP %s = %q, want qwenwork", agentproduct.HeaderName, got)
 	}
-	if got := edition.ClawType(); got != "message-brand" {
-		t.Fatalf("message clawType = %q, want message-brand", got)
+	if got := headers["claw-type"]; got != "wukong" {
+		t.Fatalf("HTTP claw-type = %q, want wukong", got)
+	}
+	if got := edition.ClawType(); got != "qwenwork" {
+		t.Fatalf("message clawType = %q, want qwenwork", got)
 	}
 }
 
-func TestResolveIdentityHeadersRestoresAgentProductAfterNilCredentialHeaders(t *testing.T) {
+func TestResolveIdentityHeadersRestoresIdentityAfterNilCredentialHeaders(t *testing.T) {
 	t.Setenv("DWS_CONFIG_DIR", t.TempDir())
 	t.Setenv(agentproduct.EnvName, "qwenwork")
 
@@ -218,7 +260,7 @@ func TestResolveIdentityHeadersRestoresAgentProductAfterNilCredentialHeaders(t *
 	credentialHookCalled := false
 	edition.Override(&edition.Hooks{
 		MergeHeaders: func(headers map[string]string) map[string]string {
-			headers[agentproduct.HeaderName] = "wukong"
+			headers["claw-type"] = "wukong"
 			return headers
 		},
 		EnterpriseCredentialHeaders: func(map[string]string) map[string]string {
@@ -234,25 +276,49 @@ func TestResolveIdentityHeadersRestoresAgentProductAfterNilCredentialHeaders(t *
 	if got := headers[agentproduct.HeaderName]; got != "qwenwork" {
 		t.Fatalf("%s = %q, want qwenwork", agentproduct.HeaderName, got)
 	}
+	if got := headers["claw-type"]; got != "wukong" {
+		t.Fatalf("claw-type = %q, want wukong", got)
+	}
 }
 
-func TestEffectiveClawTypeUsesAgentProductOverride(t *testing.T) {
+func TestResolveIdentityHeadersRestoresDefaultsAfterNilMergeHeaders(t *testing.T) {
+	t.Setenv("DWS_CONFIG_DIR", t.TempDir())
+	t.Setenv(agentproduct.EnvName, "")
+
+	oldEdition := edition.Get()
+	t.Cleanup(func() { edition.Override(oldEdition) })
+	edition.Override(&edition.Hooks{
+		MergeHeaders: func(map[string]string) map[string]string {
+			return nil
+		},
+	})
+
+	headers := resolveIdentityHeaders()
+	if got := headers["claw-type"]; got != edition.DefaultOSSClawType {
+		t.Fatalf("claw-type = %q, want %q", got, edition.DefaultOSSClawType)
+	}
+	if _, ok := headers[agentproduct.HeaderName]; ok {
+		t.Fatalf("unset Product must omit %s", agentproduct.HeaderName)
+	}
+}
+
+func TestEffectiveClawTypeIgnoresAgentProduct(t *testing.T) {
 	oldEdition := edition.Get()
 	t.Cleanup(func() { edition.Override(oldEdition) })
 	edition.Override(&edition.Hooks{
 		MergeHeaders: func(headers map[string]string) map[string]string {
-			headers[agentproduct.HeaderName] = "wukong"
+			headers["claw-type"] = "wukong"
 			return headers
 		},
 	})
 
 	t.Setenv(agentproduct.EnvName, "qwenwork")
-	if got := effectiveClawType(); got != "qwenwork" {
-		t.Fatalf("effectiveClawType() = %q, want qwenwork", got)
+	if got := effectiveClawType(); got != "wukong" {
+		t.Fatalf("effectiveClawType() = %q, want wukong", got)
 	}
 	t.Setenv(authpkg.AgentCodeEnv, "agent-code")
-	if got := apperrors.HostControlBlock()["clawType"]; got != "qwenwork" {
-		t.Fatalf("hostControl.clawType = %q, want qwenwork", got)
+	if got := apperrors.HostControlBlock()["clawType"]; got != "wukong" {
+		t.Fatalf("hostControl.clawType = %q, want wukong", got)
 	}
 
 	t.Setenv(agentproduct.EnvName, "")

internal/app/app_small_coverage_test.go

@@ -335,12 +335,6 @@ func TestCrossPlatformCoverageOverlayRecoveryHostAndHelperRemainingCoverage(t *t
 	edition.Override(&edition.Hooks{ConfigDir: func() string { return "" }})
 	captureRuntimeFailure(executor.Invocation{}, nil, nil)
 	captureRuntimeFailure(executor.Invocation{}, errors.New("raw"), nil)
-	oldArgs := os.Args
-	os.Args = []string{"dws", "doc", "download", "--node", "n"}
-	if got := runtimeCommandPath(executor.Invocation{}); len(got) != 2 {
-		t.Fatalf("runtime command path = %#v", got)
-	}
-	os.Args = oldArgs
 
 	t.Setenv(authpkg.AgentCodeEnv, "")
 	if hostControlProviderFromEnv() != "" {
@@ -360,6 +354,10 @@ func TestCrossPlatformCoverageOverlayRecoveryHostAndHelperRemainingCoverage(t *t
 
 func TestCrossPlatformCoverageConfigAndCacheCommandRemainingCoverage(t *testing.T) {
 	for _, command := range []*cobra.Command{newConfigCommand(), newCacheCommand()} {
+		command.SetOut(io.Discard)
+		rootWrap := &cobra.Command{Use: "dws"}
+		rootWrap.PersistentFlags().String("format", "json", "")
+		rootWrap.AddCommand(command)
 		command.SetOut(io.Discard)
 		if err := command.RunE(command, nil); err != nil {
 			t.Fatal(err)
@@ -389,18 +387,18 @@ func TestCrossPlatformCoverageConfigAndCacheCommandRemainingCoverage(t *testing.
 	for _, format := range []string{"json", "pretty", "table"} {
 		_ = cacheRoot.PersistentFlags().Set("format", format)
 		cacheCmd.SetOut(io.Discard)
-		if err := printCacheCompatNotice(cacheCmd, "status"); err != nil {
+		if err := printCacheCompatNotice(cacheCmd, "dws cache status"); err != nil {
 			t.Fatal(err)
 		}
 	}
 	fail := errors.New("write")
 	cacheCmd.SetOut(appFailWriter{err: fail})
 	_ = cacheRoot.PersistentFlags().Set("format", "pretty")
-	if err := printCacheCompatNotice(cacheCmd, "status"); !errors.Is(err, fail) {
+	if err := printCacheCompatNotice(cacheCmd, "dws cache status"); !errors.Is(err, fail) {
 		t.Fatalf("pretty write error = %v", err)
 	}
 	_ = cacheRoot.PersistentFlags().Set("format", "table")
-	if err := printCacheCompatNotice(cacheCmd, "status"); !errors.Is(err, fail) {
+	if err := printCacheCompatNotice(cacheCmd, "dws cache status"); !errors.Is(err, fail) {
 		t.Fatalf("table write error = %v", err)
 	}
 }

internal/app/app_tiny_coverage_test.go

@@ -140,7 +140,7 @@ func TestCrossPlatformCoverageDirectRuntimeRemainingCoverage(t *testing.T) {
 	products := map[string]bool{}
 	aliases := map[string]string{}
 	tools := map[string]string{}
-	registerDynamicServer(mcptypes.ServerDescriptor{CLI: mcptypes.CLIOverlay{Skip: true}}, endpoints, products, aliases, tools)
+	registerDynamicServer(mcptypes.ServerDescriptor{CLI: mcptypes.CLIOverlay{Skip: true}}, endpoints, products, aliases, tools, false)
 	registerDynamicServer(mcptypes.ServerDescriptor{
 		Endpoint: "https://server.test",
 		CLI: mcptypes.CLIOverlay{
@@ -148,7 +148,7 @@ func TestCrossPlatformCoverageDirectRuntimeRemainingCoverage(t *testing.T) {
 			Tools:         []mcptypes.CLITool{{Name: "tool"}, {Name: " "}},
 			ToolOverrides: map[string]mcptypes.CLIToolOverride{"override": {}, " ": {}},
 		},
-	}, endpoints, products, aliases, tools)
+	}, endpoints, products, aliases, tools, false)
 	if endpoints["command"] == "" || aliases["alias"] != "id" || tools["override"] == "" {
 		t.Fatalf("registered dynamic server = %#v %#v %#v", endpoints, aliases, tools)
 	}
@@ -200,7 +200,7 @@ func TestCrossPlatformCoverageDirectRuntimeRemainingCoverage(t *testing.T) {
 			},
 		},
 	})
-	if got, ok := directRuntimeToolEndpoint("append-override"); !ok || got != "https://append.test" {
+	if got, ok := directRuntimeEndpoint("", "append-override"); !ok || got != "https://append.test" {
 		t.Fatalf("append override endpoint = %q, %v", got, ok)
 	}
 }
@@ -274,7 +274,7 @@ func TestCrossPlatformCoverageEmbeddedSkillAndTinyCommandsRemainingCoverage(t *t
 	if err := completion.RunE(completion, []string{"other"}); err != nil {
 		t.Fatal(err)
 	}
-	catalog := newCatalogCommand(nil)
+	catalog := newCatalogCommand()
 	catalog.SetOut(io.Discard)
 	if err := catalog.RunE(catalog, nil); err != nil {
 		t.Fatal(err)

internal/app/audit_command.go

@@ -12,7 +12,10 @@ import (
 	"strings"
 	"time"
 
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/helpers"
+
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/audit"
+	"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"
 )
@@ -26,6 +29,20 @@ var (
 )
 
 func newAuditCommand() *cobra.Command {
+	// Product-level Agent routing Decl (migrated from selection/audit.json
+	// products.audit). Catalog assembly stamps provenance contract_final.
+	contract.RegisterProductDecl(contract.ProductDecl{
+		ID: "audit",
+		Selection: contract.ProductSelectionDecl{
+			AgentSummary: "查看、导出和校验本地操作审计日志",
+			UseWhen: []string{
+				"需要排查本机 CLI 操作审计记录，或验证审计文件完整性",
+			},
+			AvoidWhen: []string{
+				"查钉钉业务数据或发消息请用对应产品命令，不要用 audit",
+			},
+		},
+	})
 	cmd := &cobra.Command{
 		Use:   "audit",
 		Short: "操作审计日志管理",
@@ -64,6 +81,39 @@ func newAuditTailCommand() *cobra.Command {
 		},
 	}
 	cmd.Flags().IntVarP(&n, "lines", "n", 20, "显示最近 N 条记录")
+	helpers.DeclareLeafMetadata(cmd, helpers.LeafSpec{
+		Safety: contract.SafetySpec{
+			Effect: "read", Risk: "low",
+			Confirmation: "not_required", Idempotency: "idempotent",
+		},
+		Contract: helpers.LeafContract{
+			Identity: contract.ToolIdentitySpec{
+				ProductID:      "audit",
+				Name:           "tail",
+				CanonicalPath:  "audit.tail",
+				CLIPath:        "audit tail",
+				PrimaryCLIPath: "audit tail",
+			},
+			Description: "查看本地操作审计日志最近 N 条记录",
+			Interface: &contract.InterfaceSpec{
+				Mode:         "local",
+				Availability: "available",
+				Reason:       "命令读取本地审计日志尾部，不绑定 pinned MCP RPC",
+			},
+			Selection: contract.SelectionSpec{
+				AgentSummary: "查看本地操作审计日志最近 N 条记录",
+				UseWhen:      []string{"需要快速查看最近写入的审计记录（默认最近 20 条）"},
+				AvoidWhen: []string{
+					"需要按日期范围整段导出用 audit export",
+					"需要校验哈希链用 audit verify",
+				},
+				Examples: []string{
+					"dws audit tail",
+					"dws audit tail --lines 50",
+				},
+			},
+		},
+	})
 	return cmd
 }
 
@@ -99,6 +149,39 @@ func newAuditExportCommand() *cobra.Command {
 	cmd.Flags().StringVar(&since, "since", "", "起始日期 (YYYY-MM-DD)")
 	cmd.Flags().StringVar(&until, "until", "", "截止日期 (YYYY-MM-DD)")
 	cmd.Flags().StringVar(&format, "format", "jsonl", "输出格式: jsonl 或 csv")
+	helpers.DeclareLeafMetadata(cmd, helpers.LeafSpec{
+		Safety: contract.SafetySpec{
+			Effect: "read", Risk: "low",
+			Confirmation: "not_required", Idempotency: "idempotent",
+		},
+		Contract: helpers.LeafContract{
+			Identity: contract.ToolIdentitySpec{
+				ProductID:      "audit",
+				Name:           "export",
+				CanonicalPath:  "audit.export",
+				CLIPath:        "audit export",
+				PrimaryCLIPath: "audit export",
+			},
+			Description: "按日期范围导出本地操作审计日志（jsonl 或 csv）",
+			Interface: &contract.InterfaceSpec{
+				Mode:         "local",
+				Availability: "available",
+				Reason:       "命令读取并导出本地审计日志文件，不绑定 pinned MCP RPC",
+			},
+			Selection: contract.SelectionSpec{
+				AgentSummary: "按日期范围导出本地操作审计日志（jsonl 或 csv）",
+				UseWhen:      []string{"需要把本地审计日志导出为 jsonl/csv，或按 --since/--until 取一段时间"},
+				AvoidWhen: []string{
+					"只看最近几条用 audit tail",
+					"只校验哈希链完整性用 audit verify",
+				},
+				Examples: []string{
+					"dws audit export --format jsonl",
+					"dws audit export --since 2026-07-01 --until 2026-07-14 --format csv",
+				},
+			},
+		},
+	})
 	return cmd
 }
 
@@ -152,6 +235,36 @@ func newAuditVerifyCommand() *cobra.Command {
 		},
 	}
 	cmd.Flags().StringVar(&file, "file", "", "指定审计文件路径（默认最新文件）")
+	helpers.DeclareLeafMetadata(cmd, helpers.LeafSpec{
+		Safety: contract.SafetySpec{
+			Effect: "read", Risk: "low",
+			Confirmation: "not_required", Idempotency: "idempotent",
+		},
+		Contract: helpers.LeafContract{
+			Identity: contract.ToolIdentitySpec{
+				ProductID:      "audit",
+				Name:           "verify",
+				CanonicalPath:  "audit.verify",
+				CLIPath:        "audit verify",
+				PrimaryCLIPath: "audit verify",
+			},
+			Description: "校验本地审计日志文件的哈希链完整性",
+			Interface: &contract.InterfaceSpec{
+				Mode:         "local",
+				Availability: "available",
+				Reason:       "命令校验本地审计日志哈希链，不绑定 pinned MCP RPC",
+			},
+			Selection: contract.SelectionSpec{
+				AgentSummary: "校验本地审计日志文件的哈希链完整性",
+				UseWhen:      []string{"怀疑审计文件被篡改，或需要确认最新/指定文件哈希链是否完整"},
+				AvoidWhen:    []string{"只浏览或导出日志内容时用 audit tail / audit export"},
+				Examples: []string{
+					"dws audit verify",
+					"dws audit verify --file /path/to/audit.jsonl",
+				},
+			},
+		},
+	})
 	return cmd
 }
 

internal/app/cache_command.go

@@ -21,6 +21,10 @@ import (
 	"github.com/spf13/cobra"
 )
 
+const cacheUnsupportedMessage = "dws cache 不再支持：服务发现已下线，当前版本使用编译期静态端点目录；dws cache 仅保留为兼容入口，不会刷新端点。"
+
+const cacheReplacementHint = "如遇 endpoint_not_resolved，请先执行 dws upgrade 获取包含最新 internal/syncdata 端点的版本；仍失败时检查 internal/syncdata.StaticServers() 是否覆盖目标 product/server。"
+
 type cacheCompatNotice struct {
 	Status      string `json:"status"`
 	Command     string `json:"command"`
@@ -28,24 +32,32 @@ type cacheCompatNotice struct {
 	Replacement string `json:"replacement,omitempty"`
 }
 
+// newCacheCommand keeps a visible Deprecated compatibility surface for
+// historical argv (refresh/status/clean). Behavior is a successful no-op notice.
+// Skills must not teach this path. Deprecated leaves are excluded from Schema
+// via cobra.IsAvailableCommand() — do not add schema_command_exclusions entries.
 func newCacheCommand() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:               "cache",
-		Short:             "服务发现缓存兼容入口（静态端点模式已弃用）",
-		Hidden:            true,
+		Short:             "不再支持：服务发现缓存兼容入口",
+		Long:              "此命令组仅为历史 argv 兼容保留。静态端点模式下无需服务发现缓存；Skill / Agent 请勿引导此路径。",
+		Deprecated:        "不再支持；" + cacheUnsupportedMessage,
+		Args:              cobra.NoArgs,
 		DisableAutoGenTag: true,
 		RunE: func(cmd *cobra.Command, args []string) error {
-			return cmd.Help()
+			return printCacheCompatNotice(cmd, "dws cache")
 		},
 	}
 	for _, name := range []string{"refresh", "status", "clean"} {
+		subName := name
 		sub := &cobra.Command{
-			Use:               name,
-			Short:             "已弃用：静态端点模式无需服务发现缓存",
+			Use:               subName,
+			Short:             "不再支持：静态端点模式无需服务发现缓存",
+			Deprecated:        "不再支持；" + cacheUnsupportedMessage,
 			Args:              cobra.NoArgs,
 			DisableAutoGenTag: true,
 			RunE: func(cmd *cobra.Command, args []string) error {
-				return printCacheCompatNotice(cmd, name)
+				return printCacheCompatNotice(cmd, "dws cache "+subName)
 			},
 		}
 		cmd.AddCommand(sub)
@@ -56,9 +68,9 @@ func newCacheCommand() *cobra.Command {
 func printCacheCompatNotice(cmd *cobra.Command, command string) error {
 	notice := cacheCompatNotice{
 		Status:      "deprecated",
-		Command:     "dws cache " + command,
-		Message:     "服务发现已下线，当前版本使用编译期静态端点目录；dws cache 仅保留为兼容入口，不会刷新端点。",
-		Replacement: "如遇 endpoint_not_resolved，请先执行 dws upgrade 获取包含最新 internal/syncdata 端点的版本；仍失败时检查 internal/syncdata.StaticServers() 是否覆盖目标 product/server。",
+		Command:     command,
+		Message:     cacheUnsupportedMessage,
+		Replacement: cacheReplacementHint,
 	}
 	format, _ := cmd.Root().PersistentFlags().GetString("format")
 	switch strings.ToLower(strings.TrimSpace(format)) {
@@ -66,8 +78,7 @@ func printCacheCompatNotice(cmd *cobra.Command, command string) error {
 		return json.NewEncoder(cmd.OutOrStdout()).Encode(notice)
 	case "pretty":
 		data, _ := json.MarshalIndent(notice, "", "  ")
-		var err error
-		_, err = fmt.Fprintln(cmd.OutOrStdout(), string(data))
+		_, err := fmt.Fprintln(cmd.OutOrStdout(), string(data))
 		return err
 	default:
 		_, err := fmt.Fprintf(cmd.OutOrStdout(), "%s: %s\n%s\n", notice.Command, notice.Message, notice.Replacement)

internal/app/cache_command_compat_test.go

@@ -0,0 +1,111 @@
+// 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"
+	"strings"
+	"testing"
+
+	"github.com/spf13/cobra"
+)
+
+func TestCrossPlatformCoverageCacheDeprecatedCompatShim(t *testing.T) {
+	root := NewRootCommand()
+	group := mustFindCommand(t, root, "cache")
+	if group.Hidden || group.Deprecated == "" || !group.Runnable() {
+		t.Fatalf("cache group contract: hidden=%v deprecated=%q runnable=%v", group.Hidden, group.Deprecated, group.Runnable())
+	}
+	if group.IsAvailableCommand() {
+		t.Fatal("deprecated cache group must not be IsAvailableCommand")
+	}
+
+	for _, leaf := range []string{"refresh", "status", "clean"} {
+		cmd := mustFindCommand(t, root, "cache", leaf)
+		if cmd.Hidden || cmd.Deprecated == "" || !cmd.Runnable() {
+			t.Fatalf("cache %s contract: hidden=%v deprecated=%q runnable=%v", leaf, cmd.Hidden, cmd.Deprecated, cmd.Runnable())
+		}
+		if cmd.IsAvailableCommand() {
+			t.Fatalf("deprecated cache %s must not be IsAvailableCommand", leaf)
+		}
+	}
+
+	var out bytes.Buffer
+	cmd := NewRootCommand()
+	cmd.SetOut(&out)
+	cmd.SetErr(&out)
+	cmd.SetArgs([]string{"cache", "refresh", "--format", "json"})
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("cache refresh compatibility stub: %v\n%s", err, out.String())
+	}
+	got := out.String()
+	for _, want := range []string{`"status":"deprecated"`, `"command":"dws cache refresh"`, "不再支持", "服务发现已下线"} {
+		if !strings.Contains(got, want) {
+			t.Fatalf("cache refresh output missing %q:\n%s", want, got)
+		}
+	}
+
+	for _, format := range []string{"", "json", "pretty", "table"} {
+		var buf bytes.Buffer
+		parent := &cobra.Command{Use: "dws"}
+		parent.PersistentFlags().String("format", format, "")
+		parent.SetOut(&buf)
+		sub := &cobra.Command{Use: "cache"}
+		parent.AddCommand(sub)
+		if err := printCacheCompatNotice(sub, "dws cache status"); err != nil {
+			t.Fatalf("format=%q: %v", format, err)
+		}
+		text := buf.String()
+		if !strings.Contains(text, "不再支持") && !strings.Contains(text, "服务发现已下线") {
+			t.Fatalf("format=%q missing notice:\n%s", format, text)
+		}
+		if format == "" || format == "json" || format == "pretty" {
+			if !strings.Contains(text, `"status":"deprecated"`) && !strings.Contains(text, `"status": "deprecated"`) {
+				t.Fatalf("format=%q missing deprecated JSON status:\n%s", format, text)
+			}
+		}
+	}
+
+	for _, format := range []string{"pretty", "table"} {
+		parent := &cobra.Command{Use: "dws"}
+		parent.PersistentFlags().String("format", format, "")
+		parent.SetOut(failWriter{})
+		sub := &cobra.Command{Use: "cache"}
+		parent.AddCommand(sub)
+		if err := printCacheCompatNotice(sub, "dws cache clean"); err == nil || !strings.Contains(err.Error(), "write failed") {
+			t.Fatalf("format=%q write failure = %v, want write failed", format, err)
+		}
+	}
+
+	parent := newCacheCommand()
+	var parentOut bytes.Buffer
+	rootWrap := &cobra.Command{Use: "dws"}
+	rootWrap.PersistentFlags().String("format", "json", "")
+	rootWrap.SetOut(&parentOut)
+	rootWrap.AddCommand(parent)
+	parent.SetOut(&parentOut)
+	if err := parent.RunE(parent, nil); err != nil {
+		t.Fatalf("cache parent RunE = %v, want nil success", err)
+	}
+	if !strings.Contains(parentOut.String(), `"command":"dws cache"`) {
+		t.Fatalf("cache parent notice missing command:\n%s", parentOut.String())
+	}
+
+	cache := newCacheCommand()
+	cache.SetOut(&bytes.Buffer{})
+	cache.SetArgs([]string{"status"})
+	if err := cache.Execute(); err != nil {
+		t.Fatal(err)
+	}
+}

internal/app/catalog_command.go

@@ -1,11 +1,10 @@
 package app
 
 import (
-	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/cli"
 	"github.com/spf13/cobra"
 )
 
-func newCatalogCommand(_ cli.CatalogLoader) *cobra.Command {
+func newCatalogCommand() *cobra.Command {
 	return &cobra.Command{
 		Use:               "catalog",
 		Short:             "查看服务目录 (静态端点模式)",

internal/app/command_path_fallback_badcase_replay_test.go

@@ -0,0 +1,301 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0
+
+package app
+
+import (
+	_ "embed"
+	"encoding/json"
+	stderrors "errors"
+	"fmt"
+	"io"
+	"reflect"
+	"strings"
+	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/cli"
+	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/pipeline"
+)
+
+//go:embed testdata/shortcut_hallucination_badcases_20260728.json
+var shortcutHallucinationBadcases20260728JSON []byte
+
+type shortcutHallucinationReplayCorpus struct {
+	SourceReport    string                               `json:"source_report"`
+	SourceFile      string                               `json:"source_file"`
+	SourceDWSCommit string                               `json:"source_dws_commit"`
+	Model           string                               `json:"model"`
+	ExpectedCount   int                                  `json:"expected_count"`
+	Badcases        []shortcutHallucinationReplayBadcase `json:"badcases"`
+}
+
+type shortcutHallucinationReplayBadcase struct {
+	ID               string `json:"id"`
+	CaseID           string `json:"case_id"`
+	Run              int    `json:"run"`
+	CommandIndex     int    `json:"command_index"`
+	Turn             int    `json:"turn"`
+	SourcePath       string `json:"source_path"`
+	ExpectedOutcome  string `json:"expected_outcome"`
+	Raw              string `json:"raw"`
+	OriginalExitCode int    `json:"original_exit_code"`
+	IsHelp           bool   `json:"is_help"`
+}
+
+func TestCrossPlatformCoverageShortcutHallucinationBadcases20260728Replay(t *testing.T) {
+	var corpus shortcutHallucinationReplayCorpus
+	if err := json.Unmarshal(shortcutHallucinationBadcases20260728JSON, &corpus); err != nil {
+		t.Fatalf("decode historical shortcut badcase corpus: %v", err)
+	}
+	if corpus.SourceReport != "param_hallucination_20260728_120943" ||
+		corpus.SourceFile != "raw_dashscope_qwen3_7-max_20260728_120943.json" ||
+		corpus.SourceDWSCommit != "a8e83e5" || corpus.Model != "dashscope/qwen3.7-max" {
+		t.Fatalf("unexpected historical corpus provenance: %#v", corpus)
+	}
+	if corpus.ExpectedCount != 52 || len(corpus.Badcases) != corpus.ExpectedCount {
+		t.Fatalf("historical shortcut badcases = %d, expected_count=%d; want 52", len(corpus.Badcases), corpus.ExpectedCount)
+	}
+
+	wantOutcomeCounts := map[string]int{
+		"rewrite":   8,
+		"ambiguous": 44,
+	}
+	wantSourceCounts := map[string]int{
+		"chat +group-member-list": 1,
+		"chat +group-send-text":   1,
+		"chat +list-group-bots":   1,
+		"chat +list-robot":        1,
+		"chat +list-robots":       1,
+		"chat +members":           3,
+		"chat +message-list":      1,
+		"chat +read-single":       6,
+		"chat +rename-group":      1,
+		"chat +send":              4,
+		"chat +send-by-bot":       3,
+		"chat +send-dm":           2,
+		"chat +send-file":         15,
+		"chat +send-image":        3,
+		"chat +send-media":        2,
+		"chat +send-message":      3,
+		"chat +send-single":       1,
+		"chat +send-text":         2,
+		"chat +send-to":           1,
+	}
+	rewriteTargets := map[string]string{
+		"chat +members":           "chat +group-members",
+		"chat +group-member-list": "chat +group-members",
+		"chat +list-group-bots":   "chat +chat-bots",
+		"chat +list-robot":        "chat +chat-bots",
+		"chat +list-robots":       "chat +chat-bots",
+		"chat +rename-group":      "chat +chat-update",
+	}
+
+	seenIDs := make(map[string]bool, len(corpus.Badcases))
+	gotOutcomeCounts := make(map[string]int)
+	gotSourceCounts := make(map[string]int)
+	for _, badcase := range corpus.Badcases {
+		badcase := badcase
+		t.Run(badcase.ID, func(t *testing.T) {
+			if badcase.ID == "" || seenIDs[badcase.ID] {
+				t.Fatalf("missing or duplicate historical badcase id %q", badcase.ID)
+			}
+			seenIDs[badcase.ID] = true
+			gotOutcomeCounts[badcase.ExpectedOutcome]++
+			gotSourceCounts[badcase.SourcePath]++
+
+			args := historicalShortcutBadcaseArgv(t, badcase.Raw)
+			if len(args) < 2 || strings.Join(args[:2], " ") != badcase.SourcePath {
+				t.Fatalf("raw argv source = %v, fixture source_path=%q", args, badcase.SourcePath)
+			}
+
+			root := NewSchemaSourceRootCommand()
+			root.SetOut(io.Discard)
+			root.SetErr(io.Discard)
+			root.SetArgs(args)
+			ctx, err := pipeline.RunPreParseArgs(root, newPipelineEngine(), args)
+			switch badcase.ExpectedOutcome {
+			case "rewrite":
+				assertHistoricalShortcutRewrite(t, badcase, rewriteTargets[badcase.SourcePath], ctx, err)
+			case "ambiguous":
+				assertHistoricalShortcutReason(t, badcase, ctx, err, "ambiguous_command_fallback")
+				entry, ok := cli.LookupCommandPathFallback(badcase.SourcePath)
+				if !ok || entry.Mode != cli.CommandPathFallbackAmbiguous || len(entry.Candidates) < 2 {
+					t.Fatalf("ambiguous fallback table entry = %#v, %v", entry, ok)
+				}
+			case "unknown_shortcut":
+				assertHistoricalShortcutReason(t, badcase, ctx, err, "unknown_shortcut")
+				if entry, ok := cli.LookupCommandPathFallback(badcase.SourcePath); ok {
+					t.Fatalf("contract-incomplete path unexpectedly entered fallback table: %#v", entry)
+				}
+			default:
+				t.Fatalf("unsupported expected_outcome %q", badcase.ExpectedOutcome)
+			}
+		})
+	}
+	if !reflect.DeepEqual(gotOutcomeCounts, wantOutcomeCounts) {
+		t.Errorf("historical outcome counts = %v, want %v", gotOutcomeCounts, wantOutcomeCounts)
+	}
+	if !reflect.DeepEqual(gotSourceCounts, wantSourceCounts) {
+		t.Errorf("historical source counts = %v, want %v", gotSourceCounts, wantSourceCounts)
+	}
+}
+
+func TestCrossPlatformCoverageShortcutHallucinationMerged20260720Replay(t *testing.T) {
+	tests := []struct {
+		id          string
+		raw         string
+		occurrences int
+		outcome     string
+		target      string
+	}{
+		{
+			id:          "dws_im_v2_0013-search-group",
+			raw:         `dws chat +search-group --name "dws测试群02" --format json`,
+			occurrences: 1,
+			outcome:     "official_alias",
+			target:      "chat +chat-search",
+		},
+		{
+			id:          "dws_oa_0017-list-processes",
+			raw:         `dws oa +list-processes --format json --limit 50`,
+			occurrences: 2,
+			outcome:     "ambiguous",
+		},
+	}
+	totalOccurrences := 0
+	for _, test := range tests {
+		test := test
+		t.Run(test.id, func(t *testing.T) {
+			totalOccurrences += test.occurrences
+			args := historicalShortcutBadcaseArgv(t, test.raw)
+			root := NewSchemaSourceRootCommand()
+			root.SetOut(io.Discard)
+			root.SetErr(io.Discard)
+			root.SetArgs(args)
+			ctx, err := pipeline.RunPreParseArgs(root, newPipelineEngine(), args)
+			badcase := shortcutHallucinationReplayBadcase{
+				ID:              test.id,
+				SourcePath:      strings.Join(args[:2], " "),
+				ExpectedOutcome: test.outcome,
+				Raw:             test.raw,
+			}
+			switch test.outcome {
+			case "rewrite":
+				assertHistoricalShortcutRewrite(t, badcase, test.target, ctx, err)
+			case "official_alias":
+				assertHistoricalOfficialAlias(t, badcase, test.target, ctx, err)
+			case "ambiguous":
+				assertHistoricalShortcutReason(t, badcase, ctx, err, "ambiguous_command_fallback")
+			default:
+				t.Fatalf("unsupported merged expected outcome %q", test.outcome)
+			}
+		})
+	}
+	if totalOccurrences != 3 {
+		t.Fatalf("merged shortcut hallucination occurrences = %d, want 3", totalOccurrences)
+	}
+}
+
+func assertHistoricalOfficialAlias(
+	t *testing.T,
+	badcase shortcutHallucinationReplayBadcase,
+	wantTarget string,
+	ctx *pipeline.Context,
+	err error,
+) {
+	t.Helper()
+	if err != nil {
+		t.Fatalf("historical official alias %q returned error: %v", badcase.SourcePath, err)
+	}
+	if wantTarget == "" || ctx == nil || ctx.Command != "dws "+wantTarget {
+		t.Fatalf("historical official alias context = %#v; want command dws %s", ctx, wantTarget)
+	}
+	for _, correction := range ctx.Corrections {
+		if correction.Handler == "command-path-fallback" {
+			t.Fatalf("historical official alias received fallback correction: %#v", ctx.Corrections)
+		}
+	}
+	if entry, ok := cli.LookupCommandPathFallback(badcase.SourcePath); ok {
+		t.Fatalf("official alias unexpectedly remains in fallback table: %#v", entry)
+	}
+}
+
+func historicalShortcutBadcaseArgv(t *testing.T, raw string) []string {
+	t.Helper()
+	command := strings.TrimSpace(raw)
+	for _, suffix := range []string{" 2>&1 | head -50", " 2>&1"} {
+		command = strings.TrimSuffix(command, suffix)
+	}
+	argv, err := cli.ParseAgentExampleArgv(command)
+	if err != nil {
+		t.Fatalf("parse historical raw command %q without a shell: %v", raw, err)
+	}
+	if len(argv) < 3 || argv[0] != "dws" {
+		t.Fatalf("historical raw command did not produce dws argv: %q => %v", raw, argv)
+	}
+	return append([]string(nil), argv[1:]...)
+}
+
+func assertHistoricalShortcutRewrite(
+	t *testing.T,
+	badcase shortcutHallucinationReplayBadcase,
+	wantTarget string,
+	ctx *pipeline.Context,
+	err error,
+) {
+	t.Helper()
+	if wantTarget == "" {
+		t.Fatalf("historical rewrite %q has no reviewed target", badcase.SourcePath)
+	}
+	if ctx == nil || ctx.Command != "dws "+wantTarget {
+		t.Fatalf("historical rewrite context = %#v, error=%v; want command dws %s", ctx, err, wantTarget)
+	}
+	found := false
+	for _, correction := range ctx.Corrections {
+		if correction.Handler == "command-path-fallback" && correction.Original == badcase.SourcePath && correction.Corrected == wantTarget {
+			found = true
+			break
+		}
+	}
+	if !found {
+		t.Fatalf("historical rewrite corrections = %#v; want %q -> %q", ctx.Corrections, badcase.SourcePath, wantTarget)
+	}
+	wantPrefix := strings.Fields(wantTarget)
+	if len(ctx.Args) < len(wantPrefix) || !reflect.DeepEqual(ctx.Args[:len(wantPrefix)], wantPrefix) {
+		t.Fatalf("historical rewrite argv = %v, want prefix %v", ctx.Args, wantPrefix)
+	}
+	if reason := structuredShortcutReplayReason(err); reason == "unknown_shortcut" || reason == "ambiguous_command_fallback" {
+		t.Fatalf("historical rewrite returned command-resolution reason %q: %v", reason, err)
+	}
+}
+
+func assertHistoricalShortcutReason(
+	t *testing.T,
+	badcase shortcutHallucinationReplayBadcase,
+	ctx *pipeline.Context,
+	err error,
+	wantReason string,
+) {
+	t.Helper()
+	if ctx == nil {
+		t.Fatalf("historical %s badcase returned nil context: %v", wantReason, err)
+	}
+	if got := structuredShortcutReplayReason(err); got != wantReason {
+		t.Fatalf("historical badcase %q reason = %q, error=%v; want %q (original exit=%d help=%v)", badcase.Raw, got, err, wantReason, badcase.OriginalExitCode, badcase.IsHelp)
+	}
+	if strings.Contains(strings.ToLower(fmt.Sprint(err)), "unknown flag") {
+		t.Fatalf("historical badcase %q regressed to unknown flag: %v", badcase.Raw, err)
+	}
+}
+
+func structuredShortcutReplayReason(err error) string {
+	if err == nil {
+		return ""
+	}
+	var structured *apperrors.Error
+	if stderrors.As(err, &structured) {
+		return structured.Reason
+	}
+	return ""
+}

internal/app/command_path_fallback_e2e_test.go

@@ -0,0 +1,603 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0
+
+package app
+
+import (
+	"bytes"
+	"context"
+	stderrors "errors"
+	"io"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"reflect"
+	"strings"
+	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/cli"
+	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/pipeline"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/cmdutil"
+	"github.com/spf13/cobra"
+)
+
+const (
+	runtimeShortcutFallbackChildEnv  = "DWS_RUNTIME_SHORTCUT_FALLBACK_CHILD"
+	runtimeShortcutFallbackConfigEnv = "DWS_RUNTIME_SHORTCUT_FALLBACK_CONFIG_DIR"
+)
+
+func TestCrossPlatformCoverageRuntimeUserShortcutTakesPrecedenceOverReviewedFallback(t *testing.T) {
+	if os.Getenv(runtimeShortcutFallbackChildEnv) == "1" {
+		t.Setenv("DWS_CONFIG_DIR", os.Getenv(runtimeShortcutFallbackConfigEnv))
+		engine := newPipelineEngine()
+		root := NewRootCommandWithEngine(context.Background(), engine)
+		runtimeCommand := exactAppCommand(root, "chat +members")
+		if runtimeCommand == nil || !runtimeCommand.Runnable() || cmdutil.IsHintOnlyCommand(runtimeCommand) {
+			var userDefined []string
+			for _, candidate := range shortcut.All() {
+				if candidate.UserDefined {
+					userDefined = append(userDefined, candidate.Service+" "+candidate.Command)
+				}
+			}
+			t.Fatalf("runtime shortcut was not mounted as an executable command: command=%#v user_defined=%v config=%q", runtimeCommand, userDefined, os.Getenv("DWS_CONFIG_DIR"))
+		}
+		root.SetOut(io.Discard)
+		root.SetErr(io.Discard)
+		args := []string{"chat", "+members", "--sentinel", "fixture", "--mock", "--format", "json"}
+		root.SetArgs(args)
+		ctx, err := pipeline.RunPreParseArgs(root, engine, args)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if ctx == nil || ctx.Command != "dws chat +members" {
+			t.Fatalf("runtime shortcut context = %#v", ctx)
+		}
+		assertNoCommandPathFallbackCorrection(t, ctx)
+		if err := root.Execute(); err != nil {
+			t.Fatalf("runtime shortcut execute: %v", err)
+		}
+		return
+	}
+
+	configDir := t.TempDir()
+	shortcutDir := filepath.Join(configDir, "shortcuts")
+	if err := os.MkdirAll(shortcutDir, 0o700); err != nil {
+		t.Fatal(err)
+	}
+	definition := `version: 1
+service: chat
+command: "+members"
+product: chat
+description: runtime members fixture
+execute:
+  tool: fixture_user_members
+  bind:
+    sentinel: "${sentinel}"
+flags:
+  - name: sentinel
+    type: string
+    required: true
+    desc: fixture sentinel
+`
+	if err := os.WriteFile(filepath.Join(shortcutDir, "chat.members.yaml"), []byte(definition), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	command := exec.Command(os.Args[0], "-test.run=^TestCrossPlatformCoverageRuntimeUserShortcutTakesPrecedenceOverReviewedFallback$", "-test.count=1")
+	command.Env = append(os.Environ(), runtimeShortcutFallbackConfigEnv+"="+configDir, runtimeShortcutFallbackChildEnv+"=1")
+	output, err := command.CombinedOutput()
+	if err != nil {
+		t.Fatalf("runtime shortcut child failed: %v\n%s", err, strings.TrimSpace(string(output)))
+	}
+	if !strings.Contains(string(output), `"_tool": "fixture_user_members"`) {
+		t.Fatalf("runtime shortcut child used the wrong command:\n%s", strings.TrimSpace(string(output)))
+	}
+}
+
+func TestCrossPlatformCoverageReviewedCommandFallbacksReachCanonicalDryRunPayload(t *testing.T) {
+	_, canonicalQuery, canonicalQueryAttempts, err := executeParamAliasDryRunE2E(t,
+		"chat", "+chat-search", "--query", "project", "--dry-run",
+	)
+	if err != nil || len(canonicalQueryAttempts) != 0 {
+		t.Fatalf("canonical query preview = %#v, attempts=%v, error=%v", canonicalQuery, canonicalQueryAttempts, err)
+	}
+	tests := []struct {
+		name        string
+		args        []string
+		wantCommand string
+		wantPreview paramAliasDryRunPreview
+	}{
+		{
+			name:        "group search query",
+			args:        []string{"chat", "+group-search", "--query", "project", "--dry-run"},
+			wantCommand: "dws chat +chat-search",
+			wantPreview: canonicalQuery,
+		},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			ctx, preview, attempts, executeErr := executeParamAliasDryRunE2E(t, test.args...)
+			if executeErr != nil {
+				t.Fatalf("fallback execute error = %v", executeErr)
+			}
+			if len(attempts) != 0 {
+				t.Fatalf("fallback crossed dry-run dispatch boundary: %#v", attempts)
+			}
+			if !reflect.DeepEqual(preview, test.wantPreview) {
+				t.Fatalf("fallback preview = %#v, want canonical %#v", preview, test.wantPreview)
+			}
+			if ctx == nil || ctx.Command != test.wantCommand || len(ctx.Corrections) == 0 {
+				t.Fatalf("fallback context = %#v, want command %q", ctx, test.wantCommand)
+			}
+			correction := ctx.Corrections[0]
+			if correction.Handler != "command-path-fallback" || correction.Kind != "reviewed-fallback" {
+				t.Fatalf("fallback correction = %#v", correction)
+			}
+		})
+	}
+}
+
+func TestCrossPlatformCoverageOfficialCommandAliasesBypassFallbackAndReachEquivalentPayload(t *testing.T) {
+	_, canonicalQuery, canonicalQueryAttempts, err := executeParamAliasDryRunE2E(t,
+		"chat", "+chat-search", "--query", "project", "--dry-run",
+	)
+	if err != nil || len(canonicalQueryAttempts) != 0 {
+		t.Fatalf("canonical query preview = %#v, attempts=%v, error=%v", canonicalQuery, canonicalQueryAttempts, err)
+	}
+	_, canonicalKeyword, canonicalKeywordAttempts, err := executeParamAliasDryRunE2E(t,
+		"chat", "+chat-search", "--keyword", "project", "--dry-run",
+	)
+	if err != nil || len(canonicalKeywordAttempts) != 0 {
+		t.Fatalf("canonical keyword preview = %#v, attempts=%v, error=%v", canonicalKeyword, canonicalKeywordAttempts, err)
+	}
+	_, nativeCanonical, nativeCanonicalAttempts, err := executeParamAliasDryRunE2E(t,
+		"chat", "search", "--query", "project", "--dry-run",
+	)
+	if err != nil || len(nativeCanonicalAttempts) != 0 {
+		t.Fatalf("native canonical preview = %#v, attempts=%v, error=%v", nativeCanonical, nativeCanonicalAttempts, err)
+	}
+
+	tests := []struct {
+		name        string
+		args        []string
+		wantCommand string
+		wantPreview paramAliasDryRunPreview
+	}{
+		{
+			name:        "search group shortcut alias",
+			args:        []string{"chat", "+search-group", "--keyword", "project", "--dry-run"},
+			wantCommand: "dws chat +chat-search",
+			wantPreview: canonicalKeyword,
+		},
+		{
+			name:        "chat group search shortcut alias",
+			args:        []string{"chat", "+chat-group-search", "--query", "project", "--dry-run"},
+			wantCommand: "dws chat +chat-search",
+			wantPreview: canonicalQuery,
+		},
+		{
+			name:        "hidden native compatibility leaf",
+			args:        []string{"chat", "group", "search", "--query", "project", "--dry-run"},
+			wantCommand: "dws chat group search",
+			wantPreview: nativeCanonical,
+		},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			ctx, preview, attempts, executeErr := executeParamAliasDryRunE2E(t, test.args...)
+			if executeErr != nil {
+				t.Fatalf("official alias execute error = %v", executeErr)
+			}
+			if len(attempts) != 0 {
+				t.Fatalf("official alias crossed dry-run dispatch boundary: %#v", attempts)
+			}
+			if !reflect.DeepEqual(preview, test.wantPreview) {
+				t.Fatalf("official alias preview = %#v, want canonical %#v", preview, test.wantPreview)
+			}
+			if ctx == nil || ctx.Command != test.wantCommand {
+				t.Fatalf("official alias context = %#v, want command %q", ctx, test.wantCommand)
+			}
+			assertNoCommandPathFallbackCorrection(t, ctx)
+		})
+	}
+}
+
+func TestCrossPlatformCoverageReviewedReadFallbacksResolveCanonicalLeafBeforeParameterValidation(t *testing.T) {
+	tests := []struct {
+		name   string
+		args   []string
+		target string
+	}{
+		{
+			name:   "members",
+			args:   []string{"chat", "+members", "--group", "Fixture Group"},
+			target: "chat +group-members",
+		},
+		{
+			name:   "group member list",
+			args:   []string{"chat", "+group-member-list", "--group-name", "Fixture Group"},
+			target: "chat +group-members",
+		},
+		{
+			name:   "list group bots",
+			args:   []string{"chat", "+list-group-bots", "--group", "cid-fixture"},
+			target: "chat +chat-bots",
+		},
+		{
+			name:   "list robot",
+			args:   []string{"chat", "+list-robot", "--group", "cid-fixture"},
+			target: "chat +chat-bots",
+		},
+		{
+			name:   "list robots",
+			args:   []string{"chat", "+list-robots", "--group", "cid-fixture"},
+			target: "chat +chat-bots",
+		},
+		{
+			name:   "bot list",
+			args:   []string{"chat", "+bot-list", "--group", "cid-fixture"},
+			target: "chat +chat-bots",
+		},
+		{
+			name:   "conversation detail",
+			args:   []string{"chat", "+conversation-detail", "--group", "cid-fixture"},
+			target: "chat +conversation-info",
+		},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			root := NewSchemaSourceRootCommand()
+			root.SetOut(io.Discard)
+			root.SetErr(io.Discard)
+			root.SetArgs(test.args)
+			ctx, err := pipeline.RunPreParseArgs(root, newPipelineEngine(), test.args)
+			if err != nil {
+				t.Fatal(err)
+			}
+			if ctx == nil || ctx.Command != "dws "+test.target || len(ctx.Corrections) == 0 {
+				t.Fatalf("read fallback context = %#v", ctx)
+			}
+			wantPrefix := strings.Fields(test.target)
+			if len(ctx.Args) < len(wantPrefix) || !reflect.DeepEqual(ctx.Args[:len(wantPrefix)], wantPrefix) {
+				t.Fatalf("read fallback args = %v, want prefix %v", ctx.Args, wantPrefix)
+			}
+		})
+	}
+}
+
+func TestCrossPlatformCoverageOfficialGroupMembersAliasBypassesCommandFallback(t *testing.T) {
+	args := []string{"chat", "+chat-group-members", "--conversation-id", "cid-fixture", "--member-types", "user"}
+	root := NewSchemaSourceRootCommand()
+	root.SetOut(io.Discard)
+	root.SetErr(io.Discard)
+	root.SetArgs(args)
+	ctx, err := pipeline.RunPreParseArgs(root, newPipelineEngine(), args)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if ctx == nil || ctx.Command != "dws chat +chat-members-list" {
+		t.Fatalf("official group-members alias context = %#v", ctx)
+	}
+	assertNoCommandPathFallbackCorrection(t, ctx)
+}
+
+func TestCrossPlatformCoverageReviewedRenameFallbackResolvesCanonicalLeafBeforeParameterValidation(t *testing.T) {
+	args := []string{"chat", "+rename-group", "--id", "cid-fixture", "--name", "Fixture Group"}
+	root := NewSchemaSourceRootCommand()
+	root.SetOut(io.Discard)
+	root.SetErr(io.Discard)
+	root.SetArgs(args)
+	ctx, err := pipeline.RunPreParseArgs(root, newPipelineEngine(), args)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if ctx == nil || ctx.Command != "dws chat +chat-update" || len(ctx.Corrections) == 0 {
+		t.Fatalf("rename fallback context = %#v", ctx)
+	}
+	wantPrefix := []string{"chat", "+chat-update"}
+	if len(ctx.Args) < len(wantPrefix) || !reflect.DeepEqual(ctx.Args[:len(wantPrefix)], wantPrefix) {
+		t.Fatalf("rename fallback args = %v, want prefix %v", ctx.Args, wantPrefix)
+	}
+}
+
+func TestCrossPlatformCoverageReviewedDocHistorySaveFallbacksPreserveArguments(t *testing.T) {
+	sources := []string{"+create-version", "+save-version", "+snapshot", "+version-create"}
+	for _, source := range sources {
+		t.Run(source, func(t *testing.T) {
+			args := []string{"doc", source, "--node", "node-fixture", "--mock", "--format", "json"}
+			root := NewSchemaSourceRootCommand()
+			root.SetOut(io.Discard)
+			root.SetErr(io.Discard)
+			root.SetArgs(args)
+			ctx, err := pipeline.RunPreParseArgs(root, newPipelineEngine(), args)
+			if err != nil {
+				t.Fatal(err)
+			}
+			if ctx == nil || ctx.Command != "dws doc +history-save" || len(ctx.Corrections) == 0 {
+				t.Fatalf("history-save fallback context = %#v", ctx)
+			}
+			wantArgs := []string{"doc", "+history-save", "--node", "node-fixture", "--mock", "--format", "json"}
+			if !reflect.DeepEqual(ctx.Args, wantArgs) {
+				t.Fatalf("history-save fallback args = %v, want %v", ctx.Args, wantArgs)
+			}
+			correction := ctx.Corrections[0]
+			if correction.Handler != "command-path-fallback" || correction.Kind != "reviewed-fallback" {
+				t.Fatalf("history-save correction = %#v", correction)
+			}
+		})
+	}
+}
+
+func TestCrossPlatformCoverageDocExportPDFRemainsUnknownShortcut(t *testing.T) {
+	if entry, ok := cli.LookupCommandPathFallback("doc +export-pdf"); ok {
+		t.Fatalf("+export-pdf must not receive a path-only fallback: %#v", entry)
+	}
+	root := NewSchemaSourceRootCommand()
+	root.SetOut(io.Discard)
+	root.SetErr(io.Discard)
+	args := []string{"doc", "+export-pdf", "--node", "node-fixture", "--mock", "--format", "json"}
+	root.SetArgs(args)
+	ctx, err := pipeline.RunPreParseArgs(root, newPipelineEngine(), args)
+	if ctx == nil {
+		t.Fatal("+export-pdf returned nil context")
+	}
+	var structured *apperrors.Error
+	if !stderrors.As(err, &structured) || structured.Reason != "unknown_shortcut" {
+		t.Fatalf("+export-pdf preparse error = %T %#v", err, err)
+	}
+	if len(ctx.Corrections) != 0 {
+		t.Fatalf("+export-pdf unexpectedly received corrections: %#v", ctx.Corrections)
+	}
+}
+
+func TestCrossPlatformCoverageReviewedAmbiguousCommandFallbackNeverDispatches(t *testing.T) {
+	tests := []struct {
+		path       string
+		candidates []string
+	}{
+		{path: "chat +group-send-text", candidates: []string{"chat +send-to-group", "chat +messages-send"}},
+		{path: "chat +message-list", candidates: []string{"chat +chat-messages", "chat +messages-list-direct", "chat +search-msg", "chat +unread-chats"}},
+		{path: "chat +read-single", candidates: []string{"chat +messages-list-direct", "chat +chat-messages"}},
+		{path: "chat +send", candidates: []string{"chat +messages-send", "chat +dm", "chat +send-to-group"}},
+		{path: "chat +send-by-bot", candidates: []string{"chat +messages-send", "chat message send-by-bot"}},
+		{path: "chat +send-dm", candidates: []string{"chat +dm", "chat +messages-send"}},
+		{path: "chat +send-message", candidates: []string{"chat +messages-send", "chat +dm", "chat +send-to-group"}},
+		{path: "chat +send-single", candidates: []string{"chat +dm", "chat +messages-send"}},
+		{path: "chat +send-text", candidates: []string{"chat +messages-send", "chat +dm", "chat +send-to-group"}},
+		{path: "chat +send-to", candidates: []string{"chat +messages-send", "chat +dm", "chat +send-to-group"}},
+		{path: "chat +send-file", candidates: []string{"chat +messages-send", "chat message send"}},
+		{path: "chat +send-image", candidates: []string{"chat +messages-send", "chat message send"}},
+		{path: "chat +send-media", candidates: []string{"chat +messages-send", "chat message send"}},
+		{path: "chat +conversation-category-list", candidates: []string{"chat +category-list", "chat +category-list-conversations"}},
+		{path: "chat +conversation-group-list", candidates: []string{"chat +category-list-conversations", "chat +conversation-list"}},
+		{path: "chat +list-my-groups", candidates: []string{"chat +my-groups", "chat +chat-list-mine", "chat +chat-list"}},
+		{path: "oa +list-processes", candidates: []string{"oa +list-forms", "oa +my-initiated", "oa approval list-initiated"}},
+	}
+	for _, test := range tests {
+		t.Run(test.path, func(t *testing.T) {
+			caller := &paramAliasCaptureCaller{}
+			args := append(strings.Fields(test.path), "--format", "json")
+			ctx, err := executeParamAliasE2E(t, caller, args...)
+			if ctx == nil {
+				t.Fatal("ambiguous command fallback returned nil context")
+			}
+			var structured *apperrors.Error
+			if !stderrors.As(err, &structured) || structured.Reason != "ambiguous_command_fallback" || structured.ExitCode() != 3 {
+				t.Fatalf("ambiguous error = %T %#v", err, err)
+			}
+			if len(structured.Actions) != len(test.candidates) || len(caller.calls) != 0 {
+				t.Fatalf("ambiguous actions=%v calls=%#v", structured.Actions, caller.calls)
+			}
+			for _, candidate := range test.candidates {
+				if !strings.Contains(structured.Hint, "dws "+candidate) {
+					t.Errorf("ambiguous hint %q missing candidate %q", structured.Hint, candidate)
+				}
+			}
+		})
+	}
+}
+
+func TestCrossPlatformCoverageCanonicalShortcutBadFlagDoesNotEnterCommandFallback(t *testing.T) {
+	root := NewSchemaSourceRootCommand()
+	root.SetOut(io.Discard)
+	root.SetErr(io.Discard)
+	args := []string{"chat", "+chat-search", "--definitely-not-a-real-flag", "project"}
+	root.SetArgs(args)
+	ctx, err := pipeline.RunPreParseArgs(root, newPipelineEngine(), args)
+	if err != nil {
+		t.Fatalf("preparse error = %v", err)
+	}
+	if ctx == nil || ctx.Command != "dws chat +chat-search" {
+		t.Fatalf("canonical context = %#v", ctx)
+	}
+	for _, correction := range ctx.Corrections {
+		if correction.Handler == "command-path-fallback" {
+			t.Fatalf("canonical command received fallback correction: %#v", ctx.Corrections)
+		}
+	}
+	if err := root.Execute(); err == nil || !strings.Contains(err.Error(), "unknown flag") {
+		t.Fatalf("canonical bad flag error = %v", err)
+	}
+}
+
+func TestCrossPlatformCoverageRewrittenShortcutStillUsesCanonicalParameterErrors(t *testing.T) {
+	tests := []struct {
+		name string
+		args []string
+		want string
+	}{
+		{
+			name: "missing required query",
+			args: []string{"chat", "+group-search", "--dry-run"},
+			want: "请至少指定 --query、--keyword 之一",
+		},
+		{
+			name: "unknown canonical flag",
+			args: []string{"chat", "+group-search", "--definitely-not-a-real-flag", "project"},
+			want: "unknown flag",
+		},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			root := NewSchemaSourceRootCommand()
+			root.SetOut(io.Discard)
+			root.SetErr(io.Discard)
+			root.SetArgs(test.args)
+			ctx, err := pipeline.RunPreParseArgs(root, newPipelineEngine(), test.args)
+			if err != nil {
+				t.Fatalf("preparse error = %v", err)
+			}
+			if ctx == nil || ctx.Command != "dws chat +chat-search" || len(ctx.Corrections) == 0 ||
+				ctx.Corrections[0].Handler != "command-path-fallback" {
+				t.Fatalf("rewritten context = %#v", ctx)
+			}
+			if err := root.Execute(); err == nil || !strings.Contains(err.Error(), test.want) {
+				t.Fatalf("canonical parameter error = %v, want containing %q", err, test.want)
+			}
+		})
+	}
+}
+
+func TestCrossPlatformCoverageCommandFallbackNamesStayOutOfHelpSchemaAndShortcutCatalog(t *testing.T) {
+	invalidShortcuts := map[string]bool{
+		"+bot-list":                   true,
+		"+conversation-detail":        true,
+		"+conversation-category-list": true,
+		"+conversation-group-list":    true,
+		"+list-my-groups":             true,
+		"+group-search":               true,
+		"+members":                    true,
+		"+group-member-list":          true,
+		"+list-group-bots":            true,
+		"+list-robot":                 true,
+		"+list-robots":                true,
+		"+message-list":               true,
+		"+read-single":                true,
+		"+rename-group":               true,
+		"+send":                       true,
+		"+send-by-bot":                true,
+		"+send-dm":                    true,
+		"+send-message":               true,
+		"+send-single":                true,
+		"+send-text":                  true,
+		"+send-to":                    true,
+		"+send-file":                  true,
+		"+send-image":                 true,
+		"+send-media":                 true,
+		"+group-send-text":            true,
+	}
+	root := NewSchemaSourceRootCommand()
+	chat := exactAppCommand(root, "chat")
+	if chat == nil {
+		t.Fatal("chat command missing")
+	}
+	for _, child := range chat.Commands() {
+		if invalidShortcuts[child.Name()] {
+			t.Fatalf("fallback name %q became a real command", child.Name())
+		}
+		for _, alias := range child.Aliases {
+			if invalidShortcuts[alias] {
+				t.Fatalf("fallback name %q became a Cobra alias", alias)
+			}
+		}
+	}
+	for path := range invalidShortcuts {
+		if _, ok := cli.ResolveMeta("chat " + path); ok {
+			t.Fatalf("fallback path %q leaked into embedded Schema", path)
+		}
+	}
+	for _, declared := range shortcut.All() {
+		if declared.Service == "chat" && invalidShortcuts[declared.Command] {
+			t.Fatalf("fallback name %q leaked into shortcut catalog", declared.Command)
+		}
+	}
+	if _, ok := cli.ResolveMeta("oa +list-processes"); ok {
+		t.Fatal("fallback path oa +list-processes leaked into embedded Schema")
+	}
+	for _, declared := range shortcut.All() {
+		if declared.Service == "oa" && declared.Command == "+list-processes" {
+			t.Fatal("fallback name +list-processes leaked into shortcut catalog")
+		}
+	}
+
+	group := exactAppCommand(root, "chat group")
+	searchCompatibility := exactAppCommand(root, "chat group search")
+	if group == nil || searchCompatibility == nil || !searchCompatibility.Hidden || cmdutil.IsHintOnlyCommand(searchCompatibility) {
+		t.Fatalf("chat group search must be a hidden executable compatibility leaf: group=%v search=%v", group, searchCompatibility)
+	}
+	var help bytes.Buffer
+	group.SetOut(&help)
+	if err := group.Help(); err != nil {
+		t.Fatal(err)
+	}
+	if strings.Contains(help.String(), "\n  search ") {
+		t.Fatalf("hidden fallback source leaked into group help:\n%s", help.String())
+	}
+}
+
+func TestCrossPlatformCoverageDocCommandFallbackNamesStayOutOfHelpSchemaAndShortcutCatalog(t *testing.T) {
+	invalidShortcuts := map[string]bool{
+		"+create-version": true,
+		"+save-version":   true,
+		"+snapshot":       true,
+		"+version-create": true,
+		"+export-pdf":     true,
+	}
+	root := NewSchemaSourceRootCommand()
+	doc := exactAppCommand(root, "doc")
+	if doc == nil {
+		t.Fatal("doc command missing")
+	}
+	for _, child := range doc.Commands() {
+		if invalidShortcuts[child.Name()] {
+			t.Fatalf("invalid shortcut %q became a real command", child.Name())
+		}
+		for _, alias := range child.Aliases {
+			if invalidShortcuts[alias] {
+				t.Fatalf("invalid shortcut %q became a Cobra alias", alias)
+			}
+		}
+	}
+	for path := range invalidShortcuts {
+		if _, ok := cli.ResolveMeta("doc " + path); ok {
+			t.Fatalf("invalid path %q leaked into embedded Schema", path)
+		}
+	}
+	for _, declared := range shortcut.All() {
+		if declared.Service == "doc" && invalidShortcuts[declared.Command] {
+			t.Fatalf("invalid shortcut %q leaked into shortcut catalog", declared.Command)
+		}
+	}
+}
+
+func assertNoCommandPathFallbackCorrection(t *testing.T, ctx *pipeline.Context) {
+	t.Helper()
+	for _, correction := range ctx.Corrections {
+		if correction.Handler == "command-path-fallback" {
+			t.Fatalf("official command unexpectedly received fallback correction: %#v", ctx.Corrections)
+		}
+	}
+}
+
+func exactAppCommand(root *cobra.Command, path string) *cobra.Command {
+	current := root
+	parts := strings.Fields(path)
+	if len(parts) > 0 && parts[0] == root.Name() {
+		parts = parts[1:]
+	}
+	for _, part := range parts {
+		var next *cobra.Command
+		for _, child := range current.Commands() {
+			if child.Name() == part {
+				next = child
+				break
+			}
+		}
+		if next == nil {
+			return nil
+		}
+		current = next
+	}
+	return current
+}

internal/app/coverage_edges_test.go

@@ -21,7 +21,6 @@ import (
 	"time"
 
 	authpkg "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/auth"
-	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/cli"
 	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
 	dwsevent "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event"
 	eventbus "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/bus"
@@ -33,7 +32,6 @@ import (
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/keychain"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/pat"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/plugin"
-	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/recovery"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/safety"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/transport"
 	upgradepkg "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/upgrade"
@@ -228,117 +226,6 @@ func TestCrossPlatformCoverageDocDownloadPureCoverage(t *testing.T) {
 	}
 }
 
-func TestCrossPlatformCoverageRecoveryPureCoverage(t *testing.T) {
-	if _, err := decodeRecoveryAttempts(nil, nil, "", ""); err != nil {
-		t.Fatal(err)
-	}
-	if _, err := decodeRecoveryAttempts(json.RawMessage("null"), nil, "", ""); err != nil {
-		t.Fatal(err)
-	}
-	if got, err := decodeRecoveryAttempts(json.RawMessage(`[{"command_summary":"one"}]`), nil, "", ""); err != nil || len(got) != 1 {
-		t.Fatalf("array attempts = %#v %v", got, err)
-	}
-	if _, err := decodeRecoveryAttempts(json.RawMessage("{"), nil, "", ""); err == nil {
-		t.Fatal("malformed attempts succeeded")
-	}
-	if got, err := decodeRecoveryAttempts(json.RawMessage("2"), []string{"a"}, "ok", ""); err != nil || len(got) != 2 {
-		t.Fatalf("legacy attempts = %#v %v", got, err)
-	}
-	if legacyRecoveryAttempts(0, nil, "", "") != nil || len(legacyRecoveryAttempts(1, nil, "", "")) != 1 {
-		t.Fatal("legacy attempts edge mismatch")
-	}
-
-	for _, args := range [][]string{
-		{"dws", "--debug", "doc", "get", "--node", "n"},
-		{"dws", "--format=json", "doc", "--", "ignored"},
-		{"dws", "--unknown", "value", "doc"},
-	} {
-		old := os.Args
-		os.Args = args
-		_ = currentCommandPath()
-		os.Args = old
-	}
-	for _, inv := range []executor.Invocation{
-		{LegacyPath: "legacy path"},
-		{CanonicalProduct: "doc", Tool: "get"},
-		{CanonicalProduct: "doc"},
-		{},
-	} {
-		old := os.Args
-		os.Args = []string{"dws"}
-		_ = runtimeCommandPath(inv)
-		os.Args = old
-	}
-	if cloneRecoveryArgs(nil) != nil {
-		t.Fatal("empty recovery args should clone to nil")
-	}
-	original := map[string]any{"x": 1}
-	clone := cloneRecoveryArgs(original)
-	clone["x"] = 2
-	if original["x"] != 1 {
-		t.Fatal("recovery args were not cloned")
-	}
-
-	if got, _ := (*recoveryRuntime)(nil).Search(context.Background(), "query", recovery.RecoveryContext{}); got.DocSearch.Status != "skipped" {
-		t.Fatalf("nil recovery search = %#v", got)
-	}
-	if got, _ := (&recoveryRuntime{}).Search(context.Background(), " ", recovery.RecoveryContext{}); got.DocSearch.Status != "skipped" {
-		t.Fatalf("blank recovery search = %#v", got)
-	}
-	if _, err := (*recoveryRuntime)(nil).CallToolDirect(context.Background(), "x", "y", nil); err == nil {
-		t.Fatal("nil recovery runtime call succeeded")
-	}
-	if _, err := (&recoveryRuntime{}).resolveEndpoint(context.Background(), "missing", "tool"); err == nil {
-		t.Fatal("missing recovery endpoint succeeded")
-	}
-	loaderErr := errors.New("catalog")
-	runtime := &recoveryRuntime{loader: cli.CatalogLoaderFrom(cli.Catalog{}, loaderErr)}
-	if _, err := runtime.resolveEndpoint(context.Background(), "missing", "tool"); !errors.Is(err, loaderErr) {
-		t.Fatalf("catalog recovery error = %v", err)
-	}
-	runtime.loader = cli.StaticLoader{Catalog: cli.Catalog{Products: []cli.CanonicalProduct{{ID: "empty"}, {ID: "ok", Endpoint: " https://catalog.test "}}}}
-	if _, err := runtime.resolveEndpoint(context.Background(), "empty", "tool"); err == nil {
-		t.Fatal("empty catalog endpoint succeeded")
-	}
-	if got, err := runtime.resolveEndpoint(context.Background(), "ok", "tool"); err != nil || got != "https://catalog.test" {
-		t.Fatalf("catalog endpoint = %q %v", got, err)
-	}
-	if recoveryRuntimeToken(nil) != "" || recoveryRuntimeToken(&GlobalFlags{Token: " token "}) != "token" {
-		t.Fatal("recovery token mismatch")
-	}
-	if toRecoveryToolResponse(nil) != nil {
-		t.Fatal("nil recovery response should stay nil")
-	}
-	response := toRecoveryToolResponse(&transport.ToolCallResult{IsError: true, Blocks: []transport.ContentBlock{{Type: "text", Text: "body"}}})
-	if response == nil || !response.IsError || len(response.Content) != 1 {
-		t.Fatalf("recovery response = %#v", response)
-	}
-
-	items := []any{map[string]any{"title": "A", "url": "u", "desc": "d"}, "skip", map[string]any{}}
-	for _, payload := range []map[string]any{
-		nil,
-		{"items": items},
-		{"data": map[string]any{"items": items}},
-		{"result": map[string]any{"items": items}},
-	} {
-		_ = parseDocSearchItemsFromMap(payload)
-	}
-	if toDocSearchItems("bad") != nil {
-		t.Fatal("non-list doc items accepted")
-	}
-	result := &transport.ToolCallResult{Content: map[string]any{}, Blocks: []transport.ContentBlock{{Text: "{"}, {Text: `{"items":[{"title":"B"}]}`}}}
-	if got := parseDocSearchItems(result); len(got) != 1 {
-		t.Fatalf("block doc items = %#v", got)
-	}
-	if parseDocSearchItems(nil) != nil {
-		t.Fatal("nil doc result should be nil")
-	}
-	searchItems := []recovery.DocSearchItem{{Title: "query", URL: "u"}, {Title: "other"}, {Title: "third"}, {Title: "fourth"}}
-	if len(rerankDocSearchHits("query", recovery.RecoveryContext{ToolName: "tool", CommandPath: []string{"doc"}}, searchItems)) != 3 || rerankDocSearchHits("", recovery.RecoveryContext{}, nil) != nil {
-		t.Fatal("doc search reranking mismatch")
-	}
-}
-
 func TestCrossPlatformCoverageSmallAppRegistryAndRootCoverage(t *testing.T) {
 	RegisterPluginAuth("coverage-registry", &PluginAuth{Token: "token"})
 	t.Cleanup(func() {
@@ -451,11 +338,14 @@ func TestCrossPlatformCoverageDirectRuntimeCoverage(t *testing.T) {
 		},
 	}
 	SetDynamicServers([]mcptypes.ServerDescriptor{{CLI: mcptypes.CLIOverlay{Skip: true}}, server, {CLI: mcptypes.CLIOverlay{ID: "empty"}}})
-	if got, ok := directRuntimeToolEndpoint("tool"); !ok || got != "https://one.test" {
+	if got, ok := directRuntimeEndpoint("unknown", "tool"); !ok || got != "https://one.test" {
 		t.Fatalf("tool endpoint = %q %v", got, ok)
 	}
-	if _, ok := directRuntimeToolEndpoint(" "); ok {
-		t.Fatal("blank tool endpoint resolved")
+	if got, ok := directRuntimeEndpoint("unknown", "override"); !ok || got != "https://one.test" {
+		t.Fatalf("tool override endpoint = %q %v", got, ok)
+	}
+	if _, ok := directRuntimeEndpoint("unknown", "skip"); ok {
+		t.Fatal("server-override tool endpoint resolved")
 	}
 	for _, id := range []string{"one", "cmd", "alias"} {
 		if got, ok := directRuntimeEndpoint(id, ""); !ok || got != "https://one.test" {
@@ -469,11 +359,6 @@ func TestCrossPlatformCoverageDirectRuntimeCoverage(t *testing.T) {
 		t.Fatalf("direct runtime IDs = %#v", ids)
 	}
 
-	t.Setenv(cli.CatalogFixtureEnv, "fixture")
-	if shouldUseDirectRuntime(executor.Invocation{Kind: "helper_invocation"}) {
-		t.Fatal("fixture should disable direct runtime")
-	}
-	t.Setenv(cli.CatalogFixtureEnv, "")
 	if !shouldUseDirectRuntime(executor.Invocation{Kind: "helper_invocation"}) || !shouldUseDirectRuntime(executor.Invocation{Kind: "compat_invocation"}) || shouldUseDirectRuntime(executor.Invocation{}) {
 		t.Fatal("direct runtime kind mismatch")
 	}
@@ -516,59 +401,6 @@ func TestCrossPlatformCoverageDirectRuntimeCoverage(t *testing.T) {
 	_ = defaultPATMCPEndpoint()
 }
 
-func TestCrossPlatformCoverageRecoveryLoadExecutionCoverage(t *testing.T) {
-	if _, err := loadRecoveryExecution(filepath.Join(t.TempDir(), "missing")); err == nil {
-		t.Fatal("missing recovery execution succeeded")
-	}
-	path := filepath.Join(t.TempDir(), "execution.json")
-	if err := os.WriteFile(path, []byte("{"), 0o600); err != nil {
-		t.Fatal(err)
-	}
-	if _, err := loadRecoveryExecution(path); err == nil {
-		t.Fatal("malformed recovery execution succeeded")
-	}
-	for name, body := range map[string]string{
-		"legacy": `{"action":" one ","attempt":2,"result":" ok ","error":" bad "}`,
-		"modern": `{"actions":["one"],"attempts":[{"command_summary":"one"}],"error_summary":"bad"}`,
-	} {
-		t.Run(name, func(t *testing.T) {
-			if err := os.WriteFile(path, []byte(body), 0o600); err != nil {
-				t.Fatal(err)
-			}
-			if got, err := loadRecoveryExecution(path); err != nil || len(got.Actions) != 1 || len(got.Attempts) == 0 {
-				t.Fatalf("loaded execution = %#v %v", got, err)
-			}
-		})
-	}
-}
-
-func TestCrossPlatformCoverageRecoveryRuntimeHTTP(t *testing.T) {
-	var result map[string]any = map[string]any{"content": []map[string]any{{"type": "text", "text": `{"items":[{"title":"query result","url":"u"}]}`}}}
-	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		var req struct {
-			ID int `json:"id"`
-		}
-		_ = json.NewDecoder(r.Body).Decode(&req)
-		_ = json.NewEncoder(w).Encode(map[string]any{"jsonrpc": "2.0", "id": req.ID, "result": result})
-	}))
-	defer server.Close()
-	SetDynamicServers([]mcptypes.ServerDescriptor{{Endpoint: server.URL, CLI: mcptypes.CLIOverlay{ID: "devdoc", Tools: []mcptypes.CLITool{{Name: "search_open_platform_docs_rag"}}}}})
-	t.Cleanup(func() { SetDynamicServers(nil) })
-	runtime := &recoveryRuntime{transport: transport.NewClient(server.Client()), flags: &GlobalFlags{Token: "token"}}
-	got, err := runtime.Search(context.Background(), "query", recovery.RecoveryContext{ToolName: "search"})
-	if err != nil || got.DocSearch.Status != "success" || len(got.KBHits) == 0 {
-		t.Fatalf("recovery search = %#v %v", got, err)
-	}
-	result = map[string]any{"isError": true, "content": []map[string]any{{"type": "text", "text": "failed"}}}
-	if _, err := runtime.CallToolDirect(context.Background(), "devdoc", "search_open_platform_docs_rag", nil); err == nil {
-		t.Fatal("recovery MCP error succeeded")
-	}
-	server.Close()
-	if _, err := runtime.CallToolDirect(context.Background(), "devdoc", "search_open_platform_docs_rag", nil); err == nil {
-		t.Fatal("recovery network error succeeded")
-	}
-}
-
 func TestCrossPlatformCoverageEventCommandPureCoverage(t *testing.T) {
 	oldEdition := edition.Get()
 	t.Cleanup(func() { edition.Override(oldEdition) })
@@ -765,7 +597,7 @@ func TestCrossPlatformCoverageVersionCacheCompletionCoverage(t *testing.T) {
 		child := &cobra.Command{Use: "child"}
 		root.AddCommand(child)
 		child.SetOut(io.Discard)
-		if err := printCacheCompatNotice(child, "status"); err != nil {
+		if err := printCacheCompatNotice(child, "dws cache status"); err != nil {
 			t.Fatalf("cache %s: %v", format, err)
 		}
 		root.RemoveCommand(child)
@@ -798,7 +630,6 @@ func TestCrossPlatformCoverageRuntimeRunnerRoutingCoverage(t *testing.T) {
 	}
 
 	r.transport = transport.NewClient(nil)
-	r.loader = cli.StaticLoader{}
 	r.globalFlags = &GlobalFlags{Mock: true}
 	if got, err := r.runSingle(context.Background(), inv, false); err != nil || got.Response["content"] == nil {
 		t.Fatalf("mock route = %#v %v", got, err)
@@ -809,18 +640,16 @@ func TestCrossPlatformCoverageRuntimeRunnerRoutingCoverage(t *testing.T) {
 	}
 	t.Setenv("DINGTALK_PRODUCT_MCP_URL", "")
 
+	// Dry-run is an execution barrier enforced by Run before endpoint
+	// resolution, so a dry-run invocation returns a local preview and never
+	// reaches handleCatalogMiss or the fallback runner.
 	r.globalFlags = &GlobalFlags{DryRun: true}
-	r.loader = cli.CatalogLoaderFrom(cli.Catalog{}, errors.New("load failure"))
-	if _, err := r.runSingle(context.Background(), inv, false); err == nil || !strings.Contains(err.Error(), "load failure") {
-		t.Fatalf("catalog failure = %v", err)
-	}
-	r.loader = cli.StaticLoader{}
-	if got, err := r.runSingle(context.Background(), inv, false); err != nil || got.Response["fallback"] != true || !fallback.last.DryRun {
-		t.Fatalf("dry catalog miss = %#v %v (invocation %#v)", got, err, fallback.last)
+	if got, err := r.Run(context.Background(), inv); err != nil || got.Response["dry_run"] != true || got.Response["fallback"] != nil {
+		t.Fatalf("dry endpoint miss = %#v %v", got, err)
 	}
 	r.globalFlags = &GlobalFlags{}
-	if _, err := r.runSingle(context.Background(), inv, false); err == nil {
-		t.Fatal("catalog miss succeeded")
+	if _, err := r.runSingle(context.Background(), inv, false); err == nil || !strings.Contains(err.Error(), "no dynamic endpoint registered for product or tool") {
+		t.Fatalf("endpoint miss = %v", err)
 	}
 	devInv := inv
 	devInv.CanonicalProduct = devappProductID
@@ -828,29 +657,20 @@ func TestCrossPlatformCoverageRuntimeRunnerRoutingCoverage(t *testing.T) {
 		t.Fatal("devapp catalog miss succeeded")
 	}
 
-	product := cli.CanonicalProduct{ID: "product", Endpoint: "https://catalog.test", Tools: []cli.ToolDescriptor{{RPCName: "tool"}}}
-	r.loader = cli.StaticLoader{Catalog: cli.Catalog{Products: []cli.CanonicalProduct{product}}}
-	r.globalFlags = &GlobalFlags{DryRun: true}
-	if got, err := r.runSingle(context.Background(), inv, false); err != nil || got.Response["endpoint"] != "https://catalog.test" {
-		t.Fatalf("catalog dry route = %#v %v", got, err)
-	}
-	product.Tools = nil
-	r.loader = cli.StaticLoader{Catalog: cli.Catalog{Products: []cli.CanonicalProduct{product}}}
 	SetDynamicServers([]mcptypes.ServerDescriptor{{Endpoint: "https://direct.test", CLI: mcptypes.CLIOverlay{ID: "product", Tools: []mcptypes.CLITool{{Name: "tool"}}}}})
 	t.Cleanup(func() { SetDynamicServers(nil) })
-	if got, err := r.runSingle(context.Background(), inv, false); err != nil || got.Response["endpoint"] != "https://direct.test" {
-		t.Fatalf("undeclared tool direct route = %#v %v", got, err)
+	directInv := inv
+	directInv.Kind = "helper_invocation"
+	directInv.DryRun = true
+	if got, err := r.runSingle(context.Background(), directInv, false); err != nil || got.Response["dry_run"] != true || got.Response["endpoint"] != "https://direct.test" {
+		t.Fatalf("direct runtime route = %#v %v", got, err)
 	}
 	SetDynamicServers(nil)
-	if got, err := r.runSingle(context.Background(), inv, false); err != nil || got.Response["fallback"] != true || !fallback.last.DryRun {
-		t.Fatalf("undeclared tool dry miss = %#v %v (invocation %#v)", got, err, fallback.last)
-	}
-
-	SetDynamicServers([]mcptypes.ServerDescriptor{{Endpoint: "https://owner.test", CLI: mcptypes.CLIOverlay{ID: "owner", Tools: []mcptypes.CLITool{{Name: "tool"}}}}})
-	product.Tools = []cli.ToolDescriptor{{RPCName: "tool"}}
-	r.loader = cli.StaticLoader{Catalog: cli.Catalog{Products: []cli.CanonicalProduct{product}}}
-	if got, err := r.runSingle(context.Background(), inv, false); err != nil || got.Response["endpoint"] != "https://owner.test" {
-		t.Fatalf("tool owner correction = %#v %v", got, err)
+	// With no dynamic endpoint registered, a dry-run helper invocation is still
+	// stopped by the Run barrier before endpoint resolution.
+	r.globalFlags = &GlobalFlags{DryRun: true}
+	if got, err := r.Run(context.Background(), directInv); err != nil || got.Response["dry_run"] != true || got.Response["fallback"] != nil {
+		t.Fatalf("direct runtime dry miss = %#v %v", got, err)
 	}
 
 	for _, result := range []executor.Result{{}, {Response: map[string]any{"content": "value"}}, {Response: map[string]any{"value": 1}}} {
@@ -961,7 +781,7 @@ func TestCrossPlatformCoverageExecuteInvocationCoverage(t *testing.T) {
 		t.Fatalf("stdio dry-run = %#v %v", got, err)
 	}
 	stdioInv.DryRun = false
-	if _, err := r.executeStdioInvocation(context.Background(), stdioInv); err == nil {
+	if _, err := r.executeStdioInvocationAtEndpoint(context.Background(), "", stdioInv); err == nil {
 		t.Fatal("missing stdio client succeeded")
 	}
 }
@@ -1764,9 +1584,6 @@ func TestCrossPlatformCoverageDoctorCommandCoverage(t *testing.T) {
 	}
 
 	for _, jsonOut := range []bool{false, true} {
-		if got := doctorCheckCache(io.Discard, jsonOut); got.Status != statusPass {
-			t.Fatal("cache check failed")
-		}
 		if got := doctorCheckPerf(io.Discard, jsonOut); got.Status != statusPass {
 			t.Fatalf("perf check = %#v", got)
 		}
@@ -2185,7 +2002,7 @@ func TestCrossPlatformCoverageSkillSetupRuntimeCoverage(t *testing.T) {
 	}
 	_ = os.Symlink(filepath.Join(mono, "SKILL.md"), filepath.Join(mono, "linked.md"))
 	multi := filepath.Join(t.TempDir(), "multi")
-	for _, name := range []string{"dws-shared", "dingtalk-a", "dingtalk-b"} {
+	for _, name := range []string{"dingtalk-shared", "dingtalk-a", "dingtalk-b"} {
 		dir := filepath.Join(multi, name)
 		if err := os.MkdirAll(dir, 0o755); err != nil {
 			t.Fatal(err)
@@ -2210,10 +2027,10 @@ func TestCrossPlatformCoverageSkillSetupRuntimeCoverage(t *testing.T) {
 	if _, err := os.Stat(filepath.Join(home, ".agents", "skills", "dws", "SKILL.md")); err != nil {
 		t.Fatal(err)
 	}
-	if output, warnings, err := run("--mode", "multi", "--source", multi, "--target", "agents", "--yes", "--skill", "a"); err != nil || !strings.Contains(output, "installed=2") || warnings == "" {
-		t.Fatalf("multi setup = %q / %q, %v", output, warnings, err)
+	if output, _, err := run("--mode", "multi", "--source", multi, "--target", "agents", "--yes", "--skill", "a"); err != nil || !strings.Contains(output, "installed=2") {
+		t.Fatalf("multi setup = %q, %v", output, err)
 	}
-	if _, err := os.Stat(filepath.Join(home, ".agents", "skills", "dws-shared", "SKILL.md")); err != nil {
+	if _, err := os.Stat(filepath.Join(home, ".agents", "skills", "dingtalk-shared", "SKILL.md")); err != nil {
 		t.Fatal(err)
 	}
 	if output, _, err := run("--mode", "multi", "--source", multi, "--target", "agents", "--yes", "--dry-run", "--exclude", "b"); err != nil || !strings.Contains(output, "DRY-RUN") {
@@ -2237,7 +2054,7 @@ func TestCrossPlatformCoverageSkillSetupRuntimeCoverage(t *testing.T) {
 }
 
 func TestCrossPlatformCoverageSkillSetupPureCoverage(t *testing.T) {
-	all := []string{"dingtalk-a", "dingtalk-b", "dws-shared"}
+	all := []string{"dingtalk-a", "dingtalk-b", "dingtalk-shared"}
 	for _, tc := range []struct {
 		include []string
 		exclude []string
@@ -2255,7 +2072,7 @@ func TestCrossPlatformCoverageSkillSetupPureCoverage(t *testing.T) {
 			t.Errorf("filter %#v/%#v = %v", tc.include, tc.exclude, err)
 		}
 	}
-	for _, selected := range [][]string{nil, {"dws-shared"}, {"dingtalk-a"}} {
+	for _, selected := range [][]string{nil, {"dingtalk-shared"}, {"dingtalk-a"}} {
 		_ = ensureMandatorySharedSkill(selected, all)
 	}
 	_ = ensureMandatorySharedSkill([]string{"dingtalk-a"}, []string{"dingtalk-a"})

internal/app/coverage_more_test.go

@@ -298,11 +298,10 @@ func TestCrossPlatformCoverageRootUtilityAndTimingCoverage(t *testing.T) {
 	deduplicateCommands(dedupRoot)
 	addPluginCommandsSafe(dedupRoot, []*cobra.Command{{Use: "same"}, {Use: "new"}})
 	_ = newCompletionCommand(dedupRoot)
-	_ = newCatalogCommand(nil)
+	_ = newCatalogCommand()
 	_ = newConfigCommand()
 	_ = newCacheCommand()
 	_ = newVersionCommand()
-	_ = newRecoveryCommand(context.Background(), nil, &GlobalFlags{})
 	_ = newAPICommand(&GlobalFlags{})
 	_ = NewRootCommand(context.Background())
 }

internal/app/coverage_pure_helpers_test.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 app
+
+import (
+	"context"
+	"errors"
+	"strings"
+	"testing"
+
+	authpkg "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/auth"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam"
+)
+
+func TestCrossPlatformCoverageTokenResolutionErrorBranches(t *testing.T) {
+	if err := tokenResolutionError(nil); err != nil {
+		t.Fatalf("nil error must pass through: %v", err)
+	}
+	if err := tokenResolutionError(context.Canceled); !errors.Is(err, context.Canceled) {
+		t.Fatalf("context cancellation must pass through unwrapped: %v", err)
+	}
+	if err := tokenResolutionError(context.DeadlineExceeded); !errors.Is(err, context.DeadlineExceeded) {
+		t.Fatalf("deadline exceeded must pass through unwrapped: %v", err)
+	}
+	if err := tokenResolutionError(authpkg.ErrTokenDataNotFound); err == nil ||
+		!strings.Contains(err.Error(), "dws auth login") {
+		t.Fatalf("not-found must become a login guidance error: %v", err)
+	}
+	generic := errors.New("keychain locked")
+	if err := tokenResolutionError(generic); err == nil ||
+		!strings.Contains(err.Error(), "resolve access token") || !errors.Is(err, generic) {
+		t.Fatalf("generic error must wrap with resolve access token: %v", err)
+	}
+}
+
+func TestCrossPlatformCoverageProfileSwitchCellsSameCorp(t *testing.T) {
+	profile := authpkg.Profile{CorpID: "corp-1", CorpName: "钉钉", UserName: "Alice", UserID: "u1"}
+	cfg := &authpkg.ProfilesConfig{Profiles: []authpkg.Profile{
+		profile,
+		{CorpID: "corp-1", CorpName: "钉钉", UserName: "Bob", UserID: "u2"},
+	}}
+	org, _ := profileSwitchProfileCells(profile, cfg)
+	if !strings.Contains(org, " / Alice") {
+		t.Fatalf("same-corp label must disambiguate with user name: %q", org)
+	}
+
+	noName := authpkg.Profile{CorpID: "corp-1", CorpName: "钉钉", UserID: "u1"}
+	org, _ = profileSwitchProfileCells(noName, cfg)
+	if !strings.Contains(org, " / u1") {
+		t.Fatalf("blank user name must fall back to user id: %q", org)
+	}
+
+	blankUser := authpkg.Profile{CorpID: "corp-1", CorpName: "钉钉"}
+	org, _ = profileSwitchProfileCells(blankUser, cfg)
+	if strings.Contains(org, " / ") {
+		t.Fatalf("blank user name and id must not append a suffix: %q", org)
+	}
+
+	org, _ = profileSwitchProfileCells(profile, nil)
+	if strings.Contains(org, " / ") {
+		t.Fatalf("nil config must not append a suffix: %q", org)
+	}
+}
+
+func TestCrossPlatformCoverageAuthRefreshRetryHelpers(t *testing.T) {
+	var nilErr *authRefreshFailureError
+	if got := nilErr.Unwrap(); got != nil {
+		t.Fatalf("nil receiver Unwrap = %v, want nil", got)
+	}
+	rejection := errors.New("rejected")
+	refresh := errors.New("refresh boom")
+	wrapped := (&authRefreshFailureError{rejection: rejection, refresh: refresh}).Unwrap()
+	if len(wrapped) != 2 || !errors.Is(wrapped[0], rejection) || !errors.Is(wrapped[1], refresh) {
+		t.Fatalf("Unwrap must surface both causes: %v", wrapped)
+	}
+
+	if ctx := withAuthRetrying(nil); ctx == nil || !IsAuthRetrying(ctx) {
+		t.Fatal("withAuthRetrying(nil) must produce a retry-marked background context")
+	}
+
+	var nilRunner *runtimeRunner
+	if nilRunner.managesRuntimeOAuth(false) {
+		t.Fatal("nil runner must not manage runtime OAuth")
+	}
+	if (&runtimeRunner{}).managesRuntimeOAuth(true) {
+		t.Fatal("plugin-owned auth must opt out of runtime OAuth management")
+	}
+	if !(&runtimeRunner{}).managesRuntimeOAuth(false) {
+		t.Fatal("nil global flags must manage runtime OAuth")
+	}
+	if !(&runtimeRunner{globalFlags: &GlobalFlags{}}).managesRuntimeOAuth(false) {
+		t.Fatal("blank token must manage runtime OAuth")
+	}
+	if (&runtimeRunner{globalFlags: &GlobalFlags{Token: "tok"}}).managesRuntimeOAuth(false) {
+		t.Fatal("explicit token must not manage runtime OAuth")
+	}
+}
+
+func TestCrossPlatformCoverageForceRefreshRejectedGuards(t *testing.T) {
+	if _, err := ForceRefreshAccessToken(context.Background(), "  "); err == nil ||
+		!strings.Contains(err.Error(), "config directory is empty") {
+		t.Fatalf("blank config dir error = %v", err)
+	}
+	testseam.Swap(t, &loadRefreshTokenData, func(string) (*authpkg.TokenData, error) { return nil, nil })
+	if _, err := ForceRefreshAccessToken(context.Background(), t.TempDir()); err == nil ||
+		!strings.Contains(err.Error(), "stored access token is empty") {
+		t.Fatalf("nil token data must report stored access token is empty: %v", err)
+	}
+	if _, err := forceRefreshRejectedAccessToken(context.Background(), "  ", "tok"); err == nil ||
+		!strings.Contains(err.Error(), "config directory is empty") {
+		t.Fatalf("blank config dir error = %v", err)
+	}
+	if _, err := forceRefreshRejectedAccessToken(context.Background(), t.TempDir(), " "); err == nil ||
+		!strings.Contains(err.Error(), "rejected access token is empty") {
+		t.Fatalf("blank rejected token error = %v", err)
+	}
+}
+
+func TestCrossPlatformCoverageGetCachedRuntimeTokenSeam(t *testing.T) {
+	token, err := getCachedRuntimeToken(context.Background())
+	if err != nil && strings.TrimSpace(token) != "" {
+		t.Fatalf("failed token resolution must not return a token: %q / %v", token, err)
+	}
+}

internal/app/direct_runtime.go

@@ -16,12 +16,10 @@ package app
 import (
 	"net"
 	"net/url"
-	"os"
 	"strings"
 	"sync"
 
 	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/executor"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/mcptypes"
@@ -112,54 +110,9 @@ func SetDynamicServers(servers []mcptypes.ServerDescriptor) {
 	products := make(map[string]bool)
 	aliases := make(map[string]string)
 	toolEndpoints := make(map[string]string)
-	registerDynamicServer(defaultPATServerDescriptor(), endpoints, products, aliases, toolEndpoints)
+	registerDynamicServer(defaultPATServerDescriptor(), endpoints, products, aliases, toolEndpoints, false)
 	for _, server := range servers {
-		if server.CLI.Skip {
-			continue
-		}
-		id := strings.TrimSpace(server.CLI.ID)
-		endpoint := strings.TrimSpace(server.Endpoint)
-		if id != "" && endpoint != "" {
-			endpoints[id] = endpoint
-			products[id] = true
-		}
-		cmd := strings.TrimSpace(server.CLI.Command)
-		if cmd != "" && cmd != id && endpoint != "" {
-			endpoints[cmd] = endpoint
-			products[cmd] = true
-		}
-		for _, alias := range server.CLI.Aliases {
-			alias = strings.TrimSpace(alias)
-			if alias != "" && endpoint != "" {
-				endpoints[alias] = endpoint
-				products[alias] = true
-				// Build alias → CLI.ID mapping
-				aliases[alias] = id
-			}
-		}
-		// Build tool → endpoint mapping from CLI tools and overrides.
-		if endpoint != "" {
-			for _, tool := range server.CLI.Tools {
-				toolName := strings.TrimSpace(tool.Name)
-				if toolName != "" {
-					toolEndpoints[toolName] = endpoint
-				}
-			}
-			for toolName, override := range server.CLI.ToolOverrides {
-				toolName = strings.TrimSpace(toolName)
-				if toolName == "" {
-					continue
-				}
-				// Leaves with serverOverride are routed to a different server's
-				// endpoint (e.g. chat's "search_my_robots" → bot). Registering
-				// them here would overwrite the real owner's tool → endpoint
-				// mapping and send the invocation to the wrong MCP URL.
-				if strings.TrimSpace(override.ServerOverride) != "" {
-					continue
-				}
-				toolEndpoints[toolName] = endpoint
-			}
-		}
+		registerDynamicServer(server, endpoints, products, aliases, toolEndpoints, false)
 	}
 	dynamicEndpoints = endpoints
 	dynamicProducts = products
@@ -167,7 +120,13 @@ func SetDynamicServers(servers []mcptypes.ServerDescriptor) {
 	dynamicToolEndpoints = toolEndpoints
 }
 
-func registerDynamicServer(server mcptypes.ServerDescriptor, endpoints map[string]string, products map[string]bool, aliases map[string]string, toolEndpoints map[string]string) {
+// registerDynamicServer is the shared dynamic-server registration core used by
+// SetDynamicServers and AppendDynamicServer. It records the descriptor's
+// endpoint under its ID, command name, and aliases, and builds the tool →
+// endpoint map from its CLI tools and overrides. With protectCommandKey=true
+// (AppendDynamicServer) an already-registered command-key endpoint is never
+// overwritten; with false the entry is replaced.
+func registerDynamicServer(server mcptypes.ServerDescriptor, endpoints map[string]string, products map[string]bool, aliases map[string]string, toolEndpoints map[string]string, protectCommandKey bool) {
 	if server.CLI.Skip {
 		return
 	}
@@ -179,7 +138,13 @@ func registerDynamicServer(server mcptypes.ServerDescriptor, endpoints map[strin
 	}
 	cmd := strings.TrimSpace(server.CLI.Command)
 	if cmd != "" && cmd != id && endpoint != "" {
-		endpoints[cmd] = endpoint
+		if protectCommandKey {
+			if _, exists := endpoints[cmd]; !exists {
+				endpoints[cmd] = endpoint
+			}
+		} else {
+			endpoints[cmd] = endpoint
+		}
 		products[cmd] = true
 	}
 	for _, alias := range server.CLI.Aliases {
@@ -187,11 +152,11 @@ func registerDynamicServer(server mcptypes.ServerDescriptor, endpoints map[strin
 		if alias != "" && endpoint != "" {
 			endpoints[alias] = endpoint
 			products[alias] = true
-			// Build alias -> CLI.ID mapping.
+			// Build alias → CLI.ID mapping.
 			aliases[alias] = id
 		}
 	}
-	// Build tool -> endpoint mapping from CLI tools and overrides.
+	// Build tool → endpoint mapping from CLI tools and overrides.
 	if endpoint != "" {
 		for _, tool := range server.CLI.Tools {
 			toolName := strings.TrimSpace(tool.Name)
@@ -199,19 +164,29 @@ func registerDynamicServer(server mcptypes.ServerDescriptor, endpoints map[strin
 				toolEndpoints[toolName] = endpoint
 			}
 		}
-		for toolName := range server.CLI.ToolOverrides {
+		for toolName, override := range server.CLI.ToolOverrides {
 			toolName = strings.TrimSpace(toolName)
-			if toolName != "" {
-				toolEndpoints[toolName] = endpoint
+			if toolName == "" {
+				continue
 			}
+			// Leaves with serverOverride are routed to a different server's
+			// endpoint (e.g. chat's "search_my_robots" → bot). Registering
+			// them here would overwrite the real owner's tool → endpoint
+			// mapping and send the invocation to the wrong MCP URL.
+			if strings.TrimSpace(override.ServerOverride) != "" {
+				continue
+			}
+			toolEndpoints[toolName] = endpoint
 		}
 	}
 }
 
+// shouldUseDirectRuntime gates endpoint resolution to the only invocation
+// kinds the executor constructs: compat_invocation via
+// NewCompatibilityInvocation and helper_invocation via NewHelperInvocation.
+// Every other kind skips direct-runtime resolution and terminates at
+// handleCatalogMiss in the runner.
 func shouldUseDirectRuntime(invocation executor.Invocation) bool {
-	if strings.TrimSpace(os.Getenv(cli.CatalogFixtureEnv)) != "" {
-		return false
-	}
 	switch invocation.Kind {
 	case "compat_invocation", "helper_invocation":
 		return true
@@ -220,22 +195,6 @@ func shouldUseDirectRuntime(invocation executor.Invocation) bool {
 	}
 }
 
-// directRuntimeToolEndpoint returns the MCP endpoint owned by the server
-// whose toolOverrides registered this tool name. Used to correct catalog
-// lookups when two envelope servers share the same cli.command and the
-// per-product endpoint map collides (see runner.go cross-check).
-func directRuntimeToolEndpoint(toolName string) (string, bool) {
-	toolName = strings.TrimSpace(toolName)
-	if toolName == "" {
-		return "", false
-	}
-	dynamicMu.RLock()
-	defer dynamicMu.RUnlock()
-
-	endpoint, ok := dynamicToolEndpoints[toolName]
-	return endpoint, ok && strings.TrimSpace(endpoint) != ""
-}
-
 func directRuntimeEndpoint(productID, toolName string) (string, bool) {
 	// Priority 0: env-var override always wins (DINGTALK_<PRODUCT>_MCP_URL).
 	normalized := normalizeDirectRuntimeProductID(productID)
@@ -377,51 +336,7 @@ func AppendDynamicServer(server mcptypes.ServerDescriptor) {
 		dynamicToolEndpoints = make(map[string]string)
 	}
 
-	if server.CLI.Skip {
-		return
-	}
-
-	id := strings.TrimSpace(server.CLI.ID)
-	endpoint := strings.TrimSpace(server.Endpoint)
-	if id != "" && endpoint != "" {
-		dynamicEndpoints[id] = endpoint
-		dynamicProducts[id] = true
-	}
-	cmd := strings.TrimSpace(server.CLI.Command)
-	if cmd != "" && cmd != id && endpoint != "" {
-		if _, exists := dynamicEndpoints[cmd]; !exists {
-			dynamicEndpoints[cmd] = endpoint
-		}
-		dynamicProducts[cmd] = true
-	}
-	for _, alias := range server.CLI.Aliases {
-		alias = strings.TrimSpace(alias)
-		if alias != "" && endpoint != "" {
-			dynamicEndpoints[alias] = endpoint
-			dynamicProducts[alias] = true
-			dynamicAliases[alias] = id
-		}
-	}
-	if endpoint != "" {
-		for _, tool := range server.CLI.Tools {
-			toolName := strings.TrimSpace(tool.Name)
-			if toolName != "" {
-				dynamicToolEndpoints[toolName] = endpoint
-			}
-		}
-		for toolName, override := range server.CLI.ToolOverrides {
-			toolName = strings.TrimSpace(toolName)
-			if toolName == "" {
-				continue
-			}
-			// Leaves with serverOverride are routed to a different server's
-			// endpoint; skip to avoid overwriting the real owner's mapping.
-			if strings.TrimSpace(override.ServerOverride) != "" {
-				continue
-			}
-			dynamicToolEndpoints[toolName] = endpoint
-		}
-	}
+	registerDynamicServer(server, dynamicEndpoints, dynamicProducts, dynamicAliases, dynamicToolEndpoints, true)
 }
 
 func normalizeDirectRuntimeProductID(productID string) string {

internal/app/doctor_command.go

@@ -61,7 +61,7 @@ func newDoctorCommand() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:               "doctor",
 		Short:             "环境健康检查",
-		Long:              "一键检查登录态、网络连通性、缓存状态和版本更新，快速定位常见问题。",
+		Long:              "一键检查登录态、网络连通性和版本更新，快速定位常见问题。",
 		Args:              cobra.NoArgs,
 		DisableAutoGenTag: true,
 		RunE:              runDoctor,
@@ -92,9 +92,6 @@ func runDoctor(cmd *cobra.Command, _ []string) error {
 	networkResult := doctorCheckNetwork(cmd.Context(), w, jsonOut, networkTimeout)
 	checks = append(checks, networkResult)
 
-	cacheResult := doctorCheckCache(w, jsonOut)
-	checks = append(checks, cacheResult)
-
 	versionResult := doctorCheckVersion(w, jsonOut, networkTimeout)
 	checks = append(checks, versionResult)
 
@@ -297,24 +294,6 @@ func doctorCheckNetwork(ctx context.Context, w io.Writer, jsonOut bool, timeout
 	return r
 }
 
-// ── Cache check ─────────────────────────────────────────────────────────
-
-func doctorCheckCache(w io.Writer, jsonOut bool) checkResult {
-	if !jsonOut {
-		fmt.Fprint(w, tui.Dim("检查缓存状态...       "))
-	}
-
-	r := checkResult{
-		Name:    "cache",
-		Status:  statusPass,
-		Message: "静态端点模式, 无需缓存",
-	}
-	if !jsonOut {
-		printCheckResult(w, r)
-	}
-	return r
-}
-
 // ── Version check ───────────────────────────────────────────────────────
 
 func doctorCheckVersion(w io.Writer, jsonOut bool, timeout time.Duration) checkResult {

internal/app/doctor_command_test.go

@@ -109,31 +109,6 @@ func TestPrintCheckResultNoHint(t *testing.T) {
 	}
 }
 
-func TestDoctorCheckCacheEmpty(t *testing.T) {
-	t.Setenv("DWS_CACHE_DIR", t.TempDir())
-
-	var buf bytes.Buffer
-	r := doctorCheckCache(&buf, false)
-
-	if r.Status != statusPass {
-		t.Errorf("expected pass for static endpoint mode, got %s", r.Status)
-	}
-}
-
-func TestDoctorCheckCacheEmptyJSON(t *testing.T) {
-	t.Setenv("DWS_CACHE_DIR", t.TempDir())
-
-	var buf bytes.Buffer
-	r := doctorCheckCache(&buf, true)
-
-	if r.Status != statusPass {
-		t.Errorf("expected pass for static endpoint mode, got %s", r.Status)
-	}
-	if buf.Len() != 0 {
-		t.Error("expected no output in JSON mode")
-	}
-}
-
 func TestDoctorCheckAuthReportsKeychainUnavailable(t *testing.T) {
 	t.Setenv("DWS_CONFIG_DIR", filepath.Join(t.TempDir(), "config"))
 

internal/app/event_command.go

@@ -29,9 +29,11 @@ import (
 	"text/tabwriter"
 	"time"
 
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/helpers"
+
 	authpkg "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/auth"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/cli"
-	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract"
 	dwsevent "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/bus"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/busctl"
@@ -73,6 +75,20 @@ var (
 // newEventCommand returns the `event` parent command and all its subcommands.
 // Wired into root.go's utilityCommands list.
 func newEventCommand() *cobra.Command {
+	// Product-level Agent routing Decl (migrated from selection/event.json
+	// products.event). Catalog assembly stamps provenance contract_final.
+	contract.RegisterProductDecl(contract.ProductDecl{
+		ID: "event",
+		Selection: contract.ProductSelectionDecl{
+			AgentSummary: "订阅/消费个人消息、动作与群生命周期事件，并管理订阅生命周期",
+			UseWhen: []string{
+				"需要实时监听个人消息接收、全量消息、已读、撤回、表情回应或群生命周期事件，或管理个人事件订阅生命周期",
+			},
+			AvoidWhen: []string{
+				"查历史聊天或主动发消息分别用 chat 查询/发送命令",
+			},
+		},
+	})
 	cmd := &cobra.Command{
 		Use:               "event",
 		Short:             "事件订阅 (DingTalk Stream 长连接)",
@@ -83,6 +99,7 @@ func newEventCommand() *cobra.Command {
 		RunE:              func(c *cobra.Command, _ []string) error { return c.Help() },
 	}
 	cmd.AddCommand(
+		newEventListenIMCommand(),
 		newEventConsumeCommand(),
 		newEventListCommand(),
 		newEventSchemaCommand(),
@@ -353,7 +370,7 @@ SIGTERM、关 stdin，或先用 dws event stop <subscribe_id> --dry-run 预览
 	f.StringVar(&streamOpts.TicketURL, "stream-ticket-url", strings.TrimSpace(os.Getenv("DWS_STREAM_TICKET_URL")),
 		"个人 Stream 取票 URL；默认由 MCP base 派生 /stream/connections/ticket")
 	hideEventInternalFlags(cmd, "as")
-	cli.AnnotateRuntimePositionals(cmd, cli.RuntimeSchemaPositional{
+	cli.AnnotateRuntimePositionals(cmd, contract.RuntimeSchemaPositional{
 		Name:        "event_key",
 		Type:        "string",
 		Description: "要消费的一个或多个个人事件码；多个事件必须共享同一目标和过滤上下文",
@@ -361,6 +378,46 @@ SIGTERM、关 stdin，或先用 dws event stop <subscribe_id> --dry-run 预览
 		Variadic:    true,
 		Index:       0,
 	})
+	helpers.DeclareLeafMetadata(cmd, helpers.LeafSpec{
+		Safety: contract.SafetySpec{
+			Effect: "write", Risk: "medium",
+			Confirmation: "not_required", Idempotency: "non_idempotent",
+		},
+		Contract: helpers.LeafContract{
+			Identity: contract.ToolIdentitySpec{
+				ProductID:      "event",
+				Name:           "consume",
+				CanonicalPath:  "event.consume",
+				CLIPath:        "event consume",
+				PrimaryCLIPath: "event consume",
+			},
+			Description: "订阅并持续消费一个或多个兼容的个人事件；Agent 使用 --flatten 输出顶层业务 NDJSON",
+			Interface: &contract.InterfaceSpec{
+				Mode:         "composite",
+				Availability: "available",
+				Reason:       "Reviewed composite workflow: the command creates or reuses a remote personal-event subscription and coordinates the local event bus and Stream consumer; no single pinned RPC represents the workflow.",
+			},
+			Selection: contract.SelectionSpec{
+				AgentSummary: "订阅并持续消费一个或多个兼容的个人事件；Agent 使用 --flatten 输出顶层业务 NDJSON",
+				UseWhen: []string{
+					"需要实时监听 @我、指定单聊、指定群或指定发送人的后续消息事件",
+					"用户明确要求监听当前身份的所有单聊或所有群消息",
+					"需要监听指定单聊或群聊中的消息已读、撤回或表情回应事件",
+					"需要监听指定群的标题变更、成员进退群或群解散事件",
+					"监听机器人、外部联系人等以 openDingtalkId 标识的单聊目标",
+					"同一目标、同一过滤条件需要同时监听多个兼容事件",
+				},
+				AvoidWhen: []string{
+					"只查历史聊天记录时用 chat 查询命令",
+					"只看事件目录/字段时用 event list / event schema",
+				},
+				Examples: []string{
+					"dws event consume user_im_message_receive_user --open-dingtalk-id open-example --flatten --max-events 1 --format ndjson",
+					"dws event consume user_im_message_receive_o2o user_im_message_read_o2o --user test-user-001 --flatten --max-events 2 --format ndjson",
+				},
+			},
+		},
+	})
 	return cmd
 }
 
@@ -728,6 +785,36 @@ func newEventListCommand() *cobra.Command {
 	cmd.Flags().BoolVar(&enabledOnly, "enabled-only", false, "个人事件目录只显示 enabled")
 	cmd.Flags().BoolVar(&includePending, "include-pending", false, "个人事件目录包含 pending 项")
 	hideEventInternalFlags(cmd, "as", "all", "all-editions", "client-id")
+	helpers.DeclareLeafMetadata(cmd, helpers.LeafSpec{
+		Safety: contract.SafetySpec{
+			Effect: "read", Risk: "low",
+			Confirmation: "not_required", Idempotency: "idempotent",
+		},
+		Contract: helpers.LeafContract{
+			Identity: contract.ToolIdentitySpec{
+				ProductID:      "event",
+				Name:           "list",
+				CanonicalPath:  "event.list",
+				CLIPath:        "event list",
+				PrimaryCLIPath: "event list",
+			},
+			Description: "列出支持的个人事件目录与状态说明",
+			Interface: &contract.InterfaceSpec{
+				Mode:         "local",
+				Availability: "available",
+				Reason:       "命令读取 CLI 内置的个人事件目录，不绑定 pinned MCP RPC",
+			},
+			Selection: contract.SelectionSpec{
+				AgentSummary: "列出支持的个人事件目录与状态说明",
+				UseWhen:      []string{"尚不知道可用 event_key，需要先盘点个人事件目录"},
+				AvoidWhen: []string{
+					"已知 event_key 要看 payload 字段时用 event schema",
+					"要开始监听时用 event consume",
+				},
+				Examples: []string{"dws event list --format json"},
+			},
+		},
+	})
 	return cmd
 }
 
@@ -796,6 +883,33 @@ func newEventStatusCommand() *cobra.Command {
 	cmd.Flags().StringVar(&personalOpts.StreamSourceID, "stream-source-id", strings.TrimSpace(os.Getenv("DWS_STREAM_SOURCE_ID")),
 		"个人事件 sourceId；开源版默认 open，可由 edition 覆盖")
 	hideEventInternalFlags(cmd, "as", "all", "all-editions", "client-id", "fail-on-orphan")
+	helpers.DeclareLeafMetadata(cmd, helpers.LeafSpec{
+		Safety: contract.SafetySpec{
+			Effect: "read", Risk: "low",
+			Confirmation: "not_required", Idempotency: "idempotent",
+		},
+		Contract: helpers.LeafContract{
+			Identity: contract.ToolIdentitySpec{
+				ProductID:      "event",
+				Name:           "status",
+				CanonicalPath:  "event.status",
+				CLIPath:        "event status",
+				PrimaryCLIPath: "event status",
+			},
+			Description: "查看个人事件订阅、本地 bus 与消费进程状态",
+			Interface: &contract.InterfaceSpec{
+				Mode:         "composite",
+				Availability: "available",
+				Reason:       "Reviewed composite workflow: the command reads the remote personal-event subscription control plane and combines it with local bus and consumer state; no single pinned RPC represents the result.",
+			},
+			Selection: contract.SelectionSpec{
+				AgentSummary: "查看个人事件订阅、本地 bus 与消费进程状态",
+				UseWhen:      []string{"需要确认订阅是否活跃、bus/consume 是否仍在运行"},
+				AvoidWhen:    []string{"取消订阅用 event stop；列事件目录用 event list"},
+				Examples:     []string{"dws event status --format json"},
+			},
+		},
+	})
 	return cmd
 }
 
@@ -1037,39 +1151,22 @@ func newEventStopCommand() *cobra.Command {
 		Args:              cobra.MaximumNArgs(1),
 		DisableAutoGenTag: true,
 		RunE: func(c *cobra.Command, args []string) error {
+			// Local validation runs in DeclareLeafMetadata Validate (PreRunE)
+			// before ConfirmSafety. Confirmation is the framework wrap.
 			as, err := eventNormalizeAs(asIdentity)
 			if err != nil {
 				return err
 			}
 			if as == "user" {
 				opts.SubscribeID = firstArg(args)
-				hasSubscribeID := strings.TrimSpace(opts.SubscribeID) != ""
-				if hasSubscribeID && opts.All {
-					return fmt.Errorf("event stop --as user: subscribe_id and --all are mutually exclusive")
-				}
-				if !hasSubscribeID && !opts.All {
-					return fmt.Errorf("event stop --as user: subscribe_id is required unless --all is set")
-				}
 				if eventStopDryRun(c) {
 					return writeEventStopDryRun(c, as, opts)
 				}
-				if !eventStopConfirmed(c) {
-					return eventStopConfirmationRequired("event stop 会取消个人事件订阅并停止本地消费")
-				}
 				return eventRunPersonalStop(c, opts)
 			}
-			if err := rejectChangedFlags(c, "user", "all", "personal-event-base-url", "stream-source-id"); err != nil {
-				return fmt.Errorf("event stop: %w", err)
-			}
-			if len(args) > 0 {
-				return fmt.Errorf("event stop: subscribe_id is only supported with --as user")
-			}
 			if eventStopDryRun(c) {
 				return writeEventStopDryRun(c, as, opts)
 			}
-			if !eventStopConfirmed(c) {
-				return eventStopConfirmationRequired("event stop 会停止事件消费")
-			}
 			configDir := defaultConfigDir()
 			clientID, _, _, _, err := eventResolveAppCredentials(configDir)
 			if err != nil {
@@ -1095,13 +1192,68 @@ func newEventStopCommand() *cobra.Command {
 		"个人事件 sourceId；开源版默认 open，可由 edition 覆盖")
 	cmd.Flags().BoolVar(&opts.All, "all", false, "取消当前身份下本地记录的所有个人订阅")
 	hideEventInternalFlags(cmd, "as")
-	cli.AnnotateRuntimePositionals(cmd, cli.RuntimeSchemaPositional{
+	cli.AnnotateRuntimePositionals(cmd, contract.RuntimeSchemaPositional{
 		Name:        "subscribe_id",
 		Type:        "string",
 		Description: "要取消的个人事件订阅 ID；与 --all 二选一",
 		Required:    false,
 		Index:       0,
 	})
+	helpers.DeclareLeafMetadata(cmd, helpers.LeafSpec{
+		Safety: contract.SafetySpec{
+			Effect: "destructive", Risk: "high",
+			Confirmation: "user_required", Idempotency: "unknown",
+		},
+		Validate: func(c *cobra.Command, args []string) error {
+			as, err := eventNormalizeAs(asIdentity)
+			if err != nil {
+				return err
+			}
+			if as == "user" {
+				subscribeID := firstArg(args)
+				hasSubscribeID := strings.TrimSpace(subscribeID) != ""
+				if hasSubscribeID && opts.All {
+					return fmt.Errorf("event stop --as user: subscribe_id and --all are mutually exclusive")
+				}
+				if !hasSubscribeID && !opts.All {
+					return fmt.Errorf("event stop --as user: subscribe_id is required unless --all is set")
+				}
+				return nil
+			}
+			if err := rejectChangedFlags(c, "user", "all", "personal-event-base-url", "stream-source-id"); err != nil {
+				return fmt.Errorf("event stop: %w", err)
+			}
+			if len(args) > 0 {
+				return fmt.Errorf("event stop: subscribe_id is only supported with --as user")
+			}
+			return nil
+		},
+		Contract: helpers.LeafContract{
+			Identity: contract.ToolIdentitySpec{
+				ProductID:      "event",
+				Name:           "stop",
+				CanonicalPath:  "event.stop",
+				CLIPath:        "event stop",
+				PrimaryCLIPath: "event stop",
+			},
+			Description: "取消个人事件订阅并停止对应本地消费",
+			DryRun:      &contract.DryRunSpec{PreviewKind: "request", RemoteReads: false},
+			Interface: &contract.InterfaceSpec{
+				Mode:         "composite",
+				Availability: "available",
+				Reason:       "Reviewed composite workflow: the command deletes remote personal-event subscriptions, interrupts local consumers, updates local state, and may stop the local bus; no single pinned RPC represents the workflow.",
+			},
+			Selection: contract.SelectionSpec{
+				AgentSummary: "取消个人事件订阅并停止对应本地消费",
+				UseWhen:      []string{"用户明确要求取消已知 subscribe_id（或清理全部）并停止消费"},
+				AvoidWhen: []string{
+					"只需检查状态时用 event status",
+					"目标订阅不明确或用户未确认时不要停止",
+				},
+				Examples: []string{"dws event stop SUBSCRIBE_ID --dry-run"},
+			},
+		},
+	})
 	return cmd
 }
 
@@ -1110,20 +1262,6 @@ func eventStopDryRun(cmd *cobra.Command) bool {
 	return value
 }
 
-func eventStopConfirmed(cmd *cobra.Command) bool {
-	value, _ := cmd.Flags().GetBool("yes")
-	return value
-}
-
-func eventStopConfirmationRequired(action string) error {
-	return apperrors.NewValidation(
-		action+"；请先使用 --dry-run 预览，确认后加 --yes 执行",
-		apperrors.WithReason("confirmation_required"),
-		apperrors.WithHint("先以相同参数加 --dry-run 预览；获得用户确认后改用 --yes 执行"),
-		apperrors.WithActions("使用 --dry-run 生成预览", "获得用户确认后使用 --yes 执行"),
-	)
-}
-
 func writeEventStopDryRun(cmd *cobra.Command, identity string, opts personalStopOptions) error {
 	payload := map[string]any{
 		"dry_run":  true,
@@ -1274,7 +1412,3 @@ func eventTypesWithDefault(types []string) []string {
 	}
 	return registry.CatchAllEventTypes()
 }
-
-// compile-time guard: avoid "imported and not used" if any of these
-// indirect imports become unused after future refactors.
-var _ = io.Discard

internal/app/event_listen_im.go

@@ -0,0 +1,295 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+
+package app
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"strings"
+	"time"
+
+	"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/event/personal"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/helpers"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut/targetresolver"
+	"github.com/spf13/cobra"
+)
+
+type listenIMOptions struct {
+	Kind             string
+	Events           []string
+	UserID           string
+	OpenDingTalkID   string
+	UserQuery        string
+	ChatID           string
+	ChatQuery        string
+	QueryCSV         string
+	MaxEvents        int
+	Duration         time.Duration
+	DryRun           bool
+	ControlBaseURL   string
+	StreamTicketMode string
+	StreamTicketURL  string
+	StreamSourceID   string
+}
+
+type listenIMPlan struct {
+	EventKeys       []string
+	UserID          string
+	OpenDingTalkID  string
+	GroupID         string
+	ResolvedTargets []any
+}
+
+type eventTargetReader struct{}
+
+func (eventTargetReader) CallMCPData(product, tool string, params map[string]any) (map[string]any, error) {
+	text, err := helpers.CallMCPReadToolTextOnServer(product, tool, params)
+	if err != nil {
+		return nil, err
+	}
+	if strings.TrimSpace(text) == "" {
+		return map[string]any{}, nil
+	}
+	var data map[string]any
+	if err := json.Unmarshal([]byte(text), &data); err != nil {
+		return nil, apperrors.NewInternal(fmt.Sprintf("解析 %s 返回失败: %v", tool, err))
+	}
+	return data, nil
+}
+
+var eventListenIMReader = func() targetresolver.Reader { return eventTargetReader{} }
+
+func newEventListenIMCommand() *cobra.Command {
+	var opts listenIMOptions
+	cmd := &cobra.Command{
+		Use:   "+listen-im",
+		Short: "按 IM 意图解析目标并监听一个或多个个人消息事件",
+		Long: "把 @我、指定发送人、指定群、全部单聊或全部群聊等用户意图确定性编译为个人 EventKey，" +
+			"自然姓名/群名会先唯一解析，再复用 event consume 的订阅、ready marker、NDJSON、取消、回滚和清理生命周期。",
+		Args:              cobra.NoArgs,
+		DisableAutoGenTag: true,
+		RunE: func(c *cobra.Command, _ []string) error {
+			plan, err := compileListenIMPlan(eventListenIMReader(), opts)
+			if err != nil {
+				return fmt.Errorf("event +listen-im: %w", err)
+			}
+			consumeOpts := personalConsumeOptions{
+				EventKey:         firstArg(plan.EventKeys),
+				EventKeys:        plan.EventKeys,
+				Flatten:          true,
+				UserID:           plan.UserID,
+				OpenDingTalkID:   plan.OpenDingTalkID,
+				GroupID:          plan.GroupID,
+				QueryCSV:         opts.QueryCSV,
+				ControlBaseURL:   opts.ControlBaseURL,
+				StreamTicketMode: opts.StreamTicketMode,
+				StreamTicketURL:  opts.StreamTicketURL,
+				StreamSourceID:   opts.StreamSourceID,
+				Common: commonConsumeOptions{
+					FormatRaw: "ndjson",
+					MaxEvents: opts.MaxEvents,
+					Duration:  opts.Duration,
+					DryRun:    opts.DryRun,
+				},
+			}
+			return eventRunPersonalConsume(c, consumeOpts)
+		},
+	}
+	f := cmd.Flags()
+	f.StringVar(&opts.Kind, "kind", "at-me", "监听意图: at-me|sender|group|all-direct|all-group")
+	f.StringSliceVar(&opts.Events, "events", []string{"message"}, "事件种类: message,reaction,read,recall")
+	f.StringVar(&opts.UserID, "user", "", "指定发送人/单聊对端 userId")
+	f.StringVar(&opts.OpenDingTalkID, "open-dingtalk-id", "", "指定发送人/单聊对端 openDingTalkId")
+	f.StringVar(&opts.UserQuery, "user-query", "", "按姓名/花名唯一解析指定发送人")
+	f.StringVar(&opts.ChatID, "chat-id", "", "指定群 openConversationId")
+	f.StringVar(&opts.ChatQuery, "chat-query", "", "按群名唯一解析指定群")
+	f.StringVar(&opts.QueryCSV, "query", "", "消息文本关键词过滤，逗号分隔；仅 message 事件")
+	f.IntVar(&opts.MaxEvents, "max-events", 0, "收到 N 条后退出 (0 = 不限)")
+	f.DurationVar(&opts.Duration, "duration", 0, "运行时长上限 (Go duration，如 30s/5m；0 = 不限)")
+	f.BoolVar(&opts.DryRun, "dry-run", false, "解析目标并打印订阅计划，不创建订阅或连接 bus")
+	f.StringVar(&opts.ControlBaseURL, "personal-event-base-url", "", "个人事件控制面 base URL；默认由 MCP base 派生 /dws")
+	f.StringVar(&opts.StreamTicketMode, "stream-ticket-mode", strings.TrimSpace(os.Getenv("DWS_STREAM_TICKET_MODE")), "个人 Stream 建联模式；默认 normal")
+	f.StringVar(&opts.StreamSourceID, "stream-source-id", strings.TrimSpace(os.Getenv("DWS_STREAM_SOURCE_ID")), "个人 Stream sourceId；开源版默认 open")
+	f.StringVar(&opts.StreamTicketURL, "stream-ticket-url", strings.TrimSpace(os.Getenv("DWS_STREAM_TICKET_URL")), "个人 Stream 取票 URL")
+	hideEventInternalFlags(cmd, "personal-event-base-url", "stream-ticket-mode", "stream-source-id", "stream-ticket-url")
+	cli.AnnotateRuntimeFlagEnum(cmd, "kind", "at-me", "sender", "group", "all-direct", "all-group")
+	cli.AnnotateRuntimeFlagEnum(cmd, "events", "message", "reaction", "read", "recall")
+	cli.AnnotateRuntimeConstraints(cmd, cli.RuntimeSchemaConstraints{
+		MutuallyExclusive: [][]string{{"user", "open-dingtalk-id", "user-query", "chat-id", "chat-query"}},
+	})
+	helpers.DeclareLeafMetadata(cmd, helpers.LeafSpec{
+		Safety: contract.SafetySpec{
+			Effect: "write", Risk: "medium",
+			Confirmation: "not_required", Idempotency: "non_idempotent",
+		},
+		Contract: helpers.LeafContract{
+			Identity: contract.ToolIdentitySpec{
+				ProductID:      "event",
+				Name:           "listen_im",
+				CanonicalPath:  "event.listen_im",
+				CLIPath:        "event +listen-im",
+				PrimaryCLIPath: "event +listen-im",
+			},
+			Description: "把 @我、指定发送人、指定群、全部单聊或全部群聊等用户意图确定性编译为个人 EventKey，自然姓名/群名会先唯一解析，再复用 event consume 的订阅、ready marker、NDJSON、取消、回滚和清理生命周期。",
+			Interface: &contract.InterfaceSpec{
+				Mode:         "composite",
+				Availability: "available",
+				Reason:       "Reviewed IM event facade: it deterministically maps kind/events to public personal EventKeys, resolves one natural user/chat target with the shared typed resolver, then delegates one single- or multi-event invocation to the existing subscription, bus, ready-marker, NDJSON, rollback, cancellation, and cleanup lifecycle.",
+			},
+			Selection: contract.SelectionSpec{
+				AgentSummary: "按 @我、姓名、群名或全量范围监听一个或多个 IM 消息事件",
+				UseWhen: []string{
+					"已知要监听 @我、指定发送人、指定群、全部单聊或全部群聊的 message/reaction/read/recall 事件时使用；姓名用 --user-query、群名用 --chat-query，CLI 会唯一解析目标并把多个兼容事件合并到一个消费生命周期。",
+				},
+				AvoidWhen: []string{
+					"需要群标题/成员/解散等生命周期事件、显式 EventKey、复用 subscribe_id、Filter DSL、原始 transport envelope 或其它底层 consume 控制时使用 event consume；只查历史消息时使用 chat 查询入口",
+				},
+				Examples: []string{
+					"dws event +listen-im --kind at-me --max-events 1",
+					"dws event +listen-im --kind group --events message,reaction --chat-id <openConversationId> --duration 10m",
+				},
+			},
+			Parameters: []contract.ParamDecl{
+				{Name: "chat-id", Property: "chatId"},
+				{Name: "chat-query", Property: "chatQuery"},
+				{Name: "dry-run", Property: "dryRun"},
+				{Name: "duration", Property: "duration"},
+				{Name: "events", Property: "events"},
+				{Name: "kind", Property: "kind"},
+				{Name: "max-events", Property: "maxEvents"},
+				{Name: "open-dingtalk-id", Property: "openDingtalkId"},
+				{Name: "query", Property: "query"},
+				{Name: "user", Property: "user"},
+				{Name: "user-query", Property: "userQuery"},
+			},
+		},
+	})
+	return cmd
+}
+
+func compileListenIMPlan(reader targetresolver.Reader, opts listenIMOptions) (listenIMPlan, error) {
+	kind := strings.ToLower(strings.TrimSpace(opts.Kind))
+	if kind == "" {
+		kind = "at-me"
+	}
+	events := uniqueListenIMValues(opts.Events)
+	if len(events) == 0 {
+		return listenIMPlan{}, apperrors.NewValidation("--events 至少包含一个事件种类")
+	}
+	if strings.TrimSpace(opts.QueryCSV) != "" {
+		for _, eventName := range events {
+			if eventName != "message" {
+				return listenIMPlan{}, apperrors.NewValidation("--query 只支持 message 事件")
+			}
+		}
+	}
+
+	plan := listenIMPlan{}
+	var err error
+	switch kind {
+	case "at-me", "all-direct", "all-group":
+		if listenIMTargetCount(opts) != 0 {
+			return listenIMPlan{}, apperrors.NewValidation(fmt.Sprintf("--kind %s 不接受用户或群目标", kind))
+		}
+	case "sender":
+		if listenIMUserTargetCount(opts) != 1 || listenIMChatTargetCount(opts) != 0 {
+			return listenIMPlan{}, apperrors.NewValidation("--kind sender 必须且只能指定 --user、--open-dingtalk-id 或 --user-query 之一")
+		}
+		plan.UserID = strings.TrimSpace(opts.UserID)
+		plan.OpenDingTalkID = strings.TrimSpace(opts.OpenDingTalkID)
+		if query := strings.TrimSpace(opts.UserQuery); query != "" {
+			resolved, resolveErr := targetresolver.ResolveUser(reader, query, targetresolver.IdentityAny)
+			if resolveErr != nil {
+				return listenIMPlan{}, resolveErr
+			}
+			plan.ResolvedTargets = append(plan.ResolvedTargets, resolved)
+			plan.UserID = resolved.Selected.UserID
+			if plan.UserID == "" {
+				plan.OpenDingTalkID = resolved.Selected.OpenDingTalkID
+			}
+		}
+	case "group":
+		if listenIMChatTargetCount(opts) != 1 || listenIMUserTargetCount(opts) != 0 {
+			return listenIMPlan{}, apperrors.NewValidation("--kind group 必须且只能指定 --chat-id 或 --chat-query 之一")
+		}
+		plan.GroupID = strings.TrimSpace(opts.ChatID)
+		if query := strings.TrimSpace(opts.ChatQuery); query != "" {
+			resolved, resolveErr := targetresolver.ResolveChat(reader, query)
+			if resolveErr != nil {
+				return listenIMPlan{}, resolveErr
+			}
+			plan.ResolvedTargets = append(plan.ResolvedTargets, resolved)
+			plan.GroupID = resolved.Selected.OpenConversationID
+		}
+	default:
+		return listenIMPlan{}, apperrors.NewValidation("--kind 必须是 at-me、sender、group、all-direct 或 all-group")
+	}
+
+	plan.EventKeys, err = listenIMEventKeys(kind, events)
+	if err != nil {
+		return listenIMPlan{}, err
+	}
+	return plan, nil
+}
+
+func listenIMEventKeys(kind string, events []string) ([]string, error) {
+	mapping := map[string]map[string]string{
+		"at-me":      {"message": personal.EventMention},
+		"sender":     {"message": personal.EventFromUser, "reaction": personal.EventReactionO2O, "read": personal.EventReadO2O, "recall": personal.EventRecallO2O},
+		"group":      {"message": personal.EventInChat, "reaction": personal.EventReactionGroup, "read": personal.EventReadGroup, "recall": personal.EventRecallGroup},
+		"all-direct": {"message": personal.EventAllSingleChat},
+		"all-group":  {"message": personal.EventAllGroupChat},
+	}
+	byEvent := mapping[kind]
+	keys := make([]string, 0, len(events))
+	for _, eventName := range events {
+		key := byEvent[eventName]
+		if key == "" {
+			return nil, apperrors.NewValidation(fmt.Sprintf("--kind %s 不支持 event %s", kind, eventName))
+		}
+		keys = append(keys, key)
+	}
+	return keys, nil
+}
+
+func listenIMUserTargetCount(opts listenIMOptions) int {
+	return nonEmptyListenIMCount(opts.UserID, opts.OpenDingTalkID, opts.UserQuery)
+}
+
+func listenIMChatTargetCount(opts listenIMOptions) int {
+	return nonEmptyListenIMCount(opts.ChatID, opts.ChatQuery)
+}
+
+func listenIMTargetCount(opts listenIMOptions) int {
+	return listenIMUserTargetCount(opts) + listenIMChatTargetCount(opts)
+}
+
+func nonEmptyListenIMCount(values ...string) int {
+	count := 0
+	for _, value := range values {
+		if strings.TrimSpace(value) != "" {
+			count++
+		}
+	}
+	return count
+}
+
+func uniqueListenIMValues(values []string) []string {
+	out := make([]string, 0, len(values))
+	seen := map[string]bool{}
+	for _, value := range values {
+		value = strings.ToLower(strings.TrimSpace(value))
+		if value == "" || seen[value] {
+			continue
+		}
+		seen[value] = true
+		out = append(out, value)
+	}
+	return out
+}

internal/app/event_listen_im_test.go

@@ -0,0 +1,360 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+
+package app
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"fmt"
+	"reflect"
+	"strings"
+	"testing"
+
+	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/consume"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/personal"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/helpers"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut/targetresolver"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition"
+	"github.com/spf13/cobra"
+)
+
+type listenIMFakeReader struct {
+	responses map[string]map[string]any
+	calls     []string
+}
+
+type listenIMErrorReader struct{ err error }
+
+func (r listenIMErrorReader) CallMCPData(string, string, map[string]any) (map[string]any, error) {
+	return nil, r.err
+}
+
+type listenIMHelperCaller struct {
+	text string
+	err  error
+}
+
+func (c listenIMHelperCaller) CallTool(context.Context, string, string, map[string]any) (*edition.ToolResult, error) {
+	return c.result()
+}
+
+func (c listenIMHelperCaller) CallReadTool(context.Context, string, string, map[string]any) (*edition.ToolResult, error) {
+	return c.result()
+}
+
+func (c listenIMHelperCaller) result() (*edition.ToolResult, error) {
+	if c.err != nil {
+		return nil, c.err
+	}
+	return &edition.ToolResult{Content: []edition.ContentBlock{{Type: "text", Text: c.text}}}, nil
+}
+
+func (listenIMHelperCaller) Format() string { return "json" }
+func (listenIMHelperCaller) DryRun() bool   { return false }
+func (listenIMHelperCaller) Fields() string { return "" }
+func (listenIMHelperCaller) JQ() string     { return "" }
+
+func (f *listenIMFakeReader) CallMCPData(product, tool string, _ map[string]any) (map[string]any, error) {
+	key := product + "/" + tool
+	f.calls = append(f.calls, key)
+	if response, ok := f.responses[key]; ok {
+		return response, nil
+	}
+	return map[string]any{}, nil
+}
+
+func TestCrossPlatformCoverageCompileListenIMPlanResolvesGroupAndMapsMultipleEvents(t *testing.T) {
+	reader := &listenIMFakeReader{responses: map[string]map[string]any{
+		"im/search_groups": {
+			"result": []any{map[string]any{"title": "项目群", "openConversationId": "cid-1"}},
+		},
+	}}
+	plan, err := compileListenIMPlan(reader, listenIMOptions{
+		Kind:      "group",
+		Events:    []string{"message", "reaction", "recall"},
+		ChatQuery: "项目群",
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	wantKeys := []string{personal.EventInChat, personal.EventReactionGroup, personal.EventRecallGroup}
+	if !reflect.DeepEqual(plan.EventKeys, wantKeys) || plan.GroupID != "cid-1" {
+		t.Fatalf("plan = %#v, want keys=%v group=cid-1", plan, wantKeys)
+	}
+	if !reflect.DeepEqual(reader.calls, []string{"im/search_groups"}) {
+		t.Fatalf("resolver calls = %#v", reader.calls)
+	}
+}
+
+func TestCrossPlatformCoverageCompileListenIMPlanReturnsStructuredAmbiguityBeforeSubscription(t *testing.T) {
+	reader := &listenIMFakeReader{responses: map[string]map[string]any{
+		"contact/search_contact_by_key_word": {
+			"result": []any{
+				map[string]any{"name": "张三", "userId": "u1"},
+				map[string]any{"name": "张三", "userId": "u2"},
+			},
+		},
+	}}
+	_, err := compileListenIMPlan(reader, listenIMOptions{
+		Kind:      "sender",
+		Events:    []string{"message"},
+		UserQuery: "张三",
+	})
+	if err == nil {
+		t.Fatal("ambiguous sender unexpectedly compiled")
+	}
+	var typed *apperrors.Error
+	if !errors.As(err, &typed) || typed.Reason != "resolution_ambiguous" {
+		t.Fatalf("ambiguity error = %#v", err)
+	}
+}
+
+func TestCrossPlatformCoverageEventListenIMCommandDelegatesOneCompiledConsumeLifecycle(t *testing.T) {
+	reader := &listenIMFakeReader{responses: map[string]map[string]any{
+		"im/search_groups": {
+			"result": []any{map[string]any{"title": "项目群", "openConversationId": "cid-1"}},
+		},
+	}}
+	oldReader := eventListenIMReader
+	oldRun := eventRunPersonalConsume
+	t.Cleanup(func() {
+		eventListenIMReader = oldReader
+		eventRunPersonalConsume = oldRun
+	})
+	eventListenIMReader = func() targetresolver.Reader { return reader }
+	var captured personalConsumeOptions
+	var calls int
+	eventRunPersonalConsume = func(_ *cobra.Command, opts personalConsumeOptions) error {
+		calls++
+		captured = opts
+		return nil
+	}
+
+	cmd := newEventListenIMCommand()
+	cmd.SetArgs([]string{
+		"--kind", "group",
+		"--events", "message,reaction",
+		"--chat-query", "项目群",
+		"--max-events", "2",
+		"--duration", "30s",
+		"--dry-run",
+	})
+	if err := cmd.Execute(); err != nil {
+		t.Fatal(err)
+	}
+	if calls != 1 {
+		t.Fatalf("consume lifecycle calls = %d, want 1", calls)
+	}
+	if !reflect.DeepEqual(captured.EventKeys, []string{personal.EventInChat, personal.EventReactionGroup}) ||
+		captured.GroupID != "cid-1" || !captured.Flatten || !captured.Common.DryRun ||
+		captured.Common.MaxEvents != 2 || captured.Common.Duration.String() != "30s" {
+		t.Fatalf("captured options = %#v", captured)
+	}
+}
+
+func TestCrossPlatformCoverageCompileListenIMPlanRejectsIncompatibleKindAndTargets(t *testing.T) {
+	reader := &listenIMFakeReader{}
+	cases := []listenIMOptions{
+		{Kind: "at-me", Events: []string{"reaction"}},
+		{Kind: "all-group", Events: []string{"message"}, ChatID: "cid"},
+		{Kind: "sender", Events: []string{"message"}},
+		{Kind: "group", Events: []string{"message"}, ChatID: "cid", ChatQuery: "群"},
+		{Kind: "group", Events: []string{"message", "reaction"}, ChatID: "cid", QueryCSV: "关键词"},
+	}
+	for _, opts := range cases {
+		if _, err := compileListenIMPlan(reader, opts); err == nil {
+			t.Errorf("options unexpectedly accepted: %#v", opts)
+		}
+	}
+}
+
+func TestCrossPlatformCoverageListenIMCompletionBranches(t *testing.T) {
+	for _, tc := range []struct {
+		name string
+		text string
+		err  error
+		ok   bool
+	}{
+		{name: "transport", err: errors.New("transport")},
+		{name: "empty", text: "  ", ok: true},
+		{name: "invalid json", text: "{invalid"},
+		{name: "valid", text: `{"result":{"ok":true}}`, ok: true},
+	} {
+		t.Run("reader "+tc.name, func(t *testing.T) {
+			helpers.InitDeps(listenIMHelperCaller{text: tc.text, err: tc.err})
+			data, err := (eventTargetReader{}).CallMCPData("im", "search_groups", nil)
+			if (err == nil) != tc.ok {
+				t.Fatalf("data=%#v error=%v ok=%v", data, err, tc.ok)
+			}
+		})
+	}
+
+	if plan, err := compileListenIMPlan(&listenIMFakeReader{}, listenIMOptions{Events: []string{" MESSAGE ", "message"}}); err != nil || len(plan.EventKeys) != 1 {
+		t.Fatalf("default/deduplicated plan = %#v, %v", plan, err)
+	}
+	if _, err := compileListenIMPlan(&listenIMFakeReader{}, listenIMOptions{Kind: "at-me"}); err == nil {
+		t.Fatal("empty event set unexpectedly accepted")
+	}
+	if _, err := compileListenIMPlan(&listenIMFakeReader{}, listenIMOptions{Kind: "unknown", Events: []string{"message"}}); err == nil {
+		t.Fatal("unknown kind unexpectedly accepted")
+	}
+
+	reader := &listenIMFakeReader{responses: map[string]map[string]any{
+		"contact/search_contact_by_key_word": {
+			"result": []any{map[string]any{"name": "甲", "openDingTalkId": "D-user"}},
+		},
+	}}
+	plan, err := compileListenIMPlan(reader, listenIMOptions{Kind: "sender", Events: []string{"message"}, UserQuery: "甲"})
+	if err != nil || plan.UserID != "" || plan.OpenDingTalkID != "D-user" {
+		t.Fatalf("open-id sender plan = %#v, %v", plan, err)
+	}
+	wantErr := errors.New("resolution failed")
+	if _, err := compileListenIMPlan(listenIMErrorReader{err: wantErr}, listenIMOptions{Kind: "sender", Events: []string{"message"}, UserQuery: "甲"}); !errors.Is(err, wantErr) {
+		t.Fatalf("sender resolution error = %v", err)
+	}
+	if _, err := compileListenIMPlan(listenIMErrorReader{err: wantErr}, listenIMOptions{Kind: "group", Events: []string{"message"}, ChatQuery: "群"}); !errors.Is(err, wantErr) {
+		t.Fatalf("group resolution error = %v", err)
+	}
+
+	cmd := newEventListenIMCommand()
+	cmd.SilenceUsage = true
+	cmd.SilenceErrors = true
+	cmd.SetArgs([]string{"--kind", "sender"})
+	if err := cmd.Execute(); err == nil || !strings.Contains(err.Error(), "event +listen-im") {
+		t.Fatalf("command compile error = %v", err)
+	}
+}
+
+func TestCrossPlatformCoverageEventListenIME2ELifecycleCleansAndRollsBack(t *testing.T) {
+	newReader := func() *listenIMFakeReader {
+		return &listenIMFakeReader{responses: map[string]map[string]any{
+			"im/search_groups": {
+				"result": []any{map[string]any{"title": "项目群", "openConversationId": "cid-1"}},
+			},
+		}}
+	}
+	installFacade := func(t *testing.T, reader *listenIMFakeReader) {
+		t.Helper()
+		oldReader := eventListenIMReader
+		oldRun := eventRunPersonalConsume
+		t.Cleanup(func() {
+			eventListenIMReader = oldReader
+			eventRunPersonalConsume = oldRun
+		})
+		eventListenIMReader = func() targetresolver.Reader { return reader }
+		eventRunPersonalConsume = runPersonalEventConsume
+	}
+	installLifecycle := func(t *testing.T) {
+		t.Helper()
+		restore := installPersonalManySeams(t)
+		t.Cleanup(restore)
+		t.Setenv("DWS_CONFIG_DIR", t.TempDir())
+		personalResolveEventIdentity = func(context.Context, string, string) (personal.Identity, error) {
+			return personal.Identity{
+				AccessToken: "token", CorpID: "corp", UserID: "user",
+				ClientID: "client", SourceID: "open",
+			}, nil
+		}
+		personalUpsertRunState = func(string, personal.RunState) error { return nil }
+		personalValidateConsumeConfig = func(consume.Config) error { return nil }
+		personalValidateNoOutputConflict = func(consume.Config, string) error { return nil }
+	}
+
+	t.Run("ready then clean every created subscription", func(t *testing.T) {
+		reader := newReader()
+		installFacade(t, reader)
+		installLifecycle(t)
+		var created, deleted, removed []string
+		personalEnsureSubscription = func(_ context.Context, _ *personal.Client, _ personal.Identity, opts personalConsumeOptions) (*personal.Subscription, string, string, error) {
+			created = append(created, opts.EventKey)
+			return &personal.Subscription{SubscribeID: "sub-" + opts.EventKey}, opts.EventKey, "group", nil
+		}
+		personalDeleteSubscription = func(_ *personal.Client, _ context.Context, id string) error {
+			deleted = append(deleted, id)
+			return nil
+		}
+		personalRemoveRunStates = func(_ string, ids []string) error {
+			removed = append(removed, ids...)
+			return nil
+		}
+		personalConsumeRunMany = func(_ context.Context, cfg consume.Config, specs []consume.ConsumerSpec) error {
+			if len(specs) != 2 || !cfg.Flatten {
+				t.Fatalf("consume specs/config = %#v / %#v", specs, cfg)
+			}
+			fmt.Fprintf(cfg.Stderr, "[event] ready event_count=%d bus_pid=123\n", len(specs))
+			return nil
+		}
+
+		cmd := newEventListenIMCommand()
+		var stderr bytes.Buffer
+		cmd.SetErr(&stderr)
+		cmd.SetArgs([]string{
+			"--kind", "group", "--events", "message,reaction",
+			"--chat-query", "项目群", "--max-events", "1",
+		})
+		if err := cmd.Execute(); err != nil {
+			t.Fatal(err)
+		}
+		wantEvents := []string{personal.EventInChat, personal.EventReactionGroup}
+		if !reflect.DeepEqual(created, wantEvents) {
+			t.Fatalf("created = %#v, want %#v", created, wantEvents)
+		}
+		wantDeleted := []string{"sub-" + personal.EventReactionGroup, "sub-" + personal.EventInChat}
+		if !reflect.DeepEqual(deleted, wantDeleted) || !reflect.DeepEqual(removed, wantDeleted) {
+			t.Fatalf("deleted=%#v removed=%#v want=%#v", deleted, removed, wantDeleted)
+		}
+		if !strings.Contains(stderr.String(), "[event] ready event_count=2") {
+			t.Fatalf("missing ready marker: %s", stderr.String())
+		}
+		if !reflect.DeepEqual(reader.calls, []string{"im/search_groups"}) {
+			t.Fatalf("resolver calls = %#v", reader.calls)
+		}
+	})
+
+	t.Run("second create failure rolls back first without starting consumer", func(t *testing.T) {
+		reader := newReader()
+		installFacade(t, reader)
+		installLifecycle(t)
+		wantErr := errors.New("second subscription failed")
+		calls := 0
+		personalEnsureSubscription = func(_ context.Context, _ *personal.Client, _ personal.Identity, opts personalConsumeOptions) (*personal.Subscription, string, string, error) {
+			calls++
+			if calls == 2 {
+				return nil, "", "", wantErr
+			}
+			return &personal.Subscription{SubscribeID: "sub-first"}, opts.EventKey, "group", nil
+		}
+		var deleted, removed []string
+		personalDeleteSubscription = func(_ *personal.Client, _ context.Context, id string) error {
+			deleted = append(deleted, id)
+			return nil
+		}
+		personalRemoveRunStates = func(_ string, ids []string) error {
+			removed = append(removed, ids...)
+			return nil
+		}
+		personalConsumeRunMany = func(context.Context, consume.Config, []consume.ConsumerSpec) error {
+			t.Fatal("consumer started after partial subscription failure")
+			return nil
+		}
+
+		cmd := newEventListenIMCommand()
+		var stderr bytes.Buffer
+		cmd.SetErr(&stderr)
+		cmd.SilenceUsage = true
+		cmd.SetArgs([]string{
+			"--kind", "group", "--events", "message,reaction",
+			"--chat-query", "项目群",
+		})
+		err := cmd.Execute()
+		if err == nil || !strings.Contains(err.Error(), wantErr.Error()) {
+			t.Fatalf("error = %v, want %v", err, wantErr)
+		}
+		if !reflect.DeepEqual(deleted, []string{"sub-first"}) || !reflect.DeepEqual(removed, []string{"sub-first"}) {
+			t.Fatalf("rollback deleted=%#v removed=%#v", deleted, removed)
+		}
+	})
+}

internal/app/event_personal_command.go

@@ -29,8 +29,11 @@ import (
 	"text/tabwriter"
 	"time"
 
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/helpers"
+
 	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"
 	dwsevent "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/bus"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/busctl"
@@ -170,13 +173,43 @@ func newEventSchemaCommand() *cobra.Command {
 	cmd.Flags().StringVarP(&formatRaw, "format", "f", "json", "输出格式: json")
 	cmd.Flags().BoolVar(&flatten, "flatten", false, "显示 --flatten 消费模式对应的顶层业务字段 schema")
 	hideEventInternalFlags(cmd, "as")
-	cli.AnnotateRuntimePositionals(cmd, cli.RuntimeSchemaPositional{
+	cli.AnnotateRuntimePositionals(cmd, contract.RuntimeSchemaPositional{
 		Name:        "event_key",
 		Type:        "string",
 		Description: "要查询 payload 字段定义的个人事件码",
 		Required:    true,
 		Index:       0,
 	})
+	helpers.DeclareLeafMetadata(cmd, helpers.LeafSpec{
+		Safety: contract.SafetySpec{
+			Effect: "read", Risk: "low",
+			Confirmation: "not_required", Idempotency: "idempotent",
+		},
+		Contract: helpers.LeafContract{
+			Identity: contract.ToolIdentitySpec{
+				ProductID:      "event",
+				Name:           "schema",
+				CanonicalPath:  "event.schema",
+				CLIPath:        "event schema",
+				PrimaryCLIPath: "event schema",
+			},
+			Description: "查询指定个人事件码的输出字段结构；Agent 应查询 --flatten 模式",
+			Interface: &contract.InterfaceSpec{
+				Mode:         "local",
+				Availability: "available",
+				Reason:       "命令读取 CLI 内置的个人事件 payload 定义，不绑定 pinned MCP RPC",
+			},
+			Selection: contract.SelectionSpec{
+				AgentSummary: "查询指定个人事件码的输出字段结构；Agent 应查询 --flatten 模式",
+				UseWhen:      []string{"已知任一公开个人 IM event_key，消费前需要理解输出字段或保守 payload 契约"},
+				AvoidWhen: []string{
+					"查询 CLI 命令参数契约时用顶层 dws schema",
+					"要实际收事件时用 event consume",
+				},
+				Examples: []string{"dws event schema user_im_message_receive_at --flatten --format json"},
+			},
+		},
+	})
 	return cmd
 }
 

internal/app/event_registration_test.go

@@ -10,7 +10,7 @@ import (
 	"github.com/spf13/cobra"
 )
 
-func TestEventCommandRemainsVisibleAsBuiltInPublicGroup(t *testing.T) {
+func TestCrossPlatformCoverageEventCommandRemainsVisibleAsBuiltInPublicGroup(t *testing.T) {
 	root := &cobra.Command{Use: "dws"}
 	event := newEventCommand()
 	markdown := &cobra.Command{Use: "markdown"}
@@ -37,7 +37,7 @@ func TestEventCommandRemainsVisibleAsBuiltInPublicGroup(t *testing.T) {
 		leaves = append(leaves, command.Name())
 	}
 	sort.Strings(leaves)
-	want := []string{"consume", "list", "schema", "status", "stop"}
+	want := []string{"+listen-im", "consume", "list", "schema", "status", "stop"}
 	if len(leaves) != len(want) {
 		t.Fatalf("public event leaves = %v, want %v", leaves, want)
 	}
@@ -48,7 +48,7 @@ func TestEventCommandRemainsVisibleAsBuiltInPublicGroup(t *testing.T) {
 	}
 }
 
-func TestPluginCannotReplaceBuiltInEventCommand(t *testing.T) {
+func TestCrossPlatformCoveragePluginCannotReplaceBuiltInEventCommand(t *testing.T) {
 	root := &cobra.Command{Use: "dws"}
 	builtIn := newEventCommand()
 	root.AddCommand(builtIn)

internal/app/event_stop_safety_test.go

@@ -71,7 +71,7 @@ func TestEventStopDryRunPrecedesConfirmationAndReturnsPreview(t *testing.T) {
 	}
 }
 
-func TestEventStopDryRunDoesNotBypassTargetValidation(t *testing.T) {
+func TestCrossPlatformCoverageEventStopDryRunDoesNotBypassTargetValidation(t *testing.T) {
 	for _, test := range []struct {
 		name string
 		args []string

internal/app/host_compat.go

@@ -11,6 +11,13 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+// This file holds deliberate no-op stubs that act as edition-sync anchors for
+// the private wukong edition overlay. The overlay replaces these function
+// bodies with real host-compatibility configuration while the open-source
+// build keeps them empty; both editions therefore share identical call sites
+// (access_token_resolve.go, auth_command.go, doctor_command.go,
+// force_refresh.go). These stubs are sync seams for the edition overlay, not
+// dead code: do not delete them or their call sites during cleanup.
 package app
 
 import (

internal/app/legacy.go

@@ -27,9 +27,11 @@ import (
 	"github.com/spf13/cobra"
 )
 
-func newLegacyPublicCommands(runner executor.Runner, caller edition.ToolCaller, loadUserShortcuts bool) []*cobra.Command {
-	injectStaticServers()
-	helpers.InitDeps(caller)
+// mountLegacyPublicCommands builds the product + shortcut command tree without
+// mutating process-global MCP deps or dynamic server endpoints. Used by the
+// Schema source root (declaration-only) path so assembly cannot clobber a live
+// runtime's InitDeps caller or plugin endpoints.
+func mountLegacyPublicCommands(runner executor.Runner, loadUserShortcuts bool) []*cobra.Command {
 	commands := helpers.NewPublicCommands(runner)
 	// Load user-defined shortcuts (~/.dws/shortcuts/*.yaml) BEFORE compiling the
 	// command tree, so distilled high-frequency operations mount alongside the
@@ -51,6 +53,14 @@ func newLegacyPublicCommands(runner executor.Runner, caller edition.ToolCaller,
 	return mergeTopLevelCommands(commands)
 }
 
+// newLegacyPublicCommands is the executable CLI path: inject static MCP
+// endpoints, InitDeps, then mount the public command tree.
+func newLegacyPublicCommands(runner executor.Runner, caller edition.ToolCaller, loadUserShortcuts bool) []*cobra.Command {
+	injectStaticServers()
+	helpers.InitDeps(caller)
+	return mountLegacyPublicCommands(runner, loadUserShortcuts)
+}
+
 func injectStaticServers() {
 	hooks := edition.Get()
 	var servers []edition.ServerInfo
@@ -82,10 +92,6 @@ func injectStaticServers() {
 	SetDynamicServers(descriptors)
 }
 
-func newLegacyHiddenCommands(_ executor.Runner) []*cobra.Command {
-	return nil
-}
-
 func mergeTopLevelCommands(commands []*cobra.Command) []*cobra.Command {
 	byName := make(map[string]*cobra.Command, len(commands))
 	for _, cmd := range commands {

internal/app/mcp_url_command.go

@@ -18,7 +18,10 @@ import (
 	"fmt"
 	"strings"
 
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/helpers"
+
 	"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/output"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition"
@@ -74,13 +77,43 @@ func newMCPURLGetCommand(caller edition.ToolCaller) *cobra.Command {
 			return writeMCPURLResult(cmd, result)
 		},
 	}
-	cli.AnnotateRuntimePositionals(cmd, cli.RuntimeSchemaPositional{
+	cli.AnnotateRuntimePositionals(cmd, contract.RuntimeSchemaPositional{
 		Name:        "mcp_id",
 		Type:        "string",
 		Description: "钉钉 MCP 市场中的 mcpId",
 		Required:    true,
 		Index:       0,
 	})
+	helpers.DeclareLeafMetadata(cmd, helpers.LeafSpec{
+		Safety: contract.SafetySpec{
+			Effect: "read", Risk: "medium",
+			Confirmation: "not_required", Idempotency: "idempotent",
+		},
+		Contract: helpers.LeafContract{
+			Identity: contract.ToolIdentitySpec{
+				ProductID:      "mcp",
+				Name:           "url_get",
+				CanonicalPath:  "mcp.url_get",
+				CLIPath:        "mcp url get",
+				PrimaryCLIPath: "mcp url get",
+			},
+			Description: "按 MCP 市场 mcpId 获取当前用户和组织可用的 Streamable HTTP 地址",
+			Interface: &contract.InterfaceSpec{
+				Mode:         "composite",
+				Availability: "available",
+				Reason:       "Reviewed unpinned remote adapter: the public CLI wrapper calls the helper-only mcp-meta/get_mcp_server_url endpoint, which is intentionally absent from the public product catalog and pinned MCP metadata.",
+			},
+			Selection: contract.SelectionSpec{
+				AgentSummary: "按 MCP 市场 mcpId 获取当前用户和组织可用的 Streamable HTTP 地址",
+				UseWhen:      []string{"已知钉钉 MCP 市场 mcpId，需要获得当前身份可用的 Streamable HTTP 连接地址"},
+				AvoidWhen: []string{
+					"只是查询 DWS 已公开命令或参数时使用 dws schema",
+					"用户要求把返回的凭据 URL 发送到群聊、文档、邮件、日志或代码仓库时不要执行或传播",
+				},
+				Examples: []string{"dws mcp url get 10043 --format json"},
+			},
+		},
+	})
 	return cmd
 }
 

internal/app/multi_skill_safety_contract_test.go

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

internal/app/p1_shared_install_test.go

@@ -33,43 +33,43 @@ func contains(ss []string, want string) bool {
 	return false
 }
 
-// dws-shared must ship even when --skill narrows the set to a single product.
+// dingtalk-shared must ship even when --skill narrows the set to a single product.
 func TestP1SharedAlwaysIncludedWithSkillFilter(t *testing.T) {
-	src := writeMultiSkillSrc(t, "dws-shared", "dingtalk-aitable", "dingtalk-calendar")
+	src := writeMultiSkillSrc(t, "dingtalk-shared", "dingtalk-aitable", "dingtalk-calendar")
 	all, err := listMultiSkillNames(src)
 	if err != nil {
 		t.Fatal(err)
 	}
-	if !contains(all, "dws-shared") {
-		t.Fatalf("listMultiSkillNames did not enumerate dws-shared: %v", all)
+	if !contains(all, "dingtalk-shared") {
+		t.Fatalf("listMultiSkillNames did not enumerate dingtalk-shared: %v", all)
 	}
 	filtered, err := filterMultiSkillNames(all, []string{"aitable"}, nil)
 	if err != nil {
 		t.Fatal(err)
 	}
-	if contains(filtered, "dws-shared") {
-		t.Fatalf("precondition: filter should drop dws-shared for -s aitable: %v", filtered)
+	if contains(filtered, "dingtalk-shared") {
+		t.Fatalf("precondition: filter should drop dingtalk-shared for -s aitable: %v", filtered)
 	}
 	final := ensureMandatorySharedSkill(filtered, all)
-	if !contains(final, "dws-shared") {
-		t.Fatalf("ensureMandatorySharedSkill must re-add dws-shared: %v", final)
+	if !contains(final, "dingtalk-shared") {
+		t.Fatalf("ensureMandatorySharedSkill must re-add dingtalk-shared: %v", final)
 	}
 
-	// Actually install with the filtered+mandatory set and assert dws-shared landed.
+	// Actually install with the filtered+mandatory set and assert dingtalk-shared landed.
 	dest := t.TempDir()
 	var out, errOut bytes.Buffer
 	if _, _, err := installMultiSkillToHomes(src, final, []string{dest}, &out, &errOut); err != nil {
 		t.Fatalf("install: %v (%s)", err, errOut.String())
 	}
-	if _, err := os.Stat(filepath.Join(dest, "dws-shared", "SKILL.md")); err != nil {
-		t.Fatalf("dws-shared not installed with -s aitable: %v", err)
+	if _, err := os.Stat(filepath.Join(dest, "dingtalk-shared", "SKILL.md")); err != nil {
+		t.Fatalf("dingtalk-shared not installed with -s aitable: %v", err)
 	}
 	if _, err := os.Stat(filepath.Join(dest, "dingtalk-aitable", "SKILL.md")); err != nil {
 		t.Fatalf("dingtalk-aitable not installed: %v", err)
 	}
 }
 
-// When the source has no dws-shared (older layout), nothing is forced.
+// When the source has no dingtalk-shared (older layout), nothing is forced.
 func TestP1SharedNoopWhenAbsent(t *testing.T) {
 	src := writeMultiSkillSrc(t, "dingtalk-aitable")
 	all, err := listMultiSkillNames(src)
@@ -77,7 +77,7 @@ func TestP1SharedNoopWhenAbsent(t *testing.T) {
 		t.Fatal(err)
 	}
 	final := ensureMandatorySharedSkill([]string{"dingtalk-aitable"}, all)
-	if contains(final, "dws-shared") {
-		t.Fatalf("must not invent dws-shared when source lacks it: %v", final)
+	if contains(final, "dingtalk-shared") {
+		t.Fatalf("must not invent dingtalk-shared when source lacks it: %v", final)
 	}
 }

internal/app/param_alias_e2e_test.go

@@ -39,7 +39,7 @@ func (c *paramAliasCaptureCaller) CallTool(_ context.Context, server, tool strin
 		copyArgs[key] = value
 	}
 	c.calls = append(c.calls, paramAliasToolCall{server: server, tool: tool, args: copyArgs})
-	text := paramAliasResponseForTool(tool)
+	text := c.paramAliasResponseForTool(tool)
 	return &edition.ToolResult{Content: []edition.ContentBlock{{Type: "text", Text: text}}}, nil
 }
 
@@ -48,7 +48,7 @@ func (c *paramAliasCaptureCaller) CallTool(_ context.Context, server, tool strin
 // print the transport result and need an empty object; smart shortcuts that
 // inspect a read response receive the smallest shape that lets their full RunE
 // complete without falling back to a validation error.
-func paramAliasResponseForTool(tool string) string {
+func (c *paramAliasCaptureCaller) paramAliasResponseForTool(tool string) string {
 	switch tool {
 	case "list_calendar_events":
 		return `{"result":{"events":[]}}`
@@ -58,6 +58,27 @@ func paramAliasResponseForTool(tool string) string {
 		return `{"deptList":[{"deptId":1,"name":"Fixture Dept"}]}`
 	case "search_groups":
 		return `{"result":{"items":[{"openConversationId":"fixture-conversation","title":"Fixture Group"}]}}`
+	case "search_contact_by_key_word":
+		return `{"result":[{"name":"Fixture User","userId":"fixture-user","openDingTalkId":"D-fixture-user"}]}`
+	case "list_doc_versions":
+		return `{"result":{"items":[{"version":3}]}}`
+	case "revert_doc_version":
+		return `{"version":3}`
+	case "search_doc_templates":
+		return `{"result":[{"templateId":"fixture-template-id"}]}`
+	case "create_document":
+		return `{"nodeId":"fixture-node"}`
+	case "get_document_content":
+		for index := len(c.calls) - 2; index >= 0; index-- {
+			call := c.calls[index]
+			for _, key := range []string{"jsonml", "markdown"} {
+				if content, ok := call.args[key].(string); ok {
+					encoded, _ := json.Marshal(map[string]any{"revision": 1, key: content})
+					return string(encoded)
+				}
+			}
+		}
+		return `{"revision":1}`
 	default:
 		return `{}`
 	}
@@ -132,7 +153,7 @@ func executeParamAliasDryRunE2E(t *testing.T, args ...string) (*pipeline.Context
 	}()
 	rejectRunner := &paramAliasDryRunRejectRunner{}
 	originalRunnerFactory := rootNewCommandRunnerWithFlags
-	rootNewCommandRunnerWithFlags = func(cli.CatalogLoader, *GlobalFlags) executor.Runner {
+	rootNewCommandRunnerWithFlags = func(*GlobalFlags) executor.Runner {
 		return rejectRunner
 	}
 	root := NewRootCommand()
@@ -165,6 +186,24 @@ func executeParamAliasDryRunE2E(t *testing.T, args ...string) (*pipeline.Context
 	return ctx, preview, append([]executor.Invocation(nil), rejectRunner.attempts...), executeErr
 }
 
+func TestCrossPlatformCoverageFlagListDryRunStopsBeforeReadDispatch(t *testing.T) {
+	_, preview, attempts, err := executeParamAliasDryRunE2E(t,
+		"chat", "+flag-list", "--page-size", "20", "--cursor", "0", "--dry-run",
+	)
+	if err != nil {
+		t.Fatalf("flag-list dry-run error = %v", err)
+	}
+	if len(attempts) != 0 {
+		t.Fatalf("flag-list dry-run crossed dispatch boundary: %#v", attempts)
+	}
+	if !preview.DryRun || preview.Executed || preview.Tool != "list_message_favorites" {
+		t.Fatalf("flag-list dry-run preview = %#v", preview)
+	}
+	if preview.Arguments["cursor"] != float64(0) || preview.Arguments["size"] != "20" {
+		t.Fatalf("flag-list dry-run arguments = %#v", preview.Arguments)
+	}
+}
+
 func executeParamAliasE2E(t *testing.T, caller *paramAliasCaptureCaller, args ...string) (*pipeline.Context, error) {
 	t.Helper()
 	originalArgs := os.Args
@@ -172,7 +211,7 @@ func executeParamAliasE2E(t *testing.T, caller *paramAliasCaptureCaller, args ..
 	defer func() { os.Args = originalArgs }()
 
 	originalRunnerFactory := rootNewCommandRunnerWithFlags
-	rootNewCommandRunnerWithFlags = func(cli.CatalogLoader, *GlobalFlags) executor.Runner {
+	rootNewCommandRunnerWithFlags = func(*GlobalFlags) executor.Runner {
 		return &paramAliasCaptureRunner{caller: caller}
 	}
 	root := NewRootCommand()
@@ -191,7 +230,7 @@ func executeParamAliasE2E(t *testing.T, caller *paramAliasCaptureCaller, args ..
 	return ctx, root.Execute()
 }
 
-func TestBooleanStickyCannotBypassDestructiveConfirmation(t *testing.T) {
+func TestCrossPlatformCoverageBooleanStickyCannotBypassDestructiveConfirmation(t *testing.T) {
 	tests := []struct {
 		name           string
 		confirmation   []string
@@ -244,7 +283,7 @@ func TestBooleanStickyCannotBypassDestructiveConfirmation(t *testing.T) {
 	}
 }
 
-func TestParamAliasReadCommandFinalPayload(t *testing.T) {
+func TestCrossPlatformCoverageParamAliasReadCommandFinalPayload(t *testing.T) {
 	caller := &paramAliasCaptureCaller{}
 	start := "2026-03-10T14:00:00+08:00"
 	end := "2026-03-10T18:00:00+08:00"
@@ -279,7 +318,7 @@ func TestParamAliasReadCommandFinalPayload(t *testing.T) {
 	}
 }
 
-func TestParamAliasWriteCommandFinalPayload(t *testing.T) {
+func TestCrossPlatformCoverageParamAliasWriteCommandFinalPayload(t *testing.T) {
 	caller := &paramAliasCaptureCaller{}
 	ctx, err := executeParamAliasE2E(t, caller,
 		"chat", "message", "send",
@@ -311,7 +350,7 @@ func TestParamAliasWriteCommandFinalPayload(t *testing.T) {
 	}
 }
 
-func TestChatReactionConversationAliasesReachCanonicalPayload(t *testing.T) {
+func TestCrossPlatformCoverageChatReactionConversationAliasesReachCanonicalPayload(t *testing.T) {
 	tests := []struct {
 		name     string
 		command  []string
@@ -390,7 +429,7 @@ func TestChatReactionConversationAliasesReachCanonicalPayload(t *testing.T) {
 	}
 }
 
-func TestAllGeneratedChatParamAliasesReachRuntimeCobraContract(t *testing.T) {
+func TestCrossPlatformCoverageAllGeneratedChatParamAliasesReachRuntimeCobraContract(t *testing.T) {
 	root := NewRootCommand()
 	engine := newPipelineEngine()
 	entries, err := cli.ReduceParamAliases(root)
@@ -478,7 +517,7 @@ func TestAllGeneratedChatParamAliasesReachRuntimeCobraContract(t *testing.T) {
 	t.Logf("verified generated chat parameter routes: entries=%d aliases=%d blocked=%d ambiguous=%d", chatEntries, aliasCases, guardCases[pipeline.FlagProtectionBlocked], guardCases[pipeline.FlagProtectionAmbiguous])
 }
 
-func TestIMUserIDHallucinationRoutes(t *testing.T) {
+func TestCrossPlatformCoverageIMUserIDHallucinationRoutes(t *testing.T) {
 	tests := []struct {
 		command string
 		want    string
@@ -531,7 +570,7 @@ func TestIMUserIDHallucinationRoutes(t *testing.T) {
 	}
 }
 
-func TestHiddenIMListDirectRemainsOutsideCentralAliasTable(t *testing.T) {
+func TestCrossPlatformCoverageHiddenIMListDirectRemainsOutsideCentralAliasTable(t *testing.T) {
 	const command = "chat message list-direct"
 	if _, ok := cli.LookupParamAlias(command); ok {
 		t.Fatalf("hidden command %q unexpectedly entered the public generated alias table", command)
@@ -556,7 +595,7 @@ func TestHiddenIMListDirectRemainsOutsideCentralAliasTable(t *testing.T) {
 	}
 }
 
-func TestSelectedParamAliasesProduceCanonicalEquivalentDryRunPreviews(t *testing.T) {
+func TestCrossPlatformCoverageSelectedParamAliasesProduceCanonicalEquivalentDryRunPreviews(t *testing.T) {
 	tests := []struct {
 		name            string
 		tool            string
@@ -653,7 +692,7 @@ func TestSelectedParamAliasesProduceCanonicalEquivalentDryRunPreviews(t *testing
 	}
 }
 
-func TestParamAliasCanonicalConflictFailsBeforeRunE(t *testing.T) {
+func TestCrossPlatformCoverageParamAliasCanonicalConflictFailsBeforeRunE(t *testing.T) {
 	caller := &paramAliasCaptureCaller{}
 	for _, args := range [][]string{
 		{"calendar", "event", "list", "--date", "2026-03-10", "--start", "2026-03-11"},
@@ -678,7 +717,7 @@ func TestParamAliasCanonicalConflictFailsBeforeRunE(t *testing.T) {
 	}
 }
 
-func TestAllReviewedParamAliasGuardsReachRuntimeContract(t *testing.T) {
+func TestCrossPlatformCoverageAllReviewedParamAliasGuardsReachRuntimeContract(t *testing.T) {
 	concepts, err := cli.LoadParamConcepts()
 	if err != nil {
 		t.Fatalf("LoadParamConcepts() error = %v", err)
@@ -770,7 +809,7 @@ func TestAllReviewedParamAliasGuardsReachRuntimeContract(t *testing.T) {
 	}
 }
 
-func TestRepresentativeParamAliasGuardsReachFinalErrorsWithoutDispatch(t *testing.T) {
+func TestCrossPlatformCoverageRepresentativeParamAliasGuardsReachFinalErrorsWithoutDispatch(t *testing.T) {
 	for _, test := range []struct {
 		path       string
 		emitted    string
@@ -817,7 +856,7 @@ func TestRepresentativeParamAliasGuardsReachFinalErrorsWithoutDispatch(t *testin
 	}
 }
 
-func TestFlagConflictErrorFormattingIsDeterministic(t *testing.T) {
+func TestCrossPlatformCoverageFlagConflictErrorFormattingIsDeterministic(t *testing.T) {
 	err := (&pipeline.FlagConflictError{Command: "dws demo", Canonical: "start", Spellings: []string{"start", "date"}}).Error()
 	want := `conflicting parameter spellings for --start on "dws demo": --date, --start; pass exactly one spelling`
 	if err != want {

internal/app/param_alias_fixture_test.go

@@ -44,7 +44,7 @@ import (
 //   - expect=<realFlag>            : emitted must reduce to that canonical flag.
 //   - expect=did-you-mean:blocked  : block guard hit; never auto-rewritten.
 //   - expect=did-you-mean:ambiguous: co-occurrence guard hit; never rewritten.
-func TestParamAliasFixtureThroughEmbeddedDeliveryPath(t *testing.T) {
+func TestCrossPlatformCoverageParamAliasFixtureThroughEmbeddedDeliveryPath(t *testing.T) {
 	concepts, err := cli.LoadParamConcepts()
 	if err != nil {
 		t.Fatalf("LoadParamConcepts() error = %v", err)
@@ -113,13 +113,19 @@ func TestParamAliasFixtureThroughEmbeddedDeliveryPath(t *testing.T) {
 					t.Fatalf("reviewed canonical --%s on %q is not a real Cobra flag", c.Expect, c.Command)
 				}
 				flagArgs := ctx.Args[len(strings.Fields(c.Command)):]
-				if len(flagArgs) < 2 || flagArgs[1] != fixtureValue {
-					t.Fatalf("%q on %q lost its value: args=%v", c.Emitted, c.Command, ctx.Args)
+				if len(flagArgs) == 0 {
+					t.Fatalf("%q on %q lost its flag and value: args=%v", c.Emitted, c.Command, ctx.Args)
 				}
 				got := flagArgs[0]
-				gotBare := strings.SplitN(strings.TrimPrefix(got, "--"), "=", 2)[0]
+				gotBare, inlineValue, hasInlineValue := strings.Cut(strings.TrimPrefix(got, "--"), "=")
 				switch {
-				case got == "--"+c.Expect:
+				case hasInlineValue && inlineValue != fixtureValue:
+					t.Fatalf("%q on %q changed its inline value: got %q, want %q (args=%v)", c.Emitted, c.Command, inlineValue, fixtureValue, ctx.Args)
+				case !hasInlineValue && (len(flagArgs) < 2 || flagArgs[1] != fixtureValue):
+					t.Fatalf("%q on %q lost its value: args=%v", c.Emitted, c.Command, ctx.Args)
+				}
+				switch {
+				case gotBare == c.Expect:
 					// (1) rewritten; the embedded table must agree.
 					if !hasEntry {
 						t.Fatalf("%q on %q was rewritten without an embedded alias entry", c.Emitted, c.Command)

internal/app/param_alias_payload_equivalence_test.go

@@ -29,14 +29,37 @@ var paramAliasCompleteCommands = map[string][]string{
 	"attendance check result":                  {"attendance", "check", "result", "--users", "user-1,user-2", "--start", "2026-03-01", "--end", "2026-03-02"},
 	"attendance +check-result":                 {"attendance", "+check-result", "--users", "user-1,user-2", "--start", "2026-03-01", "--end", "2026-03-02"},
 	"calendar event list":                      {"calendar", "event", "list", "--start", "2026-03-10T14:00:00+08:00", "--end", "2026-03-10T18:00:00+08:00", "--calendar-id", "primary", "--cursor", "cursor-1", "--limit", "7"},
+	"chat +chat-messages":                      {"chat", "+chat-messages", "--group", "fixture-conversation"},
+	"chat +chat-add-bot":                       {"chat", "+chat-add-bot", "--id", "fixture-conversation", "--robot-code", "robot-1", "--yes"},
+	"chat +chat-audit-join":                    {"chat", "+chat-audit-join", "--group", "fixture-conversation", "--record-id", "7", "--applicant", "user-1", "--inviter", "user-2", "--status", "AuditApprove", "--yes"},
+	"chat +chat-members-get":                   {"chat", "+chat-members-get", "--id", "fixture-conversation", "--users", "D-user-1,D-user-2"},
+	"chat +chat-members-list":                  {"chat", "+chat-members-list", "--conversation-id", "fixture-conversation", "--member-types", "user,bot"},
+	"chat +chat-mute-member":                   {"chat", "+chat-mute-member", "--group", "fixture-conversation", "--users", "D-user-1,D-user-2", "--mute-time", "3600000", "--yes"},
+	"chat +chat-remove-bot":                    {"chat", "+chat-remove-bot", "--id", "fixture-conversation", "--bot-id", "bot-1", "--yes"},
+	"chat +chat-role-remove-user":              {"chat", "+chat-role-remove-user", "--group", "fixture-conversation", "--user", "D-user-1", "--role-ids", "role-1", "--yes"},
+	"chat +chat-transfer-owner":                {"chat", "+chat-transfer-owner", "--group", "fixture-conversation", "--new-owner", "D-user-1", "--yes"},
+	"chat +chat-update":                        {"chat", "+chat-update", "--group", "fixture-conversation", "--name", "Fixture Renamed Group", "--yes"},
 	"chat +bot-find":                           {"chat", "+bot-find", "--query", "fixture", "--limit", "7"},
 	"chat +bot-search":                         {"chat", "+bot-search", "--name", "Fixture Bot", "--page", "2", "--size", "7"},
 	"chat +category-create":                    {"chat", "+category-create", "--title", "Fixture Cat", "--yes"},
 	"chat +category-rename":                    {"chat", "+category-rename", "--category-id", "7", "--title", "Renamed Cat", "--yes"},
 	"chat +group-members":                      {"chat", "+group-members", "--group", "Fixture Group"},
+	"chat +conversation-set-top":               {"chat", "+conversation-set-top", "--conversation-id", "fixture-conversation", "--yes"},
+	"chat +feed-group-query-item":              {"chat", "+feed-group-query-item", "--category-id", "7", "--conversation-ids", "fixture-conversation"},
+	"chat +flag-cancel":                        {"chat", "+flag-cancel", "--conversation-id", "fixture-conversation", "--message-id", "message-1", "--yes"},
+	"chat +flag-create":                        {"chat", "+flag-create", "--conversation-id", "fixture-conversation", "--message-id", "message-1", "--yes"},
+	"chat +flag-list":                          {"chat", "+flag-list", "--cursor", "0", "--page-size", "7"},
+	"chat +messages-combine-forward":           {"chat", "+messages-combine-forward", "--src-conversation-id", "fixture-source", "--msg-ids", "message-1,message-2", "--dest-conversation-id", "fixture-destination", "--yes"},
+	"chat +messages-forward":                   {"chat", "+messages-forward", "--src-conversation-id", "fixture-source", "--msg-id", "message-1", "--dest-conversation-id", "fixture-destination", "--yes"},
+	"chat +messages-forward-topic":             {"chat", "+messages-forward-topic", "--src-msg-id", "message-1", "--src-conversation-id", "fixture-source", "--src-thread-id", "convThread-fixture", "--dest-conversation-id", "fixture-destination", "--yes"},
+	"chat +messages-list":                      {"chat", "+messages-list", "--group", "fixture-conversation", "--time", "2026-03-10 00:00:00", "--limit", "7"},
 	"chat +messages-list-direct":               {"chat", "+messages-list-direct", "--user", "user-1", "--time", "2026-03-10 00:00:00", "--limit", "7"},
 	"chat +messages-list-unread-conversations": {"chat", "+messages-list-unread-conversations", "--count", "7", "--exclude-muted"},
+	"chat +messages-reply":                     {"chat", "+messages-reply", "--conversation-id", "fixture-conversation", "--ref-msg-id", "message-1", "--ref-sender", "D-sender", "--text", "hello fixture", "--yes"},
+	"chat +messages-resource-download":         {"chat", "+messages-resource-download", "--resource-id", "resource-1", "--message-id", "message-1", "--open-conversation-id", "fixture-conversation", "--output", "downloads/fixture.bin"},
+	"chat +messages-set-pin":                   {"chat", "+messages-set-pin", "--open-conversation-id", "fixture-conversation", "--msg-id", "message-1", "--yes"},
 	"chat +messages-send-by-webhook":           {"chat", "+messages-send-by-webhook", "--token", "fixture-token", "--title", "Fixture Alert", "--text", "fixture", "--at-users", "user-1,user-2", "--yes"},
+	"chat +search-msg":                         {"chat", "+search-msg", "--group", "fixture-conversation", "--query", "fixture", "--start", "2026-03-10T00:00:00+08:00", "--end", "2026-03-11T00:00:00+08:00", "--no-enrich"},
 	"chat +send-to-group":                      {"chat", "+send-to-group", "--group", "Fixture Group", "--text", "hello fixture", "--yes"},
 	"chat +unread-chats":                       {"chat", "+unread-chats", "--count", "7", "--exclude-muted"},
 	"chat bot find":                            {"chat", "bot", "find", "--query", "fixture", "--limit", "7"},
@@ -79,9 +102,36 @@ var paramAliasCompleteCommands = map[string][]string{
 	"ding +receiver-status":                    {"ding", "+receiver-status", "--ding-id", "ding-1"},
 	"ding message receiver-status":             {"ding", "message", "receiver-status", "--ding-id", "ding-1"},
 	"ding message send":                        {"ding", "message", "send", "--robot-code", "robot-1", "--content", "fixture", "--users", "user-1", "--yes"},
+	"doc +comment-create":                      {"doc", "+comment-create", "--node", "node-1", "--content", "fixture comment", "--yes"},
+	"doc +comment-list":                        {"doc", "+comment-list", "--node", "node-1", "--limit", "7", "--cursor", "cursor-1"},
+	"doc +comment-reply":                       {"doc", "+comment-reply", "--node", "node-1", "--comment-key", "comment-1", "--content", "fixture reply", "--yes"},
+	"doc +access-grant":                        {"doc", "+access-grant", "--node", "node-1", "--to", "Fixture User", "--role", "READER", "--workspace", "workspace-1", "--yes"},
+	"doc +copy":                                {"doc", "+copy", "--node", "node-1", "--workspace", "workspace-1", "--yes"},
+	"doc +create":                              {"doc", "+create", "--name", "Fixture Document", "--content", "fixture body", "--doc-format", "markdown"},
+	"doc +create-from-template":                {"doc", "+create-from-template", "--query", "fixture template", "--name", "Fixture From Template", "--folder", "folder-1", "--workspace", "workspace-1"},
+	"doc +doc-append":                          {"doc", "+doc-append", "--doc", "node-1", "--text", "fixture appendix", "--yes"},
+	"doc +export-submit":                       {"doc", "+export-submit", "--node", "node-1", "--export-format", "docx"},
+	"doc +fetch":                               {"doc", "+fetch", "--node", "node-1", "--scope", "section", "--start-block-id", "block-1"},
+	"doc +find-doc":                            {"doc", "+find-doc", "--query", "fixture", "--limit", "7"},
+	"doc +history-revert":                      {"doc", "+history-revert", "--node", "node-1", "--version", "3", "--yes"},
+	"doc +inspect":                             {"doc", "+inspect", "--node", "node-1", "--include-history"},
+	"doc +list":                                {"doc", "+list", "--folder", "folder-1", "--cursor", "cursor-1"},
+	"doc +move":                                {"doc", "+move", "--node", "node-1", "--folder", "folder-1", "--yes"},
+	"doc +search":                              {"doc", "+search", "--query", "fixture", "--limit", "7", "--cursor", "cursor-1"},
+	"doc +template-list":                       {"doc", "+template-list", "--source", "MY", "--limit", "7", "--cursor", "cursor-1"},
 	"doc +template-search":                     {"doc", "+template-search", "--query", "fixture", "--source", "MY", "--limit", "7"},
+	"doc +version-list":                        {"doc", "+version-list", "--node", "node-1", "--limit", "7", "--cursor", "cursor-1"},
+	"doc +version-revert":                      {"doc", "+version-revert", "--node", "node-1", "--version", "3", "--yes"},
+	"doc +version-save":                        {"doc", "+version-save", "--node", "node-1", "--yes"},
+	"doc +update":                              {"doc", "+update", "--node", "node-1", "--command", "overwrite", "--content", `["root",{}]`, "--doc-format", "jsonml", "--expected-revision", "1", "--yes"},
 	"doc block insert":                         {"doc", "block", "insert", "--node", "node-1", "--text", "fixture paragraph", "--yes"},
 	"doc block update":                         {"doc", "block", "update", "--node", "node-1", "--block-id", "block-1", "--text", "fixture paragraph", "--yes"},
+	"doc comment create":                       {"doc", "comment", "create", "--node", "node-1", "--content", "fixture comment", "--yes"},
+	"doc comment create-inline":                {"doc", "comment", "create-inline", "--node", "node-1", "--block-id", "block-1", "--start", "0", "--end", "7", "--content", "fixture comment", "--yes"},
+	"doc comment delete":                       {"doc", "comment", "delete", "--node", "node-1", "--comment-key", "comment-1", "--yes"},
+	"doc comment reply":                        {"doc", "comment", "reply", "--node", "node-1", "--comment-key", "comment-1", "--content", "fixture reply", "--mentioned-open-conversation-id", "cid-1,cid-2", "--yes"},
+	"doc comment update":                       {"doc", "comment", "update", "--node", "node-1", "--comment-key", "comment-1", "--content", "fixture update", "--yes"},
+	"doc version revert":                       {"doc", "version", "revert", "--node", "node-1", "--version", "3", "--yes"},
 	"drive info":                               {"drive", "info", "--node", "node-1", "--space-id", "space-1"},
 	"drive list":                               {"drive", "list", "--folder", "folder-1", "--limit", "7"},
 	"mail +find-mail-user":                     {"mail", "+find-mail-user", "--query", "fixture", "--limit", "7"},
@@ -99,6 +149,13 @@ var paramAliasCompleteCommands = map[string][]string{
 // that case the shared command template above cannot contain every canonical
 // flag at once, so select a fixture-specific complete invocation here.
 var paramAliasCompleteCommandVariants = map[string]map[string][]string{
+	"doc +copy": {
+		"folder":    {"doc", "+copy", "--node", "node-1", "--folder", "folder-1", "--yes"},
+		"workspace": {"doc", "+copy", "--node", "node-1", "--workspace", "workspace-1", "--yes"},
+	},
+	"doc block insert": {
+		"parent-block": {"doc", "block", "insert", "--node", "node-1", "--parent-block", "parent-block-1", "--index", "0", "--text", "fixture paragraph", "--yes"},
+	},
 	"chat message list": {
 		"user": {"chat", "message", "list", "--user", "user-1", "--time", "2026-03-10 00:00:00", "--limit", "7"},
 	},
@@ -109,6 +166,9 @@ var paramAliasCompleteCommandVariants = map[string]map[string][]string{
 		"group":     {"chat", "message", "send", "--group", "fixture-conversation", "--text", "hello fixture", "--uuid", "param-alias-equivalence-group", "--yes"},
 		"file-path": {"chat", "message", "send", "--group", "fixture-conversation", "--msg-type", "file", "--file-path", "../../go.mod", "--dentry-id", "1", "--space-id", "2", "--uuid", "param-alias-equivalence-file", "--yes"},
 	},
+	"chat +conversation-set-top": {
+		"conversation-ids": {"chat", "+conversation-set-top", "--conversation-ids", "fixture-conversation-1,fixture-conversation-2", "--yes"},
+	},
 }
 
 // paramAliasNewIMCases is the exact set of aliases added by the reviewed IM
@@ -119,6 +179,7 @@ var paramAliasNewIMCases = []struct {
 	emitted   string
 	canonical string
 }{
+	{command: "chat +chat-messages", emitted: "chat", canonical: "group"},
 	{command: "chat +bot-find", emitted: "name", canonical: "query"},
 	{command: "chat bot find", emitted: "name", canonical: "query"},
 	{command: "chat +bot-search", emitted: "query", canonical: "name"},
@@ -129,6 +190,7 @@ var paramAliasNewIMCases = []struct {
 	{command: "chat +messages-list-unread-conversations", emitted: "limit", canonical: "count"},
 	{command: "chat +messages-list-unread-conversations", emitted: "size", canonical: "count"},
 	{command: "chat +messages-send-by-webhook", emitted: "at-user-ids", canonical: "at-users"},
+	{command: "chat +search-msg", emitted: "chat", canonical: "group"},
 	{command: "chat +unread-chats", emitted: "limit", canonical: "count"},
 	{command: "chat +unread-chats", emitted: "size", canonical: "count"},
 	{command: "chat bot search", emitted: "query", canonical: "name"},
@@ -145,6 +207,38 @@ var paramAliasNewIMCases = []struct {
 	{command: "chat message send", emitted: "file", canonical: "file-path"},
 	{command: "chat message send-by-bot", emitted: "at-users", canonical: "at-user-ids"},
 	{command: "chat message send-by-webhook", emitted: "at-user-ids", canonical: "at-users"},
+	{command: "chat +chat-update", emitted: "chat-id", canonical: "group"},
+	{command: "chat +chat-update", emitted: "conversation-id", canonical: "group"},
+	{command: "chat +chat-update", emitted: "open-conversation-id", canonical: "group"},
+	{command: "chat +chat-update", emitted: "title", canonical: "name"},
+	{command: "chat +chat-update", emitted: "new-title", canonical: "name"},
+	{command: "chat +flag-list", emitted: "limit", canonical: "page-size"},
+	{command: "chat +chat-members-list", emitted: "chat-id", canonical: "conversation-id"},
+	{command: "chat +chat-members-list", emitted: "id", canonical: "conversation-id"},
+	{command: "chat +conversation-set-top", emitted: "open-conversation-id", canonical: "conversation-id"},
+	{command: "chat +conversation-set-top", emitted: "chat-ids", canonical: "conversation-ids"},
+	{command: "chat +chat-members-get", emitted: "conversation-id", canonical: "id"},
+	{command: "chat +chat-members-get", emitted: "open-dingtalk-ids", canonical: "users"},
+	{command: "chat +chat-members-get", emitted: "chat", canonical: "id"},
+	{command: "chat +messages-list", emitted: "start", canonical: "time"},
+	{command: "chat +messages-reply", emitted: "msg-id", canonical: "ref-msg-id"},
+	{command: "chat +messages-reply", emitted: "chat", canonical: "conversation-id"},
+	{command: "chat +flag-cancel", emitted: "group", canonical: "conversation-id"},
+	{command: "chat +flag-cancel", emitted: "chat", canonical: "conversation-id"},
+	{command: "chat +flag-create", emitted: "group", canonical: "conversation-id"},
+	{command: "chat +chat-add-bot", emitted: "conversation-id", canonical: "id"},
+	{command: "chat +chat-add-bot", emitted: "robot", canonical: "robot-code"},
+	{command: "chat +chat-audit-join", emitted: "applicant-user-id", canonical: "applicant"},
+	{command: "chat +chat-mute-member", emitted: "user-ids", canonical: "users"},
+	{command: "chat +chat-remove-bot", emitted: "open-bot-id", canonical: "bot-id"},
+	{command: "chat +chat-role-remove-user", emitted: "open-dingtalk-id", canonical: "user"},
+	{command: "chat +chat-transfer-owner", emitted: "user-id", canonical: "new-owner"},
+	{command: "chat +feed-group-query-item", emitted: "chat-ids", canonical: "conversation-ids"},
+	{command: "chat +messages-combine-forward", emitted: "src-open-cid", canonical: "src-conversation-id"},
+	{command: "chat +messages-forward", emitted: "source-message-id", canonical: "msg-id"},
+	{command: "chat +messages-forward-topic", emitted: "src-open-message-id", canonical: "src-msg-id"},
+	{command: "chat +messages-resource-download", emitted: "conversation-id", canonical: "open-conversation-id"},
+	{command: "chat +messages-set-pin", emitted: "conversation-id", canonical: "open-conversation-id"},
 }
 
 // paramAliasRepresentativePayloadCases keeps final transport coverage across
@@ -159,17 +253,36 @@ var paramAliasNewIMCases = []struct {
 // That duplicated command construction was enough to push the pre-existing
 // macOS app suite beyond its package-level 10-minute timeout.
 var paramAliasRepresentativePayloadCases = map[string]bool{
-	paramAliasPayloadCaseKey("aitable +record-query", "base"):         true, // concept alias on a shortcut read
-	paramAliasPayloadCaseKey("attendance check result", "user-ids"):   true, // list-valued concept alias
-	paramAliasPayloadCaseKey("calendar event list", "date"):           true, // time concept alias
-	paramAliasPayloadCaseKey("chat message add-favorite", "msg-id"):   true, // scoped IM identifier alias
-	paramAliasPayloadCaseKey("contact user profile get", "user-id"):   true, // native compatibility flag
-	paramAliasPayloadCaseKey("devdoc article search", "current-page"): true, // command override
-	paramAliasPayloadCaseKey("mail folder update", "folder-id"):       true, // write-command identifier alias
-	paramAliasPayloadCaseKey("report list", "from-date"):              true, // date-range concept alias
+	paramAliasPayloadCaseKey("aitable +record-query", "base"):                        true, // concept alias on a shortcut read
+	paramAliasPayloadCaseKey("attendance check result", "user-ids"):                  true, // list-valued concept alias
+	paramAliasPayloadCaseKey("calendar event list", "date"):                          true, // time concept alias
+	paramAliasPayloadCaseKey("chat message add-favorite", "msg-id"):                  true, // scoped IM identifier alias
+	paramAliasPayloadCaseKey("contact user profile get", "user-id"):                  true, // native compatibility flag
+	paramAliasPayloadCaseKey("devdoc article search", "current-page"):                true, // command override
+	paramAliasPayloadCaseKey("doc +comment-create", "body"):                          true, // write shortcut content alias
+	paramAliasPayloadCaseKey("doc +copy", "parent-folder-id"):                        true, // Doc folder role on a write shortcut
+	paramAliasPayloadCaseKey("doc +create", "content-format"):                        true, // shortcut format alias preserves markdown/jsonml enum
+	paramAliasPayloadCaseKey("doc +create-from-template", "keyword"):                 true, // template search alias composes with a write workflow
+	paramAliasPayloadCaseKey("doc +create-from-template", "workspace-id"):            true, // template target workspace identifier
+	paramAliasPayloadCaseKey("doc +create-from-template", "parent-folder-id"):        true, // template target folder identifier
+	paramAliasPayloadCaseKey("doc +export-submit", "doc-id"):                         true, // Doc node identifier alias
+	paramAliasPayloadCaseKey("doc +fetch", "start-block"):                            true, // section boundary role remains exact
+	paramAliasPayloadCaseKey("doc +history-revert", "version-number"):                true, // destructive history version alias keeps confirmation
+	paramAliasPayloadCaseKey("doc +inspect", "include-versions"):                     true, // boolean section alias preserves value
+	paramAliasPayloadCaseKey("doc +template-list", "next-token"):                     true, // Doc cursor alias on a read shortcut
+	paramAliasPayloadCaseKey("doc +update", "mode"):                                  true, // write operation selector alias
+	paramAliasPayloadCaseKey("doc +update", "revision"):                              true, // optimistic edit revision alias
+	paramAliasPayloadCaseKey("doc +access-grant", "doc-id"):                          true, // permission write keeps document identity
+	paramAliasPayloadCaseKey("doc +version-revert", "version-number"):                true, // high-write version role with canonical confirmation
+	paramAliasPayloadCaseKey("doc block insert", "content"):                          true, // block write content alias
+	paramAliasPayloadCaseKey("doc block insert", "parent-block-id"):                  true, // scoped block-role alias
+	paramAliasPayloadCaseKey("doc comment delete", "comment-id"):                     true, // destructive comment-key alias
+	paramAliasPayloadCaseKey("doc comment reply", "mentioned-open-conversation-ids"): true, // list-valued group mention role
+	paramAliasPayloadCaseKey("mail folder update", "folder-id"):                      true, // write-command identifier alias
+	paramAliasPayloadCaseKey("report list", "from-date"):                             true, // date-range concept alias
 }
 
-func TestReviewedParamAliasesHaveCompleteTemplatesAndRepresentativeFinalPayloads(t *testing.T) {
+func TestCrossPlatformCoverageReviewedParamAliasesHaveCompleteTemplatesAndRepresentativeFinalPayloads(t *testing.T) {
 	concepts, err := cli.LoadParamConcepts()
 	if err != nil {
 		t.Fatalf("LoadParamConcepts() error = %v", err)
@@ -220,6 +333,7 @@ func TestReviewedParamAliasesHaveCompleteTemplatesAndRepresentativeFinalPayloads
 			if ctx == nil {
 				t.Fatal("complete alias command skipped PreParse")
 			}
+			normalizeParamAliasVolatileDefaults(fixture.Command, canonicalCaller, aliasCaller)
 			if !reflect.DeepEqual(aliasCaller.calls, canonicalCaller.calls) {
 				t.Fatalf("final transport calls differ\ncanonical args: %v\nalias args: %v\ncanonical calls: %#v\nalias calls: %#v", canonicalArgs, aliasArgs, canonicalCaller.calls, aliasCaller.calls)
 			}
@@ -252,7 +366,7 @@ func TestReviewedParamAliasesHaveCompleteTemplatesAndRepresentativeFinalPayloads
 	}
 }
 
-func TestNewIMParamAliasesReachCanonicalEquivalentFinalPayloads(t *testing.T) {
+func TestCrossPlatformCoverageNewIMParamAliasesReachCanonicalEquivalentFinalPayloads(t *testing.T) {
 	activeAliases := 0
 	for _, test := range paramAliasNewIMCases {
 		test := test
@@ -268,8 +382,9 @@ func TestNewIMParamAliasesReachCanonicalEquivalentFinalPayloads(t *testing.T) {
 			}
 
 			canonicalCaller := &paramAliasCaptureCaller{}
-			if _, err := executeParamAliasPayloadE2E(t, canonicalCaller, canonicalArgs...); err != nil {
-				t.Fatalf("complete canonical command failed: %v\nargs=%v\ncalls=%#v", err, canonicalArgs, canonicalCaller.calls)
+			_, canonicalErr := executeParamAliasPayloadE2E(t, canonicalCaller, canonicalArgs...)
+			if canonicalErr != nil && !paramAliasExpectedCaptureBoundaryError(test.command, canonicalErr) {
+				t.Fatalf("complete canonical command failed: %v\nargs=%v\ncalls=%#v", canonicalErr, canonicalArgs, canonicalCaller.calls)
 			}
 			if len(canonicalCaller.calls) == 0 {
 				t.Fatalf("complete canonical command reached no final transport payload: args=%v", canonicalArgs)
@@ -285,13 +400,17 @@ func TestNewIMParamAliasesReachCanonicalEquivalentFinalPayloads(t *testing.T) {
 			}
 			activeAliases++
 			aliasCaller := &paramAliasCaptureCaller{}
-			ctx, err := executeParamAliasPayloadE2E(t, aliasCaller, aliasArgs...)
-			if err != nil {
-				t.Fatalf("complete alias command failed: %v\nargs=%v\ncalls=%#v", err, aliasArgs, aliasCaller.calls)
+			ctx, aliasErr := executeParamAliasPayloadE2E(t, aliasCaller, aliasArgs...)
+			if aliasErr != nil && !paramAliasExpectedCaptureBoundaryError(test.command, aliasErr) {
+				t.Fatalf("complete alias command failed: %v\nargs=%v\ncalls=%#v", aliasErr, aliasArgs, aliasCaller.calls)
 			}
 			if ctx == nil {
 				t.Fatal("complete alias command skipped PreParse")
 			}
+			if (canonicalErr == nil) != (aliasErr == nil) || (canonicalErr != nil && canonicalErr.Error() != aliasErr.Error()) {
+				t.Fatalf("canonical and alias completion errors differ: canonical=%v alias=%v", canonicalErr, aliasErr)
+			}
+			normalizeParamAliasVolatileDefaults(test.command, canonicalCaller, aliasCaller)
 			if !reflect.DeepEqual(aliasCaller.calls, canonicalCaller.calls) {
 				t.Fatalf("final transport calls differ\ncanonical args: %v\nalias args: %v\ncanonical calls: %#v\nalias calls: %#v", canonicalArgs, aliasArgs, canonicalCaller.calls, aliasCaller.calls)
 			}
@@ -302,6 +421,33 @@ func TestNewIMParamAliasesReachCanonicalEquivalentFinalPayloads(t *testing.T) {
 	}
 }
 
+// Resource download deliberately continues from the transport call into a
+// local HTTPS download. The generic capture caller returns an empty object, so
+// this command's stable post-transport validation error is the expected test
+// boundary; canonical and alias calls must still produce the same request and
+// the same error.
+func paramAliasExpectedCaptureBoundaryError(command string, err error) bool {
+	return command == "chat +messages-resource-download" && err != nil &&
+		strings.Contains(err.Error(), "资源下载接口未返回合法的 HTTPS 下载地址")
+}
+
+// +chat-messages supplies the current wall-clock time when callers omit
+// --time. Alias equivalence concerns the resolved target and transport shape;
+// a suite crossing a second boundary must not make that default appear
+// alias-dependent.
+func normalizeParamAliasVolatileDefaults(command string, callers ...*paramAliasCaptureCaller) {
+	if command != "chat +chat-messages" {
+		return
+	}
+	for _, caller := range callers {
+		for i := range caller.calls {
+			if caller.calls[i].tool == "list_conversation_message_v2" || caller.calls[i].tool == "list_individual_chat_message" {
+				delete(caller.calls[i].args, "time")
+			}
+		}
+	}
+}
+
 func paramAliasCompleteCommand(command, canonical string) ([]string, bool) {
 	complete, ok := paramAliasCompleteCommands[command]
 	if variants := paramAliasCompleteCommandVariants[command]; variants != nil {

internal/app/pat_auth_retry.go

@@ -569,9 +569,9 @@ func handlePatAuthCheck(
 	// In host-controlled PAT mode (driven solely by DINGTALK_DWS_AGENTCODE),
 	// or when flowId is absent, the CLI returns machine-readable JSON to
 	// stderr and leaves UI/polling/retry to the host. `claw-type` is NOT
-	// used for this decision — it is only forwarded on the wire via
-	// the edition default / DWS_AGENT_PRODUCT override and surfaced in
-	// hostControl for traceability.
+	// used for this decision — its edition-fixed value is forwarded on the
+	// wire and surfaced in hostControl for traceability. DWS_AGENT_PRODUCT
+	// does not affect this PAT contract.
 	if hostOwnedPAT || patData.Data.FlowID == "" {
 		if hostOwnedPAT {
 			return executor.Result{}, &apperrors.PATError{RawJSON: enrichPATErrorForHostControl(patErr.RawJSON)}

internal/app/pat_auth_retry_test.go

@@ -1007,11 +1007,11 @@ func TestHandlePatAuthCheck_HostControlledFlowIDPassthrough(t *testing.T) {
 	t.Setenv("DWS_CONFIG_DIR", tmpDir)
 	// Host-owned decision: driven ONLY by DINGTALK_DWS_AGENTCODE.
 	// DINGTALK_AGENT is set to demonstrate it does NOT leak into
-	// hostControl.clawType. With no DWS_AGENT_PRODUCT override the
-	// open-source edition default remains "openClaw".
+	// hostControl.clawType. DWS_AGENT_PRODUCT is also set to demonstrate
+	// that Product does not change the open-source fixed "openClaw" value.
 	t.Setenv(authpkg.AgentCodeEnv, "agt-sales")
 	t.Setenv("DINGTALK_AGENT", "sales-copilot")
-	t.Setenv(agentproduct.EnvName, "")
+	t.Setenv(agentproduct.EnvName, "qwenwork")
 
 	mock := &mockRunner{
 		runFunc: func(ctx context.Context, inv executor.Invocation) (executor.Result, error) {

internal/app/pat_hostcontrol_wire.go

@@ -29,9 +29,8 @@ import (
 //   - Host-owned is triggered iff DINGTALK_DWS_AGENTCODE is non-empty.
 //   - When triggered, `clawType` in the emitted hostControl block MUST be the
 //     exact value the CLI actually injects on the wire. Each edition supplies
-//     its existing default and an optional valid DWS_AGENT_PRODUCT overrides
-//     it. Invalid input falls back here for library compatibility; root command
-//     execution rejects it before network access.
+//     its fixed value; DWS_AGENT_PRODUCT is a separate observability and IM
+//     message-display signal and never affects this PAT value.
 //   - When DINGTALK_DWS_AGENTCODE is empty the provider returns "" so
 //     HostControlBlock yields nil and no hostControl block is emitted.
 func init() {
@@ -59,5 +58,5 @@ func effectiveClawType() string {
 			headers = h.MergeHeaders(headers)
 		}
 	}
-	return resolveEffectiveAgentProduct(headers)
+	return resolveEditionClawType(headers)
 }

internal/app/plugin_commands_test.go

@@ -30,6 +30,7 @@ import (
 	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/executor"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/pipeline"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/cmdutil"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/mcptypes"
 	"github.com/spf13/cobra"
@@ -417,10 +418,8 @@ func TestConflictingPluginDescriptorCannotReplaceDistributionEndpoint(t *testing
 
 func TestSchemaSourceRootDoesNotLoadRuntimePlugins(t *testing.T) {
 	isolatePluginRuntime(t)
-	previous := rootLoadPlugins
-	t.Cleanup(func() { rootLoadPlugins = previous })
 	var calls atomic.Int32
-	rootLoadPlugins = func(*cobra.Command, *pipeline.Engine, executor.Runner) []*cobra.Command {
+	testseam.Swap(t, &rootLoadPlugins, func(*cobra.Command, *pipeline.Engine, executor.Runner) []*cobra.Command {
 		calls.Add(1)
 		AppendDynamicServer(conferencePluginDescriptor())
 		return buildPluginCommands(
@@ -428,7 +427,7 @@ func TestSchemaSourceRootDoesNotLoadRuntimePlugins(t *testing.T) {
 			executor.EchoRunner{},
 			nil,
 		)
-	}
+	})
 
 	base := NewSchemaSourceRootCommand()
 	if calls.Load() != 0 {

internal/app/plugin_registration_residual_test.go

@@ -18,6 +18,7 @@ import (
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/pipeline"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/plugin"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut/userdef"
+	"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/cmdutil"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/mcptypes"
@@ -27,14 +28,11 @@ import (
 type schemaSourceContextKey struct{}
 
 func TestSchemaSourceRootPropagatesContextWithoutLoadingPlugins(t *testing.T) {
-	previous := rootLoadPlugins
-	t.Cleanup(func() { rootLoadPlugins = previous })
-
 	pluginLoads := 0
-	rootLoadPlugins = func(*cobra.Command, *pipeline.Engine, executor.Runner) []*cobra.Command {
+	testseam.Swap(t, &rootLoadPlugins, func(*cobra.Command, *pipeline.Engine, executor.Runner) []*cobra.Command {
 		pluginLoads++
 		return nil
-	}
+	})
 	wantContext := context.WithValue(context.Background(), schemaSourceContextKey{}, "schema")
 	root := NewSchemaSourceRootCommand(wantContext)
 	if root.Context() != wantContext {

internal/app/preparse_presentation_test.go

@@ -24,7 +24,7 @@ import (
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/pipeline"
 )
 
-func TestLeadingPersistentFlagVariantsReachTheRealCommand(t *testing.T) {
+func TestCrossPlatformCoverageLeadingPersistentFlagVariantsReachTheRealCommand(t *testing.T) {
 	tests := []struct {
 		name string
 		args []string
@@ -55,7 +55,7 @@ func TestLeadingPersistentFlagVariantsReachTheRealCommand(t *testing.T) {
 	}
 }
 
-func TestPreParseConflictHonorsErrorPresentationFlags(t *testing.T) {
+func TestCrossPlatformCoveragePreParseConflictHonorsErrorPresentationFlags(t *testing.T) {
 	root := NewSchemaSourceRootCommand()
 	args := []string{
 		"chat", "message", "send",
@@ -98,3 +98,65 @@ func TestPreParseConflictHonorsErrorPresentationFlags(t *testing.T) {
 		t.Fatalf("--debug details missing from early error:\n%s", rendered)
 	}
 }
+
+func TestCrossPlatformCoverageCommandResolutionPrecedesFlagErrorsOnProductionTree(t *testing.T) {
+	tests := []struct {
+		name        string
+		args        []string
+		wantReason  string
+		wantCommand string
+	}{
+		{
+			name:        "unknown shortcut",
+			args:        []string{"chat", "+chat-mesages", "--keyword", "x", "--format", "json"},
+			wantReason:  "unknown_shortcut",
+			wantCommand: "dws chat",
+		},
+		{
+			name:        "unknown dev app subcommand",
+			args:        []string{"dev", "app", "search", "--keyword", "x", "--format", "json"},
+			wantReason:  "unknown_subcommand",
+			wantCommand: "dws dev app",
+		},
+	}
+
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			root := NewSchemaSourceRootCommand()
+			ctx, err := pipeline.RunPreParseArgs(root, newPipelineEngine(), test.args)
+			if ctx == nil || ctx.Command != test.wantCommand {
+				t.Fatalf("Context = %#v, want command %q", ctx, test.wantCommand)
+			}
+			err = newPreParseValidationError(err)
+			var structured *apperrors.Error
+			if !stderrors.As(err, &structured) {
+				t.Fatalf("error = %T %v", err, err)
+			}
+			if structured.Reason != test.wantReason || structured.ExitCode() != 3 {
+				t.Fatalf("structured error = %#v", structured)
+			}
+			if len(structured.AvailableFlags) != 0 || strings.Contains(structured.Message, "unknown flag") {
+				t.Fatalf("command error leaked flag classification: %#v", structured)
+			}
+		})
+	}
+}
+
+func TestCrossPlatformCoverageResolvedShortcutStillUsesExactLeafFlagError(t *testing.T) {
+	root := NewSchemaSourceRootCommand()
+	root.SetOut(io.Discard)
+	root.SetErr(io.Discard)
+	args := []string{"chat", "+chat-messages", "--keyword", "x", "--format", "json"}
+	if ctx, err := pipeline.RunPreParseArgs(root, newPipelineEngine(), args); err != nil {
+		t.Fatalf("valid shortcut path failed PreParse: %#v, %v", ctx, err)
+	}
+	root.SetArgs(args)
+	err := root.Execute()
+	var structured *apperrors.Error
+	if !stderrors.As(err, &structured) {
+		t.Fatalf("error = %T %v", err, err)
+	}
+	if structured.Reason != "unknown_flag" || !strings.Contains(structured.Message, "dws chat +chat-messages --help") {
+		t.Fatalf("resolved shortcut flag error = %#v", structured)
+	}
+}

internal/app/recovery_command.go

@@ -1,510 +1,118 @@
+// 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"
 	"fmt"
-	"net/http"
-	"os"
-	"sort"
 	"strings"
-	"time"
 
-	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/cli"
 	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
-	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/output"
-	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/recovery"
-	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/transport"
 	"github.com/spf13/cobra"
 )
 
-var (
-	recoverySavePlan     = (*recovery.Store).SavePlan
-	recoverySaveAnalysis = (*recovery.Store).SaveAnalysis
-)
+const recoveryUnsupportedMessage = "dws recovery 不再支持：失败快照恢复计划/执行/闭环已下线，请改用 doctor / schema / 对应业务命令排查。"
 
-func newRecoveryCommand(_ context.Context, loader cli.CatalogLoader, flags *GlobalFlags) *cobra.Command {
-	var (
-		planUseLast    bool
-		planEventID    string
-		executeUseLast bool
-		executeEventID string
-		finalEventID   string
-		finalOutcome   string
-		executionFile  string
-	)
-
-	runtime := newRecoveryRuntime(loader, flags)
+type recoveryCompatNotice struct {
+	Status  string `json:"status"`
+	Command string `json:"command"`
+	Message string `json:"message"`
+}
 
+// newRecoveryCommand keeps a visible Deprecated compatibility surface for
+// historical argv and Interface Integrity. Behavior is unchanged: every leaf
+// returns an explicit unsupported notice. Skills must not teach this path.
+func newRecoveryCommand() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:               "recovery",
-		Short:             "错误恢复辅助命令",
-		Long:              "读取失败快照，生成恢复分析，并回写恢复结果。",
+		Short:             "不再支持：错误恢复辅助命令（兼容入口）",
+		Long:              "此命令组仅为历史 argv 兼容保留，不再读取失败快照或生成恢复计划。Skill / Agent 请勿引导此路径。",
+		Deprecated:        "不再支持；" + recoveryUnsupportedMessage,
 		Args:              cobra.NoArgs,
 		DisableAutoGenTag: true,
 		RunE: func(cmd *cobra.Command, args []string) error {
-			return cmd.Help()
+			return printRecoveryUnsupported(cmd, "dws recovery")
 		},
 	}
 
 	planCmd := &cobra.Command{
 		Use:               "plan",
-		Short:             "基于失败快照生成恢复计划",
+		Short:             "不再支持：基于失败快照生成恢复计划",
+		Deprecated:        "不再支持；" + recoveryUnsupportedMessage,
 		Args:              cobra.NoArgs,
 		DisableAutoGenTag: true,
 		RunE: func(cmd *cobra.Command, args []string) error {
-			store := recovery.NewStore(defaultConfigDir())
-			last, err := loadRecoverySnapshot(store, planUseLast, planEventID)
-			if err != nil {
-				return err
-			}
-
-			planner := recovery.NewPlanner(runtime)
-			plan := planner.PlanWithOptions(cmd.Context(), last.Context, recovery.PlanOptions{
-				EventID:         last.EventID,
-				EnableDocSearch: true,
-			})
-			recovery.HydratePlanForEvent(last.EventID, last.Context, last.Replay, &plan)
-			if err := recoverySavePlan(store, last.EventID, plan); err != nil {
-				return fmt.Errorf("保存恢复计划失败: %w", err)
-			}
-
-			payload := map[string]any{
-				"event_id": last.EventID,
-				"context":  last.Context,
-				"plan":     plan,
-			}
-			return output.WriteCommandPayload(cmd, payload, output.FormatJSON)
+			return printRecoveryUnsupported(cmd, "dws recovery plan")
 		},
 	}
-	planCmd.Flags().BoolVar(&planUseLast, "last", false, "读取最近一次失败快照")
-	planCmd.Flags().StringVar(&planEventID, "event-id", "", "按 event_id 读取失败快照")
+	planCmd.Flags().Bool("last", false, "旧版兼容参数；recovery 不再支持")
+	planCmd.Flags().String("event-id", "", "旧版兼容参数；recovery 不再支持")
 
 	executeCmd := &cobra.Command{
 		Use:               "execute",
-		Short:             "生成面向 Agent 的恢复分析包",
+		Short:             "不再支持：生成面向 Agent 的恢复分析包",
+		Deprecated:        "不再支持；" + recoveryUnsupportedMessage,
 		Args:              cobra.NoArgs,
 		DisableAutoGenTag: true,
 		RunE: func(cmd *cobra.Command, args []string) error {
-			store := recovery.NewStore(defaultConfigDir())
-			last, err := loadRecoverySnapshot(store, executeUseLast, executeEventID)
-			if err != nil {
-				return err
-			}
-
-			planner := recovery.NewPlanner(runtime)
-			executor := recovery.NewExecutor(planner, runtime)
-			bundle := executor.Execute(cmd.Context(), *last)
-			if err := recoverySaveAnalysis(store, last.EventID, bundle.Plan, bundle); err != nil {
-				return fmt.Errorf("保存恢复分析失败: %w", err)
-			}
-
-			return output.WriteCommandPayload(cmd, bundle, output.FormatJSON)
+			return printRecoveryUnsupported(cmd, "dws recovery execute")
 		},
 	}
-	executeCmd.Flags().BoolVar(&executeUseLast, "last", false, "读取最近一次失败快照")
-	executeCmd.Flags().StringVar(&executeEventID, "event-id", "", "按 event_id 读取失败快照")
+	executeCmd.Flags().Bool("last", false, "旧版兼容参数；recovery 不再支持")
+	executeCmd.Flags().String("event-id", "", "旧版兼容参数；recovery 不再支持")
 
 	finalizeCmd := &cobra.Command{
 		Use:               "finalize",
-		Short:             "回写恢复闭环结果",
+		Short:             "不再支持：回写恢复闭环结果",
+		Deprecated:        "不再支持；" + recoveryUnsupportedMessage,
 		Args:              cobra.NoArgs,
 		DisableAutoGenTag: true,
 		RunE: func(cmd *cobra.Command, args []string) error {
-			if strings.TrimSpace(finalEventID) == "" {
-				return fmt.Errorf("必须提供 --event-id")
-			}
-			if strings.TrimSpace(finalOutcome) == "" {
-				return fmt.Errorf("必须提供 --outcome")
-			}
-			switch finalOutcome {
-			case "recovered", "failed", "handoff":
-			default:
-				return fmt.Errorf("--outcome 仅支持 recovered|failed|handoff")
-			}
-
-			store := recovery.NewStore(defaultConfigDir())
-			var execution *recovery.RecoveryExecution
-			if strings.TrimSpace(executionFile) != "" {
-				loaded, err := loadRecoveryExecution(executionFile)
-				if err != nil {
-					return err
-				}
-				execution = &loaded
-			}
-			if err := store.Finalize(finalEventID, finalOutcome, execution); err != nil {
-				return fmt.Errorf("回写恢复结果失败: %w", err)
-			}
-
-			payload := map[string]any{
-				"event_id": finalEventID,
-				"outcome":  finalOutcome,
-				"success":  true,
-			}
-			if execution != nil {
-				payload["execution_recorded"] = true
-			}
-			return output.WriteCommandPayload(cmd, payload, output.FormatJSON)
+			return printRecoveryUnsupported(cmd, "dws recovery finalize")
 		},
 	}
-	finalizeCmd.Flags().StringVar(&finalEventID, "event-id", "", "恢复事件 ID")
-	finalizeCmd.Flags().StringVar(&finalOutcome, "outcome", "", "恢复结果: recovered|failed|handoff")
-	finalizeCmd.Flags().StringVar(&executionFile, "execution-file", "", "Agent 执行详情 JSON 文件")
+	finalizeCmd.Flags().String("event-id", "", "旧版兼容参数；recovery 不再支持")
+	finalizeCmd.Flags().String("outcome", "", "旧版兼容参数；recovery 不再支持")
+	finalizeCmd.Flags().String("execution-file", "", "旧版兼容参数；recovery 不再支持")
 
 	cmd.AddCommand(planCmd, executeCmd, finalizeCmd)
 	return cmd
 }
 
-func loadRecoverySnapshot(store *recovery.Store, useLast bool, eventID string) (*recovery.LastError, error) {
-	if useLast && strings.TrimSpace(eventID) != "" {
-		return nil, fmt.Errorf("--last 和 --event-id 不能同时使用")
+func printRecoveryUnsupported(cmd *cobra.Command, command string) error {
+	notice := recoveryCompatNotice{
+		Status:  "unsupported",
+		Command: command,
+		Message: recoveryUnsupportedMessage,
 	}
-	switch {
-	case useLast:
-		last, err := store.LoadLastError()
-		if err != nil {
-			return nil, fmt.Errorf("读取失败快照失败: %w", err)
+	format, _ := cmd.Root().PersistentFlags().GetString("format")
+	switch strings.ToLower(strings.TrimSpace(format)) {
+	case "", "json":
+		if err := json.NewEncoder(cmd.OutOrStdout()).Encode(notice); err != nil {
+			return err
 		}
-		return last, nil
-	case strings.TrimSpace(eventID) != "":
-		last, err := store.LoadErrorByEvent(strings.TrimSpace(eventID))
-		if err != nil {
-			return nil, fmt.Errorf("读取失败快照失败: %w", err)
+		return apperrors.NewValidation(recoveryUnsupportedMessage)
+	case "pretty":
+		data, _ := json.MarshalIndent(notice, "", "  ")
+		if _, err := fmt.Fprintln(cmd.OutOrStdout(), string(data)); err != nil {
+			return err
 		}
-		return last, nil
+		return apperrors.NewValidation(recoveryUnsupportedMessage)
 	default:
-		return nil, fmt.Errorf("必须通过 --last 或 --event-id 指定失败快照")
-	}
-}
-
-func loadRecoveryExecution(path string) (recovery.RecoveryExecution, error) {
-	var execution recovery.RecoveryExecution
-	data, err := os.ReadFile(path)
-	if err != nil {
-		return execution, fmt.Errorf("读取恢复执行详情失败: %w", err)
-	}
-	var payload recoveryExecutionPayload
-	if err := json.Unmarshal(data, &payload); err != nil {
-		return execution, fmt.Errorf("解析恢复执行详情失败: %w", err)
-	}
-	execution.Actions = append([]string(nil), payload.Actions...)
-	if len(execution.Actions) == 0 && strings.TrimSpace(payload.Action) != "" {
-		execution.Actions = []string{strings.TrimSpace(payload.Action)}
-	}
-	execution.Result = strings.TrimSpace(payload.Result)
-	execution.ErrorSummary = strings.TrimSpace(payload.ErrorSummary)
-	if execution.ErrorSummary == "" {
-		execution.ErrorSummary = strings.TrimSpace(payload.Error)
-	}
-
-	attempts, err := decodeRecoveryAttempts(payload.Attempts, execution.Actions, execution.Result, execution.ErrorSummary)
-	if err != nil {
-		return execution, fmt.Errorf("解析恢复执行详情失败: %w", err)
-	}
-	if len(attempts) == 0 && payload.Attempt > 0 {
-		attempts = legacyRecoveryAttempts(payload.Attempt, execution.Actions, execution.Result, execution.ErrorSummary)
-	}
-	execution.Attempts = attempts
-	return execution, nil
-}
-
-type recoveryExecutionPayload struct {
-	Action       string          `json:"action,omitempty"`
-	Actions      []string        `json:"actions,omitempty"`
-	Attempt      int             `json:"attempt,omitempty"`
-	Attempts     json.RawMessage `json:"attempts,omitempty"`
-	Result       string          `json:"result,omitempty"`
-	Error        string          `json:"error,omitempty"`
-	ErrorSummary string          `json:"error_summary,omitempty"`
-}
-
-func decodeRecoveryAttempts(raw json.RawMessage, actions []string, result, errorSummary string) ([]recovery.RecoveryAttempt, error) {
-	trimmed := strings.TrimSpace(string(raw))
-	if trimmed == "" || trimmed == "null" {
-		return nil, nil
-	}
-	if strings.HasPrefix(trimmed, "[") {
-		var attempts []recovery.RecoveryAttempt
-		if err := json.Unmarshal(raw, &attempts); err != nil {
-			return nil, err
+		if _, err := fmt.Fprintf(cmd.OutOrStdout(), "%s: %s\n", notice.Command, notice.Message); err != nil {
+			return err
 		}
-		return attempts, nil
-	}
-
-	var count int
-	if err := json.Unmarshal(raw, &count); err != nil {
-		return nil, err
-	}
-	return legacyRecoveryAttempts(count, actions, result, errorSummary), nil
-}
-
-func legacyRecoveryAttempts(count int, actions []string, result, errorSummary string) []recovery.RecoveryAttempt {
-	if count <= 0 {
-		return nil
-	}
-	summary := strings.TrimSpace(strings.Join(actions, ", "))
-	if summary == "" {
-		summary = "legacy execution attempt"
-	}
-	attempts := make([]recovery.RecoveryAttempt, 0, count)
-	for i := 0; i < count; i++ {
-		attempts = append(attempts, recovery.RecoveryAttempt{
-			CommandSummary: summary,
-			Result:         result,
-			ErrorSummary:   errorSummary,
-			Source:         "legacy_execution_file",
-		})
-	}
-	return attempts
-}
-
-type recoveryRuntime struct {
-	loader    cli.CatalogLoader
-	transport *transport.Client
-	flags     *GlobalFlags
-}
-
-func newRecoveryRuntime(loader cli.CatalogLoader, flags *GlobalFlags) *recoveryRuntime {
-	var httpClient *http.Client
-	if flags != nil && flags.Timeout > 0 {
-		httpClient = &http.Client{Timeout: time.Duration(flags.Timeout) * time.Second}
-	}
-	client := transport.NewClient(httpClient)
-	client.ExtraHeaders = resolveIdentityHeaders()
-	return &recoveryRuntime{
-		loader:    loader,
-		transport: client,
-		flags:     flags,
+		return apperrors.NewValidation(recoveryUnsupportedMessage)
 	}
 }
-
-func (r *recoveryRuntime) Search(ctx context.Context, query string, rc recovery.RecoveryContext) (recovery.KnowledgeRetrieval, error) {
-	const (
-		searchPage = 1
-		searchSize = 5
-	)
-	requestArgs := map[string]any{
-		"keyword": query,
-		"page":    searchPage,
-		"size":    searchSize,
-	}
-
-	retrieval := recovery.KnowledgeRetrieval{
-		DocSearch: recovery.DocSearch{
-			Provider: "open_platform_docs",
-			Query:    query,
-			Page:     searchPage,
-			Size:     searchSize,
-			Status:   "empty",
-			Request: &recovery.ToolCallRecord{
-				ServerID:  "devdoc",
-				ToolName:  "search_open_platform_docs_rag",
-				Arguments: cloneRecoveryArgs(requestArgs),
-			},
-		},
-	}
-	if r == nil || strings.TrimSpace(query) == "" {
-		retrieval.DocSearch.Status = "skipped"
-		return retrieval, nil
-	}
-	result, err := r.CallToolDirect(ctx, "devdoc", "search_open_platform_docs_rag", requestArgs)
-	if result != nil {
-		retrieval.DocSearch.Response = toRecoveryToolResponse(result)
-	}
-	if err != nil {
-		retrieval.DocSearch.Status = "error"
-		retrieval.DocSearch.Error = err.Error()
-		return retrieval, err
-	}
-
-	retrieval.DocSearch.Items = parseDocSearchItems(result)
-	if len(retrieval.DocSearch.Items) > 0 {
-		retrieval.DocSearch.Status = "success"
-		retrieval.KBHits = rerankDocSearchHits(query, rc, retrieval.DocSearch.Items)
-	}
-	return retrieval, nil
-}
-
-func (r *recoveryRuntime) CallToolDirect(ctx context.Context, serverID, toolName string, args map[string]any) (*transport.ToolCallResult, error) {
-	if r == nil || r.transport == nil {
-		return nil, fmt.Errorf("recovery runtime not initialized")
-	}
-	endpoint, err := r.resolveEndpoint(ctx, serverID, toolName)
-	if err != nil {
-		return nil, err
-	}
-	authToken, err := resolveRuntimeAuthToken(ctx, recoveryRuntimeToken(r.flags))
-	if err != nil {
-		return nil, tokenResolutionError(err)
-	}
-	tc := r.transport.WithAuth(authToken, resolveIdentityHeaders())
-	result, err := tc.CallTool(ctx, endpoint, toolName, args)
-	if err != nil {
-		return nil, err
-	}
-	if result.IsError {
-		return &result, apperrors.NewAPI(
-			extractMCPErrorMessage(result),
-			apperrors.WithOperation("tools/call"),
-			apperrors.WithReason("mcp_tool_error"),
-			apperrors.WithServerKey(serverID),
-		)
-	}
-	return &result, nil
-}
-
-func (r *recoveryRuntime) resolveEndpoint(ctx context.Context, productID, toolName string) (string, error) {
-	if endpoint, ok := directRuntimeEndpoint(productID, toolName); ok {
-		return endpoint, nil
-	}
-	if r == nil || r.loader == nil {
-		return "", fmt.Errorf("未找到服务 %s 的 endpoint", productID)
-	}
-	catalog, err := r.loader.Load(ctx)
-	if err != nil {
-		return "", err
-	}
-	product, ok := catalog.FindProduct(productID)
-	if !ok || strings.TrimSpace(product.Endpoint) == "" {
-		return "", fmt.Errorf("未找到服务 %s 的 endpoint", productID)
-	}
-	return strings.TrimSpace(product.Endpoint), nil
-}
-
-func recoveryRuntimeToken(flags *GlobalFlags) string {
-	if flags == nil {
-		return ""
-	}
-	return strings.TrimSpace(flags.Token)
-}
-
-func toRecoveryToolResponse(result *transport.ToolCallResult) *recovery.ToolResponse {
-	if result == nil {
-		return nil
-	}
-	response := &recovery.ToolResponse{IsError: result.IsError}
-	if len(result.Blocks) > 0 {
-		response.Content = make([]recovery.ToolResponseBlock, 0, len(result.Blocks))
-		for _, block := range result.Blocks {
-			response.Content = append(response.Content, recovery.ToolResponseBlock{
-				Type: block.Type,
-				Text: block.Text,
-			})
-		}
-	}
-	return response
-}
-
-func parseDocSearchItems(result *transport.ToolCallResult) []recovery.DocSearchItem {
-	if result == nil {
-		return nil
-	}
-	if items := parseDocSearchItemsFromMap(result.Content); len(items) > 0 {
-		return items
-	}
-	for _, block := range result.Blocks {
-		var payload map[string]any
-		if err := json.Unmarshal([]byte(block.Text), &payload); err == nil {
-			if items := parseDocSearchItemsFromMap(payload); len(items) > 0 {
-				return items
-			}
-		}
-	}
-	return nil
-}
-
-func parseDocSearchItemsFromMap(payload map[string]any) []recovery.DocSearchItem {
-	if len(payload) == 0 {
-		return nil
-	}
-	if items := toDocSearchItems(payload["items"]); len(items) > 0 {
-		return items
-	}
-	if data, ok := payload["data"].(map[string]any); ok {
-		if items := toDocSearchItems(data["items"]); len(items) > 0 {
-			return items
-		}
-	}
-	if result, ok := payload["result"].(map[string]any); ok {
-		if items := toDocSearchItems(result["items"]); len(items) > 0 {
-			return items
-		}
-	}
-	return nil
-}
-
-func toDocSearchItems(raw any) []recovery.DocSearchItem {
-	list, ok := raw.([]any)
-	if !ok {
-		return nil
-	}
-	items := make([]recovery.DocSearchItem, 0, len(list))
-	for _, entry := range list {
-		object, ok := entry.(map[string]any)
-		if !ok {
-			continue
-		}
-		item := recovery.DocSearchItem{}
-		if title, ok := object["title"].(string); ok {
-			item.Title = title
-		}
-		if url, ok := object["url"].(string); ok {
-			item.URL = url
-		}
-		if desc, ok := object["desc"].(string); ok {
-			item.Desc = desc
-		}
-		if item.Title != "" || item.URL != "" || item.Desc != "" {
-			items = append(items, item)
-		}
-	}
-	return items
-}
-
-func rerankDocSearchHits(query string, rc recovery.RecoveryContext, items []recovery.DocSearchItem) []recovery.KBHit {
-	if len(items) == 0 {
-		return nil
-	}
-	keywords := strings.Fields(strings.ToLower(strings.TrimSpace(query)))
-	type scoredHit struct {
-		hit   recovery.KBHit
-		score float64
-	}
-	scored := make([]scoredHit, 0, len(items))
-	for _, item := range items {
-		text := strings.ToLower(strings.Join(append([]string{
-			item.Title,
-			item.URL,
-			item.Desc,
-			rc.ToolName,
-		}, rc.CommandPath...), " "))
-		score := 0.0
-		for _, keyword := range keywords {
-			if strings.Contains(text, keyword) {
-				score += 1
-			}
-		}
-		scored = append(scored, scoredHit{
-			hit: recovery.KBHit{
-				Source:  "open_platform_docs",
-				Title:   item.Title,
-				URL:     item.URL,
-				Snippet: item.Desc,
-				Score:   score,
-			},
-			score: score,
-		})
-	}
-	sort.SliceStable(scored, func(i, j int) bool {
-		return scored[i].score > scored[j].score
-	})
-	limit := len(scored)
-	if limit > 3 {
-		limit = 3
-	}
-	hits := make([]recovery.KBHit, 0, limit)
-	for _, item := range scored[:limit] {
-		hits = append(hits, item.hit)
-	}
-	return hits
-}

internal/app/recovery_command_compat_test.go

@@ -0,0 +1,110 @@
+// 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"
+	"errors"
+	"strings"
+	"testing"
+
+	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/executor"
+	"github.com/spf13/cobra"
+)
+
+func TestCrossPlatformCoverageRecoveryDeprecatedUnsupportedShim(t *testing.T) {
+	root := NewRootCommand()
+	group := mustFindCommand(t, root, "recovery")
+	if group.Hidden || group.Deprecated == "" || !group.Runnable() {
+		t.Fatalf("recovery group contract: hidden=%v deprecated=%q runnable=%v", group.Hidden, group.Deprecated, group.Runnable())
+	}
+
+	for _, leaf := range []string{"plan", "execute", "finalize"} {
+		cmd := mustFindCommand(t, root, "recovery", leaf)
+		if cmd.Hidden || cmd.Deprecated == "" || !cmd.Runnable() {
+			t.Fatalf("recovery %s contract: hidden=%v deprecated=%q runnable=%v", leaf, cmd.Hidden, cmd.Deprecated, cmd.Runnable())
+		}
+		wantFlags := []string{"event-id"}
+		switch leaf {
+		case "plan", "execute":
+			wantFlags = append(wantFlags, "last")
+		case "finalize":
+			wantFlags = append(wantFlags, "outcome", "execution-file")
+		}
+		for _, flag := range wantFlags {
+			if cmd.Flags().Lookup(flag) == nil {
+				t.Fatalf("recovery %s missing --%s", leaf, flag)
+			}
+		}
+		for _, child := range newRecoveryCommand().Commands() {
+			if child.Name() != leaf {
+				continue
+			}
+			if err := child.RunE(child, nil); err == nil || !strings.Contains(err.Error(), "不再支持") {
+				t.Fatalf("recovery %s RunE = %v, want 不再支持", leaf, err)
+			}
+		}
+	}
+
+	for _, format := range []string{"", "json", "pretty", "table"} {
+		var out bytes.Buffer
+		cmd := &cobra.Command{Use: "dws"}
+		cmd.PersistentFlags().String("format", format, "")
+		cmd.SetOut(&out)
+		sub := &cobra.Command{Use: "recovery"}
+		cmd.AddCommand(sub)
+		err := printRecoveryUnsupported(sub, "dws recovery plan")
+		if err == nil {
+			t.Fatalf("format=%q returned nil error", format)
+		}
+		typed, ok := err.(*apperrors.Error)
+		if !ok || typed.Category != apperrors.CategoryValidation {
+			t.Fatalf("format=%q error = %T/%v, want validation Error", format, err, err)
+		}
+		got := out.String() + err.Error()
+		if !strings.Contains(got, "不再支持") {
+			t.Fatalf("format=%q missing 不再支持:\n%s", format, got)
+		}
+		if format == "" || format == "json" || format == "pretty" {
+			if !strings.Contains(got, `"status":"unsupported"`) && !strings.Contains(got, `"status": "unsupported"`) {
+				t.Fatalf("format=%q missing unsupported JSON status:\n%s", format, got)
+			}
+		}
+	}
+
+	for _, format := range []string{"json", "pretty", "table"} {
+		cmd := &cobra.Command{Use: "dws"}
+		cmd.PersistentFlags().String("format", format, "")
+		cmd.SetOut(failWriter{})
+		sub := &cobra.Command{Use: "recovery"}
+		cmd.AddCommand(sub)
+		if err := printRecoveryUnsupported(sub, "dws recovery plan"); err == nil || !strings.Contains(err.Error(), "write failed") {
+			t.Fatalf("format=%q write failure = %v, want write failed", format, err)
+		}
+	}
+
+	if err := newRecoveryCommand().RunE(newRecoveryCommand(), nil); err == nil || !strings.Contains(err.Error(), "不再支持") {
+		t.Fatalf("recovery parent RunE = %v, want 不再支持", err)
+	}
+	captureRuntimeFailure(executor.Invocation{}, nil, nil)
+}
+
+type failWriter struct{}
+
+func (failWriter) Write([]byte) (int, error) {
+	return 0, errWriteFailed
+}
+
+var errWriteFailed = errors.New("write failed")

internal/app/recovery_command_full_coverage_test.go

@@ -1,153 +0,0 @@
-package app
-
-import (
-	"context"
-	"errors"
-	"io"
-	"os"
-	"path/filepath"
-	"strings"
-	"testing"
-
-	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/cli"
-	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/recovery"
-	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/transport"
-)
-
-func recoveryCoverageRun(cmdArgs ...string) (string, error) {
-	cmd := newRecoveryCommand(context.Background(), cli.StaticLoader{}, &GlobalFlags{})
-	out := &strings.Builder{}
-	cmd.SetOut(out)
-	cmd.SetErr(io.Discard)
-	cmd.SetArgs(cmdArgs)
-	err := cmd.Execute()
-	return out.String(), err
-}
-
-func TestCrossPlatformCoverageRecoveryCommandRemainingCoverage(t *testing.T) {
-	oldSavePlan, oldSaveAnalysis := recoverySavePlan, recoverySaveAnalysis
-	t.Cleanup(func() {
-		recoverySavePlan, recoverySaveAnalysis = oldSavePlan, oldSaveAnalysis
-	})
-	configDir := t.TempDir()
-	t.Setenv("DWS_CONFIG_DIR", configDir)
-	store := recovery.NewStore(configDir)
-	last, err := store.Capture(recovery.RecoveryContext{ServerID: "doc", ToolName: "get"})
-	if err != nil {
-		t.Fatal(err)
-	}
-	recoverySavePlan = func(*recovery.Store, string, recovery.RecoveryPlan) error { return errors.New("save plan") }
-	if _, err := recoveryCoverageRun("plan", "--last"); err == nil {
-		t.Fatal("injected plan save failure succeeded")
-	}
-	recoverySavePlan = oldSavePlan
-	recoverySaveAnalysis = func(*recovery.Store, string, recovery.RecoveryPlan, recovery.RecoveryBundle) error {
-		return errors.New("save analysis")
-	}
-	if _, err := recoveryCoverageRun("execute", "--last"); err == nil {
-		t.Fatal("injected analysis save failure succeeded")
-	}
-	recoverySaveAnalysis = oldSaveAnalysis
-
-	parent := newRecoveryCommand(context.Background(), nil, nil)
-	parent.SetOut(io.Discard)
-	if err := parent.RunE(parent, nil); err != nil {
-		t.Fatal(err)
-	}
-	if out, err := recoveryCoverageRun("plan", "--last"); err != nil || !strings.Contains(out, last.EventID) {
-		t.Fatalf("recovery plan = %q, %v", out, err)
-	}
-	if out, err := recoveryCoverageRun("execute", "--event-id", last.EventID); err != nil || out == "" {
-		t.Fatalf("recovery execute = %q, %v", out, err)
-	}
-
-	for _, args := range [][]string{
-		{"finalize"},
-		{"finalize", "--event-id", last.EventID},
-		{"finalize", "--event-id", last.EventID, "--outcome", "unknown"},
-		{"finalize", "--event-id", last.EventID, "--outcome", "recovered", "--execution-file", "missing"},
-	} {
-		if _, err := recoveryCoverageRun(args...); err == nil {
-			t.Fatalf("recovery finalize %#v should fail", args)
-		}
-	}
-	executionPath := filepath.Join(t.TempDir(), "execution.json")
-	if err := os.WriteFile(executionPath, []byte(`{"action":"retry","attempt":1,"result":"ok"}`), 0o600); err != nil {
-		t.Fatal(err)
-	}
-	if out, err := recoveryCoverageRun("finalize", "--event-id", last.EventID, "--outcome", "handoff", "--execution-file", executionPath); err != nil || !strings.Contains(out, "execution_recorded") {
-		t.Fatalf("recovery finalize = %q, %v", out, err)
-	}
-	if _, err := recoveryCoverageRun("finalize", "--event-id", last.EventID, "--outcome", "failed"); err != nil {
-		t.Fatal(err)
-	}
-
-	if _, err := loadRecoverySnapshot(store, true, last.EventID); err == nil {
-		t.Fatal("conflicting snapshot selectors should fail")
-	}
-	if _, err := loadRecoverySnapshot(store, false, "missing"); err == nil {
-		t.Fatal("missing event snapshot should fail")
-	}
-	if _, err := loadRecoverySnapshot(store, false, ""); err == nil {
-		t.Fatal("empty snapshot selector should fail")
-	}
-	missingStore := recovery.NewStore(t.TempDir())
-	if _, err := loadRecoverySnapshot(missingStore, true, ""); err == nil {
-		t.Fatal("missing latest snapshot should fail")
-	}
-
-	eventsPath := filepath.Join(configDir, "recovery", "recovery_events.jsonl")
-	if err := os.Remove(eventsPath); err != nil {
-		t.Fatal(err)
-	}
-	if err := os.Mkdir(eventsPath, 0o700); err != nil {
-		t.Fatal(err)
-	}
-	if _, err := recoveryCoverageRun("plan", "--last"); err == nil {
-		t.Fatal("recovery plan save should fail")
-	}
-	if _, err := recoveryCoverageRun("execute", "--last"); err == nil {
-		t.Fatal("recovery analysis save should fail")
-	}
-	if _, err := recoveryCoverageRun("finalize", "--event-id", last.EventID, "--outcome", "recovered"); err == nil {
-		t.Fatal("recovery finalization save should fail")
-	}
-}
-
-func TestCrossPlatformCoverageRecoveryExecutionAndRuntimeRemainingCoverage(t *testing.T) {
-	t.Setenv("DINGTALK_DEVDOC_MCP_URL", "http://127.0.0.1:1")
-	path := filepath.Join(t.TempDir(), "execution.json")
-	if err := os.WriteFile(path, []byte(`{"attempts":{}}`), 0o600); err != nil {
-		t.Fatal(err)
-	}
-	if _, err := loadRecoveryExecution(path); err == nil {
-		t.Fatal("invalid attempts should fail")
-	}
-	if _, err := decodeRecoveryAttempts([]byte(`[{}`), nil, "", ""); err == nil {
-		t.Fatal("invalid attempt array should fail")
-	}
-
-	fail := errors.New("catalog")
-	SetDynamicServers(nil)
-	runtime := &recoveryRuntime{
-		loader:    cli.CatalogLoaderFrom(cli.Catalog{}, fail),
-		transport: transport.NewClient(nil),
-	}
-	if _, err := runtime.CallToolDirect(context.Background(), "missing", "tool", nil); !errors.Is(err, fail) {
-		t.Fatalf("direct resolution error = %v", err)
-	}
-	if got, err := runtime.Search(context.Background(), "query", recovery.RecoveryContext{}); err == nil || got.DocSearch.Status != "error" {
-		t.Fatalf("search error = %#v, %v", got, err)
-	}
-	if got := parseDocSearchItems(&transport.ToolCallResult{Content: map[string]any{}, Blocks: []transport.ContentBlock{{Text: "not-json"}}}); got != nil {
-		t.Fatalf("empty doc search items = %#v", got)
-	}
-	for _, payload := range []map[string]any{
-		{"data": map[string]any{}},
-		{"result": map[string]any{}},
-	} {
-		if got := parseDocSearchItemsFromMap(payload); got != nil {
-			t.Fatalf("empty nested doc search items = %#v", got)
-		}
-	}
-}

internal/app/recovery_runtime.go

@@ -1,94 +1,10 @@
 package app
 
 import (
-	"os"
-	"strings"
-
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/executor"
-	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/recovery"
 )
 
-func captureRuntimeFailure(invocation executor.Invocation, rawErr, wrappedErr error) {
-	if rawErr == nil && wrappedErr == nil {
-		return
-	}
-	store := recovery.NewStore(defaultConfigDir())
-	if store == nil || !store.Enabled() {
-		return
-	}
-	input := recovery.CaptureInput{
-		CommandPath: runtimeCommandPath(invocation),
-		ServerID:    strings.TrimSpace(invocation.CanonicalProduct),
-		ToolName:    strings.TrimSpace(invocation.Tool),
-		Args:        cloneRecoveryArgs(invocation.Params),
-		Argv:        append([]string(nil), os.Args[1:]...),
-		RawErr:      rawErr,
-		WrappedErr:  wrappedErr,
-	}
-	_, _ = store.Capture(recovery.BuildContext(input), recovery.BuildReplay(input))
-}
-
-func runtimeCommandPath(invocation executor.Invocation) []string {
-	if path := currentCommandPath(); len(path) > 0 {
-		return path
-	}
-	if legacy := strings.Fields(strings.TrimSpace(invocation.LegacyPath)); len(legacy) > 0 {
-		return legacy
-	}
-	if product := strings.TrimSpace(invocation.CanonicalProduct); product != "" {
-		if tool := strings.TrimSpace(invocation.Tool); tool != "" {
-			return []string{product, tool}
-		}
-		return []string{product}
-	}
-	return nil
-}
-
-func currentCommandPath() []string {
-	boolFlags := map[string]struct{}{
-		"--verbose": {},
-		"-v":        {},
-		"--debug":   {},
-		"--mock":    {},
-		"--dry-run": {},
-		"--yes":     {},
-		"-y":        {},
-		"--help":    {},
-		"-h":        {},
-		"--json":    {},
-	}
-	path := make([]string, 0, len(os.Args))
-	skipNext := false
-	for _, arg := range os.Args[1:] {
-		if skipNext {
-			skipNext = false
-			continue
-		}
-		if arg == "--" {
-			break
-		}
-		if strings.HasPrefix(arg, "-") {
-			if strings.Contains(arg, "=") {
-				continue
-			}
-			if _, ok := boolFlags[arg]; ok {
-				continue
-			}
-			skipNext = true
-			continue
-		}
-		path = append(path, arg)
-	}
-	return path
-}
-
-func cloneRecoveryArgs(args map[string]any) map[string]any {
-	if len(args) == 0 {
-		return nil
-	}
-	out := make(map[string]any, len(args))
-	for key, value := range args {
-		out[key] = value
-	}
-	return out
-}
+// captureRuntimeFailure previously persisted a recovery snapshot for
+// `dws recovery`. The recovery package is gone; keep a no-op seam so runner
+// failure paths stay stable while the visible Deprecated shim remains.
+func captureRuntimeFailure(_ executor.Invocation, _, _ error) {}

internal/app/root.go

@@ -39,7 +39,6 @@ import (
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/pipeline"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/pipeline/handlers"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/plugin"
-	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/recovery"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut/usage"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/agentproduct"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/cmdutil"
@@ -51,15 +50,11 @@ import (
 
 type outputFileContextKey struct{}
 
-const recoveryEventStderrPrefix = "RECOVERY_EVENT_ID="
-
 var (
 	rootNormalizeProcessProfileArgs = normalizeProcessProfileArgs
 	rootExecuteCommand              = (*cobra.Command).ExecuteC
 	rootNewRootCommandWithEngine    = NewRootCommandWithEngine
 	rootRunPreParse                 = pipeline.RunPreParse
-	rootLatestRecoveryCapture       = recovery.LatestCapture
-	rootResetRecoveryState          = recovery.ResetRuntimeState
 	rootStopAllStdioClients         = StopAllStdioClients
 	rootLoadPlugins                 = loadPlugins
 	rootMkdirAll                    = os.MkdirAll
@@ -107,7 +102,6 @@ func Execute() (exitCode int) {
 	ctx = WithTimingCollector(ctx, timing)
 
 	initStart := time.Now()
-	rootResetRecoveryState()
 	engine := newPipelineEngine()
 	root := rootNewRootCommandWithEngine(ctx, engine)
 	timing.Record("cmd_init", time.Since(initStart))
@@ -133,9 +127,6 @@ func Execute() (exitCode int) {
 			_, _ = fmt.Fprintln(os.Stderr)
 		}
 		_ = printExecutionError(executed, os.Stdout, os.Stderr, err)
-		if last := rootLatestRecoveryCapture(); last != nil && last.EventID != "" {
-			_, _ = fmt.Fprintf(os.Stderr, "%s%s\n", recoveryEventStderrPrefix, last.EventID)
-		}
 		return apperrors.ExitCode(err)
 	}
 	return 0
@@ -144,6 +135,9 @@ func Execute() (exitCode int) {
 // newPreParseValidationError keeps pipeline handler identity in internal logs
 // while exposing only the underlying parameter-domain error to CLI users.
 func newPreParseValidationError(err error) error {
+	if structured, ok := err.(*apperrors.Error); ok {
+		return structured
+	}
 	userErr := err
 	var handlerErr *pipeline.HandlerError
 	if stderrors.As(err, &handlerErr) && handlerErr.Unwrap() != nil {
@@ -369,41 +363,43 @@ func commandRequestsJSONErrors(cmd *cobra.Command) bool {
 // is propagated to background goroutines and the Cobra command tree so
 // that SIGINT/SIGTERM can cancel in-flight work.
 func NewRootCommand(ctx ...context.Context) *cobra.Command {
+	registerSchemaRuntimeDelivery()
 	var rootCtx context.Context
 	if len(ctx) > 0 && ctx[0] != nil {
 		rootCtx = ctx[0]
 	}
-	return newRootCommandWithEngine(rootCtx, nil, true)
+	return newRootCommandWithEngine(rootCtx, nil, true, false)
 }
 
 // NewSchemaSourceRootCommand constructs the distribution-owned command tree
-// used by Schema generation and command-surface policy. Installed plugins and
-// user-defined shortcuts must not change the reviewed embedded Schema.
+// used as the Schema assembly source root (RegisterSchemaSourceRoot →
+// ResolveSchemaBuild) and by command-surface policy. Installed plugins and
+// user-defined shortcuts must not change the reviewed Schema surface.
+// declarationOnly skips injectStaticServers / helpers.InitDeps so Schema
+// assembly cannot clobber a live process's ToolCaller or plugin endpoints.
 func NewSchemaSourceRootCommand(ctx ...context.Context) *cobra.Command {
 	var rootCtx context.Context
 	if len(ctx) > 0 && ctx[0] != nil {
 		rootCtx = ctx[0]
 	}
-	return newRootCommandWithEngine(rootCtx, nil, false)
+	return newRootCommandWithEngine(rootCtx, nil, false, true)
 }
 
 // NewRootCommandWithEngine constructs the root CLI command with an
 // optional pipeline engine for input correction. When engine is nil,
 // no pipeline processing is applied.
 func NewRootCommandWithEngine(rootCtx context.Context, engine *pipeline.Engine) *cobra.Command {
-	return newRootCommandWithEngine(rootCtx, engine, true)
+	registerSchemaRuntimeDelivery()
+	return newRootCommandWithEngine(rootCtx, engine, true, false)
 }
 
-func newRootCommandWithEngine(rootCtx context.Context, engine *pipeline.Engine, loadRuntimeExtensions bool) *cobra.Command {
+func newRootCommandWithEngine(rootCtx context.Context, engine *pipeline.Engine, loadRuntimeExtensions bool, declarationOnly bool) *cobra.Command {
 	if rootCtx == nil {
 		rootCtx = context.Background()
 	}
 	flags := &GlobalFlags{}
 	authpkg.SetRuntimeProfile(preparseProfileFlag(os.Args[1:]))
-	loader := cli.EnvironmentLoader{
-		LookupEnv: os.LookupEnv,
-	}
-	runner := rootNewCommandRunnerWithFlags(loader, flags)
+	runner := rootNewCommandRunnerWithFlags(flags)
 
 	root := &cobra.Command{
 		Use:               "dws",
@@ -458,13 +454,8 @@ func newRootCommandWithEngine(rootCtx context.Context, engine *pipeline.Engine,
 
 	bindPersistentFlags(root, flags)
 
-	schemaCmd := newSchemaCommand(loader)
-	mcpCmd := newMCPCommand(rootCtx, loader, runner, engine)
-	// The legacy dynamic MCP surface remains disabled, but reviewed static MCP
-	// helpers registered below are part of the public CLI and Schema surface.
-	mcpCmd.Hidden = false
-	mcpCmd.Short = "管理 MCP 服务连接信息"
-	mcpCmd.Long = "管理经过审核并纳入 Schema 的 MCP 服务连接辅助能力。"
+	schemaCmd := cli.NewSchemaCommand()
+	mcpCmd := cli.NewMCPCommand()
 	// Wrap the caller so every MCP tool call's shape is recorded to the local
 	// usage log (privacy-preserving; see internal/shortcut/usage). Powers
 	// `dws shortcut stats` and future high-frequency shortcut distillation.
@@ -477,13 +468,13 @@ func newRootCommandWithEngine(rootCtx context.Context, engine *pipeline.Engine,
 		newAPICommand(flags),
 		newSkillCommand(),
 		newCacheCommand(),
-		newCatalogCommand(loader),
+		newCatalogCommand(),
 		newConfigCommand(),
 		newDoctorCommand(),
+		newRecoveryCommand(),
 		newEventCommand(),
 		newAuditCommand(),
 		newCompletionCommand(root),
-		newRecoveryCommand(rootCtx, loader, flags),
 		newUpgradeCommand(),
 		newVersionCommand(),
 		newPluginCommand(),
@@ -493,8 +484,14 @@ func newRootCommandWithEngine(rootCtx context.Context, engine *pipeline.Engine,
 	}
 	root.AddCommand(utilityCommands...)
 
-	root.AddCommand(newLegacyPublicCommands(runner, patCaller, loadRuntimeExtensions)...)
-	root.AddCommand(newLegacyHiddenCommands(runner)...)
+	if declarationOnly {
+		// Schema / surface assembly: mount the reviewed tree only. Do not
+		// injectStaticServers or InitDeps — those mutate process globals and
+		// would clobber a live runtime's caller and plugin endpoints.
+		root.AddCommand(mountLegacyPublicCommands(runner, loadRuntimeExtensions)...)
+	} else {
+		root.AddCommand(newLegacyPublicCommands(runner, patCaller, loadRuntimeExtensions)...)
+	}
 
 	// PAT authorization commands (open-source core)
 	pat.RegisterCommands(root, patCaller)
@@ -692,18 +689,6 @@ func newVersionCommand() *cobra.Command {
 	}
 }
 
-func newSchemaCommand(loader cli.CatalogLoader) *cobra.Command {
-	return cli.NewSchemaCommand(loader)
-}
-
-// buildMCPCommandFn is a test seam for newMCPCommand.
-var buildMCPCommandFn = cli.NewMCPCommand
-
-// newMCPCommand builds the `dws mcp` command tree.
-func newMCPCommand(ctx context.Context, loader cli.CatalogLoader, runner executor.Runner, engine *pipeline.Engine) *cobra.Command {
-	return buildMCPCommandFn(ctx, loader, runner, engine)
-}
-
 // hideNonDirectRuntimeCommands marks top-level product commands as hidden
 // unless they correspond to a static endpoint product or an edition-visible
 // compatibility command.
@@ -711,27 +696,6 @@ func newMCPCommand(ctx context.Context, loader cli.CatalogLoader, runner executo
 // stay hidden.
 func hideNonDirectRuntimeCommands(root *cobra.Command) {
 	allowedProducts := resolveVisibleProducts()
-	staticCommands := map[string]bool{
-		"auth":       true,
-		"api":        true,
-		"audit":      true,
-		"cache":      true,
-		"config":     true,
-		"dev":        true,
-		"doctor":     true,
-		"event":      true,
-		"completion": true,
-		"skill":      true,
-		"plugin":     true,
-		"profile":    true,
-		"version":    true,
-		"help":       true,
-		"markdown":   true,
-		"recovery":   true,
-		"schema":     true,
-		"mcp":        true,
-		"upgrade":    true,
-	}
 	for _, cmd := range root.Commands() {
 		name := cmd.Name()
 		if cmd.Hidden {
@@ -747,16 +711,40 @@ func hideNonDirectRuntimeCommands(root *cobra.Command) {
 	}
 }
 
+// builtinCommandNames is the shared base set of built-in command names. Both
+// staticCommands (the visibility allow-list used by
+// hideNonDirectRuntimeCommands) and reservedCommands (the plugin-override
+// blocklist) derive from this single set so they cannot drift apart.
+var builtinCommandNames = map[string]bool{
+	"auth": true, "api": true, "audit": true, "cache": true, "config": true,
+	"doctor": true, "event": true, "completion": true, "skill": true,
+	"plugin": true, "profile": true, "recovery": true, "version": true, "help": true,
+	"schema": true, "mcp": true, "upgrade": true,
+}
+
+// commandNameSet returns a new set containing every name in base plus extras.
+func commandNameSet(base map[string]bool, extras ...string) map[string]bool {
+	set := make(map[string]bool, len(base)+len(extras))
+	for name := range base {
+		set[name] = true
+	}
+	for _, extra := range extras {
+		set[extra] = true
+	}
+	return set
+}
+
+// staticCommands is the set of built-in commands that stay visible even when
+// they are not backed by a static endpoint product. Asymmetry with
+// reservedCommands is intentional: dev/markdown stay visible but are not
+// plugin-reserved, while login/logout are plugin-reserved but are not static
+// top-level commands.
+var staticCommands = commandNameSet(builtinCommandNames, "dev", "markdown")
+
 // reservedCommands is the set of built-in command names that plugins must
 // not override. This protects core CLI functionality from being hijacked
 // by a malicious or misconfigured plugin.
-var reservedCommands = map[string]bool{
-	"auth": true, "api": true, "audit": true, "login": true, "logout": true,
-	"plugin": true, "profile": true, "skill": true, "cache": true,
-	"config": true, "doctor": true, "event": true, "completion": true,
-	"recovery": true, "upgrade": true, "version": true,
-	"schema": true, "mcp": true, "help": true,
-}
+var reservedCommands = commandNameSet(builtinCommandNames, "login", "logout")
 
 var replaceablePluginFallbacks = map[string]bool{
 	"conference": true,
@@ -1332,13 +1320,25 @@ func registerPluginAuthFromHeaders(srv mcptypes.ServerDescriptor) {
 // Register → PreParse → PostParse → PreRequest → PostResponse.
 //
 // Phases are invoked at their respective integration points:
-//   - Register:     during command tree construction (newMCPCommand)
+//   - Register:     during command tree construction (cli.NewMCPCommand)
 //   - PreParse:     before Cobra parses raw argv (RunPreParse)
 //   - PostParse:    after Cobra parsing, before validation (canonical RunE)
 //   - PreRequest:   after validation, before JSON-RPC dispatch (canonical RunE)
 //   - PostResponse: after transport returns, before stdout (canonical RunE)
 func newPipelineEngine() *pipeline.Engine {
 	engine := pipeline.NewEngine()
+	engine.SetCommandPathFallbackLookup(func(path string) (pipeline.CommandPathFallback, bool) {
+		entry, ok := cli.LookupCommandPathFallback(path)
+		if !ok {
+			return pipeline.CommandPathFallback{}, false
+		}
+		return pipeline.CommandPathFallback{
+			From:       entry.From,
+			Mode:       string(entry.Mode),
+			To:         entry.To,
+			Candidates: append([]string(nil), entry.Candidates...),
+		}, true
+	})
 	engine.RegisterAll(
 		// Register handler runs during command tree building.
 		handlers.RegisterHandler{},

internal/app/root_construction_bench_test.go

@@ -0,0 +1,33 @@
+// 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 "testing"
+
+// BenchmarkNewRootCommand measures building the real Cobra tree — roughly 800
+// leaves with their flags, Schema annotations and PostMount work.
+//
+// It is the other half of the cold-start attribution: `dws version` never
+// decodes the Schema catalog, so whatever it spends beyond process start is
+// mostly this. Without splitting the two, an optimization aimed at JSON parsing
+// could target the smaller cost.
+func BenchmarkNewRootCommand(b *testing.B) {
+	b.ReportAllocs()
+	for i := 0; i < b.N; i++ {
+		root := NewRootCommand()
+		if root == nil {
+			b.Fatal("nil root")
+		}
+	}
+}

internal/app/root_full_coverage_test.go

@@ -12,7 +12,6 @@ import (
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/executor"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/pipeline"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/plugin"
-	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/recovery"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/transport"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/mcptypes"
@@ -24,8 +23,6 @@ func TestCrossPlatformCoverageRootExecuteAllBranchesCoverage(t *testing.T) {
 	oldExecute := rootExecuteCommand
 	oldNewRoot := rootNewRootCommandWithEngine
 	oldPreParse := rootRunPreParse
-	oldLatest := rootLatestRecoveryCapture
-	oldReset := rootResetRecoveryState
 	oldStop := rootStopAllStdioClients
 	oldArgs := os.Args
 	t.Cleanup(func() {
@@ -33,20 +30,16 @@ func TestCrossPlatformCoverageRootExecuteAllBranchesCoverage(t *testing.T) {
 		rootExecuteCommand = oldExecute
 		rootNewRootCommandWithEngine = oldNewRoot
 		rootRunPreParse = oldPreParse
-		rootLatestRecoveryCapture = oldLatest
-		rootResetRecoveryState = oldReset
 		rootStopAllStdioClients = oldStop
 		os.Args = oldArgs
 	})
 	os.Args = []string{"dws"}
 	rootNormalizeProcessProfileArgs = func() func() { return func() {} }
 	rootRunPreParse = func(*cobra.Command, *pipeline.Engine) error { return nil }
-	rootResetRecoveryState = func() {}
 	rootStopAllStdioClients = func() {}
 	rootNewRootCommandWithEngine = func(context.Context, *pipeline.Engine) *cobra.Command {
 		return &cobra.Command{Use: "dws", SilenceErrors: true, SilenceUsage: true}
 	}
-	rootLatestRecoveryCapture = func() *recovery.LastError { return nil }
 	rootExecuteCommand = func(cmd *cobra.Command) (*cobra.Command, error) { return cmd, nil }
 	if code := Execute(); code != 0 {
 		t.Fatalf("successful Execute code = %d", code)
@@ -59,7 +52,6 @@ func TestCrossPlatformCoverageRootExecuteAllBranchesCoverage(t *testing.T) {
 	rootRunPreParse = func(*cobra.Command, *pipeline.Engine) error { return nil }
 
 	wantErr := errors.New("unknown command missing")
-	rootLatestRecoveryCapture = func() *recovery.LastError { return &recovery.LastError{EventID: "evt-test"} }
 	rootExecuteCommand = func(*cobra.Command) (*cobra.Command, error) { return nil, wantErr }
 	if code := Execute(); code == 0 {
 		t.Fatal("failed Execute returned zero")

internal/app/root_help.go

@@ -163,9 +163,16 @@ func commandShort(cmd *cobra.Command) string {
 
 // resolveVisibleProducts returns the set of top-level product IDs that should
 // be treated as visible. It unions the edition's VisibleProducts hook (when
-// set) with DirectRuntimeProductIDs(), so dynamically-registered products —
-// including plugins loaded via AppendDynamicServer — are never silently hidden
-// by a static VisibleProducts list.
+// set), StaticServers product IDs, and DirectRuntimeProductIDs(), so
+// dynamically-registered products — including plugins loaded via
+// AppendDynamicServer — are never silently hidden by a static VisibleProducts
+// list.
+//
+// StaticServers are consulted directly (without injectStaticServers) so the
+// declaration-only Schema source root can keep reviewed products visible
+// without mutating the process-global dynamic endpoint registry.
+// SupplementServers stay out of this set: they are helper-only endpoints and
+// must not synthesize top-level product visibility.
 func resolveVisibleProducts() map[string]bool {
 	allowed := map[string]bool{}
 	if fn := edition.Get().VisibleProducts; fn != nil {
@@ -173,6 +180,13 @@ func resolveVisibleProducts() map[string]bool {
 			allowed[p] = true
 		}
 	}
+	if fn := edition.Get().StaticServers; fn != nil {
+		for _, server := range fn() {
+			if id := strings.TrimSpace(server.ID); id != "" {
+				allowed[id] = true
+			}
+		}
+	}
 	for id := range DirectRuntimeProductIDs() {
 		allowed[id] = true
 	}

internal/app/root_help_test.go

@@ -23,6 +23,7 @@ import (
 	"testing"
 
 	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"
 )
@@ -71,6 +72,39 @@ func TestCalendarEventCreateHelpKeepsRoomsStringMetavar(t *testing.T) {
 
 func TestRootKeepsMainBranchChatCompatibilityCommands(t *testing.T) {
 	root := NewRootCommand()
+	for _, path := range []string{
+		"chat send",
+		"chat history",
+		"im send",
+		"im history",
+	} {
+		command, remaining, err := root.Find(strings.Fields(path))
+		if err != nil {
+			t.Fatalf("find %s: %v", path, err)
+		}
+		if len(remaining) != 0 || !command.Hidden || !command.Runnable() {
+			t.Fatalf("%s compatibility contract: remaining=%v hidden=%v runnable=%v", path, remaining, command.Hidden, command.Runnable())
+		}
+	}
+	for _, tc := range []struct {
+		args []string
+		hint string
+	}{
+		{args: []string{"chat", "send", "--group", "cid-stable", "--text", "hello"}, hint: "dws chat message send"},
+		{args: []string{"im", "send", "--group", "cid-stable", "--text", "hello"}, hint: "dws chat message send"},
+		{args: []string{"chat", "history", "--group", "cid-stable", "--limit", "20"}, hint: "dws chat message list --group <GROUP_OPEN_CONVERSATION_ID>"},
+		{args: []string{"im", "history", "--group", "cid-stable", "--limit", "20"}, hint: "dws chat message list --group <GROUP_OPEN_CONVERSATION_ID>"},
+	} {
+		command := NewRootCommand()
+		command.SilenceErrors = true
+		command.SilenceUsage = true
+		command.SetArgs(tc.args)
+		err := command.Execute()
+		if err == nil || !strings.Contains(err.Error(), "ambiguous command") || !strings.Contains(err.Error(), tc.hint) {
+			t.Fatalf("dws %s error = %v, want migration hint %q", strings.Join(tc.args, " "), err, tc.hint)
+		}
+	}
+
 	listDirect := mustFindCommand(t, root, "chat", "message", "list-direct")
 	for _, flag := range []string{"user", "open-dingtalk-id", "time", "forward", "limit"} {
 		if listDirect.Flags().Lookup(flag) == nil {
@@ -161,9 +195,7 @@ func TestRootChatMediaUploadWithoutAppCredentialsReturnsMigrationValidation(t *t
 		"--file", filePath,
 		"--type", "image",
 	}
-	previousArgs := os.Args
-	os.Args = append([]string{"dws"}, commandArgs...)
-	t.Cleanup(func() { os.Args = previousArgs })
+	testseam.Swap(t, &os.Args, append([]string{"dws"}, commandArgs...))
 
 	root := NewRootCommand()
 	var output bytes.Buffer
@@ -387,20 +419,14 @@ func TestRootKeepsSVIPChatCompatibilityFlags(t *testing.T) {
 	}
 }
 
-func TestCacheRefreshCompatibilityStub(t *testing.T) {
-	cmd := NewRootCommand()
-	var out bytes.Buffer
-	cmd.SetOut(&out)
-	cmd.SetErr(&out)
-	cmd.SetArgs([]string{"cache", "refresh", "--format", "json"})
-	if err := cmd.Execute(); err != nil {
-		t.Fatalf("cache refresh compatibility stub: %v\n%s", err, out.String())
+func TestCacheCommandDeprecatedCompatStub(t *testing.T) {
+	root := NewRootCommand()
+	cmd, _, err := root.Find([]string{"cache", "refresh"})
+	if err != nil || cmd == nil || cmd == root {
+		t.Fatalf("dws cache refresh compatibility stub missing: %v", err)
 	}
-	got := out.String()
-	for _, want := range []string{`"status":"deprecated"`, `"command":"dws cache refresh"`, "服务发现已下线"} {
-		if !strings.Contains(got, want) {
-			t.Fatalf("cache refresh output missing %q:\n%s", want, got)
-		}
+	if cmd.Hidden || cmd.Deprecated == "" {
+		t.Fatalf("cache refresh must be visible Deprecated: hidden=%v deprecated=%q", cmd.Hidden, cmd.Deprecated)
 	}
 }
 

internal/app/runner.go

@@ -30,7 +30,6 @@ 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"
 	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"
@@ -123,7 +122,7 @@ func logHostOwnedPATDecisionOnce() {
 	})
 }
 
-func newCommandRunnerWithFlags(loader cli.CatalogLoader, flags *GlobalFlags) executor.Runner {
+func newCommandRunnerWithFlags(flags *GlobalFlags) executor.Runner {
 	// Ensure DWS_CLIENT_ID env is populated from persisted config before
 	// resolveIdentityHeaders reads it.  This covers fresh-process cold starts
 	// where no env var has been inherited from a parent process.
@@ -141,10 +140,8 @@ func newCommandRunnerWithFlags(loader cli.CatalogLoader, flags *GlobalFlags) exe
 	transportClient.ExtraHeaders = resolveIdentityHeaders()
 	transportClient.FileLogger = FileLoggerInstance()
 	return &runtimeRunner{
-		loader:             loader,
 		transport:          transportClient,
 		globalFlags:        flags,
-		fallback:           executor.EchoRunner{},
 		scanner:            newRuntimeContentScanner(),
 		enforceContentScan: runtimeFlagEnabled(os.Getenv(runtimeContentScanEnforceEnv), false),
 		includeScanReport:  runtimeFlagEnabled(os.Getenv(runtimeContentScanReportOutputEnv), false),
@@ -152,7 +149,6 @@ func newCommandRunnerWithFlags(loader cli.CatalogLoader, flags *GlobalFlags) exe
 }
 
 type runtimeRunner struct {
-	loader             cli.CatalogLoader
 	transport          *transport.Client
 	globalFlags        *GlobalFlags
 	fallback           executor.Runner
@@ -204,20 +200,14 @@ func (r *runtimeRunner) Run(ctx context.Context, invocation executor.Invocation)
 		return r.runMultiProfile(ctx, invocation, selections)
 	}
 	if strings.TrimSpace(rawProfile) != "" {
-		profile, err := authpkg.ResolveProfile(defaultConfigDir(), rawProfile)
+		profile, err := runnerResolveProfile(defaultConfigDir(), rawProfile)
 		if err != nil {
 			return executor.Result{}, apperrors.NewValidation(err.Error())
 		}
 		if profile == nil {
 			return executor.Result{}, apperrors.NewValidation(fmt.Sprintf("profile %q not found", rawProfile))
 		}
-		resolvedSelector := authpkg.ProfileSelector(*profile)
-		if strings.TrimSpace(profile.UserID) == "" {
-			// Preserve a unique local-name selector for an unresolved account.
-			// Reducing it to corpId can select a different exact account through
-			// the organization's current-account pointer.
-			resolvedSelector = rawProfile
-		}
+		resolvedSelector := profileRuntimeSelector(*profile, rawProfile)
 		authpkg.SetRuntimeProfile(resolvedSelector)
 		defer authpkg.SetRuntimeProfile(rawProfile)
 	}
@@ -244,12 +234,12 @@ func (r *runtimeRunner) RunReadOnly(ctx context.Context, invocation executor.Inv
 }
 
 func (r *runtimeRunner) runSingle(ctx context.Context, invocation executor.Invocation, prefetchToken bool) (executor.Result, error) {
-	if r.loader == nil || r.transport == nil {
+	if r.transport == nil {
 		return r.fallback.Run(ctx, invocation)
 	}
 	r.transport.ExtraHeaders = resolveIdentityHeaders()
 
-	// Mock mode: skip catalog validation, use a placeholder endpoint.
+	// Mock mode: skip endpoint resolution, use a placeholder endpoint.
 	if r.globalFlags != nil && r.globalFlags.Mock {
 		endpoint := fmt.Sprintf("https://mock-mcp-%s.dingtalk.com", invocation.CanonicalProduct)
 		if override, ok := productEndpointOverride(invocation.CanonicalProduct); ok {
@@ -260,7 +250,7 @@ func (r *runtimeRunner) runSingle(ctx context.Context, invocation executor.Invoc
 
 	// Prefetch the Keychain token in the background. Keychain access costs
 	// ~70ms on macOS; starting it here lets the load overlap with endpoint
-	// resolution and catalog loading below.
+	// resolution below.
 	if prefetchToken {
 		go func() {
 			_, _ = runnerGetCachedRuntimeToken(ctx)
@@ -273,56 +263,21 @@ func (r *runtimeRunner) runSingle(ctx context.Context, invocation executor.Invoc
 		}
 	}
 
-	catalogStart := time.Now()
-	catalog, err := r.loader.Load(ctx)
-	RecordTiming(ctx, "catalog_load", time.Since(catalogStart))
-	if err != nil {
-		var degraded *cli.CatalogDegraded
-		if !errors.As(err, &degraded) {
-			return executor.Result{}, err
-		}
-	}
+	// Discovery is retired: endpoint resolution is the dynamic server
+	// registry only, so a direct-runtime miss is terminal.
+	return r.handleCatalogMiss(ctx, invocation, "no dynamic endpoint registered for product or tool")
+}
 
-	product, ok := catalog.FindProduct(invocation.CanonicalProduct)
-	if !ok || strings.TrimSpace(product.Endpoint) == "" {
-		return r.handleCatalogMiss(ctx, invocation, "product missing from discovery catalog and no supplement/env override")
+// profileRuntimeSelector resolves the runtime profile selector for an
+// invocation. It preserves a unique local-name selector for an unresolved
+// account (empty UserID): reducing it to corpId can select a different exact
+// account through the organization's current-account pointer. Shared by the
+// single-profile path in Run and the multi-profile path in runMultiProfile.
+func profileRuntimeSelector(profile authpkg.Profile, rawSelector string) string {
+	if strings.TrimSpace(profile.UserID) == "" {
+		return rawSelector
 	}
-	if _, ok := product.FindTool(invocation.Tool); !ok {
-		// Catalog knows the product but not the tool — this happens when the
-		// catalog entry came from SupplementServers (endpoint-only, no tool
-		// list). Trust directRuntimeEndpoint to re-resolve a working endpoint
-		// for the tool. If that also misses, fall through to handleCatalogMiss
-		// so stderr still carries the explicit not-resolved signal.
-		if endpoint, ok := directRuntimeEndpoint(invocation.CanonicalProduct, invocation.Tool); ok {
-			if r.globalFlags != nil && r.globalFlags.DryRun {
-				invocation.DryRun = true
-			}
-			return r.executeInvocation(ctx, endpoint, invocation)
-		}
-		return r.handleCatalogMiss(ctx, invocation, fmt.Sprintf("tool %q not declared by product %q in discovery catalog", invocation.Tool, invocation.CanonicalProduct))
-	}
-	if r.globalFlags != nil && r.globalFlags.DryRun {
-		invocation.DryRun = true
-	}
-
-	endpoint := product.Endpoint
-	if override, ok := productEndpointOverride(invocation.CanonicalProduct); ok {
-		endpoint = override
-	}
-	// Multi-server tool-name authority correction.
-	//
-	// When two envelope servers share the same cli.command (e.g. group-chat
-	// and im both publish `dws chat ...`), the endpoints[cmd] map in
-	// registerDynamicServer is the second-writer wins, and catalog FindProduct
-	// may pick the wrong product's Endpoint for a tool whose real owner is
-	// a different server. Cross-check the canonical tool→endpoint map: when
-	// the per-tool endpoint exists and differs from the per-product endpoint
-	// catalog returned, trust the tool-owner endpoint (the server that
-	// actually declares this tool in its toolOverrides).
-	if toolEndpoint, ok := directRuntimeToolEndpoint(invocation.Tool); ok && toolEndpoint != "" && toolEndpoint != endpoint {
-		endpoint = toolEndpoint
-	}
-	return r.executeInvocation(ctx, endpoint, invocation)
+	return authpkg.ProfileSelector(profile)
 }
 
 type multiProfileSelection struct {
@@ -376,10 +331,7 @@ func (r *runtimeRunner) runMultiProfile(ctx context.Context, invocation executor
 	failed := 0
 
 	for _, selection := range selections {
-		resolvedSelector := authpkg.ProfileSelector(selection.Profile)
-		if strings.TrimSpace(selection.Profile.UserID) == "" {
-			resolvedSelector = selection.Selector
-		}
+		resolvedSelector := profileRuntimeSelector(selection.Profile, selection.Selector)
 		authpkg.SetRuntimeProfile(resolvedSelector)
 		result, err := r.runSingle(ctx, cloneInvocation(invocation), false)
 
@@ -461,6 +413,33 @@ func multiProfileErrorPayload(err error) map[string]any {
 		if typed.Operation != "" {
 			payload["operation"] = typed.Operation
 		}
+		if typed.Origin != "" {
+			payload["origin"] = typed.Origin
+		}
+		if typed.FailureStage != "" {
+			payload["stage"] = typed.FailureStage
+		}
+		if typed.ExecutionStarted != nil {
+			payload["execution_started"] = *typed.ExecutionStarted
+		}
+		if typed.RetryableSet {
+			payload["retryable"] = typed.Retryable
+		}
+		if typed.Hint != "" {
+			payload["hint"] = typed.Hint
+		}
+		if len(typed.Actions) > 0 {
+			payload["actions"] = append([]string(nil), typed.Actions...)
+		}
+		if len(typed.Details) > 0 {
+			payload["details"] = typed.Details
+		}
+		if typed.ServerDiag.TraceID != "" {
+			payload["trace_id"] = typed.ServerDiag.TraceID
+		}
+		if typed.ServerDiag.ServerErrorCode != "" {
+			payload["server_error_code"] = typed.ServerDiag.ServerErrorCode
+		}
 		if code := typed.ExitCode(); code != 0 {
 			payload["exitCode"] = code
 		}
@@ -468,45 +447,51 @@ func multiProfileErrorPayload(err error) map[string]any {
 	return payload
 }
 
-// handleCatalogMiss decides what to do when discovery catalog does not cover the
-// requested product / tool and no `directRuntimeEndpoint` match fired earlier.
+// handleCatalogMiss decides what to do when the dynamic server registry has
+// no endpoint for the requested product / tool and no `directRuntimeEndpoint`
+// match fired earlier. The discovery catalog is retired; endpoint resolution
+// is the dynamic server registry only, so a registry miss here is terminal.
 //
-// Previously every catalog miss silently fell through to EchoRunner, which
+// Previously every miss silently fell through to EchoRunner, which
 // returns an empty `executor.Result{Response: nil}`. The helper-invocation
 // adapter then converted that into `&edition.ToolResult{}`, whose `Content`
 // marshals to `null`, surfacing as `{"Content": null}` at the CLI. Users had no
 // signal that endpoint resolution failed — see the fix-wukong-discovery-missing-servers plan (Phase 3) for the full trace.
 //
-// New contract:
-//   - Dry-run (invocation.DryRun or globalFlags.DryRun): keep EchoRunner so
-//     `--dry-run` still prints the planned payload without real execution.
-//   - Otherwise: return an explicit apperrors.NewAPI("endpoint_not_resolved")
-//     with the offending product/tool attached. This fails fast to stderr and
-//     makes missing envelopes / supplement gaps immediately visible.
-func (r *runtimeRunner) handleCatalogMiss(ctx context.Context, invocation executor.Invocation, detail string) (executor.Result, error) {
-	dryRun := invocation.DryRun || (r.globalFlags != nil && r.globalFlags.DryRun)
-	if dryRun {
-		invocation.DryRun = true
-		return r.fallback.Run(ctx, invocation)
-	}
+// Contract: return an explicit apperrors.NewAPI("endpoint_not_resolved")
+// with the offending product/tool attached. This fails fast to stderr and
+// makes missing envelopes / supplement gaps immediately visible. Dry-run
+// invocations never reach this path in production: Run enforces the dry-run
+// barrier before endpoint resolution, and runSingle is only re-entered via
+// Run (multi-profile and PAT retry both route back through it).
+func (r *runtimeRunner) handleCatalogMiss(_ context.Context, invocation executor.Invocation, detail string) (executor.Result, error) {
+	return executor.Result{}, endpointNotResolvedError(invocation.CanonicalProduct, invocation.Tool, detail)
+}
+
+// endpointNotResolvedError builds the shared terminal error for a dynamic
+// server registry miss. Both the runtime runner (handleCatalogMiss) and the
+// recovery runtime (resolveEndpoint) use it so endpoint misses classify
+// identically: CategoryAPI, operation "discovery.resolve", reason
+// "endpoint_not_resolved", with the product ID as the server key.
+func endpointNotResolvedError(productID, toolName, detail string) error {
 	hint := "当前命令已注册，但静态端点目录中缺少对应 product/server endpoint。这通常是服务发现下线后的同步产物缺口，不是参数错误；请不要通过反复调整 flag 重试。"
 	actions := []string{
 		"确认 internal/syncdata.StaticServers() 是否包含该 product/server",
 		"运行 sync-oss 重新生成静态端点与路由",
 		"若该能力已下线，请在 skill 与 --help 中标记 unavailable 并提供替代命令",
 	}
-	if strings.TrimSpace(invocation.CanonicalProduct) == devappProductID {
+	if strings.TrimSpace(productID) == devappProductID {
 		hint = "dev app（product id: devapp）是 helper-only 产品，命令树不依赖服务发现；真实调用需要通过 StaticServers/SupplementServers 注入 MCP endpoint，或本地调试临时设置 DINGTALK_DEVAPP_MCP_URL。"
 		actions = []string{
 			"检查 StaticServers/SupplementServers 是否包含 devapp endpoint",
 			"本地调试可临时设置 DINGTALK_DEVAPP_MCP_URL 后重试",
 		}
 	}
-	return executor.Result{}, apperrors.NewAPI(
-		fmt.Sprintf("endpoint not resolved for product %q (tool %q): %s", invocation.CanonicalProduct, invocation.Tool, detail),
+	return apperrors.NewAPI(
+		fmt.Sprintf("endpoint not resolved for product %q (tool %q): %s", productID, toolName, detail),
 		apperrors.WithOperation("discovery.resolve"),
 		apperrors.WithReason("endpoint_not_resolved"),
-		apperrors.WithServerKey(invocation.CanonicalProduct),
+		apperrors.WithServerKey(productID),
 		apperrors.WithHint(hint),
 		apperrors.WithActions(actions...),
 	)
@@ -720,7 +705,6 @@ func (r *runtimeRunner) executeInvocation(ctx context.Context, endpoint string,
 
 	if callResult.IsError {
 		diag := transport.ExtractServerDiagnosticsFromMap(callResult.Content)
-		logBusinessError(r.transport.FileLogger, "mcp_tool_error", invocation, callResult.Content, diag)
 
 		// ClassifyToolResult hook: let the overlay intercept known error
 		// patterns (PAT permission, gateway-auth) before generic handling.
@@ -737,14 +721,14 @@ func (r *runtimeRunner) executeInvocation(ctx context.Context, endpoint string,
 			}
 		}
 
-		mcpErr := apperrors.NewAPI(
+		mcpErr := newServerFailureAPIError(
 			extractMCPErrorMessage(callResult),
-			apperrors.WithOperation("tools/call"),
-			apperrors.WithReason("mcp_tool_error"),
-			apperrors.WithServerKey(invocation.CanonicalProduct),
-			apperrors.WithHint("MCP tool returned a business error; check tool parameters and refer to skill documentation."),
-			apperrors.WithServerDiag(diag),
+			"mcp_tool_error",
+			"MCP tool returned a business error; check tool parameters and refer to skill documentation.",
+			invocation.CanonicalProduct,
+			diag,
 		)
+		logBusinessError(r.transport.FileLogger, serverFailureReason(mcpErr, "mcp_tool_error"), invocation, callResult.Content, diag)
 		// PAT scope error in business response: offer human-readable output and retry
 		if isPatScopeError(mcpErr) {
 			scopeErr := extractPatScopeError(mcpErr)
@@ -762,14 +746,15 @@ func (r *runtimeRunner) executeInvocation(ctx context.Context, endpoint string,
 
 	if bizErr := detectBusinessError(callResult.Content); bizErr != "" {
 		diag := transport.ExtractServerDiagnosticsFromMap(callResult.Content)
-		logBusinessError(r.transport.FileLogger, "business_error", invocation, callResult.Content, diag)
-		return executor.Result{}, apperrors.NewAPI(bizErr,
-			apperrors.WithOperation("tools/call"),
-			apperrors.WithReason("business_error"),
-			apperrors.WithServerKey(invocation.CanonicalProduct),
-			apperrors.WithHint("The API returned a business-level error. Check required parameters and values."),
-			apperrors.WithServerDiag(diag),
+		classifiedErr := newServerFailureAPIError(
+			bizErr,
+			"business_error",
+			"The API returned a business-level error. Check required parameters and values.",
+			invocation.CanonicalProduct,
+			diag,
 		)
+		logBusinessError(r.transport.FileLogger, serverFailureReason(classifiedErr, "business_error"), invocation, callResult.Content, diag)
+		return executor.Result{}, classifiedErr
 	}
 
 	invocation.Implemented = true
@@ -792,13 +777,6 @@ func (r *runtimeRunner) executeInvocation(ctx context.Context, endpoint string,
 	return executor.Result{Invocation: invocation, Response: response}, nil
 }
 
-// executeStdioInvocation dispatches a tool call through a local StdioClient
-// subprocess instead of the HTTP transport. This is used for plugin stdio
-// servers whose endpoints use the stdio:// scheme.
-func (r *runtimeRunner) executeStdioInvocation(ctx context.Context, invocation executor.Invocation) (executor.Result, error) {
-	return r.executeStdioInvocationAtEndpoint(ctx, "", invocation)
-}
-
 func (r *runtimeRunner) executeStdioInvocationAtEndpoint(
 	ctx context.Context,
 	endpoint string,
@@ -1005,9 +983,8 @@ func resolveIdentityHeaders() map[string]string {
 
 	// Inject environment variable based headers for MCP gateway tracking.
 	// DINGTALK_AGENT, if set by the caller, is forwarded verbatim as the
-	// x-dingtalk-agent header. It does NOT influence claw-type (which comes
-	// from the edition default plus the explicit DWS_AGENT_PRODUCT override)
-	// and it does NOT influence the host-owned PAT decision (driven solely by
+	// x-dingtalk-agent header. It does NOT influence the edition-fixed
+	// claw-type or the host-owned PAT decision (driven solely by
 	// DINGTALK_DWS_AGENTCODE).
 	sessionID := os.Getenv(envDingtalkSessionID)
 	if sessionID == "" {
@@ -1068,22 +1045,30 @@ func resolveIdentityHeaders() map[string]string {
 	if fn := edition.Get().MergeHeaders; fn != nil {
 		headers = fn(headers)
 	}
-	// Resolve the Agent Product before credential injection. The credential
-	// hook has a separate contract and must not be able to replace the
-	// request identity used by PAT hostControl serialization.
-	headers = applyAgentProductOverride(headers)
-	agentProduct := headers[agentproduct.HeaderName]
+	if headers == nil {
+		headers = make(map[string]string)
+	}
+
+	// claw-type is the edition-fixed routing/PAT identity. Agent Product is a
+	// separate caller-declared observability and IM-display dimension.
+	clawType := resolveEditionClawType(headers)
+	headers["claw-type"] = clawType
+	headers = applyAgentProductHeader(headers)
+	agentProduct, hasAgentProduct := headers[agentproduct.HeaderName]
 	if fn := edition.Get().EnterpriseCredentialHeaders; fn != nil {
 		headers = fn(headers)
 	}
 	if headers == nil {
 		headers = make(map[string]string)
 	}
-	// DWS_AGENT_PRODUCT is the explicit caller override for the existing
-	// claw-type wire header. Reassert the resolved product after credential
-	// injection so that hook cannot alter identity. Invalid values are ignored
-	// on this best-effort library path; root execution rejects them earlier.
-	headers[agentproduct.HeaderName] = agentProduct
+	// Credential hooks cannot alter either identity dimension. Restore the
+	// fixed claw-type and the validated Product Header (or its absence).
+	headers["claw-type"] = clawType
+	if hasAgentProduct {
+		headers[agentproduct.HeaderName] = agentProduct
+	} else {
+		delete(headers, agentproduct.HeaderName)
+	}
 	return headers
 }
 

internal/app/runner_full_coverage_test.go

@@ -8,7 +8,6 @@ import (
 	"testing"
 
 	authpkg "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/auth"
-	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/cli"
 	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/executor"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/safety"
@@ -35,7 +34,7 @@ func TestCrossPlatformCoverageRunnerRemainingRoutingCoverage(t *testing.T) {
 		runnerGetCachedRuntimeToken = oldCachedToken
 	})
 
-	created := newCommandRunnerWithFlags(cli.StaticLoader{}, &GlobalFlags{Timeout: 2})
+	created := newCommandRunnerWithFlags(&GlobalFlags{Timeout: 2})
 	if created.(*runtimeRunner).transport == nil {
 		t.Fatal("runner transport was not created")
 	}
@@ -55,21 +54,20 @@ func TestCrossPlatformCoverageRunnerRemainingRoutingCoverage(t *testing.T) {
 		return "", nil
 	}
 	r := &runtimeRunner{
-		loader:    cli.CatalogLoaderFrom(cli.Catalog{}, wantErr),
 		transport: transport.NewClient(nil),
 		fallback:  runnerCoverageFallback{},
 	}
 	directMiss := inv
 	directMiss.Kind = "helper_invocation"
-	if _, err := r.runSingle(context.Background(), directMiss, false); !errors.Is(err, wantErr) {
-		t.Fatalf("direct runtime miss load error = %v", err)
+	if _, err := r.runSingle(context.Background(), directMiss, false); err == nil || !strings.Contains(err.Error(), "no dynamic endpoint registered for product or tool") {
+		t.Fatalf("direct runtime miss = %v", err)
 	}
 	directHit := executor.Invocation{Kind: "helper_invocation", CanonicalProduct: defaultPATProductID, Tool: "pat", DryRun: true}
 	if got, err := r.runSingle(context.Background(), directHit, false); err != nil || got.Response["dry_run"] != true {
 		t.Fatalf("direct runtime hit = %#v, %v", got, err)
 	}
-	if _, err := r.runSingle(context.Background(), inv, true); !errors.Is(err, wantErr) {
-		t.Fatalf("runSingle error = %v", err)
+	if _, err := r.runSingle(context.Background(), inv, true); err == nil {
+		t.Fatal("endpoint miss succeeded")
 	}
 	<-prefetched
 
@@ -113,17 +111,18 @@ func TestCrossPlatformCoverageRunnerRemainingRoutingCoverage(t *testing.T) {
 		t.Fatalf("multi success aggregation = %#v, %v", result, err)
 	}
 
-	product := cli.CanonicalProduct{ID: "product", Endpoint: "https://catalog.test", Tools: []cli.ToolDescriptor{{RPCName: "tool"}}}
 	r = &runtimeRunner{
-		loader:      cli.StaticLoader{Catalog: cli.Catalog{Products: []cli.CanonicalProduct{product}}},
 		transport:   transport.NewClient(nil),
 		globalFlags: &GlobalFlags{DryRun: true},
 		fallback:    runnerCoverageFallback{},
 	}
+	overrideInv := inv
+	overrideInv.Kind = "helper_invocation"
+	overrideInv.DryRun = true
 	t.Setenv("DINGTALK_PRODUCT_MCP_URL", "https://override.test")
-	got, err := r.runSingle(context.Background(), inv, false)
+	got, err := r.runSingle(context.Background(), overrideInv, false)
 	if err != nil || got.Response["endpoint"] != "https://override.test" {
-		t.Fatalf("catalog override = %#v, %v", got, err)
+		t.Fatalf("direct runtime override = %#v, %v", got, err)
 	}
 }
 
@@ -307,7 +306,7 @@ func TestCrossPlatformCoverageRunnerRemainingStdioAuthAndHeadersCoverage(t *test
 	inv := executor.Invocation{CanonicalProduct: "stdio-product", Tool: "tool"}
 	wantErr := errors.New("stdio failed")
 	runnerStdioEnsureInitialized = func(*transport.StdioClient, context.Context) error { return wantErr }
-	if _, err := r.executeStdioInvocation(context.Background(), inv); err == nil || !strings.Contains(err.Error(), "stdio initialize failed") {
+	if _, err := r.executeStdioInvocationAtEndpoint(context.Background(), "", inv); err == nil || !strings.Contains(err.Error(), "stdio initialize failed") {
 		t.Fatalf("stdio initialize error = %v", err)
 	}
 	runnerStdioEnsureInitialized = func(*transport.StdioClient, context.Context) error { return nil }
@@ -322,19 +321,19 @@ func TestCrossPlatformCoverageRunnerRemainingStdioAuthAndHeadersCoverage(t *test
 	runnerStdioCallTool = func(*transport.StdioClient, context.Context, string, map[string]any) (transport.ToolCallResult, error) {
 		return transport.ToolCallResult{}, wantErr
 	}
-	if _, err := r.executeStdioInvocation(context.Background(), inv); err == nil || !strings.Contains(err.Error(), "stdio failed") {
+	if _, err := r.executeStdioInvocationAtEndpoint(context.Background(), "", inv); err == nil || !strings.Contains(err.Error(), "stdio failed") {
 		t.Fatalf("stdio call error = %v", err)
 	}
 	runnerStdioCallTool = func(*transport.StdioClient, context.Context, string, map[string]any) (transport.ToolCallResult, error) {
 		return transport.ToolCallResult{IsError: true, Content: map[string]any{"message": "tool failed"}}, nil
 	}
-	if _, err := r.executeStdioInvocation(context.Background(), inv); err == nil || !strings.Contains(err.Error(), "tool failed") {
+	if _, err := r.executeStdioInvocationAtEndpoint(context.Background(), "", inv); err == nil || !strings.Contains(err.Error(), "tool failed") {
 		t.Fatalf("stdio tool error = %v", err)
 	}
 	runnerStdioCallTool = func(*transport.StdioClient, context.Context, string, map[string]any) (transport.ToolCallResult, error) {
 		return transport.ToolCallResult{Content: map[string]any{"ok": true}}, nil
 	}
-	if got, err := r.executeStdioInvocation(context.Background(), inv); err != nil || !got.Invocation.Implemented {
+	if got, err := r.executeStdioInvocationAtEndpoint(context.Background(), "", inv); err != nil || !got.Invocation.Implemented {
 		t.Fatalf("stdio success = %#v, %v", got, err)
 	}
 	RegisterStdioClient("plugin/server-key", client)

internal/app/schema_agent_examples_dry_run_test.go

@@ -27,35 +27,42 @@ import (
 	"testing"
 
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/cli"
+	"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/pkg/edition"
 	"github.com/fatih/color"
 )
 
 var (
-	manualAgentExamplePlaceholderPattern = regexp.MustCompile(`<([^>]+)>`)
-	manualAgentExampleDryRunJSONPattern  = regexp.MustCompile(`(?i)"dry_run"\s*:\s*true`)
-	manualAgentExampleDryRunPlanPattern  = regexp.MustCompile(`(?i)"preview_kind"\s*:\s*"plan"`)
+	agentExamplePlaceholderPattern = regexp.MustCompile(`<([^>]+)>`)
+	agentExampleDryRunJSONPattern  = regexp.MustCompile(`(?i)"dry_run"\s*:\s*true`)
+	agentExampleDryRunPlanPattern  = regexp.MustCompile(`(?i)"preview_kind"\s*:\s*"plan"`)
+	// agentExampleDryRunInvocationPattern recognizes the executor
+	// envelope (and the dev connect preview, which mirrors its shape): the
+	// top-level contract is an invocation that merely embeds the would-be
+	// request inside response, so it must classify as invocation, not request.
+	agentExampleDryRunInvocationPattern = regexp.MustCompile(
+		`"kind"\s*:\s*"(?:(?:helper|compat|workflow)_invocation|connect_preview)"`)
 )
 
-// TestManualAgentExamplesContract is the always-on gate. It validates every
+// TestAgentExamplesContract is the always-on gate. It validates every
 // example, including contract_only entries, against the live bound Cobra path,
 // flags, required arguments, constraints, and final typed safety.
-func TestManualAgentExamplesContract(t *testing.T) {
-	plan := manualAgentExampleExecutionPlan(t)
+func TestAgentExamplesContract(t *testing.T) {
+	plan := agentExampleExecutionPlan(t)
 	if plan.Total == 0 {
 		t.Fatal("no reviewed Agent examples were contract validated")
 	}
 	t.Logf("Agent example contract: total=%d contract=%d dry_run=%d contract_only=%d", plan.Total, plan.Contract, plan.DryRun, plan.ContractOnly)
 }
 
-// TestManualAgentExamplesDryRun first validates every reviewed example against
+// TestAgentExamplesDryRun first validates every reviewed example against
 // its real BoundCommand, Cobra required arguments, and final typed constraints.
 // It then executes only the deterministic, explicitly declared dry_run subset
 // without injecting --yes. Global flag inheritance is not treated as capability
 // evidence. Runtime failures never create implicit skips. No shell is involved
 // and HOME is isolated.
-func TestManualAgentExamplesDryRun(t *testing.T) {
+func TestAgentExamplesDryRun(t *testing.T) {
 	if os.Getenv("DWS_AGENT_EXAMPLES_DRY_RUN") != "1" {
 		t.Skip("set DWS_AGENT_EXAMPLES_DRY_RUN=1 to execute the explicitly reviewed Agent dry-run subset")
 	}
@@ -74,45 +81,45 @@ func TestManualAgentExamplesDryRun(t *testing.T) {
 	t.Setenv("HTTPS_PROXY", "http://127.0.0.1:1")
 	t.Setenv("NO_PROXY", "")
 
-	plan := manualAgentExampleExecutionPlan(t)
+	plan := agentExampleExecutionPlan(t)
 	if plan.Total == 0 {
 		t.Fatal("no reviewed Agent examples were contract validated")
 	}
 	t.Chdir(sandboxRoot)
-	files := newManualAgentExampleFiles(t, sandboxRoot)
+	files := newAgentExampleFiles(t, sandboxRoot)
 
 	selected := 0
 	executed := 0
 	for _, execution := range plan.Examples {
-		if !manualAgentExampleShouldExerciseDryRun(execution) {
+		if !agentExampleShouldExerciseDryRun(execution) {
 			continue
 		}
 		selected++
 		execution := execution
 		t.Run(fmt.Sprintf("%s/%d", strings.ReplaceAll(execution.CanonicalPath, ".", "/"), execution.Index), func(t *testing.T) {
-			argv, err := cli.ParseManualAgentExampleArgv(execution.Example)
+			argv, err := cli.ParseAgentExampleArgv(execution.Example)
 			if err != nil {
 				t.Fatalf("parse example %q: %v", execution.Example, err)
 			}
-			args := materializeManualAgentExampleArgv(argv[1:], files)
-			if manualAgentExampleHasFlag(args, "yes") {
+			args := materializeAgentExampleArgv(argv[1:], files)
+			if agentExampleHasFlag(args, "yes") {
 				t.Fatalf("dry-run gate must not inject or accept --yes\nsource: %s\nargv: %q", execution.Example, args)
 			}
-			if !manualAgentExampleHasFlag(args, "dry-run") {
+			if !agentExampleHasFlag(args, "dry-run") {
 				args = append([]string{"--dry-run"}, args...)
 			}
 
-			capture, err := executeManualAgentExampleCapture(t, args)
+			capture, err := executeAgentExampleCapture(t, args)
 			if capture.ToolCallAttempts != 0 {
 				t.Fatalf("eligible dry-run attempted %d ToolCaller invocation(s)\nsource: %s\nargv: %q\noutput:\n%s", capture.ToolCallAttempts, execution.Example, args, capture.Output)
 			}
-			if capture.StdinBytesRead != 0 || manualAgentExamplePromptObserved(capture.Output) {
+			if capture.StdinBytesRead != 0 || agentExamplePromptObserved(capture.Output) {
 				t.Fatalf("eligible dry-run entered an interactive confirmation path (stdin bytes read: %d)\nsource: %s\nargv: %q\noutput:\n%s", capture.StdinBytesRead, execution.Example, args, capture.Output)
 			}
 			if err != nil {
 				t.Fatalf("dry-run example failed: %v\nsource: %s\nargv: %q\noutput:\n%s", err, execution.Example, args, capture.Output)
 			}
-			previewKind, observed := manualAgentExampleDryRunEvidence(capture)
+			previewKind, observed := agentExampleDryRunEvidence(capture)
 			if !observed {
 				t.Fatalf("example returned without audited dry-run evidence (caller dry-run checks: %d)\nsource: %s\nargv: %q\noutput:\n%s", capture.DryRunChecks, execution.Example, args, capture.Output)
 			}
@@ -133,27 +140,20 @@ func TestManualAgentExamplesDryRun(t *testing.T) {
 	}
 	sort.Strings(reasonCodes)
 	for _, reasonCode := range reasonCodes {
-		t.Logf("Agent examples contract_only[%s]=%d", reasonCode, plan.ContractOnlyByReason[cli.ManualAgentExampleReasonCode(reasonCode)])
+		t.Logf("Agent examples contract_only[%s]=%d", reasonCode, plan.ContractOnlyByReason[cli.AgentExampleReasonCode(reasonCode)])
 	}
 }
 
-// manualAgentExampleShouldExerciseDryRun is the single selection boundary for
+// agentExampleShouldExerciseDryRun is the single selection boundary for
 // the runtime gate. Capability comes only from the final typed ToolSpec; the
 // example disposition may narrow that set but can never invent support.
-func manualAgentExampleShouldExerciseDryRun(execution cli.ManualAgentExampleExecution) bool {
-	return execution.DryRun != nil && execution.Mode == cli.ManualAgentExampleModeDryRun
+func agentExampleShouldExerciseDryRun(execution cli.AgentExampleExecution) bool {
+	return execution.DryRun != nil && execution.Mode == cli.AgentExampleModeDryRun
 }
 
-func manualAgentExampleExecutionPlan(t testing.TB) cli.ManualAgentExampleExecutionPlan {
+func agentExampleExecutionPlan(t testing.TB) cli.AgentExampleExecutionPlan {
 	t.Helper()
-	hints, err := cli.LoadAgentHintsFromSelectionForValidation(os.DirFS("../cli/schema_hints/selection"))
-	if err != nil {
-		t.Fatalf("LoadAgentHintsFromSelectionForValidation() error = %v", err)
-	}
 	contractRoot := NewRootCommand()
-	if _, err := cli.ApplyEmbeddedManualSchemaHints(contractRoot); err != nil {
-		t.Fatalf("ApplyEmbeddedManualSchemaHints() error = %v", err)
-	}
 	effective, err := cli.BuildEffectiveCommandRegistry(contractRoot)
 	if err != nil {
 		t.Fatalf("BuildEffectiveCommandRegistry() error = %v", err)
@@ -169,41 +169,41 @@ func manualAgentExampleExecutionPlan(t testing.TB) cli.ManualAgentExampleExecuti
 	if err := cli.ValidateReviewedDryRunCapabilityDelivery(registry); err != nil {
 		t.Fatalf("ValidateReviewedDryRunCapabilityDelivery() error = %v", err)
 	}
-	plan, err := cli.BuildManualAgentExampleExecutionPlan(bound, registry, hints)
+	plan, err := cli.BuildAgentExampleExecutionPlan(bound, registry)
 	if err != nil {
-		t.Fatalf("BuildManualAgentExampleExecutionPlan() error = %v", err)
+		t.Fatalf("BuildAgentExampleExecutionPlan() error = %v", err)
 	}
 	return plan
 }
 
-type manualAgentExampleCapture struct {
+type agentExampleCapture struct {
 	Output           string
 	DryRunChecks     int64
 	ToolCallAttempts int64
 	StdinBytesRead   int64
 }
 
-type manualAgentExampleFailClosedCaller struct {
+type agentExampleFailClosedCaller struct {
 	dryRunChecks     atomic.Int64
 	toolCallAttempts atomic.Int64
 }
 
-func (c *manualAgentExampleFailClosedCaller) CallTool(_ context.Context, productID, toolName string, _ map[string]any) (*edition.ToolResult, error) {
+func (c *agentExampleFailClosedCaller) CallTool(_ context.Context, productID, toolName string, _ map[string]any) (*edition.ToolResult, error) {
 	c.toolCallAttempts.Add(1)
 	return nil, fmt.Errorf("real ToolCaller invocation blocked during Agent example dry-run: %s/%s", productID, toolName)
 }
 
-func (c *manualAgentExampleFailClosedCaller) Format() string { return "json" }
+func (c *agentExampleFailClosedCaller) Format() string { return "json" }
 
-func (c *manualAgentExampleFailClosedCaller) DryRun() bool {
+func (c *agentExampleFailClosedCaller) DryRun() bool {
 	c.dryRunChecks.Add(1)
 	return true
 }
 
-func (c *manualAgentExampleFailClosedCaller) Fields() string { return "" }
-func (c *manualAgentExampleFailClosedCaller) JQ() string     { return "" }
+func (c *agentExampleFailClosedCaller) Fields() string { return "" }
+func (c *agentExampleFailClosedCaller) JQ() string     { return "" }
 
-func executeManualAgentExampleCapture(t testing.TB, args []string) (manualAgentExampleCapture, error) {
+func executeAgentExampleCapture(t testing.TB, args []string) (agentExampleCapture, error) {
 	t.Helper()
 	oldArgs := os.Args
 	os.Args = append([]string{"dws"}, args...)
@@ -239,7 +239,7 @@ func executeManualAgentExampleCapture(t testing.TB, args []string) (manualAgentE
 
 	root := NewRootCommand()
 	originalCaller := helpers.GetCaller()
-	auditCaller := &manualAgentExampleFailClosedCaller{}
+	auditCaller := &agentExampleFailClosedCaller{}
 	helpers.InitDeps(auditCaller)
 	defer helpers.InitDeps(originalCaller)
 	var output bytes.Buffer
@@ -261,7 +261,7 @@ func executeManualAgentExampleCapture(t testing.TB, args []string) (manualAgentE
 	if err != nil {
 		t.Fatalf("inspect guarded stdin: %v", err)
 	}
-	return manualAgentExampleCapture{
+	return agentExampleCapture{
 		Output:           output.String() + string(captured),
 		DryRunChecks:     auditCaller.dryRunChecks.Load(),
 		ToolCallAttempts: auditCaller.toolCallAttempts.Load(),
@@ -269,7 +269,7 @@ func executeManualAgentExampleCapture(t testing.TB, args []string) (manualAgentE
 	}, execErr
 }
 
-type manualAgentExampleFiles struct {
+type agentExampleFiles struct {
 	root     string
 	markdown string
 	json     string
@@ -278,7 +278,7 @@ type manualAgentExampleFiles struct {
 	image    string
 }
 
-func newManualAgentExampleFiles(t testing.TB, root string) manualAgentExampleFiles {
+func newAgentExampleFiles(t testing.TB, root string) agentExampleFiles {
 	t.Helper()
 	markdown := filepath.Join(root, "content.md")
 	jsonFile := filepath.Join(root, "report.json")
@@ -296,13 +296,20 @@ func newManualAgentExampleFiles(t testing.TB, root string) manualAgentExampleFil
 			t.Fatalf("write dry-run fixture %s: %v", path, err)
 		}
 	}
-	return manualAgentExampleFiles{root: root, markdown: markdown, json: jsonFile, batch: batch, binary: binary, image: image}
+	return agentExampleFiles{
+		root:     root,
+		markdown: "./" + filepath.Base(markdown),
+		json:     "./" + filepath.Base(jsonFile),
+		batch:    "./" + filepath.Base(batch),
+		binary:   "./" + filepath.Base(binary),
+		image:    "./" + filepath.Base(image),
+	}
 }
 
-func materializeManualAgentExampleArgv(argv []string, files manualAgentExampleFiles) []string {
+func materializeAgentExampleArgv(argv []string, files agentExampleFiles) []string {
 	result := append([]string(nil), argv...)
 	for index := range result {
-		result[index] = manualAgentExamplePlaceholderPattern.ReplaceAllStringFunc(result[index], func(match string) string {
+		result[index] = agentExamplePlaceholderPattern.ReplaceAllStringFunc(result[index], func(match string) string {
 			name := strings.TrimSuffix(strings.TrimPrefix(match, "<"), ">")
 			switch strings.ToLower(name) {
 			case "basetime", "remindertimestamp", "reminder-time-stamp":
@@ -323,7 +330,7 @@ func materializeManualAgentExampleArgv(argv []string, files manualAgentExampleFi
 	}
 
 	for index := 0; index < len(result); index++ {
-		name, inline, ok := manualAgentExampleLongFlag(result[index])
+		name, inline, ok := agentExampleLongFlag(result[index])
 		if !ok {
 			continue
 		}
@@ -368,7 +375,7 @@ func materializeManualAgentExampleArgv(argv []string, files manualAgentExampleFi
 	return result
 }
 
-func manualAgentExampleLongFlag(argument string) (name, inline string, ok bool) {
+func agentExampleLongFlag(argument string) (name, inline string, ok bool) {
 	if !strings.HasPrefix(argument, "--") {
 		return "", "", false
 	}
@@ -376,7 +383,7 @@ func manualAgentExampleLongFlag(argument string) (name, inline string, ok bool)
 	return name, inline, name != ""
 }
 
-func manualAgentExampleHasFlag(argv []string, target string) bool {
+func agentExampleHasFlag(argv []string, target string) bool {
 	for _, argument := range argv {
 		if argument == "--"+target || strings.HasPrefix(argument, "--"+target+"=") {
 			return true
@@ -385,33 +392,36 @@ func manualAgentExampleHasFlag(argv []string, target string) bool {
 	return false
 }
 
-func manualAgentExampleDryRunObserved(capture manualAgentExampleCapture) bool {
-	_, ok := manualAgentExampleDryRunEvidence(capture)
+func agentExampleDryRunObserved(capture agentExampleCapture) bool {
+	_, ok := agentExampleDryRunEvidence(capture)
 	return ok
 }
 
-func manualAgentExampleDryRunEvidence(capture manualAgentExampleCapture) (string, bool) {
+func agentExampleDryRunEvidence(capture agentExampleCapture) (string, bool) {
 	normalized := strings.ToLower(capture.Output)
-	if manualAgentExampleDryRunJSONPattern.MatchString(capture.Output) && manualAgentExampleDryRunPlanPattern.MatchString(capture.Output) {
-		return cli.DryRunPreviewPlan, true
+	if agentExampleDryRunJSONPattern.MatchString(capture.Output) && agentExampleDryRunPlanPattern.MatchString(capture.Output) {
+		return contract.DryRunPreviewPlan, true
 	}
-	if manualAgentExampleDryRunJSONPattern.MatchString(capture.Output) {
-		return cli.DryRunPreviewRequest, true
+	if agentExampleDryRunJSONPattern.MatchString(capture.Output) && agentExampleDryRunInvocationPattern.MatchString(capture.Output) {
+		return contract.DryRunPreviewInvocation, true
+	}
+	if agentExampleDryRunJSONPattern.MatchString(capture.Output) {
+		return contract.DryRunPreviewRequest, true
 	}
 	if strings.Contains(normalized, "[dry-run]") {
-		return cli.DryRunPreviewInvocation, true
+		return contract.DryRunPreviewInvocation, true
 	}
 	if capture.DryRunChecks > 0 && strings.Contains(capture.Output, "操作:") {
-		return cli.DryRunPreviewPlan, true
+		return contract.DryRunPreviewPlan, true
 	}
 	return "", false
 }
 
-func TestManualAgentExampleDryRunEvidenceAcceptsSharedAndCommandPlans(t *testing.T) {
-	if !manualAgentExampleDryRunObserved(manualAgentExampleCapture{Output: "[DRY-RUN] Preview only, not executed:\nTool: calendar_list"}) {
+func TestAgentExampleDryRunEvidenceAcceptsSharedAndCommandPlans(t *testing.T) {
+	if !agentExampleDryRunObserved(agentExampleCapture{Output: "[DRY-RUN] Preview only, not executed:\nTool: calendar_list"}) {
 		t.Fatal("dry-run output with a Tool and nil Arguments was not recognized")
 	}
-	if manualAgentExampleDryRunObserved(manualAgentExampleCapture{Output: "Tool: calendar_list"}) {
+	if agentExampleDryRunObserved(agentExampleCapture{Output: "Tool: calendar_list"}) {
 		t.Fatal("a Tool line without dry-run evidence must not be accepted")
 	}
 	for _, falseEvidence := range []string{
@@ -419,28 +429,28 @@ func TestManualAgentExampleDryRunEvidenceAcceptsSharedAndCommandPlans(t *testing
 		"Run again with --dry-run to preview the operation",
 		`{"dry_run":false,"executed":true}`,
 	} {
-		if manualAgentExampleDryRunObserved(manualAgentExampleCapture{Output: falseEvidence}) {
+		if agentExampleDryRunObserved(agentExampleCapture{Output: falseEvidence}) {
 			t.Errorf("non-evidence text was mistaken for a successful dry-run: %q", falseEvidence)
 		}
 	}
 	operationSummary := "操作:             下载钉盘文件\n文件ID: test"
-	if manualAgentExampleDryRunObserved(manualAgentExampleCapture{Output: operationSummary}) {
+	if agentExampleDryRunObserved(agentExampleCapture{Output: operationSummary}) {
 		t.Fatal("a human-only operation summary without an audited dry-run check must not be accepted")
 	}
-	if !manualAgentExampleDryRunObserved(manualAgentExampleCapture{Output: operationSummary, DryRunChecks: 1}) {
+	if !agentExampleDryRunObserved(agentExampleCapture{Output: operationSummary, DryRunChecks: 1}) {
 		t.Fatal("a command plan guarded by the injected caller's dry-run check was not recognized")
 	}
 }
 
-func TestCrossPlatformCoverageManualAgentExampleDryRunEvidenceClassifiesStructuredPlan(t *testing.T) {
-	kind, observed := manualAgentExampleDryRunEvidence(manualAgentExampleCapture{
+func TestCrossPlatformCoverageAgentExampleDryRunEvidenceClassifiesStructuredPlan(t *testing.T) {
+	kind, observed := agentExampleDryRunEvidence(agentExampleCapture{
 		Output:       `{"dry_run":true,"executed":false,"preview_kind":"plan"}`,
 		DryRunChecks: 1,
 	})
-	if !observed || kind != cli.DryRunPreviewPlan {
+	if !observed || kind != contract.DryRunPreviewPlan {
 		t.Fatalf("structured plan classified as kind=%q observed=%v", kind, observed)
 	}
-	if manualAgentExampleDryRunObserved(manualAgentExampleCapture{
+	if agentExampleDryRunObserved(agentExampleCapture{
 		Output:       `{"dry_run":false,"executed":false,"preview_kind":"plan"}`,
 		DryRunChecks: 1,
 	}) {
@@ -448,7 +458,38 @@ func TestCrossPlatformCoverageManualAgentExampleDryRunEvidenceClassifiesStructur
 	}
 }
 
-func manualAgentExamplePromptObserved(output string) bool {
+func TestAgentExampleDryRunEvidenceClassifiesExecutorEnvelopeAsInvocation(t *testing.T) {
+	// Executor dry-run envelope: invocation at top level, the would-be request
+	// nested inside response — must classify as invocation, never request.
+	envelope := `{
+  "invocation": {"kind": "helper_invocation", "stage": "helper_override", "implemented": false,
+    "dry_run": true, "canonical_product": "devapp", "tool": "create_dev_app"},
+  "response": {"dry_run": true, "request": {"jsonrpc": "2.0", "method": "tools/call"},
+    "note": "execution skipped by --dry-run"}
+}`
+	kind, observed := agentExampleDryRunEvidence(agentExampleCapture{Output: envelope})
+	if !observed || kind != contract.DryRunPreviewInvocation {
+		t.Fatalf("executor envelope classified as kind=%q observed=%v, want invocation", kind, observed)
+	}
+	for _, invKind := range []string{"compat_invocation", "workflow_invocation", "connect_preview"} {
+		out := strings.Replace(envelope, "helper_invocation", invKind, 1)
+		if kind, ok := agentExampleDryRunEvidence(agentExampleCapture{Output: out}); !ok || kind != contract.DryRunPreviewInvocation {
+			t.Fatalf("kind %q envelope classified as %q/%v, want invocation", invKind, kind, ok)
+		}
+	}
+	// A bare MCP dry-run document has no invocation kind and stays request.
+	mcpDoc := `{"dry_run": true, "executed": false, "tool": "get_dev_app", "arguments": {}}`
+	if kind, ok := agentExampleDryRunEvidence(agentExampleCapture{Output: mcpDoc}); !ok || kind != contract.DryRunPreviewRequest {
+		t.Fatalf("bare MCP dry-run classified as %q/%v, want request", kind, ok)
+	}
+	// Plan still wins over an invocation-shaped payload.
+	planDoc := `{"dry_run": true, "preview_kind": "plan", "kind": "helper_invocation"}`
+	if kind, ok := agentExampleDryRunEvidence(agentExampleCapture{Output: planDoc}); !ok || kind != contract.DryRunPreviewPlan {
+		t.Fatalf("plan precedence broken: %q/%v", kind, ok)
+	}
+}
+
+func agentExamplePromptObserved(output string) bool {
 	normalized := strings.ToLower(output)
 	for _, marker := range []string{
 		"confirm ",
@@ -469,7 +510,7 @@ func manualAgentExamplePromptObserved(output string) bool {
 	return false
 }
 
-func TestManualAgentExamplePromptObservedRejectsInteractiveConfirmation(t *testing.T) {
+func TestAgentExamplePromptObservedRejectsInteractiveConfirmation(t *testing.T) {
 	for _, prompt := range []string{
 		"Confirm deletion? (yes/no):",
 		"Confirm action? (yes/no):",
@@ -480,11 +521,11 @@ func TestManualAgentExamplePromptObservedRejectsInteractiveConfirmation(t *testi
 		"Are you sure you want to continue?",
 		"Operation cancelled",
 	} {
-		if !manualAgentExamplePromptObserved(prompt) {
+		if !agentExamplePromptObserved(prompt) {
 			t.Errorf("interactive confirmation output was not detected: %q", prompt)
 		}
 	}
-	if manualAgentExamplePromptObserved(`{"dry_run":true,"confirmation":"user_required"}`) {
+	if agentExamplePromptObserved(`{"dry_run":true,"confirmation":"user_required"}`) {
 		t.Fatal("typed safety metadata was mistaken for an interactive prompt")
 	}
 }
@@ -498,26 +539,26 @@ func TestAitableAdvpermDisableDryRunSkipsConfirmationAndToolCall(t *testing.T) {
 		"aitable", "advperm", "disable",
 		"--base-id", "BASE_ID",
 	}
-	if manualAgentExampleHasFlag(args, "yes") {
+	if agentExampleHasFlag(args, "yes") {
 		t.Fatal("regression test must not bypass confirmation with --yes")
 	}
-	capture, err := executeManualAgentExampleCapture(t, args)
+	capture, err := executeAgentExampleCapture(t, args)
 	if err != nil {
 		t.Fatalf("advperm disable fail-closed dry-run failed: %v\noutput:\n%s", err, capture.Output)
 	}
-	if capture.StdinBytesRead != 0 || manualAgentExamplePromptObserved(capture.Output) {
+	if capture.StdinBytesRead != 0 || agentExamplePromptObserved(capture.Output) {
 		t.Fatalf("advperm disable dry-run entered confirmation (stdin bytes read: %d)\noutput:\n%s", capture.StdinBytesRead, capture.Output)
 	}
 	if capture.ToolCallAttempts != 0 {
 		t.Fatalf("advperm disable dry-run attempted %d real ToolCaller invocation(s)\noutput:\n%s", capture.ToolCallAttempts, capture.Output)
 	}
-	if !manualAgentExampleDryRunObserved(capture) {
+	if !agentExampleDryRunObserved(capture) {
 		t.Fatalf("advperm disable returned no audited dry-run evidence (caller dry-run checks: %d)\noutput:\n%s", capture.DryRunChecks, capture.Output)
 	}
 }
 
-func TestManualAgentExampleFailClosedCallerRecordsToolCalls(t *testing.T) {
-	caller := &manualAgentExampleFailClosedCaller{}
+func TestAgentExampleFailClosedCallerRecordsToolCalls(t *testing.T) {
+	caller := &agentExampleFailClosedCaller{}
 	if !caller.DryRun() {
 		t.Fatal("fail-closed caller must advertise dry-run mode")
 	}
@@ -532,7 +573,7 @@ func TestManualAgentExampleFailClosedCallerRecordsToolCalls(t *testing.T) {
 	}
 }
 
-func TestManualAgentExampleChatGroupMuteMemberUsesCommandDryRunPreview(t *testing.T) {
+func TestAgentExampleChatGroupMuteMemberUsesCommandDryRunPreview(t *testing.T) {
 	sandboxRoot := t.TempDir()
 	configDir := filepath.Join(sandboxRoot, "config")
 	if err := os.MkdirAll(configDir, 0o700); err != nil {
@@ -541,7 +582,7 @@ func TestManualAgentExampleChatGroupMuteMemberUsesCommandDryRunPreview(t *testin
 	setTestHome(t, sandboxRoot)
 	t.Setenv("DWS_CONFIG_DIR", configDir)
 
-	capture, err := executeManualAgentExampleCapture(t, []string{
+	capture, err := executeAgentExampleCapture(t, []string{
 		"--dry-run",
 		"chat", "group-mute-member",
 		"--group", "test_openConversationId",
@@ -557,10 +598,10 @@ func TestManualAgentExampleChatGroupMuteMemberUsesCommandDryRunPreview(t *testin
 	if capture.DryRunChecks == 0 {
 		t.Fatalf("group-mute-member did not enter its audited command dry-run path\noutput:\n%s", capture.Output)
 	}
-	if capture.StdinBytesRead != 0 || manualAgentExamplePromptObserved(capture.Output) {
+	if capture.StdinBytesRead != 0 || agentExamplePromptObserved(capture.Output) {
 		t.Fatalf("group-mute-member dry-run entered an interactive prompt (stdin bytes read: %d)\noutput:\n%s", capture.StdinBytesRead, capture.Output)
 	}
-	if !manualAgentExampleDryRunObserved(capture) {
+	if !agentExampleDryRunObserved(capture) {
 		t.Fatalf("group-mute-member returned no audited dry-run evidence\noutput:\n%s", capture.Output)
 	}
 	for _, expected := range []string{`"uids"`, `"userId1"`, `"userId2"`} {

internal/app/schema_agent_selection_contract_test.go

@@ -14,13 +14,12 @@
 package app
 
 import (
-	"os"
 	"testing"
 
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/cli"
 )
 
-func TestManualAgentSelectionScenariosCoverEveryExecutableSchemaTool(t *testing.T) {
+func TestAgentSelectionScenariosCoverEveryExecutableSchemaTool(t *testing.T) {
 	root := NewRootCommand()
 	effective, err := cli.BuildEffectiveCommandRegistry(root)
 	if err != nil {
@@ -30,14 +29,9 @@ func TestManualAgentSelectionScenariosCoverEveryExecutableSchemaTool(t *testing.
 	if err != nil {
 		t.Fatalf("BindEffectiveCommandRegistry() error = %v", err)
 	}
-	hints, err := cli.LoadAgentHintsFromSelectionForValidation(os.DirFS("../cli/schema_hints/selection"))
+	fixture, report, err := cli.BuildAgentSelectionEvalFixture(bound)
 	if err != nil {
-		t.Fatalf("LoadAgentHintsFromSelectionForValidation() error = %v", err)
-	}
-
-	fixture, report, err := cli.BuildManualAgentSelectionEvalFixture(bound, hints)
-	if err != nil {
-		t.Fatalf("BuildManualAgentSelectionEvalFixture() error = %v", err)
+		t.Fatalf("BuildAgentSelectionEvalFixture() error = %v", err)
 	}
 	if report.Tools != len(bound.Commands) {
 		t.Fatalf("selection tools = %d, bound commands = %d", report.Tools, len(bound.Commands))

internal/app/schema_agent_selection_live_test.go

@@ -31,42 +31,42 @@ import (
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/cli"
 )
 
-const manualAgentSelectionLiveBatchSize = 12
+const agentSelectionLiveBatchSize = 12
 
-type manualAgentSelectionLiveCandidate struct {
+type agentSelectionLiveCandidate struct {
 	CanonicalPath string   `json:"canonical_path"`
 	AgentSummary  string   `json:"agent_summary"`
 	UseWhen       []string `json:"use_when"`
 	AvoidWhen     []string `json:"avoid_when"`
 }
 
-type manualAgentSelectionLiveInput struct {
-	Cases      []manualAgentSelectionLiveCase      `json:"cases"`
-	Candidates []manualAgentSelectionLiveCandidate `json:"candidates"`
+type agentSelectionLiveInput struct {
+	Cases      []agentSelectionLiveCase      `json:"cases"`
+	Candidates []agentSelectionLiveCandidate `json:"candidates"`
 }
 
-// manualAgentSelectionLiveCase is deliberately answer-free. Expected and
+// agentSelectionLiveCase is deliberately answer-free. Expected and
 // forbidden canonicals stay only in the local assertion fixture and are never
 // sent to the model being evaluated.
-type manualAgentSelectionLiveCase struct {
+type agentSelectionLiveCase struct {
 	ID       string `json:"id"`
 	Scenario string `json:"scenario"`
 }
 
-type manualAgentSelectionLiveResult struct {
+type agentSelectionLiveResult struct {
 	ID            string `json:"id"`
 	CanonicalPath string `json:"canonical_path"`
 }
 
-type manualAgentSelectionLiveResponse struct {
-	Results []manualAgentSelectionLiveResult `json:"results"`
+type agentSelectionLiveResponse struct {
+	Results []agentSelectionLiveResult `json:"results"`
 }
 
-// TestManualAgentSelectionArkLive is intentionally opt-in. Deterministic CI
+// TestAgentSelectionArkLive is intentionally opt-in. Deterministic CI
 // validates all fixture and Cobra facts without network access; this test asks
 // a real model to interpret the reviewed natural-language scenarios. Set
 // DWS_AGENT_SELECTION_FULL=1 to evaluate every positive and negative case.
-func TestManualAgentSelectionArkLive(t *testing.T) {
+func TestAgentSelectionArkLive(t *testing.T) {
 	if os.Getenv("DWS_AGENT_SELECTION_LIVE") != "1" {
 		t.Skip("set DWS_AGENT_SELECTION_LIVE=1 and ARK_API_KEY/ARK_BASE_URL/ARK_MODEL to run live Agent command-selection evaluation")
 	}
@@ -82,47 +82,47 @@ func TestManualAgentSelectionArkLive(t *testing.T) {
 			t.Fatalf("%s is required when DWS_AGENT_SELECTION_LIVE=1", name)
 		}
 	}
-	if err := validateManualAgentSelectionLiveBaseURL(baseURL, os.Getenv("DWS_AGENT_SELECTION_ALLOWED_BASE_URLS")); err != nil {
+	if err := validateAgentSelectionLiveBaseURL(baseURL, os.Getenv("DWS_AGENT_SELECTION_ALLOWED_BASE_URLS")); err != nil {
 		t.Fatal(err)
 	}
 
-	fixture, hints := manualAgentSelectionLiveFixture(t)
-	cases := selectManualAgentSelectionLiveCases(t, fixture.Cases)
-	for _, batch := range batchManualAgentSelectionLiveCases(cases, manualAgentSelectionLiveBatchSize) {
+	fixture, selectionSet := agentSelectionLiveFixture(t)
+	cases := selectAgentSelectionLiveCases(t, fixture.Cases)
+	for _, batch := range batchAgentSelectionLiveCases(cases, agentSelectionLiveBatchSize) {
 		productID := batch[0].ProductID
-		t.Run(productID+"/"+sanitizeManualAgentSelectionLiveTestID(batch[0].ID), func(t *testing.T) {
-			input := buildManualAgentSelectionLiveInput(batch, hints)
-			results := callManualAgentSelectionLiveModel(t, baseURL, apiKey, model, input)
-			assertManualAgentSelectionLiveResults(t, batch, results)
+		t.Run(productID+"/"+sanitizeAgentSelectionLiveTestID(batch[0].ID), func(t *testing.T) {
+			input := buildAgentSelectionLiveInput(batch, selectionSet)
+			results := callAgentSelectionLiveModel(t, baseURL, apiKey, model, input)
+			assertAgentSelectionLiveResults(t, batch, results)
 		})
 	}
 }
 
-func buildManualAgentSelectionLiveInput(batch []cli.ManualAgentSelectionCase, hints cli.ManualAgentHintSet) manualAgentSelectionLiveInput {
-	input := manualAgentSelectionLiveInput{Cases: make([]manualAgentSelectionLiveCase, 0, len(batch))}
+func buildAgentSelectionLiveInput(batch []cli.AgentSelectionCase, selectionSet cli.FixtureAgentSelectionSet) agentSelectionLiveInput {
+	input := agentSelectionLiveInput{Cases: make([]agentSelectionLiveCase, 0, len(batch))}
 	if len(batch) == 0 {
 		return input
 	}
 	for _, selectionCase := range batch {
-		input.Cases = append(input.Cases, manualAgentSelectionLiveCase{
+		input.Cases = append(input.Cases, agentSelectionLiveCase{
 			ID:       selectionCase.ID,
 			Scenario: selectionCase.Scenario,
 		})
 	}
-	input.Candidates = make([]manualAgentSelectionLiveCandidate, 0, len(batch[0].CandidateCanonicals))
+	input.Candidates = make([]agentSelectionLiveCandidate, 0, len(batch[0].CandidateCanonicals))
 	for _, canonical := range batch[0].CandidateCanonicals {
-		hint := hints.Tools[canonical]
-		input.Candidates = append(input.Candidates, manualAgentSelectionLiveCandidate{
+		tool := selectionSet.Tools[canonical]
+		input.Candidates = append(input.Candidates, agentSelectionLiveCandidate{
 			CanonicalPath: canonical,
-			AgentSummary:  hint.AgentSummary,
-			UseWhen:       hint.UseWhen,
-			AvoidWhen:     hint.AvoidWhen,
+			AgentSummary:  tool.AgentSummary,
+			UseWhen:       tool.UseWhen,
+			AvoidWhen:     tool.AvoidWhen,
 		})
 	}
 	return input
 }
 
-func manualAgentSelectionLiveFixture(t testing.TB) (cli.ManualAgentSelectionFixture, cli.ManualAgentHintSet) {
+func agentSelectionLiveFixture(t testing.TB) (cli.AgentSelectionFixture, cli.FixtureAgentSelectionSet) {
 	t.Helper()
 	root := NewRootCommand()
 	effective, err := cli.BuildEffectiveCommandRegistry(root)
@@ -133,18 +133,14 @@ func manualAgentSelectionLiveFixture(t testing.TB) (cli.ManualAgentSelectionFixt
 	if err != nil {
 		t.Fatalf("BindEffectiveCommandRegistry() error = %v", err)
 	}
-	hints, err := cli.LoadAgentHintsFromSelectionForValidation(os.DirFS("../cli/schema_hints/selection"))
+	fixture, _, err := cli.BuildAgentSelectionEvalFixture(bound)
 	if err != nil {
-		t.Fatalf("LoadAgentHintsFromSelectionForValidation() error = %v", err)
+		t.Fatalf("BuildAgentSelectionEvalFixture() error = %v", err)
 	}
-	fixture, _, err := cli.BuildManualAgentSelectionEvalFixture(bound, hints)
-	if err != nil {
-		t.Fatalf("BuildManualAgentSelectionEvalFixture() error = %v", err)
-	}
-	return fixture, hints
+	return fixture, cli.FixtureAgentSelectionSet{}
 }
 
-func selectManualAgentSelectionLiveCases(t testing.TB, cases []cli.ManualAgentSelectionCase) []cli.ManualAgentSelectionCase {
+func selectAgentSelectionLiveCases(t testing.TB, cases []cli.AgentSelectionCase) []cli.AgentSelectionCase {
 	t.Helper()
 	if raw := strings.TrimSpace(os.Getenv("DWS_AGENT_SELECTION_CASES")); raw != "" {
 		selected := map[string]bool{}
@@ -153,7 +149,7 @@ func selectManualAgentSelectionLiveCases(t testing.TB, cases []cli.ManualAgentSe
 				selected[id] = true
 			}
 		}
-		result := make([]cli.ManualAgentSelectionCase, 0, len(selected))
+		result := make([]cli.AgentSelectionCase, 0, len(selected))
 		for _, selectionCase := range cases {
 			if selected[selectionCase.ID] {
 				result = append(result, selectionCase)
@@ -171,13 +167,13 @@ func selectManualAgentSelectionLiveCases(t testing.TB, cases []cli.ManualAgentSe
 		return result
 	}
 	if os.Getenv("DWS_AGENT_SELECTION_FULL") == "1" {
-		return append([]cli.ManualAgentSelectionCase(nil), cases...)
+		return append([]cli.AgentSelectionCase(nil), cases...)
 	}
 
 	// Smoke mode exercises one positive and one negative scenario per product.
 	seenPositive := map[string]bool{}
 	seenNegative := map[string]bool{}
-	result := make([]cli.ManualAgentSelectionCase, 0)
+	result := make([]cli.AgentSelectionCase, 0)
 	for _, selectionCase := range cases {
 		if selectionCase.ExpectedCanonical != "" && !seenPositive[selectionCase.ProductID] {
 			seenPositive[selectionCase.ProductID] = true
@@ -191,11 +187,11 @@ func selectManualAgentSelectionLiveCases(t testing.TB, cases []cli.ManualAgentSe
 	return result
 }
 
-func batchManualAgentSelectionLiveCases(cases []cli.ManualAgentSelectionCase, batchSize int) [][]cli.ManualAgentSelectionCase {
+func batchAgentSelectionLiveCases(cases []cli.AgentSelectionCase, batchSize int) [][]cli.AgentSelectionCase {
 	if batchSize <= 0 {
 		batchSize = 1
 	}
-	grouped := map[string][]cli.ManualAgentSelectionCase{}
+	grouped := map[string][]cli.AgentSelectionCase{}
 	products := make([]string, 0)
 	for _, selectionCase := range cases {
 		if _, ok := grouped[selectionCase.ProductID]; !ok {
@@ -204,7 +200,7 @@ func batchManualAgentSelectionLiveCases(cases []cli.ManualAgentSelectionCase, ba
 		grouped[selectionCase.ProductID] = append(grouped[selectionCase.ProductID], selectionCase)
 	}
 	sort.Strings(products)
-	result := make([][]cli.ManualAgentSelectionCase, 0)
+	result := make([][]cli.AgentSelectionCase, 0)
 	for _, productID := range products {
 		productCases := grouped[productID]
 		for start := 0; start < len(productCases); start += batchSize {
@@ -212,15 +208,15 @@ func batchManualAgentSelectionLiveCases(cases []cli.ManualAgentSelectionCase, ba
 			if end > len(productCases) {
 				end = len(productCases)
 			}
-			result = append(result, append([]cli.ManualAgentSelectionCase(nil), productCases[start:end]...))
+			result = append(result, append([]cli.AgentSelectionCase(nil), productCases[start:end]...))
 		}
 	}
 	return result
 }
 
-func callManualAgentSelectionLiveModel(t testing.TB, baseURL, apiKey, model string, input manualAgentSelectionLiveInput) []manualAgentSelectionLiveResult {
+func callAgentSelectionLiveModel(t testing.TB, baseURL, apiKey, model string, input agentSelectionLiveInput) []agentSelectionLiveResult {
 	t.Helper()
-	body, err := marshalManualAgentSelectionLiveRequest(baseURL, model, input)
+	body, err := marshalAgentSelectionLiveRequest(baseURL, model, input)
 	if err != nil {
 		t.Fatalf("marshal live selection request: %v", err)
 	}
@@ -260,7 +256,7 @@ func callManualAgentSelectionLiveModel(t testing.TB, baseURL, apiKey, model stri
 	if len(envelope.Choices) == 0 || strings.TrimSpace(envelope.Choices[0].Message.Content) == "" {
 		t.Fatal("live selection response has no model content")
 	}
-	var selection manualAgentSelectionLiveResponse
+	var selection agentSelectionLiveResponse
 	decoder := json.NewDecoder(strings.NewReader(envelope.Choices[0].Message.Content))
 	decoder.DisallowUnknownFields()
 	if err := decoder.Decode(&selection); err != nil {
@@ -269,7 +265,7 @@ func callManualAgentSelectionLiveModel(t testing.TB, baseURL, apiKey, model stri
 	return selection.Results
 }
 
-func marshalManualAgentSelectionLiveRequest(baseURL, model string, input manualAgentSelectionLiveInput) ([]byte, error) {
+func marshalAgentSelectionLiveRequest(baseURL, model string, input agentSelectionLiveInput) ([]byte, error) {
 	inputJSON, err := json.Marshal(input)
 	if err != nil {
 		return nil, fmt.Errorf("marshal live selection input: %w", err)
@@ -294,9 +290,9 @@ func marshalManualAgentSelectionLiveRequest(baseURL, model string, input manualA
 	return json.Marshal(requestBody)
 }
 
-func assertManualAgentSelectionLiveResults(t testing.TB, cases []cli.ManualAgentSelectionCase, results []manualAgentSelectionLiveResult) {
+func assertAgentSelectionLiveResults(t testing.TB, cases []cli.AgentSelectionCase, results []agentSelectionLiveResult) {
 	t.Helper()
-	byID := make(map[string]manualAgentSelectionLiveResult, len(results))
+	byID := make(map[string]agentSelectionLiveResult, len(results))
 	for _, result := range results {
 		if _, exists := byID[result.ID]; exists {
 			t.Fatalf("live selection returned duplicate case ID %q", result.ID)
@@ -315,7 +311,7 @@ func assertManualAgentSelectionLiveResults(t testing.TB, cases []cli.ManualAgent
 			t.Errorf("live selection returned empty canonical for %q", selectionCase.ID)
 			continue
 		}
-		if selected != "none" && !containsManualAgentSelectionCanonical(selectionCase.CandidateCanonicals, selected) {
+		if selected != "none" && !containsAgentSelectionCanonical(selectionCase.CandidateCanonicals, selected) {
 			t.Errorf("live selection returned non-candidate %q for %q", selected, selectionCase.ID)
 			continue
 		}
@@ -336,13 +332,13 @@ func assertManualAgentSelectionLiveResults(t testing.TB, cases []cli.ManualAgent
 	}
 }
 
-func validateManualAgentSelectionLiveBaseURL(raw, extraAllowed string) error {
+func validateAgentSelectionLiveBaseURL(raw, extraAllowed string) error {
 	parsed, err := url.Parse(raw)
 	if err != nil || parsed.Scheme == "" || parsed.Host == "" || parsed.RawQuery != "" || parsed.Fragment != "" || parsed.User != nil {
 		return fmt.Errorf("ARK_BASE_URL must be an absolute HTTP(S) API base without query or fragment")
 	}
 	if parsed.Scheme == "http" {
-		if !manualAgentSelectionLoopbackHost(parsed.Hostname()) {
+		if !agentSelectionLiveLoopbackHost(parsed.Hostname()) {
 			return fmt.Errorf("ARK_BASE_URL may use plaintext HTTP only for a loopback test endpoint")
 		}
 		return nil
@@ -367,7 +363,7 @@ func validateManualAgentSelectionLiveBaseURL(raw, extraAllowed string) error {
 	return nil
 }
 
-func manualAgentSelectionLoopbackHost(host string) bool {
+func agentSelectionLiveLoopbackHost(host string) bool {
 	if strings.EqualFold(strings.TrimSpace(host), "localhost") {
 		return true
 	}
@@ -375,7 +371,7 @@ func manualAgentSelectionLoopbackHost(host string) bool {
 	return ip != nil && ip.IsLoopback()
 }
 
-func containsManualAgentSelectionCanonical(values []string, target string) bool {
+func containsAgentSelectionCanonical(values []string, target string) bool {
 	for _, value := range values {
 		if value == target {
 			return true
@@ -384,36 +380,36 @@ func containsManualAgentSelectionCanonical(values []string, target string) bool
 	return false
 }
 
-func sanitizeManualAgentSelectionLiveTestID(value string) string {
+func sanitizeAgentSelectionLiveTestID(value string) string {
 	value = strings.ReplaceAll(value, ".", "_")
 	value = strings.ReplaceAll(value, "/", "_")
 	return value
 }
 
-func TestManualAgentSelectionLiveResultContract(t *testing.T) {
-	cases := []cli.ManualAgentSelectionCase{
+func TestAgentSelectionLiveResultContract(t *testing.T) {
+	cases := []cli.AgentSelectionCase{
 		{ID: "sample.search/use_when/0", Scenario: "find an item", ExpectedCanonical: "sample.search", CandidateCanonicals: []string{"sample.create", "sample.search"}},
 		{ID: "sample.search/avoid_when/0", Scenario: "create an item", ForbiddenCanonical: "sample.search", CandidateCanonicals: []string{"sample.create", "sample.search"}},
 	}
 	t.Run("accepts exact positive and negative choices", func(t *testing.T) {
-		assertManualAgentSelectionLiveResults(t, cases, []manualAgentSelectionLiveResult{
+		assertAgentSelectionLiveResults(t, cases, []agentSelectionLiveResult{
 			{ID: cases[0].ID, CanonicalPath: "sample.search"},
 			{ID: cases[1].ID, CanonicalPath: "sample.create"},
 		})
 	})
 }
 
-func TestManualAgentSelectionLiveInputDoesNotLeakAssertionsOrRepeatCandidates(t *testing.T) {
-	batch := []cli.ManualAgentSelectionCase{
+func TestAgentSelectionLiveInputDoesNotLeakAssertionsOrRepeatCandidates(t *testing.T) {
+	batch := []cli.AgentSelectionCase{
 		{ID: "sample.search/use_when/0", Scenario: "find an item", ExpectedCanonical: "sample.search", CandidateCanonicals: []string{"sample.create", "sample.search"}},
 		{ID: "sample.search/avoid_when/0", Scenario: "create an item", ForbiddenCanonical: "sample.search", CandidateCanonicals: []string{"sample.create", "sample.search"}},
 	}
-	hints := cli.ManualAgentHintSet{Tools: map[string]cli.ManualAgentToolHint{
+	selectionSet := cli.FixtureAgentSelectionSet{Tools: map[string]cli.AgentToolSelection{
 		"sample.create": {AgentSummary: "Create an item", UseWhen: []string{"create"}, AvoidWhen: []string{"find"}},
 		"sample.search": {AgentSummary: "Search items", UseWhen: []string{"find"}, AvoidWhen: []string{"create"}},
 	}}
-	input := buildManualAgentSelectionLiveInput(batch, hints)
-	data, err := marshalManualAgentSelectionLiveRequest("https://ark.cn-beijing.volces.com/api/plan/v3", "fixed-model", input)
+	input := buildAgentSelectionLiveInput(batch, selectionSet)
+	data, err := marshalAgentSelectionLiveRequest("https://ark.cn-beijing.volces.com/api/plan/v3", "fixed-model", input)
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -430,7 +426,7 @@ func TestManualAgentSelectionLiveInputDoesNotLeakAssertionsOrRepeatCandidates(t
 	}
 }
 
-func TestValidateManualAgentSelectionLiveBaseURL(t *testing.T) {
+func TestValidateAgentSelectionLiveBaseURL(t *testing.T) {
 	tests := []struct {
 		name         string
 		baseURL      string
@@ -450,7 +446,7 @@ func TestValidateManualAgentSelectionLiveBaseURL(t *testing.T) {
 	}
 	for _, test := range tests {
 		t.Run(test.name, func(t *testing.T) {
-			err := validateManualAgentSelectionLiveBaseURL(test.baseURL, test.extraAllowed)
+			err := validateAgentSelectionLiveBaseURL(test.baseURL, test.extraAllowed)
 			if test.wantErr == "" {
 				if err != nil {
 					t.Fatalf("validate base URL: %v", err)

internal/app/schema_completeness_test.go

@@ -10,12 +10,12 @@ import (
 )
 
 func TestRuntimeSchemaCompletenessCoversPublicCommandTree(t *testing.T) {
-	exclusions, err := cli.EmbeddedRuntimeSchemaExclusions()
+	exclusions, err := cli.ReviewedRuntimeSchemaExclusions()
 	if err != nil {
 		t.Fatal(err)
 	}
 	root := NewSchemaSourceRootCommand()
-	if err := cli.ValidateEmbeddedRuntimeSchemaCompleteness(root); err != nil {
+	if err := cli.ValidateRuntimeSchemaCompleteness(root); err != nil {
 		t.Fatal(err)
 	}
 	report := cli.RuntimeSchemaCompleteness(root, exclusions)

internal/app/schema_contract_test.go

@@ -45,7 +45,7 @@ func fullSchemaSnapshotForTest(t testing.TB) cli.SchemaCatalogSnapshot {
 	return fullSchemaSnapshot
 }
 
-func TestEmbeddedSchemaContractMapsToExecutableTree(t *testing.T) {
+func TestDeliverySchemaContractMapsToExecutableTree(t *testing.T) {
 	root := NewRootCommand()
 	effective, err := cli.BuildEffectiveCommandRegistry(root)
 	if err != nil {
@@ -63,7 +63,7 @@ func TestEmbeddedSchemaContractMapsToExecutableTree(t *testing.T) {
 	root.SetErr(&stderr)
 	root.SetArgs([]string{"schema", "--all", "--format", "json"})
 	if err := root.Execute(); err != nil {
-		t.Fatalf("execute embedded schema --all: %v; stderr=%s", err, stderr.String())
+		t.Fatalf("execute delivery schema --all: %v; stderr=%s", err, stderr.String())
 	}
 	var payload struct {
 		Products []struct {
@@ -73,7 +73,7 @@ func TestEmbeddedSchemaContractMapsToExecutableTree(t *testing.T) {
 		} `json:"products"`
 	}
 	if err := json.Unmarshal(stdout.Bytes(), &payload); err != nil {
-		t.Fatalf("decode embedded schema --all: %v", err)
+		t.Fatalf("decode delivery schema --all: %v", err)
 	}
 	actual := make(map[string]bool)
 	var duplicates []string
@@ -81,7 +81,7 @@ func TestEmbeddedSchemaContractMapsToExecutableTree(t *testing.T) {
 		for _, tool := range product.Tools {
 			canonical := strings.TrimSpace(tool.CanonicalPath)
 			if canonical == "" {
-				t.Fatal("embedded schema --all contains an empty canonical path")
+				t.Fatal("delivery schema --all contains an empty canonical path")
 			}
 			if actual[canonical] {
 				duplicates = append(duplicates, canonical)
@@ -91,7 +91,7 @@ func TestEmbeddedSchemaContractMapsToExecutableTree(t *testing.T) {
 	}
 	if len(duplicates) > 0 {
 		sort.Strings(duplicates)
-		t.Fatalf("embedded schema --all contains duplicate canonicals: %v", duplicates)
+		t.Fatalf("delivery schema --all contains duplicate canonicals: %v", duplicates)
 	}
 
 	var missing, extra []string
@@ -108,16 +108,16 @@ func TestEmbeddedSchemaContractMapsToExecutableTree(t *testing.T) {
 	if len(missing) > 0 || len(extra) > 0 {
 		sort.Strings(missing)
 		sort.Strings(extra)
-		t.Fatalf("embedded Schema canonical set differs from EffectiveCommandRegistry: missing=%v extra=%v", missing, extra)
+		t.Fatalf("runtime-assembled Schema canonical set differs from EffectiveCommandRegistry: missing=%v extra=%v", missing, extra)
 	}
 }
 
 func TestGeneratedSchemaContractMapsToExecutableTree(t *testing.T) {
 	root := NewRootCommand()
 	snapshot := fullSchemaSnapshotForTest(t)
-	bindings, err := cli.EmbeddedSchemaParameterBindings()
+	bindings, err := cli.LoadSchemaParameterBindings()
 	if err != nil {
-		t.Fatalf("EmbeddedSchemaParameterBindings() error = %v", err)
+		t.Fatalf("LoadSchemaParameterBindings() error = %v", err)
 	}
 	if len(snapshot.Tools) == 0 {
 		t.Fatal("generated Schema Catalog contains no tools")
@@ -370,9 +370,6 @@ func schemaContractStringSlice(value any) []string {
 // delivered set must always equal the public EffectiveCommandRegistry set.
 func schemaContractPayloadForBoundCanonicals(t *testing.T, root *cobra.Command, canonicals ...string) cli.SchemaSnapshotPayload {
 	t.Helper()
-	if _, err := cli.ApplyEmbeddedManualSchemaHints(root); err != nil {
-		t.Fatalf("apply manual Schema hints: %v", err)
-	}
 	effective, err := cli.BuildEffectiveCommandRegistry(root)
 	if err != nil {
 		t.Fatalf("build effective CommandRegistry: %v", err)
@@ -458,14 +455,14 @@ func TestPromptingWritesRequireUserConfirmation(t *testing.T) {
 		"sheet.delete_pivot_table": "medium",
 	}
 	wantSources := map[string]string{
-		"attendance.class_create":  "internal/cli/schema_hints/metadata/attendance.json",
-		"attendance.class_update":  "internal/cli/schema_hints/metadata/attendance.json",
-		"doc.delete_comment":       "internal/cli/schema_hints/metadata/doc.json",
-		"doc.version_revert":       "internal/cli/schema_hints/metadata/doc.json",
-		"drive.publish_set":        "internal/cli/schema_hints/metadata/drive.json",
-		"drive.publish_unset":      "internal/cli/schema_hints/metadata/drive.json",
-		"sheet.chart_delete":       "internal/cli/schema_hints/metadata/sheet.json",
-		"sheet.delete_pivot_table": "internal/cli/schema_hints/metadata/sheet.json",
+		"attendance.class_create":  "corecmd.contract",
+		"attendance.class_update":  "corecmd.contract",
+		"doc.delete_comment":       "corecmd.contract",
+		"doc.version_revert":       "corecmd.contract",
+		"drive.publish_set":        "corecmd.contract",
+		"drive.publish_unset":      "corecmd.contract",
+		"sheet.chart_delete":       "corecmd.contract",
+		"sheet.delete_pivot_table": "corecmd.contract",
 	}
 	canonicals := make([]string, 0, len(wantEffects))
 	for canonical := range wantEffects {

internal/app/schema_help_flag_completeness_test.go

@@ -19,11 +19,11 @@ import (
 
 // TestFinalSchemaParametersMatchExecutableHelpFlags is the fast, in-process
 // Help <-> Schema parameter completeness gate. It deliberately starts from the
-// reviewed registry and its exact Cobra bindings, then compares every public
-// primary leaf with the final delivered ToolSpec projection. The binder has
-// already proved that reviewed compatibility leaves have the same executable
-// contract as their primary, so aliases do not create a second parameter
-// source here.
+// collected command identity and its exact Cobra bindings, then compares
+// every public primary leaf with the final delivered ToolSpec projection. The
+// binder has already proved that compatibility aliases of a leaf share the
+// same executable contract as their primary, so aliases do not create a
+// second parameter source here.
 func TestFinalSchemaParametersMatchExecutableHelpFlags(t *testing.T) {
 	root := NewRootCommand()
 	bound := boundSchemaCommandsForHelpFlagTest(t, root)
@@ -31,15 +31,15 @@ func TestFinalSchemaParametersMatchExecutableHelpFlags(t *testing.T) {
 	assertSchemaParametersMatchExecutableHelpFlags(t, bound, snapshot.Tools, "source-built final Schema")
 }
 
-// TestEmbeddedSchemaParametersMatchExecutableHelpFlags runs the same exact-set
+// TestDeliverySchemaParametersMatchExecutableHelpFlags runs the same exact-set
 // gate against the artifact that ships in the binary. Going through the real
 // schema --all command is intentional: a stale generated Catalog must fail
 // even when a fresh source-built snapshot would agree with Cobra Help.
-func TestEmbeddedSchemaParametersMatchExecutableHelpFlags(t *testing.T) {
+func TestDeliverySchemaParametersMatchExecutableHelpFlags(t *testing.T) {
 	root := NewRootCommand()
 	bound := boundSchemaCommandsForHelpFlagTest(t, root)
-	tools := embeddedSchemaAllToolsForHelpFlagTest(t, root)
-	assertSchemaParametersMatchExecutableHelpFlags(t, bound, tools, "embedded schema --all")
+	tools := deliverySchemaAllToolsForHelpFlagTest(t, root)
+	assertSchemaParametersMatchExecutableHelpFlags(t, bound, tools, "delivery schema --all")
 }
 
 func boundSchemaCommandsForHelpFlagTest(t testing.TB, root *cobra.Command) cli.BoundCommandRegistry {
@@ -55,14 +55,14 @@ func boundSchemaCommandsForHelpFlagTest(t testing.TB, root *cobra.Command) cli.B
 	return bound
 }
 
-func embeddedSchemaAllToolsForHelpFlagTest(t testing.TB, root *cobra.Command) map[string]map[string]any {
+func deliverySchemaAllToolsForHelpFlagTest(t testing.TB, root *cobra.Command) map[string]map[string]any {
 	t.Helper()
 	var stdout, stderr bytes.Buffer
 	root.SetOut(&stdout)
 	root.SetErr(&stderr)
 	root.SetArgs([]string{"schema", "--all", "--format", "json"})
 	if err := root.Execute(); err != nil {
-		t.Fatalf("execute embedded schema --all: %v; stderr=%s", err, stderr.String())
+		t.Fatalf("execute delivery schema --all: %v; stderr=%s", err, stderr.String())
 	}
 	var payload struct {
 		Products []struct {
@@ -70,23 +70,23 @@ func embeddedSchemaAllToolsForHelpFlagTest(t testing.TB, root *cobra.Command) ma
 		} `json:"products"`
 	}
 	if err := json.Unmarshal(stdout.Bytes(), &payload); err != nil {
-		t.Fatalf("decode embedded schema --all: %v", err)
+		t.Fatalf("decode delivery schema --all: %v", err)
 	}
 	tools := make(map[string]map[string]any)
 	for _, product := range payload.Products {
 		for _, tool := range product.Tools {
 			canonical := strings.TrimSpace(schemaContractString(tool["canonical_path"]))
 			if canonical == "" {
-				t.Fatal("embedded schema --all contains an empty canonical path")
+				t.Fatal("delivery schema --all contains an empty canonical path")
 			}
 			if _, exists := tools[canonical]; exists {
-				t.Fatalf("embedded schema --all contains duplicate canonical %q", canonical)
+				t.Fatalf("delivery schema --all contains duplicate canonical %q", canonical)
 			}
 			tools[canonical] = tool
 		}
 	}
 	if len(tools) == 0 {
-		t.Fatal("embedded schema --all contains no tools")
+		t.Fatal("delivery schema --all contains no tools")
 	}
 	return tools
 }

internal/app/schema_identity_collect_probe_test.go

@@ -0,0 +1,68 @@
+// 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 (
+	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/cli"
+)
+
+// TestCollectedIdentityIsValidSingleSource is the standing gate for the
+// retired reviewed registry: command identity collected from live Cobra
+// leaves carrying ContractFinal.Identity must be a valid single source for
+// EffectiveCommandRegistry assembly. It asserts the collector returns a
+// non-empty spec set with no missing primaries, builds an effective registry
+// from it, and produces a stable SourceHash across repeated collection walks.
+func TestCrossPlatformCoverageCollectedIdentityIsValidSingleSource(t *testing.T) {
+	root := NewRootCommand()
+	collected, report, err := cli.CollectIdentitySpecs(root)
+	if err != nil {
+		t.Fatalf("collect identity specs: %v", err)
+	}
+	if len(collected) == 0 {
+		t.Fatal("identity collection returned no command specs")
+	}
+	if len(report.MissingPrimary) != 0 {
+		t.Fatalf("identity collection reported missing primaries: %v", report.MissingPrimary)
+	}
+
+	t.Logf("walk leaves=%d withIdentity=%d hiddenPrimaries=%d excluded=%d noIdentity=%d collected=%d",
+		report.Leaves, report.WithIdentity, report.HiddenPrimaries, report.Excluded, len(report.NoIdentity), len(collected))
+	for _, leaf := range report.NoIdentity {
+		t.Logf("NO_IDENTITY_LEAF %s", leaf)
+	}
+
+	effective, err := cli.BuildEffectiveFromSpecs(collected)
+	if err != nil {
+		t.Fatalf("build effective registry from collected specs: %v", err)
+	}
+	sourceHash := effective.SourceHash()
+	t.Logf("collected SourceHash=%s commands=%d", sourceHash, len(effective.Commands))
+	if sourceHash == "" {
+		t.Fatal("effective registry SourceHash is empty")
+	}
+
+	collectedAgain, _, err := cli.CollectIdentitySpecs(root)
+	if err != nil {
+		t.Fatalf("re-collect identity specs: %v", err)
+	}
+	effectiveAgain, err := cli.BuildEffectiveFromSpecs(collectedAgain)
+	if err != nil {
+		t.Fatalf("rebuild effective registry from collected specs: %v", err)
+	}
+	if got := effectiveAgain.SourceHash(); got != sourceHash {
+		t.Fatalf("collected identity SourceHash is not stable across walks: %q vs %q", got, sourceHash)
+	}
+}

internal/app/schema_interface_disposition_contract_test.go

@@ -5,74 +5,66 @@
 package app
 
 import (
-	"encoding/json"
-	"os"
 	"sort"
-	"strings"
 	"testing"
 )
 
 func TestReviewedRoutedInterfacesReachFinalSchema(t *testing.T) {
 	type interfaceCase struct {
-		canonical    string
-		mode         string
-		reason       string
-		sourceSuffix string
+		canonical string
+		mode      string
+		reason    string
 	}
 	tests := []interfaceCase{
 		{
-			canonical:    "attendance.get_attendance_summary",
-			mode:         "composite",
-			reason:       "Reviewed unpinned remote adapter: the CLI calls attendance-wukong/get_user_attendance_summary, which is absent from the pinned MCP metadata snapshot; the incompatible attendance/get_attendance_summary contract must not be advertised.",
-			sourceSuffix: "internal/cli/schema_hints/metadata/attendance.json",
+			canonical: "attendance.get_attendance_summary",
+			mode:      "composite",
+			reason:    "Reviewed unpinned remote adapter: the CLI calls attendance-wukong/get_user_attendance_summary, which is absent from the pinned MCP metadata snapshot; the incompatible attendance/get_attendance_summary contract must not be advertised.",
 		},
 		{
-			canonical:    "drive.list_files",
-			mode:         "composite",
-			reason:       "The CLI command routes by --workspace between drive/list_files and doc/list_nodes, so the reviewed executable wrapper has no single direct MCP interface.",
-			sourceSuffix: "internal/cli/schema_hints/metadata/drive.json",
+			canonical: "drive.list_files",
+			mode:      "composite",
+			reason:    "The CLI command routes by --workspace between drive/list_files and doc/list_nodes, so the reviewed executable wrapper has no single direct MCP interface.",
 		},
 		{
-			canonical:    "chat.search_groups",
-			mode:         "composite",
-			reason:       "Reviewed unpinned remote adapter: the CLI calls im/search_groups with a flat payload, while the pinned snapshot only contains the incompatible chat/search_groups_by_keyword contract.",
-			sourceSuffix: "internal/cli/schema_hints/metadata/chat.json",
+			canonical: "chat.search_groups",
+			mode:      "composite",
+			reason:    "Reviewed unpinned remote adapter: the CLI calls im/search_groups with a flat payload, while the pinned snapshot only contains the incompatible chat/search_groups_by_keyword contract.",
 		},
 		{
-			canonical:    "sheet.range_batch_set_style",
-			mode:         "composite",
-			reason:       "The CLI reads a local batch file and performs multiple sheet/update_range calls with local continue-on-error control; the workflow has no single direct MCP interface.",
-			sourceSuffix: "internal/cli/schema_hints/metadata/sheet.json",
+			canonical: "sheet.range_batch_set_style",
+			mode:      "composite",
+			reason:    "The CLI assembles style cell matrices locally from --ranges or a local batch file and submits them as one sheet/batch_update operations array; no single direct MCP interface represents the wrapper input shape.",
 		},
 		{
-			canonical:    "sheet.range_read",
-			mode:         "composite",
-			reason:       "Reviewed unpinned remote adapter: the CLI calls sheet/get_cell_infos, which is absent from the pinned MCP metadata snapshot; the incompatible sheet/get_range contract must not be advertised.",
-			sourceSuffix: "internal/cli/schema_hints/metadata/sheet.json",
+			canonical: "sheet.create_with_data",
+			mode:      "composite",
+			reason:    "Reviewed composite workflow: the command calls sheet/create_workspace_sheet, waits for the new document to become writable, resolves the default worksheet, writes the initial data through sheet/set_range_from_csv or sheet/table_put, reads it back with sheet/get_range_as_csv, and optionally applies sheet/set_cell_range, sheet/update_dimension and sheet/merge_cells; no single pinned RPC represents the workflow.",
 		},
 		{
-			canonical:    "wiki.list_wikiSpaces",
-			mode:         "composite",
-			reason:       "The CLI command routes by --type between wiki/list_wikiSpaces and drive/list_spaces, so the reviewed executable wrapper has no single direct MCP interface.",
-			sourceSuffix: "internal/cli/schema_hints/metadata/wiki.json",
+			canonical: "sheet.range_read",
+			mode:      "composite",
+			reason:    "Reviewed unpinned remote adapter: the CLI calls sheet/get_cell_infos, which is absent from the pinned MCP metadata snapshot; the incompatible sheet/get_range contract must not be advertised.",
 		},
 		{
-			canonical:    "event.consume",
-			mode:         "composite",
-			reason:       "Reviewed composite workflow: the command creates or reuses a remote personal-event subscription and coordinates the local event bus and Stream consumer; no single pinned RPC represents the workflow.",
-			sourceSuffix: "internal/cli/schema_hints/metadata/event.json",
+			canonical: "wiki.list_wikiSpaces",
+			mode:      "composite",
+			reason:    "The CLI command routes by --type between wiki/list_wikiSpaces and drive/list_spaces, so the reviewed executable wrapper has no single direct MCP interface.",
 		},
 		{
-			canonical:    "event.status",
-			mode:         "composite",
-			reason:       "Reviewed composite workflow: the command reads the remote personal-event subscription control plane and combines it with local bus and consumer state; no single pinned RPC represents the result.",
-			sourceSuffix: "internal/cli/schema_hints/metadata/event.json",
+			canonical: "event.consume",
+			mode:      "composite",
+			reason:    "Reviewed composite workflow: the command creates or reuses a remote personal-event subscription and coordinates the local event bus and Stream consumer; no single pinned RPC represents the workflow.",
 		},
 		{
-			canonical:    "event.stop",
-			mode:         "composite",
-			reason:       "Reviewed composite workflow: the command deletes remote personal-event subscriptions, interrupts local consumers, updates local state, and may stop the local bus; no single pinned RPC represents the workflow.",
-			sourceSuffix: "internal/cli/schema_hints/metadata/event.json",
+			canonical: "event.status",
+			mode:      "composite",
+			reason:    "Reviewed composite workflow: the command reads the remote personal-event subscription control plane and combines it with local bus and consumer state; no single pinned RPC represents the result.",
+		},
+		{
+			canonical: "event.stop",
+			mode:      "composite",
+			reason:    "Reviewed composite workflow: the command deletes remote personal-event subscriptions, interrupts local consumers, updates local state, and may stop the local bus; no single pinned RPC represents the workflow.",
 		},
 	}
 	for _, canonical := range []string{
@@ -82,10 +74,9 @@ func TestReviewedRoutedInterfacesReachFinalSchema(t *testing.T) {
 		"aitable.view_update_timebar",
 	} {
 		tests = append(tests, interfaceCase{
-			canonical:    canonical,
-			mode:         "composite",
-			reason:       "The CLI performs an aitable/get_views preflight, locally transforms the requested configuration, and then calls aitable/update_view; the two-call workflow has no single direct MCP interface.",
-			sourceSuffix: "internal/cli/schema_hints/metadata/aitable.json",
+			canonical: canonical,
+			mode:      "composite",
+			reason:    "The CLI performs an aitable/get_views preflight, locally transforms the requested configuration, and then calls aitable/update_view; the two-call workflow has no single direct MCP interface.",
 		})
 	}
 
@@ -119,11 +110,11 @@ func TestReviewedRoutedInterfacesReachFinalSchema(t *testing.T) {
 					t.Errorf("missing %s provenance", field)
 					continue
 				}
-				if got := schemaContractString(entry["precedence"]); got != "reviewed_explicit" {
-					t.Errorf("%s provenance precedence = %q, want reviewed_explicit", field, got)
+				if got := schemaContractString(entry["precedence"]); got != "contract_final" {
+					t.Errorf("%s provenance precedence = %q, want contract_final", field, got)
 				}
-				if got := schemaContractString(entry["source"]); !strings.HasSuffix(got, test.sourceSuffix) {
-					t.Errorf("%s provenance source = %q, want suffix %q", field, got, test.sourceSuffix)
+				if got := schemaContractString(entry["source"]); got != "corecmd.contract" {
+					t.Errorf("%s provenance source = %q, want corecmd.contract", field, got)
 				}
 			}
 			if got := provenance["interface_ref"]["value"]; got != nil {
@@ -174,151 +165,81 @@ func TestViewGetWrappersUsePinnedGetViewsInterface(t *testing.T) {
 		provenance := schemaContractMap(tool["field_provenance"])
 		for _, field := range []string{"interface_mode", "availability", "interface_ref"} {
 			entry := provenance[field]
-			if got := schemaContractString(entry["precedence"]); got != "reviewed_explicit" {
-				t.Errorf("%s %s precedence = %q, want reviewed_explicit", canonical, field, got)
+			if got := schemaContractString(entry["precedence"]); got != "contract_final" {
+				t.Errorf("%s %s precedence = %q, want contract_final", canonical, field, got)
 			}
-			if got := schemaContractString(entry["source"]); !strings.Contains(got, "internal/cli/schema_hints/metadata/") {
-				t.Errorf("%s %s source = %q, want reviewed interface disposition source", canonical, field, got)
+			if got := schemaContractString(entry["source"]); got != "corecmd.contract" {
+				t.Errorf("%s %s source = %q, want corecmd.contract", canonical, field, got)
 			}
 		}
 	}
 }
 
+// TestReviewedInterfaceDispositionSourceOwnsRuntimeSurface asserts that every
+// delivered Catalog tool owns interface disposition via ContractFinal
+// (corecmd.contract). Former schema_hints audit JSON
+// (runtime-surface-completeness / zz-interface-disposition-review) is retired.
 func TestReviewedInterfaceDispositionSourceOwnsRuntimeSurface(t *testing.T) {
-	type hintFile struct {
-		Source map[string]any            `json:"source"`
-		Tools  map[string]map[string]any `json:"tools"`
-	}
-	load := func(path string) hintFile {
-		t.Helper()
-		data, err := os.ReadFile(path)
-		if err != nil {
-			t.Fatalf("read %s: %v", path, err)
-		}
-		var value hintFile
-		if err := json.Unmarshal(data, &value); err != nil {
-			t.Fatalf("decode %s: %v", path, err)
-		}
-		return value
-	}
-	runtimeSurface := load("../cli/schema_hints/runtime-surface-completeness.json")
-	legacyDispositionKeys := load("../cli/schema_hints/zz-interface-disposition-review.json").Tools
-	dispositions := hintFile{Source: map[string]any{"reviewed": true}, Tools: map[string]map[string]any{}}
-	for _, product := range []string{
-		"attendance", "aitable", "chat", "drive", "event", "sheet", "wiki", "doc", "mail", "todo", "calendar", "conference", "contact", "dev", "devdoc", "ding", "live", "minutes", "oa", "pat", "report", "aisearch",
-	} {
-		path := "../cli/schema_hints/metadata/" + product + ".json"
-		if _, err := os.Stat(path); err != nil {
-			continue
-		}
-		file := load(path)
-		for canonical, hint := range file.Tools {
-			if _, ok := legacyDispositionKeys[canonical]; !ok {
-				continue
-			}
-			trimmed := map[string]any{}
-			for _, field := range []string{"interface_mode", "availability", "interface_ref", "interface_reason"} {
-				if value, exists := hint[field]; exists {
-					trimmed[field] = value
-				}
-			}
-			dispositions.Tools[canonical] = trimmed
-		}
-	}
-	if dispositions.Source["reviewed"] != true {
-		t.Fatalf("interface disposition source reviewed = %#v, want true", dispositions.Source["reviewed"])
-	}
-	for canonical, hint := range runtimeSurface.Tools {
-		if hint["reviewed"] != false {
-			t.Errorf("%s runtime surface reviewed = %#v, want false", canonical, hint["reviewed"])
-		}
-		for _, field := range []string{"interface_mode", "availability", "interface_ref", "interface_reason"} {
-			if _, exists := hint[field]; exists {
-				t.Errorf("%s runtime surface still owns %s", canonical, field)
-			}
-		}
-		if _, exists := dispositions.Tools[canonical]; !exists {
-			t.Errorf("%s runtime surface has no reviewed interface disposition", canonical)
-		}
-	}
-
-	allowedFields := map[string]bool{
-		"interface_mode":   true,
-		"availability":     true,
-		"interface_ref":    true,
-		"interface_reason": true,
-	}
-	canonicals := make([]string, 0, len(dispositions.Tools))
-	for canonical, hint := range dispositions.Tools {
+	tools := deliverySchemaAllToolsForHelpFlagTest(t, NewRootCommand())
+	canonicals := make([]string, 0, len(tools))
+	for canonical := range tools {
 		canonicals = append(canonicals, canonical)
-		for field := range hint {
-			if !allowedFields[field] {
-				t.Errorf("%s interface-only source contains non-interface field %s", canonical, field)
-			}
-		}
-		mode := schemaContractString(hint["interface_mode"])
-		if mode == "local" {
-			t.Errorf("%s remote interface review is incorrectly classified local", canonical)
-		}
-		if schemaContractString(hint["availability"]) != "available" {
-			t.Errorf("%s reviewed disposition is not available", canonical)
-		}
-		switch mode {
-		case "mcp":
-			ref := schemaInterfaceObject(hint["interface_ref"])
-			if schemaContractString(ref["product_id"]) == "" || schemaContractString(ref["rpc_name"]) == "" {
-				t.Errorf("%s reviewed mcp disposition has no complete interface_ref", canonical)
-			}
-		case "composite":
-			if hint["interface_ref"] != nil {
-				t.Errorf("%s reviewed composite disposition advertises interface_ref %#v", canonical, hint["interface_ref"])
-			}
-			if schemaContractString(hint["interface_reason"]) == "" {
-				t.Errorf("%s reviewed composite disposition has no reason", canonical)
-			}
-		default:
-			t.Errorf("%s reviewed disposition mode = %q", canonical, mode)
-		}
 	}
 	sort.Strings(canonicals)
-	payload := schemaContractPayloadForBoundCanonicals(t, NewRootCommand(), canonicals...)
+	if len(canonicals) == 0 {
+		t.Fatal("delivery schema --all contains no tools")
+	}
 	for _, canonical := range canonicals {
-		want := dispositions.Tools[canonical]
-		tool := payload.Tools[canonical]
-		if got := schemaContractString(tool["interface_mode"]); got != schemaContractString(want["interface_mode"]) {
-			t.Errorf("%s final interface_mode = %q, want %q", canonical, got, want["interface_mode"])
+		tool := tools[canonical]
+		mode := schemaContractString(tool["interface_mode"])
+		availability := schemaContractString(tool["availability"])
+		switch mode {
+		case "mcp", "composite", "local":
+		default:
+			t.Errorf("%s interface_mode = %q, want mcp|composite|local", canonical, mode)
 		}
-		if got := schemaContractString(tool["availability"]); got != schemaContractString(want["availability"]) {
-			t.Errorf("%s final availability = %q, want %q", canonical, got, want["availability"])
+		switch availability {
+		case "available", "unavailable":
+		default:
+			t.Errorf("%s availability = %q, want available|unavailable", canonical, availability)
 		}
-		if schemaContractString(want["interface_mode"]) == "composite" {
+		switch {
+		case availability == "unavailable":
 			if tool["interface_ref"] != nil {
-				t.Errorf("%s final composite interface_ref = %#v, want nil", canonical, tool["interface_ref"])
+				t.Errorf("%s unavailable interface_ref = %#v, want nil", canonical, tool["interface_ref"])
 			}
-			if got := schemaContractString(tool["interface_reason"]); got != schemaContractString(want["interface_reason"]) {
-				t.Errorf("%s final interface_reason = %q, want %q", canonical, got, want["interface_reason"])
+			if schemaContractString(tool["interface_reason"]) == "" {
+				t.Errorf("%s unavailable disposition missing interface_reason", canonical)
 			}
-		} else {
-			gotRef := schemaInterfaceObject(tool["interface_ref"])
-			wantRef := schemaInterfaceObject(want["interface_ref"])
-			for _, field := range []string{"product_id", "rpc_name"} {
-				if got := schemaContractString(gotRef[field]); got != schemaContractString(wantRef[field]) {
-					t.Errorf("%s final interface_ref.%s = %q, want %q", canonical, field, got, wantRef[field])
-				}
+		case mode == "mcp":
+			ref := schemaInterfaceObject(tool["interface_ref"])
+			if schemaContractString(ref["product_id"]) == "" || schemaContractString(ref["rpc_name"]) == "" {
+				t.Errorf("%s mcp disposition has incomplete interface_ref", canonical)
+			}
+		case mode == "composite":
+			if tool["interface_ref"] != nil {
+				t.Errorf("%s composite interface_ref = %#v, want nil", canonical, tool["interface_ref"])
+			}
+			if schemaContractString(tool["interface_reason"]) == "" {
+				t.Errorf("%s composite disposition missing interface_reason", canonical)
+			}
+		case mode == "local":
+			if tool["interface_ref"] != nil {
+				t.Errorf("%s local interface_ref = %#v, want nil", canonical, tool["interface_ref"])
 			}
 		}
 		provenance := schemaContractMap(tool["field_provenance"])
 		fields := []string{"interface_mode", "availability", "interface_ref"}
-		if schemaContractString(want["interface_mode"]) == "composite" {
+		if mode == "composite" || availability == "unavailable" {
 			fields = append(fields, "interface_reason")
 		}
 		for _, field := range fields {
 			entry := provenance[field]
-			if got := schemaContractString(entry["precedence"]); got != "reviewed_explicit" {
-				t.Errorf("%s final %s precedence = %q, want reviewed_explicit", canonical, field, got)
+			if got := schemaContractString(entry["precedence"]); got != "contract_final" {
+				t.Errorf("%s %s precedence = %q, want contract_final", canonical, field, got)
 			}
-			if got := schemaContractString(entry["source"]); !strings.Contains(got, "internal/cli/schema_hints/metadata/") {
-				t.Errorf("%s final %s source = %q, want reviewed disposition source", canonical, field, got)
+			if got := schemaContractString(entry["source"]); got != "corecmd.contract" {
+				t.Errorf("%s %s source = %q, want corecmd.contract", canonical, field, got)
 			}
 		}
 	}

internal/app/schema_oa_approval_contract_test.go

@@ -0,0 +1,76 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+
+package app
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestOAApprovalDualModeConstraintsReachEmbeddedSchema(t *testing.T) {
+	tools := deliverySchemaAllToolsForHelpFlagTest(t, NewRootCommand())
+
+	tests := []struct {
+		canonical         string
+		optional          []string
+		requireTogether   []string
+		mutuallyExclusive []string
+	}{
+		{
+			canonical:         "oa.forecast_process",
+			optional:          []string{"request", "process-code", "dept-id", "form-values"},
+			requireTogether:   []string{"process-code", "dept-id", "form-values"},
+			mutuallyExclusive: []string{"process-code", "dept-id", "form-values"},
+		},
+		{
+			canonical:         "oa.start_process_instance",
+			optional:          []string{"request", "process-code", "dept-id", "form-values", "originator-user-id", "approvers", "approvers-action-type", "cc-list", "cc-position"},
+			requireTogether:   []string{"process-code", "form-values"},
+			mutuallyExclusive: []string{"process-code", "dept-id", "form-values", "originator-user-id", "approvers", "approvers-action-type", "cc-list", "cc-position"},
+		},
+	}
+
+	for _, test := range tests {
+		t.Run(test.canonical, func(t *testing.T) {
+			tool := tools[test.canonical]
+			parameters := schemaContractMap(tool["parameters"])
+			for _, name := range test.optional {
+				if got := parameters[name]["required"]; got != false {
+					t.Errorf("--%s required = %#v, want false for dual-mode command", name, got)
+				}
+			}
+			assertSchemaContractConstraintGroup(t, tool, "require_one_of", []string{"request", "process-code"})
+			assertSchemaContractConstraintGroup(t, tool, "require_together", test.requireTogether)
+			for _, name := range test.mutuallyExclusive {
+				assertSchemaContractConstraintGroup(t, tool, "mutually_exclusive", []string{"request", name})
+			}
+			constraints, _ := tool["constraints"].(map[string]any)
+			groups, _ := constraints["mutually_exclusive"].([]any)
+			if len(groups) != len(test.mutuallyExclusive) {
+				t.Errorf("mutually_exclusive group count = %d, want %d: %#v", len(groups), len(test.mutuallyExclusive), groups)
+			}
+			for _, rawGroup := range groups {
+				group, _ := rawGroup.([]any)
+				if len(group) != 2 {
+					t.Errorf("mutually_exclusive contains an over-broad group: %#v", group)
+				}
+			}
+
+			hasRequestOnlyExample := false
+			for _, example := range schemaContractStringSlice(tool["examples"]) {
+				if strings.Contains(example, " --request ") && !strings.Contains(example, " --process-code ") && !strings.Contains(example, " --form-values ") {
+					hasRequestOnlyExample = true
+				}
+			}
+			if !hasRequestOnlyExample {
+				t.Errorf("examples do not contain a request-only invocation: %#v", tool["examples"])
+			}
+		})
+	}
+
+	create := tools["oa.start_process_instance"]
+	if got := schemaContractString(create["confirmation"]); got != "user_required" {
+		t.Errorf("create-instance confirmation = %q, want user_required", got)
+	}
+}

internal/app/schema_resolve_meta_cache_test.go

@@ -0,0 +1,85 @@
+// 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"
+	"io"
+	"os"
+	"os/exec"
+	"strings"
+	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/cli"
+)
+
+const schemaResolveMetaCacheChildEnv = "DWS_SCHEMA_RESOLVE_META_CACHE_CHILD"
+
+// TestResolveMetaAndLeafHelpReuseAssembledMetaCache proves production
+// RegisterSchemaSourceRoot → delivery Once caches CommandMeta: first
+// ResolveMeta pays assembly once; subsequent ResolveMeta and leaf --help
+// Safety do not increment the Catalog counter.
+func TestResolveMetaAndLeafHelpReuseAssembledMetaCache(t *testing.T) {
+	if os.Getenv(schemaResolveMetaCacheChildEnv) == "1" {
+		registerSchemaRuntimeDelivery()
+
+		counts := cli.RuntimeSchemaMetadataLoadCounts()
+		if counts.Catalog != 0 || counts.MetaIndex != 0 {
+			t.Fatalf("precondition Catalog/MetaIndex = %#v", counts)
+		}
+
+		meta, ok := cli.ResolveMeta("dev app delete")
+		if !ok || meta.Identity.Canonical == "" {
+			t.Fatalf("ResolveMeta(dev app delete) = %#v ok=%v", meta, ok)
+		}
+		counts = cli.RuntimeSchemaMetadataLoadCounts()
+		if counts.Catalog != 1 || counts.MetaIndex != 1 {
+			t.Fatalf("after first ResolveMeta counts = %#v, want Catalog=1 MetaIndex=1", counts)
+		}
+
+		for range 4 {
+			if _, ok := cli.ResolveMeta("dev app delete"); !ok {
+				t.Fatal("steady ResolveMeta ok=false")
+			}
+		}
+		counts = cli.RuntimeSchemaMetadataLoadCounts()
+		if counts.Catalog != 1 || counts.MetaIndex != 1 {
+			t.Fatalf("after steady ResolveMeta counts = %#v", counts)
+		}
+
+		root := NewRootCommand()
+		var helpOut bytes.Buffer
+		root.SetOut(&helpOut)
+		root.SetErr(io.Discard)
+		root.SetArgs([]string{"dev", "app", "delete", "--help"})
+		if err := root.Execute(); err != nil {
+			t.Fatalf("dev app delete --help: %v", err)
+		}
+		if meta.Safety.ShouldRender() && !strings.Contains(helpOut.String(), "Safety:") {
+			t.Fatalf("leaf --help missing Safety annotation; output=%q", helpOut.String())
+		}
+		counts = cli.RuntimeSchemaMetadataLoadCounts()
+		if counts.Catalog != 1 || counts.MetaIndex != 1 {
+			t.Fatalf("leaf --help re-assembled Schema: %#v", counts)
+		}
+		return
+	}
+
+	command := exec.Command(os.Args[0], "-test.run=^TestResolveMetaAndLeafHelpReuseAssembledMetaCache$", "-test.count=1")
+	command.Env = append(os.Environ(), schemaResolveMetaCacheChildEnv+"=1")
+	output, err := command.CombinedOutput()
+	if err != nil {
+		t.Fatalf("ResolveMeta cache child failed: %v\n%s", err, strings.TrimSpace(string(output)))
+	}
+}

internal/app/schema_safety_contract_test.go

@@ -15,45 +15,54 @@ type finalSchemaSafetyWant struct {
 	risk         string
 	confirmation string
 	idempotency  string
+	// provenance is the expected field_provenance precedence; empty defaults
+	// to "contract_final" (DeclareLeafMetadata / corecmd.Contract). Production
+	// metadata shells no longer carry reviewed tool rows.
+	provenance string
 }
 
 func TestReviewedMutationSafetyReachesFinalSchema(t *testing.T) {
+	const declared = "contract_final"
 	wants := []finalSchemaSafetyWant{
-		{canonical: "aitable.form_field_hide", effect: "write", risk: "medium", confirmation: "not_required", idempotency: "idempotent"},
-		{canonical: "chat.dismiss_group", effect: "destructive", risk: "high", confirmation: "user_required", idempotency: "unknown"},
-		{canonical: "drive.recycle_restore", effect: "write", risk: "medium", confirmation: "not_required", idempotency: "unknown"},
-		{canonical: "minutes.create_speaker_summary", effect: "write", risk: "medium", confirmation: "not_required", idempotency: "unknown"},
-		{canonical: "sheet.clear_range", effect: "write", risk: "medium", confirmation: "user_required", idempotency: "unknown"},
-		{canonical: "sheet.batch_update", effect: "write", risk: "medium", confirmation: "user_required", idempotency: "unknown"},
-		{canonical: "sheet.range_batch_clear", effect: "write", risk: "medium", confirmation: "user_required", idempotency: "unknown"},
-		{canonical: "sheet.group_dimension", effect: "write", risk: "medium", confirmation: "not_required", idempotency: "unknown"},
-		{canonical: "sheet.sort_filter", effect: "write", risk: "medium", confirmation: "not_required", idempotency: "unknown"},
-		{canonical: "sheet.ungroup_dimension", effect: "write", risk: "medium", confirmation: "not_required", idempotency: "unknown"},
+		{canonical: "aitable.form_field_hide", effect: "write", risk: "medium", confirmation: "not_required", idempotency: "idempotent", provenance: declared},
+		{canonical: "chat.dismiss_group", effect: "destructive", risk: "high", confirmation: "user_required", idempotency: "unknown", provenance: declared},
+		{canonical: "drive.recycle_restore", effect: "write", risk: "medium", confirmation: "not_required", idempotency: "unknown", provenance: declared},
+		{canonical: "minutes.create_speaker_summary", effect: "write", risk: "medium", confirmation: "not_required", idempotency: "unknown", provenance: declared},
+		{canonical: "sheet.clear_range", effect: "write", risk: "medium", confirmation: "user_required", idempotency: "unknown", provenance: declared},
+		{canonical: "sheet.batch_update", effect: "write", risk: "medium", confirmation: "user_required", idempotency: "unknown", provenance: declared},
+		{canonical: "sheet.range_batch_clear", effect: "write", risk: "medium", confirmation: "user_required", idempotency: "unknown", provenance: declared},
+		{canonical: "sheet.group_dimension", effect: "write", risk: "medium", confirmation: "not_required", idempotency: "unknown", provenance: declared},
+		{canonical: "sheet.sort_filter", effect: "write", risk: "medium", confirmation: "not_required", idempotency: "unknown", provenance: declared},
+		{canonical: "sheet.ungroup_dimension", effect: "write", risk: "medium", confirmation: "not_required", idempotency: "unknown", provenance: declared},
 	}
 	assertFinalSchemaSafety(t, wants)
 }
 
 func TestDevAppWriteGuardRequiresFinalSchemaConfirmation(t *testing.T) {
+	// devapp 全树已声明化：provenance 为 contract_final；effect/risk 逐字
+	// 保持 merge-base 评审值（写操作一律 high，publish 为 write/high），
+	// 重分级需要独立的契约变更 PR。
+	const declared = "contract_final"
 	wants := []finalSchemaSafetyWant{
-		{canonical: "dev.add_dev_app_members", effect: "write", risk: "high", confirmation: "user_required", idempotency: "unknown"},
-		{canonical: "dev.apply_dev_app_permissions", effect: "write", risk: "high", confirmation: "user_required", idempotency: "unknown"},
-		{canonical: "dev.create_dev_app", effect: "write", risk: "high", confirmation: "user_required", idempotency: "unknown"},
-		{canonical: "dev.create_dev_app_version", effect: "write", risk: "high", confirmation: "user_required", idempotency: "unknown"},
-		{canonical: "dev.delete_dev_app", effect: "destructive", risk: "high", confirmation: "user_required", idempotency: "unknown"},
-		{canonical: "dev.disable_dev_app", effect: "write", risk: "high", confirmation: "user_required", idempotency: "unknown"},
-		{canonical: "dev.disable_dev_app_robot", effect: "write", risk: "high", confirmation: "user_required", idempotency: "unknown"},
-		{canonical: "dev.enable_dev_app", effect: "write", risk: "high", confirmation: "user_required", idempotency: "unknown"},
-		{canonical: "dev.enable_dev_app_robot", effect: "write", risk: "high", confirmation: "user_required", idempotency: "unknown"},
-		{canonical: "dev.publish_dev_app_version", effect: "write", risk: "high", confirmation: "user_required", idempotency: "unknown"},
-		{canonical: "dev.remove_dev_app_members", effect: "write", risk: "high", confirmation: "user_required", idempotency: "unknown"},
-		{canonical: "dev.remove_dev_app_permissions", effect: "write", risk: "high", confirmation: "user_required", idempotency: "unknown"},
-		{canonical: "dev.set_extension_robot_config", effect: "write", risk: "high", confirmation: "user_required", idempotency: "unknown"},
-		{canonical: "dev.set_extension_webapp_config", effect: "write", risk: "high", confirmation: "user_required", idempotency: "unknown"},
-		{canonical: "dev.submit_robot_create_task", effect: "write", risk: "high", confirmation: "user_required", idempotency: "unknown"},
-		{canonical: "dev.subscribe_dev_app_events", effect: "write", risk: "high", confirmation: "user_required", idempotency: "unknown"},
-		{canonical: "dev.unsubscribe_dev_app_events", effect: "write", risk: "high", confirmation: "user_required", idempotency: "unknown"},
-		{canonical: "dev.update_dev_app", effect: "write", risk: "high", confirmation: "user_required", idempotency: "unknown"},
-		{canonical: "dev.update_dev_app_security_config", effect: "write", risk: "high", confirmation: "user_required", idempotency: "unknown"},
+		{canonical: "dev.add_dev_app_members", effect: "write", risk: "high", confirmation: "user_required", idempotency: "unknown", provenance: declared},
+		{canonical: "dev.apply_dev_app_permissions", effect: "write", risk: "high", confirmation: "user_required", idempotency: "unknown", provenance: declared},
+		{canonical: "dev.create_dev_app", effect: "write", risk: "high", confirmation: "user_required", idempotency: "unknown", provenance: declared},
+		{canonical: "dev.create_dev_app_version", effect: "write", risk: "high", confirmation: "user_required", idempotency: "unknown", provenance: declared},
+		{canonical: "dev.delete_dev_app", effect: "destructive", risk: "high", confirmation: "user_required", idempotency: "unknown", provenance: declared},
+		{canonical: "dev.disable_dev_app", effect: "write", risk: "high", confirmation: "user_required", idempotency: "unknown", provenance: declared},
+		{canonical: "dev.disable_dev_app_robot", effect: "write", risk: "high", confirmation: "user_required", idempotency: "unknown", provenance: declared},
+		{canonical: "dev.enable_dev_app", effect: "write", risk: "high", confirmation: "user_required", idempotency: "unknown", provenance: declared},
+		{canonical: "dev.enable_dev_app_robot", effect: "write", risk: "high", confirmation: "user_required", idempotency: "unknown", provenance: declared},
+		{canonical: "dev.publish_dev_app_version", effect: "write", risk: "high", confirmation: "user_required", idempotency: "unknown", provenance: declared},
+		{canonical: "dev.remove_dev_app_members", effect: "write", risk: "high", confirmation: "user_required", idempotency: "unknown", provenance: declared},
+		{canonical: "dev.remove_dev_app_permissions", effect: "write", risk: "high", confirmation: "user_required", idempotency: "unknown", provenance: declared},
+		{canonical: "dev.set_extension_robot_config", effect: "write", risk: "high", confirmation: "user_required", idempotency: "unknown", provenance: declared},
+		{canonical: "dev.set_extension_webapp_config", effect: "write", risk: "high", confirmation: "user_required", idempotency: "unknown", provenance: declared},
+		{canonical: "dev.submit_robot_create_task", effect: "write", risk: "high", confirmation: "user_required", idempotency: "unknown", provenance: declared},
+		{canonical: "dev.subscribe_dev_app_events", effect: "write", risk: "high", confirmation: "user_required", idempotency: "unknown", provenance: declared},
+		{canonical: "dev.unsubscribe_dev_app_events", effect: "write", risk: "high", confirmation: "user_required", idempotency: "unknown", provenance: declared},
+		{canonical: "dev.update_dev_app", effect: "write", risk: "high", confirmation: "user_required", idempotency: "unknown", provenance: declared},
+		{canonical: "dev.update_dev_app_security_config", effect: "write", risk: "high", confirmation: "user_required", idempotency: "unknown", provenance: declared},
 	}
 	assertFinalSchemaSafety(t, wants)
 }
@@ -77,13 +86,17 @@ func assertFinalSchemaSafety(t *testing.T, wants []finalSchemaSafetyWant) {
 				"confirmation": want.confirmation,
 				"idempotency":  want.idempotency,
 			}
+			wantProvenance := want.provenance
+			if wantProvenance == "" {
+				wantProvenance = "contract_final"
+			}
 			provenance := schemaContractMap(tool["field_provenance"])
 			for field, expected := range values {
 				if got := schemaContractString(tool[field]); got != expected {
 					t.Errorf("%s = %q, want %q", field, got, expected)
 				}
-				if got := schemaContractString(provenance[field]["precedence"]); got != "reviewed_explicit" {
-					t.Errorf("%s provenance precedence = %q, want reviewed_explicit", field, got)
+				if got := schemaContractString(provenance[field]["precedence"]); got != wantProvenance {
+					t.Errorf("%s provenance precedence = %q, want %s", field, got, wantProvenance)
 				}
 			}
 		})

internal/app/schema_shortcut_contract_test.go

@@ -16,12 +16,16 @@ import (
 )
 
 const (
-	publicShortcutCount          = 265
-	schemaPublishedShortcutCount = 215
+	publicShortcutCount = 357
+	// schemaPublishedShortcutCount counts every delivered *.shortcut_* tool,
+	// including hidden leaves such as minutes.shortcut_minutes_search.
+	schemaPublishedShortcutCount = 358
+	// publiclyDeliveredShortcutCount is the public-catalog subset of that surface.
+	publiclyDeliveredShortcutCount = 357
 )
 
-func TestEmbeddedSchemaCoversOrExactlyExcludesEveryPublicShortcutContract(t *testing.T) {
-	tools := embeddedSchemaAllToolsForHelpFlagTest(t, NewRootCommand())
+func TestDeliverySchemaCoversOrExactlyExcludesEveryPublicShortcutContract(t *testing.T) {
+	tools := deliverySchemaAllToolsForHelpFlagTest(t, NewRootCommand())
 	public := make([]shortcut.Shortcut, 0, publicShortcutCount)
 	for _, candidate := range shortcut.All() {
 		if candidate.UserDefined || !shortcut.InPublicCatalog(candidate.Service, candidate.Command) {
@@ -40,10 +44,10 @@ func TestEmbeddedSchemaCoversOrExactlyExcludesEveryPublicShortcutContract(t *tes
 		}
 	}
 	if deliveredShortcuts != schemaPublishedShortcutCount {
-		t.Fatalf("embedded schema --all shortcut tools = %d, want %d", deliveredShortcuts, schemaPublishedShortcutCount)
+		t.Fatalf("delivery schema --all shortcut tools = %d, want %d", deliveredShortcuts, schemaPublishedShortcutCount)
 	}
 
-	exclusions, err := cli.EmbeddedRuntimeSchemaExclusions()
+	exclusions, err := cli.ReviewedRuntimeSchemaExclusions()
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -64,23 +68,23 @@ func TestEmbeddedSchemaCoversOrExactlyExcludesEveryPublicShortcutContract(t *tes
 			if tool == nil {
 				cliPath := declared.Service + " " + declared.Command
 				if !excludedPaths[cliPath] {
-					t.Fatalf("embedded schema --all is missing %s (%s) without an exact reviewed exclusion", canonical, cliPath)
+					t.Fatalf("delivery schema --all is missing %s (%s) without an exact reviewed exclusion", canonical, cliPath)
 				}
 				excludedShortcuts++
 				return
 			}
-			assertEmbeddedShortcutIdentityAndSelection(t, tool, declared, canonical)
-			assertEmbeddedShortcutSafetyAndInterface(t, tool, declared, canonical)
-			assertEmbeddedShortcutParameters(t, tool, declared, canonical)
-			assertEmbeddedShortcutConstraints(t, tool, declared, canonical)
+			assertDeliveryShortcutIdentityAndSelection(t, tool, declared, canonical)
+			assertDeliveryShortcutSafetyAndInterface(t, tool, declared, canonical)
+			assertDeliveryShortcutParameters(t, tool, declared, canonical)
+			assertDeliveryShortcutConstraints(t, tool, declared, canonical)
 		})
 	}
-	if got, want := excludedShortcuts, publicShortcutCount-schemaPublishedShortcutCount; got != want {
+	if got, want := excludedShortcuts, publicShortcutCount-publiclyDeliveredShortcutCount; got != want {
 		t.Fatalf("exactly excluded public shortcuts = %d, want %d", got, want)
 	}
 }
 
-func TestEmbeddedShortcutProgressiveQueriesReturnCompleteContracts(t *testing.T) {
+func TestDeliveryShortcutProgressiveQueriesReturnCompleteContracts(t *testing.T) {
 	leaf := executeShortcutSchemaQuery(t, "--cli-path", "chat +messages-read-status")
 	if got, want := schemaContractString(leaf["canonical_path"]), "chat.shortcut_messages_read_status"; got != want {
 		t.Fatalf("shortcut leaf canonical_path = %q, want %q", got, want)
@@ -89,11 +93,15 @@ func TestEmbeddedShortcutProgressiveQueriesReturnCompleteContracts(t *testing.T)
 		t.Fatalf("shortcut leaf confirmation = %q, want %q", got, want)
 	}
 	conversationID := schemaContractMap(leaf["parameters"])["conversation-id"]
-	if required, _ := conversationID["required"].(bool); !required {
-		t.Fatal("public --conversation-id must become required after hidden compatibility aliases are removed from Schema")
+	if required, _ := conversationID["required"].(bool); required {
+		t.Fatal("public --conversation-id must stay optional when hidden siblings still satisfy the declared exactly_one group")
 	}
-	if got := leaf["constraints"]; got != nil {
-		t.Fatalf("shortcut leaf constraints = %#v, want omitted after hidden compatibility aliases collapse", got)
+	wantMessagesConstraints := map[string]any{
+		"require_one_of":     [][]string{{"conversation-id", "group", "id"}},
+		"mutually_exclusive": [][]string{{"conversation-id", "group", "id"}},
+	}
+	if got := leaf["constraints"]; !schemaContractJSONEqual(got, wantMessagesConstraints) {
+		t.Fatalf("shortcut leaf constraints = %#v, want %#v", got, wantMessagesConstraints)
 	}
 
 	constrainedLeaf := executeShortcutSchemaQuery(t, "--cli-path", "calendar +freebusy")
@@ -106,7 +114,7 @@ func TestEmbeddedShortcutProgressiveQueriesReturnCompleteContracts(t *testing.T)
 
 	product := executeShortcutSchemaQuery(t, "chat")
 	productPayload, _ := product["product"].(map[string]any)
-	if got, want := int(product["count"].(float64)), 129; got != want {
+	if got, want := int(product["count"].(float64)), 187; got != want {
 		t.Fatalf("schema chat count = %d, want %d", got, want)
 	}
 	summaries := schemaContractObjectSlice(productPayload["tools"])
@@ -116,8 +124,77 @@ func TestEmbeddedShortcutProgressiveQueriesReturnCompleteContracts(t *testing.T)
 			shortcutCount++
 		}
 	}
-	if shortcutCount != 47 {
-		t.Fatalf("schema chat shortcut summaries = %d, want 47", shortcutCount)
+	if shortcutCount != 98 {
+		t.Fatalf("schema chat shortcut summaries = %d, want 98", shortcutCount)
+	}
+}
+
+func TestDeliveryDocUpdateShortcutPublishesCompleteConditionalContract(t *testing.T) {
+	leaf := executeShortcutSchemaQuery(t, "--cli-path", "doc +update")
+	if got, want := schemaContractString(leaf["confirmation"]), "user_required"; got != want {
+		t.Fatalf("confirmation = %q, want %q", got, want)
+	}
+	parameters := schemaContractMap(leaf["parameters"])
+	if got, want := len(parameters), 11; got != want {
+		t.Fatalf("parameter count = %d, want %d: %#v", got, want, parameters)
+	}
+	if required, _ := parameters["node"]["required"].(bool); !required {
+		t.Errorf("--node required = %#v, want true", parameters["node"]["required"])
+	}
+	if required, _ := parameters["command"]["required"].(bool); required {
+		t.Errorf("--command required = true, want runtime custom validation")
+	}
+	wantProperties := map[string]string{
+		"node": "node", "doc": "node", "command": "command", "content": "content", "text": "content", "doc-format": "docFormat",
+		"block-id": "blockId", "after-block-id": "afterBlockId", "old": "old", "new": "new",
+		"expected-revision": "expectedRevision",
+	}
+	for name, want := range wantProperties {
+		if got := schemaContractString(parameters[name]["property"]); got != want {
+			t.Errorf("--%s property = %q, want %q", name, got, want)
+		}
+	}
+	for _, name := range []string{"content", "block-id", "after-block-id", "old", "new"} {
+		parameter := parameters[name]
+		if required, _ := parameter["required"].(bool); required {
+			t.Errorf("--%s required = true, want runtime custom validation", name)
+		}
+		if got := schemaContractString(parameter["required_when"]); got != "" {
+			t.Errorf("--%s required_when = %q, want compatibility-safe custom validation", name, got)
+		}
+	}
+	if constraints, exists := leaf["constraints"]; exists && constraints != nil {
+		t.Fatalf("enum-discriminated requirements must not be mispublished as relationship constraints: %#v", constraints)
+	}
+}
+
+func TestDeliveryDocCommentExportImportContractsAreCanonical(t *testing.T) {
+	comment := executeShortcutSchemaQuery(t, "--cli-path", "doc +comment-create")
+	commentParameters := schemaContractMap(comment["parameters"])
+	for _, name := range []string{"node", "content", "selection", "block-id", "start", "end", "selected-text", "mention"} {
+		if _, ok := commentParameters[name]; !ok {
+			t.Errorf("comment-create missing --%s: %#v", name, commentParameters)
+		}
+	}
+	for name, want := range map[string]string{"node": "node", "mention": "mention"} {
+		if got := schemaContractString(commentParameters[name]["property"]); got != want {
+			t.Errorf("comment-create --%s property = %q, want %q", name, got, want)
+		}
+	}
+
+	export := executeShortcutSchemaQuery(t, "--cli-path", "doc +export")
+	exportFormat := schemaContractMap(export["parameters"])["export-format"]
+	if required, _ := exportFormat["required"].(bool); required {
+		t.Fatalf("export --export-format required = true, want compatibility default")
+	}
+	if defaultValue := schemaContractString(exportFormat["default"]); defaultValue != "docx" {
+		t.Fatalf("export --export-format default = %q, want docx", defaultValue)
+	}
+
+	importLeaf := executeShortcutSchemaQuery(t, "--cli-path", "doc +import")
+	constraints, _ := importLeaf["constraints"].(map[string]any)
+	if requireOneOf, ok := constraints["require_one_of"]; ok && !schemaContractJSONEqual(requireOneOf, [][]string{}) {
+		t.Fatalf("import unexpectedly requires a target: %#v", constraints)
 	}
 }
 
@@ -143,7 +220,7 @@ func shortcutSchemaCanonical(declared shortcut.Shortcut) string {
 	return declared.Service + ".shortcut_" + name
 }
 
-func assertEmbeddedShortcutIdentityAndSelection(
+func assertDeliveryShortcutIdentityAndSelection(
 	t testing.TB,
 	tool map[string]any,
 	declared shortcut.Shortcut,
@@ -179,24 +256,16 @@ func assertEmbeddedShortcutIdentityAndSelection(
 	}
 }
 
-func assertEmbeddedShortcutSafetyAndInterface(
+func assertDeliveryShortcutSafetyAndInterface(
 	t testing.TB,
 	tool map[string]any,
 	declared shortcut.Shortcut,
 	canonical string,
 ) {
 	t.Helper()
-	risk := declared.Risk
-	if risk == "" {
-		risk = shortcut.RiskRead
-	}
-	wantEffect, wantRisk, wantConfirmation, wantIdempotency := "read", "low", "not_required", "idempotent"
-	switch risk {
-	case shortcut.RiskWrite:
-		wantEffect, wantRisk, wantConfirmation, wantIdempotency = "write", "medium", "user_required", "unknown"
-	case shortcut.RiskHighWrite:
-		wantEffect, wantRisk, wantConfirmation, wantIdempotency = "destructive", "high", "user_required", "unknown"
-	}
+	safety := shortcut.EffectiveSafety(declared)
+	wantEffect, wantRisk := safety.Effect, safety.Risk
+	wantConfirmation, wantIdempotency := safety.Confirmation, safety.Idempotency
 	for field, want := range map[string]string{
 		"effect":         wantEffect,
 		"risk":           wantRisk,
@@ -214,7 +283,7 @@ func assertEmbeddedShortcutSafetyAndInterface(
 	}
 }
 
-func assertEmbeddedShortcutParameters(
+func assertDeliveryShortcutParameters(
 	t testing.TB,
 	tool map[string]any,
 	declared shortcut.Shortcut,
@@ -226,6 +295,15 @@ func assertEmbeddedShortcutParameters(
 	for _, flag := range declared.Flags {
 		if !flag.Hidden {
 			publicFlags = append(publicFlags, flag)
+			if flag.AliasesVisible {
+				for _, alias := range flag.Aliases {
+					aliasFlag := flag
+					aliasFlag.Name = alias
+					aliasFlag.Default = ""
+					aliasFlag.Aliases = nil
+					publicFlags = append(publicFlags, aliasFlag)
+				}
+			}
 		}
 	}
 	if got, want := len(parameters), len(publicFlags); got != want {
@@ -291,6 +369,13 @@ func shortcutSchemaRequired(declared shortcut.Shortcut, flagName string) bool {
 		if flag.Name == flagName && flag.Required {
 			return true
 		}
+		if flag.Required && flag.AliasesVisible {
+			for _, alias := range flag.Aliases {
+				if alias == flagName {
+					return true
+				}
+			}
+		}
 	}
 	public := make(map[string]bool, len(declared.Flags))
 	for _, flag := range declared.Flags {
@@ -308,14 +393,20 @@ func shortcutSchemaRequired(declared shortcut.Shortcut, flagName string) bool {
 				visible = append(visible, constrained)
 			}
 		}
-		if len(visible) == 1 && visible[0] == flagName {
+		// Match AnnotateConstraints: only collapse to required when the projected
+		// group has a single member (no remaining hidden siblings).
+		flags := visible
+		if len(visible) < len(constraint.Flags) {
+			flags = append([]string(nil), constraint.Flags...)
+		}
+		if len(flags) == 1 && flags[0] == flagName {
 			return true
 		}
 	}
 	return false
 }
 
-func assertEmbeddedShortcutConstraints(
+func assertDeliveryShortcutConstraints(
 	t testing.TB,
 	tool map[string]any,
 	declared shortcut.Shortcut,
@@ -330,12 +421,18 @@ func assertEmbeddedShortcutConstraints(
 	}
 	want := map[string][][]string{}
 	for _, constraint := range declared.Constraints {
-		flags := make([]string, 0, len(constraint.Flags))
+		visible := make([]string, 0, len(constraint.Flags))
 		for _, flagName := range constraint.Flags {
 			if public[flagName] {
-				flags = append(flags, flagName)
+				visible = append(visible, flagName)
 			}
 		}
+		// Match AnnotateConstraints declare≡execute projection: keep the full
+		// declared group when any hidden sibling remains.
+		flags := visible
+		if len(visible) < len(constraint.Flags) {
+			flags = append([]string(nil), constraint.Flags...)
+		}
 		switch constraint.Kind {
 		case shortcut.ConstraintAtLeastOne:
 			if len(flags) > 1 {

internal/app/schema_source_register.go

@@ -0,0 +1,36 @@
+// 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 (
+	"sync"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/cli"
+	"github.com/spf13/cobra"
+)
+
+var registerSchemaRuntimeDeliveryOnce sync.Once
+
+// registerSchemaRuntimeDelivery installs the ResolveSchemaBuild root factory
+// for production Catalog / ResolveMeta delivery. Called from NewRootCommand
+// (and optionally cmd entrypoints). Intentionally NOT an init() side effect:
+// importing app from package cli_test must not flip package-cli tests onto
+// the assembly path.
+func registerSchemaRuntimeDelivery() {
+	registerSchemaRuntimeDeliveryOnce.Do(func() {
+		cli.RegisterSchemaSourceRoot(func() *cobra.Command {
+			return NewSchemaSourceRootCommand()
+		})
+	})
+}

internal/app/schema_source_register_coverage_test.go

@@ -0,0 +1,32 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+
+package app
+
+import (
+	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/cli"
+)
+
+// TestCrossPlatformCoverageRegisterSchemaRuntimeDelivery covers the production
+// RegisterSchemaSourceRoot install path used by NewRootCommand.
+func TestCrossPlatformCoverageRegisterSchemaRuntimeDelivery(t *testing.T) {
+	registerSchemaRuntimeDelivery()
+	if !cli.SchemaSourceRootRegistered() {
+		t.Fatal("registerSchemaRuntimeDelivery did not install Schema source root")
+	}
+	meta, ok := cli.ResolveMeta("dev app delete")
+	if !ok || meta.Identity.Canonical == "" {
+		t.Fatalf("ResolveMeta after registerSchemaRuntimeDelivery = %#v ok=%v", meta, ok)
+	}
+	safety, ok := cli.SafetyForCLIPath("dev app delete")
+	if !ok || safety.Effect == "" {
+		t.Fatalf("SafetyForCLIPath after register = %#v ok=%v", safety, ok)
+	}
+	// Idempotent: Once must not panic or clear the factory.
+	registerSchemaRuntimeDelivery()
+	if !cli.SchemaSourceRootRegistered() {
+		t.Fatal("second registerSchemaRuntimeDelivery cleared Schema source root")
+	}
+}